stack/docs/design/README.md

# Mosaic Stack design, draft 1

- Status: draft 1, 2026-10-09. A design, not built software. Nothing
  under `packages/` changed for it.
- 2026-10-10: Jason accepted the direction. The mark stays the refined
  Relay as a placeholder until he revises it. The defaults below are
  provisional. Implementers start from `IMPLEMENTING.md`.
- 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 41 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 (20 features);
- **in progress**: has an open queue row (3);
- **planned**: in the PRD or a brief, with no code yet (1);
- **proposed**: new in this design (17).

- **In progress.** All row 41 (S6): talk to the stack-owned PM
  session, the launch budget, and `mosaic stop`.
- **Planned.** The business file view.
- **Proposed** (the larger items). The Inbox tabs, Seen for decisions,
  task priority and requirement columns, agent state per role, 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.

Corrections on 2026-10-10, checked against the code:
- the 08:00 digest is implemented (`packages/cli/src/notifier.mjs`);
- `mosaic stop` is row 41 work;
- task priority and agent state are not in the bus reads, so they
  moved out of the implemented rows.

`IMPLEMENTING.md` has the gap map per view.

## Open decisions for Jason

1. **Default palette and mode.** Provisional: Harbor, following the
   system setting, with Dim available.
2. **Final mark.** The refined Relay is the placeholder (Jason,
   2026-10-10: "Use the design's logo for now and we will revise.").
3. **Resolving from the web.** The PRD rules it out (REQ-DEC-3).
   Provisional: keep the Copy command through v1.
4. **One `mosaic` app.** Provisional: `mosaic` with no arguments opens
   the full-screen app, and the verbs remain for scripts.
5. **Decision Seen from the web.** It would give the browser a
   human-authority write. Recommended: keep it in the terminal for
   v1.

## Files

- `IMPLEMENTING.md`: the brief for implementing agents.
- `mosaic-stack-design.html`: the preview page. Its source is built from
  a scratch file. Edit the HTML directly for draft 2.
- `tokens.json`, `tokens.css`: design values. `tokens.css` is
  generated by `tools/build-tokens.mjs`.
- `icons.svg`: the icon sprite, plus the placeholder mark.
- `brand/relay-refined.svg`, `brand/relay-original.svg`: the mark in
  Harbor action blue.
- `tools/check-design.mjs`: browser checks for the preview.