docs(design): Mosaic Stack design draft 1, brand, web console and mosaic TUI

docs/design/ holds the preview page (brand, 13 console views in five
states, 13 terminal screens, 39-feature coverage with status), the
README spec and the Relay mark. Design only; no package code changed.
Open for Jason: default palette and mode, final mark, web resolution,
one mosaic app.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

docs/design/README.md

@@ -0,0 +1,198 @@
+# Mosaic Stack design, draft 1
+
+- Status: draft 1, 2026-10-09. A design for review, not built software.
+  Nothing under `packages/` changed for it.
+- Asked for by Jason: branding, WebUI page designs, a TUI design, and
+  every feature included.
+- Preview: `mosaic-stack-design.html` in this directory. It is one
+  self-contained page with four tabs (Brand, Console, Terminal, Coverage),
+  and it is also published as a private claude.ai artifact. Sample data
+  throughout: ids, times and counts are illustrative.
+- "GUI" in the request is the WebUI. There is no separate desktop app in
+  this design. A desktop app is not in the PRD.
+
+## Sources
+
+- `docs/prd/mosaic-stack.md` (PRD 1.0) for requirements and limits.
+- Jason's earlier rulings on the console: the d3 layout, Manrope with
+  JetBrains Mono, ten palettes in three modes, the Relay mark, blue
+  without a purple gradient.
+- Slice 1 briefs and Dewey's `agents/dewey/work/wui/` notes for the web
+  routes that exist.
+- `packages/conversation`, `packages/bus`, `packages/cli`,
+  `packages/control-board` and `packages/webui` for the exact strings,
+  keys and states shown. Haiku 5.5 subagents gathered these. I checked
+  the strings that the mockups quote.
+
+## Brand
+
+- **Mark: Relay, refined.** Two interlocking hooks that pass work from
+  one to the other. The refined version is drawn on a 16-unit grid so it
+  stays sharp at 16 and 24 px (`brand/relay-refined.svg`). The original
+  56-unit drawing is kept (`brand/relay-original.svg`) and holds up from
+  48 px. The Brand tab shows both at 16, 24, 32, 48 and 96 px.
+- **Name.** "Mosaic Stack" in prose and the header. `mosaic` is the
+  command and the short in-app wordmark.
+- **Type.** Manrope for the interface. JetBrains Mono for ids, commands,
+  refusal codes and anything a person might type or paste. Scale:
+  28/800 page title, 20/800 section, 16/700 question, 14/400 text (table
+  cells 13 to 14), 11/700 caps labels, mono 12.5. Tabular figures in
+  columns.
+- **Colour.** Ten palettes, each in Light, Dim and Dark: Harbor (the
+  proposed default), Carmine, Atlantic, Terracotta, Aubergine, Mineral,
+  Cobalt, Rosewood, Graphite and Grove. Every palette defines the same
+  semantic tokens: canvas, surface, raised, line, border, text, muted,
+  action, onAction, accent, success, warning, danger and focus. No
+  gradients.
+- **Icons.** Seventeen line icons on a 24-unit grid, 1.75 stroke, round
+  joins, no fills: one per console section plus search, copy, close and
+  terminal. An icon never carries state alone.
+- **Voice: calm precision.** Name the thing, the state and the next
+  step. Keep the system's own words (refusal codes, event kinds, task
+  refs) exactly as the bus records them, in mono. The Brand tab gives
+  Say / Not pairs, for example "Vikunja last read 14:21:07 (12 s ago)",
+  not "Everything is up to date! 🎉".
+- **Status vocabulary.** One set of words and marks for both surfaces:
+  - agent state: ● working, ◐ waiting (shows the Input needed text),
+    ▲ error, ○ offline, – idle, ? unknown;
+  - decision class: routine (logged), within-role (logged), cross-role
+    (to the arbiter: delivery → pm, technical → cto), gated (to you),
+    BLOCKING (CLI inbox and Discord DM now; otherwise the 08:00 CT
+    digest);
+  - task markers: changed in Vikunja, not created by the stack,
+    conflict, missing: moved, not-found, no-access.
+
+  Colour is never the only signal.
+
+## WebUI: the console
+
+The d3 layout:
+- a command bar with Ctrl+K;
+- a left section list plus the project tree;
+- a dense table in the middle;
+- a right-hand inspector drawer.
+
+The Board is home. Views are in-page routes in the preview (the
+section list and Ctrl+K switch them).
+
+| View | Purpose | Data source |
+|---|---|---|
+| `board` | Who is working, who is waiting, what needs you; seat table with Input needed and Seen | control board, bus |
+| `inbox` | Decisions: For you / Routed to roles / Recent; inspector shows the authorization sentence and copy commands | bus decisions |
+| `talk` | The PM conversation: controller or observer, receipts, take control | conversation terminal |
+| `tasks` | Vikunja tasks with bucket, priority, requirement and markers; freshness line | sync bot reads |
+| `agents` | Role holders, launch budget (Opus n of 4, Sonnet n of 4), credential metadata | bus role claims, business file |
+| `trail` | Every event for one task or decision, with filter chips | event store |
+| `queue` | Queue rows, read-only | `docs/plans/queue.json` |
+| `runs` | Run records and release status | `<dataRoot>/runs`, `release.sh status` |
+| `ledger` | Ledger counts and the queue check | `packages/ledger` |
+| `business` | Business file: roles, arbiters, limits, authority map, variables | business file, `roles/*.json` |
+| `library` | Skills and contracts in launch bundles | meta-harness |
+| `settings` | Appearance, notifications, about (loopback, no sign-in) | system config, read-only |
+| `onboarding` (Set up) | First-run checklist | bootstrap checks |
+| anything else | Not found, with links back | — |
+
+Every view has five designed states, selectable in the preview:
+normal, loading, empty, error with stale data kept on screen, and
+refusal (fail closed, naming the missing file or rule).
+
+Keyboard: Ctrl+K palette, ↑/↓ through table rows, Enter opens the
+inspector, Esc closes it and returns focus to the row.
+
+Below 1100 px the inspector overlays the table. Below 760 px the
+section list becomes a horizontal strip, the inspector becomes a
+full-screen sheet, and the page header stops pinning.
+
+## TUI: `mosaic`
+
+A full-screen app over the existing verbs. The design assumes `mosaic`
+with no arguments opens it; the verbs stay for scripts (open decision
+below).
+
+- **Sizes.** Designed at 120×36, and every screen must also fit 80×24.
+  Below 100 columns the nav shows keys only, tables drop their
+  lower-priority columns (in Inbox, RAISED BY and REACHES YOU), and
+  detail moves below the list. The compact screen shows Inbox at
+  80×24.
+- **Screens.** Talk (controller and observer), Inbox, Decide (confirm),
+  Outcome unknown, Tasks, Agents, Trail, Help, 80×24 compact, NO_COLOR,
+  refused in an agent run, quit to the shell.
+- **Nav keys.** `c` talk, `i` inbox, `t` tasks, `a` agents, `r` trail;
+  ↑↓ or j/k move; Enter opens; `v` trail of the selection; `:` command
+  line (`:decide`, `:trail`, `:q`); `?` help; `q` quit; Tab moves between
+  the nav and the composer.
+- **Composer.** It keeps the conversation terminal's keys: Enter sends,
+  Ctrl-J newline, Ctrl-T take control, Ctrl-G interrupt, Ctrl-O
+  reconnect, PgUp/PgDn scroll. Header: `<state> | controller|observer |
+  unknown events: N`.
+- **Deciding.** In Inbox, a digit chooses an option. The app then prints
+  the CLI's own lines: `your choice: 1 (Push now); this authorizes the
+  action`, then `resolve <short> with <k>? [y/N]`. Only `y` resolves.
+- **Outcome unknown.** It shows the CLI's text: "outcome unknown: the broker may
+  have recorded it. Check mosaic inbox or mosaic trail <id> before trying
+  again". No retry key.
+- **Inside an agent run.** The app refuses to open and exits 3 with
+  `refused: this runs only from a human shell, outside any agent run
+  (found CLAUDECODE, CLAUDE_CODE_ENTRYPOINT in the environment)`.
+- **Colour.** The app uses the terminal's own 16 colours, so it follows
+  the user's theme:
+  - blue (4): action and selection;
+  - yellow (3): the PM and decisions;
+  - green (2): working, pass, fresh;
+  - bright yellow (11): waiting, stale, expiring, outcome unknown;
+  - red (1): blocking, refused, error, conflict;
+  - bright black (8): hints and rules;
+  - reverse video: the selected row.
+
+  With `NO_COLOR` set, every state still reads from its word and mark.
+
+## Boundaries the design keeps
+
+- **REQ-DEC-3.** A human resolves a decision only from a `mosaic` CLI
+  session outside any agent run. The web shows the decision and a Copy
+  button for `mosaic decide <short> <k>`. It has no Resolve button.
+- **Seen is not resolution.** Seen on the Board and in the inspector
+  acknowledges an Input needed line or a decision. It answers nothing.
+- **Read-only web.** Tasks, the queue, the business file, roles and
+  settings are views. Agents change tasks through the broker's verbs.
+  Rows move only through `queue move`.
+- **Secrets.** Credentials appear as service, account, role and expiry.
+  Values and file paths are never shown.
+- **Loopback only, no sign-in** in v1 (PRD scope).
+
+## Coverage
+
+The Coverage tab lists 39 features. Each row gives the requirement, the
+web screen, the TUI screen and a status. The status describes the code
+today, not these screens:
+- **implemented**: exists in the code now (18 features);
+- **in progress**: has an open queue row (3);
+- **planned**: in the PRD or a brief, with no code yet (3);
+- **proposed**: new in this design (15).
+
+- **In progress.** Talk to the stack-owned PM session (row 41), the
+  launch budget (row 41), and the trail filter chips (row 40).
+- **Planned.** The 08:00 digest, `mosaic stop`, and the business file
+  view.
+- **Proposed** (the larger items). The Inbox tabs, Seen for decisions,
+  the field-writer table on tasks, credential expiry, the command
+  palette, and the business, library, queue, runs and ledger views.
+  Also first-run setup and the five-state treatment on every view.
+
+## Open decisions for Jason
+
+1. **Default palette and mode.** Proposed: Harbor, following the system
+   setting, with Dim available.
+2. **Final mark.** Proposed: refined Relay. The original stays usable
+   from 48 px.
+3. **Resolving from the web.** The PRD rules it out (REQ-DEC-3).
+   Proposed: keep the Copy command through v1.
+4. **One `mosaic` app.** Proposed: `mosaic` with no arguments opens the
+   full-screen app, and the verbs remain for scripts.
+
+## Files
+
+- `mosaic-stack-design.html`: the preview page. Its source is built from
+  a scratch file. Edit the HTML directly for draft 2.
+- `brand/relay-refined.svg`, `brand/relay-original.svg`: the mark in
+  Harbor action blue.

docs/design/brand/relay-original.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 56 56" fill="#215fac" role="img" aria-label="Mosaic Stack Relay concept"><path fill-rule="evenodd" d="M4 18 18 4h12l10 10-8 8-8-8h-2L14 22v2l8 8-8 8L4 30zm48 8L38 40H26L16 30l8-8 8 8h2l8-8v-2l-8-8 8-8 10 10z" transform="translate(0 6)"/></svg>

docs/design/brand/relay-refined.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 17"><path fill="#215fac" fill-rule="evenodd" d="M1 7 5 3 9 3 12 6 9 9 6 6 4 8 4 9 7 12 5 14 1 10ZM15 10 11 14 7 14 4 11 7 8 10 11 12 9 12 8 9 5 11 3 15 7Z"/></svg>