From a2bf41a9b2347a5e52a8036765008e0c48b9de67 Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Wed, 7 Oct 2026 03:44:09 -0400
Subject: [PATCH 1/5] docs(ui): Compass Settings design record (RIG-4775)

Section nav and /settings/:section routing, row anatomy on the shared
primitives, a per-section save model, and the Providers section from the
enrollment record (RIG-3121). Two open questions for Matt.

Ledger-impact: DL-431, DL-433, DL-434 added.
Spec-impact: none. Refs RIG-4775

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 docs/designs/ui/compass-settings/design.md | 399 +++++++++++++++++++++
 1 file changed, 399 insertions(+)
 create mode 100644 docs/designs/ui/compass-settings/design.md

diff --git a/docs/designs/ui/compass-settings/design.md b/docs/designs/ui/compass-settings/design.md
new file mode 100644
index 000000000..5ca8d479f
--- /dev/null
+++ b/docs/designs/ui/compass-settings/design.md
@@ -0,0 +1,399 @@
+# Compass Settings page
+
+Builds on: brand parity (`compass-brand-parity/design.md`, open PR #1915:
+square corners, weights, surfaces, `--cx-border-field`, text-entry
+primitives), [UX foundation](../compass-ux-foundation/design.md)
+Refs: RIG-4775 (this record); RIG-3121 (Providers, task E5 of the
+[gateway OAuth enrollment record](../../server/compass-gateway-oauth-enrollment/design.md));
+ledger DL-431, DL-433, DL-434 (DL-432 is held for Open Questions 1 and 2)
+Depends on: brand-parity T9 (S1); enrollment E3 (S7)
+
+## Problem / Intent
+
+Matt's ask: "Settings styling and layout are bad, and we likely need many
+more settings. Write a full settings design (sections, which settings
+exist, layout), then implement."
+
+Today Settings is one page that edits the tracker config. Defects (from
+`SettingsView.tsx`, the `.settings-*` rules in `app.css`, and
+`settings.png`):
+
+1. **Bespoke boxes.** `.settings-input`/`.settings-select` and
+   `.settings-btn*` copy `.cx-input` and `.cx-btn`.
+2. **Raw sizes and bold.** `14px`/`12px` heads at weight `600`, `11px`
+   labels, a `10px` gap; none is a token.
+3. **Rounded cards.** `.settings-section` has `--cx-radius-md`.
+4. **Fixed widths and wrapping.** `100px` and `140px` status columns clip
+   long names; the `flex-wrap` fields row breaks into ragged lines.
+5. **One page, no sections.** Editor and model registry share one scroll
+   and one route.
+6. **The one edit does little.** The store always uses
+   `createFixtureTrackerSeam(DEFAULT_TRACKER_CONFIG)`, which ignores its
+   `_config`; only the handle reaches the fixture queue. The kind and the
+   status map change nothing, and the server maps tracker status itself
+   (DL-129). Nothing shows the server, account, motion, or providers.
+
+Brand-parity T2a and T9 fix defects 2 and 3 (they sweep every radius and
+`font-weight: 600` in `app.css`). This record fixes the rest: one view
+with a section nav, a route per section, one row anatomy on the shared
+primitives, and a save model per section.
+
+## Approach
+
+### A1 — Sections and settings
+
+Sections in nav order, with the recommended Open Question answers:
+
+- **General** (`general`)
+  - Server URL: read-only `connection.baseUrl`, the URL the transport uses
+    in both hosts. New.
+  - Mode: read-only `shellMode()`: none → Browser, `"embedded"` → Embedded
+    server, `"client"`/`"setup"`/`"reopen"` → Remote server (setup reaches
+    the app only by connecting; reopen never mounts it). New.
+  - Server version: read-only `version`, `api_version`, and `rev` from
+    `GetServerInfo` (the UI reads the first two today). "Not connected"
+    when `store.daemon().live` is false. New.
+  - Signed in as: read-only handle and display name, `store.caller()`. New.
+  - Keyboard shortcuts: a button that opens the shortcuts overlay. New.
+  - Usage data: Open Question 2. New.
+- **Appearance** (`appearance`): Reduce motion, Follow system or Always,
+  per device in localStorage `compass.settings.reduceMotion`. Always sets
+  `:root[data-reduce="on"]`, which the CSS already honors and nothing sets
+  today. New.
+- **Tracker** (`tracker`): exists; its future is Open Question 1.
+- **Models** (`models`): the model registry, read-only. Exists.
+- **Providers** (`providers`): enrollment E5 (A5). Needs E3
+  (`ProviderEnrollmentService`), not yet in the proto, Go, or the UI.
+
+Not in this record: editing the server URL (deferred, native server URL
+record OQ-5); browser sign-out (no signed-out boot path); a day theme
+(ux-foundation D2, "later"); key remap (deferred; a Keyboard section comes
+with it); notifications (none exist); Secrets (`SecretsService` overlaps
+the Providers API-key entry, so it gets its own design after E5); Replay
+tour (a General row once the tour UI merges); the fleet config bundle
+(`GetAgentConfigInfo`, read-only member names: fleet information, not a
+preference; a later Fleet section can show it beside Models); pinned
+agents and window layout (set in place, they stay there).
+
+### A2 — Layout
+
+`.settings-view` is a grid of two columns: the section nav and the body.
+
+- **Nav.** `<nav aria-label="Settings sections">` of links in the
+  vertical `.cx-tabs` look; the current one has `aria-current="page"`.
+  Links, because each section is a route that opens, copies, and goes back.
+- **Narrow pane.** Under `@container view-panel (inline-size < 560px)` the
+  nav is a horizontal `.cx-tabs` strip above the body, and rows stack.
+- **Body.** One section. A head (`--cx-text-sm`, `--cx-text-bright`,
+  uppercase, letter-spaced, no weight, per brand-parity A9) and one line
+  of help in `--cx-text-dim`. Capped at `72ch`.
+- **Row.** A grid, `minmax(16ch, 1fr) minmax(0, 2fr)`: the label (help
+  under it in `--cx-text-dim`, `--cx-text-xs`, via `aria-describedby`),
+  then the control. A `1px solid var(--cx-border)` line between rows; no
+  card, radius, or fill.
+- **Controls**, all primitives, no box styles: `input.cx-input`,
+  `select.cx-select`, plain text for read-only values, `.cx-btn` actions
+  (`primary` commits, `danger` destroys). One of two or three is `.cx-btn`
+  buttons with `aria-pressed` (the pressed one also `data-selected`) in a
+  `role="group"` named by the row label; each is a tab stop.
+- **Row status.** Pending, done, or error text in a `role="status"` under
+  the row; errors in `--cx-error`.
+
+### A3 — Route
+
+`/settings/:section`. `parseRoute` maps bare `/settings` to the first
+section and an unknown section id to the Bridge (as `/agent` with no id
+does). `routePath` always prints `/settings/<section>`, so bare
+`/settings` is not canonical.
+
+A non-canonical path renders the catch-all, `RedirectHome`, which sends
+its own view to `/`. It becomes `RedirectCanonical`, which sends its view
+to `routePath(view.route())`: `/` for every path that goes home today,
+`/settings/<first>` for `/settings`, so old links and restored layouts
+land on a section.
+
+Every opener (`showSettings`, behind `Mod+,`, `G S`, the palette, and the
+destinations list; and the sidebar link) targets `store.settingsPath()`,
+the last section shown in this window or the first. The layout's `open`
+dedupe matches exact paths, so an open Settings tab on that section is
+focused, not duplicated. A detached window (DL-160) opens on its section.
+The palette gets "Go to Settings: Label" per section; the window title is
+"Settings · Label".
+
+### A4 — Save model, per section
+
+- **Immediate** for a device preference (Reduce motion, Usage data): the
+  change applies and is stored on click.
+- **Per action** for Providers: each Connect, code, key, and Disconnect is
+  one RPC with its own pending and error state on its row. Fields keep
+  their text until submitted.
+- **None** for read-only rows. No page-level Save; Tracker follows Open
+  Question 1.
+
+### A5 — Providers (E5)
+
+S7 implements E5 as written: the `ListProviders` policy filter, connected
+state, Connect then the paste-code dialog with `instructions`, the
+attempt-expiry countdown and re-begin, API-key entry, Disconnect with a
+confirm, E5's store accessors, and no token value rendered or stored. It
+changes E5 in two points only: E5's "beside the tracker-config editor"
+becomes the Providers section, one A2 row per provider; and E5's
+"draft/commit pattern" becomes A4's per-action model, because each action
+is its own RPC and the tracker editor may go (Open Question 1).
+
+## Alternatives considered
+
+- **One long page with anchored headings.** The hash router owns `#`, so
+  a heading cannot be linked, and every section shares one scroll.
+- **A modal dialog.** DL-160 makes Settings a window-scoped view.
+- **Horizontal tabs only.** Four or five sections fit a strip today, but
+  the out-of-scope list names more (Keyboard, Secrets, Fleet, a
+  server-backed Tracker), and a strip under the window's tab strip
+  (DL-390) reads as nested tabs. It stays as the narrow fallback.
+- **A switch primitive, or a roving radiogroup.** A switch is a new
+  primitive for two rows. A radiogroup needs one tab stop and arrow keys;
+  `createRovingGroup` is built around dispatcher command ids.
+  `aria-pressed` buttons need neither.
+- **One Save bar for the whole page.** Device preferences and RPC actions
+  cannot wait for a page-level Save.
+
+## Global Constraints
+
+- **After brand-parity T9.** T2a and T9 rewrite the `.settings-*` radii
+  and weights and recapture every shot; S1 starts after T9 merges, so it
+  does not rebase on the same lines or recapture twice. T7 only changes
+  the `.cx-input` border; tasks use `.cx-input` before or after it.
+- **Route conflicts.** Brand-parity T5 (`/agents`) and T10 (`/backlog`
+  and `/done` render the Bridge) edit `RouteMatch`, `parseRoute`,
+  `ROUTE_PATTERN`, and `appRoutes`. The cases do not overlap; whichever
+  lands second rebases.
+- **Tokens only**, the D7 stylelint guard, and the T2a and T9 rules.
+- **Each component imports the primitive CSS it renders** (brand-parity
+  A7). No new primitive and no `.settings-*` box style; layout classes in
+  `settings.css` only.
+- **Every entry keeps working:** `Mod+,`, `G S`, palette `view.settings`,
+  the sidebar link, and `/#/settings`.
+- **Device preferences** use localStorage keys `compass.settings.<name>`
+  through `safeLocalStorage()`; an invalid value reads as the default.
+- **Copy.** Sentence-case labels; one-sentence help.
+- **Baselines and stacking.** Recapture under the pinned dev shell and
+  commit per DL-399; one linear line, red-first tests, lane `implement-ts`.
+- **Public repo.** Cite only this repo and `docs/specs/brand/`.
+
+## Plan
+
+S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens.
+
+### S1 — Shell and section route
+
+- **Gate:** brand-parity T9 merged.
+- **Do:** A2, A3, with today's two parts as the first sections.
+- **Interfaces:**
+  - `apps/ui/src/view-route.ts`:
+    `export const SETTINGS_SECTIONS = ["tracker", "models"] as const;`,
+    `export type SettingsSection = (typeof SETTINGS_SECTIONS)[number];`,
+    `export const SETTINGS_SECTION_LABEL: Record<SettingsSection, string>`.
+    The settings member of `RouteMatch` becomes
+    `{ view: "settings"; section: SettingsSection }`. `parseRoute`: no
+    `param` → `SETTINGS_SECTIONS[0]`; a known id → that id; another →
+    `{ view: "bridge" }`. `routePath` → `` `/settings/${section}` ``.
+  - `ViewHost.tsx`: `ROUTE_PATTERN.settings = "/settings/:section"`.
+    `routes.tsx`: `{ path: "/settings/:section", component: SettingsView }`;
+    `RedirectHome` → `RedirectCanonical`, which calls
+    `view.navigate(routePath(view.route()))`.
+  - Store: `settingsSection(): SettingsSection`,
+    `setSettingsSection(section: SettingsSection): void`, and
+    `settingsPath(): string`; `showSettings` navigates to
+    `settingsPath()`; the `LeftSidebar` link uses
+    `() => store.settingsPath()`.
+  - `components/SettingsView.tsx` moves to `components/settings/`:
+    `SettingsView.tsx` (the shell: reads the section from its view scope,
+    calls `setSettingsSection`, renders nav and body, imports `tabs.css`,
+    `button.css`, `input.css`, and `./settings.css`); `TrackerSection.tsx`
+    and `ModelsSection.tsx` (today's two blocks, unchanged);
+    `SettingsRow.tsx` (`export function SettingsRow(props: { label: string;
+    help?: string; for?: string; children: JSX.Element }): JSX.Element`);
+    `sections.tsx` (`export const SECTION_VIEW: Record<SettingsSection, ()
+    => JSX.Element>`); `settings.css` (shell, nav, fallback, rows).
+  - `spine.ts`: a `view.settings.<id>` per section, "Go to Settings:
+    Label", shaped like `view.settings`; `route-title.ts`: "Settings ·
+    Label".
+  - `app.css`: take `.settings-view` out of the shared list rule; delete
+    `.settings-head` and `.settings-section*`.
+  - Tests that expect bare `/settings` move to `/settings/<id>`
+    (`view-route.test.ts`, `window-history.test.tsx`,
+    `tab-keep-alive.test.tsx`); `settings-mapping.test.ts` changes its
+    import; `SettingsView.model-registry.test.tsx` →
+    `settings/ModelsSection.test.tsx`.
+- **Test (red first):** `view-route.test.ts`: `/settings/models`
+  round-trips; `/settings` parses to the first section; `/settings/nope`
+  parses to the Bridge. `settings/SettingsView.test.tsx` with `mountApp`:
+  `/settings` ends on `/settings/tracker` with that link
+  `aria-current="page"`; clicking Models moves to `/settings/models` and
+  shows the registry, not the editor; after that, `store.showSettings()`
+  returns to `/settings/models`; `/nope` still ends on `/`.
+- **Baselines:** recapture `settings.png`; add `settings-narrow.png` (480px).
+
+### S2 — General section
+
+- **Do:** A1 General, without Usage data (S6).
+- **Interfaces:**
+  - `SETTINGS_SECTIONS` gains `"general"` first;
+    `settings/GeneralSection.tsx` in `SECTION_VIEW`.
+  - `DaemonInfo` gains `rev: string`; `probeServer` reads `rev`;
+    `STUB_DAEMON.rev` is `""`.
+  - `AppStoreOptions` gains `serverUrl?: string`, which `main` in
+    `index.tsx` sets to `connection.baseUrl`; the store exposes
+    `serverUrl(): string | undefined`.
+  - `GeneralSection.tsx` exports `modeLabel(mode: ShellMode | undefined):
+    "Browser" | "Embedded server" | "Remote server"`, an exhaustive switch.
+- **Test (red first):** `settings/GeneralSection.test.tsx` with
+  `createRouterTransport` serving `getServerInfo` (`1.2.3`, an API
+  version, `abc123`): the three show; offline shows "Not connected"; the
+  caller's handle shows; the shortcuts button opens the overlay;
+  `modeLabel` maps all five inputs.
+- **Baselines:** recapture `settings.png` (now General).
+
+### S3 — Appearance section
+
+- **Interfaces:**
+  - New `apps/ui/src/preferences.ts`:
+
+    ```ts
+    export type ReduceMotion = "system" | "on";
+    export const REDUCE_MOTION_KEY = "compass.settings.reduceMotion";
+    export function loadReduceMotion(storage: Storage | undefined): ReduceMotion;
+    export function saveReduceMotion(storage: Storage | undefined, value: ReduceMotion): void;
+    export function applyReduceMotion(root: HTMLElement, value: ReduceMotion): void;
+    ```
+
+  - Store: `reduceMotion(): ReduceMotion` and `setReduceMotion(value:
+    ReduceMotion): void` (saves and applies); `mount.tsx` applies the
+    stored value before the first render. `SETTINGS_SECTIONS` gains
+    `"appearance"` after `"general"`; `settings/AppearanceSection.tsx`.
+- **Test (red first):** `preferences.test.ts`: none or junk → `"system"`;
+  `"on"` → `"on"`; apply `"on"` sets `data-reduce`, `"system"` removes it.
+  `AppearanceSection.test.tsx`: Always sets `aria-pressed`, the root
+  attribute, and the stored value.
+
+### S4 — Tracker, per Open Question 1
+
+- **Gate:** Open Question 1. Interfaces are for the recommended (e).
+- **Interfaces (e):**
+  - Delete `settings/TrackerSection.tsx`, `mergeFromTracker`,
+    `settings-mapping.test.ts`, `"tracker"` from `SETTINGS_SECTIONS`, the
+    `"tracker"` keyword of `view.settings`, and every remaining
+    `.settings-*` selector in `app.css`.
+  - `AppStore` drops `setTrackerConfig` and its two `store.test.ts` cases;
+    `trackerConfig` stays at `DEFAULT_TRACKER_CONFIG` for the fixture
+    queue.
+  - `apps/ui/src/design/surfaces.md` § Backlog / Done / Settings: replace
+    the status-mapping editor sentences (composition, empty state, flip
+    item 2) with the A2 row anatomy.
+  - File a follow-up: a server-backed Tracker section once the tracker
+    contract lands.
+- **Interfaces (a):** the editor on A2 rows; the status map is a `<table>`
+  with one free-text `input.cx-input` per state, as today (no source lists
+  a tracker's statuses); Reset and Save in a sticky section foot.
+  `settings/tracker-draft.ts` exports `createTrackerDraft(store: AppStore):
+  TrackerDraft` (`draft()`, `dirty()`, `set(next)`, `reset()`, `save()`),
+  held by the shell so a draft survives a section switch, with a nav dot
+  when dirty. `surfaces.md`'s "two-column `.cx-tree-row` table" becomes
+  that table. **(d):** the same rows, read-only, under "Preview, not
+  connected".
+- **Test (red first):** (e): no Tracker link, and `/settings/tracker` ends
+  on `/`. (a): `tracker-draft.test.ts` (clean at start; `set` dirties;
+  `reset` restores; `save` commits and cleans), and an edit survives a
+  switch to Models and back.
+- **Baselines:** recapture `settings.png`; (a) and (d) add
+  `settings-tracker.png`.
+
+### S5 — Tracker persistence
+
+- **Gate:** Open Question 1 is (a); otherwise dropped.
+- **Interfaces:** `preferences.ts` adds `loadTrackerConfig(storage:
+  Storage | undefined, workspace: string): TrackerConfig | undefined` and
+  `saveTrackerConfig(storage: Storage | undefined, workspace: string,
+  config: TrackerConfig): void`, key `compass.settings.tracker.${workspace}`
+  with the pins' `workspaceKey`. The store loads it with the pins;
+  `setTrackerConfig` saves it.
+- **Test (red first):** `store.test.ts`: a new store on the same storage
+  and workspace reads the saved config; another workspace and malformed
+  JSON give the default.
+
+### S6 — Usage data
+
+- **Gate:** Open Question 2. Interfaces are for the recommended (b).
+- **Interfaces:**
+  - `Analytics` gains `readonly enabled: boolean`, `optOut()`, `optIn()`,
+    and `optedOut(): boolean` (posthog-js `opt_out_capturing()`,
+    `opt_in_capturing()`, `has_opted_out_capturing()`); `NoopAnalytics`
+    has `enabled` false and `optedOut()` true.
+  - `AppStoreOptions` gains `analytics?: Analytics`; the store exposes
+    `analytics(): Analytics | undefined` (reused if the tour analytics
+    branch lands it first).
+  - A Usage data row in `GeneralSection.tsx`: On and Off `aria-pressed`
+    buttons, or "Off. This build sends no usage data." when disabled.
+- **Test (red first):** `analytics.test.ts`: `optOut` calls
+  `opt_out_capturing`. `GeneralSection.test.tsx` with a fake `Analytics`:
+  Off calls `optOut`, On calls `optIn`, the pressed button follows
+  `optedOut()`, and a disabled build shows the text and no buttons.
+
+### S7 — Providers section (E5)
+
+- **Gate:** enrollment E3 merged. **Do:** A5; E5's Interfaces and test
+  cycle are the contract.
+- **Interfaces:** E5's, plus: `SETTINGS_SECTIONS` gains `"providers"`
+  after `"models"`; `settings/ProvidersSection.tsx`; `openExternal` moves
+  from `MarkdownText.tsx` to `apps/ui/src/open-external.ts` (`export
+  function openExternal(url: string): void`) so Connect opens `auth_url`
+  in both hosts.
+- **Test (red first):** E5's cycle, plus: only the providers
+  `ListProviders` returns are rendered. **Baselines:** add
+  `settings-providers.png`.
+
+## Tasks
+
+- [ ] S1 — Shell and section route (after brand-parity T9)
+- [ ] S2 — General section (after S1)
+- [ ] S3 — Appearance section (after S2)
+- [ ] S4 — Tracker per Open Question 1 (after S3 and Open Question 1)
+- [ ] S5 — Tracker persistence (only if Open Question 1 is (a); after S4)
+- [ ] S6 — Usage data (after S2 and Open Question 2; top of the line)
+- [ ] S7 — Providers, E5 (after S1 and enrollment E3; top of the line)
+
+## Open Questions
+
+1. **The tracker editor.** It edits a config that only the fixture seam
+   reads, and only its handle; the kind and the status map change nothing.
+   DL-129 puts the mapping on the server, which ingests tracker status
+   through the reverse `TrackerStatusMapping`.
+   - (a) Keep the editor, rebuild it on A2 (S4), and persist it in
+     localStorage keyed by `workspaceKey` (S5). Small, but it saves a
+     value nothing uses: `rule://no-inert-gating` argues against it.
+   - (d) Show the config read-only as "Preview, not connected", and drop
+     S5. Honest about the state, but it shows a status map the server
+     does not use, which can mislead.
+   - (e) Delete the client-side editor and `setTrackerConfig`; the
+     mapping stays on the server. A Tracker section returns, server-backed,
+     when the tracker contract lands. Loses the one editable setting
+     today, and its tests.
+   - **Recommendation:** (e). Nothing the editor writes reaches the
+     server, and a read-only preview of a value the server does not use
+     misleads more than it shows.
+2. **A usage-data control, and where it goes.** No record decides
+   analytics consent. The observability record sends managed builds to
+   Rigel's PostHog and keeps self-hosted builds off by default or on the
+   deployer's own key; most self-hosted builds have no key.
+   - (a) A per-device On or Off in its own Privacy section, stored by
+     posthog-js (`opt_out_capturing()`). In a build with no key, the
+     section is one sentence.
+   - (b) The same control as a Usage data row in General, giving four
+     sections, or five if Open Question 1 keeps Tracker. A build with no
+     key shows one read-only line.
+   - (c) No user control; the deployer decides at build time. No work, but
+     a user of a managed build cannot opt out in the app.
+   - (d) A per-account consent stored on the server and read at boot.
+     Follows the account, but needs a proto field and a server task.
+   - **Recommendation:** (b). It gives a user control now with no server
+     work and no near-empty section; (d) can replace its storage later.

From 48a6a54922308dd023609a5cb2a32066c431f985 Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Wed, 7 Oct 2026 06:59:53 -0400
Subject: [PATCH 2/5] docs(ui): fold review into the Settings record (RIG-4775)

showSettings opens through the layout so dedupe applies; redirect change
stated; nav selection attributes; one held id per open question.

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 docs/designs/ui/compass-settings/design.md | 275 +++++++++++----------
 1 file changed, 138 insertions(+), 137 deletions(-)

diff --git a/docs/designs/ui/compass-settings/design.md b/docs/designs/ui/compass-settings/design.md
index 5ca8d479f..918f20e07 100644
--- a/docs/designs/ui/compass-settings/design.md
+++ b/docs/designs/ui/compass-settings/design.md
@@ -5,7 +5,8 @@ square corners, weights, surfaces, `--cx-border-field`, text-entry
 primitives), [UX foundation](../compass-ux-foundation/design.md)
 Refs: RIG-4775 (this record); RIG-3121 (Providers, task E5 of the
 [gateway OAuth enrollment record](../../server/compass-gateway-oauth-enrollment/design.md));
-ledger DL-431, DL-433, DL-434 (DL-432 is held for Open Questions 1 and 2)
+ledger DL-431, DL-433, DL-434; DL-432 and DL-435 are held for Open
+Questions 1 and 2
 Depends on: brand-parity T9 (S1); enrollment E3 (S7)
 
 ## Problem / Intent
@@ -27,11 +28,11 @@ Today Settings is one page that edits the tracker config. Defects (from
    long names; the `flex-wrap` fields row breaks into ragged lines.
 5. **One page, no sections.** Editor and model registry share one scroll
    and one route.
-6. **The one edit does little.** The store always uses
-   `createFixtureTrackerSeam(DEFAULT_TRACKER_CONFIG)`, which ignores its
-   `_config`; only the handle reaches the fixture queue. The kind and the
-   status map change nothing, and the server maps tracker status itself
-   (DL-129). Nothing shows the server, account, motion, or providers.
+6. **The one edit does little.** The store always uses the fixture seam,
+   which ignores its `_config`; `setTrackerConfig` rebuilds it, but only
+   the handle reaches the fixture queue. The kind and the status map
+   change nothing, and the server maps tracker status itself (DL-129).
+   Nothing shows the server, account, motion, or providers.
 
 Brand-parity T2a and T9 fix defects 2 and 3 (they sweep every radius and
 `font-weight: 600` in `app.css`). This record fixes the rest: one view
@@ -42,91 +43,88 @@ primitives, and a save model per section.
 
 ### A1 — Sections and settings
 
-Sections in nav order, with the recommended Open Question answers:
-
-- **General** (`general`)
-  - Server URL: read-only `connection.baseUrl`, the URL the transport uses
-    in both hosts. New.
-  - Mode: read-only `shellMode()`: none → Browser, `"embedded"` → Embedded
-    server, `"client"`/`"setup"`/`"reopen"` → Remote server (setup reaches
-    the app only by connecting; reopen never mounts it). New.
-  - Server version: read-only `version`, `api_version`, and `rev` from
-    `GetServerInfo` (the UI reads the first two today). "Not connected"
-    when `store.daemon().live` is false. New.
-  - Signed in as: read-only handle and display name, `store.caller()`. New.
-  - Keyboard shortcuts: a button that opens the shortcuts overlay. New.
-  - Usage data: Open Question 2. New.
+Sections in nav order. Tracker is OQ1; Usage data's place is OQ2.
+
+- **General** (`general`): Server URL (`connection.baseUrl`, the
+  transport's URL in both hosts); Mode (`shellMode()`: none → Browser,
+  `"embedded"` → Embedded server, `"client"`/`"setup"`/`"reopen"` →
+  Remote server, since setup reaches the app only by connecting and
+  reopen never mounts it); Server version (`version`, `api_version`, and
+  `rev` from `GetServerInfo`; "Not connected" when `store.daemon().live`
+  is false); Signed in as (`store.caller()` handle and display name); a
+  Keyboard shortcuts button that opens the overlay; Usage data (OQ2). New.
 - **Appearance** (`appearance`): Reduce motion, Follow system or Always,
   per device in localStorage `compass.settings.reduceMotion`. Always sets
-  `:root[data-reduce="on"]`, which the CSS already honors and nothing sets
-  today. New.
-- **Tracker** (`tracker`): exists; its future is Open Question 1.
+  `:root[data-reduce="on"]`, which the CSS honors and nothing sets. New.
+- **Tracker** (`tracker`): exists; Open Question 1.
 - **Models** (`models`): the model registry, read-only. Exists.
 - **Providers** (`providers`): enrollment E5 (A5). Needs E3
   (`ProviderEnrollmentService`), not yet in the proto, Go, or the UI.
 
-Not in this record: editing the server URL (deferred, native server URL
-record OQ-5); browser sign-out (no signed-out boot path); a day theme
-(ux-foundation D2, "later"); key remap (deferred; a Keyboard section comes
-with it); notifications (none exist); Secrets (`SecretsService` overlaps
-the Providers API-key entry, so it gets its own design after E5); Replay
-tour (a General row once the tour UI merges); the fleet config bundle
-(`GetAgentConfigInfo`, read-only member names: fleet information, not a
-preference; a later Fleet section can show it beside Models); pinned
-agents and window layout (set in place, they stay there).
+Not in this record: server URL edits (deferred, native server URL record
+OQ-5); browser sign-out (no signed-out boot path); a day theme (D2,
+"later"); key remap (deferred; a Keyboard section comes with it);
+notifications (none exist); Secrets (`SecretsService` overlaps the
+Providers key entry; its own design after E5); Replay tour (a General row
+once the tour UI merges); `GetAgentConfigInfo` (fleet member names, not a
+preference; a later Fleet section); pins and window layout (set in place).
 
 ### A2 — Layout
 
 `.settings-view` is a grid of two columns: the section nav and the body.
 
-- **Nav.** `<nav aria-label="Settings sections">` of links in the
-  vertical `.cx-tabs` look; the current one has `aria-current="page"`.
-  Links, because each section is a route that opens, copies, and goes back.
-- **Narrow pane.** Under `@container view-panel (inline-size < 560px)` the
-  nav is a horizontal `.cx-tabs` strip above the body, and rows stack.
-- **Body.** One section. A head (`--cx-text-sm`, `--cx-text-bright`,
+- **Nav.** `<nav aria-label="Settings sections"
+  class="cx-tabs settings-nav" data-orientation="v">` of `a.cx-tab` links;
+  the current link has `data-selected` (the `.cx-tabs` selection rule)
+  and `aria-current="page"`. Links, because each section is a route.
+- **Narrow pane.** Under `@container view-panel (width < 560px)` (as in
+  `app.css`), `settings.css` lays `.settings-nav` out as a row above the
+  body and restates the `data-orientation="h"` border and bottom accent,
+  since CSS cannot change the attribute; rows stack.
+- **Body.** One section: a head (`--cx-text-sm`, `--cx-text-bright`,
   uppercase, letter-spaced, no weight, per brand-parity A9) and one line
-  of help in `--cx-text-dim`. Capped at `72ch`.
+  of help in `--cx-text-dim`; capped at `72ch`.
 - **Row.** A grid, `minmax(16ch, 1fr) minmax(0, 2fr)`: the label (help
   under it in `--cx-text-dim`, `--cx-text-xs`, via `aria-describedby`),
-  then the control. A `1px solid var(--cx-border)` line between rows; no
+  then the control; a `1px solid var(--cx-border)` line between rows; no
   card, radius, or fill.
-- **Controls**, all primitives, no box styles: `input.cx-input`,
-  `select.cx-select`, plain text for read-only values, `.cx-btn` actions
-  (`primary` commits, `danger` destroys). One of two or three is `.cx-btn`
-  buttons with `aria-pressed` (the pressed one also `data-selected`) in a
-  `role="group"` named by the row label; each is a tab stop.
-- **Row status.** Pending, done, or error text in a `role="status"` under
-  the row; errors in `--cx-error`.
+- **Controls**, all primitives: `input.cx-input`, `select.cx-select`,
+  plain text when read-only, `.cx-btn` actions (`primary` commits,
+  `danger` destroys). Two or three choices are `.cx-btn` buttons with
+  `aria-pressed` (the pressed one also `data-selected`) in a
+  `role="group"` named by the row label. Row status (pending, done,
+  error) sits under the row in a `role="status"`, errors in `--cx-error`.
 
 ### A3 — Route
 
 `/settings/:section`. `parseRoute` maps bare `/settings` to the first
-section and an unknown section id to the Bridge (as `/agent` with no id
-does). `routePath` always prints `/settings/<section>`, so bare
-`/settings` is not canonical.
-
-A non-canonical path renders the catch-all, `RedirectHome`, which sends
-its own view to `/`. It becomes `RedirectCanonical`, which sends its view
-to `routePath(view.route())`: `/` for every path that goes home today,
-`/settings/<first>` for `/settings`, so old links and restored layouts
-land on a section.
-
-Every opener (`showSettings`, behind `Mod+,`, `G S`, the palette, and the
-destinations list; and the sidebar link) targets `store.settingsPath()`,
-the last section shown in this window or the first. The layout's `open`
-dedupe matches exact paths, so an open Settings tab on that section is
-focused, not duplicated. A detached window (DL-160) opens on its section.
-The palette gets "Go to Settings: Label" per section; the window title is
-"Settings · Label".
+section and an unknown id to the Bridge. `routePath` always prints
+`/settings/<section>`, so bare `/settings` is not canonical.
+
+The catch-all `RedirectHome` (sends its view to `/`) becomes
+`RedirectCanonical` (sends it to `routePath(view.route())`), so
+`/settings`, old links, and restored layouts land on a section. A
+behavior change: a path with extra segments now lands on the view it
+parses to, not `/` (`/backlog/foo` → `/backlog`, `/agent/x/extra` →
+`/agent/x`, `/channel/x/topic` → `/channel/x`). Unknown heads still land
+on `/`.
+
+Every opener (`showSettings` behind `Mod+,`, `G S`, the palette, and the
+destinations list; and the sidebar link) dispatches the layout's `open`
+action for `store.settingsPath()`, the last section shown in this window
+or the first. `open` matches exact paths, so an open single-view Settings
+tab on that section is focused. A second behavior change: today
+`showSettings` navigates the focused view in place (`navigateFocused`);
+after S1, with no such tab, Settings opens in a new tab, and the tab cap
+applies. A detached window (DL-160) opens on its section. The palette gets
+"Go to Settings: Label" per section; the title is "Settings · Label".
 
 ### A4 — Save model, per section
 
-- **Immediate** for a device preference (Reduce motion, Usage data): the
-  change applies and is stored on click.
+- **Immediate** for a device preference (Reduce motion, Usage data):
+  applied and stored on click.
 - **Per action** for Providers: each Connect, code, key, and Disconnect is
-  one RPC with its own pending and error state on its row. Fields keep
-  their text until submitted.
+  one RPC with its own pending and error state on its row.
 - **None** for read-only rows. No page-level Save; Tracker follows Open
   Question 1.
 
@@ -144,18 +142,16 @@ is its own RPC and the tracker editor may go (Open Question 1).
 ## Alternatives considered
 
 - **One long page with anchored headings.** The hash router owns `#`, so
-  a heading cannot be linked, and every section shares one scroll.
+  a heading cannot be linked; every section shares one scroll.
 - **A modal dialog.** DL-160 makes Settings a window-scoped view.
-- **Horizontal tabs only.** Four or five sections fit a strip today, but
-  the out-of-scope list names more (Keyboard, Secrets, Fleet, a
-  server-backed Tracker), and a strip under the window's tab strip
-  (DL-390) reads as nested tabs. It stays as the narrow fallback.
-- **A switch primitive, or a roving radiogroup.** A switch is a new
-  primitive for two rows. A radiogroup needs one tab stop and arrow keys;
-  `createRovingGroup` is built around dispatcher command ids.
-  `aria-pressed` buttons need neither.
-- **One Save bar for the whole page.** Device preferences and RPC actions
-  cannot wait for a page-level Save.
+- **Horizontal tabs only.** Four or five sections fit today, but more are
+  named (Keyboard, Secrets, Fleet, a server-backed Tracker), and a strip
+  under the window's tab strip (DL-390) reads as nested tabs. It stays as
+  the narrow fallback.
+- **A switch, or a roving radiogroup.** A switch is a new primitive for
+  two rows; a radiogroup needs arrow keys, and `createRovingGroup` is
+  built around dispatcher command ids. `aria-pressed` needs neither.
+- **One Save bar.** Device preferences and RPCs cannot wait for it.
 
 ## Global Constraints
 
@@ -163,10 +159,13 @@ is its own RPC and the tracker editor may go (Open Question 1).
   and weights and recapture every shot; S1 starts after T9 merges, so it
   does not rebase on the same lines or recapture twice. T7 only changes
   the `.cx-input` border; tasks use `.cx-input` before or after it.
-- **Route conflicts.** Brand-parity T5 (`/agents`) and T10 (`/backlog`
-  and `/done` render the Bridge) edit `RouteMatch`, `parseRoute`,
-  `ROUTE_PATTERN`, and `appRoutes`. The cases do not overlap; whichever
-  lands second rebases.
+- **Overlap with brand parity.** T5 (`/agents`) edits `RouteMatch`,
+  `parseRoute`, `routePath`, `appRoutes`, `route-title.ts`, `spine.ts`,
+  `store.ts`, and `LeftSidebar.tsx`, as S1 does. T10 leaves
+  `view-route.ts` and `ViewHost.tsx` alone but edits the `/backlog` and
+  `/done` entries in `routes.tsx`, `LeftSidebar.tsx` and its test (S1),
+  and `surfaces.md` § Backlog / Done / Settings (S4). The edits do not
+  overlap in meaning; whichever lands second rebases.
 - **Tokens only**, the D7 stylelint guard, and the T2a and T9 rules.
 - **Each component imports the primitive CSS it renders** (brand-parity
   A7). No new primitive and no `.settings-*` box style; layout classes in
@@ -175,7 +174,7 @@ is its own RPC and the tracker editor may go (Open Question 1).
   the sidebar link, and `/#/settings`.
 - **Device preferences** use localStorage keys `compass.settings.<name>`
   through `safeLocalStorage()`; an invalid value reads as the default.
-- **Copy.** Sentence-case labels; one-sentence help.
+  Copy is sentence-case; help is one sentence.
 - **Baselines and stacking.** Recapture under the pinned dev shell and
   commit per DL-399; one linear line, red-first tests, lane `implement-ts`.
 - **Public repo.** Cite only this repo and `docs/specs/brand/`.
@@ -203,9 +202,10 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
     `view.navigate(routePath(view.route()))`.
   - Store: `settingsSection(): SettingsSection`,
     `setSettingsSection(section: SettingsSection): void`, and
-    `settingsPath(): string`; `showSettings` navigates to
-    `settingsPath()`; the `LeftSidebar` link uses
-    `() => store.settingsPath()`.
+    `settingsPath(): string`. `showSettings` runs `hideShortcuts()` then
+    `dispatchLayout({ kind: "open", path: settingsPath() })`, not
+    `navigateTo`. The `LeftSidebar` link passes `() => store.settingsPath()`
+    to `openLink`; its plain click still calls `showSettings`.
   - `components/SettingsView.tsx` moves to `components/settings/`:
     `SettingsView.tsx` (the shell: reads the section from its view scope,
     calls `setSettingsSection`, renders nav and body, imports `tabs.css`,
@@ -220,18 +220,26 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
     Label".
   - `app.css`: take `.settings-view` out of the shared list rule; delete
     `.settings-head` and `.settings-section*`.
-  - Tests that expect bare `/settings` move to `/settings/<id>`
-    (`view-route.test.ts`, `window-history.test.tsx`,
-    `tab-keep-alive.test.tsx`); `settings-mapping.test.ts` changes its
-    import; `SettingsView.model-registry.test.tsx` →
+  - Tests that expect bare `/settings` move to `/settings/<id>`:
+    `view-route.test.ts`, `window-history.test.tsx`,
+    `tab-keep-alive.test.tsx`, and `components/LeftSidebar.test.tsx` ("a
+    view link opens its view in a new tab…" expects `["/",
+    "/settings/tracker"]`). `settings-mapping.test.ts` changes its import;
+    `SettingsView.model-registry.test.tsx` →
     `settings/ModelsSection.test.tsx`.
-- **Test (red first):** `view-route.test.ts`: `/settings/models`
-  round-trips; `/settings` parses to the first section; `/settings/nope`
-  parses to the Bridge. `settings/SettingsView.test.tsx` with `mountApp`:
-  `/settings` ends on `/settings/tracker` with that link
-  `aria-current="page"`; clicking Models moves to `/settings/models` and
-  shows the registry, not the editor; after that, `store.showSettings()`
-  returns to `/settings/models`; `/nope` still ends on `/`.
+- **Test (red first):**
+  - `view-route.test.ts`: `/settings/models` round-trips; `/settings`
+    parses to the first section; `/settings/nope` parses to the Bridge.
+  - `routing.test.tsx` (`RedirectCanonical`): `mountApp("/backlog/foo")`
+    ends on `/backlog`; `mountApp("/no-such-surface")` still ends on `/`.
+  - `settings/SettingsView.test.tsx` with `mountApp`: `/settings` ends on
+    `/settings/tracker`, its link has `data-selected` and
+    `aria-current="page"`; clicking Models moves to `/settings/models` and
+    shows the registry, not the editor.
+  - `store.test.ts` (`showSettings` uses `open`): from `/` it gives tabs
+    `["/", "/settings/tracker"]`, the new one active; from `/` again it
+    focuses that tab (still two); after that tab moves to
+    `/settings/models`, it focuses it again.
 - **Baselines:** recapture `settings.png`; add `settings-narrow.png` (480px).
 
 ### S2 — General section
@@ -251,8 +259,7 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
   `createRouterTransport` serving `getServerInfo` (`1.2.3`, an API
   version, `abc123`): the three show; offline shows "Not connected"; the
   caller's handle shows; the shortcuts button opens the overlay;
-  `modeLabel` maps all five inputs.
-- **Baselines:** recapture `settings.png` (now General).
+  `modeLabel` maps all five inputs. **Baselines:** recapture `settings.png`.
 
 ### S3 — Appearance section
 
@@ -278,34 +285,29 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
 
 ### S4 — Tracker, per Open Question 1
 
-- **Gate:** Open Question 1. Interfaces are for the recommended (e).
-- **Interfaces (e):**
+- **Gate:** Open Question 1. Interfaces are for the recommended (c).
+- **Interfaces (c):**
   - Delete `settings/TrackerSection.tsx`, `mergeFromTracker`,
-    `settings-mapping.test.ts`, `"tracker"` from `SETTINGS_SECTIONS`, the
-    `"tracker"` keyword of `view.settings`, and every remaining
-    `.settings-*` selector in `app.css`.
+    `settings-mapping.test.ts`, `"tracker"` from `SETTINGS_SECTIONS` and
+    the `view.settings` keywords, and every remaining `.settings-*` rule.
   - `AppStore` drops `setTrackerConfig` and its two `store.test.ts` cases;
-    `trackerConfig` stays at `DEFAULT_TRACKER_CONFIG` for the fixture
-    queue.
-  - `apps/ui/src/design/surfaces.md` § Backlog / Done / Settings: replace
-    the status-mapping editor sentences (composition, empty state, flip
-    item 2) with the A2 row anatomy.
-  - File a follow-up: a server-backed Tracker section once the tracker
-    contract lands.
-- **Interfaces (a):** the editor on A2 rows; the status map is a `<table>`
-  with one free-text `input.cx-input` per state, as today (no source lists
-  a tracker's statuses); Reset and Save in a sticky section foot.
-  `settings/tracker-draft.ts` exports `createTrackerDraft(store: AppStore):
+    `trackerConfig` stays at `DEFAULT_TRACKER_CONFIG` for the fixture queue.
+  - `surfaces.md` § Backlog / Done / Settings: replace the status-mapping
+    sentences (composition, empty state, flip item 2) with the A2 rows.
+  - File a follow-up: a server-backed Tracker section with the tracker
+    contract.
+- **Interfaces (a):** the editor on A2 rows; the status map a `<table>` of
+  free-text `input.cx-input` per state, as today (no source lists a
+  tracker's statuses); Reset and Save in a sticky foot.
+  `settings/tracker-draft.ts`: `createTrackerDraft(store: AppStore):
   TrackerDraft` (`draft()`, `dirty()`, `set(next)`, `reset()`, `save()`),
   held by the shell so a draft survives a section switch, with a nav dot
-  when dirty. `surfaces.md`'s "two-column `.cx-tree-row` table" becomes
-  that table. **(d):** the same rows, read-only, under "Preview, not
-  connected".
-- **Test (red first):** (e): no Tracker link, and `/settings/tracker` ends
-  on `/`. (a): `tracker-draft.test.ts` (clean at start; `set` dirties;
-  `reset` restores; `save` commits and cleans), and an edit survives a
-  switch to Models and back.
-- **Baselines:** recapture `settings.png`; (a) and (d) add
+  when dirty; `surfaces.md`'s `.cx-tree-row` table becomes that table.
+  **(b):** the same rows, read-only, under "Preview, not connected".
+- **Test (red first):** (c): no Tracker link; `/settings/tracker` ends on
+  `/`. (a): `tracker-draft.test.ts` (clean at start; `set` dirties;
+  `reset` restores; `save` commits and cleans); an edit survives a switch
+  to Models and back. **Baselines:** `settings.png`; (a) and (b) add
   `settings-tracker.png`.
 
 ### S5 — Tracker persistence
@@ -324,16 +326,15 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
 ### S6 — Usage data
 
 - **Gate:** Open Question 2. Interfaces are for the recommended (b).
-- **Interfaces:**
-  - `Analytics` gains `readonly enabled: boolean`, `optOut()`, `optIn()`,
-    and `optedOut(): boolean` (posthog-js `opt_out_capturing()`,
-    `opt_in_capturing()`, `has_opted_out_capturing()`); `NoopAnalytics`
-    has `enabled` false and `optedOut()` true.
-  - `AppStoreOptions` gains `analytics?: Analytics`; the store exposes
-    `analytics(): Analytics | undefined` (reused if the tour analytics
-    branch lands it first).
-  - A Usage data row in `GeneralSection.tsx`: On and Off `aria-pressed`
-    buttons, or "Off. This build sends no usage data." when disabled.
+- **Interfaces:** `Analytics` gains `readonly enabled: boolean`,
+  `optOut()`, `optIn()`, and `optedOut(): boolean` (posthog-js
+  `opt_out_capturing()`, `opt_in_capturing()`,
+  `has_opted_out_capturing()`); `NoopAnalytics` has `enabled` false and
+  `optedOut()` true. `AppStoreOptions` gains `analytics?: Analytics` and
+  the store exposes `analytics(): Analytics | undefined` (reused if the
+  tour analytics branch lands it first). A Usage data row in
+  `GeneralSection.tsx`: On and Off `aria-pressed` buttons, or "Off. This
+  build sends no usage data." when disabled.
 - **Test (red first):** `analytics.test.ts`: `optOut` calls
   `opt_out_capturing`. `GeneralSection.test.tsx` with a fake `Analytics`:
   Off calls `optOut`, On calls `optIn`, the pressed button follows
@@ -371,14 +372,14 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
    - (a) Keep the editor, rebuild it on A2 (S4), and persist it in
      localStorage keyed by `workspaceKey` (S5). Small, but it saves a
      value nothing uses: `rule://no-inert-gating` argues against it.
-   - (d) Show the config read-only as "Preview, not connected", and drop
+   - (b) Show the config read-only as "Preview, not connected", and drop
      S5. Honest about the state, but it shows a status map the server
      does not use, which can mislead.
-   - (e) Delete the client-side editor and `setTrackerConfig`; the
+   - (c) Delete the client-side editor and `setTrackerConfig`; the
      mapping stays on the server. A Tracker section returns, server-backed,
      when the tracker contract lands. Loses the one editable setting
      today, and its tests.
-   - **Recommendation:** (e). Nothing the editor writes reaches the
+   - **Recommendation:** (c). Nothing the editor writes reaches the
      server, and a read-only preview of a value the server does not use
      misleads more than it shows.
 2. **A usage-data control, and where it goes.** No record decides

From d647bd2e820a72eaf03c08125a492afc264edf41 Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Wed, 7 Oct 2026 07:05:04 -0400
Subject: [PATCH 3/5] docs(ui): Settings opener behaviour becomes an open
 question (RIG-4775)

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 docs/designs/ui/compass-settings/design.md | 192 ++++++++++-----------
 1 file changed, 96 insertions(+), 96 deletions(-)

diff --git a/docs/designs/ui/compass-settings/design.md b/docs/designs/ui/compass-settings/design.md
index 918f20e07..0ad61faf6 100644
--- a/docs/designs/ui/compass-settings/design.md
+++ b/docs/designs/ui/compass-settings/design.md
@@ -5,8 +5,8 @@ square corners, weights, surfaces, `--cx-border-field`, text-entry
 primitives), [UX foundation](../compass-ux-foundation/design.md)
 Refs: RIG-4775 (this record); RIG-3121 (Providers, task E5 of the
 [gateway OAuth enrollment record](../../server/compass-gateway-oauth-enrollment/design.md));
-ledger DL-431, DL-433, DL-434; DL-432 and DL-435 are held for Open
-Questions 1 and 2
+ledger DL-431, DL-433, DL-434; DL-432, DL-435, and DL-436 are held for
+Open Questions 1, 2, and 3
 Depends on: brand-parity T9 (S1); enrollment E3 (S7)
 
 ## Problem / Intent
@@ -110,14 +110,11 @@ parses to, not `/` (`/backlog/foo` → `/backlog`, `/agent/x/extra` →
 on `/`.
 
 Every opener (`showSettings` behind `Mod+,`, `G S`, the palette, and the
-destinations list; and the sidebar link) dispatches the layout's `open`
-action for `store.settingsPath()`, the last section shown in this window
-or the first. `open` matches exact paths, so an open single-view Settings
-tab on that section is focused. A second behavior change: today
-`showSettings` navigates the focused view in place (`navigateFocused`);
-after S1, with no such tab, Settings opens in a new tab, and the tab cap
-applies. A detached window (DL-160) opens on its section. The palette gets
-"Go to Settings: Label" per section; the title is "Settings · Label".
+destinations list; and the sidebar link) targets `store.settingsPath()`,
+the last section shown in this window or the first. Whether it navigates
+the focused view or opens a tab is Open Question 3. A detached window
+(DL-160) opens on its section. The palette gets "Go to Settings: Label"
+per section; the title is "Settings · Label".
 
 ### A4 — Save model, per section
 
@@ -130,14 +127,12 @@ applies. A detached window (DL-160) opens on its section. The palette gets
 
 ### A5 — Providers (E5)
 
-S7 implements E5 as written: the `ListProviders` policy filter, connected
-state, Connect then the paste-code dialog with `instructions`, the
-attempt-expiry countdown and re-begin, API-key entry, Disconnect with a
-confirm, E5's store accessors, and no token value rendered or stored. It
-changes E5 in two points only: E5's "beside the tracker-config editor"
-becomes the Providers section, one A2 row per provider; and E5's
-"draft/commit pattern" becomes A4's per-action model, because each action
-is its own RPC and the tracker editor may go (Open Question 1).
+S7 implements E5 as written (policy filter, connected state, Connect and
+the paste-code dialog with `instructions`, expiry countdown and re-begin,
+API-key entry, confirmed Disconnect, E5's store accessors, no token
+rendered or stored), with two changes: "beside the tracker-config editor"
+becomes one A2 row per provider in Providers, and the "draft/commit
+pattern" becomes A4's per-action model (each action is one RPC).
 
 ## Alternatives considered
 
@@ -145,20 +140,17 @@ is its own RPC and the tracker editor may go (Open Question 1).
   a heading cannot be linked; every section shares one scroll.
 - **A modal dialog.** DL-160 makes Settings a window-scoped view.
 - **Horizontal tabs only.** Four or five sections fit today, but more are
-  named (Keyboard, Secrets, Fleet, a server-backed Tracker), and a strip
-  under the window's tab strip (DL-390) reads as nested tabs. It stays as
-  the narrow fallback.
-- **A switch, or a roving radiogroup.** A switch is a new primitive for
-  two rows; a radiogroup needs arrow keys, and `createRovingGroup` is
-  built around dispatcher command ids. `aria-pressed` needs neither.
+  named (Keyboard, Secrets, Fleet), and a strip under the window's tab
+  strip (DL-390) reads as nested tabs. It is the narrow fallback.
+- **A switch, or a roving radiogroup.** A new primitive for two rows, or
+  arrow-key code built for dispatcher ids; `aria-pressed` needs neither.
 - **One Save bar.** Device preferences and RPCs cannot wait for it.
 
 ## Global Constraints
 
 - **After brand-parity T9.** T2a and T9 rewrite the `.settings-*` radii
-  and weights and recapture every shot; S1 starts after T9 merges, so it
-  does not rebase on the same lines or recapture twice. T7 only changes
-  the `.cx-input` border; tasks use `.cx-input` before or after it.
+  and weights and recapture every shot, so S1 starts after T9 merges. T7
+  only changes the `.cx-input` border; tasks use `.cx-input` either way.
 - **Overlap with brand parity.** T5 (`/agents`) edits `RouteMatch`,
   `parseRoute`, `routePath`, `appRoutes`, `route-title.ts`, `spine.ts`,
   `store.ts`, and `LeftSidebar.tsx`, as S1 does. T10 leaves
@@ -166,15 +158,14 @@ is its own RPC and the tracker editor may go (Open Question 1).
   `/done` entries in `routes.tsx`, `LeftSidebar.tsx` and its test (S1),
   and `surfaces.md` § Backlog / Done / Settings (S4). The edits do not
   overlap in meaning; whichever lands second rebases.
-- **Tokens only**, the D7 stylelint guard, and the T2a and T9 rules.
-- **Each component imports the primitive CSS it renders** (brand-parity
-  A7). No new primitive and no `.settings-*` box style; layout classes in
-  `settings.css` only.
+- **Tokens only**, the D7 stylelint guard, and the T2a and T9 rules. Each
+  component imports the primitive CSS it renders (brand-parity A7); no
+  new primitive and no `.settings-*` box style (layout in `settings.css`).
 - **Every entry keeps working:** `Mod+,`, `G S`, palette `view.settings`,
   the sidebar link, and `/#/settings`.
 - **Device preferences** use localStorage keys `compass.settings.<name>`
   through `safeLocalStorage()`; an invalid value reads as the default.
-  Copy is sentence-case; help is one sentence.
+- **Copy.** Sentence-case labels; help is one sentence.
 - **Baselines and stacking.** Recapture under the pinned dev shell and
   commit per DL-399; one linear line, red-first tests, lane `implement-ts`.
 - **Public repo.** Cite only this repo and `docs/specs/brand/`.
@@ -202,10 +193,11 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
     `view.navigate(routePath(view.route()))`.
   - Store: `settingsSection(): SettingsSection`,
     `setSettingsSection(section: SettingsSection): void`, and
-    `settingsPath(): string`. `showSettings` runs `hideShortcuts()` then
-    `dispatchLayout({ kind: "open", path: settingsPath() })`, not
-    `navigateTo`. The `LeftSidebar` link passes `() => store.settingsPath()`
-    to `openLink`; its plain click still calls `showSettings`.
+    `settingsPath(): string`. The `LeftSidebar` link passes
+    `() => store.settingsPath()` to `openLink`; its plain click calls
+    `showSettings`. `showSettings` runs `hideShortcuts()`, then per Open
+    Question 3: (a) `navigateTo(settingsPath())`; (b)
+    `dispatchLayout({ kind: "open", path: settingsPath() })`.
   - `components/SettingsView.tsx` moves to `components/settings/`:
     `SettingsView.tsx` (the shell: reads the section from its view scope,
     calls `setSettingsSection`, renders nav and body, imports `tabs.css`,
@@ -236,25 +228,23 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
     `/settings/tracker`, its link has `data-selected` and
     `aria-current="page"`; clicking Models moves to `/settings/models` and
     shows the registry, not the editor.
-  - `store.test.ts` (`showSettings` uses `open`): from `/` it gives tabs
-    `["/", "/settings/tracker"]`, the new one active; from `/` again it
-    focuses that tab (still two); after that tab moves to
-    `/settings/models`, it focuses it again.
+  - `store.test.ts` (`showSettings`, per Open Question 3), after the
+    view moves to `/settings/models` and then to `/`: (a) one tab, its
+    view on `/settings/models`; (b) from `/` it opens
+    `/settings/models` in a second, active tab, and a repeat call from
+    `/` focuses that tab (still two).
 - **Baselines:** recapture `settings.png`; add `settings-narrow.png` (480px).
 
 ### S2 — General section
 
-- **Do:** A1 General, without Usage data (S6).
-- **Interfaces:**
-  - `SETTINGS_SECTIONS` gains `"general"` first;
-    `settings/GeneralSection.tsx` in `SECTION_VIEW`.
-  - `DaemonInfo` gains `rev: string`; `probeServer` reads `rev`;
-    `STUB_DAEMON.rev` is `""`.
-  - `AppStoreOptions` gains `serverUrl?: string`, which `main` in
-    `index.tsx` sets to `connection.baseUrl`; the store exposes
-    `serverUrl(): string | undefined`.
-  - `GeneralSection.tsx` exports `modeLabel(mode: ShellMode | undefined):
-    "Browser" | "Embedded server" | "Remote server"`, an exhaustive switch.
+- **Interfaces:** `SETTINGS_SECTIONS` gains `"general"` first, with
+  `settings/GeneralSection.tsx` (rows except Usage data, S6). `DaemonInfo`
+  gains `rev: string` (`probeServer` reads it; `STUB_DAEMON.rev` is
+  `""`). `AppStoreOptions` gains `serverUrl?: string`, set by `main` in
+  `index.tsx` to `connection.baseUrl`; the store exposes `serverUrl():
+  string | undefined`. `GeneralSection.tsx` exports `modeLabel(mode:
+  ShellMode | undefined): "Browser" | "Embedded server" | "Remote
+  server"`, an exhaustive switch.
 - **Test (red first):** `settings/GeneralSection.test.tsx` with
   `createRouterTransport` serving `getServerInfo` (`1.2.3`, an API
   version, `abc123`): the three show; offline shows "Not connected"; the
@@ -317,11 +307,10 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
   Storage | undefined, workspace: string): TrackerConfig | undefined` and
   `saveTrackerConfig(storage: Storage | undefined, workspace: string,
   config: TrackerConfig): void`, key `compass.settings.tracker.${workspace}`
-  with the pins' `workspaceKey`. The store loads it with the pins;
-  `setTrackerConfig` saves it.
-- **Test (red first):** `store.test.ts`: a new store on the same storage
-  and workspace reads the saved config; another workspace and malformed
-  JSON give the default.
+  with the pins' `workspaceKey`, loaded with the pins and saved by
+  `setTrackerConfig`. **Test (red first):** a new store on the same
+  storage and workspace reads it; another workspace or bad JSON gives the
+  default.
 
 ### S6 — Usage data
 
@@ -343,19 +332,16 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
 ### S7 — Providers section (E5)
 
 - **Gate:** enrollment E3 merged. **Do:** A5; E5's Interfaces and test
-  cycle are the contract.
-- **Interfaces:** E5's, plus: `SETTINGS_SECTIONS` gains `"providers"`
-  after `"models"`; `settings/ProvidersSection.tsx`; `openExternal` moves
-  from `MarkdownText.tsx` to `apps/ui/src/open-external.ts` (`export
-  function openExternal(url: string): void`) so Connect opens `auth_url`
-  in both hosts.
-- **Test (red first):** E5's cycle, plus: only the providers
-  `ListProviders` returns are rendered. **Baselines:** add
-  `settings-providers.png`.
+  cycle are the contract, plus: `SETTINGS_SECTIONS` gains `"providers"`
+  after `"models"` (`settings/ProvidersSection.tsx`); `openExternal`
+  moves from `MarkdownText.tsx` to `apps/ui/src/open-external.ts`
+  (`export function openExternal(url: string): void`) for `auth_url` in
+  both hosts; a test that only `ListProviders`' providers render.
+  **Baselines:** add `settings-providers.png`.
 
 ## Tasks
 
-- [ ] S1 — Shell and section route (after brand-parity T9)
+- [ ] S1 — Shell and route (after brand-parity T9; opener per OQ3)
 - [ ] S2 — General section (after S1)
 - [ ] S3 — Appearance section (after S2)
 - [ ] S4 — Tracker per Open Question 1 (after S3 and Open Question 1)
@@ -365,36 +351,50 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
 
 ## Open Questions
 
-1. **The tracker editor.** It edits a config that only the fixture seam
-   reads, and only its handle; the kind and the status map change nothing.
-   DL-129 puts the mapping on the server, which ingests tracker status
-   through the reverse `TrackerStatusMapping`.
-   - (a) Keep the editor, rebuild it on A2 (S4), and persist it in
-     localStorage keyed by `workspaceKey` (S5). Small, but it saves a
-     value nothing uses: `rule://no-inert-gating` argues against it.
-   - (b) Show the config read-only as "Preview, not connected", and drop
-     S5. Honest about the state, but it shows a status map the server
-     does not use, which can mislead.
-   - (c) Delete the client-side editor and `setTrackerConfig`; the
-     mapping stays on the server. A Tracker section returns, server-backed,
-     when the tracker contract lands. Loses the one editable setting
-     today, and its tests.
-   - **Recommendation:** (c). Nothing the editor writes reaches the
-     server, and a read-only preview of a value the server does not use
-     misleads more than it shows.
+1. **The tracker editor.** It edits a config only the fixture seam reads,
+   and only its handle; the kind and the status map change nothing.
+   DL-129 puts the mapping on the server (the reverse
+   `TrackerStatusMapping`).
+   - (a) Keep it, rebuild it on A2 (S4), persist it per `workspaceKey`
+     (S5). Small, but it saves a value nothing uses
+     (`rule://no-inert-gating`).
+   - (b) Show it read-only as "Preview, not connected"; drop S5. Honest,
+     but it shows a status map the server does not use.
+   - (c) Delete the editor and `setTrackerConfig`; a server-backed Tracker
+     section returns with the tracker contract. Loses the one editable
+     setting and its tests.
+   - **Recommendation:** (c). Nothing it writes reaches the server, and a
+     preview of an unused value misleads more than it shows.
 2. **A usage-data control, and where it goes.** No record decides
    analytics consent. The observability record sends managed builds to
-   Rigel's PostHog and keeps self-hosted builds off by default or on the
-   deployer's own key; most self-hosted builds have no key.
+   Rigel's PostHog; self-hosted builds are off or use the deployer's key,
+   and most have no key.
    - (a) A per-device On or Off in its own Privacy section, stored by
-     posthog-js (`opt_out_capturing()`). In a build with no key, the
-     section is one sentence.
-   - (b) The same control as a Usage data row in General, giving four
-     sections, or five if Open Question 1 keeps Tracker. A build with no
-     key shows one read-only line.
-   - (c) No user control; the deployer decides at build time. No work, but
-     a user of a managed build cannot opt out in the app.
-   - (d) A per-account consent stored on the server and read at boot.
-     Follows the account, but needs a proto field and a server task.
-   - **Recommendation:** (b). It gives a user control now with no server
-     work and no near-empty section; (d) can replace its storage later.
+     posthog-js (`opt_out_capturing()`). With no key, the section is one
+     sentence.
+   - (b) The same control as a row in General: four sections, or five if
+     Open Question 1 keeps Tracker. With no key, one read-only line.
+   - (c) No control; the deployer decides at build time. A managed-build
+     user cannot opt out in the app.
+   - (d) Per-account consent stored on the server. Follows the account;
+     needs a proto field and a server task.
+   - **Recommendation:** (b): user control now, no server work, no
+     near-empty section; (d) can replace its storage later.
+3. **How a Settings opener behaves.** DL-390: "links navigate the focused
+   view in place and `Mod`+click or middle-click opens a tab"; only that
+   tab path dedupes an open path. Today `showSettings` follows it
+   (`navigateFocused`), like `showBacklog` and `showDone`.
+   - (a) Keep DL-390. `Mod+,`, `G S`, the palette, and the sidebar link
+     navigate the focused view to the last section; bare `/settings`
+     still redirects to the first. Dedupe stays with Mod-click and
+     middle-click. One rule for every view, no ledger change; but `Mod+,`
+     replaces the focused view (Back returns), and with Settings in a
+     background tab it makes a second Settings view.
+   - (b) Settings openers open or focus a Settings tab, amending DL-390
+     for Settings only, as DL-409 did for New tab. Keeps the user's place
+     and never duplicates Settings, like an editor's settings tab. Costs a
+     second DL-390 exception, Settings unlike the other `show*` openers,
+     and the 10-tab cap can refuse `Mod+,`.
+   - **Recommendation:** (a). DL-390 is uniform, and Mod-click and
+     middle-click already open a deduped tab. Revisit as (b) if dogfood
+     shows duplicate Settings views.

From 7d8de9ba7bc960113d91175c1800de9c4b1057ce Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Wed, 7 Oct 2026 23:31:14 -0400
Subject: [PATCH 4/5] docs(ui): fold Matt's Settings rulings into the record
 (RIG-4775)

OQ1 deletes the tracker editor (DL-432), OQ2 adds no usage-data control
(DL-435), OQ3 keeps DL-390 for Settings openers (DL-436).

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 docs/designs/ui/compass-settings/design.md | 204 +++++++--------------
 1 file changed, 63 insertions(+), 141 deletions(-)

diff --git a/docs/designs/ui/compass-settings/design.md b/docs/designs/ui/compass-settings/design.md
index 0ad61faf6..005245b85 100644
--- a/docs/designs/ui/compass-settings/design.md
+++ b/docs/designs/ui/compass-settings/design.md
@@ -5,9 +5,8 @@ square corners, weights, surfaces, `--cx-border-field`, text-entry
 primitives), [UX foundation](../compass-ux-foundation/design.md)
 Refs: RIG-4775 (this record); RIG-3121 (Providers, task E5 of the
 [gateway OAuth enrollment record](../../server/compass-gateway-oauth-enrollment/design.md));
-ledger DL-431, DL-433, DL-434; DL-432, DL-435, and DL-436 are held for
-Open Questions 1, 2, and 3
-Depends on: brand-parity T9 (S1); enrollment E3 (S7)
+ledger DL-431 to DL-436
+Depends on: brand-parity T9 (S1); enrollment E3 (S5)
 
 ## Problem / Intent
 
@@ -37,13 +36,14 @@ Today Settings is one page that edits the tracker config. Defects (from
 Brand-parity T2a and T9 fix defects 2 and 3 (they sweep every radius and
 `font-weight: 600` in `app.css`). This record fixes the rest: one view
 with a section nav, a route per section, one row anatomy on the shared
-primitives, and a save model per section.
+primitives, and a save model per section. It deletes the tracker editor
+(defect 6).
 
 ## Approach
 
 ### A1 — Sections and settings
 
-Sections in nav order. Tracker is OQ1; Usage data's place is OQ2.
+Four sections, in nav order.
 
 - **General** (`general`): Server URL (`connection.baseUrl`, the
   transport's URL in both hosts); Mode (`shellMode()`: none → Browser,
@@ -52,22 +52,24 @@ Sections in nav order. Tracker is OQ1; Usage data's place is OQ2.
   reopen never mounts it); Server version (`version`, `api_version`, and
   `rev` from `GetServerInfo`; "Not connected" when `store.daemon().live`
   is false); Signed in as (`store.caller()` handle and display name); a
-  Keyboard shortcuts button that opens the overlay; Usage data (OQ2). New.
+  Keyboard shortcuts button that opens the overlay. New.
 - **Appearance** (`appearance`): Reduce motion, Follow system or Always,
   per device in localStorage `compass.settings.reduceMotion`. Always sets
   `:root[data-reduce="on"]`, which the CSS honors and nothing sets. New.
-- **Tracker** (`tracker`): exists; Open Question 1.
 - **Models** (`models`): the model registry, read-only. Exists.
 - **Providers** (`providers`): enrollment E5 (A5). Needs E3
   (`ProviderEnrollmentService`), not yet in the proto, Go, or the UI.
 
-Not in this record: server URL edits (deferred, native server URL record
-OQ-5); browser sign-out (no signed-out boot path); a day theme (D2,
-"later"); key remap (deferred; a Keyboard section comes with it);
-notifications (none exist); Secrets (`SecretsService` overlaps the
-Providers key entry; its own design after E5); Replay tour (a General row
-once the tour UI merges); `GetAgentConfigInfo` (fleet member names, not a
-preference; a later Fleet section); pins and window layout (set in place).
+Not in this record: a Tracker section (DL-432: S4 deletes the editor; a
+server-backed one returns with the tracker contract); a usage-data
+control (DL-435: the deployer decides at build time); server URL edits
+(deferred, native server URL record OQ-5); browser sign-out (no
+signed-out boot path); a day theme (D2, "later"); key remap (deferred; a
+Keyboard section comes with it); notifications (none exist); Secrets
+(`SecretsService` overlaps the Providers key entry; its own design after
+E5); Replay tour (a General row once the tour UI merges);
+`GetAgentConfigInfo` (fleet member names, not a preference; a later
+Fleet section); pins and window layout (set in place).
 
 ### A2 — Layout
 
@@ -111,23 +113,23 @@ on `/`.
 
 Every opener (`showSettings` behind `Mod+,`, `G S`, the palette, and the
 destinations list; and the sidebar link) targets `store.settingsPath()`,
-the last section shown in this window or the first. Whether it navigates
-the focused view or opens a tab is Open Question 3. A detached window
-(DL-160) opens on its section. The palette gets "Go to Settings: Label"
-per section; the title is "Settings · Label".
+the last section shown in this window or the first. Openers follow DL-390
+(DL-436): a plain open navigates the focused view; `Mod`+click or
+middle-click on the link opens a deduped tab. A detached window (DL-160)
+opens on its section. The palette gets "Go to Settings: Label" per
+section; the title is "Settings · Label".
 
 ### A4 — Save model, per section
 
-- **Immediate** for a device preference (Reduce motion, Usage data):
-  applied and stored on click.
+- **Immediate** for a device preference (Reduce motion): applied and
+  stored on click.
 - **Per action** for Providers: each Connect, code, key, and Disconnect is
   one RPC with its own pending and error state on its row.
-- **None** for read-only rows. No page-level Save; Tracker follows Open
-  Question 1.
+- **None** for read-only rows. No page-level Save.
 
 ### A5 — Providers (E5)
 
-S7 implements E5 as written (policy filter, connected state, Connect and
+S5 implements E5 as written (policy filter, connected state, Connect and
 the paste-code dialog with `instructions`, expiry countdown and re-begin,
 API-key entry, confirmed Disconnect, E5's store accessors, no token
 rendered or stored), with two changes: "beside the tracker-config editor"
@@ -139,9 +141,9 @@ pattern" becomes A4's per-action model (each action is one RPC).
 - **One long page with anchored headings.** The hash router owns `#`, so
   a heading cannot be linked; every section shares one scroll.
 - **A modal dialog.** DL-160 makes Settings a window-scoped view.
-- **Horizontal tabs only.** Four or five sections fit today, but more are
-  named (Keyboard, Secrets, Fleet), and a strip under the window's tab
-  strip (DL-390) reads as nested tabs. It is the narrow fallback.
+- **Horizontal tabs only.** Four sections fit today, but more are named
+  (Keyboard, Secrets, Fleet), and a strip under the window's tab strip
+  (DL-390) reads as nested tabs. It is the narrow fallback.
 - **A switch, or a roving radiogroup.** A new primitive for two rows, or
   arrow-key code built for dispatcher ids; `aria-pressed` needs neither.
 - **One Save bar.** Device preferences and RPCs cannot wait for it.
@@ -172,7 +174,7 @@ pattern" becomes A4's per-action model (each action is one RPC).
 
 ## Plan
 
-S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens.
+S1 → S2 → S3 → S4; S5 stacks on the top when enrollment E3 merges.
 
 ### S1 — Shell and section route
 
@@ -195,9 +197,8 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
     `setSettingsSection(section: SettingsSection): void`, and
     `settingsPath(): string`. The `LeftSidebar` link passes
     `() => store.settingsPath()` to `openLink`; its plain click calls
-    `showSettings`. `showSettings` runs `hideShortcuts()`, then per Open
-    Question 3: (a) `navigateTo(settingsPath())`; (b)
-    `dispatchLayout({ kind: "open", path: settingsPath() })`.
+    `showSettings`. `showSettings` runs `hideShortcuts()`, then
+    `navigateTo(settingsPath())` (DL-436).
   - `components/SettingsView.tsx` moves to `components/settings/`:
     `SettingsView.tsx` (the shell: reads the section from its view scope,
     calls `setSettingsSection`, renders nav and body, imports `tabs.css`,
@@ -228,19 +229,17 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
     `/settings/tracker`, its link has `data-selected` and
     `aria-current="page"`; clicking Models moves to `/settings/models` and
     shows the registry, not the editor.
-  - `store.test.ts` (`showSettings`, per Open Question 3), after the
-    view moves to `/settings/models` and then to `/`: (a) one tab, its
-    view on `/settings/models`; (b) from `/` it opens
-    `/settings/models` in a second, active tab, and a repeat call from
-    `/` focuses that tab (still two).
+  - `store.test.ts` (`showSettings`): after the view moves to
+    `/settings/models` and then to `/`, a call leaves one tab, its view
+    on `/settings/models`.
 - **Baselines:** recapture `settings.png`; add `settings-narrow.png` (480px).
 
 ### S2 — General section
 
 - **Interfaces:** `SETTINGS_SECTIONS` gains `"general"` first, with
-  `settings/GeneralSection.tsx` (rows except Usage data, S6). `DaemonInfo`
-  gains `rev: string` (`probeServer` reads it; `STUB_DAEMON.rev` is
-  `""`). `AppStoreOptions` gains `serverUrl?: string`, set by `main` in
+  `settings/GeneralSection.tsx` (A1's rows). `DaemonInfo` gains
+  `rev: string` (`probeServer` reads it; `STUB_DAEMON.rev` is `""`).
+  `AppStoreOptions` gains `serverUrl?: string`, set by `main` in
   `index.tsx` to `connection.baseUrl`; the store exposes `serverUrl():
   string | undefined`. `GeneralSection.tsx` exports `modeLabel(mode:
   ShellMode | undefined): "Browser" | "Embedded server" | "Remote
@@ -273,63 +272,24 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
   `AppearanceSection.test.tsx`: Always sets `aria-pressed`, the root
   attribute, and the stored value.
 
-### S4 — Tracker, per Open Question 1
+### S4 — Delete the tracker editor
 
-- **Gate:** Open Question 1. Interfaces are for the recommended (c).
-- **Interfaces (c):**
+- **Interfaces:**
   - Delete `settings/TrackerSection.tsx`, `mergeFromTracker`,
     `settings-mapping.test.ts`, `"tracker"` from `SETTINGS_SECTIONS` and
-    the `view.settings` keywords, and every remaining `.settings-*` rule.
+    the `view.settings` keywords, and every remaining `.settings-*` rule in
+    `app.css` except `.settings-registry*` and `.settings-map-arrow`, which
+    Models uses.
   - `AppStore` drops `setTrackerConfig` and its two `store.test.ts` cases;
     `trackerConfig` stays at `DEFAULT_TRACKER_CONFIG` for the fixture queue.
   - `surfaces.md` § Backlog / Done / Settings: replace the status-mapping
     sentences (composition, empty state, flip item 2) with the A2 rows.
   - File a follow-up: a server-backed Tracker section with the tracker
     contract.
-- **Interfaces (a):** the editor on A2 rows; the status map a `<table>` of
-  free-text `input.cx-input` per state, as today (no source lists a
-  tracker's statuses); Reset and Save in a sticky foot.
-  `settings/tracker-draft.ts`: `createTrackerDraft(store: AppStore):
-  TrackerDraft` (`draft()`, `dirty()`, `set(next)`, `reset()`, `save()`),
-  held by the shell so a draft survives a section switch, with a nav dot
-  when dirty; `surfaces.md`'s `.cx-tree-row` table becomes that table.
-  **(b):** the same rows, read-only, under "Preview, not connected".
-- **Test (red first):** (c): no Tracker link; `/settings/tracker` ends on
-  `/`. (a): `tracker-draft.test.ts` (clean at start; `set` dirties;
-  `reset` restores; `save` commits and cleans); an edit survives a switch
-  to Models and back. **Baselines:** `settings.png`; (a) and (b) add
-  `settings-tracker.png`.
-
-### S5 — Tracker persistence
-
-- **Gate:** Open Question 1 is (a); otherwise dropped.
-- **Interfaces:** `preferences.ts` adds `loadTrackerConfig(storage:
-  Storage | undefined, workspace: string): TrackerConfig | undefined` and
-  `saveTrackerConfig(storage: Storage | undefined, workspace: string,
-  config: TrackerConfig): void`, key `compass.settings.tracker.${workspace}`
-  with the pins' `workspaceKey`, loaded with the pins and saved by
-  `setTrackerConfig`. **Test (red first):** a new store on the same
-  storage and workspace reads it; another workspace or bad JSON gives the
-  default.
-
-### S6 — Usage data
-
-- **Gate:** Open Question 2. Interfaces are for the recommended (b).
-- **Interfaces:** `Analytics` gains `readonly enabled: boolean`,
-  `optOut()`, `optIn()`, and `optedOut(): boolean` (posthog-js
-  `opt_out_capturing()`, `opt_in_capturing()`,
-  `has_opted_out_capturing()`); `NoopAnalytics` has `enabled` false and
-  `optedOut()` true. `AppStoreOptions` gains `analytics?: Analytics` and
-  the store exposes `analytics(): Analytics | undefined` (reused if the
-  tour analytics branch lands it first). A Usage data row in
-  `GeneralSection.tsx`: On and Off `aria-pressed` buttons, or "Off. This
-  build sends no usage data." when disabled.
-- **Test (red first):** `analytics.test.ts`: `optOut` calls
-  `opt_out_capturing`. `GeneralSection.test.tsx` with a fake `Analytics`:
-  Off calls `optOut`, On calls `optIn`, the pressed button follows
-  `optedOut()`, and a disabled build shows the text and no buttons.
-
-### S7 — Providers section (E5)
+- **Test (red first):** no Tracker link; `/settings/tracker` ends on `/`.
+  **Baselines:** recapture `settings.png`.
+
+### S5 — Providers section (E5)
 
 - **Gate:** enrollment E3 merged. **Do:** A5; E5's Interfaces and test
   cycle are the contract, plus: `SETTINGS_SECTIONS` gains `"providers"`
@@ -341,60 +301,22 @@ S1 → S2 → S3 → S4 → S5; S6 and S7 stack on the top when their gate opens
 
 ## Tasks
 
-- [ ] S1 — Shell and route (after brand-parity T9; opener per OQ3)
+- [ ] S1 — Shell and route (after brand-parity T9)
 - [ ] S2 — General section (after S1)
 - [ ] S3 — Appearance section (after S2)
-- [ ] S4 — Tracker per Open Question 1 (after S3 and Open Question 1)
-- [ ] S5 — Tracker persistence (only if Open Question 1 is (a); after S4)
-- [ ] S6 — Usage data (after S2 and Open Question 2; top of the line)
-- [ ] S7 — Providers, E5 (after S1 and enrollment E3; top of the line)
-
-## Open Questions
-
-1. **The tracker editor.** It edits a config only the fixture seam reads,
-   and only its handle; the kind and the status map change nothing.
-   DL-129 puts the mapping on the server (the reverse
-   `TrackerStatusMapping`).
-   - (a) Keep it, rebuild it on A2 (S4), persist it per `workspaceKey`
-     (S5). Small, but it saves a value nothing uses
-     (`rule://no-inert-gating`).
-   - (b) Show it read-only as "Preview, not connected"; drop S5. Honest,
-     but it shows a status map the server does not use.
-   - (c) Delete the editor and `setTrackerConfig`; a server-backed Tracker
-     section returns with the tracker contract. Loses the one editable
-     setting and its tests.
-   - **Recommendation:** (c). Nothing it writes reaches the server, and a
-     preview of an unused value misleads more than it shows.
-2. **A usage-data control, and where it goes.** No record decides
-   analytics consent. The observability record sends managed builds to
-   Rigel's PostHog; self-hosted builds are off or use the deployer's key,
-   and most have no key.
-   - (a) A per-device On or Off in its own Privacy section, stored by
-     posthog-js (`opt_out_capturing()`). With no key, the section is one
-     sentence.
-   - (b) The same control as a row in General: four sections, or five if
-     Open Question 1 keeps Tracker. With no key, one read-only line.
-   - (c) No control; the deployer decides at build time. A managed-build
-     user cannot opt out in the app.
-   - (d) Per-account consent stored on the server. Follows the account;
-     needs a proto field and a server task.
-   - **Recommendation:** (b): user control now, no server work, no
-     near-empty section; (d) can replace its storage later.
-3. **How a Settings opener behaves.** DL-390: "links navigate the focused
-   view in place and `Mod`+click or middle-click opens a tab"; only that
-   tab path dedupes an open path. Today `showSettings` follows it
-   (`navigateFocused`), like `showBacklog` and `showDone`.
-   - (a) Keep DL-390. `Mod+,`, `G S`, the palette, and the sidebar link
-     navigate the focused view to the last section; bare `/settings`
-     still redirects to the first. Dedupe stays with Mod-click and
-     middle-click. One rule for every view, no ledger change; but `Mod+,`
-     replaces the focused view (Back returns), and with Settings in a
-     background tab it makes a second Settings view.
-   - (b) Settings openers open or focus a Settings tab, amending DL-390
-     for Settings only, as DL-409 did for New tab. Keeps the user's place
-     and never duplicates Settings, like an editor's settings tab. Costs a
-     second DL-390 exception, Settings unlike the other `show*` openers,
-     and the 10-tab cap can refuse `Mod+,`.
-   - **Recommendation:** (a). DL-390 is uniform, and Mod-click and
-     middle-click already open a deduped tab. Revisit as (b) if dogfood
-     shows duplicate Settings views.
+- [ ] S4 — Delete the tracker editor (after S3)
+- [ ] S5 — Providers, E5 (after S1 and enrollment E3; top of the line)
+
+## Resolved Questions
+
+1. **The tracker editor:** delete it (Matt, 2026-10-08, DL-432). It
+   edits a config only the fixture seam reads, and the server maps tracker
+   status (DL-129). A server-backed Tracker section returns with the
+   tracker contract.
+2. **A usage-data control:** "None for now, may add later." (Matt,
+   2026-10-08, DL-435). No control in the app; the deployer decides at
+   build time.
+3. **How a Settings opener behaves:** keep DL-390 with no Settings
+   exception (Matt, 2026-10-08, DL-436). `Mod+,` replaces the focused
+   view (Back returns); with Settings in a background tab it makes a
+   second Settings view.

From 7264c753953be8ea896db1c2cb3667e6306b38fa Mon Sep 17 00:00:00 2001
From: mintaka <mintaka@rigel.build>
Date: Sat, 10 Oct 2026 00:33:07 -0400
Subject: [PATCH 5/5] docs(ui): move the Settings decisions into per-decision
 files (RIG-4775)

DECISIONS.md is now one front-matter file per decision under
docs/designs/decisions/; the rows this record added move there unchanged.

Co-authored-by: Matt Wilkinson <matt@rigel.build>
---
 docs/designs/decisions/ui/DL-431.md | 6 ++++++
 docs/designs/decisions/ui/DL-432.md | 6 ++++++
 docs/designs/decisions/ui/DL-433.md | 6 ++++++
 docs/designs/decisions/ui/DL-434.md | 6 ++++++
 docs/designs/decisions/ui/DL-435.md | 6 ++++++
 docs/designs/decisions/ui/DL-436.md | 6 ++++++
 6 files changed, 36 insertions(+)
 create mode 100644 docs/designs/decisions/ui/DL-431.md
 create mode 100644 docs/designs/decisions/ui/DL-432.md
 create mode 100644 docs/designs/decisions/ui/DL-433.md
 create mode 100644 docs/designs/decisions/ui/DL-434.md
 create mode 100644 docs/designs/decisions/ui/DL-435.md
 create mode 100644 docs/designs/decisions/ui/DL-436.md

diff --git a/docs/designs/decisions/ui/DL-431.md b/docs/designs/decisions/ui/DL-431.md
new file mode 100644
index 000000000..d76ca82bc
--- /dev/null
+++ b/docs/designs/decisions/ui/DL-431.md
@@ -0,0 +1,6 @@
+---
+id: DL-431
+decision: "Settings is one view with a section nav (vertical `.cx-tabs` links, a horizontal strip under a 560px pane) that shows one section at a time; each section is a route, `/settings/:section`, part of the view's `RouteMatch`. Bare `/settings` is not canonical: the catch-all becomes `RedirectCanonical`, which sends a view to `routePath` of its parsed route, so `/settings` lands on the first section"
+status: "Active (Matt, 2026-10-07)"
+record: ../../ui/compass-settings/design.md#a3--route
+---
diff --git a/docs/designs/decisions/ui/DL-432.md b/docs/designs/decisions/ui/DL-432.md
new file mode 100644
index 000000000..22b188fad
--- /dev/null
+++ b/docs/designs/decisions/ui/DL-432.md
@@ -0,0 +1,6 @@
+---
+id: DL-432
+decision: "Settings has no Tracker section: the client-side tracker editor and `AppStore.setTrackerConfig` are deleted, since the config they edit reaches only the fixture seam and the server maps tracker status (DL-129); a server-backed Tracker section returns with the tracker contract"
+status: "Active (Matt, 2026-10-08)"
+record: ../../ui/compass-settings/design.md#resolved-questions
+---
diff --git a/docs/designs/decisions/ui/DL-433.md b/docs/designs/decisions/ui/DL-433.md
new file mode 100644
index 000000000..000e5355c
--- /dev/null
+++ b/docs/designs/decisions/ui/DL-433.md
@@ -0,0 +1,6 @@
+---
+id: DL-433
+decision: "A Settings row is a two-column grid, label and help on the left and the control on the right, with a line between rows and no card, radius, or fill; controls are only `.cx-input`, `.cx-select`, and `.cx-btn` (`aria-pressed` buttons for two or three choices); Settings adds no box style and no switch primitive"
+status: "Active (Matt, 2026-10-07)"
+record: ../../ui/compass-settings/design.md#a2--layout
+---
diff --git a/docs/designs/decisions/ui/DL-434.md b/docs/designs/decisions/ui/DL-434.md
new file mode 100644
index 000000000..3dedf0fcf
--- /dev/null
+++ b/docs/designs/decisions/ui/DL-434.md
@@ -0,0 +1,6 @@
+---
+id: DL-434
+decision: "The Settings save model is per section, with no page-level Save: a device preference applies and stores on click; each Providers action is its own RPC with its own pending and error state on its row; read-only rows have none"
+status: "Active (Matt, 2026-10-07)"
+record: ../../ui/compass-settings/design.md#a4--save-model-per-section
+---
diff --git a/docs/designs/decisions/ui/DL-435.md b/docs/designs/decisions/ui/DL-435.md
new file mode 100644
index 000000000..65b555adc
--- /dev/null
+++ b/docs/designs/decisions/ui/DL-435.md
@@ -0,0 +1,6 @@
+---
+id: DL-435
+decision: "Compass has no in-app usage-data control: the deployer decides at build time whether a build sends usage data. A control may be added later; none is planned"
+status: "Active (Matt, 2026-10-08)"
+record: ../../ui/compass-settings/design.md#resolved-questions
+---
diff --git a/docs/designs/decisions/ui/DL-436.md b/docs/designs/decisions/ui/DL-436.md
new file mode 100644
index 000000000..655056762
--- /dev/null
+++ b/docs/designs/decisions/ui/DL-436.md
@@ -0,0 +1,6 @@
+---
+id: DL-436
+decision: "Settings openers (`Mod+,`, `G S`, the palette, the sidebar link) follow DL-390 with no exception: a plain open navigates the focused view to the last Settings section shown in the window, bare `/settings` redirects to the first, and only `Mod`+click or middle-click opens a deduped tab"
+status: "Active (Matt, 2026-10-08)"
+record: ../../ui/compass-settings/design.md#a3--route
+---