Decide what the home screen offers: commands and settings

[Sandstorm831]

Question

What does Secant's home screen offer beyond its menu? Decide whether it carries a command bar where / lists commands, which commands exist and how they are invoked and filtered, which settings a user can change (themes first), and where per-user preferences persist.

[Sandstorm831]

Starting context

Input	Why it matters	Authority
Charting record, section Raised during charting	The reporter's ask: a home command bar where / lists commands, and a way to pick themes and other settings, like OpenCode	Canonical (source report)
Study how OpenCode's home screen offers commands, themes, and settings	OpenCode's prompt, / list, palette, theme picker, two preference stores, and startup load order, plus Secant's current home and theme	Research
src/tui/home.tsx and src/tui/vendor/theme-context.tsx	Secant's current four-entry menu and the vendored theme system, fixed to nord	Canonical (current behaviour)
src/composition/wiring.ts (the Secant home, ~/.secant or SECANT_HOME)	Where Secant already keeps per-user state, and so where saved preferences could live	Canonical (current behaviour)
ADR 0018 and src/tui/AGENTS.md	The vendor boundary and the TUI Module's key-binding and layout invariants a command bar must respect	Canonical
Slicing rulebook, rule 1	A user-facing slice lands in the TUI and headless clients alike, so decide what a setting means for headless	Canonical

Required methods

• /grilling
• /domain-modeling
• /prototype, only if how the home screen looks becomes the open question

Reading rule

Read the research's Answer and its Secant-today section first. Decide what the home screen offers and how commands are invoked before deciding
which settings exist and where they persist. Saved preferences are new durable state with no glossary term or owning Module yet: name the concept
and choose its owner under the topology guidance rather than letting the TUI own a file on its own.

[Sandstorm831]

Resolution

Confirmed with the human on 2026-09-29. This is a planning decision; implementation follows the map's milestone and spec route.

Home and command access

Home becomes one command launcher: a search field with its commands listed underneath. It has no slash prefix and no ordinary agent-message input. With an empty query, the order is fixed:

1. Start a Run
2. Workflow Bundles
3. Previous Runs
4. Harnesses
5. Themes
6. Quit

Typing searches command names and descriptions and ranks matches by relevance; the fixed order breaks ties. Clearing the query restores the fixed order. Keep search simple: one command catalog and shared search behavior for Home and the palette, using existing suitable presentation primitives. No personalized ordering, command history, plugin framework, or configurable ranking is needed.

On arrival, search has focus and nothing is selected. Up/Down transfers focus to the results and selects an item. Enter runs an explicitly selected item; it does not run a search result while search has focus, even if only one result matches. Esc from results returns focus to search, and Esc within search clears its query. Ctrl+C clears text first, then invokes Quit when empty. No bare-letter command shortcuts steal text input. Returning Home resets query, selection, and focus to that initial state.

Ctrl+P opens the applicable command palette on other screens. Initially Themes and Quit are available throughout the app; the four navigation commands remain on Home. Quit uses its existing confirmation and shutdown handling. Both surfaces share the same command catalog; each command owns its availability and action, while surfaces own presentation and focus. Modal focus takes precedence over underlying bindings.

Theme and appearance

Themes opens a searchable picker over the 25 existing vendored themes, with a Dark / Light appearance choice. Defaults are everforest / Dark: everforest is already decided by ADR 0036. Use the existing themes' dark and light palettes.

Moving theme selection previews it across the UI. Enter or clicking confirms the chosen appearance. Esc cancels an unconfirmed preview and restores the appearance active before that preview. The saved and currently applied values are distinct: applying an appearance is independent of saving it.

A failed save leaves the chosen theme and appearance active. Report that the active choice was not saved and allow retry without undoing it; the picker can remain open for retry. A confirmed choice is not rolled back because persistence failed. The next launch uses the last successfully saved preferences.

No animation or mouse setting is added. Custom theme files and automatic terminal-mode detection are deferred.

Preferences, ownership, and headless

Preferences are saved presentation choices shared across Workspaces within one Secant home: theme and dark/light appearance. They determine a TUI's initial appearance; local preview or an unsuccessful save can make its active appearance differ.

The existing Secant home (~/.secant, overridden by SECANT_HOME) scopes Preferences. Separate homes keep separate choices. Catalog owns persistence in its existing catalog.db, and Application exposes preference reads and changes through the Projection Port. Composition supplies the resolved home. TUI owns command search, focus, theme assets, live preview, and rendering; it does not own a durable file. Keep the Interface narrow, semantic, and shared by the clients.

Headless gains a small secant settings command group to read and change the same saved Preferences through the same Application Interface. These values affect the TUI; they do not change headless output colors.

Missing or unsupported preference values fall back to the relevant default (everforest or Dark). A preference read failure uses defaults with a notice. Failures affecting the whole Catalog retain existing handling; preference recovery does not hide those failures. Failure classification and validation stay with their owning Modules, and presentation formats the result.

Updates preserve unrelated preferences atomically. For the same preference, the latest committed change wins. The current TUI applies its local choice immediately; another running instance picks up saved changes on its next launch. No cross-process live preference synchronization is introduced.

Disposition

The architecture record names Preferences, extends Catalog's durable responsibility, and amends ADR 0018's original fixed-theme/no-picker assumption. ADR 0036's everforest default, vendor provenance, attribution, and existing Quit behavior remain authoritative.

The map's fog about typed Workbench commands is now sharp enough for Decide how typed commands work in the Run Workbench compose: command names, discovery, literal message handling, availability, and settlement still need their own human decision. This ticket does not decide or implement those commands.

This resolves Home commands and settings and supplies a decided input to Approve the second pre-public-release Amendment: the decided redesigns.

[Sandstorm831]

Repository record

The documentation is in Record home launcher and saved Preferences decision, merged after all 14 applicable CI checks passed. The four skipped jobs were tag-only release approval/promotion jobs. Merge commit 29e1cbfef65b7512371787356c0a3dc32898ec65 is signed and verified; it preserves the human's original signed commit.

• ADR 0037: saved Preferences ownership and independent appearance application
• Preferences glossary
• Updated topology guide
• ADR 0018 amendment

The pinned commit was made and pushed by the human; GitHub verifies its SSH signature. These records preserve the confirmed resolution above.