stack/docs/design/IMPLEMENTING.md

# Implementing the Mosaic Stack design

This brief is for the agents who build the design. Read it with
`README.md` (the spec) and the preview `mosaic-stack-design.html`.

## Status

- **2026-10-10:** Jason accepted the direction of draft 1. The mark
  stays the refined Relay as a placeholder until he revises it. Do not
  spend work on logo variants.
- **Provisional defaults**, carried in the files and reversible:
  - Harbor palette, following the system light or dark setting;
  - the web shows decisions and copies `mosaic decide`; it never
    resolves them (REQ-DEC-3);
  - `mosaic` with no arguments opens the full-screen app. Today it
    exits 4 (usage).
- **Not authorized by this brief:** queue rows, dispatch, push, or
  any change to a security boundary. Sage owns the queue. Each
  implementation row needs its own brief and review.

## Sources of truth

When two sources disagree, the higher one wins:

1. The PRD (`docs/prd/mosaic-stack.md`) and the repository invariants
   (`AGENTS.md`).
2. Shipped behaviour and strings in `packages/`. The design quotes
   them, and the code is the reference.
3. This brief.
4. `tokens.json`, and the generated `tokens.css`.
5. The preview. It uses sample data and its own internal names. Copy
   layout and states from it, not data, ids or code.

## Files

| File | Use |
|---|---|
| `tokens.json` | Every design value: 10 palettes × light, dim and dark (14 colours each), type scale, radii, spacing, layout widths, terminal colours, status vocabulary |
| `tokens.css` | Generated from `tokens.json`. Do not edit by hand |
| `icons.svg` | Sprite: `mark` (placeholder) and 17 line icons `i-board` … `i-flag` |
| `brand/relay-refined.svg` | The placeholder mark as a standalone file |
| `tools/build-tokens.mjs` | Regenerates `tokens.css`; `--check` exits 1 when it is stale |
| `tools/check-design.mjs` | Browser checks for the preview (see Acceptance) |

## Tokens

- **Names match the shipped console.** `tokens.css` uses the property
  names `packages/webui` already uses: `--canvas` … `--danger`,
  `--onAction` (camelCase, as `brand.js` sets it), `--font`, `--mono`,
  `--r`, `--r-lg`, `--pad`, `--gap`. It adds two names:
  - `--r-table` (8 px);
  - `--strong` (a `color-mix` of `--text`).
- **Selectors.** No attribute means Harbor, light or dark from
  `prefers-color-scheme`. `data-mode="light|dim|dark"` sets the mode.
  `data-palette="<id>"` picks any other palette. The webui already sets
  both attributes on `<html>`.
- **Values are the shipped values.** For all 10 × 3 × 14 colours,
  `tokens.json` equals what `packages/webui/src/public/brand.js`
  `tokens()` computes. Checked 2026-10-10: 0 mismatches.
- **Adopting it in the webui:**
  - serve `tokens.css` (add it to the `files` map in
    `packages/webui/src/serve.mjs`);
  - stop the inline `setProperty` loop in `app.js` `theme()`, which
    would override the stylesheet;
  - keep setting `data-palette` and `data-mode`;
  - add a System choice that removes `data-mode`;
  - keep the localStorage key `mosaic-console-appearance`.
- **Changes the design makes to existing values:**
  - `--r` goes from 8 to 6 px;
  - `--r-lg` goes from 14 to 10 px;
  - `--gap` stays 12 px and `--pad` stays 16 px;
  - `--shadow` stays owned by `app.css`. Use it only for overlays: the
    inspector over the table, the command palette and the toast.
- **Fonts.** The console's CSP is `font-src 'self'`, so every font is
  self-hosted. Manrope 400 to 700 is already served. Add JetBrains Mono
  400, 500 and 700. Manrope 800 is optional: titles may use 700.
- **Type scale:**
  - page title 28/800;
  - section 20/800;
  - question 16/700;
  - text 14/400 at 1.5;
  - table cells 13;
  - labels 11/700 in capitals with 0.06em tracking;
  - mono 12.5.

  Use `font-variant-numeric: tabular-nums` in columns.
- **Regenerate** after editing `tokens.json`:
  `node docs/design/tools/build-tokens.mjs`. Copy the result to the
  webui; the design directory stays the source.

## Icons and the mark

- **Format.** 24-unit grid, `stroke="currentColor"`, width 1.75, round
  caps and joins, no fills. The webui inlines icons through
  `Brand.icon(id)` with the same stroke rules. Replace those paths with
  the sprite's paths so there is one icon set, or serve `icons.svg` and
  use `<svg><use href="/icons.svg#i-inbox"/></svg>`. CSP
  `default-src 'self'` allows a same-origin sprite.
- **Labels.** An icon never carries state alone. Every icon in
  navigation sits next to its text label.
- **The mark.** The `mark` symbol uses `fill="currentColor"` and
  `viewBox="0 0 16 17"`. Draw it at 16, 24 or 32 px. It is a
  placeholder: keep it in one component so a later swap touches one
  file.

## Components

Every component needs the listed states, keyboard behaviour and
focus ring (`--focus`, 2 px, offset 2 px).

| Component | States and rules |
|---|---|
| Command bar | Business name, freshness line ("Vikunja last read 14:21:07 (12 s ago)"), Ctrl+K button. Warning colour plus words when stale |
| Section list | Icon + label + count; `aria-current="page"` on the active view. Below 760 px it becomes a horizontal strip that scrolls inside itself |
| Dense table | 13 px cells, padding 7/10, header labels in caps. Row hover, selected row, ↑/↓ moves, Enter opens the inspector. Wide tables scroll inside their own container |
| Inspector | Right drawer, 300 to 370 px. Over the table below 1100 px; a full-screen sheet below 760 px. Esc closes and returns focus to the row |
| Status mark | Glyph + word, never colour alone: ● working, ◐ waiting, ▲ error, ○ offline, – idle, ? unknown |
| Class chip | routine, within-role, cross-role, gated; BLOCKING is a separate chip |
| Copy command | Mono command + Copy button. Uses the shipped strings (below). Never runs anything |
| Toast | One line, polite live region, auto-dismiss; errors stay until dismissed |
| Command palette | Ctrl+K opens; type to filter views, decisions and tasks; Enter goes; Esc closes and restores focus |
| View states | Five per view: normal; loading (skeleton rows, `aria-busy`); empty (says what would appear and where it comes from); error (banner, last good data stays on screen with its read time); refusal (fail closed: the refusal code in mono and the file or rule that is missing) |
| Not found | Names the bad route, links to the Board, mentions Ctrl+K |

## Views and the gap map

Existing routes in `packages/webui` are hash routes: `#/` (the board),
`#/inbox[/<id>]`, `#/tasks[/<ref>]`, `#/agents`,
`#/trail/task/<ref>`, `#/trail/decision/<id>` (with `?kind=`). New
views follow the same form: `#/talk`, `#/queue`, `#/runs`,
`#/ledger`, `#/business`, `#/library`, `#/settings`, `#/setup`.

Kinds of work:
- **restyle:** built; apply tokens, layout and states;
- **extend:** built; add design pieces whose data the current read
  already returns;
- **new view:** the data exists in a module; add a read-only endpoint
  to the webui server and a view;
- **backend:** the data is not produced or exposed yet;
- **blocked:** waits on another row or on Jason.

| View | Data today | Kind | Notes |
|---|---|---|---|
| Board `#/` | `GET /api/board`, `POST /api/seen` (control board) | restyle | Seat table with Input needed and Seen/Unsee already works |
| Inbox `#/inbox` | `GET /api/bus/inbox`: open decisions routed to `human` | restyle | Detail, authorization sentence, copy commands and history already work |
| Inbox tabs: Routed to roles, Recent | none: `inbox` returns open decisions for the caller's role only | backend | Needs a reader op for decisions routed to other roles and for closed ones |
| Decision Seen | broker `decision.seen` needs a human session (`broker.mjs:614-633`) | blocked | The web holds a reader session. Writing Seen from the browser gives it human authority, a security-boundary change for Jason. The web may show existing `seen` events (bus.js already reads them). The TUI may write Seen once a CLI verb exists |
| Tasks `#/tasks` | `GET /api/bus/tasks`: title, bucket, done, markers, freshness | restyle | |
| Task priority and requirement columns | not in `task_current.fields`; requirement is in the `task.created` event body | backend | |
| Field writers in the task inspector | prose in `docs/plans/2026-10-04_slice-1.md:62-72` | backend | Encode the table as data first |
| Agents `#/agents` | `GET /api/bus/agents`: latest claim per role | restyle | |
| Agent state and Input needed per role | the control board has state per seat; the bus has none per role | backend | Needs a seat-to-role mapping, or state on the bus |
| Launch budget (Opus n of 4, Sonnet n of 4) | ceiling only (`vocabulary.mjs:85-86`); `session.launched` has no model family | blocked | Row 41 (S6) |
| Stop launches (`mosaic stop`) | broker `launch.revoke` / `launch.restore`, no CLI verb | blocked | Row 41 (S6). Web shows the command only |
| Credentials (service, account, role, expiry) | `Credentials.status()` in `packages/bus/src/credentials.mjs:118`; not on the broker | backend | Metadata only. Never a value, token or path |
| Trail `#/trail/...` | `GET /api/bus/trail?subject=`; filter chips shipped (`bus.js:313`) | restyle | |
| Talk `#/talk` | the conversation History view exists; the live PM session is row 41 | blocked | Row 41 (S6). Reuse the controller/observer rules of `packages/conversation` |
| Queue `#/queue` | `packages/queue/src/store.mjs` `list`/`show`; no endpoint | new view | Read-only. Rows move only through `queue move` |
| Ledger `#/ledger` | `packages/ledger` `summarize`, `queueChecks` | new view | Read-only |
| Business `#/business` | `packages/business` `loadBusiness`, `loadRole`, `resolveInstance`, `vocabulary.mjs` | new view | Read-only. A missing or invalid file shows the refusal state. Credential refs as metadata only |
| Runs and releases `#/runs` | readers live inside `scripts/mosaic-task.mjs` and `scripts/release.sh`, not exported | backend | Extract a read-only module first |
| Library `#/library` | no meta-harness in committed code | blocked | Row 41 (S6) creates `packages/harness` |
| Settings `#/settings` | appearance exists in the webui header; notifier config `readNotifyConfig` | extend | Appearance, notifications (binding names only), about (loopback, release). Read-only apart from appearance |
| Set up `#/setup` | validation lives in `scripts/mosaic-config.mjs` (a script) | backend | First-run checklist; the installer is out of v1 scope |
| Command palette, five states, not found | client-side | extend | |

The Board is the console home. The control board's own page on port
7331 stays until the console's Board covers it.

## The full-screen terminal app

- **Where.** `packages/cli`. Node built-ins only; the CLI has no
  dependencies and must keep none.
- **Talk.** Embed the conversation `Terminal` class
  (`packages/conversation/src/terminal.mjs:54`,
  `new Terminal({client, write, rows, onQuit})`). Its `main()` owns the
  process, so do not call it. The app owns the screen and draws the
  conversation inside the Talk pane.
- **Size.** Read `process.stdout.columns` and `rows`; redraw on
  `resize`. Designed at 120×36; every screen must fit 80×24. Below
  100 columns:
  - the nav shows keys only;
  - Inbox drops RAISED BY and REACHES YOU;
  - detail moves below the list.
- **Colour.**
  - Use the terminal's own 16 colours (`tokens.json` `terminal.ansi`),
    never 256-colour or RGB.
  - Honour `NO_COLOR` (any non-empty value): no colour codes; reverse
    video stays for the selected row, and every state still reads
    from its word and mark.
  - Not a TTY: refuse the full-screen app and point at the verbs.
- **Refusal.** In an agent run, exit 3 with the transport's message
  (`packages/cli/src/transport.mjs:30`). That is the same check the
  verbs use; do not write a second one.
- **Deciding.** In Inbox, a digit picks an option. Then print the
  CLI's lines and resolve only on `y`. Reuse the `decide` code path
  rather than a copy of it. "Outcome unknown" offers no retry key.
- **Keys:**
  - `c` talk, `i` inbox, `t` tasks, `a` agents, `r` trail;
  - ↑↓ or j/k move, Enter opens, `v` opens the trail of the selection;
  - `:` command line, `?` help, `q` quit;
  - Tab moves between the nav and the composer;
  - the composer keeps the conversation keys.
- **No-argument behaviour** is a CLI change from exit 4 to opening the
  app. It is provisional; land it behind its own review.

## Strings to keep exactly

These are shipped. Reuse them; do not reword.

- **Decide:**
  - `your choice: <key> (<text>); this authorizes the action`, or
    `…; this declines the action`;
  - `resolve <id8> with <key>? [y/N] `;
  - `resolved <full id>: <key>`;
  - `outcome unknown: the broker may have recorded it. Check mosaic inbox or mosaic trail <id> before trying again`.
- **Refusal:** `refused: this runs only from a human shell, outside any agent run (found <VARS> in the environment)`.
- **Web copy:**
  - `Copied: <command>`;
  - `The clipboard is unavailable. The command is selected; press Ctrl+C to copy it.`;
  - `Decisions are answered in a terminal with mosaic decide; Console only shows them.`
- **CLI list formats** (`packages/cli/src/format.mjs`):
  - inbox `<id8>  <action>  (<class>[, blocking])  raised <at> by <role>`;
  - tasks `<ref>  <state>  <title>`;
  - agents `<role>  <holder_run>  <harness|->  since <at>`;
  - trail `<at>  <table>#<seq>  <summary>`.
- **Trail sentences, empty states and not-found lines** are in
  `packages/webui/src/public/bus.js` (for example
  `No task <ref> in this business.`). The "feat" labels there mark
  the gaps this design fills: poller status, bucket names, role
  instances and launch limits.
- **Bus wording stays in mono:** event kinds (`task.changed.external`),
  refusal codes (`decision-closed`, `launch-revoked`), task refs and
  ids.

## Boundaries

- **No Resolve button on the web.** Copy the `mosaic decide` command
  only (REQ-DEC-3).
- **Seen is not resolution.** Board Seen/Unsee exists. Decision Seen
  from the web is blocked (see the gap map).
- **Read-only web**, apart from Board Seen/Unsee, the board's
  existing reply path, and appearance settings stored in the browser.
  Queue rows move only through `queue move`; the business file is
  written by the human only.
- **Secrets.** Show service, account, role and expiry. Never show
  values, tokens or file paths. Never log them.
- **Server.**
  - Loopback only, no sign-in;
  - keep the existing CSP, Host and Origin checks;
  - new endpoints are `GET` only and return JSON;
  - no new dependencies in `packages/webui` or `packages/cli`.

## Acceptance

For every implementation row:
- the package's own suite passes: `node --test tests/` in
  `packages/webui` or `packages/cli`, plus the repository suites the row
  touches;
- `node docs/design/tools/build-tokens.mjs --check` passes when tokens
  changed;
- every changed view shows its five states. Seeded tests cover the
  empty, error-with-stale-data and refusal states;
- browser tests (`packages/webui/tests/browser.mjs` style):
  - no script errors;
  - no sideways page scroll at 400 px;
  - keyboard path: ↑/↓, Enter, Esc returning focus to the row;
  - focus is visible;
- terminal app tests:
  - every screen fits 120 columns and 80×24;
  - `NO_COLOR` output has no escape codes;
  - an agent-run environment exits 3;
- strings in "Strings to keep exactly" are unchanged (a grep test is
  enough).

`node docs/design/tools/check-design.mjs` checks the preview itself:
- no script errors across 4 tabs, 13 views × 5 states and 13 terminal
  screens;
- no sideways scroll at 400 px;
- terminal widths;
- palette colours against `tokens.json`.

It needs a local Chromium (`$CHROMIUM` or `/usr/bin/chromium`). Run it
after editing the preview.

## Proposed rows (for Sage)

Draft order. These go after rows 41 and 42. Sage decides whether to
queue them, and in what order.

1. **Console tokens and shell restyle** (frontend; Dewey's area).
   - Scope:
     - adopt `tokens.css`;
     - command bar, section list, dense table, inspector, toast,
       command palette, not found;
     - five states on Board, Inbox, Tasks, Agents and Trail.
   - No new data.
2. **Read-only views with existing data** (frontend plus webui
   server). Queue, Ledger, Business, Settings: `GET` endpoints over the
   existing modules.
3. **Full-screen `mosaic` app** (CLI): Inbox, Tasks, Agents, Trail,
   Help, decide, NO_COLOR and 80×24. Talk joins after row 41.
   - Needs Jason's confirmation of no-argument `mosaic`.
4. **Backend reads for the design** (bus):
   - decisions routed to roles and recent decisions;
   - task priority and requirement;
   - agent state per role;
   - credential status on the broker;
   - the field-writer table as data;
   - a runs and release reader module.

   Each is a separate small row.
5. **After row 41:** Talk view, launch budget, `mosaic stop` in both
   surfaces, Library.

## Open decisions for Jason

1. Default palette and mode (provisional: Harbor, following the system
   setting).
2. The final mark (placeholder: refined Relay).
3. No-argument `mosaic` opens the full-screen app (provisional).
4. Decision Seen from the web. It needs a human-authority write path
   from the browser. The recommendation is to keep it in the terminal
   for v1.