chore(core): add qrcode dependency for recovery QR

- coordination/v0.5.1-pm-prompt.md — PM coordinates 3 streams, enforces
  interface contracts (A-B settings signature, B-C security component),
  owns merge order and pre-tag checklist
- coordination/v0.5.1-dev-a-prompt.md — Stream A: fullscreen 3-column
  layout, sidebar category nav, detail drawer, bottom sheet, popup type-
  picker polish, per-type glyph icons, empty states, toast system (13 tasks)
- coordination/v0.5.1-dev-b-prompt.md — Stream B: settings left-nav
  redesign (Autofill, Display, Security, Generator, Retention, Backup,
  Import sections), security component stub (10 tasks)
- coordination/v0.5.1-dev-c-prompt.md — Stream C: recovery_qr.rs core,
  WASM session expansion, CLI subcommand, settings-security.ts three-state
  component, setup wizard Style C redesign + QR banner (12 tasks)
- Archive v0.5.0 coordination files to coordination/archive/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude/settings.json

@@ -1,4 +1,10 @@
 {
+  "mcpServers": {
+    "relay": {
+      "type": "sse",
+      "url": "http://localhost:7331/sse"
+    }
+  },
   "enabledPlugins": {
     "superpowers@claude-plugins-official": true
   }

.gitignore

@@ -7,3 +7,4 @@ extension/dist-firefox/
 extension/wasm/
 reference.jpg
 ref.jpg
+tools/relay/node_modules/

CHANGELOG.md

@@ -1,9 +1,76 @@
 # Changelog
 
-## Unreleased
+## v0.5.0 — 2026-05-02
+
+Three release trains roll into one tag — backup/restore + LastPass
+import (originally v0.3.0), device authentication (originally v0.4.0),
+and the v0.5.0 polish + harden bundle (security fixes + UX fixes +
+two confirmed bugs).
+
+### Security
+
+- **Pre-receive hook now actually verifies signatures (audit S1, HIGH).**
+  Earlier `relicario-server` builds accepted any commit with a
+  `Good signature` line on stderr regardless of which key signed it —
+  device-auth was a no-op. The hook now builds an `allowed_signers`
+  file from `devices.json` at the commit (via `GIT_CONFIG_*` env, no
+  global git-config mutation), parses the SSH SHA-256 fingerprint out
+  of `git verify-commit --raw` stderr, and rejects unregistered keys or
+  revoked keys whose committer-date is at or after the revocation
+  timestamp. Bootstrap mode is preserved only when **both**
+  `devices.json` AND `revoked.json` are empty (closes an
+  empty-devices.json privilege-escalation route).
+- **Backup-restore tar unpacking hardened (audit S2).** `relicario
+  backup restore` no longer trusts `tar::Archive::unpack`'s defaults.
+  A new `relicario_core::safe_unpack_git_archive` validates each
+  entry's path components (rejects `..`, absolute paths, Windows
+  drive prefixes), rejects symlinks/hardlinks, and caps total
+  uncompressed size at the lower of 100×compressed-bytes or 1 GiB.
+  The CLI restore path adds a paranoid `dest.starts_with(.git/)`
+  check after path-joining as defense-in-depth.
+- **`RELICARIO_*` env-var surface audited (audit S3).** `docs/SECURITY.md`
+  gains a per-variable trust table. `RELICARIO_NO_GROUPS_CACHE` (a
+  developer escape hatch, not a user knob) is now
+  `cfg(debug_assertions)`-gated and is a no-op in `--release` builds;
+  the env-var lookup is removed from the binary by the optimiser.
+
+### Fixed
+
+- **Strength meter no longer goes stale after the regenerate button (B1).**
+  Programmatic `input.value = newPassword` doesn't fire `input`
+  events; the regenerate handler now dispatches a synthetic
+  `InputEvent('input', { bubbles: true })` so the meter listener
+  re-rates the new value.
+- **Snake_case error codes no longer leak into the UI (B2 / P4).**
+  Errors like `vault_locked`, `origin_mismatch`, `unauthorized_sender`
+  used to render verbatim in the fullscreen vault tab and (in some
+  cases) the popup. New `extension/src/shared/error-copy.ts` central
+  registry maps every service-worker error code to friendly
+  title/body/CTA copy; the popup and fullscreen tab consume the
+  same map. The fullscreen lock screen's `vault_locked` block now
+  reads `Vault locked / Unlock your vault to continue. / [Unlock
+  vault]`. A generated test enumerates the live error codes via
+  grep so the registry can't drift.
 
 ### Added
 
+- **Sidebar logo in the fullscreen vault tab.** The
+  `vault-sidebar__header` now renders the 16-optimized SVG logo
+  inline before the "Relicario" wordmark (20×20 px, `flex-shrink: 0`
+  so it survives narrow-pane wraps). Popup unaffected.
+- **Password coloring (P1).** Revealed passwords in the popup
+  item-detail, fullscreen item view, field-history viewer, and
+  generator preview render digits and symbols in distinct colors.
+  Defaults: blue digits, red symbols. Users can override via the
+  new Display section in settings (color pickers + live preview
+  swatch + reset). Defaults round-trip via
+  `chrome.storage.sync.password_display_scheme`; cross-device when
+  Chrome sync is enabled.
+- **Setup wizard hands off to the fullscreen vault tab on completion
+  (P2).** Both create-new and attach-existing flows now open
+  `vault.html` in a new tab and best-effort close the setup tab
+  after device registration succeeds — replaces the prior
+  setup-tab-stays-open terminal screen.
 - **Sync now button** in the extension settings view — surfaces the
   previously hidden `{ type: 'sync' }` SW message to users with success /
   error feedback.
@@ -59,6 +126,30 @@
   file `cmd_backup_export` writes on success). Reads "never" for
   fresh vaults, "4 days ago" otherwise.
 
+### Changed
+
+- **Form layout in the fullscreen vault tab is now visually consistent
+  (P3).** Notes, custom-fields disclosure, attachments disclosure, and
+  form-actions in fullscreen logins now sit inside a `.form-lower`
+  wrapper with the same `max-width: 960px; margin: 0 auto` envelope as
+  the `.form-grid` cards above. Removes the visual rhythm break at the
+  2-col → full-width transition. The popup surface is unchanged.
+- **Documentation refreshed for v0.5.0 (doc audit, 14 findings).**
+  `docs/architecture/overview.md` now describes four codebases (the
+  `relicario-server` pre-receive hook crate is no longer invisible);
+  `CLAUDE.md` project tree and roadmap reflect current state;
+  `docs/SECURITY.md` names the server crate and its `verify-commit` /
+  `generate-hook` subcommands and notes the without-the-hook-it's-
+  advisory caveat; `docs/ARCHITECTURE.md` shows `settings.enc` as a
+  parallel artifact in the vault-creation flow; the foundational
+  design spec gains a "historical" status banner pointing readers at
+  the current docs.
+- `relicario generate` now consults `VaultSettings.generator_defaults` when
+  invoked inside an initialized vault. Explicit flags (`--length`,
+  `--bip39`, `--words`, `--symbols`, `--separator`) override the vault
+  default. Outside a vault, behavior is unchanged (length 20, safe symbol
+  set, 5 BIP39 words, space separator).
+
 ### Known limitations
 
 - **Mid-restore failure leaves the target remote in a half-written
@@ -74,6 +165,13 @@
 
 ### Internal
 
+- 5 stale local feature branches and 3 worktrees pruned (audit C1).
+- Pre-existing clippy warnings cleaned up across `relicario-{core,cli}`
+  (deref operators, `Option::is_none_or` over `map_or(true, ...)`,
+  `iter_mut().enumerate()` patterns, `div_ceil()`) so the workspace
+  builds clean under `-D warnings`.
+- `Cargo.lock` regenerated and committed; was stale since the
+  `--totp-qr` commit.
 - Refactored `cmd_add` and `cmd_edit` in the CLI: each `ItemCore` variant
   now has its own `build_*_item` / `edit_*` helper. Pure mechanical
   extraction; behavior unchanged. The dispatcher matches and delegates.
@@ -83,14 +181,6 @@
   `setup.ts` since it walks live wizard state. Setup.ts went from
   1205 → 1137 lines.
 
-### Changed
-
-- `relicario generate` now consults `VaultSettings.generator_defaults` when
-  invoked inside an initialized vault. Explicit flags (`--length`,
-  `--bip39`, `--words`, `--symbols`, `--separator`) override the vault
-  default. Outside a vault, behavior is unchanged (length 20, safe symbol
-  set, 5 BIP39 words, space separator).
-
 ## v0.2.0 — 2026-04-27
 
 ### Fixed

CLAUDE.md

@@ -48,9 +48,11 @@ crates/
 │   ├── src/helpers.rs      # vault_dir, git_command, iso8601
 │   ├── src/session.rs      # UnlockedVault (master key in Zeroizing)
 │   └── tests/              # basic_flows, edit_and_history, attachments, settings, vault_detection
-└── relicario-wasm/            # WASM bindings for the extension
-    ├── src/lib.rs          # #[wasm_bindgen] surface
-    └── src/session.rs      # opaque SessionHandle → Zeroizing<[u8;32]>
+├── relicario-wasm/            # WASM bindings for the extension
+│   ├── src/lib.rs          # #[wasm_bindgen] surface
+│   └── src/session.rs      # opaque SessionHandle → Zeroizing<[u8;32]>
+└── relicario-server/          # `relicario-server` binary (pre-receive Git hook)
+    └── src/main.rs         # verify-commit + generate-hook subcommands
 ```
 
 ## Key design decisions
@@ -76,7 +78,7 @@ passphrase (UTF-8 bytes) || image_secret (32 bytes from reference JPEG)
 
 - Tests use fast Argon2id params (m=256, t=1, p=1) so they don't take forever.
 - Test JPEGs are generated synthetically via `make_test_jpeg()` — no binary test fixtures.
-- Item IDs are random 8-char hex strings.
+- Item IDs and Field IDs are random 16-char hex strings (64 bits of OsRng entropy). AttachmentIds are content-addressed: first 32 hex chars of SHA-256 over the plaintext (128 bits).
 - Git history is preserved as an audit log — no squashing.
 - The CLI shells out to `git` for sync — no libgit2/gitoxide dependency.
 
@@ -90,4 +92,4 @@ Full threat model, entropy analysis, and architecture: `docs/superpowers/specs/2
 
 ## Roadmap
 
-Next: WASM build + Chrome MV3 browser extension (Plan 2). Then mobile (Rust core compiles to ARM).
+Next: v0.5.0 polish + harden (in progress). After that, Phases 3/4 of the fullscreen UX redesign (vault-tab shell + command palette), Plan 1C-γ (attachments + Document + trash/history/device UI), and the LastPass importer. Mobile (Rust core compiles to ARM) and recovery QR remain on the roadmap.

crates/relicario-core/Cargo.toml

@@ -31,5 +31,6 @@ zstd = { version = "0.13", default-features = false }
 tar = { version = "0.4", default-features = false }
 base64 = "0.22"
 csv = "1"
+qrcode = { version = "0.14", default-features = false }
 
 [dev-dependencies]

docs/ARCHITECTURE.md

@@ -83,8 +83,9 @@ vault_salt ────────►│                  │
 
                     ┌──────────────────┐
 master_key ────────►│  XChaCha20-      │──────► manifest.enc
-empty manifest ────►│  Poly1305        │
-                    └──────────────────┘
+empty manifest ────►│  Poly1305        │        settings.enc
+default settings ──►│  encrypt (×2)    │        (parallel artifacts;
+                    └──────────────────┘         independent nonces)
 
                     ┌──────────────────┐
                     │  git init        │──────► vault repo
@@ -92,6 +93,14 @@ empty manifest ────►│  Poly1305        │
                     └──────────────────┘
 ```
 
+Item creation, the typed-item envelope (`Item` + per-type `ItemCore`),
+attachment encryption, and field-history tracking are not shown above —
+they are described in [`crates/relicario-core/ARCHITECTURE.md`](../crates/relicario-core/ARCHITECTURE.md).
+The flow above covers only the crypto-pipeline shape that vault init
+establishes; the per-item lifecycle reuses the same `master_key` +
+XChaCha20-Poly1305 primitives against `items/<id>.enc` and
+`attachments/<item-id>/<aid>.enc`.
+
 ## Unlock Flow (every vault operation)
 
 ```

docs/SECURITY.md

@@ -48,6 +48,19 @@ When enabled, device authentication provides:
 - **Push access control**: Deploy keys managed via Gitea API
 - **Instant revocation**: One command cuts off both signing and push
 
+Enforcement requires deploying the `relicario-server` pre-receive hook
+on the vault remote. The crate provides two subcommands:
+
+- `relicario-server generate-hook` — emits the hook script to install at
+  `<repo>/hooks/pre-receive`
+- `relicario-server verify-commit <sha>` — checks one commit's signature
+  against `.relicario/devices.json` and `.relicario/revoked.json` as of
+  that commit; the hook calls this for every pushed ref
+
+Without the server hook, signed commits provide authorship metadata only
+— any process with push access can land an unsigned commit, since
+verification is otherwise advisory.
+
 See `docs/superpowers/specs/2026-05-02-device-authentication-design.md`.
 
 ## Access Control
@@ -57,8 +70,7 @@ Without device authentication, access control is transport-layer only:
 - **CLI**: SSH key authentication to git remote
 - **Extension**: Git credentials in browser storage
 
-Device registration was optional before v0.4.0. With device auth enabled,
-all commits must be signed by a registered device.
+Device registration is optional but recommended for shared vaults.
 
 ## Configuration env vars
 

docs/architecture/overview.md

@@ -1,6 +1,6 @@
 # Architecture overview — Relicario
 
-This is the cross-codebase entry point. It describes how the three Relicario codebases fit together, the contracts that flow between them, and the conventions they share. It is **deliberately thin**; the deep content lives in per-codebase docs.
+This is the cross-codebase entry point. It describes how the four Relicario codebases fit together, the contracts that flow between them, and the conventions they share. It is **deliberately thin**; the deep content lives in per-codebase docs.
 
 > If you are about to make a change in a single codebase, read its `ARCHITECTURE.md` first:
 >
@@ -10,7 +10,7 @@ This is the cross-codebase entry point. It describes how the three Relicario cod
 >
 > If you want historical *why*, see `docs/superpowers/specs/` — those are time-stamped decision artifacts. This overview describes what *is*.
 
-## The three codebases
+## The four codebases
 
 ```
                           ┌─────────────────────┐
@@ -18,36 +18,40 @@ This is the cross-codebase entry point. It describes how the three Relicario cod
                           │  (Rust, no I/O)     │
                           │  crypto · items     │
                           │  manifest · stego   │
-                       └──────────┬──────────┘
+                          │  device keys + fp   │
+                          └──┬───────────┬──────┘
+                             │           │
+            ┌────────────────┼───────────┴──────┬────────────────────┐
+            │                │                  │                    │
+            ▼                ▼                  ▼                    ▼
+   ┌────────────────┐ ┌──────────────────┐ ┌────────────────────┐
+   │ relicario-cli  │ │ relicario-server │ │  relicario-wasm    │
+   │ (Rust binary)  │ │ (Rust binary)    │ │  (#[wasm_bindgen]  │
+   │                │ │                  │ │   bindings)        │
+   │ filesystem +   │ │ pre-receive hook │ │                    │
+   │ git +          │ │ verify-commit  + │ │  compiled to WASM  │
+   │ clap UX        │ │ generate-hook    │ │  for the extension │
+   └────────────────┘ └──────────────────┘ └──────────┬─────────┘
                                                       │
-            ┌─────────────────────┼─────────────────────┐
-            │                     │                     │
-            ▼                     ▼                     ▼
-   ┌────────────────┐   ┌────────────────────┐  (compiled to WASM
-   │ relicario-cli  │   │  relicario-wasm    │   inside the      )
-   │ (Rust binary)  │   │  (#[wasm_bindgen]  │   extension       │
-   │                │   │   bindings)        │                   │
-   │ filesystem +   │   │                    │                   │
-   │ git +          │   └────────┬───────────┘                   │
-   │ clap UX        │            │                               │
-   └────────────────┘            ▼                               │
-                       ┌─────────────────────┐                   │
-                       │  extension          │                   │
-                       │  (TypeScript)       │                   │
-                       │  popup · vault      │                   │
-                       │  setup · content    │                   │
-                       │  service worker     │                   │
+                                                      ▼
+                                           ┌─────────────────────┐
+                                           │  extension          │
+                                           │  (TypeScript)       │
+                                           │  popup · vault      │
+                                           │  setup · content    │
+                                           │  service worker     │
                                            └─────────────────────┘
 ```
 
 | Codebase | Language | Role | Key boundary |
 |---|---|---|---|
-| `relicario-core` | Rust | Crypto, item types, manifest, attachments, imgsecret, generators. Pure, no I/O. | Only `bytes-in / bytes-out`. No filesystem, no git, no network. |
+| `relicario-core` | Rust | Crypto, item types, manifest, attachments, imgsecret, generators, device keys / fingerprints. Pure, no I/O. | Only `bytes-in / bytes-out`. No filesystem, no git, no network. |
 | `relicario-cli` | Rust binary | Wraps core with filesystem ops, git plumbing, clap UX. | Only entry point that runs without a browser; sole working interface during disaster recovery. |
 | `relicario-wasm` | Rust → WASM | Thin `#[wasm_bindgen]` exports from core for the extension. | Compiles `relicario-core` to WASM; no extra logic. |
+| `relicario-server` | Rust binary | Pre-receive Git hook (`verify-commit`) plus hook installer (`generate-hook`) running on the vault remote. Verifies SSH-signed commits against `.relicario/devices.json` and `.relicario/revoked.json`. | Lives on the git server, not on a client device. The only Relicario component the user does not run themselves. Sees only public key material. |
 | `extension` | TypeScript | Browser-resident UI. Five entry-point bundles (popup, vault tab, setup, content script, service worker). | The service worker is the only crypto holder; popup/vault/content/setup never touch the master key. |
 
-The CLI and the extension are **at parity**: every user-facing capability lands in both surfaces together. Diverging is allowed only with a documented reason. See the per-codebase docs for which surface owns which user flow.
+The CLI and the extension are **at parity**: every user-facing capability lands in both surfaces together. Diverging is allowed only with a documented reason. See the per-codebase docs for which surface owns which user flow. The server has no user-facing surface — it is a server-side enforcer of the device-auth invariant the clients already agreed to.
 
 ## Inter-codebase contracts
 
@@ -151,6 +155,7 @@ The CLI keeps its master key in process memory; if the process exits or crashes,
 | Target | Tool | Output | When to run |
 |---|---|---|---|
 | Native CLI | `cargo build` (debug or `--release`) | `target/{debug,release}/relicario` | After CLI changes; for distribution |
+| Server hook | `cargo build -p relicario-server --release` | `target/release/relicario-server` | After server changes; deploy onto the git remote |
 | Native test suites | `cargo test` (workspace) | — | After any Rust change |
 | WASM module | `wasm-pack build --target web` (via `npm run build:wasm`) | `extension/wasm/relicario_wasm{,_bg.wasm,.js}` | After core or wasm crate changes |
 | Chrome extension | `webpack` (`npm run build`) | `extension/dist/` | After TS or WASM changes; for Chrome distribution |
@@ -196,6 +201,7 @@ Core tests use **fast Argon2id params** (m=256, t=1, p=1) so they don't take for
 | A new popup view, vault tab feature, or autofill change | [`extension/ARCHITECTURE.md`](../../extension/ARCHITECTURE.md) |
 | A new SW message type | `extension/src/shared/messages.ts` (capability sets), then [`extension/ARCHITECTURE.md § Invariants`](../../extension/ARCHITECTURE.md) |
 | A new GitHost (e.g. GitLab support) | `extension/src/service-worker/git-host.ts` (interface) and existing implementations |
+| The pre-receive hook / device-auth enforcement | `crates/relicario-server/src/main.rs`, then `docs/superpowers/specs/2026-05-02-device-authentication-design.md` for rationale |
 | Adding a new item type | core's `item_types/` mod, then CLI's `build_*_item`/`edit_*` helpers, then extension's `popup/components/types/<type>.ts` |
 | Threat model / why a primitive was chosen | `docs/superpowers/specs/2026-04-11-relicario-design.md` (historical, but authoritative for rationale) |
 | Format of the import/export feature | `docs/superpowers/specs/2026-04-27-relicario-import-export-design.md` (designed but not yet implemented) |

docs/superpowers/MULTI-AGENT.md

@@ -0,0 +1,165 @@
+# Multi-Agent Development Paradigm
+
+This repo uses a three-terminal workflow for large development lifts: one Claude Code session acts as **PM** and two act as **senior developers** (Dev-A, Dev-B), each working in their own git worktree on a parallel feature branch.
+
+A local relay MCP server eliminates manual message copying between terminals — agents call `post_message`/`read_messages` instead of asking the user to copy-paste.
+
+---
+
+## Overview
+
+| Role | Terminal | Branch | Responsibilities |
+|------|----------|--------|-----------------|
+| PM | 1 | `main` (read-only) | Drive doc-audit follow-ups, review PRs, write CHANGELOG, authorize merges and tagging |
+| Dev-A | 2 | `feature/<release>-plan-a-*` | Implement Plan A tasks in their own worktree |
+| Dev-B | 3 | `feature/<release>-plan-b-*` | Implement Plan B tasks in their own worktree |
+| Relay server | 4 | — | Message bus; Ctrl-C to stop at end of lift |
+
+**User's job:** authorize merges (the PM asks), resolve escalations the PM can't handle, and watch the streams. You are no longer the message bus.
+
+---
+
+## Starting a lift
+
+### Prerequisites
+
+- [ ] Kickoff prompts exist in `docs/superpowers/coordination/` (generate with the `multi-agent-kickoff` skill if not)
+- [ ] No uncommitted changes in main that would confuse the devs
+- [ ] `tools/relay/` is present (run `ls tools/relay/` to confirm)
+
+### Launch sequence
+
+```bash
+# 1. Start the relay server (this terminal becomes the relay log)
+tools/relay/start.sh           # prints copy-paste instructions, then starts server
+
+# Optional: use a multiplexer to auto-open all four terminals
+tools/relay/start.sh --tmux    # creates tmux session "relay-lift" with 4 windows
+tools/relay/start.sh --kitty   # creates kitty tab "relay" + 3 windows
+```
+
+`start.sh` prints the paths to the three kickoff prompt files. In each Claude Code terminal, run `cat <path>` and paste everything below the `---` line as the first message.
+
+---
+
+## Coordination protocol
+
+Agents communicate by posting structured blocks to each other's inboxes. Four message kinds:
+
+| Kind | Block header | When used |
+|------|-------------|-----------|
+| `status` | `## STATUS UPDATE — DEV-*` | After completing a task, getting blocked, or reaching a review-ready state |
+| `question` | `## QUESTION TO PM — DEV-*` | When a dev needs PM input mid-task |
+| `directive` | `## DIRECTIVE TO DEV-*` | When PM instructs a dev to proceed, hold, rescope, or approve a PR |
+| `free` | (none) | Ad-hoc messages not covered by the above |
+
+A well-formed `status` block:
+
+```
+## STATUS UPDATE — DEV-B
+Time: 2026-05-02T14:30:00-07:00
+Branch: feature/v0.5.0-plan-b-extension-ux
+Task: P4 / error-copy map
+Status: DONE
+Last commit: abc1234 feat(extension): centralize ERROR_COPY map
+Tests: green
+Notes: No issues. Ready for PM review of P4 before starting B1.
+```
+
+---
+
+## Using the relay tools
+
+All three Claude Code sessions have these tools available when the relay server is running:
+
+```
+post_message(from, to, kind, body)   → { id }
+read_messages(for)                   → RelayMessage[]   (drains inbox)
+list_pending(for)                    → { count, kinds } (non-destructive)
+```
+
+Typical dev flow per task:
+
+```
+1. read_messages(for="dev-b")           # check for directives before starting
+2. ... do the work ...
+3. post_message(from="dev-b", to="pm", kind="status", body="## STATUS UPDATE...")
+```
+
+Typical PM flow:
+
+```
+1. read_messages(for="pm")             # see what devs posted
+2. ... review ...
+3. post_message(from="pm", to="dev-b", kind="directive", body="## DIRECTIVE TO DEV-B...")
+```
+
+---
+
+## If the relay server isn't running
+
+Claude Code will show a yellow MCP connection warning for the `relay` server. The tools will be unavailable.
+
+Agents fall back to the manual protocol: they emit the structured blocks as text and ask the user to copy-paste them to the relevant terminal. This is slower but fully functional — the coordination protocol works either way.
+
+To restart a crashed server mid-lift:
+
+```bash
+tools/relay/start.sh
+```
+
+In-flight messages are lost on restart. Any agent with unread messages should re-post them.
+
+---
+
+## Generating kickoff prompts
+
+### Full workflow (spec → plans → kickoff)
+
+**Step 1 — Write a spec**
+
+Run the `superpowers:brainstorming` skill. At the end it invokes `superpowers:writing-plans` for each dev stream. Each stream gets its own plan file in `docs/superpowers/plans/`. The spec lives in `docs/superpowers/specs/`.
+
+**Step 2 — Invoke the kickoff skill**
+
+Say anything like:
+- "kick off the multi-agent thing for v0.6.0"
+- "spin up PM and devs for this release"
+- "set up the three-terminal paradigm"
+
+The `multi-agent-kickoff` skill auto-triggers on those phrases. It will:
+
+1. Auto-discover the spec and plans by date/release label (asks to confirm if ambiguous)
+2. Generate `docs/superpowers/coordination/<release>-pm-prompt.md` and one `-dev-<letter>-prompt.md` per plan
+3. Inject the relay paragraph, branch names, worktree paths, test commands, and scope partitioning automatically from the plans and `CLAUDE.md`
+4. Commit the prompts and print launch instructions
+
+N>2 devs works automatically — 3 plans produces PM + Dev-A/B/C prompts.
+
+**Step 3 — Launch**
+
+```bash
+tools/relay/start.sh        # prints prompt file paths, starts relay server
+# open N+1 terminals, paste each prompt below its '---' line
+```
+
+The skill reminder: run `tools/relay/start.sh` **before** opening the Claude Code sessions — the MCP tools need the server up when each session initializes.
+
+---
+
+## Ending a lift
+
+1. PM emits `REVIEW-COMPLETE` and `MERGE-APPROVED` for each dev's PR
+2. User merges each PR (the PM session does `gh pr merge` with user authorization)
+3. PM tags the release (only after explicit user `yes`)
+4. Ctrl-C the relay terminal — all in-memory messages are discarded
+
+---
+
+## Roles and boundaries (quick reference)
+
+**PM must not:** write feature code, merge without user authorization, tag without user approval, run `git push --force` / `git reset --hard` without asking.
+
+**Devs must not:** merge their branch to main, push `--force`, run `git reset --hard` without asking.
+
+**User must:** authorize all merges and the release tag. Everything else is delegated.

docs/superpowers/audits/2026-05-02-doc-audit.md

@@ -5,8 +5,9 @@ Pre-v0.5.0 audit of Relicario's documentation against the current codebase.
 ## Summary
 
 - **Total findings:** 14
-- **Fixed inline:** 6
-- **Need user input (proposed only):** 8
+- **Fixed inline (initial pass):** 6
+- **Fixed during v0.5.0 PM run (this audit, follow-up commits):** 8
+- **No action needed:** 0
 - **Top 3 recommendations:**
   1. **Add `relicario-server` to architecture docs.** It exists in `crates/`, is referenced by SECURITY.md, and underpins device-auth, but `docs/architecture/overview.md`'s "three codebases" framing and `CLAUDE.md`'s project-structure tree still pretend it doesn't exist (Findings 1, 2, 9). This is the single biggest gap before tagging v0.5.0.
   2. **Replace `CLAUDE.md`'s Roadmap.** It still says "Next: WASM build + Chrome MV3 browser extension (Plan 2)" — a milestone that shipped weeks ago. Multiple subsequent train rounds (typed items, attachments, backup, LastPass, device auth, fullscreen UX phases) have shipped, none of which are reflected (Finding 3).
@@ -24,7 +25,7 @@ The codebase itself is well-documented — `crates/{relicario-core,relicario-cli
 **Issue:** The repo now has **four** Rust crates (`relicario-core`, `relicario-cli`, `relicario-wasm`, `relicario-server`) plus the extension. The framing "The three codebases" + accompanying ASCII diagram + four-row table all predate the May 2026 server crate. `relicario-server` is the pre-receive hook binary that enforces device-signature verification — load-bearing for the device-auth model that SECURITY.md already advertises.
 **Fix:** Re-title the section ("The four codebases" or "The relicario codebases"), add a server box to the diagram, add a row to the table. The role is "Pre-receive Git hook that verifies commit signatures against `.relicario/devices.json` and `.relicario/revoked.json`".
 **Severity:** must-fix-before-v0.5.0
-**Status:** Proposed; needs user decision (>50 words of new prose; touches the framing of the whole overview doc)
+**Status:** Fixed in `ca059e7` (PM follow-up, 2026-05-02): "four codebases" framing, ASCII diagram fans core out to cli + server + wasm, table row added, build matrix gains `cargo build -p relicario-server`, "Where to look next" points at server src + design spec.
 
 ---
 
@@ -34,7 +35,7 @@ The codebase itself is well-documented — `crates/{relicario-core,relicario-cli
 **Issue:** The `crates/` tree only lists `relicario-core/`, `relicario-cli/`, `relicario-wasm/`. `relicario-server/` is missing. Since CLAUDE.md is the project-level summary every Claude session reads, this is the highest-leverage staleness.
 **Fix:** Add a fourth crate entry for `relicario-server/` with `src/main.rs # pre-receive hook: verify_commit + generate_hook`.
 **Severity:** must-fix-before-v0.5.0
-**Status:** Proposed; needs user decision (CLAUDE.md is user-controlled per audit constraints)
+**Status:** Fixed in `8fd9a05` (PM follow-up, 2026-05-02 with user approval): added `relicario-server/` entry to project tree.
 
 ---
 
@@ -44,7 +45,7 @@ The codebase itself is well-documented — `crates/{relicario-core,relicario-cli
 **Issue:** Says `Next: WASM build + Chrome MV3 browser extension (Plan 2). Then mobile (Rust core compiles to ARM).` Plan 2 (extension) shipped, then Plans 1A-1C, 3A (backup), 3B (LastPass), Plan 4 (security fixes + device auth), and Phases 1-2B of the fullscreen UX redesign all shipped. The current "next thing" per project memory is v0.5.0 polish + harden plus Phase 3/4 of fullscreen UX.
 **Fix:** Replace with a current-state Roadmap line (e.g. `Next: v0.5.0 polish + harden, then Phase 3 (vault tab shell). Mobile (ARM) and recovery QR remain on the roadmap.`).
 **Severity:** must-fix-before-v0.5.0
-**Status:** Proposed; needs user decision (CLAUDE.md is user-controlled; phrasing is a judgment call)
+**Status:** Fixed in `8fd9a05` (PM follow-up, 2026-05-02 with user approval): replaced with the v0.5.0 / Phases 3-4 / 1C-γ / LastPass / mobile / recovery-QR picture.
 
 ---
 
@@ -54,7 +55,7 @@ The codebase itself is well-documented — `crates/{relicario-core,relicario-cli
 **Issue:** Audit M8 bumped `ItemId`/`FieldId` to 16-char hex (64 bits). Verified against `crates/relicario-core/src/ids.rs:3-4, 35-37` and `tests/integration` — they're 16 hex chars. The same line also doesn't mention that `AttachmentId` was bumped to 32 hex chars / 128 bits (audit I2/B4).
 **Fix:** Change to: `Item IDs and Field IDs are random 16-char hex strings (64 bits of OsRng entropy). AttachmentIds are content-addressed: first 32 hex chars of SHA-256(plaintext) (128 bits, audit I2/B4).`
 **Severity:** must-fix-before-v0.5.0
-**Status:** Proposed; needs user decision (CLAUDE.md is user-controlled)
+**Status:** Fixed in `8fd9a05` (PM follow-up, 2026-05-02 with user approval): now reads "Item IDs and Field IDs are random 16-char hex strings (64 bits of OsRng entropy). AttachmentIds are content-addressed: first 32 hex chars of SHA-256 over the plaintext (128 bits)."
 
 ---
 
@@ -114,7 +115,7 @@ The codebase itself is well-documented — `crates/{relicario-core,relicario-cli
 **Issue:** The vault-creation pipeline in this doc shows `master_key → XChaCha20-Poly1305 → manifest.enc` only. In reality `cmd_init` also encrypts and writes `settings.enc` (default `VaultSettings`). Field-history-tracked items, attachments, the `Item` envelope shape — none of these are in the flow doc. Without context on typed items, a new contributor reading this doc would have a v0.1-era model of the system.
 **Fix:** Add a settings.enc step to the flow; either expand the items section or note that the full item lifecycle is in `crates/relicario-core/ARCHITECTURE.md`.
 **Severity:** nice-to-have (the per-codebase ARCHITECTURE.md files are the source of truth; this top-level doc could just point at them)
-**Status:** Proposed; needs user decision (>50 words of new prose, design choice between rewriting vs trimming)
+**Status:** Fixed in `76d092d` (PM follow-up, 2026-05-02): trim path. Added settings.enc as a parallel artifact in the encrypt step, then a short paragraph pointing at `crates/relicario-core/ARCHITECTURE.md` for the per-item lifecycle.
 
 ---
 
@@ -124,7 +125,7 @@ The codebase itself is well-documented — `crates/{relicario-core,relicario-cli
 **Issue:** Says `Device registration was optional before v0.4.0. With device auth enabled, all commits must be signed by a registered device.` But (a) v0.4.0 hasn't been tagged yet — the changelog goes v0.1.0 → v0.2.0 → "Unreleased", and the next tag-in-flight per project memory is v0.5.0; (b) per the v0.5.0 polish + harden spec, device-auth enforcement is **currently a no-op** because the pre-receive hook fix (S1) hasn't landed. Saying "all commits MUST be signed" is aspirational, not current.
 **Fix:** Reword to clarify (a) the actual version line (e.g. "Pre-v0.5.0 vaults can opt out by leaving `devices.json` empty"), AND (b) acknowledge that signature *enforcement* depends on the pre-receive hook being deployed and the S1 fix landing. Could just be a one-line caveat.
 **Severity:** must-fix-before-v0.5.0 (security-doc accuracy is part of the legibility pitch)
-**Status:** Proposed; needs user decision (security wording — exact phrasing matters)
+**Status:** Fixed in `1342228` (PM follow-up, 2026-05-02 with user approval): dropped the "before v0.4.0" version line entirely (v0.4.0 was never tagged); replaced with a single line saying registration is optional but recommended for shared vaults. Enforcement story now lives in the Device Authentication section (see F12).
 
 ---
 
@@ -134,7 +135,7 @@ The codebase itself is well-documented — `crates/{relicario-core,relicario-cli
 **Issue:** The "Device Authentication" section refers to a "pre-receive hook" but never says it lives in `crates/relicario-server`, what binary the hook calls (`relicario-server verify-commit <sha>`), or how to install it (`relicario-server generate-hook`). For a self-hosted user reading this to decide whether to enable it, those are the two essential operational facts.
 **Fix:** Add a short paragraph naming the crate and the two subcommands, pointing to the design spec.
 **Severity:** nice-to-have
-**Status:** Proposed; needs user decision (>50 words of new prose)
+**Status:** Fixed in `1342228` (PM follow-up, 2026-05-02): added paragraph naming the `relicario-server` crate, both subcommands (`generate-hook`, `verify-commit`), and the caveat that signed commits without the server hook provide authorship metadata only.
 
 ---
 
@@ -144,7 +145,7 @@ The codebase itself is well-documented — `crates/{relicario-core,relicario-cli
 **Issue:** This doc is explicitly historical (per `docs/architecture/overview.md` "Stale spec docs" disclaimer), so editing it as architecture would violate convention. Still worth flagging that "Post-V1 Ideas" lists secure notes, secure documents, mobile, LastPass import, Firefox extension, TOTP — most of which have shipped. Per project policy this is *informational only*; the spec is a time-stamped decision artifact.
 **Fix:** None — leave alone. If desired, prepend a one-line "Status: V1 shipped 2026-04-22; many Post-V1 ideas have since landed — see CHANGELOG.md" at the top of the file.
 **Severity:** informational
-**Status:** Proposed; needs user decision (touches a historical spec the user may want to leave frozen)
+**Status:** Fixed in `9c97f9f` (PM follow-up, 2026-05-02): added the optional one-line status banner at the top of the spec pointing at CHANGELOG.md and overview.md for current state. Body of the spec untouched per the "specs are frozen decision artifacts" convention.
 
 ---
 
@@ -160,10 +161,18 @@ The codebase itself is well-documented — `crates/{relicario-core,relicario-cli
 
 ## Inline-fix verification
 
-Files modified during this audit:
+### Initial pass (commit `900ccf1`):
 
 - `README.md` — vault layout (`items/`, `settings.enc`, `attachments/`), crate tree (added `relicario-wasm`, `relicario-server`, typed-items modules), ID width, Roadmap.
 - `docs/ARCHITECTURE.md` — git-server box (`items/`, `settings.enc`, `attachments/`, `revoked.json`), crate-architecture inner box (current core modules), removed "Future: relicario-wasm" line.
 - `docs/architecture/overview.md` — conventions table (16-char hex IDs, 128-bit AttachmentIds).
 
-No source files, `Cargo.lock`, or extension code were modified. CLAUDE.md, SECURITY.md, and the foundational design spec were not modified — those changes need user review per the audit constraints.
+### v0.5.0 PM follow-up pass (commits `ca059e7`, `8fd9a05`, `1342228`, `76d092d`, `9c97f9f`):
+
+- `docs/architecture/overview.md` — F1: four-codebases framing, ASCII diagram fans out to server, table row, build matrix, "Where to look next".
+- `CLAUDE.md` — F2: project tree gains `relicario-server`. F3: Roadmap line replaced. F4: Item/Field/Attachment ID widths and entropy noted.
+- `docs/SECURITY.md` — F11: dropped `before v0.4.0` line. F12: Device Authentication section now names the `relicario-server` crate and its subcommands, with the "without the hook, commits are advisory" caveat.
+- `docs/ARCHITECTURE.md` — F10: settings.enc shown alongside manifest.enc in the Vault Creation Flow; pointer added to per-crate ARCHITECTURE.md for typed-items detail.
+- `docs/superpowers/specs/2026-04-11-relicario-design.md` — F13: optional one-line "historical spec" status banner at top.
+
+No source files, `Cargo.lock`, or extension code were modified at any point.

docs/superpowers/coordination/v0.5.1-pm-prompt.md

@@ -0,0 +1,165 @@
+# PM Kickoff Prompt — v0.5.1 UX Polish + Recovery QR
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are the **project manager** for the Relicario v0.5.1 release. Three senior developers report to you, each working in their own terminal on a parallel feature branch. The user runs all four terminals and relays messages between them.
+
+## Setup
+
+- Working directory: `/home/alee/Sources/relicario`
+- Branch: stay on `main`. Do not check out feature branches.
+- Today: 2026-05-03. Project rules in `CLAUDE.md` apply (Spanish flourish, capitalization, autonomy defaults, never run git-destructive commands without asking).
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/specs/2026-05-03-v0.5.x-ux-polish-and-recovery-qr-design.md` — full spec
+3. `docs/superpowers/coordination/v0.5.1-dev-a-prompt.md` — Dev A's plan (Stream A: fullscreen + popup layout)
+4. `docs/superpowers/coordination/v0.5.1-dev-b-prompt.md` — Dev B's plan (Stream B: settings UX)
+5. `docs/superpowers/coordination/v0.5.1-dev-c-prompt.md` — Dev C's plan (Stream C: recovery QR)
+
+## Your authority
+
+- Approve or deny scope changes from devs
+- Review and merge PRs from all three feature branches
+- **Drive the interface contract** between B and C (see below) — this is your first hands-on action
+- Write the `CHANGELOG.md` entry for v0.5.1
+- Tag `v0.5.1` once everything is integrated **— but only after explicit user approval**
+
+## Your boundaries
+
+- Don't write feature code yourself. Edits to docs / CHANGELOG / CLAUDE.md are fine.
+- Don't deviate from the spec without user approval.
+- Don't merge a PR until the dev says `REVIEW-READY` and you've run `gh pr diff` to confirm.
+- Don't tag without user approval.
+- Project rule: ask the user before any git-destructive op.
+
+## Stream overview
+
+| Stream | Branch | Owner | Core files |
+|--------|--------|-------|-----------|
+| A — Fullscreen + popup layout | `feature/v0.5.1-stream-a-layout` | DEV-A | `vault.ts`, `vault.css`, `item-list.ts`, `item-form.ts`, `glyphs.ts`, `toast.ts` |
+| B — Settings UX | `feature/v0.5.1-stream-b-settings` | DEV-B | `settings.ts`, `settings-vault.ts` (decomposed), `settings-security.ts` (stub only) |
+| C — Recovery QR | `feature/v0.5.1-stream-c-recovery-qr` | DEV-C | `recovery_qr.rs`, WASM `session.rs`/`lib.rs`, `settings-security.ts`, `setup.ts` |
+
+## Interface contracts (enforce before work starts)
+
+### A–B: Settings component signature
+
+DEV-B's settings component is wired into vault.ts by DEV-A. Both must agree before either proceeds with their vault.ts / settings.ts work.
+
+**Agreed interface** (post to both devs as your first directive):
+
+```ts
+// extension/src/popup/components/settings.ts
+
+/**
+ * Render the full sectioned settings view into `container`.
+ * May be called from vault.ts (fullscreen, full-width pane) or popup.ts (popup).
+ */
+export async function renderSettings(container: HTMLElement): Promise<void>;
+
+/**
+ * Teardown: close any open generator panel, remove keyboard listeners.
+ * Call before navigating away from the settings view.
+ */
+export function teardownSettings(): void;
+```
+
+DEV-A imports `{ renderSettings, teardownSettings }` from `settings.ts` in vault.ts.
+DEV-B exports these names with these exact signatures.
+
+### B–C: Security section component signature
+
+DEV-C owns and implements `settings-security.ts`. DEV-B imports it for the Security section. They must agree before DEV-B writes B4 (Security section) or DEV-C writes C8 (settings-security.ts).
+
+**Agreed interface** (post to both devs as your first directive):
+
+```ts
+// extension/src/popup/components/settings-security.ts
+
+/**
+ * Render the three-state Recovery QR + trusted devices security section
+ * into `container`. `sessionHandle` is the current WASM session handle value
+ * (from the service-worker's session), or null if the vault is locked.
+ */
+export async function renderSecuritySection(
+  container: HTMLElement,
+  sessionHandle: number | null,
+): Promise<void>;
+
+/**
+ * Teardown: remove any event listeners attached during render.
+ */
+export function teardownSecuritySection(): void;
+```
+
+DEV-B stubs this interface in `settings-security.ts` immediately after receiving this directive. DEV-C replaces it with the real implementation.
+
+## Merge order and strategy
+
+1. **C lands first** (or concurrently with A; no A or B dependency). Merge once DEV-C posts REVIEW-READY.
+2. **A and B can merge in either order** after C is on main, since both will rebase/merge main before PR.
+3. No squash merges — git history is preserved per project rule.
+4. No force pushes. Each dev opens a PR; PM reviews diff; PM merges with `gh pr merge --merge`.
+
+## Coordination protocol
+
+You are one of four terminals. The user relays messages.
+
+**You receive:** `## STATUS UPDATE — DEV-A/B/C` or `## QUESTION TO PM — DEV-X` blocks.
+
+**You emit:** a `## DIRECTIVE TO DEV-X` block. Format:
+
+```
+## DIRECTIVE TO DEV-A (or B or C)
+Time: <iso8601>
+Action: PROCEED | HOLD | RESCOPE | REVIEW-COMPLETE | MERGE-APPROVED
+Notes: <one paragraph max>
+Next: <one concrete instruction or "continue plan">
+```
+
+When asked "status?" by the user at any time:
+
+```
+## RELEASE STATUS — v0.5.1
+Dev A: <task X of Y, status>
+Dev B: <task X of Y, status>
+Dev C: <task X of Y, status>
+PM: <current action>
+Blockers: <list, or "none">
+Next milestone: <e.g., "Dev C REVIEW-READY", "all three merged">
+```
+
+## Reviewing PRs
+
+When a dev posts `Action: REVIEW-READY` with a PR URL:
+1. `gh pr view <url>` to read description and CI status
+2. `gh pr diff <url>` to read changes
+3. Check diff against the spec sections owned by that stream
+4. If green: post `Action: MERGE-APPROVED` and run `gh pr merge --merge`
+5. If red: post `Action: HOLD` with specific concerns
+
+## Pre-tag checklist
+
+Before tagging v0.5.1:
+
+- [ ] `feature/v0.5.1-stream-a-layout` merged to main
+- [ ] `feature/v0.5.1-stream-b-settings` merged to main
+- [ ] `feature/v0.5.1-stream-c-recovery-qr` merged to main
+- [ ] `cargo test` green on main
+- [ ] `bun run test` green (extension)
+- [ ] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` green
+- [ ] `bun run build` + `bun run build:firefox` clean (extension)
+- [ ] No emoji in any UI surface (grep: `'🔑\|📝\|🪪\|💳\|🗝\|📄\|⏱️'` in `extension/src/`)
+- [ ] `GLYPH_VAULT_TAB` in glyphs.ts; no inline `&#x2934;` anywhere
+- [ ] `recovery_qr_generated_at` is the only persisted QR artifact (grep: no QR SVG in chrome.storage calls)
+- [ ] Settings left-nav sections all render without console errors
+- [ ] `CHANGELOG.md` entry for v0.5.1 written
+- [ ] Explicit user approval to tag
+
+## First action
+
+After reading: post a `## RELEASE STATUS — v0.5.1` block, then post your first directive to all three devs simultaneously — confirming the A–B and B–C interface contracts above. Wait for devs to acknowledge before instructing them to proceed with their task lists.

docs/superpowers/plans/2026-05-02-relay-server.md

@@ -0,0 +1,956 @@
+# Relay Server Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a local MCP SSE server that gives PM, Dev-A, and Dev-B Claude Code sessions native `post_message`/`read_messages`/`list_pending` tools, eliminating manual copy-paste during multi-agent development lifts.
+
+**Architecture:** A single Node.js process hosts an HTTP server with SSE transport for the MCP protocol. Three named in-memory FIFO queues (one per role) hold consume-once messages. A `start.sh` launcher prints copy-paste instructions (default) or spawns a tmux/kitty layout (flags). The multi-agent-kickoff skill templates get a `<<RELAY_PARAGRAPH>>` placeholder injected so every future lift prompt auto-includes relay instructions.
+
+**Tech Stack:** Node.js v25, `@modelcontextprotocol/sdk` (MCP + SSE transport), `tsx` (dev dep, runs TypeScript directly), Node built-in `node:test` runner. No Express, no Hono, no Zod as a direct dep.
+
+---
+
+## File map
+
+| Action | Path | Responsibility |
+|--------|------|----------------|
+| Create | `tools/relay/package.json` | npm metadata, scripts, single runtime dep + tsx devDep |
+| Create | `tools/relay/tsconfig.json` | TypeScript config for ESM Node target |
+| Create | `tools/relay/queue.ts` | `RelayQueue` class — in-memory FIFO, `post`/`read`/`pending`, `isRole` guard |
+| Create | `tools/relay/queue.test.ts` | Node `node:test` unit tests for queue (5 cases) |
+| Create | `tools/relay/server.ts` | MCP `Server` + `SSEServerTransport` HTTP server on port 7331 |
+| Create | `tools/relay/start.sh` | Launcher: `--manual` (default), `--tmux`, `--kitty` |
+| Modify | `.gitignore` | Add `tools/relay/node_modules/` |
+| Modify | `.claude/settings.json` | Add `mcpServers.relay` SSE entry |
+| Create | `docs/superpowers/MULTI-AGENT.md` | Paradigm reference README |
+| Modify | `~/.claude/skills/multi-agent-kickoff/templates/pm-prompt.md` | Add `<<RELAY_PARAGRAPH>>` section |
+| Modify | `~/.claude/skills/multi-agent-kickoff/templates/dev-prompt.md` | Add `<<RELAY_PARAGRAPH>>` section |
+| Modify | `~/.claude/skills/multi-agent-kickoff/SKILL.md` | Placeholder ref + step 8 update + `<<DEV_ROLE>>` placeholder |
+
+---
+
+## Task 1: Scaffold `tools/relay/`
+
+**Files:**
+- Create: `tools/relay/package.json`
+- Create: `tools/relay/tsconfig.json`
+- Modify: `.gitignore`
+
+- [ ] **Step 1: Create `tools/relay/package.json`**
+
+```json
+{
+  "name": "@relicario/relay",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "npx tsx server.ts",
+    "test": "node --import=tsx/esm --test queue.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "@types/node": "^22.0.0"
+  }
+}
+```
+
+- [ ] **Step 2: Create `tools/relay/tsconfig.json`**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true
+  },
+  "include": ["*.ts"]
+}
+```
+
+- [ ] **Step 3: Add to root `.gitignore`**
+
+Open `/home/alee/Sources/relicario/.gitignore` and append:
+
+```
+tools/relay/node_modules/
+```
+
+- [ ] **Step 4: Install dependencies and verify**
+
+```bash
+cd tools/relay && npm install
+```
+
+Expected: `node_modules/` created, no errors. Verify with:
+
+```bash
+ls node_modules/@modelcontextprotocol/sdk && ls node_modules/tsx
+```
+
+Expected: both directories exist.
+
+- [ ] **Step 5: Commit scaffold**
+
+```bash
+git add tools/relay/package.json tools/relay/tsconfig.json tools/relay/package-lock.json .gitignore
+git commit -m "chore(relay): scaffold tools/relay with MCP SDK dep"
+```
+
+---
+
+## Task 2: `queue.ts` — TDD
+
+**Files:**
+- Create: `tools/relay/queue.ts`
+- Create: `tools/relay/queue.test.ts`
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `tools/relay/queue.test.ts`:
+
+```typescript
+import { describe, it, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { RelayQueue, isRole } from "./queue.ts";
+
+describe("RelayQueue", () => {
+  let q: RelayQueue;
+
+  beforeEach(() => {
+    q = new RelayQueue();
+  });
+
+  it("post + read roundtrip returns the message with correct fields", () => {
+    q.post("dev-b", "pm", "status", "Task P4 DONE");
+    const msgs = q.read("pm");
+    assert.equal(msgs.length, 1);
+    assert.equal(msgs[0].from, "dev-b");
+    assert.equal(msgs[0].to, "pm");
+    assert.equal(msgs[0].kind, "status");
+    assert.equal(msgs[0].body, "Task P4 DONE");
+    assert.ok(typeof msgs[0].id === "string" && msgs[0].id.length > 0);
+    assert.ok(typeof msgs[0].ts === "string");
+  });
+
+  it("consume-once: second read returns empty", () => {
+    q.post("dev-a", "pm", "question", "Should I use approach A?");
+    q.read("pm");
+    const second = q.read("pm");
+    assert.deepEqual(second, []);
+  });
+
+  it("list_pending does not drain inbox", () => {
+    q.post("dev-b", "pm", "directive", "PROCEED");
+    const before = q.pending("pm");
+    assert.equal(before.count, 1);
+    const after = q.read("pm");
+    assert.equal(after.length, 1);
+  });
+
+  it("FIFO ordering across multiple senders", () => {
+    q.post("dev-a", "pm", "status", "first");
+    q.post("dev-b", "pm", "status", "second");
+    q.post("dev-a", "pm", "question", "third");
+    const msgs = q.read("pm");
+    assert.equal(msgs.length, 3);
+    assert.equal(msgs[0].body, "first");
+    assert.equal(msgs[1].body, "second");
+    assert.equal(msgs[2].body, "third");
+  });
+
+  it("isRole rejects unknown strings", () => {
+    assert.ok(isRole("pm"));
+    assert.ok(isRole("dev-a"));
+    assert.ok(isRole("dev-b"));
+    assert.ok(!isRole("dev-c"));
+    assert.ok(!isRole(""));
+    assert.ok(!isRole("PM"));
+  });
+});
+```
+
+- [ ] **Step 2: Run tests to confirm they fail**
+
+```bash
+cd tools/relay && node --import=tsx/esm --test queue.test.ts
+```
+
+Expected: fails with `Cannot find module './queue.ts'` or similar. If it fails with a different error, investigate before continuing.
+
+- [ ] **Step 3: Write `queue.ts`**
+
+Create `tools/relay/queue.ts`:
+
+```typescript
+import { randomUUID } from "node:crypto";
+
+export type Role = "pm" | "dev-a" | "dev-b";
+export type MessageKind = "status" | "question" | "directive" | "free";
+
+export interface RelayMessage {
+  id: string;
+  from: Role;
+  to: Role;
+  kind: MessageKind;
+  body: string;
+  ts: string;
+}
+
+const KNOWN_ROLES = new Set<string>(["pm", "dev-a", "dev-b"]);
+
+export function isRole(s: string): s is Role {
+  return KNOWN_ROLES.has(s);
+}
+
+export class RelayQueue {
+  private readonly queues = new Map<Role, RelayMessage[]>([
+    ["pm", []],
+    ["dev-a", []],
+    ["dev-b", []],
+  ]);
+
+  post(from: Role, to: Role, kind: MessageKind, body: string): RelayMessage {
+    const msg: RelayMessage = {
+      id: randomUUID(),
+      from,
+      to,
+      kind,
+      body,
+      ts: new Date().toISOString(),
+    };
+    this.queues.get(to)!.push(msg);
+    return msg;
+  }
+
+  read(forRole: Role): RelayMessage[] {
+    const inbox = this.queues.get(forRole)!;
+    const messages = [...inbox];
+    inbox.length = 0;
+    return messages;
+  }
+
+  pending(forRole: Role): { count: number; kinds: MessageKind[] } {
+    const inbox = this.queues.get(forRole)!;
+    return {
+      count: inbox.length,
+      kinds: inbox.map((m) => m.kind),
+    };
+  }
+}
+```
+
+- [ ] **Step 4: Run tests to confirm they pass**
+
+```bash
+cd tools/relay && node --import=tsx/esm --test queue.test.ts
+```
+
+Expected output (all 5 passing):
+```
+▶ RelayQueue
+  ✔ post + read roundtrip returns the message with correct fields
+  ✔ consume-once: second read returns empty
+  ✔ list_pending does not drain inbox
+  ✔ FIFO ordering across multiple senders
+  ✔ isRole rejects unknown strings
+▶ RelayQueue (Xms)
+ℹ tests 5
+ℹ pass 5
+ℹ fail 0
+```
+
+If any test fails, fix `queue.ts` before proceeding.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tools/relay/queue.ts tools/relay/queue.test.ts
+git commit -m "feat(relay): in-memory queue with consume-once semantics"
+```
+
+---
+
+## Task 3: `server.ts`
+
+**Files:**
+- Create: `tools/relay/server.ts`
+
+- [ ] **Step 1: Write `server.ts`**
+
+Create `tools/relay/server.ts`:
+
+```typescript
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import http from "node:http";
+import { RelayQueue, isRole } from "./queue.ts";
+
+const PORT = 7331;
+const queue = new RelayQueue();
+
+const mcpServer = new Server(
+  { name: "relay", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+const TOOLS = [
+  {
+    name: "post_message",
+    description:
+      "Push a message to a recipient's inbox. Returns the assigned message id.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        from: {
+          type: "string",
+          enum: ["pm", "dev-a", "dev-b"],
+          description: "Your role name",
+        },
+        to: {
+          type: "string",
+          enum: ["pm", "dev-a", "dev-b"],
+          description: "Recipient role name",
+        },
+        kind: {
+          type: "string",
+          enum: ["status", "question", "directive", "free"],
+          description: "Message type matching the coordination protocol",
+        },
+        body: {
+          type: "string",
+          description: "Message body — freeform markdown, typically the full formatted block",
+        },
+      },
+      required: ["from", "to", "kind", "body"],
+    },
+  },
+  {
+    name: "read_messages",
+    description:
+      "Pop and return all pending messages for this recipient. Inbox is empty after this call (consume-once).",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        for: {
+          type: "string",
+          enum: ["pm", "dev-a", "dev-b"],
+          description: "Your role name",
+        },
+      },
+      required: ["for"],
+    },
+  },
+  {
+    name: "list_pending",
+    description:
+      "Return count and kinds of pending messages without consuming them.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        for: {
+          type: "string",
+          enum: ["pm", "dev-a", "dev-b"],
+          description: "Your role name",
+        },
+      },
+      required: ["for"],
+    },
+  },
+];
+
+mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const a = args as Record<string, string>;
+
+  if (name === "post_message") {
+    if (!isRole(a.from)) {
+      return { content: [{ type: "text" as const, text: `Error: unknown role "${a.from}"` }], isError: true };
+    }
+    if (!isRole(a.to)) {
+      return { content: [{ type: "text" as const, text: `Error: unknown role "${a.to}"` }], isError: true };
+    }
+    const kind = a.kind as "status" | "question" | "directive" | "free";
+    const msg = queue.post(a.from, a.to, kind, a.body);
+    const ts = new Date(msg.ts).toTimeString().slice(0, 8);
+    const preview = a.body.slice(0, 60).replace(/\n/g, " ");
+    const ellipsis = a.body.length > 60 ? "..." : "";
+    process.stdout.write(`[${ts}] ${a.from} → ${a.to}  [${kind}]  "${preview}${ellipsis}"\n`);
+    return { content: [{ type: "text" as const, text: JSON.stringify({ id: msg.id }) }] };
+  }
+
+  if (name === "read_messages") {
+    if (!isRole(a.for)) {
+      return { content: [{ type: "text" as const, text: `Error: unknown role "${a.for}"` }], isError: true };
+    }
+    const messages = queue.read(a.for);
+    return { content: [{ type: "text" as const, text: JSON.stringify(messages) }] };
+  }
+
+  if (name === "list_pending") {
+    if (!isRole(a.for)) {
+      return { content: [{ type: "text" as const, text: `Error: unknown role "${a.for}"` }], isError: true };
+    }
+    const result = queue.pending(a.for);
+    return { content: [{ type: "text" as const, text: JSON.stringify(result) }] };
+  }
+
+  return {
+    content: [{ type: "text" as const, text: `Error: unknown tool "${name}"` }],
+    isError: true,
+  };
+});
+
+const transports = new Map<string, SSEServerTransport>();
+
+const httpServer = http.createServer(async (req, res) => {
+  try {
+    if (req.method === "GET" && req.url === "/sse") {
+      const transport = new SSEServerTransport("/message", res);
+      transports.set(transport.sessionId, transport);
+      transport.onclose = () => transports.delete(transport.sessionId);
+      await mcpServer.connect(transport);
+    } else if (req.method === "POST" && req.url?.startsWith("/message")) {
+      const url = new URL(req.url, `http://127.0.0.1:${PORT}`);
+      const sessionId = url.searchParams.get("sessionId") ?? "";
+      const transport = transports.get(sessionId);
+      if (transport) {
+        await transport.handlePostMessage(req, res);
+      } else {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "session not found" }));
+      }
+    } else {
+      res.writeHead(404).end("not found");
+    }
+  } catch (err) {
+    console.error("[relay] error:", err);
+    if (!res.headersSent) res.writeHead(500).end(String(err));
+  }
+});
+
+httpServer.listen(PORT, "127.0.0.1", () => {
+  console.log(`[relay] server ready on :${PORT}`);
+  console.log(`[relay] tools: post_message, read_messages, list_pending`);
+  console.log(`[relay] waiting for connections — Ctrl-C to stop`);
+});
+```
+
+- [ ] **Step 2: Smoke-test server startup**
+
+In one terminal:
+```bash
+cd tools/relay && npx tsx server.ts
+```
+
+Expected output:
+```
+[relay] server ready on :7331
+[relay] tools: post_message, read_messages, list_pending
+[relay] waiting for connections — Ctrl-C to stop
+```
+
+In a second terminal, verify the port is listening:
+```bash
+curl -s --max-time 2 http://127.0.0.1:7331/sse | head -3
+```
+
+Expected: SSE `data:` stream begins (it won't complete — the connection stays open). Ctrl-C both.
+
+If the server errors on startup, check that `@modelcontextprotocol/sdk` is installed and review any TypeScript errors by running `npx tsc --noEmit` in `tools/relay/`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tools/relay/server.ts
+git commit -m "feat(relay): MCP SSE server with post_message/read_messages/list_pending"
+```
+
+---
+
+## Task 4: `start.sh`
+
+**Files:**
+- Create: `tools/relay/start.sh`
+
+- [ ] **Step 1: Write `start.sh`**
+
+Create `tools/relay/start.sh`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel)"
+PORT=7331
+MODE="manual"
+
+for arg in "$@"; do
+  case "$arg" in
+    --tmux)   MODE="tmux"   ;;
+    --kitty)  MODE="kitty"  ;;
+    --manual) MODE="manual" ;;
+    *) echo "Unknown option: $arg" >&2; echo "Usage: $0 [--manual|--tmux|--kitty]" >&2; exit 1 ;;
+  esac
+done
+
+# Port check
+if lsof -ti:"$PORT" &>/dev/null; then
+  echo "Error: port $PORT is already in use."
+  echo "Relay already running? Kill it with: kill \$(lsof -ti:$PORT)"
+  exit 1
+fi
+
+# Install deps (no-op if node_modules current)
+cd "$SCRIPT_DIR"
+npm install --silent
+
+# Discover latest coordination prompts for instructions
+COORD_DIR="$REPO_ROOT/docs/superpowers/coordination"
+PM_PROMPT="$(ls -t "$COORD_DIR"/*-pm-prompt.md 2>/dev/null | head -1 || echo "(none found — run multi-agent-kickoff skill first)")"
+DEV_A_PROMPT="$(ls -t "$COORD_DIR"/*-dev-a-prompt.md 2>/dev/null | head -1 || echo "(none found)")"
+DEV_B_PROMPT="$(ls -t "$COORD_DIR"/*-dev-b-prompt.md 2>/dev/null | head -1 || echo "(none found)")"
+
+print_manual_instructions() {
+  echo ""
+  echo "╔══════════════════════════════════════════════════════════════╗"
+  echo "║          RELAY SERVER — MULTI-AGENT LIFT LAUNCHER            ║"
+  echo "╚══════════════════════════════════════════════════════════════╝"
+  echo ""
+  echo "Open 3 new terminals. In each, start Claude Code and paste"
+  echo "the content BELOW the '---' line from the corresponding file."
+  echo ""
+  echo "  Terminal 1 (PM):    cat '$PM_PROMPT'"
+  echo "  Terminal 2 (Dev A): cat '$DEV_A_PROMPT'"
+  echo "  Terminal 3 (Dev B): cat '$DEV_B_PROMPT'"
+  echo ""
+  echo "This terminal becomes the relay log. Keep it open."
+  echo ""
+  echo "══════════════════════════════════════════════════════════════"
+}
+
+launch_tmux() {
+  SESSION="relay-lift"
+  tmux new-session -d -s "$SESSION" -n "relay" \
+    "cd '$SCRIPT_DIR' && npx tsx server.ts"
+  tmux new-window -t "$SESSION:" -n "pm" "cd '$REPO_ROOT' && claude"
+  tmux new-window -t "$SESSION:" -n "dev-a" "cd '$REPO_ROOT' && claude"
+  tmux new-window -t "$SESSION:" -n "dev-b" "cd '$REPO_ROOT' && claude"
+  echo ""
+  echo "[relay] Opened tmux session '$SESSION' with 4 windows: relay, pm, dev-a, dev-b."
+  echo "[relay] Paste the kickoff prompt into each Claude window."
+  echo "        Prompts:"
+  echo "          PM:    $PM_PROMPT"
+  echo "          Dev A: $DEV_A_PROMPT"
+  echo "          Dev B: $DEV_B_PROMPT"
+  echo ""
+  tmux attach-session -t "$SESSION"
+}
+
+launch_kitty() {
+  kitty @ launch --new-tab --tab-title "relay" -- \
+    bash -c "cd '$SCRIPT_DIR' && npx tsx server.ts"
+  kitty @ launch --new-window --window-title "PM" -- \
+    bash -c "cd '$REPO_ROOT' && claude"
+  kitty @ launch --new-window --window-title "Dev-A" -- \
+    bash -c "cd '$REPO_ROOT' && claude"
+  kitty @ launch --new-window --window-title "Dev-B" -- \
+    bash -c "cd '$REPO_ROOT' && claude"
+  echo ""
+  echo "[relay] Opened kitty tab 'relay' + 3 windows (PM, Dev-A, Dev-B)."
+  echo "        Paste the kickoff prompts into each Claude window."
+  echo "          PM:    $PM_PROMPT"
+  echo "          Dev A: $DEV_A_PROMPT"
+  echo "          Dev B: $DEV_B_PROMPT"
+}
+
+case "$MODE" in
+  manual)
+    print_manual_instructions
+    exec npx tsx "$SCRIPT_DIR/server.ts"
+    ;;
+  tmux)
+    launch_tmux
+    ;;
+  kitty)
+    launch_kitty
+    ;;
+esac
+```
+
+- [ ] **Step 2: Make executable**
+
+```bash
+chmod +x tools/relay/start.sh
+```
+
+- [ ] **Step 3: Smoke-test `--manual` mode**
+
+```bash
+cd /home/alee/Sources/relicario && tools/relay/start.sh
+```
+
+Expected: prints the launch box with prompt paths, then server starts and shows `[relay] server ready on :7331`. Ctrl-C to stop.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tools/relay/start.sh
+git commit -m "feat(relay): start.sh launcher with --manual/--tmux/--kitty modes"
+```
+
+---
+
+## Task 5: Claude Code MCP configuration
+
+**Files:**
+- Modify: `.claude/settings.json`
+
+- [ ] **Step 1: Read current `.claude/settings.json`**
+
+```bash
+cat .claude/settings.json
+```
+
+- [ ] **Step 2: Add the relay MCP server entry**
+
+The file currently has `{ "enabledPlugins": { ... } }`. Add `"mcpServers"` at the top level:
+
+```json
+{
+  "mcpServers": {
+    "relay": {
+      "type": "sse",
+      "url": "http://localhost:7331/sse"
+    }
+  },
+  "enabledPlugins": {
+    "superpowers@claude-plugins-official": true
+  }
+}
+```
+
+Preserve whatever is already in `enabledPlugins` — only add the `mcpServers` key.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add .claude/settings.json
+git commit -m "chore(relay): add relay MCP server to project Claude config"
+```
+
+---
+
+## Task 6: `docs/superpowers/MULTI-AGENT.md`
+
+**Files:**
+- Create: `docs/superpowers/MULTI-AGENT.md`
+
+- [ ] **Step 1: Write the paradigm README**
+
+Create `docs/superpowers/MULTI-AGENT.md`:
+
+```markdown
+# Multi-Agent Development Paradigm
+
+This repo uses a three-terminal workflow for large development lifts: one Claude Code session acts as **PM** and two act as **senior developers** (Dev-A, Dev-B), each working in their own git worktree on a parallel feature branch.
+
+A local relay MCP server eliminates manual message copying between terminals — agents call `post_message`/`read_messages` instead of asking the user to copy-paste.
+
+---
+
+## Overview
+
+| Role | Terminal | Branch | Responsibilities |
+|------|----------|--------|-----------------|
+| PM | 1 | `main` (read-only) | Drive doc-audit follow-ups, review PRs, write CHANGELOG, authorize merges and tagging |
+| Dev-A | 2 | `feature/<release>-plan-a-*` | Implement Plan A tasks in their own worktree |
+| Dev-B | 3 | `feature/<release>-plan-b-*` | Implement Plan B tasks in their own worktree |
+| Relay server | 4 | — | Message bus; Ctrl-C to stop at end of lift |
+
+**User's job:** authorize merges (the PM asks), resolve escalations the PM can't handle, and watch the streams. You are no longer the message bus.
+
+---
+
+## Starting a lift
+
+### Prerequisites
+
+- [ ] Kickoff prompts exist in `docs/superpowers/coordination/` (generate with the `multi-agent-kickoff` skill if not)
+- [ ] No uncommitted changes in main that would confuse the devs
+- [ ] `tools/relay/` is present (run `ls tools/relay/` to confirm)
+
+### Launch sequence
+
+```bash
+# 1. Start the relay server (this terminal becomes the relay log)
+tools/relay/start.sh           # prints copy-paste instructions, then starts server
+
+# Optional: use a multiplexer to auto-open all four terminals
+tools/relay/start.sh --tmux    # creates tmux session "relay-lift" with 4 windows
+tools/relay/start.sh --kitty   # creates kitty tab "relay" + 3 windows
+```
+
+`start.sh` prints the paths to the three kickoff prompt files. In each Claude Code terminal, run `cat <path>` and paste everything below the `---` line as the first message.
+
+---
+
+## Coordination protocol
+
+Agents communicate by posting structured blocks to each other's inboxes. Four message kinds:
+
+| Kind | Block header | When used |
+|------|-------------|-----------|
+| `status` | `## STATUS UPDATE — DEV-*` | After completing a task, getting blocked, or reaching a review-ready state |
+| `question` | `## QUESTION TO PM — DEV-*` | When a dev needs PM input mid-task |
+| `directive` | `## DIRECTIVE TO DEV-*` | When PM instructs a dev to proceed, hold, rescope, or approve a PR |
+| `free` | (none) | Ad-hoc messages not covered by the above |
+
+A well-formed `status` block:
+
+```
+## STATUS UPDATE — DEV-B
+Time: 2026-05-02T14:30:00-07:00
+Branch: feature/v0.5.0-plan-b-extension-ux
+Task: P4 / error-copy map
+Status: DONE
+Last commit: abc1234 feat(extension): centralize ERROR_COPY map
+Tests: green
+Notes: No issues. Ready for PM review of P4 before starting B1.
+```
+
+---
+
+## Using the relay tools
+
+All three Claude Code sessions have these tools available when the relay server is running:
+
+```
+post_message(from, to, kind, body)   → { id }
+read_messages(for)                   → RelayMessage[]   (drains inbox)
+list_pending(for)                    → { count, kinds } (non-destructive)
+```
+
+Typical dev flow per task:
+
+```
+1. read_messages(for="dev-b")           # check for directives before starting
+2. ... do the work ...
+3. post_message(from="dev-b", to="pm", kind="status", body="## STATUS UPDATE...")
+```
+
+Typical PM flow:
+
+```
+1. read_messages(for="pm")             # see what devs posted
+2. ... review ...
+3. post_message(from="pm", to="dev-b", kind="directive", body="## DIRECTIVE TO DEV-B...")
+```
+
+---
+
+## If the relay server isn't running
+
+Claude Code will show a yellow MCP connection warning for the `relay` server. The tools will be unavailable.
+
+Agents fall back to the manual protocol: they emit the structured blocks as text and ask the user to copy-paste them to the relevant terminal. This is slower but fully functional — the coordination protocol works either way.
+
+To restart a crashed server mid-lift:
+
+```bash
+tools/relay/start.sh
+```
+
+In-flight messages are lost on restart. Any agent with unread messages should re-post them.
+
+---
+
+## Generating kickoff prompts
+
+Use the `multi-agent-kickoff` skill (in the `superpowers` plugin). It auto-discovers the spec and plans for the release, substitutes all placeholders including the relay paragraph, and writes files to `docs/superpowers/coordination/`.
+
+The skill reminder: run `tools/relay/start.sh` **before** opening the three Claude Code sessions — the MCP tools need the server to be up when each session initializes.
+
+---
+
+## Ending a lift
+
+1. PM emits `REVIEW-COMPLETE` and `MERGE-APPROVED` for each dev's PR
+2. User merges each PR (the PM session does `gh pr merge` with user authorization)
+3. PM tags the release (only after explicit user `yes`)
+4. Ctrl-C the relay terminal — all in-memory messages are discarded
+
+---
+
+## Roles and boundaries (quick reference)
+
+**PM must not:** write feature code, merge without user authorization, tag without user approval, run `git push --force` / `git reset --hard` without asking.
+
+**Devs must not:** merge their branch to main, push `--force`, run `git reset --hard` without asking.
+
+**User must:** authorize all merges and the release tag. Everything else is delegated.
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/superpowers/MULTI-AGENT.md
+git commit -m "docs: add multi-agent development paradigm README"
+```
+
+---
+
+## Task 7: Update `multi-agent-kickoff` skill
+
+**Files:**
+- Modify: `~/.claude/skills/multi-agent-kickoff/templates/pm-prompt.md`
+- Modify: `~/.claude/skills/multi-agent-kickoff/templates/dev-prompt.md`
+- Modify: `~/.claude/skills/multi-agent-kickoff/SKILL.md`
+
+- [ ] **Step 1: Read current templates**
+
+```bash
+cat ~/.claude/skills/multi-agent-kickoff/templates/pm-prompt.md
+cat ~/.claude/skills/multi-agent-kickoff/templates/dev-prompt.md
+```
+
+Note where the "Setup" section ends in each template. The relay paragraph goes right after it (before "Required reading").
+
+- [ ] **Step 2: Add `<<RELAY_PARAGRAPH>>` to `pm-prompt.md`**
+
+In `~/.claude/skills/multi-agent-kickoff/templates/pm-prompt.md`, find the "## Setup" section and add the placeholder block immediately after it (before the "## Required reading" heading):
+
+```markdown
+<<RELAY_PARAGRAPH>>
+```
+
+The generated output for this placeholder (substituted by the skill at generation time) is:
+
+```markdown
+## Relay server
+
+A message-bus MCP server is running on `localhost:7331`. You have three native tools:
+
+- `post_message(from, to, kind, body)` — push a message; `from` is always `"pm"` for you
+- `read_messages(for)` — drain your inbox; call with `for="pm"` before each action
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm`, `dev-a`, `dev-b`. Use these instead of asking the user to copy-paste. After sending any directive, call `post_message(from="pm", to="dev-a", kind="directive", body="...")`.
+```
+
+- [ ] **Step 3: Add `<<RELAY_PARAGRAPH>>` to `dev-prompt.md`**
+
+In `~/.claude/skills/multi-agent-kickoff/templates/dev-prompt.md`, find the "## Setup" section and add immediately after it (before "## Required reading"):
+
+```markdown
+<<RELAY_PARAGRAPH>>
+```
+
+The generated output for this placeholder is role-specific (uses `<<DEV_ROLE>>`):
+
+```markdown
+## Relay server
+
+A message-bus MCP server is running on `localhost:7331`. You have three native tools:
+
+- `post_message(from, to, kind, body)` — push a message; your `from` is always `"<<DEV_ROLE>>"`
+- `read_messages(for)` — drain your inbox; call with `for="<<DEV_ROLE>>"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm`, `dev-a`, `dev-b`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="<<DEV_ROLE>>")`. After emitting any status/question block: `post_message(from="<<DEV_ROLE>>", to="pm", kind="status"|"question", body="...")`.
+```
+
+- [ ] **Step 4: Update `SKILL.md` — add two entries to the placeholder reference table**
+
+In `~/.claude/skills/multi-agent-kickoff/SKILL.md`, find the "### Common to all prompts" section of the Placeholder reference and add:
+
+```markdown
+- `<<RELAY_PARAGRAPH>>` — the relay server instruction block (substituted from the template above). For the PM prompt, `from` is hardcoded to `"pm"`. For dev prompts, uses `<<DEV_ROLE>>`.
+```
+
+In the "### Per-dev" section, add:
+
+```markdown
+- `<<DEV_ROLE>>` — lowercase relay role name, e.g. `dev-a`, `dev-b`. Derived from `<<DEV_LETTER>>` by lowercasing and prepending `dev-`. Set when `<<DEV_LETTER>>` is set.
+```
+
+- [ ] **Step 5: Update `SKILL.md` — step 8 (kickoff instructions)**
+
+Find step 8 in the Process section ("Print kickoff instructions") and prepend a bullet:
+
+```markdown
+8. **Print kickoff instructions.** Tell the user exactly what to do:
+   - **Start the relay server first:** `tools/relay/start.sh` (or `--tmux`/`--kitty` for auto-layout). The server must be running before the sessions open so the MCP tools initialize correctly.
+   - Open three terminal windows (or panes — their choice of multiplexer)
+   ...rest of existing bullets unchanged...
+```
+
+Also update the "After generation" section — change bullet 4 ("From that point on, they're the message bus...") to:
+
+```markdown
+4. The relay server handles message routing — agents call `post_message`/`read_messages` directly. The user only needs to step in for escalations the PM can't resolve, or if the relay server is down (manual fallback: copy-paste the block to the relevant terminal as before)
+```
+
+- [ ] **Step 6: Commit skill changes**
+
+The skill files live outside the git repo, so no git commit needed. Verify the changes look right:
+
+```bash
+grep -n "RELAY_PARAGRAPH\|DEV_ROLE\|relay server" ~/.claude/skills/multi-agent-kickoff/SKILL.md | head -10
+grep -n "RELAY_PARAGRAPH" ~/.claude/skills/multi-agent-kickoff/templates/pm-prompt.md
+grep -n "RELAY_PARAGRAPH" ~/.claude/skills/multi-agent-kickoff/templates/dev-prompt.md
+```
+
+Expected: each grep returns at least one match.
+
+---
+
+## Final verification
+
+- [ ] **Run queue tests one more time from repo root**
+
+```bash
+cd tools/relay && node --import=tsx/esm --test queue.test.ts
+```
+
+Expected: 5 passing, 0 failing.
+
+- [ ] **Start server and verify it binds**
+
+```bash
+tools/relay/start.sh &
+sleep 1
+curl -s --max-time 1 http://127.0.0.1:7331/sse | head -1 || true
+kill %1
+```
+
+Expected: `data:` line appears (SSE stream started), then server killed cleanly.
+
+- [ ] **Verify MCP config is present**
+
+```bash
+python3 -c "import json; d=json.load(open('.claude/settings.json')); print(d['mcpServers']['relay'])"
+```
+
+Expected: `{'type': 'sse', 'url': 'http://localhost:7331/sse'}`
+
+- [ ] **Verify skill placeholders were added**
+
+```bash
+grep "RELAY_PARAGRAPH" ~/.claude/skills/multi-agent-kickoff/templates/pm-prompt.md \
+                       ~/.claude/skills/multi-agent-kickoff/templates/dev-prompt.md
+```
+
+Expected: one match per file.

docs/superpowers/specs/2026-04-11-relicario-design.md

@@ -1,5 +1,7 @@
 # Relicario — Design Specification
 
+> **Status:** historical. V1 shipped 2026-04-22; several "Post-V1 Ideas" listed below (typed items, attachments, secure documents, TOTP, Firefox extension, LastPass import, device authentication) have since shipped. See `CHANGELOG.md` and `docs/architecture/overview.md` for current state. Do not edit this spec as if it were architecture documentation — it is a time-stamped decision artifact.
+
 A git-backed, self-hostable password manager with a Rust core, CLI, and Chrome browser extension. The reference image as a DCT-embedded secret carrier is the core differentiator.
 
 ## Overview

docs/superpowers/specs/2026-05-02-relay-server-design.md

@@ -0,0 +1,218 @@
+# Relay Server Design
+
+**Date:** 2026-05-02  
+**Status:** Approved  
+**Scope:** Dev tooling — not shipped in any product artifact
+
+---
+
+## Problem
+
+Multi-agent development lifts (PM + Dev-A + Dev-B in parallel Claude Code sessions) require passing status updates, questions, and directives between terminals. Today the user manually copies and pastes every message block. This is error-prone, breaks flow, and scales poorly as lift complexity grows.
+
+## Goal
+
+A lightweight MCP server running on localhost that gives all three Claude Code sessions native tools to post and read messages. The user stops being the message bus.
+
+---
+
+## Repository layout
+
+```
+tools/relay/
+├── package.json      # private, not published; single dep: @modelcontextprotocol/sdk
+├── tsconfig.json
+├── server.ts         # MCP SSE server entry point (~150 lines)
+├── queue.ts          # in-memory queue logic (~50 lines)
+├── queue.test.ts     # Node built-in test runner
+└── start.sh          # launcher script
+```
+
+Added to root `.gitignore`: `tools/relay/node_modules/`, `tools/relay/dist/`.
+
+---
+
+## Tech stack
+
+- **Runtime:** Node.js (v25, already installed at `/usr/bin/node`)
+- **Package manager:** npm (bun has known compat gaps with the MCP SDK's SSE transport)
+- **Dependencies:** `@modelcontextprotocol/sdk`, `tsx` (devDependency, runs TypeScript directly — no compile step)
+- **Transport:** SSE (`SSEServerTransport` from the SDK handles the HTTP layer — no Express or Hono needed)
+- **Port:** `7331` (hardcoded; easy to remember, unlikely to collide)
+
+---
+
+## Queue model
+
+Three named inboxes: `pm`, `dev-a`, `dev-b`. Each is a FIFO array in memory.
+
+Message shape:
+
+```ts
+interface RelayMessage {
+  id: string;           // uuid v4
+  from: string;         // sender role name
+  to: string;           // recipient role name
+  kind: "status" | "question" | "directive" | "free";
+  body: string;         // freeform, typically the existing markdown block format
+  ts: string;           // ISO 8601
+}
+```
+
+`kind` maps to the existing coordination protocol:
+
+| kind        | existing block              |
+|-------------|-----------------------------|
+| `status`    | `## STATUS UPDATE — DEV-*`  |
+| `question`  | `## QUESTION TO PM — DEV-*` |
+| `directive` | `## DIRECTIVE TO DEV-*`     |
+| `free`      | ad-hoc / unstructured       |
+
+Messages are **consume-once**: `read_messages` drains the inbox. There is no persistence — if the server restarts mid-lift, in-flight messages are lost. Acceptable for a dev tool; agents re-send on reconnect.
+
+---
+
+## MCP tool surface
+
+All three tools are exposed to every connected session.
+
+### `post_message`
+
+```
+post_message(from: "pm"|"dev-a"|"dev-b", to: "pm"|"dev-a"|"dev-b", kind: "status"|"question"|"directive"|"free", body: string) → { id: string }
+```
+
+Pushes one message onto the target's inbox. Returns the assigned message id. Errors if `to` or `from` is not a known role. Agents declare their own identity via `from` — the kickoff prompt tells each agent its role name.
+
+### `read_messages`
+
+```
+read_messages(for: "pm"|"dev-a"|"dev-b") → RelayMessage[]
+```
+
+Pops and returns all pending messages for that recipient, in FIFO order. After this call the inbox is empty.
+
+### `list_pending`
+
+```
+list_pending(for: "pm"|"dev-a"|"dev-b") → { count: number, kinds: string[] }
+```
+
+Returns count and kind breakdown of pending messages without consuming them. Lets an agent cheaply check "do I have anything to act on?" before committing to a `read_messages` call.
+
+---
+
+## Server terminal output
+
+Every `post_message` call prints a one-liner to stdout in the dedicated relay terminal:
+
+```
+[14:32:01] dev-b → pm  [status]   "Task P4 DONE, last commit abc1234..."
+[14:33:15] pm → dev-b  [directive] "PROCEED to task B1"
+```
+
+This log is the operational value of keeping the server in a dedicated terminal rather than backgrounding it.
+
+---
+
+## Launcher script (`start.sh`)
+
+`start.sh` accepts one optional flag:
+
+| Flag       | Behavior |
+|------------|----------|
+| *(default)*| `--manual` mode: prints three labeled prompt blocks (one per role) for copy-paste into fresh Claude Code sessions, then starts the server in the foreground |
+| `--tmux`   | Creates a new tmux window with four panes: relay server + PM + Dev-A + Dev-B, each pre-loaded with its kickoff command |
+| `--kitty`  | Same layout using kitty's `launch --new-tab` / `--new-window` |
+
+Execution order (all modes):
+
+1. `cd tools/relay && npm install --silent` (no-op if `node_modules` is current)
+2. Print the session snippet (copy-paste blocks or multiplexer launch)
+3. Foreground `npx tsx server.ts` — the terminal that ran `start.sh` becomes the relay terminal; no compile step needed
+
+Port-already-in-use check before step 3: if `:7331` is bound, print `relay already running? kill it with: kill $(lsof -ti:7331)` and exit 1.
+
+---
+
+## Claude Code configuration
+
+Add to project `.claude/settings.json`:
+
+```json
+"mcpServers": {
+  "relay": {
+    "type": "sse",
+    "url": "http://localhost:7331/sse"
+  }
+}
+```
+
+This is project-scoped — the relay tools only appear in Relicario Claude Code sessions. When the server is not running, Claude Code shows a yellow MCP connection warning but does not break. Agents gracefully fall back to asking the user to relay manually (existing behavior).
+
+---
+
+## Kickoff prompt changes
+
+One paragraph added near the top of each coordination prompt (`v0.5.0-pm-prompt.md`, `v0.5.0-dev-a-prompt.md`, `v0.5.0-dev-b-prompt.md` as template):
+
+> **Relay server:** A message-bus MCP server is running. You have three tools: `post_message(to, kind, body)`, `read_messages(for)`, `list_pending(for)`. Recipients: `pm`, `dev-a`, `dev-b`. Use these instead of asking the user to copy-paste. Before starting each task call `read_messages(for="<your-role>")`. After emitting any status, question, or directive block, call `post_message` with `kind` set to the block type and `body` set to the formatted block.
+
+The `multi-agent-kickoff` skill is updated to:
+- Remind the user to run `tools/relay/start.sh` before opening the three sessions
+- Inject the relay paragraph automatically into every generated kickoff prompt
+
+---
+
+## Error handling
+
+| Scenario | Behavior |
+|----------|----------|
+| Unknown `to` in `post_message` | MCP error returned; message not queued |
+| Server crash / restart | In-flight messages lost; agent re-sends |
+| Port 7331 in use at startup | Startup exits 1 with a kill hint |
+| Session connects before server starts | Claude Code shows MCP warning; agent falls back to manual relay |
+
+No authentication. This is localhost-only, single-machine, dev-tool use.
+
+---
+
+## Testing
+
+`queue.test.ts` using Node's built-in `node:test` runner. No extra test dep.
+
+Coverage:
+- `post_message` + `read_messages` roundtrip (single and multiple messages)
+- Consume-once: second `read_messages` on same inbox returns empty
+- `list_pending` does not drain inbox
+- FIFO ordering across multiple senders to the same inbox
+- Unknown recipient returns an error
+
+No integration test against the MCP SSE transport — that is the SDK's responsibility.
+
+---
+
+## Top-level README (`docs/superpowers/MULTI-AGENT.md`)
+
+A durable reference document covering the whole development paradigm — not the relay server specifically, but the entire three-terminal workflow that the relay server enables. Lives in `docs/superpowers/` alongside the specs and plans it describes.
+
+**Contents:**
+
+1. **Overview** — the PM/Dev-A/Dev-B pattern: why three terminals, what each role owns, what the user's job is (authorize merges, resolve escalations)
+2. **Starting a lift** — prerequisites checklist, then: `tools/relay/start.sh` → three sessions → paste kickoff prompts
+3. **Coordination protocol reference** — the four message kinds (`status`, `question`, `directive`, `free`), when each is used, what a well-formed body looks like
+4. **Using the relay tools** — `post_message`, `read_messages`, `list_pending` with one-liner examples
+5. **If the relay server isn't running** — fallback to manual copy-paste; the coordination protocol still works, just with the user as bus
+6. **Generating kickoff prompts** — point to the `multi-agent-kickoff` skill; note that the skill injects the relay paragraph automatically
+7. **Ending a lift** — PM emits MERGE-APPROVED, devs push branches, user authorizes merges, Ctrl-C the relay terminal
+
+This README is written for future-you opening the repo six months from now, not for the current lift.
+
+---
+
+## What this is not
+
+- Not a product feature — never bundled with the extension or CLI
+- Not persistent — no SQLite, no file queue, in-memory only
+- Not authenticated — localhost dev tool, no threat model
+- Not a general-purpose message bus — three hardcoded roles, no dynamic registration

docs/superpowers/specs/2026-05-03-v0.5.x-ux-polish-and-recovery-qr-design.md

@@ -0,0 +1,357 @@
+# v0.5.x — UX Polish, Settings Redesign & Recovery QR — Design
+
+**Date:** 2026-05-03  
+**Status:** Draft  
+**Target:** v0.5.1 / next release train
+
+## Overview
+
+Three parallel streams building on the v0.5.0 base:
+
+- **Stream A — Fullscreen + popup layout polish** — fullscreen vault tab gets a new 3-column layout (sidebar with type-category nav, full-width list, slide-in detail drawer); popup gets a polished type-picker; glyph additions; toast system; empty states.
+- **Stream B — Settings UX redesign** — replace the current flat settings dump with a left-nav sectioned settings page; Security section with trusted-devices and Recovery QR integration.
+- **Stream C — Recovery QR + setup wizard** — implement the recovery QR cryptographic feature (Rust core + WASM); integrate into the setup wizard's final step; wire into the vault-tab Security settings section.
+
+Streams A and B share no files with Stream C (Rust/WASM). A and B share only `glyphs.ts` and `styles.css`; all other files are disjoint. All three can run in parallel.
+
+---
+
+## Stream A — Fullscreen + Popup Layout Polish
+
+### A1. Fullscreen vault tab — 3-column layout
+
+**Current state.** `extension/src/vault/vault.ts` renders a fixed sidebar (~220px) with brand, search, item list, and bottom nav buttons. Clicking `+ new item` navigates to the type-picker. The main pane shows the selected item in a single-column layout.
+
+**New layout.**
+
+```
+┌─────────────┬──────────────────────────┬──────────────────────────┐
+│  sidebar    │  full-width list         │  detail drawer (440px)   │
+│  (200px)    │  (flex: 1)               │  slides in on row click  │
+└─────────────┴──────────────────────────┴──────────────────────────┘
+```
+
+**Sidebar changes:**
+- Replaces the current flat item list with **type-category nav**: all items are listed by section (Logins N, Secure Notes N, Cards N, Identities N, TOTP N, Keys N, Documents N) plus an "All items" entry at the top.
+- Search bar stays above the category list.
+- Bottom nav buttons remain (＋ new item, ▦ trash, ⌬ devices, ⚙ settings, ⏻ lock) — the `+ new item` button triggers the bottom sheet (see A3).
+- `⧉` replaces the current `⤴` pop-out button in the **popup toolbar only** — it stays in the popup toolbar and is not added to the fullscreen sidebar (you're already there).
+
+**Full-width list:**
+- Each row: 32px type icon (rounded, gold-tinted on selection) + title (13px) + subtitle (URL or type description, 11px muted) + `last-modified` age (10px dim, right-aligned).
+- Clicking a row: highlights the row and slides in the detail drawer from the right. The list narrows to accommodate the 440px drawer — flex layout handles this naturally.
+- Active row stays highlighted while drawer is open.
+
+**Detail drawer (440px):**
+- Header: type pill (e.g. `LOGIN`) left, action buttons right (`edit`, `history`, `copy pwd` where applicable), `✕` close.
+- Body: title (18-20px bold) + subtitle (URL/description, muted), then a **2-column field grid** for sibling fields (username/password, first/last name, number/expiry, etc.). Full-width spans for URL, notes, address, and any field without a natural pair.
+- Close (`✕` or Esc): drawer slides out, list returns to full width.
+- At ≤ 720px viewport: drawer pushes full-page (list hidden), back breadcrumb `← <Section>` navigates back.
+
+**Files affected:**
+- `extension/src/vault/vault.ts` — full layout rewrite (sidebar list → category nav, main pane wiring, drawer state)
+- `extension/src/vault/vault.css` — layout rules for 3-column, drawer, list rows, responsive breakpoint
+
+### A2. Fullscreen vault tab — "new item" bottom sheet
+
+**Current state.** Clicking `+ new item` in the sidebar sets `state.newType = null` and calls `renderPane()` which renders the type-picker inline in the main pane.
+
+**New behaviour.** A bottom sheet slides up from the bottom edge of the **main pane** (pane-only scrim — sidebar stays interactive).
+
+- Sheet structure: drag handle, "New item — choose type" label, 7-item type grid (Login, Secure Note, TOTP, Card, Identity, SSH/API Key, Document) as cards with large glyph (28px), name (11px muted). Selected type border turns gold on hover.
+- Clicking a type: sheet closes, main pane renders the add form for that type.
+- Dismissing (Esc, click scrim, `✕`): sheet closes, main pane returns to previous state.
+- Scrim covers the main pane only (not the sidebar). Sidebar nav remains clickable.
+
+**Files affected:**
+- `extension/src/vault/vault.ts` — sheet trigger, render, dismiss logic
+- `extension/src/vault/vault.css` — sheet, scrim, type-card styles
+
+### A3. Popup — polished type-picker page
+
+**Current state.** `+ new` button in the popup toolbar navigates directly to the `add` route. `renderItemForm` is called with `state.newType = null`, which presumably renders a type picker inline.
+
+**New behaviour.** Keep the current navigation model (navigate to `add` route) but upgrade the type-picker page:
+- Back arrow + "New item" title in the search-bar row (replacing search input).
+- 2-column grid of type cards: icon (glyph, 20px), name (12px bold), description (10px muted). E.g. "Login / Username + password", "TOTP / 2FA token".
+- Glyphs not emoji for type icons (use the per-type glyph table from A5).
+- `Esc` navigates back to the list.
+- Keyhint bar updates to show `Esc back`.
+
+**Files affected:**
+- `extension/src/popup/components/item-list.ts` — `+ new` button label/glyph, keyhint
+- `extension/src/popup/components/item-form.ts` (or wherever the type picker lives) — card layout, glyphs
+
+### A4. Glyphs
+
+Add to `extension/src/shared/glyphs.ts`:
+
+```ts
+export const GLYPH_VAULT_TAB = '⧉';   // pop-out to fullscreen vault tab (replaces &#x2934;)
+```
+
+Remove the inline `&#x2934;` from `extension/src/popup/components/item-list.ts:69` and replace with `GLYPH_VAULT_TAB`.
+
+### A5. Item row type icons
+
+The popup item list (`buildRowsHtml` in `item-list.ts`) currently renders title-only rows with no visual type anchor. Add a per-type glyph to each row using the item's `ManifestEntry.type` field:
+
+| Type | Glyph |
+|------|-------|
+| login | `◉` |
+| secure_note | `◫` |
+| totp | `⊡` |
+| card | `▭` |
+| identity | `⌬` |
+| key | `⊹` |
+| document | `≡` |
+
+Icon: 26×26px, rounded, `--bg-elevated` fill, gold-tinted border on active row.
+
+**Files affected:** `extension/src/popup/components/item-list.ts`, `extension/src/popup/styles.css`
+
+### A6. Empty states
+
+Two surfaces:
+
+1. **Popup item list, vault empty** — centered message: glyph `◈` (28px dim), "No items yet", "Press `+` to add your first item."
+2. **Popup item list, search returns nothing** — centered message: glyph `⊘` (28px dim), "No results for "{query}"", "Try a shorter search term."
+3. **Fullscreen list pane, section empty** — same treatment scaled for the wider pane.
+
+**Files affected:** `extension/src/popup/components/item-list.ts`, `extension/src/vault/vault.ts`
+
+### A7. Toast notification system
+
+Replace the current ad-hoc `sync-status` div with a shared toast system:
+
+- `showToast(message: string, type: 'success' | 'error' | 'info', durationMs = 2500)` in `extension/src/shared/toast.ts`.
+- Toasts appear bottom-center of the popup / bottom-right of the vault tab, auto-dismiss.
+- Used for: sync success/failure, copy-to-clipboard confirmation, device registration success.
+
+**Files affected:** new `extension/src/shared/toast.ts`, `extension/src/popup/styles.css`, `extension/src/vault/vault.css`, call sites in `item-list.ts` and `vault.ts`
+
+---
+
+## Stream B — Settings UX Redesign
+
+### B1. Settings page structure
+
+Replace the current flat settings dump (`settings.ts` + `settings-vault.ts`) with a unified settings page that renders within the fullscreen vault tab's main pane (and a compact equivalent in the popup).
+
+**Left-nav sections:**
+
+```
+Device
+  ⊙  Autofill
+  ◈  Display
+Vault
+  ◉  Security         ← Recovery QR + trusted devices (replaces devices.ts nav)
+  ↻  Generator
+  ▦  Retention
+  ⤓  Backup
+  ≡  Import
+```
+
+Each section renders its content in the right panel. The left nav is 148px; content area fills the remainder.
+
+**Device vs Vault distinction:**
+- "Device" sections read/write `chrome.storage.local` (per-browser settings).
+- "Vault" sections read/write encrypted `VaultSettings` (shared across devices via git).
+
+**Files affected:**
+- `extension/src/popup/components/settings.ts` — rewrite as sectioned layout
+- `extension/src/popup/components/settings-vault.ts` — content moves into new section components
+
+**Note on vault.ts:** DEV-B delivers the settings component with a stable export signature. The `⚙ settings` nav wiring in `vault.ts` is updated as part of Stream A's vault.ts rewrite. DEV-A and DEV-B must agree on the component's export signature before either lands.
+
+### B2. Autofill section (Device)
+
+Content replaces the current flat settings dump:
+
+- **Capture** group: "Auto-detect logins" toggle (was checkbox); "Prompt style" select (bar / toast).
+- **Blocked sites** group: list of blacklisted hostnames, each with a remove button. Add-hostname input at bottom.
+
+All options use the standardised `setting-row` pattern: left (title + description), right (control).
+
+### B3. Display section (Device)
+
+Moves the existing password-coloring UI (digit color picker, symbol color picker, live swatch, reset) from its current location into a proper Display section card.
+
+### B4. Security section (Vault)
+
+**Recovery QR card** (three states, see Stream C for implementation):
+
+- **State 1 — no QR:** amber warning ("▲ No recovery QR generated — losing your reference image would make this vault unrecoverable"), single "Generate recovery QR…" button.
+- **State 2 — QR exists, at rest:** green status ("◉ Recovery QR is set up"), last-generated date. Buttons: "Show / print QR…" and "Regenerate…". **No QR is visible in this state.**
+- **State 3 — explicit view:** modal overlay (scrim over main pane only). QR rendered at ~140×140px. Warning: "▲ Close this window before stepping away. This QR is only displayed, never saved." Actions: "⎙ Print" (triggers `window.print()` scoped to modal) and "Done" (dismisses).
+
+**Trusted devices** group: subsumes the current `⌬ devices` sidebar nav entry. Each registered device shows name, registration date, fingerprint, and a revoke button. "Register this device" entry for unregistered browsers. Once Stream B lands, the `⌬ devices` button is removed from the vault sidebar nav (settings → Security replaces it).
+
+### B5. Generator section (Vault)
+
+Pulls the existing generator-defaults content from `settings-vault.ts` into the new section layout. No functional changes — just consistent styling.
+
+### B6. Retention section (Vault)
+
+Pulls the existing retention content (trash retention, field history retention). No functional changes.
+
+### B7. Backup section (Vault)
+
+Pulls the existing backup & restore section. No functional changes.
+
+### B8. Import section (Vault)
+
+Pulls the existing import section. No functional changes.
+
+---
+
+## Stream C — Recovery QR
+
+### C1. Rust core — `relicario-core/src/recovery_qr.rs`
+
+Per the existing spec at `docs/superpowers/specs/2026-05-01-recovery-qr-design.md`. Key implementation points:
+
+**KDF input:**
+```
+b"relicario-recovery-v1\0" || u64_be(len(nfc(passphrase))) || nfc(passphrase)
+```
+Fed to Argon2id with production params (`m=64MiB, t=3, p=4`), fresh 32-byte salt per generation.
+
+**Wrap:** `XChaCha20-Poly1305(wrap_key, nonce=OsRng(24), image_secret)` — 32+16=48 bytes ciphertext.
+
+**Binary payload (109 bytes):**
+```
+[magic "RREC" 4B][version 0x01 1B][salt 32B][nonce 24B][ciphertext 48B]
+```
+
+**QR encoding:** byte mode, error-correction M, version 6 (41×41 modules). Library: `qrcode` crate (already in workspace or add it).
+
+**API surface:**
+```rust
+pub struct RecoveryQrPayload { /* opaque */ }
+
+pub fn generate_recovery_qr(
+    passphrase: &str,
+    image_secret: &[u8; 32],
+) -> Result<RecoveryQrPayload, RelicarioError>;
+
+pub fn recovery_qr_to_svg(payload: &RecoveryQrPayload) -> String;
+
+pub fn unwrap_recovery_qr(
+    payload_bytes: &[u8],
+    passphrase: &str,
+) -> Result<Zeroizing<[u8; 32]>, RelicarioError>;
+```
+
+The payload bytes are never written to disk by this module — callers are responsible for rendering only.
+
+**Passphrase entropy floor:** enforce `zxcvbn score ≥ 3` at vault init in the CLI and the setup wizard (already gated in the extension by 1C-α; confirm CLI `create` command applies the same gate).
+
+**Files affected:**
+- `crates/relicario-core/src/recovery_qr.rs` — new module
+- `crates/relicario-core/src/lib.rs` — pub mod recovery_qr
+- `crates/relicario-core/src/error.rs` — add `RecoveryQr` error variants if needed
+- `crates/relicario-core/Cargo.toml` — add `qrcode` crate
+- `crates/relicario-core/tests/` — new `recovery_qr.rs` test file
+
+### C2. CLI — `relicario recovery-qr` subcommand group
+
+```
+relicario recovery-qr generate   # prompts passphrase, renders QR to terminal (kitty/iTerm2 inline protocol or ASCII fallback)
+relicario recovery-qr unwrap      # prompts passphrase, prints image_secret as hex
+```
+
+`generate` never writes a file. It renders the QR inline in the terminal using the Kitty graphics protocol if `$TERM` indicates support, falling back to ASCII art via the `qrcode` crate's built-in ASCII renderer.
+
+**Files affected:** `crates/relicario-cli/src/main.rs`
+
+### C3. WASM bindings
+
+```ts
+// relicario-wasm/src/lib.rs
+generate_recovery_qr(passphrase: &str, image_secret: &[u8]) -> Result<String, JsValue>  // returns SVG string
+unwrap_recovery_qr(payload_b64: &str, passphrase: &str) -> Result<Vec<u8>, JsValue>     // returns image_secret bytes
+```
+
+**Files affected:** `crates/relicario-wasm/src/lib.rs`, `crates/relicario-wasm/Cargo.toml`
+
+### C4. Extension — Recovery QR in Security settings
+
+Implement the three-state Security section card described in B4:
+
+- State determined by `chrome.storage.local.recovery_qr_generated_at` (timestamp or null).
+- "Generate recovery QR…" button: calls WASM `generate_recovery_qr(passphrase, image_secret)` → stores `recovery_qr_generated_at = Date.now()` in local storage → transitions to State 3 (show modal with SVG).
+- "Show / print QR…" button: re-derives QR (requires vault to be unlocked, master key in session) → shows State 3 modal.
+- "Regenerate…" button: same as generate, with a confirmation step first.
+- Print: injects SVG into a `<iframe>` styled for print, calls `iframe.contentWindow.print()`.
+
+**Files affected:**
+- New `extension/src/popup/components/settings-security.ts`
+- `extension/src/popup/components/settings.ts` — wire Security section
+
+### C5. Extension — Recovery QR in setup wizard (Step 5 "Done")
+
+The wizard's final step adds a **skippable banner** above the "Download reference image" button:
+
+```
+◫  Generate a recovery QR before you go
+   If you lose your reference image, this QR lets you recover your vault.
+   [Generate now]  [Skip — I'll do this in Settings]
+```
+
+- "Generate now": calls WASM → shows QR modal inline on the wizard page. After dismissing, banner becomes green "◉ Recovery QR generated".
+- "Skip": dismisses banner permanently for this session; user can generate later from Settings → Security.
+- The banner is informational, not a blocker. Vault is fully usable without a recovery QR.
+
+**Files affected:** `extension/src/setup/setup.ts`
+
+### C6. Setup wizard redesign (Style C)
+
+Redesign the setup wizard from the current single-column glass-card layout to **Style C (centered hero card)**:
+
+- Full-page dark background (`--bg-page`).
+- Relicario logo glyph + wordmark centered at top.
+- **Colored progress track**: 5 segments, `--success` fill for completed, `--gold` for current, `--border` for pending.
+- Centered card (max-width 560px): step eyebrow label ("Step N of 5 · <step name>"), h2 heading, hint text, form content, action row.
+- **Glyphs not emoji** throughout. Mode cards use `◈` (create new) and `⌥` (attach). Mode-card glyphs at 28px. All other icons from the existing glyph set.
+- Probe-banner success state uses `◉` (filled circle, matches ⊙/⊘ family).
+- Action row: "◂ back" text button (left), "Continue ▸" primary button (right).
+
+This is a pure CSS/markup change — no logic changes.
+
+**Files affected:** `extension/src/setup/setup.ts`, setup CSS (inline or extracted)
+
+---
+
+## Responsive behaviour
+
+| Viewport | Fullscreen behaviour |
+|---|---|
+| ≥ 960px | 3-column: sidebar + list + drawer |
+| 720–960px | 2-column: sidebar + list; drawer pushes full-pane on click |
+| ≤ 720px | Sidebar collapses (hamburger/icon strip); list full-width; detail is full-page push |
+
+The popup is always narrow (~340px) — popup-specific components are unaffected by the fullscreen responsive rules.
+
+---
+
+## Acceptance criteria (shared)
+
+- `cargo test` green. `bun run test` green. `bun run build` + `bun run build:firefox` clean.
+- No raw `snake_case` error codes in any UI surface.
+- No emoji in any UI surface — all icons are Unicode monochrome glyphs.
+- `glyphs.ts` is the single source of truth for all icon constants; no inline Unicode literals at call sites.
+- QR code is never written to any file, `chrome.storage`, or git. `recovery_qr_generated_at` (timestamp only) is the only persisted artifact.
+- Settings left-nav sections all render without console errors. Device sections read/write `chrome.storage.local`. Vault sections read/write `VaultSettings`.
+
+---
+
+## Stream split summary (for multi-agent kickoff)
+
+| Stream | Owner | Core files | Dependency |
+|---|---|---|---|
+| A — Fullscreen + popup layout | DEV-A | `vault.ts`, `vault.css`, `item-list.ts`, `glyphs.ts` | none |
+| B — Settings UX | DEV-B | `settings.ts`, `settings-vault.ts`, new `settings-security.ts` | waits for C4 interface (can stub) |
+| C — Recovery QR | DEV-C | `recovery_qr.rs`, `relicario-wasm/src/lib.rs`, `setup.ts`, `settings-security.ts` | none |
+
+B and C share `settings-security.ts` — DEV-C owns the file, DEV-B wires it into the nav. Coordinate on interface (component export signature) before DEV-B proceeds with B4.

extension/src/__stubs__/relicario_wasm.stub.ts

@@ -0,0 +1,13 @@
+// Stub for the runtime-only WASM module. Used by vitest so that modules
+// importing relicario_wasm.js can be loaded in a Node/happy-dom environment.
+// Individual tests that exercise WASM calls should mock the relevant exports.
+
+export default async function init(): Promise<void> {}
+export const unlock = (): never => { throw new Error('wasm stub: unlock not mocked'); };
+export const lock = (): void => {};
+export const manifest_encrypt = (): never => { throw new Error('wasm stub: manifest_encrypt not mocked'); };
+export const manifest_decrypt = (): never => { throw new Error('wasm stub: manifest_decrypt not mocked'); };
+export const settings_encrypt = (): never => { throw new Error('wasm stub: settings_encrypt not mocked'); };
+export const default_vault_settings_json = (): string => '{}';
+export const embed_image_secret = (): never => { throw new Error('wasm stub: embed_image_secret not mocked'); };
+export const register_device = (): never => { throw new Error('wasm stub: register_device not mocked'); };

extension/src/popup/components/__tests__/settings.test.ts

@@ -12,6 +12,22 @@ vi.mock('../../../shared/state', () => ({
 }));
 
 import { sendMessage } from '../../../shared/state';
+import { DEFAULT_DIGIT_COLOR, DEFAULT_SYMBOL_COLOR } from '../../../shared/color-scheme';
+
+function mockChromeStorage(initial: Record<string, unknown> = {}) {
+  const store: Record<string, unknown> = { ...initial };
+  (global as any).chrome = {
+    storage: {
+      sync: {
+        get: vi.fn((key: string) => Promise.resolve(
+          key in store ? { [key]: store[key] } : {})),
+        set: vi.fn((kv: Record<string, unknown>) => { Object.assign(store, kv); return Promise.resolve(); }),
+        remove: vi.fn((key: string) => { delete store[key]; return Promise.resolve(); }),
+      },
+    },
+  };
+  return store;
+}
 
 function settingsResponses() {
   // Two parallel calls in renderSettings: get_settings + get_blacklist.
@@ -30,6 +46,7 @@ describe('settings view', () => {
   });
 
   it('renders a Sync now button', async () => {
+    mockChromeStorage();
     settingsResponses();
 
     await renderSettings(app);
@@ -38,6 +55,7 @@ describe('settings view', () => {
   });
 
   it('clicking Sync now sends a sync message and shows feedback on success', async () => {
+    mockChromeStorage();
     settingsResponses();
     (sendMessage as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ ok: true });
 
@@ -52,6 +70,7 @@ describe('settings view', () => {
   });
 
   it('shows the error when sync fails', async () => {
+    mockChromeStorage();
     settingsResponses();
     (sendMessage as ReturnType<typeof vi.fn>).mockResolvedValueOnce({ ok: false, error: 'remote_unreachable' });
 
@@ -64,3 +83,109 @@ describe('settings view', () => {
     expect(status.textContent).toMatch(/remote_unreachable/);
   });
 });
+
+describe('settings Display section', () => {
+  let app: HTMLElement;
+
+  beforeEach(() => {
+    document.body.innerHTML = '<div id="app"></div>';
+    app = document.getElementById('app')!;
+    (sendMessage as ReturnType<typeof vi.fn>).mockReset();
+  });
+
+  it('renders digit and symbol color pickers with default values when storage is empty', async () => {
+    mockChromeStorage();
+    settingsResponses();
+
+    await renderSettings(app);
+
+    const digitInput = app.querySelector<HTMLInputElement>('#display-digit-color');
+    const symbolInput = app.querySelector<HTMLInputElement>('#display-symbol-color');
+    expect(digitInput).not.toBeNull();
+    expect(symbolInput).not.toBeNull();
+    expect(digitInput!.value).toBe(DEFAULT_DIGIT_COLOR);
+    expect(symbolInput!.value).toBe(DEFAULT_SYMBOL_COLOR);
+  });
+
+  it('renders pickers with stored values when storage has a scheme', async () => {
+    mockChromeStorage({
+      password_display_scheme: { digit_color: '#112233', symbol_color: '#aabbcc' },
+    });
+    settingsResponses();
+
+    await renderSettings(app);
+
+    const digitInput = app.querySelector<HTMLInputElement>('#display-digit-color');
+    const symbolInput = app.querySelector<HTMLInputElement>('#display-symbol-color');
+    expect(digitInput!.value).toBe('#112233');
+    expect(symbolInput!.value).toBe('#aabbcc');
+  });
+
+  it('renders a color-preview-swatch element', async () => {
+    mockChromeStorage();
+    settingsResponses();
+
+    await renderSettings(app);
+
+    expect(app.querySelector('#display-swatch')).not.toBeNull();
+  });
+
+  it('changing digit color calls saveColorScheme with updated scheme', async () => {
+    mockChromeStorage();
+    settingsResponses();
+
+    await renderSettings(app);
+
+    const digitInput = app.querySelector<HTMLInputElement>('#display-digit-color')!;
+    digitInput.value = '#ff0000';
+    digitInput.dispatchEvent(new Event('change'));
+    await new Promise((r) => setTimeout(r, 0));
+
+    const syncSet = (global as any).chrome.storage.sync.set as ReturnType<typeof vi.fn>;
+    expect(syncSet).toHaveBeenCalledWith(
+      expect.objectContaining({
+        password_display_scheme: expect.objectContaining({ digit_color: '#ff0000' }),
+      }),
+    );
+  });
+
+  it('changing symbol color calls saveColorScheme with updated scheme', async () => {
+    mockChromeStorage();
+    settingsResponses();
+
+    await renderSettings(app);
+
+    const symbolInput = app.querySelector<HTMLInputElement>('#display-symbol-color')!;
+    symbolInput.value = '#00ff00';
+    symbolInput.dispatchEvent(new Event('change'));
+    await new Promise((r) => setTimeout(r, 0));
+
+    const syncSet = (global as any).chrome.storage.sync.set as ReturnType<typeof vi.fn>;
+    expect(syncSet).toHaveBeenCalledWith(
+      expect.objectContaining({
+        password_display_scheme: expect.objectContaining({ symbol_color: '#00ff00' }),
+      }),
+    );
+  });
+
+  it('clicking reset calls chrome.storage.sync.remove and restores defaults', async () => {
+    mockChromeStorage({
+      password_display_scheme: { digit_color: '#112233', symbol_color: '#aabbcc' },
+    });
+    settingsResponses();
+
+    await renderSettings(app);
+
+    const resetBtn = app.querySelector<HTMLButtonElement>('#display-reset')!;
+    resetBtn.click();
+    await new Promise((r) => setTimeout(r, 0));
+
+    const syncRemove = (global as any).chrome.storage.sync.remove as ReturnType<typeof vi.fn>;
+    expect(syncRemove).toHaveBeenCalledWith('password_display_scheme');
+
+    const digitInput = app.querySelector<HTMLInputElement>('#display-digit-color')!;
+    const symbolInput = app.querySelector<HTMLInputElement>('#display-symbol-color')!;
+    expect(digitInput.value).toBe(DEFAULT_DIGIT_COLOR);
+    expect(symbolInput.value).toBe(DEFAULT_SYMBOL_COLOR);
+  });
+});

extension/src/popup/components/field-history.ts

@@ -1,6 +1,7 @@
 /// Field history view — shows password/concealed field history for an item.
 
 import { getState, setState, sendMessage, navigate, escapeHtml } from '../../shared/state';
+import { colorizePassword } from '../../shared/password-coloring';
 import type { FieldHistoryView } from '../../shared/types';
 
 function relativeTime(unixSec: number): string {
@@ -103,6 +104,16 @@ export async function renderFieldHistory(app: HTMLElement): Promise<void> {
     </div>
   `;
 
+  // Colorize revealed entries: replace plain-text content with colorized spans
+  app.querySelectorAll<HTMLElement>('.history-entry__value.revealed').forEach((el) => {
+    const key = el.closest<HTMLElement>('.history-entry')?.dataset.entry ?? '';
+    const plaintext = valueStore.get(key);
+    if (plaintext !== undefined) {
+      el.textContent = '';
+      el.appendChild(colorizePassword(plaintext));
+    }
+  });
+
   // Wire handlers
   app.querySelector<HTMLButtonElement>('#back-btn')?.addEventListener('click', () => navigate('detail'));
 

extension/src/popup/components/fields.ts

@@ -6,6 +6,7 @@
 /// copy click handlers on any rendered rows.
 
 import { escapeHtml } from '../../shared/state';
+import { colorizePassword } from '../../shared/password-coloring';
 import type { Item, Section, Field, FieldValue } from '../../shared/types';
 
 export interface RowOpts {
@@ -46,6 +47,7 @@ export interface ConcealedRowOpts {
   id: string;
   label: string;
   value: string;
+  kind?: 'password' | 'concealed';
   monospace?: boolean;
   multiline?: boolean;
 }
@@ -53,12 +55,15 @@ export interface ConcealedRowOpts {
 /// Concealed row — value rendered hidden until the user clicks "show".
 /// Plaintext is stored in `data-field-value` on the row element and copied
 /// to the visible value span on reveal. Copy button always copies plaintext.
+/// When `kind` is "password", wireFieldHandlers applies colorizePassword on
+/// reveal so digits/symbols/letters are rendered in distinct colours.
 export function renderConcealedRow(opts: ConcealedRowOpts): string {
-  const { id, label, value, monospace, multiline } = opts;
+  const { id, label, value, kind, monospace, multiline } = opts;
   const placeholder = multiline ? `•••• (${value.length} chars)` : '••••';
   const valueClass = `field-row__value${monospace ? ' monospace' : ''}`;
+  const kindAttr = kind ? ` data-field-kind="${escapeHtml(kind)}"` : '';
   return `
-    <div class="field-row" data-field-id="${escapeHtml(id)}" data-revealed="false" data-field-value="${escapeHtml(value)}" data-field-multiline="${multiline ? 'true' : 'false'}">
+    <div class="field-row" data-field-id="${escapeHtml(id)}" data-revealed="false" data-field-value="${escapeHtml(value)}" data-field-multiline="${multiline ? 'true' : 'false'}"${kindAttr}>
       <span class="field-row__label">${escapeHtml(label)}</span>
       <span class="${valueClass}" data-field-role="value">${escapeHtml(placeholder)}</span>
       <span class="field-row__actions">
@@ -100,8 +105,14 @@ export function wireFieldHandlers(scope: HTMLElement): void {
         valueEl.textContent = placeholder;
         row.setAttribute('data-revealed', 'false');
         btn.textContent = 'show';
+      } else {
+        const isPassword = row.getAttribute('data-field-kind') === 'password';
+        valueEl.textContent = '';
+        if (isPassword) {
+          valueEl.appendChild(colorizePassword(plaintext));
         } else {
           valueEl.textContent = plaintext;
+        }
         row.setAttribute('data-revealed', 'true');
         btn.textContent = 'hide';
       }
@@ -150,6 +161,7 @@ export function renderSections(item: Item, idPrefix: string): string {
           id: `${idPrefix}-s${sIdx}-f${fIdx}`,
           label: field.label,
           value: field.value.value,
+          kind: field.value.kind,
         });
       }
     });

extension/src/popup/components/generator-panel.ts

@@ -6,6 +6,7 @@
 
 import { sendMessage } from '../../shared/state';
 import type { GeneratorRequest, VaultSettings } from '../../shared/types';
+import { colorizePassword } from '../../shared/password-coloring';
 
 interface UiKnobs {
   kind: 'random' | 'bip39';
@@ -138,7 +139,10 @@ export function openGeneratorPanel(opts: OpenPanelOpts): void {
         const d = resp.data as { password?: string; passphrase?: string };
         currentPreview = d.password ?? d.passphrase ?? '';
         const el = host.querySelector('.preview__value');
-        if (el) el.textContent = currentPreview;
+        if (el) {
+          el.textContent = '';
+          el.appendChild(colorizePassword(currentPreview));
+        }
         updateValidation();
       }
     }, 150);

extension/src/popup/components/settings.ts

@@ -3,6 +3,11 @@
 import { sendMessage, navigate, escapeHtml } from '../../shared/state';
 import type { DeviceSettings } from '../../shared/types';
 import { GLYPH_TRASH, GLYPH_DEVICES } from '../../shared/glyphs';
+import {
+  loadColorScheme, saveColorScheme, resetColorScheme,
+  DEFAULT_DIGIT_COLOR, DEFAULT_SYMBOL_COLOR,
+} from '../../shared/color-scheme';
+import { colorizePassword } from '../../shared/password-coloring';
 
 export async function renderSettings(app: HTMLElement): Promise<void> {
   app.innerHTML = '<div class="pad" style="text-align:center; padding-top:20px;"><span class="spinner"></span></div>';
@@ -62,6 +67,9 @@ export async function renderSettings(app: HTMLElement): Promise<void> {
         <div id="sync-status" class="muted" style="font-size:12px;min-height:16px;"></div>
       </div>
 
+      <div style="margin-bottom:16px;" id="display-section-container">
+      </div>
+
       <div>
         <div style="font-size:12px; color:#8b949e; margin-bottom:6px;">blacklisted sites</div>
         <div id="blacklist-container">
@@ -119,4 +127,65 @@ export async function renderSettings(app: HTMLElement): Promise<void> {
       }
     });
   });
+
+  // Render Display section after the rest of the DOM is ready
+  await renderDisplaySection();
+}
+
+function updateSwatch(swatch: HTMLElement, digitColor: string, symbolColor: string): void {
+  swatch.style.setProperty('--relicario-pwd-digit-color', digitColor);
+  swatch.style.setProperty('--relicario-pwd-symbol-color', symbolColor);
+  swatch.innerHTML = '';
+  swatch.appendChild(colorizePassword('Abc123!@#xyz'));
+}
+
+async function renderDisplaySection(): Promise<void> {
+  // The Display section container must be present in the DOM before we call this
+  const container = document.getElementById('display-section-container');
+  if (!container) return;
+
+  const scheme = await loadColorScheme();
+
+  container.innerHTML = `
+    <div style="font-size:12px; color:#8b949e; margin-bottom:6px;">display</div>
+    <div style="margin-bottom:8px;">
+      <label style="display:flex; align-items:center; gap:8px; font-size:13px;">
+        <input type="color" id="display-digit-color" value="${escapeHtml(scheme.digit_color)}">
+        digit color
+      </label>
+    </div>
+    <div style="margin-bottom:8px;">
+      <label style="display:flex; align-items:center; gap:8px; font-size:13px;">
+        <input type="color" id="display-symbol-color" value="${escapeHtml(scheme.symbol_color)}">
+        symbol color
+      </label>
+    </div>
+    <div id="display-swatch" class="color-preview-swatch"></div>
+    <div style="margin-top:8px;">
+      <button id="display-reset" class="btn" style="font-size:11px;">reset to defaults</button>
+    </div>
+  `;
+
+  const digitInput = document.getElementById('display-digit-color') as HTMLInputElement;
+  const symbolInput = document.getElementById('display-symbol-color') as HTMLInputElement;
+  const swatch = document.getElementById('display-swatch') as HTMLElement;
+
+  // Render initial swatch
+  updateSwatch(swatch, scheme.digit_color, scheme.symbol_color);
+
+  async function onColorChange(): Promise<void> {
+    const newScheme = { digit_color: digitInput.value, symbol_color: symbolInput.value };
+    await saveColorScheme(newScheme);
+    updateSwatch(swatch, newScheme.digit_color, newScheme.symbol_color);
+  }
+
+  digitInput.addEventListener('change', () => void onColorChange());
+  symbolInput.addEventListener('change', () => void onColorChange());
+
+  document.getElementById('display-reset')?.addEventListener('click', async () => {
+    await resetColorScheme();
+    digitInput.value = DEFAULT_DIGIT_COLOR;
+    symbolInput.value = DEFAULT_SYMBOL_COLOR;
+    updateSwatch(swatch, DEFAULT_DIGIT_COLOR, DEFAULT_SYMBOL_COLOR);
+  });
 }

extension/src/popup/components/types/__tests__/login.test.ts

@@ -26,7 +26,7 @@ vi.mock('../../../../setup/setup-helpers', () => ({
   entropyText: vi.fn(() => ''),
 }));
 
-import { renderForm } from '../login';
+import { renderForm, applyGeneratedPassword } from '../login';
 import { sendMessage } from '../../../../shared/state';
 
 describe('login form smart inputs', () => {
@@ -154,3 +154,37 @@ describe('Login save shape', () => {
     expect(addCall).toBeUndefined();
   });
 });
+
+describe('regenerate handler dispatches input event', () => {
+  it('dispatches an InputEvent on the input after value is set', () => {
+    const input = document.createElement('input');
+    input.type = 'password';
+    document.body.appendChild(input);
+
+    const dispatchSpy = vi.spyOn(input, 'dispatchEvent');
+
+    applyGeneratedPassword(input, 'sCMtTJkF%GN^mF#-N6D%');
+
+    expect(input.value).toBe('sCMtTJkF%GN^mF#-N6D%');
+    expect(input.type).toBe('text');
+    expect(dispatchSpy).toHaveBeenCalled();
+    const evt = dispatchSpy.mock.calls.find(c => c[0] instanceof InputEvent)?.[0] as InputEvent;
+    expect(evt).toBeDefined();
+    expect(evt.type).toBe('input');
+    expect(evt.bubbles).toBe(true);
+
+    document.body.removeChild(input);
+  });
+
+  it('bubbling listener fires when applyGeneratedPassword is called', () => {
+    const input = document.createElement('input');
+    document.body.appendChild(input);
+
+    let listenerFired = false;
+    input.addEventListener('input', () => { listenerFired = true; });
+    applyGeneratedPassword(input, 'newpass');
+    expect(listenerFired).toBe(true);
+
+    document.body.removeChild(input);
+  });
+});

extension/src/popup/components/types/login.ts

@@ -29,6 +29,15 @@ import { wireTotpPreview, wireTotpQr } from '../../../shared/form-affordances/to
 import { wireNotesMonoToggle } from '../../../shared/form-affordances/notes-tools';
 import { scheduleRate } from '../../../setup/setup-helpers';
 
+/// Sets a generated password on an input, reveals it as plain text, then
+/// dispatches a synthetic InputEvent so listeners (e.g. the strength meter)
+/// re-evaluate the new value.
+export function applyGeneratedPassword(input: HTMLInputElement, value: string): void {
+  input.value = value;
+  input.type = 'text';
+  input.dispatchEvent(new InputEvent('input', { bubbles: true }));
+}
+
 /// Called by the dispatcher before each render. Stops any in-flight
 /// tickers / intervals / listeners the previous view may have attached.
 export function teardown(): void {
@@ -75,7 +84,7 @@ export async function renderDetail(app: HTMLElement, item: Item): Promise<void>
         ${renderSignatureBlock({ accent: 'gold', children: sigInner })}
       </div>
       ${username ? renderRow({ label: 'username', value: username, copyable: true }) : ''}
-      ${renderConcealedRow({ id: 'login-password', label: 'password', value: password })}
+      ${renderConcealedRow({ id: 'login-password', label: 'password', value: password, kind: 'password' })}
       ${url ? renderRow({ label: 'url', value: url, href: url }) : ''}
       ${hasTotp ? `
         <div class="field-row">
@@ -348,6 +357,7 @@ export function renderForm(
 
       ${sectionsHtml}
 
+      <div class="${surface === 'fullscreen' ? 'form-lower' : ''}">
         <div class="form-group">
           <div class="notes-with-toggle">
             <label class="label" for="f-notes" style="margin:0;flex:1;">notes</label>
@@ -363,6 +373,7 @@ export function renderForm(
           <button class="btn btn-primary" id="save-btn">${state.loading ? '<span class="spinner"></span>' : 'save'}</button>
         </div>
       </div>
+    </div>
   `;
 
   const rerender = (): void => {
@@ -433,7 +444,7 @@ export function renderForm(
       context: 'fill-field',
       onPicked: (value) => {
         const pw = document.getElementById('f-password') as HTMLInputElement | null;
-        if (pw) { pw.value = value; pw.type = 'text'; }
+        if (pw) applyGeneratedPassword(pw, value);
       },
     });
   });

extension/src/popup/popup.ts

@@ -4,6 +4,7 @@
 /// Navigation works by updating `currentState` and calling `render()`.
 
 import type { Request, Response } from '../shared/messages';
+import { lookupErrorCopy } from '../shared/error-copy';
 import type { ItemId, ManifestEntry, Item } from '../shared/types';
 import { registerHost } from '../shared/state';
 import { renderUnlock } from './components/unlock';
@@ -18,6 +19,7 @@ import { renderFieldHistory } from './components/field-history';
 import { teardown as teardownTrash } from './components/trash';
 import { teardown as teardownDevices } from './components/devices';
 import { teardown as teardownFieldHistory } from './components/field-history';
+import { applyColorScheme } from '../shared/color-scheme';
 
 // --- Escape HTML to prevent XSS ---
 export function escapeHtml(str: string): string {
@@ -144,19 +146,8 @@ export function humanizeError(err: string): string {
   if (/settings json:/i.test(err)) {
     return 'Settings are in an invalid format — try reloading the extension.';
   }
-  if (/vault_locked/i.test(err)) {
-    return 'Vault is locked. Unlock and try again.';
-  }
-  if (/origin_mismatch/i.test(err)) {
-    return 'This login belongs to a different site — refusing to leak credentials cross-origin.';
-  }
-  if (/unauthorized_sender/i.test(err)) {
-    return 'This action is not allowed from here.';
-  }
-  if (/tab_navigated|captured_tab_gone/i.test(err)) {
-    return 'The browser tab changed before the fill could complete — try again.';
-  }
-  return err;
+  const copy = lookupErrorCopy(err);
+  return copy.body;
 }
 
 // --- Navigation ---
@@ -225,6 +216,14 @@ function render(): void {
 // --- Init ---
 
 async function init(): Promise<void> {
+  await applyColorScheme();
+
+  chrome.storage.onChanged.addListener((changes, area) => {
+    if (area === 'sync' && 'password_display_scheme' in changes) {
+      void applyColorScheme();
+    }
+  });
+
   // Snapshot the active tab at popup-open — the fill path uses this
   // tabId/url pair so the SW can verify the tab hasn't navigated before
   // forwarding credentials (audit M5 + TOCTOU close via expectedHost).

extension/src/popup/styles.css

@@ -38,6 +38,10 @@
 
   /* Focus */
   --focus-ring:    0 0 0 2px var(--gold-ring);
+
+  /* Password coloring (P1) */
+  --relicario-pwd-digit-color: #2563eb;
+  --relicario-pwd-symbol-color: #dc2626;
 }
 
 * {
@@ -1554,3 +1558,18 @@ textarea {
 .logo-lockup .brand-logo { width: 42px; height: 42px; margin: 0 auto 10px; }
 .logo-lockup .brand { font-size: 17px; font-weight: 600; color: var(--gold-text); letter-spacing: 0.5px; }
 .tagline { color: var(--text-dim); font-size: 11px; margin-top: 4px; letter-spacing: 0.3px; }
+
+/* Password character-class coloring */
+.pwd-digit  { color: var(--relicario-pwd-digit-color); }
+.pwd-symbol { color: var(--relicario-pwd-symbol-color); }
+.pwd-letter { color: inherit; }
+
+.color-preview-swatch {
+  font-family: ui-monospace, monospace;
+  font-size: 1.1rem;
+  padding: 8px 12px;
+  border: 1px solid var(--border-mid);
+  border-radius: 4px;
+  margin-top: 8px;
+  background: var(--bg-input);
+}

extension/src/setup/__tests__/setup.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { finishSetup } from '../setup';
+
+describe('finishSetup', () => {
+  beforeEach(() => {
+    (global as any).chrome = {
+      tabs: {
+        create: vi.fn(() => Promise.resolve({ id: 999 })),
+        getCurrent: vi.fn(() => Promise.resolve({ id: 42 })),
+        remove: vi.fn(() => Promise.resolve()),
+      },
+      runtime: {
+        getURL: vi.fn((p: string) => `chrome-extension://abc/${p}`),
+      },
+    };
+  });
+
+  it('opens vault.html in a new tab', async () => {
+    await finishSetup();
+    expect(chrome.runtime.getURL).toHaveBeenCalledWith('vault.html');
+    expect(chrome.tabs.create).toHaveBeenCalledWith({
+      url: 'chrome-extension://abc/vault.html',
+    });
+  });
+
+  it('closes the current setup tab after opening the vault tab', async () => {
+    await finishSetup();
+    expect(chrome.tabs.getCurrent).toHaveBeenCalled();
+    expect(chrome.tabs.remove).toHaveBeenCalledWith(42);
+  });
+
+  it('still opens the vault tab even if closing the setup tab fails', async () => {
+    (chrome.tabs.remove as any).mockRejectedValueOnce(new Error('no permission'));
+    await expect(finishSetup()).resolves.not.toThrow();
+    expect(chrome.tabs.create).toHaveBeenCalled();
+  });
+});

extension/src/setup/setup.ts

@@ -1101,6 +1101,7 @@ function attachStep5(): void {
 
       state.configPushed = true;
       render();
+      void finishSetup();
     } catch (err: unknown) {
       console.error('[relicario setup] register device failed:', err);
       state.error = `Failed to register device: ${err instanceof Error ? err.message : String(err)}`;
@@ -1131,6 +1132,23 @@ function attachStep5(): void {
   });
 }
 
+// --- Completion handoff ---
+
+/// Open the fullscreen vault tab and best-effort close the setup tab.
+export async function finishSetup(): Promise<void> {
+  const vaultUrl = chrome.runtime.getURL('vault.html');
+  await chrome.tabs.create({ url: vaultUrl });
+  try {
+    const current = await chrome.tabs.getCurrent();
+    if (current?.id !== undefined) {
+      await chrome.tabs.remove(current.id);
+    }
+  } catch {
+    // Setup tab may not be closeable (e.g., opened as popup rather than a tab).
+    // The vault tab is open — that's the user-visible success.
+  }
+}
+
 // --- Boot ---
 
 document.addEventListener('DOMContentLoaded', () => {

extension/src/shared/__tests__/color-scheme.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import {
+  loadColorScheme, saveColorScheme, resetColorScheme, applyColorScheme,
+  DEFAULT_DIGIT_COLOR, DEFAULT_SYMBOL_COLOR,
+} from '../color-scheme';
+
+function mockChromeStorage(initial: any = {}) {
+  const store = { ...initial };
+  (global as any).chrome = {
+    storage: {
+      sync: {
+        get: vi.fn((key: string) => Promise.resolve(
+          key in store ? { [key]: store[key] } : {})),
+        set: vi.fn((kv: any) => { Object.assign(store, kv); return Promise.resolve(); }),
+        remove: vi.fn((key: string) => { delete store[key]; return Promise.resolve(); }),
+      },
+    },
+  };
+  return store;
+}
+
+describe('color-scheme storage', () => {
+  beforeEach(() => {
+    // happy-dom provides document globally; reset inline styles between tests
+    document.documentElement.removeAttribute('style');
+  });
+
+  it('load returns defaults when storage is empty', async () => {
+    mockChromeStorage();
+    const scheme = await loadColorScheme();
+    expect(scheme.digit_color).toBe(DEFAULT_DIGIT_COLOR);
+    expect(scheme.symbol_color).toBe(DEFAULT_SYMBOL_COLOR);
+  });
+
+  it('load returns stored values when present', async () => {
+    mockChromeStorage({
+      password_display_scheme: { digit_color: '#123456', symbol_color: '#abcdef' },
+    });
+    const scheme = await loadColorScheme();
+    expect(scheme.digit_color).toBe('#123456');
+    expect(scheme.symbol_color).toBe('#abcdef');
+  });
+
+  it('save round-trips', async () => {
+    mockChromeStorage();
+    await saveColorScheme({ digit_color: '#111111', symbol_color: '#222222' });
+    const scheme = await loadColorScheme();
+    expect(scheme).toEqual({ digit_color: '#111111', symbol_color: '#222222' });
+  });
+
+  it('reset removes the storage key', async () => {
+    const store = mockChromeStorage({
+      password_display_scheme: { digit_color: '#000000', symbol_color: '#ffffff' },
+    });
+    await resetColorScheme();
+    expect(store.password_display_scheme).toBeUndefined();
+    const scheme = await loadColorScheme();
+    expect(scheme.digit_color).toBe(DEFAULT_DIGIT_COLOR);
+  });
+
+  it('apply sets CSS custom properties on document.documentElement', async () => {
+    mockChromeStorage({
+      password_display_scheme: { digit_color: '#deadbe', symbol_color: '#feed00' },
+    });
+    await applyColorScheme();
+    const root = document.documentElement.style;
+    expect(root.getPropertyValue('--relicario-pwd-digit-color').trim()).toBe('#deadbe');
+    expect(root.getPropertyValue('--relicario-pwd-symbol-color').trim()).toBe('#feed00');
+  });
+
+  it('save rejects malformed hex values', async () => {
+    mockChromeStorage();
+    await expect(saveColorScheme({ digit_color: 'not-a-color', symbol_color: '#ffffff' }))
+      .rejects.toThrow();
+  });
+});

extension/src/shared/__tests__/error-copy.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { execSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { ERROR_COPY, lookupErrorCopy } from '../error-copy';
+
+const repoRoot = resolve(__dirname, '../../../..');
+
+function discoverCodes(): Set<string> {
+  const out = execSync(
+    `grep -rohE "ok: false, error: '[^']+'" extension/src/service-worker/ \
+       --include="*.ts" --exclude-dir=__tests__`,
+    { cwd: repoRoot, encoding: 'utf-8' },
+  );
+  const codes = new Set<string>();
+  for (const line of out.split('\n')) {
+    const m = line.match(/error: '([^']+)'/);
+    if (m) codes.add(m[1]);
+  }
+  return codes;
+}
+
+describe('ERROR_COPY', () => {
+  it('contains an entry for every error code returned by the service worker', () => {
+    const discovered = discoverCodes();
+    expect(discovered.size).toBeGreaterThan(0);
+    const missing: string[] = [];
+    for (const code of discovered) {
+      if (!ERROR_COPY[code]) missing.push(code);
+    }
+    expect(missing).toEqual([]);
+  });
+
+  it('lookupErrorCopy returns the mapped entry for known codes', () => {
+    const copy = lookupErrorCopy('vault_locked');
+    expect(copy.title).toBe('Vault locked');
+    expect(copy.body).toMatch(/unlock/i);
+  });
+
+  it('lookupErrorCopy falls back to a generic shape for unknown codes', () => {
+    const copy = lookupErrorCopy('made_up_code_xyz');
+    expect(copy.title).toBe('Something went wrong');
+    expect(copy.body).toContain('made_up_code_xyz');
+  });
+});

extension/src/shared/__tests__/password-coloring.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { colorizePassword, PWD_DIGIT, PWD_SYMBOL, PWD_LETTER } from '../password-coloring';
+
+describe('colorizePassword', () => {
+
+  function classes(frag: DocumentFragment): string[] {
+    return Array.from(frag.querySelectorAll('span')).map(s => s.className);
+  }
+  function texts(frag: DocumentFragment): string[] {
+    return Array.from(frag.querySelectorAll('span')).map(s => s.textContent ?? '');
+  }
+
+  it('returns empty fragment for empty input', () => {
+    const frag = colorizePassword('');
+    expect(frag.childNodes.length).toBe(0);
+  });
+
+  it('classifies a mixed-class run', () => {
+    const frag = colorizePassword('aB3$xY');
+    expect(classes(frag)).toEqual([PWD_LETTER, PWD_DIGIT, PWD_SYMBOL, PWD_LETTER]);
+    expect(texts(frag)).toEqual(['aB', '3', '$', 'xY']);
+  });
+
+  it('all-letters produces a single letter span', () => {
+    const frag = colorizePassword('passwd');
+    expect(classes(frag)).toEqual([PWD_LETTER]);
+    expect(texts(frag)).toEqual(['passwd']);
+  });
+
+  it('all-digits produces a single digit span', () => {
+    const frag = colorizePassword('123456');
+    expect(classes(frag)).toEqual([PWD_DIGIT]);
+    expect(texts(frag)).toEqual(['123456']);
+  });
+
+  it('all-symbols produces a single symbol span', () => {
+    const frag = colorizePassword('!@#$%^');
+    expect(classes(frag)).toEqual([PWD_SYMBOL]);
+    expect(texts(frag)).toEqual(['!@#$%^']);
+  });
+
+  it('classifies unicode letters as letters', () => {
+    const frag = colorizePassword('áñü');
+    expect(classes(frag)).toEqual([PWD_LETTER]);
+  });
+
+  it('classifies whitespace as symbol', () => {
+    const frag = colorizePassword('a b');
+    expect(classes(frag)).toEqual([PWD_LETTER, PWD_SYMBOL, PWD_LETTER]);
+    expect(texts(frag)).toEqual(['a', ' ', 'b']);
+  });
+
+  it('representative password snapshot: aB3$xY7&_!', () => {
+    const frag = colorizePassword('aB3$xY7&_!');
+    expect(classes(frag)).toEqual([
+      PWD_LETTER, PWD_DIGIT, PWD_SYMBOL, PWD_LETTER, PWD_DIGIT, PWD_SYMBOL,
+    ]);
+    expect(texts(frag)).toEqual(['aB', '3', '$', 'xY', '7', '&_!']);
+  });
+});

extension/src/shared/color-scheme.ts

@@ -0,0 +1,48 @@
+export const DEFAULT_DIGIT_COLOR = '#2563eb';
+export const DEFAULT_SYMBOL_COLOR = '#dc2626';
+const STORAGE_KEY = 'password_display_scheme';
+const HEX_RE = /^#[0-9a-fA-F]{6}$/;
+
+export interface ColorScheme {
+  digit_color: string;
+  symbol_color: string;
+}
+
+export const DEFAULT_SCHEME: ColorScheme = {
+  digit_color: DEFAULT_DIGIT_COLOR,
+  symbol_color: DEFAULT_SYMBOL_COLOR,
+};
+
+function isValid(s: ColorScheme): boolean {
+  return HEX_RE.test(s.digit_color) && HEX_RE.test(s.symbol_color);
+}
+
+export async function loadColorScheme(): Promise<ColorScheme> {
+  const result = await chrome.storage.sync.get(STORAGE_KEY);
+  const stored = result[STORAGE_KEY] as Partial<ColorScheme> | undefined;
+  if (!stored) return { ...DEFAULT_SCHEME };
+  return {
+    digit_color: typeof stored.digit_color === 'string' && HEX_RE.test(stored.digit_color)
+      ? stored.digit_color : DEFAULT_DIGIT_COLOR,
+    symbol_color: typeof stored.symbol_color === 'string' && HEX_RE.test(stored.symbol_color)
+      ? stored.symbol_color : DEFAULT_SYMBOL_COLOR,
+  };
+}
+
+export async function saveColorScheme(scheme: ColorScheme): Promise<void> {
+  if (!isValid(scheme)) {
+    throw new Error('Invalid color values; expected #rrggbb hex strings.');
+  }
+  await chrome.storage.sync.set({ [STORAGE_KEY]: scheme });
+}
+
+export async function resetColorScheme(): Promise<void> {
+  await chrome.storage.sync.remove(STORAGE_KEY);
+}
+
+export async function applyColorScheme(): Promise<void> {
+  const scheme = await loadColorScheme();
+  const root = document.documentElement.style;
+  root.setProperty('--relicario-pwd-digit-color', scheme.digit_color);
+  root.setProperty('--relicario-pwd-symbol-color', scheme.symbol_color);
+}

extension/src/shared/error-copy.ts

@@ -0,0 +1,102 @@
+export interface ErrorCta {
+  label: string;
+  action?: 'unlock' | 'reload_extension' | 'open_setup';
+}
+
+export interface ErrorCopy {
+  title: string;
+  body: string;
+  cta?: ErrorCta;
+}
+
+const UNLOCK_CTA: ErrorCta = { label: 'Unlock vault', action: 'unlock' };
+
+export const ERROR_COPY: Record<string, ErrorCopy> = {
+  vault_locked: {
+    title: 'Vault locked',
+    body: 'Unlock your vault to continue.',
+    cta: UNLOCK_CTA,
+  },
+  unauthorized_sender: {
+    title: 'Action not allowed',
+    body: 'This action is not allowed from here.',
+  },
+  unknown_message_type: {
+    title: 'Internal error',
+    body: 'The extension received an unknown request — try reloading.',
+    cta: { label: 'Reload extension', action: 'reload_extension' },
+  },
+  origin_mismatch: {
+    title: 'Wrong site',
+    body: 'This login belongs to a different site — refusing to leak credentials cross-origin.',
+  },
+  not_a_login: {
+    title: 'Not a login',
+    body: 'That item does not have a username and password to fill.',
+  },
+  no_totp: {
+    title: 'No 2FA on this item',
+    body: 'This item does not have a TOTP secret configured.',
+  },
+  invalid_sender_url: {
+    title: 'Cannot read tab URL',
+    body: 'The current tab has no recognizable URL — try reloading the page.',
+  },
+  tab_navigated: {
+    title: 'Tab changed',
+    body: 'The browser tab changed before the action could complete — try again.',
+  },
+  captured_tab_gone: {
+    title: 'Tab is gone',
+    body: 'The browser tab closed before the action could complete — try again.',
+  },
+  item_not_found: {
+    title: 'Item not found',
+    body: 'That item is no longer in the vault — it may have been deleted from another device.',
+  },
+  attachment_not_found: {
+    title: 'Attachment missing',
+    body: 'The attachment is referenced in the item but is not present in the vault.',
+  },
+  upload_failed: {
+    title: 'Upload failed',
+    body: 'Could not upload the attachment — check your connection and try again.',
+  },
+  download_failed: {
+    title: 'Download failed',
+    body: 'Could not download the attachment — check your connection and try again.',
+  },
+  'invalid base32 secret': {
+    title: 'Invalid secret',
+    body: 'The TOTP secret must be valid Base32 (letters A-Z and digits 2-7 only).',
+  },
+  'no items to import': {
+    title: 'Nothing to import',
+    body: 'The CSV did not contain any importable items.',
+  },
+  'no reference image stored locally': {
+    title: 'No reference image',
+    body: 'This device has no reference image saved locally — re-attach the device or restore from backup.',
+  },
+  'remote already contains a Relicario vault': {
+    title: 'Vault already exists',
+    body: 'The selected repository already contains a vault — use Attach existing instead of Create new.',
+  },
+  'Extension not configured. Run setup first.': {
+    title: 'Extension not configured',
+    body: 'Run setup before using this action.',
+    cta: { label: 'Open setup', action: 'open_setup' },
+  },
+  'Reference image not set. Run setup first.': {
+    title: 'Reference image missing',
+    body: 'Run setup to save your reference image.',
+    cta: { label: 'Open setup', action: 'open_setup' },
+  },
+};
+
+export function lookupErrorCopy(code: string): ErrorCopy {
+  return ERROR_COPY[code] ?? {
+    title: 'Something went wrong',
+    body: code,
+  };
+}

extension/src/shared/password-coloring.ts

@@ -0,0 +1,35 @@
+export const PWD_DIGIT = 'pwd-digit';
+export const PWD_SYMBOL = 'pwd-symbol';
+export const PWD_LETTER = 'pwd-letter';
+
+type Class = typeof PWD_DIGIT | typeof PWD_SYMBOL | typeof PWD_LETTER;
+
+function classify(ch: string): Class {
+  if (/^\d$/.test(ch)) return PWD_DIGIT;
+  if (/^\p{L}$/u.test(ch)) return PWD_LETTER;
+  return PWD_SYMBOL;
+}
+
+export function colorizePassword(text: string): DocumentFragment {
+  const frag = document.createDocumentFragment();
+  if (text.length === 0) return frag;
+
+  const codepoints = Array.from(text);
+  let runStart = 0;
+  let runClass = classify(codepoints[0]);
+
+  for (let i = 1; i <= codepoints.length; i++) {
+    const c = i < codepoints.length ? classify(codepoints[i]) : null;
+    if (c !== runClass) {
+      const span = document.createElement('span');
+      span.className = runClass;
+      span.textContent = codepoints.slice(runStart, i).join('');
+      frag.appendChild(span);
+      if (c !== null) {
+        runStart = i;
+        runClass = c;
+      }
+    }
+  }
+  return frag;
+}

extension/src/vault/vault.css

@@ -38,6 +38,10 @@
 
   /* Focus */
   --focus-ring:    0 0 0 2px var(--gold-ring);
+
+  /* Password coloring (P1) */
+  --relicario-pwd-digit-color: #2563eb;
+  --relicario-pwd-symbol-color: #dc2626;
 }
 
 * {
@@ -144,6 +148,36 @@ body {
   margin-top: 8px;
 }
 
+.error-block {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+  padding: 12px 16px;
+  /* rgba channels derived from --danger (#ab2b20 = rgb(171, 43, 32)) */
+  border: 1px solid rgba(171, 43, 32, 0.4);
+  border-radius: 6px;
+  background: rgba(171, 43, 32, 0.08);
+  margin-top: 12px;
+}
+.error-block .error-title {
+  font-weight: 600;
+  color: var(--danger);
+}
+.error-block .error-body {
+  color: var(--text);
+  font-size: 12px;
+  text-align: center;
+}
+.error-block .error-cta {
+  margin-top: 6px;
+}
+
+/* Password character-class coloring */
+.pwd-digit  { color: var(--relicario-pwd-digit-color); }
+.pwd-symbol { color: var(--relicario-pwd-symbol-color); }
+.pwd-letter { color: inherit; }
+
 /* Buttons */
 .btn {
   display: inline-block;
@@ -1256,6 +1290,13 @@ textarea {
   align-items: center;
   gap: 8px;
 }
+.vault-sidebar__header .brand-logo {
+  width: 20px;
+  height: 20px;
+  margin: 0;
+  display: block;
+  flex-shrink: 0;
+}
 
 .vault-sidebar__search {
   padding: 8px 12px;
@@ -1592,6 +1633,20 @@ textarea {
 @media (max-width: 720px) {
   .form-grid { grid-template-columns: 1fr; }
 }
+
+/* P3: lower form sections constrained to the same envelope as .form-grid.
+   Gated on surface === 'fullscreen' in login.ts; popup unaffected. */
+.form-lower {
+  max-width: 960px;
+  margin: 0 auto;
+}
+.form-lower > .form-group,
+.form-lower > .disclosure,
+.form-lower > .attachments-disclosure,
+.form-lower > .form-actions {
+  width: 100%;
+}
+
 .form-col {
   padding: 14px 16px;
 }

extension/src/vault/vault.ts

@@ -9,6 +9,7 @@ import type {
   ItemId, ItemType, ManifestEntry, Item, VaultSettings, GeneratorRequest,
 } from '../shared/types';
 import { registerHost } from '../shared/state';
+import { lookupErrorCopy, type ErrorCta } from '../shared/error-copy';
 import { GLYPH_TRASH, GLYPH_DEVICES, GLYPH_SETTINGS, GLYPH_LOCK } from '../shared/glyphs';
 import { renderItemDetail } from '../popup/components/item-detail';
 import { renderItemForm } from '../popup/components/item-form';
@@ -19,6 +20,7 @@ import { renderVaultSettings as renderVaultSettingsView } from '../popup/compone
 import { renderFieldHistory, teardown as teardownFieldHistory } from '../popup/components/field-history';
 import { renderBackupPanel, teardown as teardownBackup } from './components/backup-panel';
 import { renderImportPanel, teardown as teardownImport } from './components/import-panel';
+import { applyColorScheme } from '../shared/color-scheme';
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -41,6 +43,21 @@ function escapeHtml(str: string): string {
     .replace(/'/g, ''');
 }
 
+function renderErrorBlock(code: string | null | undefined): string {
+  if (!code) return '';
+  const copy = lookupErrorCopy(code);
+  const ctaHtml = copy.cta
+    ? `<button class="btn btn-primary error-cta" data-cta="${escapeHtml(copy.cta.action ?? '')}">${escapeHtml(copy.cta.label)}</button>`
+    : '';
+  return `
+    <div class="error error-block">
+      <div class="error-title">${escapeHtml(copy.title)}</div>
+      <div class="error-body">${escapeHtml(copy.body)}</div>
+      ${ctaHtml}
+    </div>
+  `;
+}
+
 function typeIcon(t: ItemType): string {
   switch (t) {
     case 'login':       return '\u{1F511}';  // key
@@ -199,7 +216,7 @@ function renderLockScreen(app: HTMLElement): void {
       <div class="vault-lock-screen__form">
         <input type="password" id="vault-passphrase" placeholder="passphrase" autocomplete="off" />
         <button class="btn btn-primary" id="vault-unlock-btn" style="width:100%;">unlock</button>
-        ${state.error ? `<div class="error" style="text-align:center;">${escapeHtml(state.error)}</div>` : ''}
+        ${renderErrorBlock(state.error)}
       </div>
     </div>
   `;
@@ -241,6 +258,7 @@ function renderShell(app: HTMLElement): void {
     app.innerHTML = `
       <div class="vault-sidebar">
         <div class="vault-sidebar__header">
+          <img class="brand-logo" src="icons/relicario-logo-16.svg" alt="">
           <span class="brand">Relicario</span>
         </div>
         <div class="vault-sidebar__search">
@@ -592,6 +610,36 @@ async function loadManifest(): Promise<void> {
 // ---------------------------------------------------------------------------
 
 document.addEventListener('DOMContentLoaded', async () => {
+  await applyColorScheme();
+
+  chrome.storage.onChanged.addListener((changes, area) => {
+    if (area === 'sync' && 'password_display_scheme' in changes) {
+      void applyColorScheme();
+    }
+  });
+
+  // Delegated handler for .error-cta buttons — set up once on the stable root.
+  const app = document.getElementById('vault-app')!;
+  app.addEventListener('click', (e) => {
+    const btn = (e.target as HTMLElement).closest<HTMLButtonElement>('.error-cta');
+    if (!btn) return;
+    const cta = btn.dataset.cta as ErrorCta['action'];
+    switch (cta) {
+      case 'unlock': {
+        document.getElementById('vault-passphrase')?.focus();
+        break;
+      }
+      case 'open_setup': {
+        void chrome.tabs.create({ url: chrome.runtime.getURL('setup.html') });
+        break;
+      }
+      case 'reload_extension': {
+        chrome.runtime.reload();
+        break;
+      }
+    }
+  });
+
   // Check if already unlocked
   const resp = await sendMessage({ type: 'is_unlocked' });
   if (resp.ok) {

extension/tsconfig.json

@@ -12,5 +12,5 @@
     "baseUrl": "."
   },
   "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "wasm", "src/**/__tests__/**"]
+  "exclude": ["node_modules", "dist", "wasm", "src/**/__tests__/**", "src/__stubs__/**"]
 }

extension/vitest.config.ts

@@ -1,6 +1,14 @@
 import { defineConfig } from 'vitest/config';
+import path from 'path';
 
 export default defineConfig({
+  resolve: {
+    alias: {
+      // Stub the runtime-only WASM module so unit tests can import setup.ts.
+      '../relicario_wasm.js': path.resolve(__dirname, 'src/__stubs__/relicario_wasm.stub.ts'),
+      'relicario-wasm': path.resolve(__dirname, 'src/__stubs__/relicario_wasm.stub.ts'),
+    },
+  },
   test: {
     environment: 'happy-dom',
     include: ['src/**/__tests__/**/*.test.ts'],

tools/relay/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@relicario/relay",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "npx tsx server.ts",
+    "test": "node --import=tsx/esm --test queue.test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.0",
+    "@types/node": "^22.0.0"
+  }
+}

tools/relay/queue.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, beforeEach } from "node:test";
+import assert from "node:assert/strict";
+import { RelayQueue, isRole } from "./queue.ts";
+
+describe("RelayQueue", () => {
+  let q: RelayQueue;
+
+  beforeEach(() => {
+    q = new RelayQueue();
+  });
+
+  it("post + read roundtrip returns the message with correct fields", () => {
+    q.post("dev-b", "pm", "status", "Task P4 DONE");
+    const msgs = q.read("pm");
+    assert.equal(msgs.length, 1);
+    assert.equal(msgs[0].from, "dev-b");
+    assert.equal(msgs[0].to, "pm");
+    assert.equal(msgs[0].kind, "status");
+    assert.equal(msgs[0].body, "Task P4 DONE");
+    assert.ok(typeof msgs[0].id === "string" && msgs[0].id.length > 0);
+    assert.ok(typeof msgs[0].ts === "string");
+  });
+
+  it("consume-once: second read returns empty", () => {
+    q.post("dev-a", "pm", "question", "Should I use approach A?");
+    q.read("pm");
+    const second = q.read("pm");
+    assert.deepEqual(second, []);
+  });
+
+  it("list_pending does not drain inbox", () => {
+    q.post("dev-b", "pm", "directive", "PROCEED");
+    const before = q.pending("pm");
+    assert.equal(before.count, 1);
+    const after = q.read("pm");
+    assert.equal(after.length, 1);
+  });
+
+  it("FIFO ordering across multiple senders", () => {
+    q.post("dev-a", "pm", "status", "first");
+    q.post("dev-b", "pm", "status", "second");
+    q.post("dev-a", "pm", "question", "third");
+    const msgs = q.read("pm");
+    assert.equal(msgs.length, 3);
+    assert.equal(msgs[0].body, "first");
+    assert.equal(msgs[1].body, "second");
+    assert.equal(msgs[2].body, "third");
+  });
+
+  it("isRole rejects unknown strings", () => {
+    assert.ok(isRole("pm"));
+    assert.ok(isRole("dev-a"));
+    assert.ok(isRole("dev-b"));
+    assert.ok(!isRole("dev-c"));
+    assert.ok(!isRole(""));
+    assert.ok(!isRole("PM"));
+  });
+});

tools/relay/queue.ts

@@ -0,0 +1,55 @@
+import { randomUUID } from "node:crypto";
+
+export type Role = "pm" | "dev-a" | "dev-b";
+export type MessageKind = "status" | "question" | "directive" | "free";
+
+export interface RelayMessage {
+  id: string;
+  from: Role;
+  to: Role;
+  kind: MessageKind;
+  body: string;
+  ts: string;
+}
+
+const KNOWN_ROLES = new Set<string>(["pm", "dev-a", "dev-b"]);
+
+export function isRole(s: string): s is Role {
+  return KNOWN_ROLES.has(s);
+}
+
+export class RelayQueue {
+  private readonly queues = new Map<Role, RelayMessage[]>([
+    ["pm", []],
+    ["dev-a", []],
+    ["dev-b", []],
+  ]);
+
+  post(from: Role, to: Role, kind: MessageKind, body: string): RelayMessage {
+    const msg: RelayMessage = {
+      id: randomUUID(),
+      from,
+      to,
+      kind,
+      body,
+      ts: new Date().toISOString(),
+    };
+    this.queues.get(to)!.push(msg);
+    return msg;
+  }
+
+  read(forRole: Role): RelayMessage[] {
+    const inbox = this.queues.get(forRole)!;
+    const messages = [...inbox];
+    inbox.length = 0;
+    return messages;
+  }
+
+  pending(forRole: Role): { count: number; kinds: MessageKind[] } {
+    const inbox = this.queues.get(forRole)!;
+    return {
+      count: inbox.length,
+      kinds: inbox.map((m) => m.kind),
+    };
+  }
+}

tools/relay/server.ts

@@ -0,0 +1,159 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import http from "node:http";
+import { RelayQueue, isRole } from "./queue.ts";
+
+const PORT = 7331;
+const queue = new RelayQueue();
+
+const mcpServer = new Server(
+  { name: "relay", version: "0.1.0" },
+  { capabilities: { tools: {} } }
+);
+
+const TOOLS = [
+  {
+    name: "post_message",
+    description:
+      "Push a message to a recipient's inbox. Returns the assigned message id.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        from: {
+          type: "string",
+          enum: ["pm", "dev-a", "dev-b"],
+          description: "Your role name",
+        },
+        to: {
+          type: "string",
+          enum: ["pm", "dev-a", "dev-b"],
+          description: "Recipient role name",
+        },
+        kind: {
+          type: "string",
+          enum: ["status", "question", "directive", "free"],
+          description: "Message type matching the coordination protocol",
+        },
+        body: {
+          type: "string",
+          description: "Message body — freeform markdown, typically the full formatted block",
+        },
+      },
+      required: ["from", "to", "kind", "body"],
+    },
+  },
+  {
+    name: "read_messages",
+    description:
+      "Pop and return all pending messages for this recipient. Inbox is empty after this call (consume-once).",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        for: {
+          type: "string",
+          enum: ["pm", "dev-a", "dev-b"],
+          description: "Your role name",
+        },
+      },
+      required: ["for"],
+    },
+  },
+  {
+    name: "list_pending",
+    description:
+      "Return count and kinds of pending messages without consuming them.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        for: {
+          type: "string",
+          enum: ["pm", "dev-a", "dev-b"],
+          description: "Your role name",
+        },
+      },
+      required: ["for"],
+    },
+  },
+];
+
+mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  const a = args as Record<string, string>;
+
+  if (name === "post_message") {
+    if (!isRole(a.from)) {
+      return { content: [{ type: "text" as const, text: `Error: unknown role "${a.from}"` }], isError: true };
+    }
+    if (!isRole(a.to)) {
+      return { content: [{ type: "text" as const, text: `Error: unknown role "${a.to}"` }], isError: true };
+    }
+    const kind = a.kind as "status" | "question" | "directive" | "free";
+    const msg = queue.post(a.from, a.to, kind, a.body);
+    const ts = new Date(msg.ts).toTimeString().slice(0, 8);
+    const preview = a.body.slice(0, 60).replace(/\n/g, " ");
+    const ellipsis = a.body.length > 60 ? "..." : "";
+    process.stdout.write(`[${ts}] ${a.from} → ${a.to}  [${kind}]  "${preview}${ellipsis}"\n`);
+    return { content: [{ type: "text" as const, text: JSON.stringify({ id: msg.id }) }] };
+  }
+
+  if (name === "read_messages") {
+    if (!isRole(a.for)) {
+      return { content: [{ type: "text" as const, text: `Error: unknown role "${a.for}"` }], isError: true };
+    }
+    const messages = queue.read(a.for);
+    return { content: [{ type: "text" as const, text: JSON.stringify(messages) }] };
+  }
+
+  if (name === "list_pending") {
+    if (!isRole(a.for)) {
+      return { content: [{ type: "text" as const, text: `Error: unknown role "${a.for}"` }], isError: true };
+    }
+    const result = queue.pending(a.for);
+    return { content: [{ type: "text" as const, text: JSON.stringify(result) }] };
+  }
+
+  return {
+    content: [{ type: "text" as const, text: `Error: unknown tool "${name}"` }],
+    isError: true,
+  };
+});
+
+const transports = new Map<string, SSEServerTransport>();
+
+const httpServer = http.createServer(async (req, res) => {
+  try {
+    if (req.method === "GET" && req.url === "/sse") {
+      const transport = new SSEServerTransport("/message", res);
+      transports.set(transport.sessionId, transport);
+      transport.onclose = () => transports.delete(transport.sessionId);
+      await mcpServer.connect(transport);
+    } else if (req.method === "POST" && req.url?.startsWith("/message")) {
+      const url = new URL(req.url, `http://127.0.0.1:${PORT}`);
+      const sessionId = url.searchParams.get("sessionId") ?? "";
+      const transport = transports.get(sessionId);
+      if (transport) {
+        await transport.handlePostMessage(req, res);
+      } else {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "session not found" }));
+      }
+    } else {
+      res.writeHead(404).end("not found");
+    }
+  } catch (err) {
+    console.error("[relay] error:", err);
+    if (!res.headersSent) res.writeHead(500).end(String(err));
+  }
+});
+
+httpServer.listen(PORT, "127.0.0.1", () => {
+  console.log(`[relay] server ready on :${PORT}`);
+  console.log(`[relay] tools: post_message, read_messages, list_pending`);
+  console.log(`[relay] waiting for connections — Ctrl-C to stop`);
+});

tools/relay/start.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel)"
+PORT=7331
+MODE="manual"
+
+for arg in "$@"; do
+  case "$arg" in
+    --tmux)   MODE="tmux"   ;;
+    --kitty)  MODE="kitty"  ;;
+    --manual) MODE="manual" ;;
+    *) echo "Unknown option: $arg" >&2; echo "Usage: $0 [--manual|--tmux|--kitty]" >&2; exit 1 ;;
+  esac
+done
+
+# Port check
+if lsof -ti:"$PORT" &>/dev/null; then
+  echo "Error: port $PORT is already in use."
+  echo "Relay already running? Kill it with: kill \$(lsof -ti:$PORT)"
+  exit 1
+fi
+
+# Install deps (no-op if node_modules current)
+cd "$SCRIPT_DIR"
+npm install --silent
+
+# Discover latest coordination prompts for instructions
+COORD_DIR="$REPO_ROOT/docs/superpowers/coordination"
+PM_PROMPT="$(ls -t "$COORD_DIR"/*-pm-prompt.md 2>/dev/null | head -1 || echo "(none found — run multi-agent-kickoff skill first)")"
+DEV_A_PROMPT="$(ls -t "$COORD_DIR"/*-dev-a-prompt.md 2>/dev/null | head -1 || echo "(none found)")"
+DEV_B_PROMPT="$(ls -t "$COORD_DIR"/*-dev-b-prompt.md 2>/dev/null | head -1 || echo "(none found)")"
+
+print_manual_instructions() {
+  echo ""
+  echo "╔══════════════════════════════════════════════════════════════╗"
+  echo "║          RELAY SERVER — MULTI-AGENT LIFT LAUNCHER            ║"
+  echo "╚══════════════════════════════════════════════════════════════╝"
+  echo ""
+  echo "Open 3 new terminals. In each, start Claude Code and paste"
+  echo "the content BELOW the '---' line from the corresponding file."
+  echo ""
+  echo "  Terminal 1 (PM):    cat '$PM_PROMPT'"
+  echo "  Terminal 2 (Dev A): cat '$DEV_A_PROMPT'"
+  echo "  Terminal 3 (Dev B): cat '$DEV_B_PROMPT'"
+  echo ""
+  echo "This terminal becomes the relay log. Keep it open."
+  echo ""
+  echo "══════════════════════════════════════════════════════════════"
+}
+
+launch_tmux() {
+  SESSION="relay-lift"
+  tmux new-session -d -s "$SESSION" -n "relay" \
+    "cd '$SCRIPT_DIR' && npx tsx server.ts"
+  tmux new-window -t "$SESSION:" -n "pm" "cd '$REPO_ROOT' && claude"
+  tmux new-window -t "$SESSION:" -n "dev-a" "cd '$REPO_ROOT' && claude"
+  tmux new-window -t "$SESSION:" -n "dev-b" "cd '$REPO_ROOT' && claude"
+  echo ""
+  echo "[relay] Opened tmux session '$SESSION' with 4 windows: relay, pm, dev-a, dev-b."
+  echo "[relay] Paste the kickoff prompt into each Claude window."
+  echo "        Prompts:"
+  echo "          PM:    $PM_PROMPT"
+  echo "          Dev A: $DEV_A_PROMPT"
+  echo "          Dev B: $DEV_B_PROMPT"
+  echo ""
+  tmux attach-session -t "$SESSION"
+}
+
+launch_kitty() {
+  kitty @ launch --new-tab --tab-title "relay" -- \
+    bash -c "cd '$SCRIPT_DIR' && npx tsx server.ts"
+  kitty @ launch --new-window --window-title "PM" -- \
+    bash -c "cd '$REPO_ROOT' && claude"
+  kitty @ launch --new-window --window-title "Dev-A" -- \
+    bash -c "cd '$REPO_ROOT' && claude"
+  kitty @ launch --new-window --window-title "Dev-B" -- \
+    bash -c "cd '$REPO_ROOT' && claude"
+  echo ""
+  echo "[relay] Opened kitty tab 'relay' + 3 windows (PM, Dev-A, Dev-B)."
+  echo "        Paste the kickoff prompts into each Claude window."
+  echo "          PM:    $PM_PROMPT"
+  echo "          Dev A: $DEV_A_PROMPT"
+  echo "          Dev B: $DEV_B_PROMPT"
+}
+
+case "$MODE" in
+  manual)
+    print_manual_instructions
+    exec npx tsx "$SCRIPT_DIR/server.ts"
+    ;;
+  tmux)
+    launch_tmux
+    ;;
+  kitty)
+    launch_kitty
+    ;;
+esac

tools/relay/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true
+  },
+  "include": ["*.ts"]
+}