Skip to content

docs: record home launcher and saved Preferences decision #268

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sandstorm831 merged 1 commit into from
Sep 29, 2026
Merged

docs: record home launcher and saved Preferences decision #268

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CONTEXT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,8 @@ cluster that matches the task, followed by its related ADRs when the task needs
- **Renderer Port** — the Secant-owned Interface around the terminal renderer, covering lifecycle only: size, key input, resize, and teardown.
It exists so the whole shell lifecycle is exercisable against a fake with no terminal, and it carries the teardown ordering the legacy Windows
console host requires. See [ADR 0018](./docs/adr/0018-adopt-opencode-presentation-as-pinned-reduced-vendor.md).
- **Preferences** — saved presentation choices shared across **Workspaces** within one Secant home: the theme and its dark or light appearance.
They determine a TUI's initial appearance; its active appearance can differ during a preview or after an unsuccessful save.

### Secant clusters

Expand Down
5 changes: 3 additions & 2 deletions docs/adr/0018-adopt-opencode-presentation-as-pinned-reduced-vendor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,9 @@ this ADR already drops — Cursor, Vercel, GitHub, Material, and Monokai — it
generic community palettes: `opencode`, `orng`, and `lucent-orng` (OpenCode's signature theme and its two orange house palettes). Shipping a theme
that carries the upstream tool's own identity inside Crucible raises the same naming question the product-named five did, so the same answer applies.
That leaves 25 of the 33 upstream theme assets shipped, each attributed by one line in `THIRD-PARTY-NOTICES.md`. Because the default OpenCode theme was
among the drops, Crucible's shipped default is `nord` — a widely-known MIT community palette — and there is no theme picker and no persisted preference
yet.
among the drops, Crucible initially shipped `nord` with no picker or persisted preference. Amended 2026-09-29: [ADR 0036](./0036-the-run-workbench-mirrors-the-agent.md)
chooses everforest as the default, and [ADR 0037](./0037-own-saved-presentation-preferences-in-catalog-and-apply-themes-independently.md) adds the picker,
dark and light appearance, and persisted Preferences.

## Amendment (ADR 0030): runtime resolved, legacy conhost dropped

Expand Down
21 changes: 21 additions & 0 deletions ...own-saved-presentation-preferences-in-catalog-and-apply-themes-independently.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# Own Saved Presentation Preferences in Catalog and Apply Themes Independently

Secant adds saved **Preferences** for theme and dark or light appearance, shared across Workspaces within one Secant home. The human confirmed the
home launcher, theme picker, and headless settings behavior on
[Decide what the home screen offers: commands and settings](https://github.com/secantdev/secant/issues/246); that ticket holds the UX decision.

Application owns preference reads and changes through the existing Projection Port, and Catalog owns their persistence in `catalog.db`. Composition
supplies the resolved Secant home. Catalog already stores home-wide Workspace approvals, so extending that owner keeps transaction ordering,
validation, and failure translation in one place without introducing another storage system or allowing presentation to own durable files. This
extends [ADR 0025](./0025-organize-target-code-around-owned-deep-modules.md)'s Catalog responsibility. TUI and headless settings use the same
Application Interface; the TUI command catalog, search, focus, theme assets, and rendering remain presentation concerns.

Applying an appearance is independent of saving Preferences. TUI preview and confirmed appearance are local presentation state; successful saves
change the durable Preferences. A failed save reports that the choice was not saved and leaves the chosen appearance active. Missing or unsupported
preference values use everforest and dark appearance; a preference read failure reports a notice and uses those defaults, while a failure affecting
the whole Catalog retains its existing handling. Updates preserve unrelated preferences atomically, with the latest committed change winning for
the same preference. Other running instances adopt saved changes on their next launch; cross-process live synchronization is outside this decision.

The defaults are everforest, as decided in [ADR 0036](./0036-the-run-workbench-mirrors-the-agent.md), and dark appearance. The picker uses the 25
existing vendored themes and their existing dark and light palettes. This supersedes ADR 0018's initial fixed-theme, no-picker, no-persistence choice;
its vendor and attribution rules remain in force. Custom theme files, automatic terminal-mode detection, and animation or mouse settings are deferred.
36 changes: 19 additions & 17 deletions docs/agents/topology.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,23 +8,23 @@ The [Module design](./module-design.md), [dependency](./dependencies.md), and [t

One ESM package contains these ownership areas. Every path exists; new files land under the area that owns their behavior, never in a new one.

| Source area | Responsibility |
| -------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `src/cli/` | CLI hosting and dispatch to the selected client; one executable entry |
| `src/composition/` | Outermost construction, configuration wiring, and lifecycle wiring |
| `src/application/` | Projection Port, separate Bundle-management Interface, Preflight, launch, and cross-domain coordination |
| `src/workflow/` | Execution-free Routing composition, static Step-kind contracts, and their authored value vocabulary |
| `src/bundle/` | Non-executing archive validation/build, Bundle Asset capture, and managed Bundle bytes |
| `src/catalog/` | `catalog.db`, installation lifetime, Trust grants and their Operation receipts, replaceable Run index |
| `src/drizzle/` | Generated per-database SQL migrations and the embedded ordered migration journals |
| `src/run/execution/` | Run lifecycle policy, uniform scheduling/retries, and private executable Step kinds |
| `src/run/store/` | Run creation/deletion, Workspace coordination and fencing, `run.db`, canonical records, and atomic publication |
| `src/run/store/artifacts/` | Private Run Artifact capture, Git staging/history, and verified Workspace materialization |
| `src/process/` | Owned child process: PATH-walk executable resolution, Windows shim resolution, direct spawn, tree-reaping kill |
| `src/harness/` | Secant's Harness Interface, discovery/qualification, and private native Adapters |
| `src/tui/` | Secant presentation plus the reduced OpenCode-derived presentation subset |
| `src/tui/renderer/` | Renderer Port lifecycle and terminal teardown ordering |
| `src/headless/` | Headless client, including Bundle-management commands |
| Source area | Responsibility |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `src/cli/` | CLI hosting and dispatch to the selected client; one executable entry |
| `src/composition/` | Outermost construction, configuration wiring, and lifecycle wiring |
| `src/application/` | Projection Port, separate Bundle-management Interface, Preferences use cases, Preflight, launch, and cross-domain coordination |
| `src/workflow/` | Execution-free Routing composition, static Step-kind contracts, and their authored value vocabulary |
| `src/bundle/` | Non-executing archive validation/build, Bundle Asset capture, and managed Bundle bytes |
| `src/catalog/` | `catalog.db`, Preferences persistence, installation lifetime, Trust grants and their Operation receipts, replaceable Run index |
| `src/drizzle/` | Generated per-database SQL migrations and the embedded ordered migration journals |
| `src/run/execution/` | Run lifecycle policy, uniform scheduling/retries, and private executable Step kinds |
| `src/run/store/` | Run creation/deletion, Workspace coordination and fencing, `run.db`, canonical records, and atomic publication |
| `src/run/store/artifacts/` | Private Run Artifact capture, Git staging/history, and verified Workspace materialization |
| `src/process/` | Owned child process: PATH-walk executable resolution, Windows shim resolution, direct spawn, tree-reaping kill |
| `src/harness/` | Secant's Harness Interface, discovery/qualification, and private native Adapters |
| `src/tui/` | Secant presentation plus the reduced OpenCode-derived presentation subset |
| `src/tui/renderer/` | Renderer Port lifecycle and terminal teardown ordering |
| `src/headless/` | Headless client, including Bundle-management commands |

`cli/main.ts` and `composition/main.ts` name entrypoints, not single-file implementations. A composition root may span cohesive private wiring files
and invoke child composition roots. Only the hosting entrypoint or parent root invokes a root; domain Modules receive dependencies.
Expand All @@ -40,6 +40,8 @@ An `index.ts` is valid for one cohesive Module after declaring it in that table.
- Clients receive Application Interfaces; they import `projection-port.ts` and, for headless Bundle management, `bundle-management.ts`.
`application.ts` is the construction surface for composition, not a client shortcut. Client contracts and their `contracts/` subtree remain
self-contained; they expose normalized semantic values rather than internal runtime, storage, or Harness objects.
- Preferences cross the Projection Port; Catalog owns their durable storage and the TUI owns active appearance. Read
[ADR 0037](../adr/0037-own-saved-presentation-preferences-in-catalog-and-apply-themes-independently.md) before changing preference ownership or save handling.
- Application coordinates the domain Modules through their Interfaces. Bundle and Catalog depend only on the static Workflow vocabulary.
Catalog's Run index is advisory; Application uses Run Store authority for lifecycle decisions.
- Drizzle owns only generated migration assets and their ordered journal Interface. Catalog and Run Store keep their schemas, queries, SQLite
Expand Down
Loading