browser/openspec/changes/fix-env-profile-settings/design.md

Context

The platform already supports file and MySQL-backed metadata stores behind repo.Store. MySQL initialization is selected by PLATFORM_STORAGE_BACKEND=mysql and uses PLATFORM_MYSQL_DSN, but platform/cmd/platform calls config.Load() directly and config.Load() only reads process environment variables. A developer who edits platform/.env and starts the binary without sourcing that file still gets the default file-backed store.

The platform web shell currently embeds profile editing, theme palette selection, background presets, upload background, and logout inside the sidebar account popover. Those controls already call the current-user profile and theme APIs, but the interaction is cramped and visually hard to use.

Goals / Non-Goals

Goals:

• Load repository-local .env values into platform configuration before storage initialization.
• Preserve process environment precedence over .env values so deployment systems can override local files.
• Keep profile and theme persistence backed by existing user APIs and the configured metadata repository.
• Replace the account popover editor with a dedicated personal settings page that is available to all authenticated users.
• Preserve the current magical crystal-moonlight shell style and shared surface classes.

Non-Goals:

• Add a normalized relational user schema or migrations beyond the existing MySQL metadata snapshot table.
• Add external account providers, billing, cloud host provisioning, or plugin marketplace workflows.
• Expose raw credentials, host paths, or direct run/plugin internals to the web UI.

Decisions

1. Load .env inside platform/config

   • config.Load() will call a small local dotenv loader before reading values.
   • The loader will check common local paths such as .env and platform/.env relative to the current working directory.
   • Existing process environment values win over file values.
   • Alternative considered: requiring users to source .env. Rejected because the observed failure is that local .env exists but platform startup does not consume it.

2. Keep MySQL persistence through the existing snapshot repository

   • The fix only makes backend selection reliable; it does not introduce normalized SQL tables for users.
   • Profile and theme updates already flow through UpdateUser, which persists through repo.Store; this remains the single write path.
   • Alternative considered: adding user-specific SQL tables now. Rejected because it is broader than the current bug and would duplicate the existing store abstraction.

3. Move personal settings to a route instead of a popover

   • Add a profileSettings page id, route, registry entry, and page component.
   • The sidebar account control becomes a navigation entry point to that page, with logout remaining available from the settings page.
   • Theme controls move into the page but continue to use theme/tokens.ts helpers and the session store API methods.
   • Alternative considered: converting the popover into a larger drawer. Rejected because the user specifically wants a normal personal configuration interface, and a page is more ergonomic for forms and preview grids.

Risks / Trade-offs

• [Risk] .env parsing can accidentally override production environment values. → Mitigation: only set variables that are not already present in os.Environ.
• [Risk] Multiple working directories make .env discovery ambiguous. → Mitigation: try root .env and platform/.env from the process working directory, and use deterministic later-file fallback only for missing keys.
• [Risk] Uploaded background data URLs can be large. → Mitigation: preserve the existing client-side behavior and persistence API contract rather than expanding backend payload rules in this change.
• [Risk] Removing the popover editor changes a familiar access point. → Mitigation: keep the sidebar account button visible and route it directly to the new personal settings page.

Migration Plan

1. Add dotenv loading tests that prove platform/.env selects MySQL settings and explicit process env overrides file values.
2. Add the personal settings route/page and update existing shell/session wiring to keep API-backed persistence.
3. Validate OpenSpec, backend config tests, frontend tests/typecheck/build, structure checks, and a browser walkthrough for the personal settings page.