Pre-flight Checks
Problem Description
Cloud configuration is currently CLI/env-driven and invisible to TUI users:
- Server URL: set via
engram cloud config --server <url>
- Token: set via
ENGRAM_CLOUD_TOKEN, with cloud.json.token as an intentional fallback
- Project enrollment: separate per-project CLI command
The TUI is the project's primary visual interface and currently has no entry point for cloud configuration.
Proposed Solution
Add a Cloud sync settings menu item to the Engram TUI dashboard with three sub-screens:
- Cloud Config: form to set the server URL plus a read-only token status line showing the active source (
ENGRAM_CLOUD_TOKEN env var, cloud.json.token fallback, or not set). The TUI persists only the server URL; the token is never written by the TUI.
- Cloud Status: read-only view of server URL, connection health, last sync, pending mutations, and last error.
- Project Enrollment: list of local projects with enroll / unenroll toggles.
Before saving the server URL, the TUI pings the server's health endpoint and surfaces the result (reachable / unreachable / unauthorized). A 401 still persists the URL because server reachability and auth are independent concerns.
A small docs update is bundled: docs/engram-cloud/troubleshooting.md should explicitly document the cloud.json.token fallback as intentional, with the env var taking precedence. No code change required — the runtime already behaves this way (see issue #343).
Affected Area
- TUI (screens, navigation, rendering)
- Documentation (troubleshooting.md)
Alternatives Considered
- Adding a masked token input and writing
cloud.json.token from the TUI: rejected because the project philosophy keeps tokens out of disk where possible.
- Removing the
cloud.json.token fallback from resolveCloudRuntimeConfig: rejected as a breaking change for users who currently rely on it.
- Implementing OAuth or browser login in the TUI: rejected — out of scope for a client-only change and would require server-side work.
- Leaving cloud setup CLI-only: rejected — the TUI is the project's visual interface and the current flow is a discoverability / UX gap.
Implementation Plan
The change will land via 4 chained PRs against a tracker branch feat/tui-cloud-config (Feature Branch Chain):
- PR 1: TUI dashboard entry + sub-menu + docs update.
- PR 2: Cloud Config form + ping command + save flow.
- PR 3: Cloud Status view.
- PR 4: Project Enrollment toggles.
Each PR follows strict TDD, adds zero new dependencies, and stays under ~400 changed lines. Tests run with go test ./....
Additional Context
Pre-flight Checks
Problem Description
Cloud configuration is currently CLI/env-driven and invisible to TUI users:
engram cloud config --server <url>ENGRAM_CLOUD_TOKEN, withcloud.json.tokenas an intentional fallbackThe TUI is the project's primary visual interface and currently has no entry point for cloud configuration.
Proposed Solution
Add a Cloud sync settings menu item to the Engram TUI dashboard with three sub-screens:
ENGRAM_CLOUD_TOKENenv var,cloud.json.tokenfallback, or not set). The TUI persists only the server URL; the token is never written by the TUI.Before saving the server URL, the TUI pings the server's health endpoint and surfaces the result (reachable / unreachable / unauthorized). A 401 still persists the URL because server reachability and auth are independent concerns.
A small docs update is bundled:
docs/engram-cloud/troubleshooting.mdshould explicitly document thecloud.json.tokenfallback as intentional, with the env var taking precedence. No code change required — the runtime already behaves this way (see issue #343).Affected Area
Alternatives Considered
cloud.json.tokenfrom the TUI: rejected because the project philosophy keeps tokens out of disk where possible.cloud.json.tokenfallback fromresolveCloudRuntimeConfig: rejected as a breaking change for users who currently rely on it.Implementation Plan
The change will land via 4 chained PRs against a tracker branch
feat/tui-cloud-config(Feature Branch Chain):Each PR follows strict TDD, adds zero new dependencies, and stays under ~400 changed lines. Tests run with
go test ./....Additional Context
sdd/tui-cloud-config/explore.sdd/tui-cloud-config/spec.cmd/engram/cloud.go.cmd/engram/main.go:resolveCloudRuntimeConfig(line 447).docs/engram-cloud/troubleshooting.md.engram cloud config --statusalias andENGRAM_CLOUD_TOKENprecedence (issue fix(cloud): client v1.15.9 sync --cloud does not send Authorization header despite valid cloud.json #343).