tools(relay): durable JSONL message log + pm wrapper + 120-char preview

- queue.ts: append every posted message to relay-log.jsonl (full body,
  survives the consume-once drain + restarts). gitignored.
- server.ts: bump the stdout preview from 60 to 120 chars.
- tools/relay/pm: absolute-path bash wrapper (read|pending|send) so relay
  ops work from any cwd without cd or hand-built JSON escaping.
- Fold in Dev-C's Phase 6 ARCHITECTURE.md slice as a coordination artifact.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.claude/workflows/release.js

@@ -0,0 +1,678 @@
+export const meta = {
+  name: 'release',
+  description: 'Relicario release lifecycle: develop features (single/multi-agent), iterate on debug, cut releases',
+  phases: [
+    { title: 'Discover' },
+    { title: 'Plan' },
+    { title: 'Execute' },
+    { title: 'Verify' },
+    { title: 'Generate' },
+    { title: 'Finalize' },
+    { title: 'Cleanup' },
+  ],
+}
+
+// ── Schemas ───────────────────────────────────────────────────────────────────
+
+const MANIFEST_SCHEMA = {
+  type: 'object',
+  properties: {
+    plans: { type: 'array', items: { type: 'string' } },
+    taskCount: { type: 'number' },
+    domains: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['plans', 'taskCount', 'domains'],
+}
+
+const TASK_LIST_SCHEMA = {
+  type: 'object',
+  properties: {
+    tasks: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          description: { type: 'string' },
+          planPath: { type: 'string' },
+          techDomain: { type: 'string' },
+        },
+        required: ['id', 'description', 'planPath', 'techDomain'],
+      },
+    },
+  },
+  required: ['tasks'],
+}
+
+const ASSIGNMENT_SCHEMA = {
+  type: 'object',
+  properties: {
+    devCount: { type: 'number' },
+    devs: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          letter: { type: 'string' },
+          scope: { type: 'string' },
+          tasks: { type: 'array', items: { type: 'string' } },
+          outOfScope: { type: 'array', items: { type: 'string' } },
+          techDomain: { type: 'string' },
+          planFiles: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['letter', 'scope', 'tasks', 'outOfScope', 'techDomain', 'planFiles'],
+      },
+    },
+    pmScope: { type: 'string' },
+  },
+  required: ['devCount', 'devs', 'pmScope'],
+}
+
+const DEBUG_RESULT_SCHEMA = {
+  type: 'object',
+  properties: {
+    fixed: { type: 'boolean' },
+    summary: { type: 'string' },
+    remainingFailures: { type: 'string' },
+  },
+  required: ['fixed', 'summary'],
+}
+
+const VERIFY_RESULT_SCHEMA = {
+  type: 'object',
+  properties: {
+    allPass: { type: 'boolean' },
+    failures: { type: 'array', items: { type: 'string' } },
+    summary: { type: 'string' },
+  },
+  required: ['allPass', 'failures', 'summary'],
+}
+
+const WORKTREE_STATUS_SCHEMA = {
+  type: 'object',
+  properties: {
+    stale: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          branch: { type: 'string' },
+        },
+        required: ['path', 'branch'],
+      },
+    },
+    active: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          branch: { type: 'string' },
+        },
+        required: ['path', 'branch'],
+      },
+    },
+  },
+  required: ['stale', 'active'],
+}
+
+const PLAN_STATE_SCHEMA = {
+  type: 'object',
+  properties: {
+    tickedTasks: { type: 'number' },
+    totalTasks: { type: 'number' },
+    gitEvidence: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['tickedTasks', 'totalTasks', 'gitEvidence'],
+}
+
+const BRANCH_CHECK_SCHEMA = {
+  type: 'object',
+  properties: {
+    collisions: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['collisions'],
+}
+
+const VERSION_CHECK_SCHEMA = {
+  type: 'object',
+  properties: {
+    consistent: { type: 'boolean' },
+    versions: { type: 'array', items: { type: 'string' } },
+    conflicts: { type: 'array', items: { type: 'string' } },
+    tagExists: { type: 'boolean' },
+  },
+  required: ['consistent', 'versions', 'conflicts', 'tagExists'],
+}
+
+const CLEANUP_RESULT_SCHEMA = {
+  type: 'object',
+  properties: {
+    removed: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          branch: { type: 'string' },
+        },
+        required: ['path', 'branch'],
+      },
+    },
+    kept: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          path: { type: 'string' },
+          branch: { type: 'string' },
+          reason: { type: 'string' },
+        },
+        required: ['path', 'branch', 'reason'],
+      },
+    },
+  },
+  required: ['removed', 'kept'],
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const REPO = '/home/alee/Sources/relicario'
+const COORD_DIR = 'docs/superpowers/coordination'
+
+function devRole(letter) {
+  return 'dev-' + letter.toLowerCase()
+}
+
+// ── Routing ───────────────────────────────────────────────────────────────────
+
+const action = (args && args.action) || 'develop'
+const mode   = (args && args.mode)   || 'single'
+const release = args && args.release
+const context = args && args.context
+
+// ── ACTION: preflight ─────────────────────────────────────────────────────────
+
+if (action === 'preflight') {
+  if (!release) throw new Error('args.release is required for action=preflight')
+
+  const [worktrees, baseline, planState, branches] = await parallel([
+
+    () => agent(
+      `Run: git -C ${REPO} worktree list\n` +
+      `Parse the output. For each worktree listed, extract its path and branch.\n` +
+      `Skip the main checkout at ${REPO} itself.\n` +
+      `Then run: git -C ${REPO} branch --merged main\n` +
+      `A worktree is stale if its branch appears in the merged list. Otherwise it is active.\n` +
+      `Return stale (merged worktrees) and active (unmerged worktrees), each as an array of {path, branch}.`,
+      { schema: WORKTREE_STATUS_SCHEMA, label: 'worktree-scan', phase: 'Discover' }
+    ),
+
+    () => agent(
+      `cd ${REPO} and run each of these commands, capturing the last 5 lines of output:\n` +
+      `  cargo test --quiet 2>&1 | tail -5\n` +
+      `  pnpm --filter extension test --run 2>&1 | tail -5\n` +
+      `Report allPass=true only if both commands exit with code 0. ` +
+      `List any failures with their error messages. Provide a one-line summary.`,
+      { schema: VERIFY_RESULT_SCHEMA, label: 'baseline-green', phase: 'Discover' }
+    ),
+
+    () => agent(
+      `Run: git -C ${REPO} log --oneline --all --grep="${release}" | head -20\n` +
+      `Capture the output as gitEvidence.\n` +
+      `Then scan ${REPO}/docs/superpowers/plans/ for any files whose filename contains "${release}".\n` +
+      `For each matching file, count lines matching "- \\[x\\]" (ticked) and "- \\[ \\]" (unticked).\n` +
+      `Sum across all matching files. Return tickedTasks, totalTasks, and gitEvidence (the git log lines).`,
+      { schema: PLAN_STATE_SCHEMA, label: 'plan-state', phase: 'Discover' }
+    ),
+
+    () => agent(
+      `Run: git -C ${REPO} branch --all\n` +
+      `Return any branch names (local or remote) that contain the string "${release}" as collisions.`,
+      { schema: BRANCH_CHECK_SCHEMA, label: 'branch-collision', phase: 'Discover' }
+    ),
+
+  ])
+
+  const issues = []
+
+  if (worktrees.stale.length > 0) {
+    issues.push('orphaned-worktrees')
+    log(`WARN [worktree-scan]: ${worktrees.stale.length} stale worktree(s) found — run action=cleanup to remove them`)
+    for (const w of worktrees.stale) {
+      log(`  stale: ${w.path} (${w.branch})`)
+    }
+  } else {
+    log(`[worktree-scan]: clean`)
+  }
+
+  if (!baseline.allPass) {
+    issues.push('baseline-failing')
+    log(`FAIL [baseline-green]: ${baseline.failures.length} failure(s): ${baseline.failures.join(' | ')}`)
+  } else {
+    log(`[baseline-green]: green`)
+  }
+
+  if (planState.tickedTasks > 0) {
+    issues.push('plan-partially-done')
+    log(`WARN [plan-state]: ${planState.tickedTasks}/${planState.totalTasks} tasks already ticked`)
+    for (const e of planState.gitEvidence) {
+      log(`  evidence: ${e}`)
+    }
+  } else {
+    log(`[plan-state]: clean slate (0 ticked tasks)`)
+  }
+
+  if (branches.collisions.length > 0) {
+    issues.push('branch-collision')
+    log(`WARN [branch-collision]: branches already exist for release label "${release}": ${branches.collisions.join(', ')}`)
+  } else {
+    log(`[branch-collision]: no collisions`)
+  }
+
+  if (issues.length === 0) {
+    log(`Preflight PASS`)
+  } else {
+    log(`Preflight has ${issues.length} warning(s): ${issues.join(', ')}`)
+  }
+
+  return { status: issues.length === 0 ? 'pass' : 'warn', issues, worktrees, baseline, planState, branches }
+}
+
+// ── ACTION: develop ───────────────────────────────────────────────────────────
+
+if (action === 'develop') {
+  if (!release) throw new Error('args.release is required for action=develop')
+
+  phase('Discover')
+  const manifest = await agent(
+    `Scan docs/superpowers/plans/ in ${REPO} for plan files belonging to release "${release}". ` +
+    `A plan file belongs if its filename contains the release label, or its opening lines reference it as its target release. ` +
+    `Read each matching file, count checkbox tasks (lines starting with - [ ]), and identify tech domains (rust, extension, docs, etc.). ` +
+    `Return: plans (relative paths from repo root), taskCount, domains.`,
+    { schema: MANIFEST_SCHEMA, label: 'discover-plans', phase: 'Discover' }
+  )
+
+  log(`Found ${manifest.plans.length} plan(s), ${manifest.taskCount} tasks — domains: ${manifest.domains.join(', ')}`)
+
+  // ── SINGLE MODE ─────────────────────────────────────────────────────────────
+
+  if (mode === 'single') {
+
+    phase('Plan')
+    const taskList = await agent(
+      `You are the PM for the ${release} release of Relicario at ${REPO}.\n` +
+      `Read these plan files:\n${manifest.plans.map(p => '  ' + p).join('\n')}\n\n` +
+      `Extract every checkbox task (- [ ] items) and order them to respect dependencies ` +
+      `(e.g. core Rust changes before WASM/CLI consumers, schema changes before UI). ` +
+      `For each task return: id (short slug like S1-step2), description (full step text), ` +
+      `planPath (which file it came from), techDomain (rust/extension/docs/cli/wasm).`,
+      { schema: TASK_LIST_SCHEMA, label: 'pm-plan', phase: 'Plan' }
+    )
+
+    log(`PM ordered ${taskList.tasks.length} tasks for sequential execution`)
+
+    phase('Execute')
+    await pipeline(
+      taskList.tasks,
+      (task) => agent(
+        `You are a senior developer on the ${release} release of Relicario.\n` +
+        `Repo: ${REPO}\n\n` +
+        `IMPORTANT: cd into ${REPO} before any git or cargo commands.\n\n` +
+        `Your task (${task.id}): ${task.description}\n` +
+        `Plan file for full context: ${task.planPath}\n` +
+        `Tech domain: ${task.techDomain}\n\n` +
+        `Instructions:\n` +
+        `1. Read the plan file for context on this specific step.\n` +
+        `2. Implement ONLY this step — do not run ahead to the next one.\n` +
+        `3. Run the relevant tests after your change (cargo test -p <crate> for Rust; pnpm build for extension).\n` +
+        `4. Commit with a conventional commit message scoped to the change.\n` +
+        `5. Report: what you did, test result (pass/fail), any blockers.`,
+        { label: task.id, phase: 'Execute' }
+      )
+    )
+
+    // ── Advisory: checkbox hygiene ───────────────────────────────────────────
+
+    await agent(
+      `Read each of these plan files from ${REPO}:\n${manifest.plans.map(p => '  ' + p).join('\n')}\n\n` +
+      `Count any lines still matching "- [ ]" (unticked checkboxes). ` +
+      `Log each unticked item with its file and line text. ` +
+      `This is advisory only — report findings but do not block or fail.`,
+      { label: 'checkbox-check', phase: 'Verify' }
+    )
+
+    phase('Verify')
+    const verifyResult = await agent(
+      `Run the full Relicario test suite from ${REPO}. IMPORTANT: cd ${REPO} first.\n` +
+      `Commands:\n` +
+      `  cargo test\n` +
+      `  cargo build --all-targets\n` +
+      `  cargo clippy -- -D warnings\n` +
+      `Report pass/fail for each command. List every failure with its error message.`,
+      { schema: VERIFY_RESULT_SCHEMA, label: 'full-verify', phase: 'Verify' }
+    )
+
+    if (!verifyResult.allPass) {
+      log(`Verify FAILED — ${verifyResult.failures.length} failure(s): ${verifyResult.failures.join(' | ')}`)
+      log(`Fix with: Workflow({name:"release", args:{action:"debug", context:"<paste failures>"}})`)
+      return { status: 'verify-failed', failures: verifyResult.failures, summary: verifyResult.summary }
+    }
+
+    // ── Advisory: debug artifact scan ────────────────────────────────────────
+
+    await agent(
+      `Run the following command from ${REPO}:\n` +
+      `  git -C ${REPO} diff $(git -C ${REPO} describe --tags --abbrev=0)..HEAD\n\n` +
+      `Examine lines beginning with "+" (additions) in the diff output.\n` +
+      `Report any occurrences of:\n` +
+      `  - dbg!( in Rust files (warn)\n` +
+      `  - console.log( in TypeScript files (warn)\n` +
+      `  - TODO or FIXME anywhere (warn)\n` +
+      `  - .unwrap() in Rust files (advisory note only, not a hard warn)\n` +
+      `Log each finding with its file and line. This is advisory only — do not block.`,
+      { label: 'debug-artifact-scan', phase: 'Finalize' }
+    )
+
+    phase('Finalize')
+    await agent(
+      `Update ${REPO}/STATUS.md to reflect the ${release} work that just completed.\n` +
+      `Mark any in-flight items as landed. Set what is now in flight next.\n` +
+      `Commit the STATUS.md update with message "docs: update STATUS for ${release} develop pass".`,
+      { label: 'update-status', phase: 'Finalize' }
+    )
+
+    log(`Single-mode develop complete. Run action=release when ready to tag.`)
+    return { status: 'complete', mode: 'single', release }
+  }
+
+  // ── MULTI MODE ──────────────────────────────────────────────────────────────
+
+  phase('Plan')
+  const assignment = await agent(
+    `You are the PM for the ${release} release of Relicario at ${REPO}.\n` +
+    `Read these plan files:\n${manifest.plans.map(p => '  ' + p).join('\n')}\n\n` +
+    `Decide how many dev streams are needed (one per major domain or plan, max 3). ` +
+    `Minimize cross-dev dependencies. For each dev assign: ` +
+    `letter (A/B/C), scope summary (2 sentences), task IDs they own, ` +
+    `out-of-scope task IDs (owned by other devs), primary techDomain, and which planFiles they need to read. ` +
+    `Also write a 2-sentence pmScope describing your oversight and review duties.`,
+    { schema: ASSIGNMENT_SCHEMA, label: 'pm-assign', phase: 'Plan' }
+  )
+
+  log(`PM assigned ${assignment.devCount} dev stream(s)`)
+
+  phase('Generate')
+  const allRoles = ['pm', ...assignment.devs.map(d => devRole(d.letter))].join(', ')
+
+  await parallel([
+
+    () => agent(
+      `Write a self-contained PM kickoff prompt to ${REPO}/${COORD_DIR}/${release}-pm-prompt.md.\n\n` +
+      `Release: ${release}\n` +
+      `PM scope: ${assignment.pmScope}\n` +
+      `Plans: ${manifest.plans.join(', ')}\n` +
+      `Dev roster:\n${assignment.devs.map(d => `  Dev-${d.letter}: ${d.scope}`).join('\n')}\n\n` +
+      `The file must include these sections in order:\n` +
+      `1. Role header ("You are the PM for the ${release} release of Relicario.")\n` +
+      `2. Working directory: ${REPO}\n` +
+      `3. Required reading: CLAUDE.md, all plan files listed above\n` +
+      `4. Authority: approve scope changes, review dev PRs, write CHANGELOG entry, drive doc updates, tag release (with user approval only)\n` +
+      `5. Boundaries: write NO feature code; NO destructive ops without user confirmation\n` +
+      `6. Relay server section: localhost:7331, your from="pm", tools: post_message/read_messages/list_pending, recipients: ${allRoles}. Include Python shim fallback.\n` +
+      `7. Dev roster with each dev letter, branch name (feature/${release}-dev-X), worktree path (${REPO}.dev-x), and scope\n` +
+      `8. Coordination protocol: DIRECTIVE block format, RELEASE STATUS rollup format\n` +
+      `9. PR review procedure (gh pr view / gh pr diff)\n` +
+      `10. Pre-tag checklist (all tests pass, CHANGELOG written, STATUS.md updated, all dev PRs merged)\n` +
+      `11. First action: read all required files, emit a RELEASE STATUS block confirming context absorbed, then check all dev inboxes\n` +
+      `Make every section concrete — the receiving Claude has zero prior context.`,
+      { label: 'gen-pm', phase: 'Generate' }
+    ),
+
+    ...assignment.devs.map((dev) => () => agent(
+      `Write a self-contained Dev-${dev.letter} kickoff prompt to ${REPO}/${COORD_DIR}/${release}-dev-${dev.letter.toLowerCase()}-prompt.md.\n\n` +
+      `Release: ${release}\n` +
+      `Dev-${dev.letter} scope: ${dev.scope}\n` +
+      `Tasks owned: ${dev.tasks.join(', ')}\n` +
+      `Out of scope: ${dev.outOfScope.join(', ')}\n` +
+      `Tech domain: ${dev.techDomain}\n` +
+      `Plan files: ${dev.planFiles.join(', ')}\n\n` +
+      `The file must include these sections in order:\n` +
+      `1. Role header ("You are Dev-${dev.letter} for the ${release} release of Relicario.")\n` +
+      `2. Worktree setup commands (run these FIRST before anything else):\n` +
+      `   git -C ${REPO} worktree add ${REPO}.dev-${dev.letter.toLowerCase()} -b feature/${release}-dev-${dev.letter.toLowerCase()}\n` +
+      `   cd ${REPO}.dev-${dev.letter.toLowerCase()}\n` +
+      `3. Working directory after setup: ${REPO}.dev-${dev.letter.toLowerCase()}\n` +
+      `4. CRITICAL subagent rule: every subagent prompt MUST start with "cd ${REPO}.dev-${dev.letter.toLowerCase()} &&" — never rely on working-directory headers alone\n` +
+      `5. Required reading: CLAUDE.md, ${dev.planFiles.join(', ')}\n` +
+      `6. Execution mode: use superpowers:subagent-driven-development\n` +
+      `7. Scope: in-scope tasks (${dev.tasks.join(', ')}), out-of-scope (${dev.outOfScope.join(', ')})\n` +
+      `8. Hard rules from the plan (copy any HIGH-severity or acceptance-test constraints verbatim)\n` +
+      `9. Relay: localhost:7331, your from="${devRole(dev.letter)}", call read_messages before each task, post status/questions to "pm". Recipients: ${allRoles}. Include Python shim fallback.\n` +
+      `10. STATUS UPDATE format: Task / Status (COMPLETE|IN-PROGRESS|BLOCKED) / Notes (what + why) / Next — print locally AND post to pm via relay\n` +
+      `11. Final test commands for ${dev.techDomain}\n` +
+      `12. PR procedure: gh pr create targeting main, title "feat(${release}): Dev-${dev.letter} — <scope>"\n` +
+      `13. First action: run worktree setup, emit STATUS UPDATE "setup complete", start Task 1`,
+      { label: `gen-dev-${dev.letter.toLowerCase()}`, phase: 'Generate' }
+    )),
+
+  ])
+
+  // Check relay, start if needed
+  await agent(
+    `Check if the relay server is running on localhost:7331 by running: ` +
+    `curl -sf http://127.0.0.1:7331/sse --max-time 2 > /dev/null 2>&1 && echo running || echo stopped\n\n` +
+    `If the output is "stopped", start it: ` +
+    `nohup npx tsx ${REPO}/tools/relay/server.ts > /tmp/relay-${release}.log 2>&1 &\n` +
+    `Then poll curl -sf http://127.0.0.1:7331/sse --max-time 1 once per second for up to 10s. ` +
+    `Report "relay ready" or "relay failed to start (check /tmp/relay-${release}.log)".`,
+    { label: 'relay-check', phase: 'Generate' }
+  )
+
+  await agent(
+    `Write a bash launch script to ${REPO}/${COORD_DIR}/${release}-launch.sh.\n\n` +
+    `Header comment: # Auto-generated by release workflow — ${release}\n` +
+    `set -e\n\n` +
+    `Section 1 — Relay health check and auto-start:\n` +
+    `  if curl -sf http://127.0.0.1:7331/sse --max-time 2 > /dev/null 2>&1; then\n` +
+    `    echo "[relay] already running"\n` +
+    `  else\n` +
+    `    echo "[relay] starting..." && nohup npx tsx ${REPO}/tools/relay/server.ts > /tmp/relay-${release}.log 2>&1 &\n` +
+    `    for i in $(seq 1 10); do sleep 1; curl -sf http://127.0.0.1:7331/sse --max-time 1 > /dev/null 2>&1 && echo "[relay] ready" && break || true; [ $i -eq 10 ] && echo "[relay] ERROR — check /tmp/relay-${release}.log" && exit 1; done\n` +
+    `  fi\n\n` +
+    `Section 2 — tmux session. Session name is the release label.\n` +
+    `  If tmux session already exists, attach and exit.\n` +
+    `  Otherwise create a new session, then for each role (pm + each dev letter) create a named window\n` +
+    `  that runs: claude\n` +
+    `  After creating windows, print a prompt-paste cheatsheet showing which file to paste in each window.\n` +
+    `  Then attach to the session.\n\n` +
+    `Devs: ${assignment.devs.map(d => 'Dev-' + d.letter).join(', ')}\n` +
+    `Prompt files in ${COORD_DIR}:\n` +
+    `  PM:    ${release}-pm-prompt.md\n` +
+    assignment.devs.map(d => `  Dev-${d.letter}: ${release}-dev-${d.letter.toLowerCase()}-prompt.md`).join('\\n') + '\\n\\n' +
+    `After writing the file, run: chmod +x ${REPO}/${COORD_DIR}/${release}-launch.sh`,
+    { label: 'gen-launch-script', phase: 'Generate' }
+  )
+
+  log(`Prompts + launch script ready in ${COORD_DIR}/`)
+  log(`Run: ${REPO}/${COORD_DIR}/${release}-launch.sh`)
+  log(`(starts relay if needed, opens tmux session, prompts you which file to paste in each window)`)
+
+  return { status: 'prompts-ready', devCount: assignment.devCount, coordDir: COORD_DIR }
+}
+
+// ── ACTION: debug ─────────────────────────────────────────────────────────────
+
+if (action === 'debug') {
+  if (!context) throw new Error('args.context required for action=debug — describe the failure or paste test output')
+
+  let currentContext = context
+  const MAX_ITERATIONS = 5
+
+  for (let i = 1; i <= MAX_ITERATIONS; i++) {
+    phase(`Debug iteration ${i}`)
+
+    const result = await agent(
+      `You are debugging a failure in Relicario at ${REPO}. IMPORTANT: cd ${REPO} first.\n\n` +
+      `Failure context:\n${currentContext}\n\n` +
+      `Use systematic debugging:\n` +
+      `1. Form a specific hypothesis about the root cause.\n` +
+      `2. Read the relevant source files and tests.\n` +
+      `3. Implement the minimal fix — no unrelated changes.\n` +
+      `4. Run the failing test(s) to confirm they now pass.\n` +
+      `5. Run cargo test to confirm no regressions.\n` +
+      `6. Commit the fix if clean.\n\n` +
+      `Return fixed=true if all tests pass, fixed=false with remainingFailures if not.`,
+      { schema: DEBUG_RESULT_SCHEMA, label: `debug-iter-${i}` }
+    )
+
+    log(`Iteration ${i}: ${result.summary}`)
+
+    if (result.fixed) {
+      log(`Fixed after ${i} iteration(s).`)
+      return { status: 'fixed', iterations: i, summary: result.summary }
+    }
+
+    currentContext = result.remainingFailures || currentContext
+    log(`Still failing — next iteration with updated context`)
+  }
+
+  log(`Reached max iterations (${MAX_ITERATIONS}). Manual intervention needed.`)
+  return { status: 'max-iterations', lastContext: currentContext }
+}
+
+// ── ACTION: verify ────────────────────────────────────────────────────────────
+
+if (action === 'verify') {
+  phase('Verify')
+  const result = await agent(
+    `Run the full Relicario test suite from ${REPO}. IMPORTANT: cd ${REPO} first.\n` +
+    `  cargo test\n` +
+    `  cargo build --all-targets\n` +
+    `  cargo clippy -- -D warnings\n` +
+    `Report pass/fail for each. List every failure with its error text.`,
+    { schema: VERIFY_RESULT_SCHEMA, label: 'verify' }
+  )
+
+  if (result.allPass) {
+    log(`All checks pass.`)
+  } else {
+    log(`FAILED: ${result.failures.join(' | ')}`)
+    log(`Fix with: Workflow({name:"release", args:{action:"debug", context:"<paste failures>"}})`)
+  }
+
+  return result
+}
+
+// ── ACTION: release ───────────────────────────────────────────────────────────
+
+if (action === 'release') {
+  if (!release) throw new Error('args.release is required for action=release')
+
+  phase('Verify')
+  const verifyResult = await agent(
+    `Run the full Relicario test suite from ${REPO}. IMPORTANT: cd ${REPO} first.\n` +
+    `  cargo test\n` +
+    `  cargo build --all-targets\n` +
+    `  cargo clippy -- -D warnings\n` +
+    `Report pass/fail. List failures.`,
+    { schema: VERIFY_RESULT_SCHEMA, label: 'pre-release-verify' }
+  )
+
+  if (!verifyResult.allPass) {
+    log(`Tests failing — cannot cut release. Fix first with action=debug.`)
+    return { status: 'blocked', failures: verifyResult.failures }
+  }
+
+  // ── Version + tag checks ─────────────────────────────────────────────────
+
+  const versionCheck = await agent(
+    `Read ${REPO}/Cargo.toml and all files matching ${REPO}/crates/*/Cargo.toml.\n` +
+    `For each file, extract the version field from the [package] section.\n` +
+    `Check whether all extracted versions are identical.\n` +
+    `Then run: git -C ${REPO} tag -l "${release}"\n` +
+    `Set tagExists=true if the output is non-empty (the tag already exists), false otherwise.\n` +
+    `Return consistent (true if all versions match), versions (list of all extracted version strings), ` +
+    `conflicts (list of "file: version" strings for any that differ from the majority), and tagExists.`,
+    { schema: VERSION_CHECK_SCHEMA, label: 'version-tag-check', phase: 'Finalize' }
+  )
+
+  if (!versionCheck.consistent) {
+    log(`FAIL [version-tag-check]: version mismatch across crates — ${versionCheck.conflicts.join(' | ')}`)
+    return { status: 'blocked', reason: 'version-mismatch' }
+  }
+
+  if (versionCheck.tagExists) {
+    log(`FAIL [version-tag-check]: tag "${release}" already exists — cannot re-tag`)
+    return { status: 'blocked', reason: 'tag-exists' }
+  }
+
+  log(`[version-tag-check]: Versions consistent (${versionCheck.versions[0]}), tag available`)
+
+  // ── Advisory: debug artifact scan ──────────────────────────────────────────
+
+  await agent(
+    `Run the following command from ${REPO}:\n` +
+    `  git -C ${REPO} diff $(git -C ${REPO} describe --tags --abbrev=0)..HEAD\n\n` +
+    `Examine lines beginning with "+" (additions) in the diff output.\n` +
+    `Report any occurrences of:\n` +
+    `  - dbg!( in Rust files (warn)\n` +
+    `  - console.log( in TypeScript files (warn)\n` +
+    `  - TODO or FIXME anywhere (warn)\n` +
+    `  - .unwrap() in Rust files (advisory note only, not a hard warn)\n` +
+    `Log each finding with its file and line. This is advisory only — do not block.`,
+    { label: 'debug-artifact-scan', phase: 'Finalize' }
+  )
+
+  phase('Finalize')
+  await agent(
+    `Cut the ${release} release for Relicario at ${REPO}. IMPORTANT: cd ${REPO} first.\n\n` +
+    `Steps (in order):\n` +
+    `1. Run: git log $(git describe --tags --abbrev=0)..HEAD --oneline\n` +
+    `   Use that output to write a ${release} section in CHANGELOG.md — user-facing language, grouped by type.\n` +
+    `2. Update STATUS.md: mark ${release} as released, set what is next.\n` +
+    `3. Update ROADMAP.md: check off the ${release} milestone.\n` +
+    `4. Commit those doc updates: git commit -m "release: ${release}"\n` +
+    `5. Create annotated tag: git tag -a ${release} -m "Release ${release}"\n` +
+    `6. STOP. Print the tag SHA and the push command, then ask the user to confirm before pushing.\n` +
+    `   Do NOT run git push or git push --tags without explicit user confirmation.`,
+    { label: 'cut-release', phase: 'Finalize' }
+  )
+
+  return { status: 'tagged', release, note: 'Confirm and push manually.' }
+}
+
+// ── ACTION: cleanup ───────────────────────────────────────────────────────────
+
+if (action === 'cleanup') {
+  phase('Cleanup')
+
+  const result = await agent(
+    `Run: git -C ${REPO} worktree list\n` +
+    `Run: git -C ${REPO} branch --merged main\n\n` +
+    `For each worktree listed (skip the main checkout at ${REPO} itself):\n` +
+    `  - If its branch appears in the merged list:\n` +
+    `      Run: git -C ${REPO} worktree remove --force <path>\n` +
+    `      Run: git -C ${REPO} branch -d <branch>   (lowercase -d only, never -D)\n` +
+    `      Add to removed: [{path, branch}]\n` +
+    `  - If its branch does NOT appear in the merged list:\n` +
+    `      Add to kept: [{path, branch, reason: "unmerged"}]\n\n` +
+    `Return removed (worktrees that were deleted) and kept (worktrees that were left in place).`,
+    { schema: CLEANUP_RESULT_SCHEMA, label: 'cleanup', phase: 'Cleanup' }
+  )
+
+  log(`Cleanup removed ${result.removed.length} worktree(s):`)
+  for (const w of result.removed) {
+    log(`  removed: ${w.path} (${w.branch})`)
+  }
+  log(`Cleanup kept ${result.kept.length} worktree(s):`)
+  for (const w of result.kept) {
+    log(`  kept: ${w.path} (${w.branch}) — ${w.reason}`)
+  }
+
+  return { status: 'done', removed: result.removed.length, kept: result.kept.length }
+}
+
+log(`Unknown action: "${action}". Valid: develop, debug, verify, release, preflight, cleanup`)
+return { status: 'error', action }

.gitignore

@@ -8,3 +8,9 @@ extension/wasm/
 reference.jpg
 ref.jpg
 tools/relay/node_modules/
+
+# Local Gitea credentials (do not commit)
+.gitea_env_vars
+
+# Scratch reviewer subagent output (raw drafts; canonical notes live in docs/superpowers/reviews/2026-*-dev-*-notes.md)
+docs/superpowers/reviews/.dev-c-content.md

CHANGELOG.md

@@ -1,5 +1,210 @@
 # Changelog
 
+## v0.7.0 — 2026-06-01
+
+Completes the extension restructure (Plan C) begun under v0.6.0. Phases
+1/2/5 (StateHost typing, SW storage extract, the P2 cluster) shipped
+2026-05-30; this tag adds the remaining three phases — executed as three
+parallel worktree streams under PM coordination — which eliminate the
+two steepest learning cliffs in the extension and close the last
+`relicario status` CLI/extension parity gap. No crypto, wire-format, or
+Rust-API changes; this is an internal-architecture + one-feature release.
+
+### Added
+
+- **`relicario status` parity in the extension.** New `get_vault_status`
+  service-worker message returns a cached sync summary
+  `{ ahead, behind, lastSyncAt, pendingItems }` with no network call —
+  `ahead`/`behind`/`lastSyncAt` read straight off the cached git-host
+  state (populated by the `sync` handler), `pendingItems` a live count of
+  active (non-trashed) manifest entries. A sidebar-footer status indicator
+  (`vault-status.ts` → `renderStatusIndicator`) renders `N pending` /
+  `N ahead` / `N behind` / `in sync` plus a `last sync …` / `never synced`
+  line, refreshed on mount and on a manual `↻` button — no timer polling,
+  matching the no-network-without-user-intent discipline.
+
+### Changed
+
+- **Setup wizard crypto moved into the service worker.** The wizard no
+  longer imports `relicario-wasm` or orchestrates the master key directly.
+  New `create_vault` / `attach_vault` SW handlers own the full flow
+  (image-secret embed/extract, unlock, manifest+settings encrypt + push,
+  `register_device` + `addDevice`, persist config + reference image,
+  `session.setCurrent`); on failure the SessionHandle is locked then freed,
+  with ownership transferring only on success. `setup.ts` collapses from
+  ~1230 LOC to a 58-LOC UI-only shell; the six render/attach step pairs
+  become a `SetupStep` registry in the new `setup/setup-steps.ts`. Adds
+  `clearWizardState` (bound to `beforeunload` and `goto('mode')`) to wipe
+  sensitive Uint8Array fields when the wizard is abandoned. The
+  non-extension copy-vault-config-JSON escape hatch is preserved.
+- **`vault.ts` split from a 1037-LOC monolith to 194 LOC of routing +
+  state.** Extracted into five focused modules — `vault-shell` (DOM
+  scaffolding, color-scheme, onMessage wiring), `vault-sidebar` (category
+  nav, 80ms debounced search, bottom nav, status-indicator footer),
+  `vault-list` (list + row rendering), `vault-drawer` (open/close/render +
+  `ensureDrawerClosedForRoute`), `vault-form-wrapper` (wrapped form + sticky
+  bar) — plus two support modules for an acyclic split (`vault-context`,
+  the VaultController contract; `vault-router`, hash routing + pane
+  dispatch).
+- **`vault_locked` RPC intercept unified.** Lifted out of `vault.ts` into
+  the `sendMessage` wrapper in `shared/state.ts`, so both popup and
+  vault-tab surfaces share one lock-redirect path.
+- **`state.gitHost` now nulled on explicit lock**, symmetric with the
+  session-timer expiry path, so the new status indicator can't surface a
+  stale `lastSyncAt` after a lock → re-unlock within one service-worker
+  lifetime.
+
+### Internal
+
+- Three-stream parallel execution (Dev-A Phase 3, Dev-B Phase 4, Dev-C
+  Phase 6) coordinated via the relay message bus; merges sequenced
+  Phase 3 → 4 → 6 with per-phase done-criteria verification.
+- Final merged-tree validation: **423/423** vitest (62 files);
+  `npm run build:all` clean for both Chrome and Firefox targets (only the
+  pre-existing ~4 MB WASM asset-size warning). Task 7.1 done-criteria
+  sweep all green. No change to `wasm.d.ts`.
+
+## v0.6.0 — 2026-05-30
+
+Rolls up four weeks of post-v0.5.0 work into one tag: the Phase 2B
+polish foundation, the v0.5.1 train (Streams A/B/C — 3-column vault
+layout, left-nav settings, Recovery QR), the 1C-γ slice (Document
+type, attachments, device registration from popup, trash & history
+UI), the Plan B multi-stream refactor (Cycles 1+2), the vault-tab
+management surfaces revamp, and the doc-structure redesign. The
+in-flight scope outgrew the original v0.5.1 plan, so this cuts as a
+minor bump.
+
+### Added
+
+- **Recovery QR — 1-of-2 disaster-recovery path.** `image_secret` is
+  encrypted under an Argon2id-derived key from the passphrase, packed
+  into a 109-byte binary payload (magic `RREC` + version 0x01 + salt
+  + nonce + AEAD ciphertext), and rendered as a QR code that is never
+  written to disk. Surfaces:
+  - Rust core: `relicario-core/src/recovery_qr.rs` — `generate_recovery_qr` /
+    `unwrap_recovery_qr` / `recovery_qr_to_svg`. Production KDF
+    params (`m=64MiB, t=3, p=4`) live behind a private-fields type so
+    they cannot drift.
+  - WASM: `generate_recovery_qr` / `unwrap_recovery_qr` exported; the
+    session now stashes `image_secret` so the QR can be regenerated
+    without re-running steganography extraction.
+  - CLI: `relicario recovery-qr generate` (TTY render) and
+    `relicario recovery-qr unwrap` subcommands.
+  - Extension: three-state Security settings card (no QR → amber
+    warning; QR exists → green status + show/regenerate; explicit
+    view → modal with print).
+  - Setup wizard: skippable "generate before you go" banner on the
+    final step.
+- **Document item type.** New typed item for storing a signed document
+  with a primary attachment. Form takes signature + signed-on date;
+  detail view renders a signature-block layout. Wired into the popup
+  add/view/edit dispatchers. Refuses to drop its primary attachment
+  (use `purge` instead).
+- **Attachments end-to-end.** Service worker uploads attachments via
+  the GitHost putBlob path (GitHub + Gitea Git Data API with fallback);
+  popup attachments-disclosure component handles add/remove/download
+  inside all six item-type forms; `📎` indicator shows on item-list
+  rows that have attachments. Per-vault attachment bytes cap is
+  enforced both at attach-time and during backup restore.
+- **Device registration from the popup.** "Register this device"
+  triggers an inline name input + WASM keypair generation + persisted
+  device entry — no setup-wizard detour.
+- **Trash + field-history UI.** Trash view shows per-item purge
+  countdown with restore / per-item purge / empty-all actions.
+  Field-history view groups changes per field with reveal/copy
+  glyph buttons. New top-level item-history-index pane lists every
+  item that has captured history. `#history/<id>` route normalizes
+  the legacy `#field-history/<id>` URL form.
+- **3-column fullscreen vault tab.** Sidebar (200px, type-category
+  nav) + list (flex) + detail drawer (440px, slides in on row click).
+  Below 720px the drawer pushes the list full-pane. Bottom sheet for
+  "new item" type picker uses a pane-only scrim so the sidebar stays
+  interactive.
+- **Left-nav settings page.** Replaces the flat settings dump.
+  Sections grouped Device (Autofill, Display — password coloring)
+  vs Vault (Security — Recovery QR + trusted devices, Generator,
+  Retention, Backup, Import). The standalone Devices sidebar entry
+  is subsumed into Security.
+- **Two-column login form in fullscreen.** Identity (title / URL /
+  group) and Credentials (username / password / TOTP) render as
+  side-by-side glass cards above 720px viewport; single-column at
+  narrow widths. Notes / custom sections / attachments stay full-width
+  below the grid. Sticky save bar at the bottom of the form pane;
+  header shows title + dirty subtitle ("unsaved · esc to cancel" or
+  "no changes") + platform-aware save hint (⌘+S / Ctrl+S).
+- **Polish vocabulary.** Patina gold palette tokens
+  (`--gold-base` `#a88a4a` replacing the brighter `#d2ab43`),
+  `.surface-backdrop` (subtle radial top-glow + 18px grid texture)
+  applied to popup body / setup body / vault body, `.glass` card
+  class with `backdrop-filter: blur(8px)`, `.btn-primary` /
+  `.btn-secondary` button hierarchy, and `GLYPH_NEXT = '▸'` replacing
+  ASCII `→` in next/continue buttons.
+- **Vault lock-screen logo.** `<img class="brand-logo">` added to the
+  lock-screen render for parity with the popup unlock view and the
+  setup wizard.
+- **Setup wizard Style C.** Centered hero card + colored progress
+  track + glyph mode icons, replacing the prior vertical glass-card
+  wizard.
+- **Toast notification system.** Shared `showToast(message, type,
+  durationMs)` at `extension/src/shared/toast.ts`. Used for sync
+  success/failure, copy confirmation, device registration result.
+  Replaces the ad-hoc `sync-status` div.
+- **Empty-state treatments.** Popup item list (vault empty / search
+  returns nothing), vault list (section empty) — each gets a centered
+  glyph + headline + hint.
+- **Per-type glyph icons in popup item rows.** `◉ login`, `◫
+  secure_note`, `⊡ totp`, `▭ card`, `⌬ identity`, `⊹ key`,
+  `≡ document`.
+
+### Changed
+
+- **Vault-tab management surfaces revamp (2026-05-24..05-30).**
+  Settings pane splits synced (cross-device via Chrome storage) from
+  local (per-browser) controls and gains a session-timeout UI.
+  Devices pane shows SHA-256 fingerprint + added-by display + inline
+  two-step revoke confirm via glyph button. Trash pane shows per-item
+  purge countdown via `daysUntilPurge`. Field-history pane gets
+  section headers and reveal/copy glyph buttons. New shared
+  utilities: `relative-time.ts` (consolidating five duplicate inline
+  copies), webcrypto `ssh-fingerprint.ts`, shared
+  section-header / glyph-btn / kv-row / fingerprint CSS.
+- **Emoji sweep.** Every remaining UI emoji replaced with a
+  monochrome glyph constant from `shared/glyphs.ts`. The pop-out
+  button is now `⧉` (U+29C9, `GLYPH_VAULT_TAB`) instead of `&#x2934;`.
+- **License switched to GPL-3.0-or-later.** Was MIT for the early
+  prototype phase. License headers + `AUTHORS` + crate `Cargo.toml`
+  authors updated.
+- **AttachmentId expanded to 128 bits with `is_valid` check.**
+  Backup restore now validates IDs (audit I2 / B4).
+- **Per-vault attachment bytes cap enforced.** Both CLI attach and
+  backup restore (audit I3).
+
+### Internal
+
+- **Plan B multi-stream refactor (Cycles 1+2).** CLI `main.rs` split
+  into per-command modules under `crates/relicario-cli/src/commands/`
+  with a shared `git_run` helper. New `prompt_or_flag<T>` and
+  `prompt_or_flag_optional<T>` helpers compress all the `build_*_item`
+  helpers. `Vault::after_manifest_change` wrapper plus a single
+  canonical `ParamsFile` in the session avoid duplicated file-system
+  rebuilds. Core/WASM seam: `base32_decode_lenient`,
+  `parse_month_year`, `guess_mime` exported from WASM; CLI parsers
+  migrated to `relicario-core::parse`. Extracted `base32` module
+  from core, deduplicated two RFC-4648 implementations.
+- **Doc-structure redesign (2026-05-30).** Renamed `ARCHITECTURE.md`
+  → `DESIGN.md`, `docs/ARCHITECTURE.md` → `docs/CRYPTO.md`,
+  `FORMATS.md` → `docs/FORMATS.md`. Added scope headers and
+  "Next:" footers to all tour docs so the reading order is canonical.
+  `CLAUDE.md` gains a living-docs table and four discipline rules
+  (scope-boundary check, code-constant pinning, new-doc rule,
+  plan-state hygiene).
+- **CLI quality-of-life.** `gen` alias for `generate`, `-l`/`-w`
+  short flags, batched purge in `cmd_purge` and `cmd_trash_empty`.
+- **Workspace audit cycle.** Stale local branches and worktrees
+  pruned. Several plan files moved into `docs/superpowers/audits/`
+  for the record.
+
 ## v0.5.0 — 2026-05-02
 
 Three release trains roll into one tag — backup/restore + LastPass
@@ -135,12 +340,12 @@ two confirmed bugs).
   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
+  `DESIGN.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
+  advisory caveat; `docs/CRYPTO.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.

CLAUDE.md

@@ -86,10 +86,75 @@ passphrase (UTF-8 bytes) || image_secret (32 bytes from reference JPEG)
 
 Source code: `ssh://git@git.adlee.work:2222/alee/relicario.git`
 
-## Design spec
+## Planning & design specs
 
-Full threat model, entropy analysis, and architecture: `docs/superpowers/specs/2026-04-11-relicario-design.md`
+**Before starting any planning or implementation task**, search `docs/superpowers/specs/` for a spec covering the feature area, and `docs/superpowers/plans/` for any existing implementation plan. The specs are the authoritative design record; plans track per-milestone implementation details. Once a plan exists, execute it via the release workflow (see **Release lifecycle** below) — not directly via subagent-driven-development or executing-plans unless the workflow is unavailable.
 
-## Roadmap
+Core references (read before touching crypto, data model, or architecture):
+- `docs/superpowers/specs/2026-04-11-relicario-design.md` — threat model, entropy analysis, crypto pipeline, crate layout
+- `docs/superpowers/specs/2026-04-18-relicario-typed-items-design.md` — typed-item data model and envelope
+- `docs/superpowers/specs/2026-04-30-relicario-fullscreen-ux-redesign-design.md` — fullscreen UX phase plan
 
-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.
+After completing any dev iteration, update `STATUS.md` to reflect what shipped and what's now in flight. Update the component doc for any area you changed (see table below).
+
+## Release lifecycle
+
+The `release` workflow (`.claude/workflows/release.js`) is the **default execution layer** for all dev work. Invoke it via the `Workflow` tool or the `/release` skill. Full reference: `docs/superpowers/RELEASE-WORKFLOW.md`.
+
+### Standard actions
+
+| Action | When | How |
+|--------|------|-----|
+| `develop` + `mode:"single"` | Implement a plan; phone/remote; fire-and-forget | `Workflow({name:"release", args:{action:"develop", mode:"single", release:"<label>"}})` |
+| `develop` + `mode:"multi"` | Parallel streams; at PC; PM supervises devs | `Workflow({name:"release", args:{action:"develop", mode:"multi", release:"<label>"}})` |
+| `debug` | Fix a failing test or broken feature after manual testing | `Workflow({name:"release", args:{action:"debug", context:"<paste failure>"}})` |
+| `verify` | Confirm tests pass before releasing | `Workflow({name:"release", args:{action:"verify"}})` |
+| `release` | Cut and tag a version | `Workflow({name:"release", args:{action:"release", release:"<label>"}})` |
+
+### Execution defaults
+
+- **Single-plan work** → `mode:"single"`. One agent works through tasks sequentially; updates `STATUS.md` automatically on completion.
+- **Multi-plan or multi-phase work** → `mode:"multi"`. PM agent reads plans, assigns dev streams (up to 6), generates prompt files + a `<release>-launch.sh` in `docs/superpowers/coordination/`. Run the launch script — it starts the relay and opens a tmux session.
+- **Debugging** → always `action:"debug"`. Never hand-fix without at least trying the debug loop first.
+- **Releasing** → always `action:"release"`. It verifies first, writes CHANGELOG, tags, and stops before push.
+
+### Multi-agent relay
+
+The relay server (`tools/relay/`) supports roles `pm`, `dev-a` through `dev-f`. The launch script starts it automatically. If you need to start it manually: `cd tools/relay && ./start.sh`. Protocol reference: `docs/superpowers/coordination/RELAY.md`.
+
+## Roadmap & status
+
+Current in-flight work: `STATUS.md`. Full roadmap with release targets: `ROADMAP.md`. Wire format reference: `docs/FORMATS.md`.
+
+## Living docs — update discipline
+
+| File | What it documents | Update when... |
+|---|---|---|
+| `DESIGN.md` | Cross-codebase structure: four codebases, contracts, secrets map, build matrix, test strategy | Adding a codebase, changing inter-codebase contracts, new build targets |
+| `docs/CRYPTO.md` | Crypto pipeline diagrams, vault creation/unlock flows, DCT embedding, encrypted file format | Changing crypto primitives, format version byte, or file format |
+| `crates/relicario-core/ARCHITECTURE.md` | Module map, invariants, key flows, test architecture for `relicario-core` | Adding/changing modules, item types, or crypto invariants in core |
+| `crates/relicario-cli/ARCHITECTURE.md` | Module map, invariants, key flows (init, unlock, all commands) for `relicario-cli` | Adding/changing CLI commands, helpers, or session behavior |
+| `extension/ARCHITECTURE.md` | Bundle structure, SW↔popup contract, component architecture | Adding bundles, changing the SW message protocol, or major UI flows |
+| `docs/SECURITY.md` | Threat model, device auth, env-var trust surface | Adding env vars, changing auth model, new security-relevant config |
+| `docs/FORMATS.md` | Wire formats: `.enc` blobs, `params.json`, `devices.json`, manifest schema | Changing any serialized format, version number, or on-disk layout |
+| `STATUS.md` | In-flight work, recent landings, what's next | End of every dev iteration |
+| `ROADMAP.md` | Full roadmap with release targets | When milestones shift or new work is scoped |
+| `CHANGELOG.md` | User-facing release history | When tagging a release |
+
+### Discipline rules
+
+Four rules to prevent the kind of drift the 2026-05-30 audits found:
+
+1. **Scope-boundary check.** When editing a tour doc, verify the change fits the doc's scope header. If it doesn't, the change belongs in a different doc — move it instead of stretching the scope. Concretely: a sentence about crypto added to `DESIGN.md` belongs in `docs/CRYPTO.md`; a wire-format table added to `docs/CRYPTO.md` belongs in `docs/FORMATS.md`.
+
+2. **Code-constant pinning.** When a tour doc cites a code constant (`VERSION_BYTE = 0x02`, `QUANT_STEP = 50.0`, `MIN_COPIES = 5`, `MANIFEST_SCHEMA_VERSION = 2`, etc.), the doc must cite the source file + line. When the underlying constant changes, grep for the citation pattern and update the docs together with the code change in the same commit. Most drift the audit found was code-constant drift — this rule attacks it at the source.
+
+3. **New-doc rule.** When adding a tour doc, also update (a) `DESIGN.md`'s code-map, (b) the reading-order sequence (the "Next:" footer chain), and (c) the living-docs table above. A new doc that doesn't appear in all three is not done.
+
+4. **Plan-state hygiene.** Plan checkboxes and `STATUS.md`/`ROADMAP.md` must reflect what's actually shipped. Two halves:
+   - **Ship side:** when a commit lands work that maps to a plan task, tick that plan's checkboxes in the same commit (or the immediately-following docs commit). Same for `STATUS.md` — the "Up next" list does not get to lag the actual state of `main` by weeks.
+   - **Execute side:** before starting execution of a plan whose checkboxes are all unchecked, spot-check git log (`git log --oneline --all --grep <distinctive-name>`) or grep for a distinctive symbol/file the plan would create. A plan whose work already merged is the worst kind of plan to re-execute. The 2026-05-30 status-audit found Phase 2B, v0.5.1 Streams A/B/C, and 1C-γ all stealth-shipped two-to-three weeks earlier because nobody ran this check.
+
+5. **Pre-flight before develop.** Before running `action:"develop"` on any release, run `action:"preflight"` first. If preflight reports FAIL (baseline not green or version mismatch), fix the failure before proceeding. WARN results (orphaned worktrees, partially-done plan) require a judgement call — acknowledge them explicitly before proceeding.
+
+6. **Cleanup after every lift.** Once all PRs for a release are merged into main, run `Workflow({name:"release", args:{action:"cleanup"}})` to remove the lift's worktrees and feature branches. Stale worktrees accumulate silently and create confusion for the next lift's branch-collision check.

Cargo.lock

@@ -2156,7 +2156,7 @@ checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
 
 [[package]]
 name = "relicario-cli"
-version = "0.2.0"
+version = "0.7.0"
 dependencies = [
  "anyhow",
  "arboard",
@@ -2185,7 +2185,7 @@ dependencies = [
 
 [[package]]
 name = "relicario-core"
-version = "0.2.0"
+version = "0.7.0"
 dependencies = [
  "argon2",
  "base64",
@@ -2231,7 +2231,7 @@ dependencies = [
 
 [[package]]
 name = "relicario-wasm"
-version = "0.2.0"
+version = "0.7.0"
 dependencies = [
  "base64",
  "ed25519-dalek",

DESIGN.md

@@ -1,12 +1,14 @@
 # Architecture overview — Relicario
 
+> **Audience:** anyone wanting to understand the system at the cross-codebase level. This doc owns the four-codebase map, inter-codebase contracts, the secrets map (what secret lives where), the build matrix, and the global code-map index. **Does NOT own:** crypto pipeline details (see [docs/CRYPTO.md](docs/CRYPTO.md)), wire formats (see [docs/FORMATS.md](docs/FORMATS.md)), threat model (see [docs/SECURITY.md](docs/SECURITY.md)), per-crate module maps (see [crates/relicario-core/ARCHITECTURE.md](crates/relicario-core/ARCHITECTURE.md), [crates/relicario-cli/ARCHITECTURE.md](crates/relicario-cli/ARCHITECTURE.md), and [extension/ARCHITECTURE.md](extension/ARCHITECTURE.md)).
+
 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:
 >
-> - [crates/relicario-core/ARCHITECTURE.md](../../crates/relicario-core/ARCHITECTURE.md)
-> - [crates/relicario-cli/ARCHITECTURE.md](../../crates/relicario-cli/ARCHITECTURE.md)
-> - [extension/ARCHITECTURE.md](../../extension/ARCHITECTURE.md)
+> - [crates/relicario-core/ARCHITECTURE.md](crates/relicario-core/ARCHITECTURE.md)
+> - [crates/relicario-cli/ARCHITECTURE.md](crates/relicario-cli/ARCHITECTURE.md)
+> - [extension/ARCHITECTURE.md](extension/ARCHITECTURE.md)
 >
 > If you want historical *why*, see `docs/superpowers/specs/` — those are time-stamped decision artifacts. This overview describes what *is*.
 
@@ -196,10 +198,10 @@ Core tests use **fast Argon2id params** (m=256, t=1, p=1) so they don't take for
 
 | If you're working on... | Start with |
 |---|---|
-| Crypto, item types, manifest format | [`crates/relicario-core/ARCHITECTURE.md`](../../crates/relicario-core/ARCHITECTURE.md) |
-| A new CLI command or a CLI bug | [`crates/relicario-cli/ARCHITECTURE.md`](../../crates/relicario-cli/ARCHITECTURE.md) |
-| 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) |
+| Crypto, item types, manifest format | [`crates/relicario-core/ARCHITECTURE.md`](crates/relicario-core/ARCHITECTURE.md) |
+| A new CLI command or a CLI bug | [`crates/relicario-cli/ARCHITECTURE.md`](crates/relicario-cli/ARCHITECTURE.md) |
+| 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` |
@@ -211,3 +213,7 @@ Core tests use **fast Argon2id params** (m=256, t=1, p=1) so they don't take for
 ## Stale spec docs
 
 The `docs/superpowers/specs/` tree is **historical** — it captures the design decisions made at planning time. Some specs (e.g. `Plan 1A`, `1B`, `1C-α`/`β`/`γ`) describe work that has shipped. Do not edit them as if they were the architecture docs; instead update the appropriate `ARCHITECTURE.md`. The specs are valuable for *why* (why XChaCha20-Poly1305, why central-embed DCT, why two-factor with steganography); the architecture docs are valuable for *what* (current invariants, current flows, current contracts).
+
+---
+
+**Next:** [docs/CRYPTO.md](docs/CRYPTO.md) — the crypto pipeline that backs this design.

LICENSE

@@ -0,0 +1,232 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright © 2007 Free Software Foundation, Inc. <https://fsf.org/>
+
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+
+Preamble
+
+The GNU General Public License is a free, copyleft license for software and other kinds of works.
+
+The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users. We, the Free Software Foundation, use the GNU General Public License for most of our software; it applies also to any other work released this way by its authors. You can apply it to your programs, too.
+
+When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
+
+To protect your rights, we need to prevent others from denying you these rights or asking you to surrender the rights. Therefore, you have certain responsibilities if you distribute copies of the software, or if you modify it: responsibilities to respect the freedom of others.
+
+For example, if you distribute copies of such a program, whether gratis or for a fee, you must pass on to the recipients the same freedoms that you received. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights.
+
+Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this License giving you legal permission to copy, distribute and/or modify it.
+
+For the developers' and authors' protection, the GPL clearly explains that there is no warranty for this free software. For both users' and authors' sake, the GPL requires that modified versions be marked as changed, so that their problems will not be attributed erroneously to authors of previous versions.
+
+Some devices are designed to deny users access to install or run modified versions of the software inside them, although the manufacturer can do so. This is fundamentally incompatible with the aim of protecting users' freedom to change the software. The systematic pattern of such abuse occurs in the area of products for individuals to use, which is precisely where it is most unacceptable. Therefore, we have designed this version of the GPL to prohibit the practice for those products. If such problems arise substantially in other domains, we stand ready to extend this provision to those domains in future versions of the GPL, as needed to protect the freedom of users.
+
+Finally, every program is threatened constantly by software patents. States should not allow patents to restrict development and use of software on general-purpose computers, but in those that do, we wish to avoid the special danger that patents applied to a free program could make it effectively proprietary. To prevent this, the GPL assures that patents cannot be used to render the program non-free.
+
+The precise terms and conditions for copying, distribution and modification follow.
+
+TERMS AND CONDITIONS
+
+0. Definitions.
+
+“This License” refers to version 3 of the GNU General Public License.
+
+“Copyright” also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
+
+“The Program” refers to any copyrightable work licensed under this License. Each licensee is addressed as “you”. “Licensees” and “recipients” may be individuals or organizations.
+
+To “modify” a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a “modified version” of the earlier work or a work “based on” the earlier work.
+
+A “covered work” means either the unmodified Program or a work based on the Program.
+
+To “propagate” a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
+
+To “convey” a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
+
+An interactive user interface displays “Appropriate Legal Notices” to the extent that it includes a convenient and prominently visible feature that (1) displays an appropriate copyright notice, and (2) tells the user that there is no warranty for the work (except to the extent that warranties are provided), that licensees may convey the work under this License, and how to view a copy of this License. If the interface presents a list of user commands or options, such as a menu, a prominent item in the list meets this criterion.
+
+1. Source Code.
+The “source code” for a work means the preferred form of the work for making modifications to it. “Object code” means any non-source form of a work.
+
+A “Standard Interface” means an interface that either is an official standard defined by a recognized standards body, or, in the case of interfaces specified for a particular programming language, one that is widely used among developers working in that language.
+
+The “System Libraries” of an executable work include anything, other than the work as a whole, that (a) is included in the normal form of packaging a Major Component, but which is not part of that Major Component, and (b) serves only to enable use of the work with that Major Component, or to implement a Standard Interface for which an implementation is available to the public in source code form. A “Major Component”, in this context, means a major essential component (kernel, window system, and so on) of the specific operating system (if any) on which the executable work runs, or a compiler used to produce the work, or an object code interpreter used to run it.
+
+The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities. However, it does not include the work's System Libraries, or general-purpose tools or generally available free programs which are used unmodified in performing those activities but which are not part of the work. For example, Corresponding Source includes interface definition files associated with source files for the work, and the source code for shared libraries and dynamically linked subprograms that the work is specifically designed to require, such as by intimate data communication or control flow between those subprograms and other parts of the work.
+
+The Corresponding Source need not include anything that users can regenerate automatically from other parts of the Corresponding Source.
+
+The Corresponding Source for a work in source code form is that same work.
+
+2. Basic Permissions.
+All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
+
+You may make, run and propagate covered works that you do not convey, without conditions so long as your license otherwise remains in force. You may convey covered works to others for the sole purpose of having them make modifications exclusively for you, or provide you with facilities for running those works, provided that you comply with the terms of this License in conveying all material for which you do not control copyright. Those thus making or running the covered works for you must do so exclusively on your behalf, under your direction and control, on terms that prohibit them from making any copies of your copyrighted material outside their relationship with you.
+
+Conveying under any other circumstances is permitted solely under the conditions stated below. Sublicensing is not allowed; section 10 makes it unnecessary.
+
+3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
+
+When you convey a covered work, you waive any legal power to forbid circumvention of technological measures to the extent such circumvention is effected by exercising rights under this License with respect to the covered work, and you disclaim any intention to limit operation or modification of the work as a means of enforcing, against the work's users, your or third parties' legal rights to forbid circumvention of technological measures.
+
+4. Conveying Verbatim Copies.
+You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
+
+You may charge any price or no price for each copy that you convey, and you may offer support or warranty protection for a fee.
+
+5. Conveying Modified Source Versions.
+You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
+
+     a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
+
+     b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7. This requirement modifies the requirement in section 4 to “keep intact all notices”.
+
+     c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy. This License will therefore apply, along with any applicable section 7 additional terms, to the whole of the work, and all its parts, regardless of how they are packaged. This License gives no permission to license the work in any other way, but it does not invalidate such permission if you have separately received it.
+
+     d) If the work has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
+
+A compilation of a covered work with other separate and independent works, which are not by their nature extensions of the covered work, and which are not combined with it such as to form a larger program, in or on a volume of a storage or distribution medium, is called an “aggregate” if the compilation and its resulting copyright are not used to limit the access or legal rights of the compilation's users beyond what the individual works permit. Inclusion of a covered work in an aggregate does not cause this License to apply to the other parts of the aggregate.
+
+6. Conveying Non-Source Forms.
+You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License, in one of these ways:
+
+     a) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by the Corresponding Source fixed on a durable physical medium customarily used for software interchange.
+
+     b) Convey the object code in, or embodied in, a physical product (including a physical distribution medium), accompanied by a written offer, valid for at least three years and valid for as long as you offer spare parts or customer support for that product model, to give anyone who possesses the object code either (1) a copy of the Corresponding Source for all the software in the product that is covered by this License, on a durable physical medium customarily used for software interchange, for a price no more than your reasonable cost of physically performing this conveying of source, or (2) access to copy the Corresponding Source from a network server at no charge.
+
+     c) Convey individual copies of the object code with a copy of the written offer to provide the Corresponding Source. This alternative is allowed only occasionally and noncommercially, and only if you received the object code with such an offer, in accord with subsection 6b.
+
+     d) Convey the object code by offering access from a designated place (gratis or for a charge), and offer equivalent access to the Corresponding Source in the same way through the same place at no further charge. You need not require recipients to copy the Corresponding Source along with the object code. If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source. Regardless of what server hosts the Corresponding Source, you remain obligated to ensure that it is available for as long as needed to satisfy these requirements.
+
+     e) Convey the object code using peer-to-peer transmission, provided you inform other peers where the object code and Corresponding Source of the work are being offered to the general public at no charge under subsection 6d.
+
+A separable portion of the object code, whose source code is excluded from the Corresponding Source as a System Library, need not be included in conveying the object code work.
+
+A “User Product” is either (1) a “consumer product”, which means any tangible personal property which is normally used for personal, family, or household purposes, or (2) anything designed or sold for incorporation into a dwelling. In determining whether a product is a consumer product, doubtful cases shall be resolved in favor of coverage. For a particular product received by a particular user, “normally used” refers to a typical or common use of that class of product, regardless of the status of the particular user or of the way in which the particular user actually uses, or expects or is expected to use, the product. A product is a consumer product regardless of whether the product has substantial commercial, industrial or non-consumer uses, unless such uses represent the only significant mode of use of the product.
+
+“Installation Information” for a User Product means any methods, procedures, authorization keys, or other information required to install and execute modified versions of a covered work in that User Product from a modified version of its Corresponding Source. The information must suffice to ensure that the continued functioning of the modified object code is in no case prevented or interfered with solely because modification has been made.
+
+If you convey an object code work under this section in, or with, or specifically for use in, a User Product, and the conveying occurs as part of a transaction in which the right of possession and use of the User Product is transferred to the recipient in perpetuity or for a fixed term (regardless of how the transaction is characterized), the Corresponding Source conveyed under this section must be accompanied by the Installation Information. But this requirement does not apply if neither you nor any third party retains the ability to install modified object code on the User Product (for example, the work has been installed in ROM).
+
+The requirement to provide Installation Information does not include a requirement to continue to provide support service, warranty, or updates for a work that has been modified or installed by the recipient, or for the User Product in which it has been modified or installed. Access to a network may be denied when the modification itself materially and adversely affects the operation of the network or violates the rules and protocols for communication across the network.
+
+Corresponding Source conveyed, and Installation Information provided, in accord with this section must be in a format that is publicly documented (and with an implementation available to the public in source code form), and must require no special password or key for unpacking, reading or copying.
+
+7. Additional Terms.
+“Additional permissions” are terms that supplement the terms of this License by making exceptions from one or more of its conditions. Additional permissions that are applicable to the entire Program shall be treated as though they were included in this License, to the extent that they are valid under applicable law. If additional permissions apply only to part of the Program, that part may be used separately under those permissions, but the entire Program remains governed by this License without regard to the additional permissions.
+
+When you convey a copy of a covered work, you may at your option remove any additional permissions from that copy, or from any part of it. (Additional permissions may be written to require their own removal in certain cases when you modify the work.) You may place additional permissions on material, added by you to a covered work, for which you have or can give appropriate copyright permission.
+
+Notwithstanding any other provision of this License, for material you add to a covered work, you may (if authorized by the copyright holders of that material) supplement the terms of this License with terms:
+
+     a) Disclaiming warranty or limiting liability differently from the terms of sections 15 and 16 of this License; or
+
+     b) Requiring preservation of specified reasonable legal notices or author attributions in that material or in the Appropriate Legal Notices displayed by works containing it; or
+
+     c) Prohibiting misrepresentation of the origin of that material, or requiring that modified versions of such material be marked in reasonable ways as different from the original version; or
+
+     d) Limiting the use for publicity purposes of names of licensors or authors of the material; or
+
+     e) Declining to grant rights under trademark law for use of some trade names, trademarks, or service marks; or
+
+     f) Requiring indemnification of licensors and authors of that material by anyone who conveys the material (or modified versions of it) with contractual assumptions of liability to the recipient, for any liability that these contractual assumptions directly impose on those licensors and authors.
+
+All other non-permissive additional terms are considered “further restrictions” within the meaning of section 10. If the Program as you received it, or any part of it, contains a notice stating that it is governed by this License along with a term that is a further restriction, you may remove that term. If a license document contains a further restriction but permits relicensing or conveying under this License, you may add to a covered work material governed by the terms of that license document, provided that the further restriction does not survive such relicensing or conveying.
+
+If you add terms to a covered work in accord with this section, you must place, in the relevant source files, a statement of the additional terms that apply to those files, or a notice indicating where to find the applicable terms.
+
+Additional terms, permissive or non-permissive, may be stated in the form of a separately written license, or stated as exceptions; the above requirements apply either way.
+
+8. Termination.
+You may not propagate or modify a covered work except as expressly provided under this License. Any attempt otherwise to propagate or modify it is void, and will automatically terminate your rights under this License (including any patent licenses granted under the third paragraph of section 11).
+
+However, if you cease all violation of this License, then your license from a particular copyright holder is reinstated (a) provisionally, unless and until the copyright holder explicitly and finally terminates your license, and (b) permanently, if the copyright holder fails to notify you of the violation by some reasonable means prior to 60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is reinstated permanently if the copyright holder notifies you of the violation by some reasonable means, this is the first time you have received notice of violation of this License (for any work) from that copyright holder, and you cure the violation prior to 30 days after your receipt of the notice.
+
+Termination of your rights under this section does not terminate the licenses of parties who have received copies or rights from you under this License. If your rights have been terminated and not permanently reinstated, you do not qualify to receive new licenses for the same material under section 10.
+
+9. Acceptance Not Required for Having Copies.
+You are not required to accept this License in order to receive or run a copy of the Program. Ancillary propagation of a covered work occurring solely as a consequence of using peer-to-peer transmission to receive a copy likewise does not require acceptance. However, nothing other than this License grants you permission to propagate or modify any covered work. These actions infringe copyright if you do not accept this License. Therefore, by modifying or propagating a covered work, you indicate your acceptance of this License to do so.
+
+10. Automatic Licensing of Downstream Recipients.
+Each time you convey a covered work, the recipient automatically receives a license from the original licensors, to run, modify and propagate that work, subject to this License. You are not responsible for enforcing compliance by third parties with this License.
+
+An “entity transaction” is a transaction transferring control of an organization, or substantially all assets of one, or subdividing an organization, or merging organizations. If propagation of a covered work results from an entity transaction, each party to that transaction who receives a copy of the work also receives whatever licenses to the work the party's predecessor in interest had or could give under the previous paragraph, plus a right to possession of the Corresponding Source of the work from the predecessor in interest, if the predecessor has it or can get it with reasonable efforts.
+
+You may not impose any further restrictions on the exercise of the rights granted or affirmed under this License. For example, you may not impose a license fee, royalty, or other charge for exercise of rights granted under this License, and you may not initiate litigation (including a cross-claim or counterclaim in a lawsuit) alleging that any patent claim is infringed by making, using, selling, offering for sale, or importing the Program or any portion of it.
+
+11. Patents.
+A “contributor” is a copyright holder who authorizes use under this License of the Program or a work on which the Program is based. The work thus licensed is called the contributor's “contributor version”.
+
+A contributor's “essential patent claims” are all patent claims owned or controlled by the contributor, whether already acquired or hereafter acquired, that would be infringed by some manner, permitted by this License, of making, using, or selling its contributor version, but do not include claims that would be infringed only as a consequence of further modification of the contributor version. For purposes of this definition, “control” includes the right to grant patent sublicenses in a manner consistent with the requirements of this License.
+
+Each contributor grants you a non-exclusive, worldwide, royalty-free patent license under the contributor's essential patent claims, to make, use, sell, offer for sale, import and otherwise run, modify and propagate the contents of its contributor version.
+
+In the following three paragraphs, a “patent license” is any express agreement or commitment, however denominated, not to enforce a patent (such as an express permission to practice a patent or covenant not to sue for patent infringement). To “grant” such a patent license to a party means to make such an agreement or commitment not to enforce a patent against the party.
+
+If you convey a covered work, knowingly relying on a patent license, and the Corresponding Source of the work is not available for anyone to copy, free of charge and under the terms of this License, through a publicly available network server or other readily accessible means, then you must either (1) cause the Corresponding Source to be so available, or (2) arrange to deprive yourself of the benefit of the patent license for this particular work, or (3) arrange, in a manner consistent with the requirements of this License, to extend the patent license to downstream recipients. “Knowingly relying” means you have actual knowledge that, but for the patent license, your conveying the covered work in a country, or your recipient's use of the covered work in a country, would infringe one or more identifiable patents in that country that you have reason to believe are valid.
+
+If, pursuant to or in connection with a single transaction or arrangement, you convey, or propagate by procuring conveyance of, a covered work, and grant a patent license to some of the parties receiving the covered work authorizing them to use, propagate, modify or convey a specific copy of the covered work, then the patent license you grant is automatically extended to all recipients of the covered work and works based on it.
+
+A patent license is “discriminatory” if it does not include within the scope of its coverage, prohibits the exercise of, or is conditioned on the non-exercise of one or more of the rights that are specifically granted under this License. You may not convey a covered work if you are a party to an arrangement with a third party that is in the business of distributing software, under which you make payment to the third party based on the extent of your activity of conveying the work, and under which the third party grants, to any of the parties who would receive the covered work from you, a discriminatory patent license (a) in connection with copies of the covered work conveyed by you (or copies made from those copies), or (b) primarily for and in connection with specific products or compilations that contain the covered work, unless you entered into that arrangement, or that patent license was granted, prior to 28 March 2007.
+
+Nothing in this License shall be construed as excluding or limiting any implied license or other defenses to infringement that may otherwise be available to you under applicable patent law.
+
+12. No Surrender of Others' Freedom.
+If conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot convey a covered work so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not convey it at all. For example, if you agree to terms that obligate you to collect a royalty for further conveying from those to whom you convey the Program, the only way you could satisfy both those terms and this License would be to refrain entirely from conveying the Program.
+
+13. Use with the GNU Affero General Public License.
+Notwithstanding any other provision of this License, you have permission to link or combine any covered work with a work licensed under version 3 of the GNU Affero General Public License into a single combined work, and to convey the resulting work. The terms of this License will continue to apply to the part which is the covered work, but the special requirements of the GNU Affero General Public License, section 13, concerning interaction through a network will apply to the combination as such.
+
+14. Revised Versions of this License.
+The Free Software Foundation may publish revised and/or new versions of the GNU General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the Program specifies that a certain numbered version of the GNU General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that numbered version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the GNU General Public License, you may choose any version ever published by the Free Software Foundation.
+
+If the Program specifies that a proxy can decide which future versions of the GNU General Public License can be used, that proxy's public statement of acceptance of a version permanently authorizes you to choose that version for the Program.
+
+Later license versions may give you additional or different permissions. However, no additional obligations are imposed on any author or copyright holder as a result of your choosing to follow a later version.
+
+15. Disclaimer of Warranty.
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+16. Limitation of Liability.
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+17. Interpretation of Sections 15 and 16.
+If the disclaimer of warranty and limitation of liability provided above cannot be given local legal effect according to their terms, reviewing courts shall apply local law that most closely approximates an absolute waiver of all civil liability in connection with the Program, unless a warranty or assumption of liability accompanies a copy of the Program in return for a fee.
+
+END OF TERMS AND CONDITIONS
+
+How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest possible use to the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms.
+
+To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively state the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.
+
+     <one line to give the program's name and a brief idea of what it does.>
+     Copyright (C) <year>  <name of author>
+
+     This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+     This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
+
+     You should have received a copy of the GNU General Public License along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program does terminal interaction, make it output a short notice like this when it starts in an interactive mode:
+
+     <program>  Copyright (C) <year>  <name of author>
+     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+     This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, your program's commands might be different; for a GUI interface, you would use an “about box”.
+
+You should also get your employer (if you work as a programmer) or school, if any, to sign a “copyright disclaimer” for the program, if necessary. For more information on this, and how to apply and follow the GNU GPL, see <https://www.gnu.org/licenses/>.
+
+The GNU General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Lesser General Public License instead of this License. But first, please read <https://www.gnu.org/philosophy/why-not-lgpl.html>.

README.md

@@ -4,6 +4,8 @@
 
 # Relicario
 
+> **Audience:** users + evaluators. This doc owns the pitch, security-model summary, quick-start commands, reference-image explanation, recovery-QR overview, and roadmap teaser. Goes no deeper — for the system tour see [DESIGN.md](DESIGN.md), for crypto see [docs/CRYPTO.md](docs/CRYPTO.md).
+
 A git-backed, self-hostable password manager where decryption requires two independent factors: a passphrase you memorize and a reference JPEG that carries a hidden secret. Compromise of either factor alone is insufficient.
 
 The server only ever sees opaque ciphertext. There is nothing else going on. This README is the security proof.
@@ -89,6 +91,12 @@ relicario list
 # Sync with your git remote
 relicario sync
 
+# Pack the vault into a single encrypted backup file
+relicario backup export -o vault.relbak
+
+# Print a recovery QR for your image_secret (see "Recovery" below)
+relicario recovery-qr generate
+
 # Generate a random password
 relicario generate -l 32
 ```
@@ -108,34 +116,30 @@ The embedding survives:
 
 This means your reference image can live on your Instagram, your personal website, or anywhere else. It's useless without your passphrase.
 
+## Recovery: what if I lose my reference image?
+
+Without your reference image, the vault is undecryptable — that's the security model. But it also makes a lost or corrupted image a single point of failure.
+
+The mitigation is the **recovery QR**: a printable QR code that wraps your image secret behind a separate recovery passphrase you choose. If you ever lose access to the reference JPEG, scan or transcribe the QR, provide the recovery passphrase, and recover the 256-bit image secret. Combined with your normal vault passphrase, this restores access to the vault.
+
+```bash
+# Print a recovery QR (after the vault is unlocked).
+# You'll be prompted for a separate recovery passphrase.
+relicario recovery-qr generate
+
+# Recover the image_secret from a stored QR payload.
+relicario recovery-qr unwrap
+```
+
+The QR payload is an XChaCha20-Poly1305 envelope keyed by Argon2id over a domain-separated input (prefixed with `b"relicario-recovery-v1\0"`), so even if you reuse your vault passphrase as your recovery passphrase, the wrap key cannot collide with a vault master key. Both salt and nonce are freshly randomized per call, so two QRs printed from the same passphrase yield different bytes — the printed copy doesn't leak whether you've printed others.
+
+Recommended practice: print the QR, store it offline (safe, deposit box), and forget about it. The recovery passphrase is what protects the printed copy from being useful to someone who finds it.
+
 ## Architecture
 
-```
-relicario/
-├── crates/
-│   ├── relicario-core/     # Platform-agnostic library (no filesystem, no network)
-│   │   ├── crypto.rs    # Argon2id KDF + XChaCha20-Poly1305 AEAD
-│   │   ├── imgsecret.rs # DCT steganography: embed/extract 256-bit secrets in JPEGs
-│   │   ├── item.rs      # Item, Field, Manifest data model (serde)
-│   │   ├── item_types/  # Per-type cores (Login, SecureNote, Card, Identity, Key, Document, Totp)
-│   │   ├── attachment.rs # Encrypted attachment helpers (content-addressed)
-│   │   ├── settings.rs  # VaultSettings (retention, generator defaults, caps)
-│   │   ├── backup.rs    # `.relbak` encrypted-backup envelope
-│   │   ├── device.rs    # ed25519 device keys + revocation entries
-│   │   └── vault.rs     # Encrypt/decrypt items, manifest, settings
-│   ├── relicario-cli/      # CLI binary: filesystem, git, terminal I/O
-│   ├── relicario-wasm/     # Thin wasm-bindgen wrapper for the browser extension
-│   └── relicario-server/   # Pre-receive hook: device-signature verification
-├── extension/              # Chrome MV3 / Firefox WebExtension (TypeScript)
-└── docs/
-    ├── ARCHITECTURE.md    # System overview + flow diagrams
-    ├── SECURITY.md        # Manifest integrity model + threat notes
-    ├── architecture/      # Cross-codebase + per-codebase architecture docs
-    └── superpowers/
-        └── specs/         # Design specifications with full threat model
-```
+A short tour of the four codebases and how they fit together lives in [DESIGN.md](DESIGN.md). Crypto pipeline diagrams are in [docs/CRYPTO.md](docs/CRYPTO.md); the wire format reference is [docs/FORMATS.md](docs/FORMATS.md); the threat model is [docs/SECURITY.md](docs/SECURITY.md).
 
-`relicario-core` takes bytes and returns bytes. It has no knowledge of filesystems, git, or networks. This makes it portable to WASM (browser extension), Android (JNI), and iOS (Swift bridge).
+`relicario-core` is the platform-agnostic bytes-in/bytes-out heart — no filesystem, no network. The CLI binary and the browser-extension WASM bridge both consume it. See per-codebase deep-dives in `crates/*/ARCHITECTURE.md` and `extension/ARCHITECTURE.md`.
 
 ### Crypto primitives
 
@@ -206,6 +210,7 @@ The binary is at `target/release/relicario`.
 - [x] Typed items: Login, SecureNote, Identity, Card, Key, Document, TOTP
 - [x] Secure document storage (encrypted file attachments)
 - [x] Backup & restore (`.relbak` encrypted envelope)
+- [x] Recovery QR (paper-printable image_secret backup with separate passphrase)
 - [x] LastPass CSV import
 - [x] Device authentication (ed25519 commit signing + pre-receive hook)
 - [ ] Import from Bitwarden / 1Password
@@ -215,8 +220,12 @@ The binary is at `target/release/relicario`.
 
 ## License
 
-MIT
+GPL-3.0-or-later — see [LICENSE](LICENSE).
 
 ---
 
-Built by [Aaron Lee](https://adlee.work). Design spec and threat model in `docs/superpowers/specs/`.
+Built by [Aaron D. Lee](https://adlee.work). Design spec and threat model in `docs/superpowers/specs/`.
+
+---
+
+**Next:** [DESIGN.md](DESIGN.md) — the system tour.

ROADMAP.md

@@ -0,0 +1,38 @@
+# Relicario Roadmap
+
+> Living document — update alongside `STATUS.md` when milestones shift.
+> "Up next" items have specs; "Medium-term" items may have specs; "Long-term" items are direction, not committed scope.
+
+## Shipped
+
+| Version | Highlights |
+|---|---|
+| v0.7.0 *(2026-06-01)* | Extension restructure (Plan C) complete — Phases 3/4/6 merged via 3 parallel worktree streams under PM coordination: setup wizard crypto migrated into the SW (`create_vault`/`attach_vault`; `setup.ts` 1230→58 LOC + step registry); `vault.ts` split 1037→194 LOC into 5 focused + 2 support modules; `vault_locked` intercept lifted into `shared/state.ts`; `get_vault_status` SW message + sidebar status indicator closing the last `relicario status` CLI/extension parity gap |
+| v0.6.0 *(2026-05-30)* | Security audit fixes; device authentication; backup/restore + LastPass import; fullscreen UX Phases 1+2A+2B; v0.5.1 Streams A/B/C (3-column vault layout + bottom-sheet picker + toast system; left-nav settings; Recovery QR end-to-end + setup wizard Style C); 1C-γ (attachments + Document type + device registration + trash + field history); Plan B multi-stream refactor (commands/ split, prompt_or_flag, core/WASM seam); vault-tab management surfaces revamp (settings synced/local split, devices fingerprint, trash purge countdown, field-history polish, item-history-index, `#history/<id>` routing); doc-structure redesign (rename to DESIGN/CRYPTO/docs/FORMATS, scope headers + Next: footers); GPL-3.0-or-later license |
+| v0.2.0 | Typed-item rewrite (Plans 1A/1B/1C-α/β₁/β₂) |
+
+See `CHANGELOG.md` for tagged-release detail and `STATUS.md` for the per-train commit list.
+
+## Up next
+
+All three 2026-05-04 architecture-review specs are now shipped (CLI restructure = Plan B Cycles 1+2; security polish = Stream A Cycle 1; extension restructure = Plan C Phases 1–6, completed v0.7.0 2026-06-01). The next committed item is:
+
+- **Phase 4: command palette** — ⌘K global search + action dispatch across the vault tab (no spec yet)
+
+## Medium-term
+
+_(promote here once specced)_
+
+## Long-term / backlog
+
+- **Relay server** — encrypted WebSocket relay for multi-device sync without a shared git server
+  Spec: `docs/superpowers/specs/2026-05-02-relay-server-design.md`
+  Plan: `docs/superpowers/plans/2026-05-02-relay-server.md` (`c0921b1`)
+  Code skeleton: `crates/relicario-server/` exists but only houses the pre-receive hook today; the relay binary would either extend or replace it.
+- **Mobile** — Rust core compiles to ARM; JNI wrapper for Android, Swift wrapper for iOS
+
+## Non-goals (explicitly deferred or cancelled)
+
+- **Reference-image rotation** — changing the image factor without re-embedding. Back-burner, not cancelled.
+- **Per-entry subkeys** — no real-world benefit at family-vault scale; see design rationale in `docs/CRYPTO.md`.
+- **libgit2 / gitoxide** — shell-out to `git` is intentional; see `crates/relicario-cli/ARCHITECTURE.md`.

STATUS.md

@@ -0,0 +1,148 @@
+# Relicario — Project Status
+
+> Update this file at the end of every dev iteration. It is the single source of truth for what is done, in progress, and next.
+
+## Version
+
+**Last release tagged:** v0.6.0 — rolled up Phase 2B, v0.5.1 Streams A/B/C, 1C-γ, Plan B refactor (Cycles 1+2), management-surfaces revamp, and the doc-structure redesign into one tag.
+**Active track:** **extension restructure (Plan C) — COMPLETE.** All six phases merged. Phases 1, 2, 5 merged 2026-05-30; Phases 3, 4, 6 merged 2026-05-31/06-01 via three parallel worktree streams (Dev-A/B/C under PM coordination). Versions bumped to v0.7.0; tag pending.
+
+## What landed on main since the v0.5.0 version bump
+
+### Phase 2B — polish foundation + form layout (merged 2026-05-02, `5da1e52`)
+
+Spec: `docs/superpowers/specs/2026-05-02-phase-2b-form-layout-design.md`
+Plan: `docs/superpowers/plans/2026-05-02-phase-2b-polish-and-form-layout.md`
+
+- Patina gold palette tokens (`--gold-base` `#a88a4a`, `--gold-mid`, `--gold-shadow`, etc.) replacing the bright amber `#d2ab43`
+- `.surface-backdrop` (radial top-glow + 18px grid texture) on popup body, setup body, vault body
+- `.glass` card class with `backdrop-filter: blur(8px)` for unlock card, setup steps, form columns
+- `.btn-primary` / `.btn-secondary` button hierarchy alongside existing `.btn`
+- `GLYPH_NEXT = '▸'` (U+25B8) replacing ASCII `→` in next/continue buttons
+- Unlock view restructure: logo-lockup (logo + brand + tagline) + glass card + primary "unlock vault" button + secondary open-vault/settings demoted
+- Setup wizard: backdrop + glass step cards + glass mode-picker cards + ▸ on next buttons
+- Two-column login form (`surface: 'popup' | 'fullscreen'` flag on `renderForm`)
+- Sticky save bar in fullscreen forms with `externalActions` flag
+- Form header with title + dirty-state subtitle + platform-aware save hint (⌘+S / Ctrl+S)
+
+### v0.5.1 Stream A — fullscreen + popup layout polish (merged 2026-05-03, `c16adc4`)
+
+- 3-column vault tab: sidebar (200px) + list (flex) + detail drawer (440px)
+- Sidebar type-category nav replacing flat item list (All items + per-type counts)
+- Bottom sheet for "new item" type picker (pane-only scrim, sidebar stays interactive)
+- Shared toast system at `extension/src/shared/toast.ts` (`showToast(message, type, durationMs)`)
+- `GLYPH_VAULT_TAB = '⧉'` (U+29C9) replacing `⤴` pop-out button in popup
+- Per-type glyph icons in popup item rows
+- Empty-state treatments (popup list empty, popup search-empty, vault list section-empty)
+- Emoji sweep — all remaining UI emoji replaced with monochrome glyph constants
+
+### v0.5.1 Stream B — settings UX redesign (merged 2026-05-03, `bd6a301`)
+
+- Unified left-nav settings page (Device / Vault grouping)
+- Sections: Autofill (Device), Display (Device — password coloring), Security (Vault — Recovery QR + trusted devices), Generator (Vault), Retention (Vault), Backup (Vault), Import (Vault)
+- `devices` standalone sidebar entry subsumed into Security section
+
+### v0.5.1 Stream C — Recovery QR (merged 2026-05-03, `934dfe0`)
+
+Spec: `docs/superpowers/specs/2026-05-01-recovery-qr-design.md`
+Plan: `docs/superpowers/plans/2026-05-01-recovery-qr-and-entropy-floor.md`
+
+- Rust core: `relicario-core/src/recovery_qr.rs` — `generate_recovery_qr` / `unwrap_recovery_qr` / `recovery_qr_to_svg` (109-byte binary payload, never written to disk)
+- WASM bindings: `generate_recovery_qr` / `unwrap_recovery_qr` + session stores `image_secret` for regeneration
+- CLI: `relicario recovery-qr generate` / `recovery-qr unwrap` subcommands (TTY render)
+- Extension: three-state Security settings card; setup wizard "generate before you go" banner
+- Setup wizard Style C redesign — centered hero card + colored progress track + glyph mode icons (replacing the prior glass-card vertical wizard)
+
+### 1C-γ — attachments + Document type + device registration + trash + history
+
+Specs: `docs/superpowers/specs/2026-04-24-relicario-extension-1c-gamma1-design.md`, `docs/superpowers/specs/2026-04-26-relicario-extension-1c-gamma2-design.md`
+Plans: `docs/superpowers/plans/2026-04-24-relicario-extension-1c-gamma1.md`, `docs/superpowers/plans/2026-04-26-relicario-extension-1c-gamma2.md`
+
+- Core: `relicario-core/src/item_types/document.rs` (DocumentCore — signature + signed-on date)
+- Extension: Document type form + signature-block detail (`extension/src/popup/components/types/document.ts`)
+- Attachments wired into 6 type forms via shared disclosure; 📎 indicator in item list
+- Attachment cap setting (per-vault bytes cap) in vault settings; CLI enforces cap on attach
+- Service worker: trash operations (listTrashed, restoreItem, purgeItem, purgeAllTrash); batched purge
+- Device registration from the popup (no setup-wizard detour)
+- Field history end-to-end (WASM `get_field_history`, popup viewer)
+- Attachment IDs expanded to 128 bits with `is_valid` check (audit I2)
+- Per-vault attachment bytes cap enforced (audit I3)
+- IDs validated on backup restore (audit B4)
+
+### Plan B multi-stream refactor (2026-05-09 → 2026-05-25)
+
+Cycle 1:
+- Stream A: security audit fixes + docs polish (`89090a8`)
+- Stream B: `main.rs` split into `commands/` modules + `git_run` helper (`b9bd152`)
+
+Cycle 2:
+- Stream A: `prompt_or_flag<T>` + builder compression — compressed `build_*_item` helpers (`3dd1e1b`)
+- Stream B: `Vault::after_manifest_change` wrapper, single canonical `ParamsFile` in session (`3759f6a`)
+- Stream C: core/WASM seam — `base32_decode_lenient`, `parse_month_year`, `guess_mime` exported from WASM; CLI parsers migrated to `relicario-core::parse` (`e69b347`)
+
+Misc:
+- CLI: `gen` alias for `generate`, `-l`/`-w` short flags, batched purge
+- `base32` module extracted from core, two duplicate RFC-4648 impls deduplicated
+- License switched to GPL-3.0-or-later
+
+### Vault-tab management surfaces revamp (2026-05-24 → 2026-05-30)
+
+Spec: `docs/superpowers/specs/2026-05-23-vault-tab-management-surfaces-revamp-design.md`
+Plan: `docs/superpowers/plans/2026-05-24-vault-tab-management-surfaces-revamp.md`
+
+- Shared utilities: `relative-time.ts` consolidating 5 duplicate inline copies (`9da45dd`, `a587965`), webcrypto `ssh-fingerprint.ts` (`1edfa67`), shared section-header / glyph-btn / kv-row / fingerprint CSS (`367adce`), history/revoke/restore glyph constants (`c943a06`)
+- Settings pane revamp — synced/local split + session timeout UI (`299e7db`)
+- Devices pane revamp — SHA256 fingerprint + added-by display + glyph revoke with inline two-step confirm (`047df6e`)
+- Trash pane revamp — per-item purge countdown via `daysUntilPurge` + glyph restore + bottom-right empty-trash (`ed6e218`)
+- Field-history pane visual polish — section headers + glyph reveal/copy buttons (`32e674e`)
+- Item-history-index pane — top-level "items with history" list (`32e1632`)
+- Sidebar slot wiring + `#history/<id>` route with `#field-history/<id>` legacy normalization (`88d7228`)
+
+### Extension restructure — Plan C Phases 3, 4, 6 (merged 2026-05-31 → 06-01, v0.7.0)
+
+Spec: `docs/superpowers/specs/2026-05-04-extension-restructure-design.md`
+Plan: `docs/superpowers/plans/2026-05-30-extension-restructure.md`
+
+Three parallel worktree streams under PM coordination (relay-bus), completing the restructure begun with Phases 1/2/5:
+
+- **Phase 3 — setup wizard SW migration + step registry** (Dev-A, merge `9df2fee`). `create_vault` / `attach_vault` SW handlers own the full vault-creation/attach flow (embed/unlock, encrypt+push, register_device+addDevice, persist config+image, `session.setCurrent`; failure path locks+frees the handle). `setup.ts` collapses 1230→58 LOC (UI-only shell, no `relicario-wasm` import); step registry + state + `clearWizardState` + `finishSetup` extracted to new `setup/setup-steps.ts`. `clearWizardState` bound to `beforeunload` + `goto('mode')`. Copy-vault-JSON escape hatch preserved.
+- **Phase 4 — vault.ts split + vault_locked lift** (Dev-B, merge `3b8368d`). `vault.ts` 1037→194 LOC. Five named modules (`vault-shell`, `vault-sidebar`, `vault-list`, `vault-drawer`, `vault-form-wrapper`) plus two support modules (`vault-context` — the VaultController contract; `vault-router` — hash routing + pane dispatch, to hold vault.ts ≤250). `vault_locked` RPC intercept lifted into `shared/state.ts`'s `sendMessage` wrapper. 80ms debounced sidebar search (`SEARCH_DEBOUNCE_MS`); `ensureDrawerClosedForRoute`; `#vault-status-slot` footer staged for Phase 6.
+- **Phase 6 — get_vault_status + sidebar status indicator** (Dev-C, merge `397cc78`). `get_vault_status` SW handler returns cached `{ahead, behind, lastSyncAt, pendingItems}` with no network call; `vault-status.ts` renders the sidebar-footer indicator (`renderStatusIndicator` into `#vault-status-slot`, refreshed on mount + manual `↻` button, no timer polling). Closes the last `relicario status` CLI/extension parity gap. Also nulls `state.gitHost` on the explicit `lock` handler (symmetric with session-expiry) so the indicator can't show a stale `lastSyncAt`.
+
+Final merged-tree validation: **423/423 vitest** (62 files), `build:all` clean (only the pre-existing 4MB WASM size warning). Task 7.1 done-criteria sweep: all green.
+
+### Doc-structure redesign (2026-05-30, complete)
+
+Spec: `docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md`
+Plan: `docs/superpowers/plans/2026-05-30-doc-structure-redesign.md` (all 37 sub-step boxes ticked)
+
+- Task 1: Renamed `ARCHITECTURE.md` → `DESIGN.md`, `docs/ARCHITECTURE.md` → `docs/CRYPTO.md`, `FORMATS.md` → `docs/FORMATS.md` (`36a59cd`)
+- Task 2: Added scope headers + "Next:" footers to all tour docs (`5e7023f`)
+- Task 3: Fixed incoming links to renamed paths (`01377e7`)
+- Task 4: Updated CLAUDE.md living-docs table + added three discipline rules (`bae3f7c`)
+- Task 5: Final verification gate — all 6 steps pass cleanly (Step 3 grep had three false positives — correct new-path sibling links inside `docs/`, not stale references)
+
+### Post-audit cleanup (2026-05-30)
+
+- `STATUS.md` + `ROADMAP.md` synced with three weeks of stealth-shipped work (`72a59c6`, `0bde093`)
+- CLAUDE.md gains rule #4 (plan-state hygiene) + doc-structure plan checkboxes ticked retroactively (`cccb7d7`)
+- Vault lock-screen logo: `<img class="brand-logo">` added to `renderLockScreen` for parity with popup unlock view (`39ae629`)
+- Extension test-debt cleared: 17 stale tests (settings + devices + router) updated to match the post-Stream-B + post-revamp components — 371/371 extension + 281 Rust tests green (`797709b`, `c9802ef`, `361f3b4`)
+- v0.6.0 cut: version bumps + CHANGELOG entry covering the full v0.5.x train
+
+## In progress (uncommitted on main)
+
+- `.claude/settings.json` — harness config tweaks (kept aside intentionally)
+- Two superseded doc-plan/spec files showing modifications — `2026-04-22-relicario-extension-1c-beta1.md` and `2026-04-11-relicario-design.md` (kept aside intentionally)
+
+## Up next
+
+Per the 2026-05-30 post-v0.6.0 audit of the three 2026-05-04 architecture-review specs:
+
+- **CLI restructure** (`2026-05-04-cli-restructure-design.md`) — *already shipped* as Plan B Cycles 1+2 (`b9bd152`, `3dd1e1b`, `3759f6a`, `e69b347`); the last gap (read-side `refresh_groups_cache` callers in list/get) closed in `d717f0d`. Done-criteria all met.
+- **Security polish** (`2026-05-04-security-polish-design.md`) — *already shipped* as Stream A Cycle 1 (`89090a8`) plus follow-ups (`0c9387f` start.sh fourth window, `229e483` recovery_qr.rs docs). All four phases done.
+- **Extension restructure** (`2026-05-04-extension-restructure-design.md`, plan `docs/superpowers/plans/2026-05-30-extension-restructure.md`) — ✅ **COMPLETE** (all six phases merged; see the dated landing section above). Phases 1/2/5 merged 2026-05-30; Phases 3/4/6 merged 2026-05-31 → 06-01. Final tree: 423/423 vitest, build:all clean. v0.7.0 versions bumped; tag pending.
+
+Beyond extension restructure, ROADMAP medium-term holds Phase 4 command palette (no spec yet). Long-term: relay server, mobile.
+
+See `ROADMAP.md` for the longer arc and `CHANGELOG.md` for tagged-release history (current head: `v0.6.0`; the `v0.7.0` entry covers this extension-restructure completion).

crates/relicario-cli/ARCHITECTURE.md

@@ -1,5 +1,7 @@
 # Architecture: relicario-cli
 
+> **Audience:** contributors editing the CLI. This doc owns the CLI module map, the clap command surface, per-command key flows, session/unlock semantics, and helpers. **Does NOT own:** crypto, wire formats, or threat model (see [../../docs/CRYPTO.md](../../docs/CRYPTO.md), [../../docs/FORMATS.md](../../docs/FORMATS.md), [../../docs/SECURITY.md](../../docs/SECURITY.md)).
+
 ## What this crate is for
 
 The `relicario` binary is the platform layer for `relicario-core`: it adds
@@ -16,22 +18,46 @@ locally, and lets recovery debugging happen with familiar tooling.
 
 ## Module map
 
-The crate is three files of source and a `tests/` directory. Each source file
-has one job.
+`src/main.rs` is now a thin clap-surface + dispatcher; per-command logic lives
+under `src/commands/`. Each source file has one job.
 
-- **`src/main.rs`** (`main.rs:1-1719`) — clap surface plus every command
-  handler. Internal structure: a top-level `Cli` / `Commands` enum
-  (`main.rs:13-275`), a flat dispatcher `match` in `main()`
-  (`main.rs:277-303`), per-command handlers named `cmd_<verb>`, and a layer of
-  per-type item helpers (`build_<type>_item` for `cmd_add`, `edit_<type>` for
-  `cmd_edit`). The per-type split is recent: commit `3f0f5b1` extracted
-  ~217-line `match` arms in `cmd_add` and `cmd_edit` into focused functions,
-  one per `ItemCore` variant, so each builder/editor reads top-to-bottom and
-  can be tested through the same integration paths. Owns all clap argument
-  parsing, all interactive prompts (`prompt`, `prompt_optional`, `prompt_keep`,
-  `prompt_keep_opt`, `prompt_yesno`, `prompt_secret`), and the shared
-  `commit_paths` helper that is the single chokepoint for git commits during
-  vault mutations.
+- **`src/main.rs`** (`main.rs:1-492`) — clap surface and the flat dispatcher.
+  Owns the top-level `Cli` / `Commands` enum and every subcommand enum
+  (`AddKind`, `TrashAction`, `SettingsAction`, `BackupAction`, `ImportAction`,
+  `DeviceAction`, `RecoveryQrCmd`). `main()` is a single `match` that
+  delegates each variant to `commands::<verb>::cmd_<verb>(...)`. Also owns the
+  three test-only env-var hooks (`test_passphrase_override`,
+  `test_item_secret_override`, `test_backup_passphrase_override`) — each is
+  stripped from release builds via `#[cfg(debug_assertions)]`.
+
+- **`src/commands/`** — one module per top-level command. `mod.rs` re-exports
+  the public surface and hosts the shared `commit_paths` helper (the single
+  chokepoint for git commits during vault mutations) plus other cross-command
+  glue. Per-command modules: `init`, `add`, `get`, `list` (also hosts
+  `cmd_history`), `edit`, `trash` (rm / restore / purge / trash empty),
+  `backup` (export / restore), `import` (lastpass), `attach` (attach /
+  attachments / extract / detach), `generate`, `settings`, `sync`, `status`,
+  `rate`, `device`, `recovery_qr`. `add` and `edit` each fan out internally to
+  per-`ItemCore` helpers (`build_<type>_item`, `edit_<type>`) so each
+  builder/editor reads top-to-bottom and can be tested through the same
+  integration paths.
+
+- **`src/prompt.rs`** — interactive prompt primitives shared across commands:
+  `prompt`, `prompt_optional`, `prompt_keep`, `prompt_keep_opt`,
+  `prompt_yesno`, `prompt_secret`. `prompt_secret` honours
+  `RELICARIO_TEST_ITEM_SECRET` before falling back to `rpassword`.
+
+- **`src/parse.rs`** — pure parsers for CLI-typed inputs (e.g. MonthYear
+  expiries, TOTP `otpauth://` URIs, comma-separated tag lists). No I/O.
+
+- **`src/device.rs`** — device-management plumbing called by
+  `commands::device`: ed25519 keypair generation via `relicario-core::device`,
+  on-disk layout under `<config_dir>/relicario/devices/<name>/`, and the
+  read/write of `.relicario/devices.json` / `revoked.json`.
+
+- **`src/gitea.rs`** — minimal Gitea REST client used by `commands::device add`
+  / `revoke` to register and remove deploy keys. Reads
+  `RELICARIO_GITEA_{URL,TOKEN,OWNER,REPO}` env vars (overridable via CLI flags).
 
 - **`src/session.rs`** (`session.rs:1-152`) — `UnlockedVault` lifecycle. Holds
   the derived master key in `Zeroizing<[u8; 32]>` for one CLI invocation; the
@@ -306,13 +332,65 @@ rewrite `devices.json`, commit `device: revoke <name>`. Note that device
 keys are kept entirely separate from the KDF (passphrase × image stays
 unchanged across device add/revoke), as per the design spec.
 
-### Backup-passphrase-style commands (none yet)
+### Backup (`commands::backup`, `commands/backup.rs`)
 
-The import / export / `import-lastpass` commands described in
-`docs/superpowers/specs/2026-04-27-relicario-import-export-design.md` are
-not yet implemented. When they land they'll fit in the dispatcher
-(`main.rs:279-302`) alongside `Sync` and `Status`. Don't add stubs here
-until that work begins.
+Two subcommands, both keyed by a *backup* passphrase that is independent of
+the vault master passphrase.
+
+- **`backup export <out> [--include-image] [--image PATH] [--no-history]`** —
+  reads the entire on-disk vault layout (`.relicario/{salt,params.json,
+  devices.json}`, `manifest.enc`, `settings.enc`, every `items/*.enc`, every
+  `attachments/<iid>/<aid>.enc`), optionally bundles the reference JPEG and
+  the `.git/` directory (as an in-memory tar), and hands the lot to
+  `relicario_core::backup::pack_backup` with a zxcvbn-gated backup
+  passphrase prompted twice. The resulting `.relbak` is written via
+  `tmp` + rename. A `.relicario/last_backup` marker file (ISO-8601 line) is
+  also written so `cmd_status` can show "last backup at …".
+- **`backup restore <input> [<target>]`** — refuses to overwrite an existing
+  vault (`target/.relicario/` must not exist). Unpacks the `.relbak` via
+  `unpack_backup`, then materialises every byte into the target layout. The
+  bundled `.git/` tar is extracted via the hardened
+  `relicario_core::safe_unpack_git_archive` (path-traversal / symlink /
+  size-cap guards) with a cap of `min(100 × tar_size, 1 GiB)`; if no
+  history was bundled, the target gets a fresh `git init` + initial commit.
+
+### Import (`commands::import`, `commands/import.rs`)
+
+- **`import lastpass <csv>`** — reads the CSV, calls
+  `relicario_core::import_lastpass::parse_lastpass_csv`, then unlocks the
+  vault and writes every produced `Item` through `vault.save_item` + manifest
+  upsert. Failed rows surface as `ImportWarning`s on stderr and never abort
+  the import; only a missing or malformed header is fatal. Commit message:
+  `import: <N> items from LastPass (<csv-filename>)`. The dispatch shape
+  (`ImportAction` subcommand enum) is in place for future importers
+  (Bitwarden, 1Password, etc.) — each would add one `ImportAction` variant
+  and one helper.
+
+### Rate (`commands::rate`, `commands/rate.rs`)
+
+`rate <passphrase|->` runs `relicario_core::generators::rate_passphrase`
+(zxcvbn-backed) and prints the 0–4 score, a human-readable label, and the
+estimated guess count as `~10^N`. Reads one line from stdin when the
+argument is `-`, which keeps the passphrase out of shell history. Purely
+informational — does not unlock or mutate anything; the `init` command
+calls `validate_passphrase_strength` directly and does not consult `rate`.
+
+### RecoveryQr (`commands::recovery_qr`, `commands/recovery_qr.rs`)
+
+Two subcommands wrapping `relicario_core::recovery_qr::{generate_recovery_qr,
+unwrap_recovery_qr}`.
+
+- **`recovery-qr generate`** — re-extracts the 32-byte image_secret from the
+  reference JPEG (via `get_image_path` + `imgsecret::extract`), prompts for
+  the recovery passphrase (which may be the same as the vault passphrase or
+  different — domain-separated by core), produces the 109-byte sealed
+  payload, and renders it as a Unicode-block QR (EcLevel::M) directly to
+  stdout. The payload is **never written to disk** — the user is expected to
+  print or photograph it.
+- **`recovery-qr unwrap`** — reads a base64-encoded payload from stdin,
+  prompts for the recovery passphrase, runs `unwrap_recovery_qr`, and prints
+  the recovered `image_secret` as hex. Useful for recovery dry-runs and for
+  reconstructing a lost reference image.
 
 ## Cross-cutting concerns
 
@@ -537,3 +615,7 @@ applies to `relicario-core` unit tests, not these CLI integration tests.
   is why every `cmd_*` that takes a `query: String` (get, edit,
   history, rm, restore, purge, attach, attachments, extract, detach)
   works the same way.
+
+---
+
+**Next:** [../../extension/ARCHITECTURE.md](../../extension/ARCHITECTURE.md) — the browser-side surface.

crates/relicario-cli/Cargo.toml

@@ -1,8 +1,9 @@
 [package]
 name = "relicario-cli"
-version = "0.2.0"
+version = "0.7.0"
 edition = "2021"
 description = "CLI for relicario password manager"
+license = "GPL-3.0-or-later"
 
 [[bin]]
 name = "relicario"

crates/relicario-cli/src/commands/add.rs

@@ -0,0 +1,313 @@
+//! `relicario add <kind>` — create a new item of the given type.
+//!
+//! `cmd_add` does the common save / manifest upsert / commit dance. The seven
+//! per-type `build_*_item` helpers each return a fully-populated `Item`. The
+//! `Document` builder is the only one that needs the unlocked vault (for the
+//! attachment-cap settings + writing the encrypted blob alongside the item).
+
+use std::path::PathBuf;
+
+use anyhow::{Context, Result};
+
+use crate::AddKind;
+use crate::parse::{base32_decode_lenient, guess_mime, parse_month_year};
+use crate::prompt::{prompt, prompt_optional, prompt_or_flag, prompt_or_flag_optional, prompt_secret};
+
+pub fn cmd_add(kind: AddKind) -> Result<()> {
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let mut manifest = vault.load_manifest()?;
+
+    let item = match kind {
+        AddKind::Login { title, username, url, password_prompt, password, group, tags, favorite, totp_qr } =>
+            build_login_item(title, username, url, password_prompt, password, group, tags, favorite, totp_qr)?,
+        AddKind::SecureNote { title, body_prompt, group, tags } =>
+            build_secure_note_item(title, body_prompt, group, tags)?,
+        AddKind::Identity { title, full_name, email, phone, date_of_birth, group, tags } =>
+            build_identity_item(title, full_name, email, phone, date_of_birth, group, tags)?,
+        AddKind::Card { title, holder, expiry, kind, group, tags } =>
+            build_card_item(title, holder, expiry, kind, group, tags)?,
+        AddKind::Key { title, label, algorithm, group, tags } =>
+            build_key_item(title, label, algorithm, group, tags)?,
+        AddKind::Document { title, file, group, tags } =>
+            build_document_item(&vault, title, file, group, tags)?,
+        AddKind::Totp { title, issuer, label, secret, period, digits, algorithm, group, tags } =>
+            build_totp_item(title, issuer, label, secret, period, digits, algorithm, group, tags)?,
+    };
+
+    vault.save_item(&item)?;
+    manifest.upsert(&item);
+    vault.after_manifest_change(&manifest)?;
+
+    let mut paths: Vec<String> = vec![
+        format!("items/{}.enc", item.id.as_str()),
+        "manifest.enc".into(),
+    ];
+    for att in &item.attachments {
+        paths.push(format!("attachments/{}/{}.enc", item.id.as_str(), att.id.as_str()));
+    }
+    let path_refs: Vec<&str> = paths.iter().map(|s| s.as_str()).collect();
+    super::commit_paths(&vault, &format!("add: {} ({})", crate::helpers::sanitize_for_commit(&item.title), item.id.as_str()), &path_refs)?;
+
+    eprintln!("Added: {} (id={})", item.title, item.id.as_str());
+    Ok(())
+}
+
+#[allow(clippy::too_many_arguments)]
+fn build_login_item(
+    title: Option<String>,
+    username: Option<String>,
+    url: Option<String>,
+    password_prompt: bool,
+    password: Option<String>,
+    group: Option<String>,
+    tags: Vec<String>,
+    favorite: bool,
+    totp_qr: Option<PathBuf>,
+) -> Result<relicario_core::Item> {
+    use relicario_core::item_types::{LoginCore, TotpAlgorithm, TotpConfig, TotpKind};
+    use relicario_core::{Item, ItemCore};
+    use zeroize::Zeroizing;
+
+    let title = prompt_or_flag(title, "Title", |s| Ok(s.to_string()))?;
+    let username = prompt_or_flag_optional(username, "Username", |s| Ok(s.to_string()))?;
+    let url = prompt_or_flag_optional(url, "URL", |s| Ok(s.to_string()))?;
+    let parsed_url = match url {
+        Some(s) => Some(url::Url::parse(&s).with_context(|| format!("invalid URL: {s}"))?),
+        None => None,
+    };
+    let password = if let Some(p) = password {
+        Some(Zeroizing::new(p))
+    } else if password_prompt {
+        Some(Zeroizing::new(prompt_secret("Password: ")?))
+    } else {
+        None
+    };
+    let totp = if let Some(path) = totp_qr {
+        let secret_b32 = crate::helpers::decode_totp_qr(&path)?;
+        let secret_bytes = base32_decode_lenient(&secret_b32)?;
+        Some(TotpConfig {
+            secret: Zeroizing::new(secret_bytes),
+            algorithm: TotpAlgorithm::Sha1,
+            digits: 6,
+            period_seconds: 30,
+            kind: TotpKind::Totp,
+        })
+    } else {
+        None
+    };
+    let mut item = Item::new(title, ItemCore::Login(LoginCore {
+        username, password, url: parsed_url, totp,
+    }));
+    item.group = group;
+    item.tags = tags;
+    item.favorite = favorite;
+    Ok(item)
+}
+
+fn build_secure_note_item(
+    title: Option<String>,
+    body_prompt: bool,
+    group: Option<String>,
+    tags: Vec<String>,
+) -> Result<relicario_core::Item> {
+    use relicario_core::item_types::SecureNoteCore;
+    use relicario_core::{Item, ItemCore};
+    use zeroize::Zeroizing;
+
+    let title = prompt_or_flag(title, "Title", |s| Ok(s.to_string()))?;
+    let body = if body_prompt {
+        eprintln!("Enter note body; end with Ctrl-D on a blank line:");
+        let mut s = String::new();
+        std::io::Read::read_to_string(&mut std::io::stdin(), &mut s)?;
+        s
+    } else {
+        prompt("Body")?
+    };
+    let mut item = Item::new(title, ItemCore::SecureNote(SecureNoteCore {
+        body: Zeroizing::new(body),
+    }));
+    item.group = group;
+    item.tags = tags;
+    Ok(item)
+}
+
+fn build_identity_item(
+    title: Option<String>,
+    full_name: Option<String>,
+    email: Option<String>,
+    phone: Option<String>,
+    date_of_birth: Option<String>,
+    group: Option<String>,
+    tags: Vec<String>,
+) -> Result<relicario_core::Item> {
+    use relicario_core::item_types::IdentityCore;
+    use relicario_core::{Item, ItemCore};
+
+    let title = prompt_or_flag(title, "Title", |s| Ok(s.to_string()))?;
+    let dob = match date_of_birth {
+        Some(s) => Some(chrono::NaiveDate::parse_from_str(&s, "%Y-%m-%d")
+            .with_context(|| format!("invalid date {s} (expected YYYY-MM-DD)"))?),
+        None => None,
+    };
+    let mut item = Item::new(title, ItemCore::Identity(IdentityCore {
+        full_name, address: None, phone, email, date_of_birth: dob,
+    }));
+    item.group = group;
+    item.tags = tags;
+    Ok(item)
+}
+
+fn build_card_item(
+    title: Option<String>,
+    holder: Option<String>,
+    expiry: Option<String>,
+    kind: String,
+    group: Option<String>,
+    tags: Vec<String>,
+) -> Result<relicario_core::Item> {
+    use relicario_core::item_types::{CardCore, CardKind};
+    use relicario_core::{Item, ItemCore};
+    use zeroize::Zeroizing;
+
+    let title = prompt_or_flag(title, "Title", |s| Ok(s.to_string()))?;
+    let number = Zeroizing::new(prompt_secret("Card number: ")?);
+    let cvv = Zeroizing::new(prompt_secret("CVV (blank to skip): ")?);
+    let cvv = if cvv.is_empty() { None } else { Some(cvv) };
+    let pin = Zeroizing::new(prompt_secret("PIN (blank to skip): ")?);
+    let pin = if pin.is_empty() { None } else { Some(pin) };
+
+    let parsed_expiry = match expiry {
+        Some(s) => Some(parse_month_year(&s)?),
+        None => None,
+    };
+    let parsed_kind = match kind.as_str() {
+        "credit"  => CardKind::Credit,
+        "debit"   => CardKind::Debit,
+        "gift"    => CardKind::Gift,
+        "loyalty" => CardKind::Loyalty,
+        "other"   => CardKind::Other,
+        other => anyhow::bail!("unknown card kind: {other}"),
+    };
+
+    let mut item = Item::new(title, ItemCore::Card(CardCore {
+        number: Some(number), holder, expiry: parsed_expiry, cvv, pin, kind: parsed_kind,
+    }));
+    item.group = group;
+    item.tags = tags;
+    Ok(item)
+}
+
+fn build_key_item(
+    title: Option<String>,
+    label: Option<String>,
+    algorithm: Option<String>,
+    group: Option<String>,
+    tags: Vec<String>,
+) -> Result<relicario_core::Item> {
+    use relicario_core::item_types::KeyCore;
+    use relicario_core::{Item, ItemCore};
+    use zeroize::Zeroizing;
+
+    let title = prompt_or_flag(title, "Title", |s| Ok(s.to_string()))?;
+    eprintln!("Paste key material; end with Ctrl-D on a blank line:");
+    let mut key_material = String::new();
+    std::io::Read::read_to_string(&mut std::io::stdin(), &mut key_material)?;
+    if key_material.trim().is_empty() { anyhow::bail!("key material required"); }
+    let public_key = prompt_optional("Public key (blank to skip)")?;
+
+    let mut item = Item::new(title, ItemCore::Key(KeyCore {
+        key_material: Zeroizing::new(key_material),
+        label, public_key, algorithm,
+    }));
+    item.group = group;
+    item.tags = tags;
+    Ok(item)
+}
+
+fn build_document_item(
+    vault: &crate::session::UnlockedVault,
+    title: Option<String>,
+    file: PathBuf,
+    group: Option<String>,
+    tags: Vec<String>,
+) -> Result<relicario_core::Item> {
+    use relicario_core::item_types::DocumentCore;
+    use relicario_core::{encrypt_attachment, AttachmentRef, Item, ItemCore};
+    use std::fs;
+
+    let title = prompt_or_flag(title, "Title", |s| Ok(s.to_string()))?;
+    let bytes = fs::read(&file)
+        .with_context(|| format!("failed to read {}", file.display()))?;
+    let caps = vault.load_settings()?.attachment_caps;
+    let enc = encrypt_attachment(&bytes, vault.key(), caps.per_attachment_max_bytes)?;
+
+    let filename = file.file_name()
+        .ok_or_else(|| anyhow::anyhow!("file path has no filename: {}", file.display()))?
+        .to_string_lossy()
+        .into_owned();
+    let mime_type = guess_mime(&filename);
+
+    let primary_attachment = enc.id.clone();
+    let mut item = Item::new(title, ItemCore::Document(DocumentCore {
+        filename: filename.clone(),
+        mime_type: mime_type.clone(),
+        primary_attachment: primary_attachment.clone(),
+    }));
+    item.group = group;
+    item.tags = tags;
+    item.attachments.push(AttachmentRef {
+        id: primary_attachment.clone(),
+        filename, mime_type,
+        size: bytes.len() as u64,
+        created: item.created,
+    });
+
+    let att_dir = vault.root().join("attachments").join(item.id.as_str());
+    fs::create_dir_all(&att_dir)?;
+    fs::write(att_dir.join(format!("{}.enc", primary_attachment.as_str())), &enc.bytes)?;
+    Ok(item)
+}
+
+#[allow(clippy::too_many_arguments)]
+fn build_totp_item(
+    title: Option<String>,
+    issuer: Option<String>,
+    label: Option<String>,
+    secret: Option<String>,
+    period: u32,
+    digits: u8,
+    algorithm: String,
+    group: Option<String>,
+    tags: Vec<String>,
+) -> Result<relicario_core::Item> {
+    use relicario_core::item_types::{TotpAlgorithm, TotpConfig, TotpCore, TotpKind};
+    use relicario_core::{Item, ItemCore};
+    use zeroize::Zeroizing;
+
+    let title = prompt_or_flag(title, "Title", |s| Ok(s.to_string()))?;
+    let secret_b32 = match secret {
+        Some(s) => s,
+        None => prompt_secret("TOTP secret (base32): ")?,
+    };
+    let secret_bytes = base32_decode_lenient(&secret_b32)?;
+    let algo = match algorithm.to_ascii_lowercase().as_str() {
+        "sha1"   => TotpAlgorithm::Sha1,
+        "sha256" => TotpAlgorithm::Sha256,
+        "sha512" => TotpAlgorithm::Sha512,
+        other => anyhow::bail!("unknown algorithm: {other}"),
+    };
+
+    let mut item = Item::new(title, ItemCore::Totp(TotpCore {
+        config: TotpConfig {
+            secret: Zeroizing::new(secret_bytes),
+            algorithm: algo,
+            digits,
+            period_seconds: period,
+            kind: TotpKind::Totp,
+        },
+        issuer, label,
+    }));
+    item.group = group;
+    item.tags = tags;
+    Ok(item)
+}

crates/relicario-cli/src/commands/attach.rs

@@ -0,0 +1,175 @@
+//! `relicario attach` / `attachments` / `extract` / `detach` — per-attachment ops.
+
+use std::path::PathBuf;
+
+use anyhow::{Context, Result};
+
+use crate::parse::guess_mime;
+
+pub fn cmd_attach(query: String, file: PathBuf) -> Result<()> {
+    use std::fs;
+    use relicario_core::{encrypt_attachment, AttachmentRef};
+    use relicario_core::time::now_unix;
+
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let mut manifest = vault.load_manifest()?;
+    let entry = super::resolve_query(&manifest, &query)?;
+    let id = entry.id.clone();
+    let _ = entry;
+    let mut item = vault.load_item(&id)?;
+    let settings = vault.load_settings()?;
+    let caps = settings.attachment_caps;
+
+    if item.attachments.len() as u32 >= caps.per_item_max_count {
+        anyhow::bail!("item already has {} attachments (max {})",
+                      item.attachments.len(), caps.per_item_max_count);
+    }
+
+    let bytes = fs::read(&file)
+        .with_context(|| format!("failed to read {}", file.display()))?;
+
+    // Check per-vault total attachment bytes cap (audit I3).
+    let current_total: u64 = manifest.items.values()
+        .flat_map(|e| &e.attachment_summaries)
+        .map(|s| s.size)
+        .sum();
+    let new_size = bytes.len() as u64;
+    let hard_cap = caps.per_vault_hard_cap_bytes;
+    let soft_cap = caps.per_vault_soft_cap_bytes;
+    if current_total + new_size > hard_cap {
+        anyhow::bail!(
+            "attachment would exceed vault hard cap ({} + {} > {} bytes)",
+            current_total, new_size, hard_cap
+        );
+    }
+    if current_total + new_size > soft_cap {
+        eprintln!(
+            "warning: vault attachments will exceed soft cap ({} bytes)",
+            soft_cap
+        );
+    }
+
+    let enc = encrypt_attachment(&bytes, vault.key(), caps.per_attachment_max_bytes)?;
+
+    let filename = file.file_name()
+        .ok_or_else(|| anyhow::anyhow!("file path has no filename: {}", file.display()))?
+        .to_string_lossy()
+        .into_owned();
+    let mime_type = guess_mime(&filename);
+    let aref = AttachmentRef {
+        id: enc.id.clone(),
+        filename,
+        mime_type,
+        size: bytes.len() as u64,
+        created: now_unix(),
+    };
+
+    let att_dir = vault.root().join("attachments").join(item.id.as_str());
+    fs::create_dir_all(&att_dir)?;
+    fs::write(att_dir.join(format!("{}.enc", enc.id.as_str())), &enc.bytes)?;
+
+    item.attachments.push(aref);
+    item.modified = now_unix();
+    vault.save_item(&item)?;
+    manifest.upsert(&item);
+    vault.after_manifest_change(&manifest)?;
+
+    let paths = [
+        format!("items/{}.enc", item.id.as_str()),
+        "manifest.enc".into(),
+        format!("attachments/{}/{}.enc", item.id.as_str(), enc.id.as_str()),
+    ];
+    let path_refs: Vec<&str> = paths.iter().map(|s| s.as_str()).collect();
+    super::commit_paths(&vault, &format!("attach: {} → {} ({})",
+                                  crate::helpers::sanitize_for_commit(&file.display().to_string()),
+                                  crate::helpers::sanitize_for_commit(&item.title),
+                                  item.id.as_str()), &path_refs)?;
+    eprintln!("Attached {} to {} (aid={})", file.display(), item.title, enc.id.as_str());
+    Ok(())
+}
+
+pub fn cmd_attachments(query: String) -> Result<()> {
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let manifest = vault.load_manifest()?;
+    let entry = super::resolve_query(&manifest, &query)?;
+    let item = vault.load_item(&entry.id)?;
+    if item.attachments.is_empty() { eprintln!("(no attachments)"); return Ok(()); }
+    println!("{:<17}  {:>12}  {:<22}  FILENAME", "AID", "SIZE", "MIME");
+    for a in &item.attachments {
+        println!("{:<17}  {:>12}  {:<22}  {}", a.id.as_str(), a.size, a.mime_type, a.filename);
+    }
+    Ok(())
+}
+
+pub fn cmd_extract(query: String, aid: String, out: Option<PathBuf>) -> Result<()> {
+    use std::fs;
+    use relicario_core::decrypt_attachment;
+
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let manifest = vault.load_manifest()?;
+    let entry = super::resolve_query(&manifest, &query)?;
+    let item = vault.load_item(&entry.id)?;
+
+    let aref = item.attachments.iter().find(|a| a.id.as_str() == aid)
+        .ok_or_else(|| anyhow::anyhow!("no attachment {aid} on {}", item.title))?;
+    let path = vault.root().join("attachments").join(item.id.as_str())
+        .join(format!("{}.enc", aid));
+    let bytes = fs::read(&path)
+        .with_context(|| format!("failed to read {}", path.display()))?;
+    let plaintext = decrypt_attachment(&bytes, vault.key())?;
+    let out_path = out.unwrap_or_else(|| PathBuf::from(&aref.filename));
+    fs::write(&out_path, plaintext.as_slice())
+        .with_context(|| format!("failed to write {}", out_path.display()))?;
+    eprintln!("Wrote {} bytes to {}", plaintext.len(), out_path.display());
+    Ok(())
+}
+
+pub fn cmd_detach(query: String, aid: String) -> Result<()> {
+    use std::fs;
+    use relicario_core::ItemCore;
+    use relicario_core::time::now_unix;
+
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let mut manifest = vault.load_manifest()?;
+    let entry = super::resolve_query(&manifest, &query)?;
+    let id = entry.id.clone();
+    let _ = entry;
+    let mut item = vault.load_item(&id)?;
+
+    let pos = item.attachments.iter().position(|a| a.id.as_str() == aid)
+        .ok_or_else(|| anyhow::anyhow!("no attachment {aid} on {}", item.title))?;
+
+    // Document items keep their primary blob in the core; refuse to orphan it.
+    if let ItemCore::Document(d) = &item.core {
+        if d.primary_attachment.as_str() == aid {
+            anyhow::bail!(
+                "cannot detach the primary attachment of a Document item; \
+                 use `purge {}` to delete the whole item",
+                item.title,
+            );
+        }
+    }
+
+    let removed = item.attachments.remove(pos);
+    let blob_path = vault.root().join("attachments").join(item.id.as_str())
+        .join(format!("{}.enc", removed.id.as_str()));
+    if blob_path.exists() {
+        fs::remove_file(&blob_path)
+            .with_context(|| format!("failed to delete {}", blob_path.display()))?;
+    }
+
+    item.modified = now_unix();
+    vault.save_item(&item)?;
+    manifest.upsert(&item);
+    vault.after_manifest_change(&manifest)?;
+
+    let item_path = format!("items/{}.enc", item.id.as_str());
+    let blob_relpath = format!("attachments/{}/{}.enc", item.id.as_str(), removed.id.as_str());
+    super::commit_paths(
+        &vault,
+        &format!("detach: {} from {} ({})", crate::helpers::sanitize_for_commit(&removed.filename), crate::helpers::sanitize_for_commit(&item.title), item.id.as_str()),
+        &[&item_path, "manifest.enc", &blob_relpath],
+    )?;
+    eprintln!("Detached {} (aid={}) from {}", removed.filename, aid, item.title);
+    Ok(())
+}

crates/relicario-cli/src/commands/backup.rs

@@ -0,0 +1,303 @@
+//! `relicario backup export` / `relicario backup restore` — pack/unpack the
+//! encrypted `.relbak` envelope.
+
+use std::path::PathBuf;
+
+use anyhow::{Context, Result};
+
+use crate::BackupAction;
+
+pub fn cmd_backup(action: BackupAction) -> Result<()> {
+    match action {
+        BackupAction::Export { out, include_image, image, no_history } => {
+            cmd_backup_export(out, include_image, image, no_history)
+        }
+        BackupAction::Restore { input, target } => cmd_backup_restore(input, target),
+    }
+}
+
+pub(super) fn cmd_backup_export(
+    out: PathBuf,
+    include_image: bool,
+    image: Option<PathBuf>,
+    no_history: bool,
+) -> Result<()> {
+    use std::fs;
+    use relicario_core::{backup, validate_passphrase_strength};
+    use zeroize::Zeroizing;
+
+    let root = crate::helpers::vault_dir()?;
+
+    // Backup passphrase — prompt twice, gate on zxcvbn (audit H3).
+    let passphrase = if let Some(p) = crate::test_backup_passphrase_override() {
+        Zeroizing::new(p)
+    } else {
+        Zeroizing::new(rpassword::prompt_password("Backup passphrase: ")?)
+    };
+    let confirm = if crate::test_backup_passphrase_override().is_some() {
+        passphrase.clone()
+    } else {
+        Zeroizing::new(rpassword::prompt_password("Confirm passphrase: ")?)
+    };
+    if passphrase.as_str() != confirm.as_str() {
+        anyhow::bail!("passphrases do not match");
+    }
+    if let Err(e) = validate_passphrase_strength(&passphrase) {
+        anyhow::bail!("backup {}. Choose a longer or more entropic phrase.", e);
+    }
+
+    // Read everything from disk that the envelope needs.
+    let salt = fs::read(root.join(".relicario").join("salt"))
+        .with_context(|| "failed to read .relicario/salt")?;
+    let params_json = fs::read_to_string(root.join(".relicario").join("params.json"))
+        .with_context(|| "failed to read .relicario/params.json")?;
+    // devices.json was removed in the B1 security audit fix; fall back to
+    // an empty array so backups of post-B1 vaults still pack cleanly.
+    // Task 12 will remove the devices field from the backup format entirely.
+    let devices_json = fs::read_to_string(root.join(".relicario").join("devices.json"))
+        .unwrap_or_else(|_| "[]".to_string());
+    let manifest_enc = fs::read(root.join("manifest.enc"))
+        .with_context(|| "failed to read manifest.enc")?;
+    let settings_enc = fs::read(root.join("settings.enc"))
+        .with_context(|| "failed to read settings.enc")?;
+
+    // Items.
+    let mut item_files = Vec::new();
+    let items_dir = root.join("items");
+    if items_dir.is_dir() {
+        for entry in fs::read_dir(&items_dir)? {
+            let p = entry?.path();
+            if p.extension().and_then(|s| s.to_str()) != Some("enc") { continue; }
+            let id = p.file_stem()
+                .and_then(|s| s.to_str())
+                .ok_or_else(|| anyhow::anyhow!("bad item filename: {}", p.display()))?
+                .to_string();
+            let bytes = fs::read(&p)?;
+            item_files.push((id, bytes));
+        }
+    }
+
+    // Attachments. Layout: attachments/<item_id>/<aid>.enc
+    let mut attach_files = Vec::new();
+    let attach_dir = root.join("attachments");
+    if attach_dir.is_dir() {
+        for entry in fs::read_dir(&attach_dir)? {
+            let item_dir = entry?.path();
+            if !item_dir.is_dir() { continue; }
+            let item_id = item_dir.file_name()
+                .and_then(|s| s.to_str())
+                .ok_or_else(|| anyhow::anyhow!("bad attachment dir: {}", item_dir.display()))?
+                .to_string();
+            for sub in fs::read_dir(&item_dir)? {
+                let p = sub?.path();
+                if p.extension().and_then(|s| s.to_str()) != Some("enc") { continue; }
+                let aid = p.file_stem()
+                    .and_then(|s| s.to_str())
+                    .ok_or_else(|| anyhow::anyhow!("bad attachment filename: {}", p.display()))?
+                    .to_string();
+                let bytes = fs::read(&p)?;
+                attach_files.push((item_id.clone(), aid, bytes));
+            }
+        }
+    }
+
+    // Optional reference image.
+    let image_bytes = if include_image {
+        let path = match image {
+            Some(p) => p,
+            None => crate::session::get_image_path()?,
+        };
+        Some(fs::read(&path)
+            .with_context(|| format!("failed to read reference image {}", path.display()))?)
+    } else {
+        None
+    };
+
+    // Optional .git/ tar.
+    let git_archive = if no_history { None } else { Some(tar_directory(&root.join(".git"))?) };
+
+    let items_refs: Vec<backup::BackupItem> = item_files.iter()
+        .map(|(id, bytes)| backup::BackupItem { id: id.clone(), ciphertext: bytes })
+        .collect();
+    let attach_refs: Vec<backup::BackupAttachment> = attach_files.iter()
+        .map(|(iid, aid, bytes)| backup::BackupAttachment {
+            item_id: iid.clone(),
+            attachment_id: aid.clone(),
+            ciphertext: bytes,
+        })
+        .collect();
+
+    let input = backup::BackupInput {
+        salt: &salt,
+        params_json: &params_json,
+        devices_json: &devices_json,
+        manifest_enc: &manifest_enc,
+        settings_enc: &settings_enc,
+        items: items_refs,
+        attachments: attach_refs,
+        reference_jpg: image_bytes.as_deref(),
+        git_archive: git_archive.as_deref(),
+    };
+
+    let bytes = backup::pack_backup(input, &passphrase)?;
+
+    // atomic_write via the existing pattern: write `.tmp`, rename.
+    let tmp = {
+        let mut t = out.as_os_str().to_owned();
+        t.push(".tmp");
+        PathBuf::from(t)
+    };
+    fs::write(&tmp, &bytes)
+        .with_context(|| format!("failed to write {}", tmp.display()))?;
+    fs::rename(&tmp, &out)
+        .with_context(|| format!("failed to rename {}", out.display()))?;
+
+    // Marker file for `cmd_status`. Format: ISO-8601 UTC line.
+    let now_iso = crate::helpers::iso8601(relicario_core::now_unix());
+    fs::write(root.join(".relicario").join("last_backup"), format!("{now_iso}\n"))?;
+
+    let mib = (bytes.len() as f64) / (1024.0 * 1024.0);
+    eprintln!(
+        "Wrote {} ({:.2} MiB). Delete after restore is verified.",
+        out.display(), mib
+    );
+    Ok(())
+}
+
+/// Tar a directory into an in-memory `Vec<u8>`. Used for `.git/` bundling.
+fn tar_directory(dir: &std::path::Path) -> Result<Vec<u8>> {
+    let mut buf = Vec::new();
+    {
+        let mut builder = tar::Builder::new(&mut buf);
+        builder.append_dir_all(".", dir)
+            .with_context(|| format!("failed to tar {}", dir.display()))?;
+        builder.finish().with_context(|| "failed to finalize git tar")?;
+    }
+    Ok(buf)
+}
+
+pub(super) fn cmd_backup_restore(input: PathBuf, target: PathBuf) -> Result<()> {
+    use std::fs;
+    use relicario_core::backup;
+    use relicario_core::{ItemId, AttachmentId};
+    use zeroize::Zeroizing;
+
+    let target = if target.is_absolute() {
+        target
+    } else {
+        std::env::current_dir()?.join(&target)
+    };
+
+    if target.join(".relicario").exists() {
+        anyhow::bail!(
+            "target dir already contains a Relicario vault; restore refuses to overwrite — use an empty directory: {}",
+            target.display()
+        );
+    }
+    fs::create_dir_all(&target)
+        .with_context(|| format!("failed to create target {}", target.display()))?;
+
+    // Read input file.
+    let bytes = fs::read(&input)
+        .with_context(|| format!("failed to read backup file {}", input.display()))?;
+
+    // Backup passphrase prompt.
+    let passphrase = if let Some(p) = crate::test_backup_passphrase_override() {
+        Zeroizing::new(p)
+    } else {
+        Zeroizing::new(rpassword::prompt_password("Backup passphrase: ")?)
+    };
+
+    let unpacked = backup::unpack_backup(&bytes, &passphrase)
+        .map_err(|e| match e {
+            relicario_core::RelicarioError::Decrypt =>
+                anyhow::anyhow!("wrong backup passphrase, or the file is corrupt"),
+            other => anyhow::anyhow!(other),
+        })?;
+
+    // Write vault layout.
+    let relicario_dir = target.join(".relicario");
+    fs::create_dir_all(&relicario_dir)?;
+    fs::create_dir_all(target.join("items"))?;
+    fs::create_dir_all(target.join("attachments"))?;
+
+    fs::write(relicario_dir.join("salt"), unpacked.salt)?;
+    fs::write(relicario_dir.join("params.json"), &unpacked.params_json)?;
+    fs::write(relicario_dir.join("devices.json"), &unpacked.devices_json)?;
+    fs::write(target.join("manifest.enc"), &unpacked.manifest_enc)?;
+    fs::write(target.join("settings.enc"), &unpacked.settings_enc)?;
+
+    for item in &unpacked.items {
+        let item_id = ItemId(item.id.clone());
+        if !item_id.is_valid() {
+            anyhow::bail!("invalid item ID in backup: {} (path traversal blocked)", item.id);
+        }
+        fs::write(target.join("items").join(format!("{}.enc", item.id)), &item.ciphertext)?;
+    }
+    for a in &unpacked.attachments {
+        let item_id = ItemId(a.item_id.clone());
+        let att_id = AttachmentId(a.attachment_id.clone());
+        if !item_id.is_valid() || !att_id.is_valid() {
+            anyhow::bail!("invalid attachment ID in backup (path traversal blocked)");
+        }
+        let dir = target.join("attachments").join(&a.item_id);
+        fs::create_dir_all(&dir)?;
+        fs::write(dir.join(format!("{}.enc", a.attachment_id)), &a.ciphertext)?;
+    }
+
+    // Reference image (if present).
+    if let Some(jpg) = &unpacked.reference_jpg {
+        let path = target.join("reference.jpg");
+        fs::write(&path, jpg)
+            .with_context(|| format!("failed to write reference image {}", path.display()))?;
+    }
+
+    // .git/ history.
+    if let Some(tar_bytes) = &unpacked.git_archive {
+        // Cap: 100× the compressed bundle size, or 1 GiB, whichever is lower.
+        let cap = std::cmp::min(
+            (tar_bytes.len() as u64).saturating_mul(100),
+            relicario_core::DEFAULT_MAX_UNCOMPRESSED,
+        );
+        let entries = relicario_core::safe_unpack_git_archive(tar_bytes, cap)
+            .with_context(|| "failed to safely unpack .git/ archive")?;
+        let git_dir = target.join(".git");
+        for (rel_path, body) in entries {
+            let dest = git_dir.join(&rel_path);
+            // Paranoid OS-level check even after textual validation in core.
+            if !dest.starts_with(&git_dir) {
+                anyhow::bail!(
+                    "tar entry {} resolved outside .git/ (path traversal blocked)",
+                    rel_path.display()
+                );
+            }
+            if let Some(parent) = dest.parent() {
+                fs::create_dir_all(parent).with_context(|| {
+                    format!("create parent {}", parent.display())
+                })?;
+            }
+            fs::write(&dest, &body).with_context(|| {
+                format!("write {}", dest.display())
+            })?;
+        }
+    } else {
+        // No history bundled — start a fresh git repo.
+        crate::helpers::git_run(&target, &["init"], "backup restore: git init")?;
+
+        // .gitignore — exclude reference image if present.
+        if target.join("reference.jpg").exists() {
+            fs::write(target.join(".gitignore"), "reference.jpg\n")?;
+        }
+
+        let _ = crate::helpers::git_command(&target, &["add", "."]).status()?;
+        let now_iso = crate::helpers::iso8601(relicario_core::now_unix());
+        let msg = format!("restore from backup {now_iso}");
+        let _ = crate::helpers::git_command(&target, &["commit", "-m", &msg]).status()?;
+    }
+
+    eprintln!(
+        "Restored vault to {}. Unlock with your passphrase + reference image.",
+        target.display()
+    );
+    Ok(())
+}

crates/relicario-cli/src/commands/device.rs

@@ -0,0 +1,255 @@
+//! `relicario device {add, revoke, list}` — device key management.
+//!
+//! Note: command bodies live here as `crate::commands::device`. Local key
+//! storage and git-signing config live separately in `crate::device`.
+
+use anyhow::Result;
+
+use crate::DeviceAction;
+
+/// Build a `GiteaClient` from flags or environment variables.
+fn load_gitea_client(
+    gitea_url: Option<String>,
+    gitea_token: Option<String>,
+    owner: Option<String>,
+    repo: Option<String>,
+) -> Result<crate::gitea::GiteaClient> {
+    let url = gitea_url
+        .or_else(|| std::env::var("RELICARIO_GITEA_URL").ok())
+        .ok_or_else(|| anyhow::anyhow!(
+            "Gitea URL required — pass --gitea-url or set RELICARIO_GITEA_URL"
+        ))?;
+    let token = gitea_token
+        .or_else(|| std::env::var("RELICARIO_GITEA_TOKEN").ok())
+        .ok_or_else(|| anyhow::anyhow!(
+            "Gitea token required — pass --gitea-token or set RELICARIO_GITEA_TOKEN"
+        ))?;
+    let owner = owner
+        .or_else(|| std::env::var("RELICARIO_GITEA_OWNER").ok())
+        .ok_or_else(|| anyhow::anyhow!(
+            "Gitea owner required — pass --owner or set RELICARIO_GITEA_OWNER"
+        ))?;
+    let repo = repo
+        .or_else(|| std::env::var("RELICARIO_GITEA_REPO").ok())
+        .ok_or_else(|| anyhow::anyhow!(
+            "Gitea repo required — pass --repo or set RELICARIO_GITEA_REPO"
+        ))?;
+    Ok(crate::gitea::GiteaClient::new(&url, &token, &owner, &repo))
+}
+
+pub fn cmd_device(action: DeviceAction) -> Result<()> {
+    use std::fs;
+    use relicario_core::device::{DeviceEntry, RevokedEntry, generate_keypair};
+
+    let root = crate::helpers::vault_dir()?;
+    let relicario_dir = root.join(".relicario");
+    let devices_path = relicario_dir.join("devices.json");
+
+    match action {
+        DeviceAction::Add { name, gitea_url, gitea_token, owner, repo, no_gitea } => {
+            // Guard: don't overwrite an already-registered device name.
+            let existing: Vec<DeviceEntry> = fs::read(&devices_path)
+                .ok()
+                .and_then(|b| serde_json::from_slice(&b).ok())
+                .unwrap_or_default();
+            if existing.iter().any(|d| d.name == name) {
+                anyhow::bail!("a device named '{}' is already registered", name);
+            }
+
+            eprintln!("Generating signing keypair...");
+            let (signing_priv, signing_pub) = generate_keypair()
+                .map_err(|e| anyhow::anyhow!("generate signing keypair: {e}"))?;
+
+            eprintln!("Generating deploy keypair...");
+            let (deploy_priv, deploy_pub) = generate_keypair()
+                .map_err(|e| anyhow::anyhow!("generate deploy keypair: {e}"))?;
+
+            // Optionally register deploy key with Gitea.
+            let gitea_key_id: u64 = if no_gitea {
+                eprintln!("Skipping Gitea deploy key registration (--no-gitea).");
+                0
+            } else {
+                let client = load_gitea_client(gitea_url, gitea_token, owner, repo)?;
+                let key_title = format!("relicario-{}", name);
+                eprintln!("Registering deploy key '{}' with Gitea...", key_title);
+                client.create_deploy_key(&key_title, &deploy_pub)?
+            };
+
+            // Store keys locally with proper permissions.
+            crate::device::store_device_keys(
+                &name,
+                &signing_priv,
+                &signing_pub,
+                &deploy_priv,
+                &deploy_pub,
+                gitea_key_id,
+            )?;
+
+            // Mark as current device.
+            crate::device::set_current_device(&name)?;
+
+            // Configure git signing + SSH deploy key in the vault repo.
+            crate::device::configure_git_signing(&root, &name)?;
+
+            // Update devices.json.
+            let current_name = name.clone();
+            let mut devices = existing;
+            devices.push(DeviceEntry {
+                name: name.clone(),
+                public_key: signing_pub.clone(),
+                added_at: relicario_core::now_unix(),
+                added_by: current_name,
+            });
+            fs::create_dir_all(&relicario_dir)?;
+            fs::write(&devices_path, serde_json::to_string_pretty(&devices)?)?;
+
+            // Commit the update.
+            crate::helpers::git_run(
+                &root,
+                &["add", ".relicario/devices.json"],
+                &format!("device register \"{name}\": git add .relicario/devices.json"),
+            )?;
+            let msg = format!("device: register {}", name);
+            crate::helpers::git_run(
+                &root,
+                &["commit", "-m", &msg],
+                &format!("device register \"{name}\": git commit"),
+            )?;
+
+            eprintln!("Device '{}' registered.", name);
+            eprintln!("Signing public key:");
+            eprintln!("  {}", signing_pub);
+            if gitea_key_id != 0 {
+                eprintln!("Gitea deploy key ID: {}", gitea_key_id);
+            }
+            Ok(())
+        }
+
+        DeviceAction::Revoke { name } => {
+            // Guard: refuse to revoke the currently active device (would lock
+            // the user out).  They must add another device first.
+            if let Some(current) = crate::device::current_device()? {
+                if current == name {
+                    anyhow::bail!(
+                        "cannot revoke the current device '{}' — you would lose \
+                         push access. Register another device first.",
+                        name
+                    );
+                }
+            }
+
+            // Load devices.json.
+            let mut devices: Vec<DeviceEntry> = fs::read(&devices_path)
+                .ok()
+                .and_then(|b| serde_json::from_slice(&b).ok())
+                .unwrap_or_default();
+
+            let device = devices
+                .iter()
+                .find(|d| d.name == name)
+                .ok_or_else(|| anyhow::anyhow!("device '{}' not found", name))?
+                .clone();
+
+            // Remove from devices.json.
+            devices.retain(|d| d.name != name);
+            fs::write(&devices_path, serde_json::to_string_pretty(&devices)?)?;
+
+            // Append to revoked.json.
+            let revoked_path = relicario_dir.join("revoked.json");
+            let mut revoked: Vec<RevokedEntry> = fs::read(&revoked_path)
+                .ok()
+                .and_then(|b| serde_json::from_slice(&b).ok())
+                .unwrap_or_default();
+
+            let revoked_by = crate::device::current_device()?
+                .unwrap_or_else(|| "unknown".to_string());
+
+            revoked.push(RevokedEntry {
+                name: name.clone(),
+                public_key: device.public_key.clone(),
+                revoked_at: relicario_core::now_unix(),
+                revoked_by,
+            });
+            fs::write(&revoked_path, serde_json::to_string_pretty(&revoked)?)?;
+
+            // Delete deploy key from Gitea (best-effort — don't fail if it
+            // was already deleted or the config is missing).
+            if let Ok(key_id) = crate::device::load_gitea_key_id(&name) {
+                if key_id != 0 {
+                    // Build client from env vars only (no flags in revoke).
+                    match load_gitea_client(None, None, None, None) {
+                        Ok(client) => {
+                            if let Err(e) = client.delete_deploy_key(key_id) {
+                                eprintln!(
+                                    "warning: failed to delete Gitea deploy key {}: {}",
+                                    key_id, e
+                                );
+                            } else {
+                                eprintln!("Deleted Gitea deploy key {}.", key_id);
+                            }
+                        }
+                        Err(_) => {
+                            eprintln!(
+                                "warning: Gitea env vars not set — deploy key {} \
+                                 not deleted from Gitea.",
+                                key_id
+                            );
+                        }
+                    }
+                }
+            }
+
+            // Commit devices.json + revoked.json (always both — revoked.json
+            // was just written above so it is guaranteed to exist).
+            let add_args = [
+                "add",
+                ".relicario/devices.json",
+                ".relicario/revoked.json",
+            ];
+            crate::helpers::git_run(
+                &root,
+                &add_args,
+                &format!("device revoke \"{name}\": git add devices.json + revoked.json"),
+            )?;
+            let msg = format!("device: revoke {}", name);
+            crate::helpers::git_run(
+                &root,
+                &["commit", "-m", &msg],
+                &format!("device revoke \"{name}\": git commit"),
+            )?;
+
+            eprintln!("Device '{}' revoked.", name);
+            eprintln!("Revoked signing key: {}", device.public_key);
+            Ok(())
+        }
+
+        DeviceAction::List => {
+            let devices: Vec<DeviceEntry> = fs::read(&devices_path)
+                .ok()
+                .and_then(|b| serde_json::from_slice(&b).ok())
+                .unwrap_or_default();
+
+            let current = crate::device::current_device()?.unwrap_or_default();
+
+            if devices.is_empty() {
+                println!("No registered devices.");
+                return Ok(());
+            }
+
+            println!("{:<20} {:<20} SIGNING KEY (prefix)", "NAME", "ADDED");
+            println!("{}", "-".repeat(72));
+            for d in &devices {
+                let marker = if d.name == current { " *" } else { "" };
+                let added = crate::helpers::iso8601(d.added_at);
+                // Show only the first 40 chars of the public key line for readability.
+                let key_prefix: String = d.public_key.chars().take(40).collect();
+                println!("{:<20} {:<20} {}{}",
+                    d.name, added, key_prefix, marker);
+            }
+            if !current.is_empty() {
+                println!("\n* = current device");
+            }
+            Ok(())
+        }
+    }
+}

crates/relicario-cli/src/commands/edit.rs

@@ -0,0 +1,171 @@
+//! `relicario edit <query>` — interactive per-type field editing with history capture.
+
+use std::path::PathBuf;
+
+use anyhow::{Context, Result};
+
+use crate::parse::base32_decode_lenient;
+use crate::prompt::{prompt_keep, prompt_keep_opt, prompt_secret, prompt_yesno};
+
+pub fn cmd_edit(query: String, totp_qr: Option<PathBuf>) -> Result<()> {
+    use relicario_core::time::now_unix;
+    use relicario_core::ItemCore;
+
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let mut manifest = vault.load_manifest()?;
+    let entry = super::resolve_query(&manifest, &query)?;
+    let id = entry.id.clone();
+    let _ = entry;
+    let mut item = vault.load_item(&id)?;
+
+    eprintln!("Editing: {} ({})  — leave a prompt blank to keep the current value.",
+              item.title, item.id.as_str());
+
+    if let Some(v) = prompt_keep("Title", &item.title)? { item.title = v; }
+    if let Some(v) = prompt_keep_opt("Group", item.group.as_deref())? { item.group = Some(v); }
+    if let Some(v) = prompt_keep_opt("Tags (comma-separated)", Some(&item.tags.join(",")))? {
+        item.tags = v.split(',').map(|s| s.trim().to_string()).filter(|s| !s.is_empty()).collect();
+    }
+
+    let history = &mut item.field_history;
+    match &mut item.core {
+        ItemCore::Login(l)      => edit_login(l, history, totp_qr)?,
+        ItemCore::SecureNote(n) => edit_secure_note(n, history)?,
+        ItemCore::Identity(i)   => edit_identity(i)?,
+        ItemCore::Card(c)       => edit_card(c, history)?,
+        ItemCore::Key(k)        => edit_key(k, history)?,
+        ItemCore::Document(_)   => edit_document_message(),
+        ItemCore::Totp(t)       => edit_totp(t, history)?,
+    }
+
+    item.modified = now_unix();
+    vault.save_item(&item)?;
+    manifest.upsert(&item);
+    vault.after_manifest_change(&manifest)?;
+    super::commit_paths(&vault, &format!("edit: {} ({})", crate::helpers::sanitize_for_commit(&item.title), item.id.as_str()),
+                 &[&format!("items/{}.enc", item.id.as_str()), "manifest.enc"])?;
+    eprintln!("Updated {}", item.id.as_str());
+    Ok(())
+}
+
+// --- Per-type edit handlers. Each mutates its core slice in place; the ones
+//     that touch history-tracked fields take the item's field_history map so
+//     they can record the prior value alongside the change.
+
+type FieldHistory = std::collections::HashMap<
+    relicario_core::FieldId,
+    Vec<relicario_core::item::FieldHistoryEntry>,
+>;
+
+fn edit_login(
+    l: &mut relicario_core::item_types::LoginCore,
+    history: &mut FieldHistory,
+    totp_qr: Option<PathBuf>,
+) -> Result<()> {
+    use relicario_core::item_types::{TotpAlgorithm, TotpConfig, TotpKind};
+    use zeroize::Zeroizing;
+    if let Some(v) = prompt_keep_opt("Username", l.username.as_deref())? { l.username = Some(v); }
+    if let Some(v) = prompt_keep_opt("URL", l.url.as_ref().map(|u| u.as_str()))? {
+        l.url = Some(url::Url::parse(&v).with_context(|| format!("invalid URL: {v}"))?);
+    }
+    if prompt_yesno("Change password?")? {
+        let old = l.password.clone();
+        l.password = Some(Zeroizing::new(prompt_secret("New password: ")?));
+        if let Some(old_pw) = old {
+            push_history(history, "login_password", Zeroizing::new(old_pw.as_str().to_string()));
+        }
+    }
+    if let Some(path) = totp_qr {
+        let secret_b32 = crate::helpers::decode_totp_qr(&path)?;
+        let secret_bytes = base32_decode_lenient(&secret_b32)?;
+        l.totp = Some(TotpConfig {
+            secret: Zeroizing::new(secret_bytes),
+            algorithm: TotpAlgorithm::Sha1,
+            digits: 6,
+            period_seconds: 30,
+            kind: TotpKind::Totp,
+        });
+        eprintln!("TOTP secret set from QR image.");
+    }
+    Ok(())
+}
+
+fn edit_secure_note(n: &mut relicario_core::item_types::SecureNoteCore, history: &mut FieldHistory) -> Result<()> {
+    use zeroize::Zeroizing;
+    if prompt_yesno("Edit body?")? {
+        let old = n.body.clone();
+        eprintln!("Enter new body; end with Ctrl-D:");
+        let mut s = String::new();
+        std::io::Read::read_to_string(&mut std::io::stdin(), &mut s)?;
+        n.body = Zeroizing::new(s);
+        push_history(history, "secure_note_body", Zeroizing::new(old.as_str().to_string()));
+    }
+    Ok(())
+}
+
+fn edit_identity(i: &mut relicario_core::item_types::IdentityCore) -> Result<()> {
+    if let Some(v) = prompt_keep_opt("Full name", i.full_name.as_deref())? { i.full_name = Some(v); }
+    if let Some(v) = prompt_keep_opt("Email", i.email.as_deref())? { i.email = Some(v); }
+    if let Some(v) = prompt_keep_opt("Phone", i.phone.as_deref())? { i.phone = Some(v); }
+    Ok(())
+}
+
+fn edit_card(c: &mut relicario_core::item_types::CardCore, history: &mut FieldHistory) -> Result<()> {
+    use zeroize::Zeroizing;
+    if let Some(v) = prompt_keep_opt("Holder", c.holder.as_deref())? { c.holder = Some(v); }
+    if prompt_yesno("Change card number?")? {
+        let old = c.number.clone();
+        c.number = Some(Zeroizing::new(prompt_secret("New number: ")?));
+        if let Some(o) = old {
+            push_history(history, "card_number", Zeroizing::new(o.as_str().to_string()));
+        }
+    }
+    Ok(())
+}
+
+fn edit_key(k: &mut relicario_core::item_types::KeyCore, history: &mut FieldHistory) -> Result<()> {
+    use zeroize::Zeroizing;
+    if prompt_yesno("Replace key material?")? {
+        eprintln!("Paste new key material; end with Ctrl-D:");
+        let mut s = String::new();
+        std::io::Read::read_to_string(&mut std::io::stdin(), &mut s)?;
+        let old = k.key_material.clone();
+        k.key_material = Zeroizing::new(s);
+        push_history(history, "key_material", Zeroizing::new(old.as_str().to_string()));
+    }
+    Ok(())
+}
+
+fn edit_document_message() {
+    eprintln!("Document items: use `relicario attach` / `relicario extract` instead.");
+}
+
+fn edit_totp(t: &mut relicario_core::item_types::TotpCore, history: &mut FieldHistory) -> Result<()> {
+    use zeroize::Zeroizing;
+    if let Some(v) = prompt_keep_opt("Issuer", t.issuer.as_deref())? { t.issuer = Some(v); }
+    if let Some(v) = prompt_keep_opt("Label", t.label.as_deref())? { t.label = Some(v); }
+    if prompt_yesno("Change TOTP secret?")? {
+        let old_b32 = data_encoding::BASE32.encode(&t.config.secret);
+        let new_b32 = prompt_secret("New TOTP secret (base32): ")?;
+        let new_bytes = base32_decode_lenient(&new_b32)?;
+        t.config.secret = Zeroizing::new(new_bytes);
+        push_history(history, "totp_secret", Zeroizing::new(old_b32));
+    }
+    Ok(())
+}
+
+fn push_history(
+    history: &mut std::collections::HashMap<relicario_core::FieldId, Vec<relicario_core::item::FieldHistoryEntry>>,
+    synthetic_key: &str,
+    old_value: zeroize::Zeroizing<String>,
+) {
+    use relicario_core::item::FieldHistoryEntry;
+    use relicario_core::time::now_unix;
+    // Synthetic FieldId for core-level fields — stable per-item (prefixed so
+    // custom-field UUIDs can't collide).
+    let fid = relicario_core::FieldId(format!("core:{synthetic_key}"));
+    history.entry(fid).or_default().push(FieldHistoryEntry {
+        value: old_value,
+        replaced_at: now_unix(),
+    });
+}

crates/relicario-cli/src/commands/generate.rs

@@ -0,0 +1,68 @@
+//! `relicario generate` — emit a fresh password or BIP39 passphrase.
+
+use anyhow::Result;
+
+pub fn cmd_generate(
+    length: Option<u32>,
+    bip39: bool,
+    words: Option<u32>,
+    symbols: Option<String>,
+    separator: Option<String>,
+) -> Result<()> {
+    use relicario_core::{
+        generate_passphrase, generate_password, Capitalization, CharClasses,
+        GeneratorRequest, SymbolCharset,
+    };
+
+    // If we're inside a vault, unlock and pull `generator_defaults`. Outside
+    // a vault, this stays a fast standalone CSPRNG tool (no unlock prompt).
+    let vault_defaults: Option<GeneratorRequest> = if crate::helpers::vault_dir().is_ok() {
+        let vault = crate::session::UnlockedVault::unlock_interactive()?;
+        Some(vault.load_settings()?.generator_defaults)
+    } else {
+        None
+    };
+
+    // `--bip39` flag forces Bip39 mode; otherwise use whatever mode the
+    // vault default is in (Random when no vault).
+    let use_bip39 = bip39 || matches!(vault_defaults, Some(GeneratorRequest::Bip39 { .. }));
+
+    let output = if use_bip39 {
+        let (def_words, def_sep, def_cap) = match &vault_defaults {
+            Some(GeneratorRequest::Bip39 { word_count, separator, capitalization }) => {
+                (*word_count, separator.clone(), *capitalization)
+            }
+            _ => (5, " ".to_string(), Capitalization::Lower),
+        };
+        generate_passphrase(&GeneratorRequest::Bip39 {
+            word_count: words.unwrap_or(def_words),
+            separator: separator.unwrap_or(def_sep),
+            capitalization: def_cap,
+        })?
+    } else {
+        let (def_length, def_classes, def_charset) = match &vault_defaults {
+            Some(GeneratorRequest::Random { length, classes, symbol_charset }) => {
+                (*length, *classes, symbol_charset.clone())
+            }
+            _ => (
+                20,
+                CharClasses { lower: true, upper: true, digits: true, symbols: true },
+                SymbolCharset::SafeOnly,
+            ),
+        };
+        let symbol_charset = match symbols.as_deref() {
+            None => def_charset,
+            Some("safe") => SymbolCharset::SafeOnly,
+            Some("extended") => SymbolCharset::Extended,
+            Some(other) => SymbolCharset::Custom(other.to_string()),
+        };
+        generate_password(&GeneratorRequest::Random {
+            length: length.unwrap_or(def_length),
+            classes: def_classes,
+            symbol_charset,
+        })?
+    };
+
+    println!("{}", output.as_str());
+    Ok(())
+}

crates/relicario-cli/src/commands/get.rs

@@ -0,0 +1,106 @@
+//! `relicario get` — print a single item, masking secrets unless `--show`.
+
+use anyhow::{Context, Result};
+
+pub fn cmd_get(query: String, show: bool, copy: bool) -> Result<()> {
+    use relicario_core::ItemCore;
+    use zeroize::Zeroizing;
+
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let manifest = vault.load_manifest()?;
+    let entry = super::resolve_query(&manifest, &query)?;
+    let item = vault.load_item(&entry.id)?;
+
+    println!("ID:       {}", item.id.as_str());
+    println!("Title:    {}", item.title);
+    println!("Type:     {:?}", item.r#type);
+    if let Some(g) = &item.group { println!("Group:    {g}"); }
+    if !item.tags.is_empty() { println!("Tags:     {}", item.tags.join(", ")); }
+    println!("Created:  {}", crate::helpers::iso8601(item.created));
+    println!("Modified: {}", crate::helpers::iso8601(item.modified));
+    if let Some(t) = item.trashed_at { println!("Trashed:  {}", crate::helpers::iso8601(t)); }
+    println!();
+
+    let primary_secret: Option<Zeroizing<String>> = match &item.core {
+        ItemCore::Login(l) => {
+            if let Some(u) = &l.username { println!("Username: {u}"); }
+            if let Some(u) = &l.url { println!("URL:      {u}"); }
+            if let Some(t) = &l.totp {
+                if show {
+                    println!("TOTP:     {}", data_encoding::BASE32.encode(&t.secret));
+                } else {
+                    println!("TOTP:     ****  (use --show to reveal)");
+                }
+            }
+            l.password.clone()
+        }
+        ItemCore::SecureNote(n) => {
+            if show { println!("Body:\n{}", n.body.as_str()); }
+            else { println!("Body:     ********"); }
+            None
+        }
+        ItemCore::Identity(i) => {
+            if let Some(v) = &i.full_name { println!("Name:     {v}"); }
+            if let Some(v) = &i.email { println!("Email:    {v}"); }
+            if let Some(v) = &i.phone { println!("Phone:    {v}"); }
+            if let Some(v) = &i.date_of_birth { println!("DOB:      {v}"); }
+            None
+        }
+        ItemCore::Card(c) => {
+            if let Some(h) = &c.holder { println!("Holder:   {h}"); }
+            if let Some(e) = &c.expiry { println!("Expiry:   {:02}/{}", e.month, e.year); }
+            println!("Kind:     {:?}", c.kind);
+            c.number.clone()
+        }
+        ItemCore::Key(k) => {
+            if let Some(l) = &k.label { println!("Label:    {l}"); }
+            if let Some(a) = &k.algorithm { println!("Algo:     {a}"); }
+            if let Some(pk) = &k.public_key { println!("Pubkey:   {pk}"); }
+            Some(k.key_material.clone())
+        }
+        ItemCore::Document(d) => {
+            println!("Filename: {}", d.filename);
+            println!("MIME:     {}", d.mime_type);
+            None
+        }
+        ItemCore::Totp(t) => {
+            if let Some(i) = &t.issuer { println!("Issuer:   {i}"); }
+            if let Some(l) = &t.label { println!("Label:    {l}"); }
+            println!("Period:   {}s", t.config.period_seconds);
+            println!("Digits:   {}", t.config.digits);
+            None
+        }
+    };
+
+    if let Some(secret) = primary_secret {
+        if show {
+            println!("Secret:   {}", secret.as_str());
+        } else {
+            println!("Secret:   ********  (use --show to reveal, --copy to clipboard)");
+        }
+        if copy {
+            copy_to_clipboard_then_clear(&secret)?;
+            eprintln!("Copied to clipboard (auto-clears in 30s).");
+        }
+    }
+
+    Ok(())
+}
+
+fn copy_to_clipboard_then_clear(secret: &zeroize::Zeroizing<String>) -> Result<()> {
+    use arboard::Clipboard;
+    let mut cb = Clipboard::new().context("failed to access clipboard")?;
+    cb.set_text(secret.as_str().to_string()).context("failed to write clipboard")?;
+    let cleared_copy = zeroize::Zeroizing::new(secret.as_str().to_owned());
+    // Unconditional clear (audit M6): spawn a detached thread that waits 30s
+    // and then rewrites the clipboard with empty string. Even if the user
+    // copies something else in the interim, we still overwrite once.
+    std::thread::spawn(move || {
+        std::thread::sleep(std::time::Duration::from_secs(30));
+        if let Ok(mut cb) = Clipboard::new() {
+            let _ = cb.set_text(String::new());
+            drop(cleared_copy); // zeroize the detached copy
+        }
+    });
+    Ok(())
+}

crates/relicario-cli/src/commands/import.rs

@@ -0,0 +1,88 @@
+//! `relicario import` — currently only LastPass CSV is supported.
+
+use std::path::PathBuf;
+
+use anyhow::{bail, Context, Result};
+
+use crate::ImportAction;
+
+pub fn cmd_import(action: ImportAction) -> Result<()> {
+    match action {
+        ImportAction::Lastpass { csv } => cmd_import_lastpass(csv),
+    }
+}
+
+fn cmd_import_lastpass(csv_path: PathBuf) -> Result<()> {
+    use std::fs;
+    use relicario_core::import_lastpass::parse_lastpass_csv;
+
+    let csv_bytes = fs::read(&csv_path)
+        .with_context(|| format!("failed to read CSV {}", csv_path.display()))?;
+
+    let (items, warnings) = parse_lastpass_csv(&csv_bytes)?;
+
+    if items.is_empty() {
+        // Print all warnings so the user sees why nothing imported.
+        for w in &warnings {
+            print_warning(w);
+        }
+        bail!(
+            "imported 0 items from {} — see warnings above",
+            csv_path.display()
+        );
+    }
+
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let mut manifest = vault.load_manifest()?;
+
+    let total = items.len();
+    let mut written_paths: Vec<String> = Vec::with_capacity(items.len() + 1);
+
+    for (idx, item) in items.iter().enumerate() {
+        vault.save_item(item)?;
+        manifest.upsert(item);
+        written_paths.push(format!("items/{}.enc", item.id.as_str()));
+
+        let n = idx + 1;
+        if n % 50 == 0 || n == total {
+            eprintln!("[{n}/{total}] importing...");
+        }
+    }
+
+    vault.after_manifest_change(&manifest)?;
+    written_paths.push("manifest.enc".into());
+
+    let path_refs: Vec<&str> = written_paths.iter().map(String::as_str).collect();
+    let csv_filename = csv_path
+        .file_name()
+        .and_then(|s| s.to_str())
+        .unwrap_or("lastpass.csv");
+    super::commit_paths(
+        &vault,
+        &format!("import: {} items from LastPass ({})", total, csv_filename),
+        &path_refs,
+    )?;
+
+    for w in &warnings {
+        print_warning(w);
+    }
+    // Counts only true skips, not partial imports. Coupled by convention to
+    // the parser's warning message strings: skip messages end in "— skipped",
+    // partial-import messages say "imported without TOTP" / "imported without URL".
+    // If a future warning uses the word "skipped" in any other sense, this filter
+    // will need to switch to an enum tag (see ImportWarning::message).
+    eprintln!(
+        "Imported {}, skipped {} (see warnings above)",
+        total,
+        warnings.iter().filter(|w| w.message.contains("skipped")).count()
+    );
+    Ok(())
+}
+
+fn print_warning(w: &relicario_core::import_lastpass::ImportWarning) {
+    let prefix = match &w.title {
+        Some(t) => format!("row {} ({}):", w.row, t),
+        None => format!("row {}:", w.row),
+    };
+    eprintln!("warning: {prefix} {}", w.message);
+}

crates/relicario-cli/src/commands/init.rs

@@ -0,0 +1,98 @@
+//! `relicario init` — bootstrap a fresh vault in the current directory.
+
+use std::path::PathBuf;
+
+use anyhow::{Context, Result};
+
+pub fn cmd_init(image: PathBuf, output: PathBuf) -> Result<()> {
+    use std::fs;
+    use rand::{rngs::OsRng, RngCore};
+    use relicario_core::{
+        derive_master_key, encrypt_manifest, encrypt_settings, imgsecret,
+        validate_passphrase_strength, KdfParams, Manifest, VaultSettings,
+    };
+    use zeroize::Zeroizing;
+
+    let root = std::env::current_dir()?;
+    let relicario_dir = root.join(".relicario");
+    if relicario_dir.exists() {
+        anyhow::bail!(".relicario/ already exists in {}", root.display());
+    }
+
+    // Passphrase with strength gate (audit H3).
+    // RELICARIO_TEST_PASSPHRASE is a test-only escape hatch that bypasses the
+    // TTY prompt so integration tests can run without a real TTY.
+    let passphrase = if let Some(p) = crate::test_passphrase_override() {
+        Zeroizing::new(p)
+    } else {
+        Zeroizing::new(rpassword::prompt_password("Choose a passphrase: ")?)
+    };
+    let confirm = if crate::test_passphrase_override().is_some() {
+        passphrase.clone()
+    } else {
+        Zeroizing::new(rpassword::prompt_password("Confirm passphrase: ")?)
+    };
+    if passphrase.as_str() != confirm.as_str() {
+        anyhow::bail!("passphrases do not match");
+    }
+    if let Err(e) = validate_passphrase_strength(&passphrase) {
+        anyhow::bail!("{}. Choose a longer or more entropic phrase.", e);
+    }
+
+    // Image secret: 32 random bytes, embedded in the carrier.
+    let image_secret = {
+        let mut buf = Zeroizing::new([0u8; 32]);
+        OsRng.fill_bytes(buf.as_mut_slice());
+        buf
+    };
+    let carrier = fs::read(&image)
+        .with_context(|| format!("failed to read carrier image {}", image.display()))?;
+    let stego = imgsecret::embed(&carrier, &image_secret)?;
+    fs::write(&output, &stego)
+        .with_context(|| format!("failed to write reference image {}", output.display()))?;
+
+    // Vault salt + KDF params.
+    let mut salt = [0u8; 32];
+    OsRng.fill_bytes(&mut salt);
+    let params = KdfParams { argon2_m: 65536, argon2_t: 3, argon2_p: 4 };
+
+    // Derive master key, then persist an empty Manifest + default VaultSettings.
+    let master_key = derive_master_key(passphrase.as_bytes(), &image_secret, &salt, &params)?;
+
+    fs::create_dir_all(&relicario_dir)?;
+    fs::create_dir_all(root.join("items"))?;
+    fs::create_dir_all(root.join("attachments"))?;
+    fs::write(relicario_dir.join("salt"), salt)?;
+    fs::write(
+        relicario_dir.join("params.json"),
+        serde_json::to_string_pretty(&crate::session::ParamsFile::for_new_vault(&params))?,
+    )?;
+    let manifest = Manifest::new();
+    fs::write(root.join("manifest.enc"), encrypt_manifest(&manifest, &master_key)?)?;
+    let settings = VaultSettings::default();
+    fs::write(root.join("settings.enc"), encrypt_settings(&settings, &master_key)?)?;
+
+    // .gitignore excludes the reference image.
+    let fname = output.file_name()
+        .ok_or_else(|| anyhow::anyhow!("output path has no filename: {}", output.display()))?
+        .to_string_lossy();
+    let gitignore = format!("{fname}\n");
+    fs::write(root.join(".gitignore"), gitignore)?;
+
+    // git init + initial commit via hardened wrapper.
+    crate::helpers::git_run(&root, &["init"], "init: git init")?;
+    let _ = crate::helpers::git_command(&root, &[
+        "add", ".gitignore", ".relicario/params.json",
+        ".relicario/salt", "manifest.enc", "settings.enc",
+    ]).status()?;
+    crate::helpers::git_run(
+        &root,
+        &["commit", "-m", "init: new Relicario vault (format v2)"],
+        "init: git commit",
+    )?;
+
+    eprintln!("Vault initialized at {}", root.display());
+    eprintln!("Reference image: {}", output.display());
+    eprintln!("  \u{2192} back this file up somewhere safe; it is your second factor.");
+    Ok(())
+}

crates/relicario-cli/src/commands/list.rs

@@ -0,0 +1,102 @@
+//! `relicario list` and `relicario history` — both read-only browse paths.
+
+use anyhow::Result;
+
+pub fn cmd_list(
+    type_filter: Option<String>,
+    group_filter: Option<String>,
+    tag_filter: Option<String>,
+    trashed: bool,
+) -> Result<()> {
+    use relicario_core::ItemType;
+
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let manifest = vault.load_manifest()?;
+
+    let parsed_type: Option<ItemType> = match type_filter.as_deref() {
+        None => None,
+        Some("login") => Some(ItemType::Login),
+        Some("secure_note") | Some("note") => Some(ItemType::SecureNote),
+        Some("identity") => Some(ItemType::Identity),
+        Some("card") => Some(ItemType::Card),
+        Some("key") => Some(ItemType::Key),
+        Some("document") => Some(ItemType::Document),
+        Some("totp") => Some(ItemType::Totp),
+        Some(other) => anyhow::bail!("unknown type filter: {other}"),
+    };
+
+    let mut entries: Vec<_> = manifest.items.values()
+        .filter(|e| {
+            if trashed { e.trashed_at.is_some() } else { e.trashed_at.is_none() }
+        })
+        .filter(|e| match parsed_type {
+            Some(t) => e.r#type == t,
+            None => true,
+        })
+        .filter(|e| group_filter.as_ref().is_none_or(|g| e.group.as_deref() == Some(g.as_str())))
+        .filter(|e| tag_filter.as_ref().is_none_or(|t| e.tags.iter().any(|x| x == t)))
+        .collect();
+    entries.sort_by(|a, b| a.title.to_lowercase().cmp(&b.title.to_lowercase()));
+
+    if entries.is_empty() {
+        eprintln!("(no items match)");
+        return Ok(());
+    }
+
+    println!("{:<16}  {:<14}  {:<6}  TITLE", "ID", "TYPE", "FAV");
+    for e in entries {
+        let fav = if e.favorite { "  *" } else { "" };
+        println!("{:<16}  {:<14}  {:<6}  {}", e.id.as_str(), format!("{:?}", e.r#type), fav, e.title);
+    }
+    Ok(())
+}
+
+pub fn cmd_history(query: String, show: bool, field: Option<String>) -> Result<()> {
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let manifest = vault.load_manifest()?;
+    let entry = super::resolve_query(&manifest, &query)?;
+    let item = vault.load_item(&entry.id)?;
+
+    println!("History for {} ({})", item.title, item.id.as_str());
+    println!();
+
+    // Filter and sort the field-id keys so output is deterministic.
+    let mut keys: Vec<&relicario_core::FieldId> = item.field_history.keys().collect();
+    keys.sort_by(|a, b| a.0.cmp(&b.0));
+
+    let mut printed_any = false;
+    for fid in keys {
+        let display_name = fid.0.strip_prefix("core:").unwrap_or(&fid.0);
+        if let Some(filter) = &field {
+            if display_name != filter && fid.0 != *filter { continue; }
+        }
+        let entries = &item.field_history[fid];
+        if entries.is_empty() { continue; }
+        printed_any = true;
+
+        println!("{display_name} ({} {})",
+                 entries.len(),
+                 if entries.len() == 1 { "entry" } else { "entries" });
+        for (i, e) in entries.iter().enumerate() {
+            let ts = crate::helpers::iso8601(e.replaced_at);
+            if show {
+                println!("  [{i}] {ts}  {}", e.value.as_str());
+            } else {
+                println!("  [{i}] {ts}  ********");
+            }
+        }
+        println!();
+    }
+
+    if !printed_any {
+        if field.is_some() {
+            println!("no history for the requested field");
+        } else {
+            println!("no history captured for this item");
+        }
+    } else if !show {
+        println!("(use --show to reveal values)");
+    }
+
+    Ok(())
+}

crates/relicario-cli/src/commands/mod.rs

@@ -0,0 +1,60 @@
+//! Per-command modules — one file per top-level subcommand.
+//!
+//! `main.rs` holds the clap surface (argument enums) and the dispatch
+//! `match`; the actual command bodies live here. Helpers shared between
+//! command modules (e.g. `commit_paths`, `resolve_query`) are defined in
+//! this file as `pub(crate)` so siblings can pull them in via
+//! `use crate::commands::*`.
+
+pub mod add;
+pub mod attach;
+pub mod backup;
+pub mod device;
+pub mod edit;
+pub mod generate;
+pub mod get;
+pub mod import;
+pub mod init;
+pub mod list;
+pub mod rate;
+pub mod recovery_qr;
+pub mod settings;
+pub mod status;
+pub mod sync;
+pub mod trash;
+
+use anyhow::Result;
+
+pub(crate) fn commit_paths(
+    vault: &crate::session::UnlockedVault,
+    message: &str,
+    paths: &[&str],
+) -> Result<()> {
+    let mut args: Vec<&str> = vec!["add"];
+    args.extend_from_slice(paths);
+    crate::helpers::git_run(vault.root(), &args, &format!("commit \"{message}\": git add"))?;
+    crate::helpers::git_run(
+        vault.root(),
+        &["commit", "-m", message],
+        &format!("commit \"{message}\": git commit"),
+    )?;
+    Ok(())
+}
+
+pub(crate) fn resolve_query<'a>(
+    manifest: &'a relicario_core::Manifest,
+    query: &str,
+) -> Result<&'a relicario_core::ManifestEntry> {
+    if let Some(entry) = manifest.items.values().find(|e| e.id.as_str() == query) {
+        return Ok(entry);
+    }
+    let hits: Vec<_> = manifest.search(query);
+    match hits.len() {
+        0 => anyhow::bail!("no item matches `{query}`"),
+        1 => Ok(hits[0]),
+        _ => {
+            let titles: Vec<&str> = hits.iter().map(|e| e.title.as_str()).collect();
+            anyhow::bail!("ambiguous — {} matches: {}", hits.len(), titles.join(", "))
+        }
+    }
+}

crates/relicario-cli/src/commands/rate.rs

@@ -0,0 +1,28 @@
+//! `relicario rate` — score a passphrase via zxcvbn.
+
+use anyhow::Result;
+
+pub fn cmd_rate(passphrase: String) -> Result<()> {
+    let pw: String = if passphrase == "-" {
+        use std::io::BufRead;
+        let stdin = std::io::stdin();
+        let mut line = String::new();
+        stdin.lock().read_line(&mut line)?;
+        line.trim_end_matches(&['\r', '\n'][..]).to_string()
+    } else {
+        passphrase
+    };
+    let est = relicario_core::generators::rate_passphrase(&pw);
+    let label = match est.score {
+        0 => "very weak",
+        1 => "weak",
+        2 => "fair",
+        3 => "good",
+        4 => "strong",
+        _ => "?",
+    };
+    println!("score:    {}/4  ({})", est.score, label);
+    println!("guesses:  ~10^{:.1}", est.guesses_log10);
+    println!("note:     init requires score ≥ 3 (see `relicario init`)");
+    Ok(())
+}

crates/relicario-cli/src/commands/recovery_qr.rs

@@ -0,0 +1,69 @@
+//! `relicario recovery-qr {generate,unwrap}` — last-resort vault-key escape hatch.
+
+use anyhow::{Context, Result};
+
+use crate::RecoveryQrCmd;
+
+pub fn cmd_recovery_qr(cmd: RecoveryQrCmd) -> Result<()> {
+    match cmd {
+        RecoveryQrCmd::Generate => cmd_recovery_qr_generate(),
+        RecoveryQrCmd::Unwrap   => cmd_recovery_qr_unwrap(),
+    }
+}
+
+fn cmd_recovery_qr_generate() -> Result<()> {
+    use relicario_core::{generate_recovery_qr, imgsecret};
+    use zeroize::Zeroizing;
+
+    let image_path = crate::session::get_image_path()?;
+    let image_bytes = std::fs::read(&image_path)
+        .with_context(|| format!("read reference image {}", image_path.display()))?;
+    let image_secret = imgsecret::extract(&image_bytes)
+        .context("extract image secret")?;
+
+    let passphrase = Zeroizing::new(
+        rpassword::prompt_password("Enter vault passphrase: ")
+            .context("read passphrase")?
+    );
+
+    let payload = generate_recovery_qr(passphrase.as_str(), &image_secret)
+        .map_err(|e| anyhow::anyhow!("{e}"))?;
+
+    use qrcode::{EcLevel, QrCode, render::unicode};
+    let code = QrCode::with_error_correction_level(payload.as_bytes(), EcLevel::M)
+        .expect("valid payload");
+    let image = code
+        .render::<unicode::Dense1x2>()
+        .dark_color(unicode::Dense1x2::Dark)
+        .light_color(unicode::Dense1x2::Light)
+        .build();
+    println!("{image}");
+    println!("Recovery QR generated. Print or photograph this code and store it securely.");
+    println!("The QR has NOT been saved to disk.");
+    Ok(())
+}
+
+fn cmd_recovery_qr_unwrap() -> Result<()> {
+    use relicario_core::unwrap_recovery_qr;
+    use std::io::BufRead;
+    use zeroize::Zeroizing;
+
+    println!("Paste the base64 recovery QR payload and press Enter:");
+    let stdin = std::io::stdin();
+    let payload_b64 = stdin.lock().lines().next()
+        .context("no input")??;
+    let payload_b64 = payload_b64.trim().to_owned();
+
+    let bytes = data_encoding::BASE64.decode(payload_b64.as_bytes())
+        .map_err(|e| anyhow::anyhow!("base64 decode: {e}"))?;
+
+    let passphrase = Zeroizing::new(
+        rpassword::prompt_password("Enter passphrase: ")
+            .context("read passphrase")?
+    );
+
+    let secret = unwrap_recovery_qr(&bytes, passphrase.as_str())
+        .map_err(|e| anyhow::anyhow!("{e}"))?;
+    println!("image_secret: {}", hex::encode(secret.as_ref()));
+    Ok(())
+}

crates/relicario-cli/src/commands/settings.rs

@@ -0,0 +1,98 @@
+//! `relicario settings {show, trash-retention, history-retention, attachment-cap, generator-defaults}`.
+
+use anyhow::Result;
+
+use crate::SettingsAction;
+
+pub fn cmd_settings(action: SettingsAction) -> Result<()> {
+    use relicario_core::{
+        Capitalization, CharClasses, GeneratorRequest, HistoryRetention,
+        SymbolCharset, TrashRetention,
+    };
+
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let mut settings = vault.load_settings()?;
+
+    match action {
+        SettingsAction::Show => {
+            println!("{}", serde_json::to_string_pretty(&settings)?);
+            return Ok(());
+        }
+        SettingsAction::TrashRetention { days, forever } => {
+            settings.trash_retention = match (days, forever) {
+                (Some(d), false) => TrashRetention::Days(d),
+                (None, true) => TrashRetention::Forever,
+                _ => anyhow::bail!("specify exactly one of --days or --forever"),
+            };
+        }
+        SettingsAction::HistoryRetention { last_n, days, forever } => {
+            settings.field_history_retention = match (last_n, days, forever) {
+                (Some(n), None, false) => HistoryRetention::LastN(n),
+                (None, Some(d), false) => HistoryRetention::Days(d),
+                (None, None, true) => HistoryRetention::Forever,
+                _ => anyhow::bail!("specify exactly one of --last-n / --days / --forever"),
+            };
+        }
+        SettingsAction::AttachmentCap {
+            per_attachment_max_bytes, per_item_max_count,
+            per_vault_soft_cap_bytes, per_vault_hard_cap_bytes,
+        } => {
+            if let Some(v) = per_attachment_max_bytes { settings.attachment_caps.per_attachment_max_bytes = v; }
+            if let Some(v) = per_item_max_count { settings.attachment_caps.per_item_max_count = v; }
+            if let Some(v) = per_vault_soft_cap_bytes { settings.attachment_caps.per_vault_soft_cap_bytes = v; }
+            if let Some(v) = per_vault_hard_cap_bytes { settings.attachment_caps.per_vault_hard_cap_bytes = v; }
+        }
+        SettingsAction::GeneratorDefaults {
+            random, bip39, length, words, symbols, separator,
+        } => {
+            // Decide target mode: explicit flag wins, else preserve current.
+            let target_bip39 = if random { false }
+                else if bip39 { true }
+                else { matches!(settings.generator_defaults, GeneratorRequest::Bip39 { .. }) };
+
+            // Pull existing fields where compatible, else seed with sensible
+            // defaults (kept in sync with `GeneratorRequest::default()`).
+            let (cur_length, cur_classes, cur_charset) = match &settings.generator_defaults {
+                GeneratorRequest::Random { length, classes, symbol_charset } => {
+                    (*length, *classes, symbol_charset.clone())
+                }
+                _ => (
+                    20,
+                    CharClasses { lower: true, upper: true, digits: true, symbols: true },
+                    SymbolCharset::SafeOnly,
+                ),
+            };
+            let (cur_words, cur_sep, cur_cap) = match &settings.generator_defaults {
+                GeneratorRequest::Bip39 { word_count, separator, capitalization } => {
+                    (*word_count, separator.clone(), *capitalization)
+                }
+                _ => (5, " ".to_string(), Capitalization::Lower),
+            };
+
+            settings.generator_defaults = if target_bip39 {
+                GeneratorRequest::Bip39 {
+                    word_count: words.unwrap_or(cur_words),
+                    separator: separator.unwrap_or(cur_sep),
+                    capitalization: cur_cap,
+                }
+            } else {
+                let charset = match symbols.as_deref() {
+                    None => cur_charset,
+                    Some("safe") => SymbolCharset::SafeOnly,
+                    Some("extended") => SymbolCharset::Extended,
+                    Some(other) => SymbolCharset::Custom(other.to_string()),
+                };
+                GeneratorRequest::Random {
+                    length: length.unwrap_or(cur_length),
+                    classes: cur_classes,
+                    symbol_charset: charset,
+                }
+            };
+        }
+    }
+
+    vault.save_settings(&settings)?;
+    super::commit_paths(&vault, "settings: update", &["settings.enc"])?;
+    eprintln!("Settings updated.");
+    Ok(())
+}

crates/relicario-cli/src/commands/status.rs

@@ -0,0 +1,52 @@
+//! `relicario status` — vault-level summary (counts, last commit, last backup).
+
+use anyhow::Result;
+
+pub fn cmd_status() -> Result<()> {
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let root = vault.root().to_path_buf();
+    let manifest = vault.load_manifest()?;
+
+    let total_items = manifest.items.len();
+    let trashed_items = manifest.items.values().filter(|e| e.trashed_at.is_some()).count();
+    let active_items = total_items - trashed_items;
+
+    let (attachment_count, attachment_bytes) = manifest.items.values()
+        .flat_map(|e| e.attachment_summaries.iter())
+        .fold((0u64, 0u64), |(c, b), s| (c + 1, b + s.size));
+
+    let last_commit = crate::helpers::git_command(&root, &[
+        "log", "-1", "--pretty=format:%h %s",
+    ]).output()
+        .ok()
+        .and_then(|o| String::from_utf8(o.stdout).ok())
+        .map(|s| s.trim().to_string())
+        .unwrap_or_else(|| "(no commits)".into());
+
+    // Last backup age (read from marker written by cmd_backup_export).
+    let last_backup_path = vault.root().join(".relicario").join("last_backup");
+    let last_backup_str = if last_backup_path.exists() {
+        let line = std::fs::read_to_string(&last_backup_path)
+            .unwrap_or_default()
+            .trim()
+            .to_string();
+        // Parse the ISO-8601 we wrote in cmd_backup_export.
+        match chrono::DateTime::parse_from_rfc3339(&line) {
+            Ok(then) => {
+                let now = relicario_core::now_unix();
+                let age = now - then.timestamp();
+                crate::helpers::humanize_age(age.max(0))
+            }
+            Err(_) => "unknown".to_string(),
+        }
+    } else {
+        "never".to_string()
+    };
+
+    println!("Vault:    {}", root.display());
+    println!("Items:    {total_items} total ({active_items} active, {trashed_items} trashed)");
+    println!("Attachments: {attachment_count} ({attachment_bytes} bytes)");
+    println!("Last commit: {last_commit}");
+    println!("Last export: {last_backup_str}");
+    Ok(())
+}

crates/relicario-cli/src/commands/sync.rs

@@ -0,0 +1,11 @@
+//! `relicario sync` — pull --rebase + push.
+
+use anyhow::Result;
+
+pub fn cmd_sync() -> Result<()> {
+    let root = crate::helpers::vault_dir()?;
+    crate::helpers::git_run(&root, &["pull", "--rebase"], "sync: git pull --rebase")?;
+    crate::helpers::git_run(&root, &["push"], "sync: git push")?;
+    eprintln!("Sync complete.");
+    Ok(())
+}

crates/relicario-cli/src/commands/trash.rs

@@ -0,0 +1,149 @@
+//! Trash umbrella: `rm` (soft-delete), `restore`, `purge` (permanent),
+//! `trash list` / `trash empty`.
+
+use anyhow::Result;
+
+use crate::TrashAction;
+
+pub fn cmd_rm(query: String) -> Result<()> {
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let mut manifest = vault.load_manifest()?;
+    let entry = super::resolve_query(&manifest, &query)?;
+    let id = entry.id.clone();
+    let _ = entry;
+    let mut item = vault.load_item(&id)?;
+    item.soft_delete();
+    vault.save_item(&item)?;
+    manifest.upsert(&item);
+    vault.after_manifest_change(&manifest)?;
+    super::commit_paths(&vault, &format!("trash: {} ({})", crate::helpers::sanitize_for_commit(&item.title), item.id.as_str()),
+                 &[&format!("items/{}.enc", item.id.as_str()), "manifest.enc"])?;
+    eprintln!("Moved to trash: {}", item.title);
+    Ok(())
+}
+
+pub fn cmd_restore(query: String) -> Result<()> {
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let mut manifest = vault.load_manifest()?;
+    let entry = super::resolve_query(&manifest, &query)?;
+    let id = entry.id.clone();
+    let _ = entry;
+    let mut item = vault.load_item(&id)?;
+    item.restore();
+    vault.save_item(&item)?;
+    manifest.upsert(&item);
+    vault.after_manifest_change(&manifest)?;
+    super::commit_paths(&vault, &format!("restore: {} ({})", crate::helpers::sanitize_for_commit(&item.title), item.id.as_str()),
+                 &[&format!("items/{}.enc", item.id.as_str()), "manifest.enc"])?;
+    eprintln!("Restored: {}", item.title);
+    Ok(())
+}
+
+/// Filesystem-only purge: removes the item.enc, attachments/<id>/, and updates
+/// the manifest in memory. Returns the relative paths the caller must stage
+/// via `git rm` after the loop. Does NOT invoke any git commands — the caller
+/// batches them.
+pub(super) fn purge_item_filesystem(
+    vault: &crate::session::UnlockedVault,
+    manifest: &mut relicario_core::Manifest,
+    id: &relicario_core::ItemId,
+    title: &str,
+) -> Result<Vec<String>> {
+    use std::{fs, io::ErrorKind};
+
+    let item_rel = format!("items/{}.enc", id.as_str());
+    let att_rel = format!("attachments/{}", id.as_str());
+
+    let ignore_missing = |r: std::io::Result<()>| -> Result<()> {
+        match r {
+            Ok(()) => Ok(()),
+            Err(e) if e.kind() == ErrorKind::NotFound => Ok(()),
+            Err(e) => Err(e.into()),
+        }
+    };
+    ignore_missing(fs::remove_file(vault.item_path(id)))?;
+    ignore_missing(fs::remove_dir_all(vault.root().join("attachments").join(id.as_str())))?;
+    manifest.remove(id);
+
+    eprintln!("Purged: {title}");
+    Ok(vec![item_rel, att_rel])
+}
+
+pub fn cmd_purge(query: String) -> Result<()> {
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let mut manifest = vault.load_manifest()?;
+    let entry = super::resolve_query(&manifest, &query)?;
+    let id = entry.id.clone();
+    let title = entry.title.clone();
+    let _ = entry;
+
+    let paths = purge_item_filesystem(&vault, &mut manifest, &id, &title)?;
+    vault.after_manifest_change(&manifest)?;
+
+    let purge_ctx = format!("purge \"{}\" ({})", title, id.as_str());
+    crate::helpers::git_rm(vault.root(), &paths, &format!("{purge_ctx}: git rm"))?;
+    crate::helpers::git_run(
+        vault.root(),
+        &["add", "manifest.enc"],
+        &format!("{purge_ctx}: git add manifest.enc"),
+    )?;
+    crate::helpers::git_run(
+        vault.root(),
+        &["commit", "-m", &format!("purge: {} ({})", title, id.as_str())],
+        &format!("{purge_ctx}: git commit"),
+    )?;
+    Ok(())
+}
+
+pub fn cmd_trash(action: TrashAction) -> Result<()> {
+    match action {
+        TrashAction::List => super::list::cmd_list(None, None, None, true),
+        TrashAction::Empty => cmd_trash_empty(),
+    }
+}
+
+pub fn cmd_trash_empty() -> Result<()> {
+    use relicario_core::time::now_unix;
+
+    let vault = crate::session::UnlockedVault::unlock_interactive()?;
+    let mut manifest = vault.load_manifest()?;
+    let settings = vault.load_settings()?;
+    let now = now_unix();
+
+    let purgeable: Vec<_> = manifest.items.values()
+        .filter(|e| match e.trashed_at {
+            Some(t) => settings.trash_retention.should_purge(t, now),
+            None => false,
+        })
+        .map(|e| (e.id.clone(), e.title.clone()))
+        .collect();
+
+    if purgeable.is_empty() {
+        eprintln!("nothing past retention window");
+        return Ok(());
+    }
+
+    let mut all_paths: Vec<String> = Vec::new();
+    let purged_count = purgeable.len();
+    for (id, title) in purgeable {
+        let mut paths = purge_item_filesystem(&vault, &mut manifest, &id, &title)?;
+        all_paths.append(&mut paths);
+    }
+
+    vault.after_manifest_change(&manifest)?;
+
+    crate::helpers::git_rm(vault.root(), &all_paths, "trash empty: git rm")?;
+    crate::helpers::git_run(
+        vault.root(),
+        &["add", "manifest.enc"],
+        "trash empty: git add manifest.enc",
+    )?;
+    crate::helpers::git_run(
+        vault.root(),
+        &["commit", "-m", &format!("trash empty: purged {} item(s)", purged_count)],
+        "trash empty: git commit",
+    )?;
+
+    eprintln!("Emptied trash: {} item(s)", purged_count);
+    Ok(())
+}

crates/relicario-cli/src/helpers.rs

@@ -55,6 +55,47 @@ pub fn git_command(repo: &Path, args: &[&str]) -> Command {
     cmd
 }
 
+/// Run `git <args>` in `repo` with the same hardening as `git_command`,
+/// capturing stdout/stderr and reproducing them on failure so the caller
+/// sees git's exact diagnostic instead of just a verb.
+///
+/// `context` should be a short caller-supplied label like `"commit add: <id>"`
+/// or `"sync: git push"`; it prefixes the bail message so the failing call is
+/// identifiable from the error alone.
+///
+/// Trade-off vs. `git_command(...).status()`: this captures the child's stderr
+/// (so live progress disappears during long-running fetches/pushes) but the
+/// captured chunk is replayed verbatim on failure. The win is that
+/// non-interactive callers (tests, hooks, CI, redirected stdout) finally see
+/// pre-receive rejections, signing-key prompts, and dirty-tree complaints
+/// instead of one-line "git X failed" bails. Use `git_command` directly when
+/// live streaming is required.
+pub fn git_run(repo: &Path, args: &[&str], context: &str) -> Result<()> {
+    let output = git_command(repo, args)
+        .output()
+        .with_context(|| format!("{context}: failed to spawn git"))?;
+    if !output.status.success() {
+        if !output.stdout.is_empty() {
+            eprint!("{}", String::from_utf8_lossy(&output.stdout));
+        }
+        if !output.stderr.is_empty() {
+            eprint!("{}", String::from_utf8_lossy(&output.stderr));
+        }
+        bail!("{context}: git failed ({})", output.status);
+    }
+    Ok(())
+}
+
+/// Stage `paths` for removal in one `git rm -rf --ignore-unmatch` invocation.
+/// `--ignore-unmatch` is load-bearing: a previous partial-write crash can
+/// leave the manifest entry without the corresponding `items/<id>.enc` on
+/// disk, and we want the rm to succeed regardless.
+pub fn git_rm(repo: &Path, paths: &[String], context: &str) -> Result<()> {
+    let mut args: Vec<&str> = vec!["rm", "-rf", "--ignore-unmatch"];
+    args.extend(paths.iter().map(String::as_str));
+    git_run(repo, &args, context)
+}
+
 /// Format a Unix-seconds timestamp as an ISO-8601 UTC string.
 /// Audit M11: replaces the old `now_iso8601` helper that actually returned
 /// a numeric string.
@@ -95,6 +136,30 @@ pub fn groups_cache_path(vault_dir: &Path) -> PathBuf {
     vault_dir.join(".relicario").join("groups.cache")
 }
 
+/// Collect all non-empty group names from the manifest and write them to the
+/// plaintext `groups.cache` file so shell completion can enumerate `--group`
+/// candidates without prompting for the vault passphrase.
+///
+/// Failures are silently swallowed — a missing cache is merely a UX degradation,
+/// not a correctness problem.
+///
+/// Visibility note: this is `pub(crate)` so only `session::after_manifest_change`
+/// can call it. The Plan B Phase 4 done-criterion requires every mutating
+/// handler to funnel through the wrapper — exposing this helper to commands/
+/// would let a caller refresh the cache without updating the manifest, breaking
+/// the invariant.
+pub(crate) fn refresh_groups_cache(vault_dir: &Path, manifest: &relicario_core::Manifest) {
+    let mut set = std::collections::BTreeSet::<String>::new();
+    for entry in manifest.items.values() {
+        if let Some(g) = entry.group.as_ref() {
+            if !g.is_empty() {
+                set.insert(g.clone());
+            }
+        }
+    }
+    let _ = write_groups_cache(vault_dir, &set);
+}
+
 /// Write the sorted set of group names to `<vault_dir>/.relicario/groups.cache`,
 /// one name per line. In debug builds, setting `RELICARIO_NO_GROUPS_CACHE`
 /// suppresses the write (developer debugging tool). In release builds the env
@@ -220,6 +285,24 @@ mod tests {
         assert_eq!(sanitize_for_commit("emoji \u{1F4AA}"), "emoji \u{1F4AA}");
     }
 
+    #[test]
+    fn git_run_bails_with_context_on_failure() {
+        // Empty tempdir — `git status` will fail with "not a git repository".
+        let tmp = TempDir::new().unwrap();
+        let err = git_run(tmp.path(), &["status"], "test_ctx").unwrap_err();
+        let msg = format!("{err}");
+        assert!(msg.contains("test_ctx"), "context not in error: {msg}");
+        assert!(msg.contains("git failed"), "missing failure marker: {msg}");
+    }
+
+    #[test]
+    fn git_run_succeeds_for_a_zero_exit_command() {
+        // `git --version` always succeeds and is independent of cwd.
+        let tmp = TempDir::new().unwrap();
+        git_run(tmp.path(), &["--version"], "version probe")
+            .expect("git --version should succeed");
+    }
+
     #[test]
     fn humanize_age_buckets() {
         assert_eq!(humanize_age(0), "just now");

crates/relicario-cli/src/parse.rs

@@ -0,0 +1,19 @@
+//! Thin shims over `relicario-core`'s migrated parsers, kept here so existing
+//! CLI callsites need no import churn. Plan B Phase 7 moved the bodies into
+//! `relicario_core::{time::MonthYear::parse, base32::decode_rfc4648_lenient,
+//! mime::guess_for_extension}`.
+
+use anyhow::Result;
+use relicario_core::MonthYear;
+
+pub(crate) fn parse_month_year(s: &str) -> Result<MonthYear> {
+    Ok(MonthYear::parse(s)?)
+}
+
+pub(crate) fn guess_mime(filename: &str) -> String {
+    relicario_core::mime::guess_for_extension(filename).to_string()
+}
+
+pub(crate) fn base32_decode_lenient(s: &str) -> Result<Vec<u8>> {
+    Ok(relicario_core::base32::decode_rfc4648_lenient(s)?)
+}

crates/relicario-cli/src/prompt.rs

@@ -0,0 +1,195 @@
+//! Interactive prompt helpers for the CLI.
+//!
+//! The `prompt`/`prompt_optional`/`prompt_secret` family reads from stdin /
+//! the TTY; the `prompt_keep`/`prompt_keep_opt`/`prompt_yesno` variants are
+//! used by the edit handlers to keep current values when the user hits enter
+//! at a blank prompt. `prompt_secret` honours `RELICARIO_TEST_ITEM_SECRET`
+//! so integration tests (which don't have a TTY) can inject secrets.
+//! `prompt_or_flag` and `prompt_or_flag_optional` thread a CLI-flag value
+//! through the same path so command handlers can use one call site whether
+//! the value came from the command line or from an interactive prompt.
+
+use anyhow::Result;
+use std::io::BufRead;
+
+/// `rpassword::prompt_password` wrapper that honours `RELICARIO_TEST_ITEM_SECRET`
+/// for integration-test use (rpassword reads /dev/tty by default, which is
+/// unavailable in assert_cmd-spawned children).
+pub(crate) fn prompt_secret(label: &str) -> Result<String> {
+    if let Some(s) = crate::test_item_secret_override() {
+        return Ok(s);
+    }
+    rpassword::prompt_password(label).map_err(Into::into)
+}
+
+fn read_required_line<R: BufRead>(reader: &mut R, label: &str) -> Result<String> {
+    eprint!("{label}: ");
+    std::io::Write::flush(&mut std::io::stderr())?;
+    let mut s = String::new();
+    reader.read_line(&mut s)?;
+    let trimmed = s.trim().to_string();
+    if trimmed.is_empty() { anyhow::bail!("{label} required"); }
+    Ok(trimmed)
+}
+
+fn read_optional_line<R: BufRead>(reader: &mut R, label: &str) -> Result<Option<String>> {
+    eprint!("{label} (leave blank to skip): ");
+    std::io::Write::flush(&mut std::io::stderr())?;
+    let mut s = String::new();
+    reader.read_line(&mut s)?;
+    let trimmed = s.trim().to_string();
+    Ok(if trimmed.is_empty() { None } else { Some(trimmed) })
+}
+
+pub(crate) fn prompt(label: &str) -> Result<String> {
+    let stdin = std::io::stdin();
+    let mut reader = std::io::BufReader::new(stdin.lock());
+    read_required_line(&mut reader, label)
+}
+
+pub(crate) fn prompt_optional(label: &str) -> Result<Option<String>> {
+    let stdin = std::io::stdin();
+    let mut reader = std::io::BufReader::new(stdin.lock());
+    read_optional_line(&mut reader, label)
+}
+
+pub(crate) fn prompt_keep(label: &str, current: &str) -> Result<Option<String>> {
+    eprint!("{label} [{current}]: ");
+    std::io::Write::flush(&mut std::io::stderr())?;
+    let mut s = String::new();
+    std::io::stdin().read_line(&mut s)?;
+    let trimmed = s.trim().to_string();
+    Ok(if trimmed.is_empty() { None } else { Some(trimmed) })
+}
+
+pub(crate) fn prompt_keep_opt(label: &str, current: Option<&str>) -> Result<Option<String>> {
+    let display = current.unwrap_or("(none)");
+    eprint!("{label} [{display}]: ");
+    std::io::Write::flush(&mut std::io::stderr())?;
+    let mut s = String::new();
+    std::io::stdin().read_line(&mut s)?;
+    let trimmed = s.trim().to_string();
+    Ok(if trimmed.is_empty() { None } else { Some(trimmed) })
+}
+
+pub(crate) fn prompt_yesno(label: &str) -> Result<bool> {
+    eprint!("{label} [y/N] ");
+    std::io::Write::flush(&mut std::io::stderr())?;
+    let mut s = String::new();
+    std::io::stdin().read_line(&mut s)?;
+    Ok(matches!(s.trim().to_ascii_lowercase().as_str(), "y" | "yes"))
+}
+
+pub(crate) fn prompt_or_flag<T>(
+    flag: Option<T>,
+    label: &str,
+    parser: impl FnOnce(&str) -> Result<T>,
+) -> Result<T> {
+    let stdin = std::io::stdin();
+    let mut reader = std::io::BufReader::new(stdin.lock());
+    prompt_or_flag_with_reader(flag, label, parser, &mut reader)
+}
+
+pub(crate) fn prompt_or_flag_optional<T>(
+    flag: Option<T>,
+    label: &str,
+    parser: impl FnOnce(&str) -> Result<T>,
+) -> Result<Option<T>> {
+    let stdin = std::io::stdin();
+    let mut reader = std::io::BufReader::new(stdin.lock());
+    prompt_or_flag_optional_with_reader(flag, label, parser, &mut reader)
+}
+
+pub(crate) fn prompt_or_flag_with_reader<T, R: BufRead>(
+    flag: Option<T>,
+    label: &str,
+    parser: impl FnOnce(&str) -> Result<T>,
+    reader: &mut R,
+) -> Result<T> {
+    if let Some(t) = flag {
+        return Ok(t);
+    }
+    let line = read_required_line(reader, label)?;
+    parser(&line)
+}
+
+pub(crate) fn prompt_or_flag_optional_with_reader<T, R: BufRead>(
+    flag: Option<T>,
+    label: &str,
+    parser: impl FnOnce(&str) -> Result<T>,
+    reader: &mut R,
+) -> Result<Option<T>> {
+    if let Some(t) = flag {
+        return Ok(Some(t));
+    }
+    match read_optional_line(reader, label)? {
+        None => Ok(None),
+        Some(line) => parser(&line).map(Some),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Cursor;
+
+    #[test]
+    fn prompt_or_flag_uses_flag_value_when_some() {
+        let mut reader = Cursor::new(Vec::<u8>::new());
+        let got = prompt_or_flag_with_reader::<String, _>(
+            Some("from-flag".to_string()),
+            "Title",
+            |_| panic!("parser must not run when flag is Some"),
+            &mut reader,
+        ).expect("flag value path should succeed");
+        assert_eq!(got, "from-flag");
+    }
+
+    #[test]
+    fn prompt_or_flag_prompts_when_none() {
+        let mut reader = Cursor::new(b"prompted\n".to_vec());
+        let got = prompt_or_flag_with_reader::<String, _>(
+            None,
+            "Title",
+            |s| Ok(s.to_string()),
+            &mut reader,
+        ).expect("prompt path should succeed");
+        assert_eq!(got, "prompted");
+    }
+
+    #[test]
+    fn prompt_or_flag_optional_returns_some_from_flag_without_reading() {
+        let mut reader = Cursor::new(Vec::<u8>::new());
+        let got = prompt_or_flag_optional_with_reader::<String, _>(
+            Some("flag-val".to_string()),
+            "URL",
+            |_| panic!("parser must not run when flag is Some"),
+            &mut reader,
+        ).expect("flag value path should succeed");
+        assert_eq!(got, Some("flag-val".to_string()));
+    }
+
+    #[test]
+    fn prompt_or_flag_optional_prompts_and_blank_yields_none() {
+        let mut reader = Cursor::new(b"\n".to_vec());
+        let got = prompt_or_flag_optional_with_reader::<String, _>(
+            None,
+            "URL",
+            |_| panic!("parser must not run on blank input"),
+            &mut reader,
+        ).expect("blank prompt should succeed with None");
+        assert_eq!(got, None);
+    }
+
+    #[test]
+    fn prompt_or_flag_optional_prompts_and_value_runs_parser() {
+        let mut reader = Cursor::new(b"  42  \n".to_vec());
+        let got = prompt_or_flag_optional_with_reader::<u32, _>(
+            None,
+            "Number",
+            |s| s.parse::<u32>().map_err(Into::into),
+            &mut reader,
+        ).expect("value should parse");
+        assert_eq!(got, Some(42));
+    }
+}

crates/relicario-cli/src/session.rs

@@ -69,9 +69,15 @@ impl UnlockedVault {
         Ok(decrypt_manifest(&bytes, &self.master_key)?)
     }
 
-    pub fn save_manifest(&self, manifest: &Manifest) -> Result<()> {
+    /// Save the manifest and refresh the plaintext groups.cache. This is the
+    /// canonical "I just mutated the manifest" funnel — every command that
+    /// changes the manifest goes through this method, so cache freshness is
+    /// a compile-time invariant rather than a discipline rule.
+    pub fn after_manifest_change(&self, manifest: &Manifest) -> Result<()> {
         let bytes = encrypt_manifest(manifest, &self.master_key)?;
-        atomic_write(&self.manifest_path(), &bytes)
+        atomic_write(&self.manifest_path(), &bytes)?;
+        crate::helpers::refresh_groups_cache(&self.root, manifest);
+        Ok(())
     }
 
     pub fn load_settings(&self) -> Result<VaultSettings> {
@@ -107,17 +113,52 @@ fn read_salt(root: &Path) -> Result<[u8; 32]> {
     Ok(salt)
 }
 
-fn read_params(root: &Path) -> Result<KdfParams> {
-    // params.json layout: { "format_version": 2, "kdf": { "argon2_m": ..., ... }, ... }
-    // We extract only the "kdf" sub-object and deserialize it as KdfParams.
-    #[derive(serde::Deserialize)]
-    struct ParamsFile {
-        kdf: KdfParams,
+#[derive(serde::Serialize, serde::Deserialize)]
+pub(crate) struct ParamsFile {
+    pub format_version: u32,
+    pub kdf: ParamsKdf,
+    pub aead: String,
+    pub salt_path: String,
+}
+
+#[derive(serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub(crate) struct ParamsKdf {
+    pub algorithm: String,
+    pub argon2_m: u32,
+    pub argon2_t: u32,
+    pub argon2_p: u32,
+}
+
+impl ParamsFile {
+    pub fn for_new_vault(params: &KdfParams) -> Self {
+        Self {
+            format_version: 2,
+            kdf: ParamsKdf {
+                algorithm: "argon2id-v0x13".into(),
+                argon2_m: params.argon2_m,
+                argon2_t: params.argon2_t,
+                argon2_p: params.argon2_p,
+            },
+            aead: "xchacha20poly1305".into(),
+            salt_path: ".relicario/salt".into(),
+        }
     }
+
+    pub fn to_kdf_params(&self) -> KdfParams {
+        KdfParams {
+            argon2_m: self.kdf.argon2_m,
+            argon2_t: self.kdf.argon2_t,
+            argon2_p: self.kdf.argon2_p,
+        }
+    }
+}
+
+fn read_params(root: &Path) -> Result<KdfParams> {
     let s = fs::read_to_string(root.join(".relicario").join("params.json"))
         .context("failed to read .relicario/params.json")?;
     let pf: ParamsFile = serde_json::from_str(&s).context("failed to parse params.json")?;
-    Ok(pf.kdf)
+    Ok(pf.to_kdf_params())
 }
 
 /// Locate the reference image path via `RELICARIO_IMAGE` env var or interactive prompt.
@@ -149,3 +190,78 @@ fn atomic_write(path: &Path, data: &[u8]) -> Result<()> {
     fs::rename(&tmp, path).with_context(|| format!("failed to rename {}", path.display()))?;
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const FIXTURE: &str = r#"{
+  "format_version": 2,
+  "kdf": {
+    "algorithm": "argon2id-v0x13",
+    "argon2_m": 65536,
+    "argon2_t": 3,
+    "argon2_p": 4
+  },
+  "aead": "xchacha20poly1305",
+  "salt_path": ".relicario/salt"
+}"#;
+
+    #[test]
+    fn params_file_round_trips_current_layout() {
+        let pf: ParamsFile = serde_json::from_str(FIXTURE).expect("parse fixture");
+        assert_eq!(pf.format_version, 2);
+        assert_eq!(pf.kdf.algorithm, "argon2id-v0x13");
+        assert_eq!(pf.kdf.argon2_m, 65536);
+        assert_eq!(pf.kdf.argon2_t, 3);
+        assert_eq!(pf.kdf.argon2_p, 4);
+        assert_eq!(pf.aead, "xchacha20poly1305");
+        assert_eq!(pf.salt_path, ".relicario/salt");
+
+        let kdf = pf.to_kdf_params();
+        assert_eq!(kdf.argon2_m, 65536);
+        assert_eq!(kdf.argon2_t, 3);
+        assert_eq!(kdf.argon2_p, 4);
+
+        let serialized = serde_json::to_string(&pf).expect("re-serialize");
+        let pf2: ParamsFile = serde_json::from_str(&serialized).expect("parse re-serialized");
+        assert_eq!(pf2.format_version, 2);
+        assert_eq!(pf2.kdf.algorithm, "argon2id-v0x13");
+        assert_eq!(pf2.kdf.argon2_m, 65536);
+        assert_eq!(pf2.kdf.argon2_t, 3);
+        assert_eq!(pf2.kdf.argon2_p, 4);
+        assert_eq!(pf2.aead, "xchacha20poly1305");
+        assert_eq!(pf2.salt_path, ".relicario/salt");
+    }
+
+    #[test]
+    fn for_new_vault_produces_expected_shape() {
+        let params = KdfParams { argon2_m: 65536, argon2_t: 3, argon2_p: 4 };
+        let pf = ParamsFile::for_new_vault(&params);
+        let v = serde_json::to_value(&pf).expect("to_value");
+        assert_eq!(v["format_version"], 2);
+        assert_eq!(v["kdf"]["algorithm"], "argon2id-v0x13");
+        assert_eq!(v["kdf"]["argon2_m"], 65536);
+        assert_eq!(v["kdf"]["argon2_t"], 3);
+        assert_eq!(v["kdf"]["argon2_p"], 4);
+        assert_eq!(v["aead"], "xchacha20poly1305");
+        assert_eq!(v["salt_path"], ".relicario/salt");
+    }
+
+    #[test]
+    fn after_manifest_change_writes_manifest_and_groups_cache() {
+        let dir = tempfile::TempDir::new().unwrap();
+        let root = dir.path().to_path_buf();
+        std::fs::create_dir_all(root.join(".relicario")).unwrap();
+        std::fs::create_dir_all(root.join("items")).unwrap();
+        let vault = UnlockedVault {
+            root: root.clone(),
+            master_key: Zeroizing::new([0u8; 32]),
+        };
+        let manifest = Manifest::new();
+
+        vault.after_manifest_change(&manifest).unwrap();
+        assert!(root.join("manifest.enc").exists());
+        assert!(root.join(".relicario/groups.cache").exists());
+    }
+}

crates/relicario-cli/tests/basic_flows.rs

@@ -109,6 +109,72 @@ fn rm_restore_purge_cycle() {
     assert!(!String::from_utf8(out.stdout).unwrap().contains("target"));
 }
 
+#[test]
+fn trash_empty_batches_into_one_commit() {
+    let v = TestVault::init();
+
+    // Add 3 items.
+    for title in ["alpha", "bravo", "charlie"] {
+        let out = v.run(&[
+            "add", "login",
+            "--title", title,
+            "--username", "u",
+            "--password", "p",
+        ]);
+        assert!(out.status.success(), "add {title} failed");
+    }
+
+    // Soft-delete all 3.
+    for title in ["alpha", "bravo", "charlie"] {
+        let out = v.run(&["rm", title]);
+        assert!(out.status.success(), "rm {title} failed");
+    }
+
+    // Set retention to 0 days so the recently-trashed items become purgeable
+    // (should_purge: now - trashed_at > 0 * 86400 = 0).
+    let out = v.run(&["settings", "trash-retention", "--days", "0"]);
+    assert!(out.status.success(), "settings trash-retention failed");
+
+    // should_purge uses strict > on (now - trashed_at), so equal-second
+    // timestamps don't qualify.
+    std::thread::sleep(std::time::Duration::from_secs(1));
+
+    // Count commits before.
+    let before = std::process::Command::new("git")
+        .args(["rev-list", "--count", "HEAD"])
+        .current_dir(v.path())
+        .output()
+        .unwrap();
+    let before_count: u32 = String::from_utf8(before.stdout).unwrap().trim().parse().unwrap();
+
+    // Run trash empty.
+    let out = v.run(&["trash", "empty"]);
+    assert!(out.status.success(), "trash empty failed: stderr={}",
+            String::from_utf8_lossy(&out.stderr));
+
+    // Count commits after.
+    let after = std::process::Command::new("git")
+        .args(["rev-list", "--count", "HEAD"])
+        .current_dir(v.path())
+        .output()
+        .unwrap();
+    let after_count: u32 = String::from_utf8(after.stdout).unwrap().trim().parse().unwrap();
+
+    assert_eq!(
+        after_count - before_count, 1,
+        "trash empty should fire exactly one commit; before={before_count} after={after_count}"
+    );
+
+    // The remaining `list --trashed` should be empty.
+    let out = v.run(&["list", "--trashed"]);
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    let stderr = String::from_utf8(out.stderr).unwrap();
+    assert!(
+        !stdout.contains("alpha") && !stdout.contains("bravo") && !stdout.contains("charlie"),
+        "items still in trashed list: stdout={stdout} stderr={stderr}"
+    );
+}
+
 #[test]
 fn generate_random_and_bip39() {
     let dir = tempfile::TempDir::new().unwrap();

crates/relicario-core/ARCHITECTURE.md

@@ -1,5 +1,7 @@
 # Architecture: relicario-core
 
+> **Audience:** contributors editing or extending `relicario-core`. This doc owns the module map for this crate, module-level invariants (e.g., no filesystem, no network), key flows at the module level, and the crate's test architecture. **Does NOT own:** crypto primitives or threat model (see [../../docs/CRYPTO.md](../../docs/CRYPTO.md), [../../docs/SECURITY.md](../../docs/SECURITY.md)), wire formats (see [../../docs/FORMATS.md](../../docs/FORMATS.md)).
+
 ## What this crate is for
 
 `relicario-core` is the platform-agnostic cryptographic and data-model heart of the
@@ -101,6 +103,38 @@ Pipeline" and "Crate Layout").
   auth factor. Owns its own `YChannel`, `EmbedRegion`, 8×8 DCT/IDCT,
   Quantization Index Modulation, and crop-recovery extractor. No other module
   imports it; it is consumed only via the public re-export from `lib.rs`.
+- **`backup.rs`** — `.relbak` v1 container format: `pack_backup` /
+  `unpack_backup` plus the `BackupInput` / `BackupOutput` / `BackupItem` /
+  `BackupAttachment` shapes. Wraps a zstd-compressed JSON envelope of vault
+  bytes (salt, params.json, devices.json, manifest, settings, items,
+  attachments, optional reference JPEG, optional `.git/` tar) in an
+  XChaCha20-Poly1305 envelope keyed by Argon2id over a user-chosen *backup*
+  passphrase. The backup key is independent of any vault master key, and
+  Argon2id parameters are pinned to the v1 values (m=64MiB, t=3, p=4) so a v1
+  reader doesn't need to negotiate them.
+- **`import_lastpass.rs`** — `parse_lastpass_csv` plus `ImportWarning`. Pure
+  bytes-in / `Vec<Item>`-out LastPass CSV importer: validates the fixed
+  8-column header, mints fresh IDs and timestamps for each row, downgrades or
+  skips malformed rows into `ImportWarning`s instead of aborting the import.
+  Only fatal error is a missing/malformed header.
+- **`device.rs`** — Device-identity surface: `DeviceEntry`, `RevokedEntry`,
+  `generate_keypair`, `sign`, `verify`, `fingerprint`. ed25519 in OpenSSH
+  format (so private keys are interchangeable with `ssh-keygen`-produced
+  keys); the same module backs both `.relicario/devices.json` entries and the
+  server's pre-receive commit-verification hook.
+- **`tar_safe.rs`** — `safe_unpack_git_archive` + `DEFAULT_MAX_UNCOMPRESSED`
+  (1 GiB). Hardened tar reader used by `backup::unpack_backup` for the
+  bundled `.git/` directory: rejects `..` components, absolute paths, Windows
+  drive prefixes, symlinks, hardlinks, and any entry whose declared size
+  (or running total across all entries) exceeds the supplied cap.
+- **`recovery_qr.rs`** — `generate_recovery_qr` / `unwrap_recovery_qr` plus
+  `recovery_qr_to_svg`. Produces a 109-byte XChaCha20-Poly1305 envelope
+  around the 32-byte image_secret, keyed by Argon2id over a user-chosen
+  recovery passphrase with the domain-separation prefix
+  `b"relicario-recovery-v1\0"`. Parameters are pinned at module scope —
+  changing them invalidates every printed QR — and both salt and nonce are
+  freshly randomized per call so two QRs printed from the same inputs are
+  different bytes.
 
 ## Invariants & contracts
 
@@ -386,11 +420,11 @@ when subsequent `decrypt_*` returns `RelicarioError::Decrypt`.
   `generators::bip39_passphrase`. A single `rand::thread_rng()` call exists
   inside an `imgsecret` test (`imgsecret.rs:1033`) to generate a random test
   secret; production code is `OsRng` only.
-- **`ed25519-dalek` is a dependency placeholder.** Listed in
-  `Cargo.toml:17` but unused in `src/`. It exists for the future
-  device-key surface (`RelicarioError::DeviceKey` is the reserved variant,
-  `error.rs:84-88`); device-key signing currently happens in
-  `relicario-cli` instead.
+- **`ed25519-dalek` is consumed by `device.rs`.** Together with `ssh-key` (for
+  OpenSSH wire encoding) it backs `generate_keypair`, `sign`, and `verify` —
+  the same primitives the CLI uses to populate `.relicario/devices.json` and
+  the server uses to verify pre-receive commit signatures. The corresponding
+  error variant is `RelicarioError::DeviceKey`.
 
 ## Test architecture
 
@@ -512,3 +546,7 @@ round-trip, and the oversized-image-header rejection path.
   source in this crate** (`time.rs:6-8`). Tests that need determinism pass an
   explicit `now: i64` to `prune_history` (`item.rs:219`) and similar — they
   do not stub `now_unix`.
+
+---
+
+**Next:** [../relicario-cli/ARCHITECTURE.md](../relicario-cli/ARCHITECTURE.md) — how the CLI wraps the core.

crates/relicario-core/Cargo.toml

@@ -1,8 +1,9 @@
 [package]
 name = "relicario-core"
-version = "0.2.0"
+version = "0.7.0"
 edition = "2021"
 description = "Core library for relicario password manager"
+license = "GPL-3.0-or-later"
 
 [dependencies]
 thiserror = "2"

crates/relicario-core/src/base32.rs

@@ -0,0 +1,132 @@
+//! RFC 4648 base32 codec, no-padding form, lenient on input.
+//!
+//! The encoder produces canonical no-padding RFC 4648 output (uppercase ASCII).
+//! The decoder is lenient: case-insensitive, optional `=` padding, whitespace
+//! anywhere is stripped before decoding.
+//!
+//! Steam Guard's authenticator uses a different (de-ambiguated) alphabet —
+//! see `crate::item_types::totp::STEAM_ALPHABET`. That codec is intentionally
+//! NOT routed through this module.
+
+use crate::error::{RelicarioError, Result};
+
+const ALPHA: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+/// RFC 4648 base32 encoder, no-padding form. Output is uppercase ASCII.
+pub fn encode_rfc4648(bytes: &[u8]) -> String {
+    let mut out = String::new();
+    let mut buffer: u32 = 0;
+    let mut bits: u32 = 0;
+    for &b in bytes {
+        buffer = (buffer << 8) | (b as u32);
+        bits += 8;
+        while bits >= 5 {
+            let idx = ((buffer >> (bits - 5)) & 0x1f) as usize;
+            out.push(ALPHA[idx] as char);
+            bits -= 5;
+        }
+    }
+    if bits > 0 {
+        let idx = ((buffer << (5 - bits)) & 0x1f) as usize;
+        out.push(ALPHA[idx] as char);
+    }
+    out
+}
+
+/// RFC 4648 base32 decoder, lenient on input.
+///
+/// Accepts upper- or lower-case letters, optional `=` padding, and whitespace
+/// anywhere. Trailing bits less than a full byte are silently discarded
+/// (canonical RFC 4648 decode).
+pub fn decode_rfc4648_lenient(s: &str) -> Result<Vec<u8>> {
+    let cleaned: String = s
+        .chars()
+        .filter(|c| !c.is_whitespace())
+        .collect::<String>()
+        .to_ascii_uppercase();
+    let trimmed = cleaned.trim_end_matches('=');
+    let mut out: Vec<u8> = Vec::with_capacity(trimmed.len() * 5 / 8);
+    let mut buffer: u32 = 0;
+    let mut bits: u32 = 0;
+    for ch in trimmed.bytes() {
+        let idx = ALPHA.iter().position(|&a| a == ch).ok_or_else(|| {
+            RelicarioError::InvalidBase32(format!("non-alphabet character {:?}", ch as char))
+        })?;
+        buffer = (buffer << 5) | (idx as u32);
+        bits += 5;
+        if bits >= 8 {
+            bits -= 8;
+            out.push(((buffer >> bits) & 0xff) as u8);
+        }
+    }
+    Ok(out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn encode_rfc4648_matches_rfc_test_vectors() {
+        // RFC 4648 §10 test vectors, no-padding form.
+        assert_eq!(encode_rfc4648(b""), "");
+        assert_eq!(encode_rfc4648(b"f"), "MY");
+        assert_eq!(encode_rfc4648(b"fo"), "MZXQ");
+        assert_eq!(encode_rfc4648(b"foo"), "MZXW6");
+        assert_eq!(encode_rfc4648(b"foob"), "MZXW6YQ");
+        assert_eq!(encode_rfc4648(b"fooba"), "MZXW6YTB");
+        assert_eq!(encode_rfc4648(b"foobar"), "MZXW6YTBOI");
+    }
+
+    #[test]
+    fn decode_rfc4648_lenient_inverts_encoder_on_known_vectors() {
+        let cases: &[(&str, &[u8])] = &[
+            ("", b""),
+            ("MY", b"f"),
+            ("MZXQ", b"fo"),
+            ("MZXW6", b"foo"),
+            ("MZXW6YQ", b"foob"),
+            ("MZXW6YTB", b"fooba"),
+            ("MZXW6YTBOI", b"foobar"),
+        ];
+        for (s, want) in cases {
+            assert_eq!(&decode_rfc4648_lenient(s).unwrap()[..], *want);
+        }
+    }
+
+    #[test]
+    fn decode_rfc4648_lenient_accepts_lowercase_and_mixed_case() {
+        assert_eq!(decode_rfc4648_lenient("mzxw6").unwrap(), b"foo");
+        assert_eq!(decode_rfc4648_lenient("MzXw6yTbOi").unwrap(), b"foobar");
+    }
+
+    #[test]
+    fn decode_rfc4648_lenient_strips_optional_padding() {
+        assert_eq!(decode_rfc4648_lenient("MY======").unwrap(), b"f");
+        assert_eq!(decode_rfc4648_lenient("MZXW6===").unwrap(), b"foo");
+        assert_eq!(decode_rfc4648_lenient("MZXW6YTBOI======").unwrap(), b"foobar");
+    }
+
+    #[test]
+    fn decode_rfc4648_lenient_strips_whitespace_anywhere() {
+        assert_eq!(decode_rfc4648_lenient(" MZXW 6YTB OI ").unwrap(), b"foobar");
+        assert_eq!(decode_rfc4648_lenient("MZXW\n6YTB\tOI").unwrap(), b"foobar");
+    }
+
+    #[test]
+    fn decode_rfc4648_lenient_rejects_non_alphabet_chars() {
+        assert!(matches!(
+            decode_rfc4648_lenient("MY1"),
+            Err(RelicarioError::InvalidBase32(_))
+        ));
+        assert!(decode_rfc4648_lenient("???").is_err());
+        assert!(decode_rfc4648_lenient("MZ!XW").is_err());
+    }
+
+    #[test]
+    fn encode_decode_round_trips_arbitrary_bytes() {
+        let bytes: Vec<u8> = (0u8..=255).collect();
+        let encoded = encode_rfc4648(&bytes);
+        assert_eq!(decode_rfc4648_lenient(&encoded).unwrap(), bytes);
+    }
+}

crates/relicario-core/src/error.rs

@@ -123,6 +123,17 @@ pub enum RelicarioError {
     /// Recovery QR generation or parsing failed.
     #[error("recovery QR: {0}")]
     RecoveryQr(String),
+
+    /// Base32 decoding failed (non-alphabet character or other malformed
+    /// input). Emitted by [`crate::base32::decode_rfc4648_lenient`] and any
+    /// typed wrappers that delegate to it.
+    #[error("invalid base32: {0}")]
+    InvalidBase32(String),
+
+    /// Card-expiry month/year string failed to parse. Emitted by
+    /// [`crate::time::MonthYear::parse`].
+    #[error("invalid month/year: {0}")]
+    InvalidMonthYear(String),
 }
 
 /// Crate-wide result alias, reducing boilerplate in function signatures.

crates/relicario-core/src/import_lastpass.rs

@@ -158,8 +158,8 @@ fn map_row(
     let totp = if totp_raw.is_empty() {
         None
     } else {
-        match decode_base32_totp(totp_raw) {
-            Some(bytes) if !bytes.is_empty() => Some(crate::item_types::TotpConfig {
+        match crate::base32::decode_rfc4648_lenient(totp_raw) {
+            Ok(bytes) if !bytes.is_empty() => Some(crate::item_types::TotpConfig {
                 secret: Zeroizing::new(bytes),
                 algorithm: crate::item_types::TotpAlgorithm::Sha1,
                 digits: 6,
@@ -196,25 +196,3 @@ fn map_row(
     (Some(item), warning)
 }
 
-/// Decode a base32-encoded TOTP secret per RFC 4648, case-insensitive,
-/// padding optional. Returns None if the input contains any non-alphabet
-/// character (after upper-casing). Used by the LastPass importer.
-fn decode_base32_totp(secret: &str) -> Option<Vec<u8>> {
-    const ALPHA: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
-    let upper = secret.trim().trim_end_matches('=').to_ascii_uppercase();
-    if upper.is_empty() { return None; }
-
-    let mut out = Vec::with_capacity(upper.len() * 5 / 8);
-    let mut buffer: u32 = 0;
-    let mut bits: u32 = 0;
-    for ch in upper.bytes() {
-        let idx = ALPHA.iter().position(|&a| a == ch)?;
-        buffer = (buffer << 5) | (idx as u32);
-        bits += 5;
-        if bits >= 8 {
-            bits -= 8;
-            out.push(((buffer >> bits) & 0xFF) as u8);
-        }
-    }
-    Some(out)
-}

crates/relicario-core/src/item.rs

@@ -244,7 +244,7 @@ fn serialize_history_value(value: &FieldValue) -> Result<Zeroizing<String>> {
         FieldValue::Concealed(c) => Zeroizing::new(c.as_str().to_owned()),
         FieldValue::Totp(cfg) => {
             // Store the base32-encoded secret string for human-recognizability.
-            let s = base32_encode(&cfg.secret);
+            let s = crate::base32::encode_rfc4648(&cfg.secret);
             Zeroizing::new(s)
         }
         _ => return Err(RelicarioError::Format("not a history-tracked kind".into())),
@@ -252,28 +252,6 @@ fn serialize_history_value(value: &FieldValue) -> Result<Zeroizing<String>> {
     Ok(s)
 }
 
-/// Minimal RFC 4648 base32 (no padding) for TOTP secret history serialization.
-fn base32_encode(bytes: &[u8]) -> String {
-    const ALPHA: &[u8] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
-    let mut out = String::new();
-    let mut buffer: u32 = 0;
-    let mut bits: u32 = 0;
-    for &b in bytes {
-        buffer = (buffer << 8) | (b as u32);
-        bits += 8;
-        while bits >= 5 {
-            let idx = ((buffer >> (bits - 5)) & 0x1f) as usize;
-            out.push(ALPHA[idx] as char);
-            bits -= 5;
-        }
-    }
-    if bits > 0 {
-        let idx = ((buffer << (5 - bits)) & 0x1f) as usize;
-        out.push(ALPHA[idx] as char);
-    }
-    out
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;

crates/relicario-core/src/item_types/totp.rs

@@ -10,6 +10,9 @@ use crate::error::{RelicarioError, Result};
 
 /// Steam Mobile Authenticator's 5-character output alphabet.
 /// Deliberately excludes ambiguous glyphs (0/O, 1/I/L, S/5, A/Z).
+///
+/// Not RFC 4648 — Steam Guard's de-ambiguated alphabet; see [`crate::base32`]
+/// for the standard implementation.
 const STEAM_ALPHABET: &[u8] = b"23456789BCDFGHJKMNPQRTVWXY";
 
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
@@ -21,6 +24,14 @@ pub struct TotpCore {
     pub label: Option<String>,
 }
 
+impl TotpConfig {
+    /// Decode a base32-encoded TOTP secret (RFC 4648, lenient input) into the
+    /// canonical `Zeroizing<Vec<u8>>` form used in [`Self::secret`].
+    pub fn parse_secret(s: &str) -> Result<Zeroizing<Vec<u8>>> {
+        Ok(Zeroizing::new(crate::base32::decode_rfc4648_lenient(s)?))
+    }
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TotpConfig {
     /// Raw bytes of the TOTP secret (decoded from base32 when imported).

crates/relicario-core/src/lib.rs

@@ -14,6 +14,8 @@
 //! - [`crypto`] — Argon2id KDF (length-prefixed inputs, Zeroizing output) and
 //!   XChaCha20-Poly1305 AEAD with VERSION_BYTE 0x02.
 //! - [`ids`] — `ItemId`, `FieldId`, and content-addressed `AttachmentId`.
+//! - [`base32`] — RFC 4648 base32 codec used for TOTP secret encode/decode.
+//! - [`mime`] — Filename-extension → MIME-type guess for attachment storage.
 //! - [`time`] — unix-seconds + `MonthYear` for card expiries.
 //! - [`item_types`] — Per-type cores (`LoginCore`, `SecureNoteCore`, etc.) and the
 //!   `ItemCore`/`ItemType` enums.
@@ -46,6 +48,10 @@ pub use crypto::{decrypt, derive_master_key, encrypt, KdfParams, VERSION_BYTE};
 pub mod ids;
 pub use ids::{AttachmentId, FieldId, ItemId};
 
+pub mod base32;
+
+pub mod mime;
+
 pub mod time;
 pub use time::{now_unix, MonthYear};
 

crates/relicario-core/src/mime.rs

@@ -0,0 +1,49 @@
+//! Tiny extension → MIME map for the small set of file types Relicario
+//! attaches today. Unknown extensions fall back to `application/octet-stream`.
+
+/// Guess a MIME type from a filename's extension. Case-insensitive.
+pub fn guess_for_extension(filename: &str) -> &'static str {
+    let lower = filename.to_ascii_lowercase();
+    match lower.rsplit_once('.').map(|(_, ext)| ext).unwrap_or("") {
+        "pdf" => "application/pdf",
+        "png" => "image/png",
+        "jpg" | "jpeg" => "image/jpeg",
+        "txt" => "text/plain",
+        "json" => "application/json",
+        _ => "application/octet-stream",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn known_extensions_match() {
+        assert_eq!(guess_for_extension("doc.pdf"), "application/pdf");
+        assert_eq!(guess_for_extension("photo.png"), "image/png");
+        assert_eq!(guess_for_extension("photo.jpg"), "image/jpeg");
+        assert_eq!(guess_for_extension("photo.jpeg"), "image/jpeg");
+        assert_eq!(guess_for_extension("notes.txt"), "text/plain");
+        assert_eq!(guess_for_extension("data.json"), "application/json");
+    }
+
+    #[test]
+    fn extension_match_is_case_insensitive() {
+        assert_eq!(guess_for_extension("doc.PDF"), "application/pdf");
+        assert_eq!(guess_for_extension("photo.JPEG"), "image/jpeg");
+    }
+
+    #[test]
+    fn unknown_or_missing_extension_falls_back() {
+        assert_eq!(guess_for_extension("unknown.xyz"), "application/octet-stream");
+        assert_eq!(guess_for_extension("noextension"), "application/octet-stream");
+        assert_eq!(guess_for_extension(""), "application/octet-stream");
+    }
+
+    #[test]
+    fn uses_extension_after_last_dot() {
+        assert_eq!(guess_for_extension("path/to/file.pdf"), "application/pdf");
+        assert_eq!(guess_for_extension("archive.tar.gz"), "application/octet-stream");
+    }
+}

crates/relicario-core/src/recovery_qr.rs

@@ -1,13 +1,107 @@
+//! Recovery-QR encoding for the reference image_secret.
+//!
+//! ## What this module produces
+//!
+//! Given a user-chosen recovery passphrase and the 32-byte image_secret
+//! (extracted from the reference JPEG via [`crate::imgsecret::extract`]), this
+//! module produces a 109-byte sealed payload that — at recovery time, with the
+//! same passphrase — yields the original image_secret back. The payload is
+//! intended to be rendered as a QR v40 EcLevel::M SVG via [`recovery_qr_to_svg`]
+//! and printed on paper, so a user who loses access to the reference JPEG can
+//! still unlock their vault if they remember the recovery passphrase.
+//!
+//! ## Why the format is structured this way
+//!
+//! The payload is an XChaCha20-Poly1305 envelope around the image_secret. The
+//! AEAD key (the "wrap key") is derived by Argon2id from a domain-separated
+//! input:
+//!
+//! ```text
+//! kdf_input = b"relicario-recovery-v1\0"
+//!          || u64_be(len(nfc(passphrase)))
+//!          || nfc(passphrase)
+//! wrap_key  = Argon2id(kdf_input, kdf_salt, RECOVERY_PRODUCTION_PARAMS) -> 32 bytes
+//! ```
+//!
+//! The `b"relicario-recovery-v1\0"` prefix is **domain separation**: it
+//! guarantees that even if the user reuses their vault passphrase as their
+//! recovery passphrase, the wrap key derived here can never collide with a
+//! vault master key derived in [`crate::crypto::derive_master_key`] (which has
+//! a different input shape entirely — passphrase + image_secret, no prefix).
+//! Without this prefix, a determined attacker who somehow recovered a wrap key
+//! could try it as a master key and vice versa.
+//!
+//! Both `kdf_salt` and `wrap_nonce` are freshly randomized per call to
+//! [`generate_recovery_qr`], so two QRs printed from the same passphrase and
+//! image_secret are different bytes — the printed QR does not leak whether
+//! the user has printed others before.
+//!
+//! ## Parameter-pinning rationale
+//!
+//! The Argon2id parameters used here are NOT [`crate::crypto::KdfParams::default`].
+//! They are pinned in `RECOVERY_PRODUCTION_PARAMS` at the value
+//! `KdfParams { argon2_m: 65536, argon2_t: 3, argon2_p: 4 }` — the same values
+//! the default happens to have *today*, but deliberately re-stated rather than
+//! referenced. This is because `KdfParams::default()` may evolve as we re-tune
+//! Argon2 cost for newer hardware, and a recovery QR printed on paper has no
+//! way to negotiate parameters at decode time. Changing the pinned values here
+//! would silently invalidate every recovery QR a user has ever printed under
+//! the previous parameter set. The const lives at module scope so the
+//! "pinned, do not change once shipped" property is visible at every use site.
+
 use chacha20poly1305::{XChaCha20Poly1305, Key, KeyInit, aead::Aead};
 use rand::RngCore;
 use unicode_normalization::UnicodeNormalization;
 use zeroize::Zeroizing;
 use crate::{crypto::KdfParams, error::{RelicarioError, Result}};
 
+// Recovery QR payload — 109 bytes total:
+//
+//  byte    field           length
+//  ------  --------------  ------
+//  0..4    MAGIC = "RREC"  4
+//  4..5    VERSION = 0x01  1
+//  5..37   kdf_salt        32   (random per QR)
+//  37..61  wrap_nonce      24   (random per QR)
+//  61..109 ciphertext      48   (32 image_secret + 16 AEAD tag)
+//  ------------------------------
+//  total                   109
 const MAGIC: &[u8; 4] = b"RREC";
 const VERSION: u8 = 0x01;
 const PAYLOAD_LEN: usize = 4 + 1 + 32 + 24 + 48; // 109
 
+// Static assertion that the documented layout above and the PAYLOAD_LEN
+// constant cannot drift apart. If a future edit changes one without the other,
+// this fails to compile.
+const _: () = assert!(PAYLOAD_LEN == 4 + 1 + 32 + 24 + 48);
+
+// Named slice ranges derived from the layout offsets above. Used by
+// `unwrap_recovery_qr_with_params` so the byte-position arithmetic at the
+// parse site is self-documenting.
+const KDF_SALT_RANGE: std::ops::Range<usize> = 5..37;
+const WRAP_NONCE_RANGE: std::ops::Range<usize> = 37..61;
+const CIPHERTEXT_RANGE: std::ops::Range<usize> = 61..109;
+
+/// Pinned recovery-QR Argon2id parameters. Re-states `KdfParams::default()`'s
+/// values rather than referencing them, because a recovery QR printed under
+/// one parameter set cannot be decoded under another. **Once shipped, these
+/// values MUST NOT change** — doing so silently invalidates every previously
+/// printed QR. See the module header for full rationale.
+const RECOVERY_PRODUCTION_PARAMS: KdfParams = KdfParams {
+    argon2_m: 65536,
+    argon2_t: 3,
+    argon2_p: 4,
+};
+
+/// A sealed 109-byte recovery payload. The bytes are an opaque package — they
+/// only become useful when fed back through [`unwrap_recovery_qr`] together
+/// with the recovery passphrase that was used to produce them.
+///
+/// [`as_bytes`](Self::as_bytes) is the only accessor. The bytes are designed to
+/// travel as a single unit; the supported transport is rendering via
+/// [`recovery_qr_to_svg`] and printing the QR on paper, but a hex string
+/// (sneakernet-friendly) works equally well as long as the full 109 bytes
+/// are preserved.
 pub struct RecoveryQrPayload {
     bytes: [u8; PAYLOAD_LEN],
 }
@@ -24,15 +118,12 @@ fn recovery_kdf_input(passphrase: &str) -> Vec<u8> {
     let prefix = b"relicario-recovery-v1\0";
     let mut input = Vec::with_capacity(prefix.len() + 8 + nfc_bytes.len());
     input.extend_from_slice(prefix);
+    // length-prefix on nfc_bytes mirrors crypto::derive_master_key (audit H1)
     input.extend_from_slice(&(nfc_bytes.len() as u64).to_be_bytes());
     input.extend_from_slice(nfc_bytes);
     input
 }
 
-fn production_params() -> KdfParams {
-    KdfParams { argon2_m: 65536, argon2_t: 3, argon2_p: 4 }
-}
-
 fn derive_wrap_key(
     passphrase: &str,
     kdf_salt: &[u8; 32],
@@ -42,11 +133,38 @@ fn derive_wrap_key(
     crate::crypto::derive_master_key_raw(&input, kdf_salt, params)
 }
 
+/// Produce a sealed [`RecoveryQrPayload`] from the recovery passphrase and the
+/// 32-byte image_secret.
+///
+/// # Inputs
+///
+/// - `passphrase`: the user's recovery passphrase (UTF-8). Independent of the
+///   vault passphrase, but the user may reuse them — the
+///   `b"relicario-recovery-v1\0"` domain-separation prefix in the KDF input
+///   guarantees the wrap key still cannot collide with a vault master key.
+/// - `image_secret`: the 32-byte secret extracted from the reference JPEG
+///   via [`crate::imgsecret::extract`].
+///
+/// # Output
+///
+/// A [`RecoveryQrPayload`] whose 109 bytes encode `MAGIC || VERSION || kdf_salt
+/// || wrap_nonce || ciphertext`. Both `kdf_salt` and `wrap_nonce` are freshly
+/// drawn from `OsRng` on every call, so two payloads generated from the same
+/// `(passphrase, image_secret)` pair are distinct bit-for-bit. The printed QR
+/// therefore does not reveal that the user has printed others before.
+///
+/// To render the payload as a printable SVG, see [`recovery_qr_to_svg`].
+///
+/// # Errors
+///
+/// Returns [`RelicarioError::RecoveryQr`] if the AEAD wrap fails (extremely
+/// unlikely in practice — this can only happen if the cipher implementation
+/// itself errors, not on user input).
 pub fn generate_recovery_qr(
     passphrase: &str,
     image_secret: &[u8; 32],
 ) -> Result<RecoveryQrPayload> {
-    generate_recovery_qr_with_params(passphrase, image_secret, &production_params())
+    generate_recovery_qr_with_params(passphrase, image_secret, &RECOVERY_PRODUCTION_PARAMS)
 }
 
 #[doc(hidden)]
@@ -78,11 +196,39 @@ pub fn generate_recovery_qr_with_params(
     Ok(RecoveryQrPayload { bytes })
 }
 
+/// Decode a recovery payload back into the original 32-byte image_secret.
+///
+/// # Inputs
+///
+/// - `payload_bytes`: the 109 bytes produced by [`generate_recovery_qr`] (after
+///   the QR has been scanned, or the hex transcribed and decoded).
+/// - `passphrase`: the recovery passphrase that was used at generate time.
+///
+/// # Output
+///
+/// The recovered image_secret as `Zeroizing<[u8; 32]>` — the wrapper ensures
+/// the secret is wiped from memory when the binding goes out of scope, so a
+/// caller that immediately feeds it into [`crate::crypto::derive_master_key`]
+/// and then drops it never leaves a copy in process memory longer than
+/// strictly necessary.
+///
+/// # Errors
+///
+/// - [`RelicarioError::RecoveryQr`] for **format** problems: wrong length,
+///   bad magic, unsupported version byte. These come from inspecting the
+///   bytes themselves, before any cryptographic work, so they leak nothing
+///   about whether the passphrase is right.
+/// - [`RelicarioError::Decrypt`] for **AEAD** failure — wrong passphrase
+///   (wrong wrap key) **or** a payload tampered after the fact. The two
+///   cases are deliberately not distinguished, mirroring the same
+///   non-distinguishing rejection as [`crate::crypto::decrypt`] (audit M4):
+///   a Poly1305 tag failure cannot, in principle, leak which bytes were
+///   wrong, and the API surface preserves that property.
 pub fn unwrap_recovery_qr(
     payload_bytes: &[u8],
     passphrase: &str,
 ) -> Result<Zeroizing<[u8; 32]>> {
-    unwrap_recovery_qr_with_params(payload_bytes, passphrase, &production_params())
+    unwrap_recovery_qr_with_params(payload_bytes, passphrase, &RECOVERY_PRODUCTION_PARAMS)
 }
 
 #[doc(hidden)]
@@ -104,9 +250,9 @@ pub fn unwrap_recovery_qr_with_params(
             format!("unsupported version 0x{:02x}", payload_bytes[4])
         ));
     }
-    let kdf_salt: &[u8; 32] = payload_bytes[5..37].try_into().expect("slice length validated above");
-    let wrap_nonce = &payload_bytes[37..61];
-    let ciphertext = &payload_bytes[61..109];
+    let kdf_salt: &[u8; 32] = payload_bytes[KDF_SALT_RANGE].try_into().expect("slice length validated above");
+    let wrap_nonce = &payload_bytes[WRAP_NONCE_RANGE];
+    let ciphertext = &payload_bytes[CIPHERTEXT_RANGE];
 
     let wrap_key = derive_wrap_key(passphrase, kdf_salt, params)?;
     let cipher = XChaCha20Poly1305::new(Key::from_slice(wrap_key.as_ref()));
@@ -119,6 +265,15 @@ pub fn unwrap_recovery_qr_with_params(
     Ok(out)
 }
 
+/// Render a [`RecoveryQrPayload`] as a printable QR-code SVG string.
+///
+/// The QR is encoded at **version 40** (the largest standard symbol, 177×177
+/// modules) at **error-correction level M** (~15% recoverable), with a
+/// minimum rendered dimension of **140×140** SVG units. The 109-byte payload
+/// fits comfortably inside v40 at level M — there is significant
+/// error-correction headroom left over, which is the point: the QR is
+/// expected to live on paper (where smudges, folds, and fading are normal)
+/// and must still scan years later.
 pub fn recovery_qr_to_svg(payload: &RecoveryQrPayload) -> String {
     use qrcode::{QrCode, EcLevel};
     let code = QrCode::with_error_correction_level(payload.bytes.as_ref(), EcLevel::M)

crates/relicario-core/src/time.rs

@@ -2,6 +2,8 @@
 
 use serde::{Deserialize, Serialize};
 
+use crate::error::{RelicarioError, Result};
+
 /// Current Unix timestamp in seconds.
 pub fn now_unix() -> i64 {
     chrono::Utc::now().timestamp()
@@ -15,7 +17,7 @@ pub struct MonthYear {
 }
 
 impl MonthYear {
-    pub fn new(month: u8, year: u16) -> Result<Self, &'static str> {
+    pub fn new(month: u8, year: u16) -> std::result::Result<Self, &'static str> {
         if !(1..=12).contains(&month) {
             return Err("month must be 1..=12");
         }
@@ -24,6 +26,28 @@ impl MonthYear {
         }
         Ok(Self { month, year })
     }
+
+    /// Parse a card-expiry string. Accepts `MM/YYYY`, `MM-YYYY`, and `MM/YY`
+    /// (two-digit year is taken as 20YY).
+    pub fn parse(s: &str) -> Result<Self> {
+        let invalid = |detail: String| RelicarioError::InvalidMonthYear(detail);
+        let (m_str, y_str) = s
+            .split_once(['/', '-'])
+            .ok_or_else(|| invalid(format!("expected MM/YYYY, got {s:?}")))?;
+        let month: u8 = m_str
+            .parse()
+            .map_err(|_| invalid(format!("bad month {m_str:?}")))?;
+        let year: u16 = if y_str.len() == 2 {
+            2000 + y_str
+                .parse::<u16>()
+                .map_err(|_| invalid(format!("bad 2-digit year {y_str:?}")))?
+        } else {
+            y_str
+                .parse()
+                .map_err(|_| invalid(format!("bad year {y_str:?}")))?
+        };
+        Self::new(month, year).map_err(|e| invalid(e.into()))
+    }
 }
 
 #[cfg(test)]
@@ -60,4 +84,30 @@ mod tests {
         let parsed: MonthYear = serde_json::from_str(&json).unwrap();
         assert_eq!(parsed, my);
     }
+
+    #[test]
+    fn parse_accepts_mm_slash_yyyy_and_mm_dash_yyyy() {
+        assert_eq!(MonthYear::parse("01/2026").unwrap(), MonthYear::new(1, 2026).unwrap());
+        assert_eq!(MonthYear::parse("12/2099").unwrap(), MonthYear::new(12, 2099).unwrap());
+        assert_eq!(MonthYear::parse("07-2030").unwrap(), MonthYear::new(7, 2030).unwrap());
+    }
+
+    #[test]
+    fn parse_accepts_mm_slash_yy() {
+        assert_eq!(MonthYear::parse("01/26").unwrap(), MonthYear::new(1, 2026).unwrap());
+        assert_eq!(MonthYear::parse("12/99").unwrap(), MonthYear::new(12, 2099).unwrap());
+    }
+
+    #[test]
+    fn parse_rejects_malformed() {
+        assert!(matches!(
+            MonthYear::parse("garbage"),
+            Err(RelicarioError::InvalidMonthYear(_))
+        ));
+        assert!(MonthYear::parse("13/2026").is_err());      // bad month
+        assert!(MonthYear::parse("01/1999").is_err());      // pre-2000
+        assert!(MonthYear::parse("01/2100").is_err());      // post-2099
+        assert!(MonthYear::parse("/2026").is_err());        // empty month
+        assert!(MonthYear::parse("01/").is_err());          // empty year
+    }
 }

crates/relicario-server/Cargo.toml

@@ -2,6 +2,8 @@
 name = "relicario-server"
 version = "0.1.0"
 edition = "2021"
+description = "Pre-receive Git hook for relicario password manager"
+license = "GPL-3.0-or-later"
 
 [dependencies]
 relicario-core = { path = "../relicario-core" }

crates/relicario-wasm/Cargo.toml

@@ -1,8 +1,9 @@
 [package]
 name = "relicario-wasm"
-version = "0.2.0"
+version = "0.7.0"
 edition = "2021"
 description = "WASM bindings for relicario password manager"
+license = "GPL-3.0-or-later"
 
 [lib]
 crate-type = ["cdylib", "rlib"]

crates/relicario-wasm/src/lib.rs

@@ -12,7 +12,13 @@ use zeroize::Zeroizing;
 
 use relicario_core::{derive_master_key, imgsecret, KdfParams};
 
-/// Handle type returned from `unlock`. Backed by a `u32`; opaque to JS.
+/// Handle returned from `unlock`. Backed by a `u32`; opaque to JS.
+///
+/// Dropping the handle (or invoking `.free()` from JS) removes the entry from
+/// the session registry, zeroizing the wrapped master key and image_secret.
+/// `lock(handle)` remains available as the explicit early-cleanup path; the
+/// `Drop` impl is the safety net that catches code paths which forget to call
+/// `lock` before letting the handle go out of scope.
 #[wasm_bindgen]
 pub struct SessionHandle(u32);
 
@@ -22,6 +28,23 @@ impl SessionHandle {
     pub fn value(&self) -> u32 { self.0 }
 }
 
+impl Drop for SessionHandle {
+    fn drop(&mut self) { let _ = session::remove(self.0); }
+}
+
+#[doc(hidden)]
+pub fn __test_make_handle() -> SessionHandle {
+    SessionHandle(session::insert(
+        Zeroizing::new([0x77u8; 32]),
+        Zeroizing::new([0u8; 32]),
+    ))
+}
+
+#[doc(hidden)]
+pub fn __test_session_exists(handle: u32) -> bool {
+    session::with(handle, |_| ()).is_some()
+}
+
 #[wasm_bindgen]
 pub fn unlock(
     passphrase: &str,
@@ -307,6 +330,32 @@ pub fn embed_image_secret(carrier: &[u8], secret: &[u8]) -> Result<Vec<u8>, JsEr
     imgsecret::embed(carrier, s).map_err(|e| JsError::new(&e.to_string()))
 }
 
+// ── Pure parsers (no session needed) ────────────────────────────────────────
+
+use relicario_core::{base32 as core_base32, mime as core_mime, MonthYear};
+
+/// Parse a card-expiry string (`MM/YYYY` / `MM-YYYY` / `MM/YY`).
+/// Returns a plain `{ month, year }` object on success.
+#[wasm_bindgen]
+pub fn parse_month_year(s: &str) -> Result<JsValue, JsError> {
+    let my = MonthYear::parse(s).map_err(|e| JsError::new(&e.to_string()))?;
+    js_value_for(&my)
+}
+
+/// Decode an RFC 4648 base32 string (case-insensitive, optional padding,
+/// whitespace-stripped). Returned as `Uint8Array` on the JS side.
+#[wasm_bindgen]
+pub fn base32_decode_lenient(s: &str) -> Result<Vec<u8>, JsError> {
+    core_base32::decode_rfc4648_lenient(s).map_err(|e| JsError::new(&e.to_string()))
+}
+
+/// Guess a MIME type from a filename's extension. Returns
+/// `application/octet-stream` for unknown or missing extensions.
+#[wasm_bindgen]
+pub fn guess_mime(filename: &str) -> String {
+    core_mime::guess_for_extension(filename).to_string()
+}
+
 use relicario_core::item_types::{TotpConfig, compute_totp_code};
 
 #[wasm_bindgen]
@@ -533,6 +582,19 @@ mod session_tests {
         assert!(!session::remove(h));   // second remove false
     }
 
+    #[test]
+    fn dropping_session_handle_clears_registry_entry() {
+        session::clear();
+        let handle = SessionHandle(session::insert(
+            Zeroizing::new([0x33u8; 32]),
+            Zeroizing::new([0u8; 32]),
+        ));
+        let id = handle.value();
+        assert!(session::with(id, |_| ()).is_some());
+        drop(handle);
+        assert!(session::with(id, |_| ()).is_none());
+    }
+
     #[test]
     fn with_yields_key_only_while_session_lives() {
         session::clear();
@@ -588,4 +650,24 @@ mod session_tests {
         // Should fail with a header validation error.
         assert!(err.is_err());
     }
+
+    #[test]
+    fn base32_decode_lenient_round_trips_known_vector() {
+        let bytes = super::base32_decode_lenient("MZXW6YTBOI").unwrap();
+        assert_eq!(bytes, b"foobar");
+    }
+
+    #[test]
+    fn guess_mime_known_and_unknown_extensions() {
+        assert_eq!(super::guess_mime("doc.pdf"), "application/pdf");
+        assert_eq!(super::guess_mime("photo.JPEG"), "image/jpeg");
+        assert_eq!(super::guess_mime("file.xyz"), "application/octet-stream");
+    }
+
+    // Error paths and JsValue serialization can't be exercised natively —
+    // JsError::new and serde_wasm_bindgen::Serializer call wasm-bindgen
+    // imports that panic off-wasm (same constraint as
+    // `parse_lastpass_csv_json_propagates_header_errors` above). Those
+    // paths are covered in core: `time::tests::parse_rejects_malformed`
+    // and `base32::tests::decode_rfc4648_lenient_rejects_non_alphabet_chars`.
 }

crates/relicario-wasm/src/session.rs

@@ -46,6 +46,9 @@ where
     SESSIONS.with(|s| s.borrow().get(&handle).map(|d| f(&d.image_secret)))
 }
 
+/// Remove a session entry. Called by both `lock(handle)` (the explicit
+/// path) and `impl Drop for SessionHandle` (the safety net). Returns
+/// `true` if an entry was removed, `false` if the handle was already gone.
 pub fn remove(handle: u32) -> bool {
     SESSIONS.with(|s| s.borrow_mut().remove(&handle).is_some())
 }

crates/relicario-wasm/tests/session_drop.rs

@@ -0,0 +1,16 @@
+//! Belt-and-suspenders companion to the native `dropping_session_handle_clears_registry_entry`
+//! test in `lib.rs`. This file exists for `wasm-pack test --node` symmetry; the
+//! native test in the same crate is what gates CI.
+
+use wasm_bindgen_test::wasm_bindgen_test;
+
+use relicario_wasm::{__test_make_handle, __test_session_exists};
+
+#[wasm_bindgen_test]
+fn dropping_session_handle_clears_registry_entry() {
+    let handle = __test_make_handle();
+    let id = handle.value();
+    assert!(__test_session_exists(id));
+    drop(handle);
+    assert!(!__test_session_exists(id));
+}

docs/CRYPTO.md

@@ -1,4 +1,6 @@
-# Relicario — Architecture
+# Relicario — Crypto Pipeline
+
+> **Audience:** anyone evaluating or auditing the crypto. This doc owns Argon2id parameters and rationale, XChaCha20-Poly1305 rationale, vault creation/unlock flow diagrams, DCT-steganography embed and extract flows, and the high-level encrypted-file-format diagram. **Does NOT own:** byte-level schemas or JSON shapes (see [FORMATS.md](FORMATS.md)), attacker scenarios (see [SECURITY.md](SECURITY.md)), or per-module crypto implementation (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)).
 
 ## System Overview
 
@@ -161,11 +163,14 @@ master_key ────────►│  XChaCha20       │──────
                     │  selected block: │
                     │                  │
                     │  QIM embed bits  │
-                    │  in positions    │
-                    │  4-15 (mid-freq) │
+                    │  in zig-zag      │
+                    │  positions 6-17  │
+                    │  (mid-frequency) │
                     │                  │
                     │  Repeat secret   │
-                    │  20+ times       │
+                    │  MIN_COPIES (5)  │
+                    │  to 50 times,    │
+                    │  by capacity     │
                     └────────┬─────────┘
                              │
                              ▼
@@ -181,6 +186,8 @@ master_key ────────►│  XChaCha20       │──────
                      carries 256-bit secret)
 ```
 
+The redundancy count is chosen at embed time based on available DCT capacity: `num_copies = (total_blocks / BLOCKS_PER_COPY).min(50)`, with `BLOCKS_PER_COPY = 22` and a floor of `MIN_COPIES = 5` (`crates/relicario-core/src/imgsecret.rs:78,530-537`). Images that cannot fit at least 5 copies are rejected before embed. Majority voting across these copies at extract time requires ≥ 60 % confidence per bit.
+
 ## Extraction (with crop recovery)
 
 ```
@@ -214,10 +221,12 @@ Input JPEG (possibly re-encoded or cropped)
 ┌─────────┬────────────────────────┬──────────────────┬──────────────────┐
 │ version │         nonce          │    ciphertext     │    auth tag      │
 │ 1 byte  │       24 bytes         │    N bytes        │    16 bytes      │
-│  0x01   │ random per write       │ XChaCha20 stream  │ Poly1305 MAC     │
+│  0x02   │ random per write       │ XChaCha20 stream  │ Poly1305 MAC     │
 └─────────┴────────────────────────┴──────────────────┴──────────────────┘
 ```
 
+`VERSION_BYTE = 0x02` (`crates/relicario-core/src/crypto.rs:59`). Blobs starting with any other byte are rejected with `UnsupportedFormatVersion { found, expected: 0x02 }`. The legacy `0x01` format from the pre-typed-items era is no longer supported.
+
 ## Crate Architecture
 
 ```
@@ -267,3 +276,7 @@ Stolen device:               ████░░░░░░░░░░░░░
 
 Both factors compromised:    game over (same as every password manager)
 ```
+
+---
+
+**Next:** [FORMATS.md](FORMATS.md) — the byte-level wire formats.

docs/FORMATS.md

@@ -0,0 +1,108 @@
+# Relicario Wire Formats
+
+> **Audience:** anyone implementing a compatible client or reading raw vault bytes. This doc owns the `.enc` blob layout, `params.json` / `salt` / `devices.json` / `revoked.json` shapes, the manifest JSON schema, the `.relbak` envelope, item-ID formats, and the settings JSON schema. **Does NOT own:** why these formats look this way (see [CRYPTO.md](CRYPTO.md)), threat model around them (see [SECURITY.md](SECURITY.md)), or Rust struct internals (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)).
+
+> Quick-reference for the load-bearing binary and JSON formats. Check this file before touching serialization, versioning, or storage layout code. Full diagrams and invariants live in the per-crate `ARCHITECTURE.md` files.
+
+## Encrypted blob (`.enc` files)
+
+Every encrypted file — `manifest.enc`, `settings.enc`, `items/<id>.enc`, `attachments/<item-id>/<aid>.enc` — uses the layout produced by `relicario_core::crypto::encrypt` (`crypto.rs`):
+
+```
+┌─────────┬────────────────────────┬──────────────────┬──────────────────┐
+│ version │         nonce          │    ciphertext     │    auth tag      │
+│ 1 byte  │       24 bytes         │    N bytes        │    16 bytes      │
+│  0x02   │ random per write       │ XChaCha20 stream  │ Poly1305 MAC     │
+└─────────┴────────────────────────┴──────────────────┴──────────────────┘
+```
+
+- `VERSION_BYTE = 0x02` (`crypto.rs:59`). Any blob starting with `0x01` is rejected with `UnsupportedFormatVersion { found: 0x01, expected: 0x02 }`.
+- Minimum valid blob length: 41 bytes (1 + 24 + 0 + 16).
+- Nonces are always fresh from `OsRng` — no caller-supplied nonces.
+- Full diagram: `docs/CRYPTO.md` § "Encrypted File Format".
+
+## `.relicario/params.json`
+
+```json
+{
+  "format_version": 2,
+  "aead": "xchacha20-poly1305",
+  "salt_path": ".relicario/salt",
+  "kdf": {
+    "argon2_m": 65536,
+    "argon2_t": 3,
+    "argon2_p": 4
+  }
+}
+```
+
+Parsed via `ParamsFile { kdf: KdfParams }` in `session.rs`. The `kdf` nesting is intentional — `format_version`, `aead`, and `salt_path` co-exist for forward-compat probing. Do not flatten. Production defaults: `m=65536` (64 MiB), `t=3`, `p=4`. Tests use `m=256, t=1, p=1`.
+
+## `.relicario/salt`
+
+32 raw bytes. Not secret. Generated once at vault init via `OsRng`. Feeds Argon2id as the KDF salt.
+
+## Manifest (`manifest.enc`)
+
+Decrypts to JSON matching the `Manifest` struct (`manifest.rs`).
+
+- **Schema version:** `MANIFEST_SCHEMA_VERSION = 2` (`manifest.rs:12`). v1 manifests (pre-typed-items) fail to parse and are not supported.
+- **`ManifestEntry` fields** (declared order in `manifest.rs:21-38`): `id`, `type`, `title`, `tags`, `favorite`, `group`, `icon_hint`, `modified`, `trashed_at`, `attachment_summaries`. The `type` field is `r#type: ItemType` in Rust but serializes as the bare JSON key `"type"` (no serde rename — `r#` is just the raw-identifier escape). `group`, `icon_hint`, and `trashed_at` are `#[serde(skip_serializing_if = "Option::is_none")]`; `tags`, `favorite`, and `attachment_summaries` use `#[serde(default)]`.
+- The manifest is rebuilt from scratch on every `upsert` — it can never drift from the source-of-truth item files.
+- Supports case-insensitive title/tag search without decrypting any item.
+
+## `.relicario/devices.json`
+
+```json
+[
+  { "name": "laptop", "public_key": "<hex-encoded ed25519 public key>" }
+]
+```
+
+An empty array (`[]`) puts the pre-receive hook in bootstrap mode (all pushes accepted). Both `devices.json` and `revoked.json` must be empty for bootstrap mode to activate — a non-empty `revoked.json` alone forces strict verification.
+
+## `.relicario/revoked.json`
+
+```json
+[
+  { "name": "old-laptop", "public_key": "<hex>", "revoked_at": 1746000000 }
+]
+```
+
+Commits by `public_key` at or after `revoked_at` (Unix seconds) are rejected by the pre-receive hook. Commits before `revoked_at` remain valid (they were authorized at the time).
+
+## Item IDs and Field IDs
+
+| Kind | Length | Entropy | Source |
+|---|---|---|---|
+| `ItemId` | 16 hex chars | 64 bits | `OsRng` |
+| `FieldId` | 16 hex chars | 64 bits | `OsRng` |
+| `AttachmentId` | 32 hex chars | 128 bits | first 16 bytes (32 hex chars) of `SHA-256` over the plaintext |
+
+`AttachmentId` is content-addressed — identical plaintexts deduplicate in git automatically. The 128-bit truncation (`ids.rs:59-69`) was widened from 64 bits per audit I2/B4 to put birthday-collision risk out of reach.
+
+## `.relbak` backup format
+
+A zstd-compressed tar archive containing a bare git clone of the vault. Designed for `relicario backup export/restore`.
+
+Full spec: `docs/superpowers/specs/2026-04-27-relicario-import-export-design.md`.
+
+## `ItemCore` JSON (internal)
+
+`ItemCore` uses `#[serde(tag = "type")]` — the outer JSON object gets a `"type"` discriminator key. No `*Core` struct may have a field named `"type"` (use `"kind"` instead — see `CardKind`, `TotpKind`).
+
+Full item type inventory: `crates/relicario-core/ARCHITECTURE.md` § "Module map".
+
+## KDF input construction
+
+The password fed to Argon2id is length-prefixed to prevent extension attacks:
+
+```
+u64_be(len(passphrase)) || passphrase_bytes || u64_be(32) || image_secret
+```
+
+NFC-normalized before hashing. Covered in `crypto.rs:229-236` and tested in `tests/format_v2.rs:44-54`.
+
+---
+
+**Next:** [SECURITY.md](SECURITY.md) — the threat model.

docs/SECURITY.md

@@ -1,5 +1,7 @@
 # Relicario Security Model
 
+> **Audience:** auditors and curious users. This doc owns the threat model, attacker-scenarios table, device-authentication model, env-var trust surface, and known limitations. **Does NOT own:** crypto primitive details (see [CRYPTO.md](CRYPTO.md)), wire formats (see [FORMATS.md](FORMATS.md)), or implementation (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md) and [../crates/relicario-cli/ARCHITECTURE.md](../crates/relicario-cli/ARCHITECTURE.md)).
+
 ## Cryptographic Protection
 
 Relicario uses two-factor vault decryption:
@@ -102,3 +104,7 @@ standard `--release` profile).
 | `RELICARIO_TEST_PASSPHRASE` | Bypass the `rpassword` prompt during integration tests. |
 | `RELICARIO_TEST_ITEM_SECRET` | Bypass the `rpassword` prompt for item-secret fields during integration tests. |
 | `RELICARIO_TEST_BACKUP_PASSPHRASE` | Bypass the `rpassword` prompt for backup export/restore passphrases during integration tests. |
+
+---
+
+**Next:** [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md) — implementation, starting with the platform-agnostic core.

docs/superpowers/RELEASE-WORKFLOW.md

@@ -0,0 +1,161 @@
+# Release Workflow
+
+Unified lifecycle workflow at `.claude/workflows/release.js`.  
+Invoke from any Claude Code session via the `Workflow` tool.
+
+---
+
+## Actions at a glance
+
+| Action | When | Mode |
+|--------|------|------|
+| `develop` | Implement plan tasks | `single` (phone/remote) or `multi` (PC, supervised) |
+| `verify` | Check tests pass | — |
+| `debug` | Fix a failing test or broken feature | — (always sequential) |
+| `release` | Cut and tag a version | — |
+
+---
+
+## Add features / implement a plan
+
+### Single-agent (phone-friendly, fire-and-forget)
+
+One agent works through all plan tasks sequentially. Kick off and check the progress tree later.
+
+```js
+Workflow({
+  name: 'release',
+  args: { action: 'develop', mode: 'single', release: 'v0.5.0' }
+})
+```
+
+**What happens:**
+1. Discovers all plan files matching `v0.5.0`
+2. PM agent reads plans, orders tasks respecting dependencies
+3. One dev agent per task runs sequentially
+4. Full `cargo test` + `cargo build` + `cargo clippy` verify pass
+5. Updates `STATUS.md`
+
+### Multi-agent (PC, supervised by PM)
+
+PM reads the plans, decides N dev streams, writes kickoff prompt files. You open the terminals.
+
+```js
+Workflow({
+  name: 'release',
+  args: { action: 'develop', mode: 'multi', release: 'v0.5.0' }
+})
+```
+
+**What happens:**
+1. Discovers plans
+2. PM agent assigns tasks to N dev streams
+3. Generates PM + N dev prompt files in `docs/superpowers/coordination/`
+4. Prints terminal-open instructions
+
+**Then you:**
+```bash
+cd tools/relay && ./start.sh          # start relay server
+# open N+1 terminal windows
+# PM window:    paste coordination/v0.5.0-pm-prompt.md
+# Dev-A window: paste coordination/v0.5.0-dev-a-prompt.md
+# Dev-B window: paste coordination/v0.5.0-dev-b-prompt.md
+```
+
+The PM supervises devs in real time via the relay. You watch all terminals.
+
+---
+
+## Run tests only
+
+```js
+Workflow({ name: 'release', args: { action: 'verify' } })
+```
+
+Runs `cargo test`, `cargo build --all-targets`, `cargo clippy`. Returns pass/fail summary.
+
+---
+
+## Debug iteration
+
+After you find a broken test or unexpected behavior, hand the failure context to the debug action. It loops up to 5 times: hypothesize → read code → fix → verify → commit.
+
+```js
+Workflow({
+  name: 'release',
+  args: {
+    action: 'debug',
+    context: 'cargo test output:\n...<paste failing test output here>...'
+  }
+})
+```
+
+Returns `{ status: "fixed", iterations: N }` when clean, or `{ status: "max-iterations" }` if it needs your eyes.
+
+---
+
+## Cut a release
+
+Runs verify first; blocked if tests fail.  
+Writes CHANGELOG, updates STATUS + ROADMAP, creates annotated tag.  
+**Stops before pushing** — you confirm manually.
+
+```js
+Workflow({
+  name: 'release',
+  args: { action: 'release', release: 'v0.5.0' }
+})
+```
+
+After it stops, review the tag then:
+```bash
+git push && git push --tags
+```
+
+---
+
+## Full lifecycle example
+
+```
+1. DEVELOP features
+   Workflow({ name:"release", args:{ action:"develop", mode:"single", release:"v0.6.0" } })
+
+2. VERIFY manually (you run the extension in browser, test your flows)
+
+3. DEBUG any failures you find
+   Workflow({ name:"release", args:{ action:"debug", context:"<paste failure>" } })
+   # repeat as needed
+
+4. VERIFY again to confirm clean
+   Workflow({ name:"release", args:{ action:"verify" } })
+
+5. RELEASE
+   Workflow({ name:"release", args:{ action:"release", release:"v0.6.0" } })
+   # review tag, then: git push && git push --tags
+```
+
+---
+
+## Phone vs PC
+
+| Scenario | Recipe |
+|----------|--------|
+| Kick off a release from your phone / remote session | `develop` + `mode:"single"` — fires in background, check `/workflows` |
+| At your PC, want to supervise and intervene | `develop` + `mode:"multi"` — generates prompts, open terminals |
+| Quick sanity check | `verify` |
+| Fixing a bug you found while testing | `debug` with failure context |
+| Cutting and tagging | `release` — always confirms before push |
+
+---
+
+## Plan file discovery
+
+The `develop` action scans `docs/superpowers/plans/` for files whose filename or opening lines reference the release label. To be explicit, pass plan paths directly (not yet wired — add `args.plans` if needed).
+
+---
+
+## Relay server roles
+
+The relay at `localhost:7331` supports roles: `pm`, `dev-a`, `dev-b`, `dev-c`.  
+Start it before opening terminal sessions: `cd tools/relay && ./start.sh`  
+See `docs/superpowers/coordination/RELAY.md` for protocol details.

docs/superpowers/coordination/2026-05-04-arch-followup-dev-a-prompt.md

@@ -0,0 +1,194 @@
+# Dev A Kickoff Prompt — arch-followup Plan A
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior developer** owning Plan A for the arch-followup "architecture-review followups" release train.
+
+Plan A is the **security & docs polish PR** — the small one that ships first, in under a day, with no dependencies on Plans B or C. It closes the only defense-in-depth crypto gap the architecture review flagged (`SessionHandle` has no `impl Drop`, so wasm-bindgen's `.free()` is a cleanup no-op while the master key sits in WASM linear memory), removes the JS-side error swallow that was masking that fact, brings `recovery_qr.rs` documentation up to the density of `crypto.rs` / `imgsecret.rs` / `backup.rs` / `tar_safe.rs`, and finishes the relay-launcher dev-c expansion. Four phases, all S-effort.
+
+A PM in another terminal coordinates you with Dev-B (CLI restructure) and Dev-C (extension restructure). With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. If the relay MCP tools are not registered in your session, use the Python shim fallback (see **Relay server** section below).
+
+## Setup (do this first)
+
+```bash
+cd /home/alee/Sources/relicario
+git fetch
+git checkout main
+git pull
+git worktree add ../relicario-plan-a -b feature/2026-05-04-a-security-polish
+cd ../relicario-plan-a
+pwd  # should print /home/alee/Sources/relicario-plan-a (or similar absolute path)
+```
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario-plan-a`**. Force-cd subagents into this directory — the project's `CLAUDE.md` memory rule explicitly requires that subagent prompts MUST start with `cd /home/alee/Sources/relicario-plan-a` so subagents don't accidentally commit to main. This is non-negotiable.
+
+Today: 2026-05-04. Project rules in `CLAUDE.md` apply.
+
+## 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-a"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-a"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-a")`. After emitting any status/question block: `post_message(from="dev-a", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-a","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-a"}'
+```
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (your scope is **P1.1, P1.7, P1.8 + the partner JS-side fix at `service-worker/session.ts:26` + the `start.sh` launcher follow-up only**)
+3. `docs/superpowers/specs/2026-05-04-security-polish-design.md` — your plan, execute phase by phase
+
+You do NOT need to read Plan B or Plan C in detail. Skim Plan B's "WASM/extension parity seam" paragraph (Phase 8) and Plan C's "Risks → `.free()` callsite policy" paragraph only if a coordination question arises — they're the points where Plans B/C reference your work.
+
+## Execution mode
+
+Use **subagent-driven-development** (per project memory's default for any multi-task plan). Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per phase, two-stage review between phases.
+
+**Every subagent prompt MUST start with**:
+```
+cd /home/alee/Sources/relicario-plan-a
+```
+…before any other instruction. This is non-negotiable per project memory.
+
+## Your scope and boundaries
+
+**In scope:** Phase 1 (Rust `impl Drop for SessionHandle` + wasm-bindgen-test + native fallback test), Phase 2 (JS `.free()` audit + remove the `try { current.free() }` swallow at `extension/src/service-worker/session.ts:26`), Phase 3 (`recovery_qr.rs` documentation pass — module-level `//!`, ASCII layout diagram, doc-comments on the four public items, `production_params` rationale or `const`), Phase 4 (`tools/relay/start.sh` dev-c expansion + verification that `queue.test.ts:54` is already fixed).
+
+**Out of scope:** anything in Plan B (CLI restructure — `cli/main.rs` split, `git_run` helper, parser migration to core, etc.) or Plan C (extension restructure — `setup.ts` SW migration, `vault.ts` split, `StateHost` typing, SW router dedup). The other P2 WASM cleanups (double-lookup, Vec<u8> clone, naming inconsistency, concurrency primitive split). DEV-C's other relay P2s (queue TTL, `call.py`/`call.ts` tracking decision). The 8 "Open architectural decisions". If you trip over an out-of-scope issue or a new bug while doing your work, file it via a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- This is a defense-in-depth crypto fix. Do NOT skip Phase 1's `wasm-bindgen-test` AND the native `#[test]` fallback — both are required by the plan's Done criteria.
+- Do NOT remove the `try { current.free() }` swallow (Phase 2) until Phase 1's `impl Drop` has landed in the same branch — Phase 2 explicitly depends on Phase 1.
+- Phase 3 must produce documentation density that visibly matches `crypto.rs` / `imgsecret.rs` / `backup.rs` / `tar_safe.rs`. If your doc-block is shorter than `crypto.rs`'s top comment, it's not done.
+- Phase 4: confirm `queue.test.ts:54` is already fixed in commit `061facd` (read the file; assert the line is `assert.ok(isRole("dev-c"));`). If it isn't, escalate via `## QUESTION TO PM` — the plan was drafted assuming it was fixed.
+- The plan's Done criteria includes recording the `grep -rn "\.free\b" extension/src/` output in the PR description as the audit deliverable. Do NOT merge the PR without that grep recorded.
+- Do not merge your branch to main. The PM owns merges.
+- Do not push `--force` or run `git reset --hard`. Per `CLAUDE.md`: ask first.
+
+## Coordination protocol
+
+You are one of multiple terminals. The relay routes messages between them.
+
+**At every phase boundary** (complete, blocked, or question): call `read_messages(for="dev-a")` first, then post your update via `post_message(from="dev-a", to="pm", kind="status"|"question", body="...")` and also print it here. Use this format:
+
+```
+## STATUS UPDATE — DEV-A
+Time: <iso8601 like 2026-05-04T14:30:00-07:00>
+Branch: feature/2026-05-04-a-security-polish
+Task: <phase number / short name>
+Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
+Last commit: <short sha + first line of message>
+Tests: <green | red (which failed) | N/A>
+Notes: <anything PM needs to know — keep to 3 sentences max>
+```
+
+**When you need PM input mid-task**: post via `post_message(kind="question")` with format:
+
+```
+## QUESTION TO PM — DEV-A
+Time: <iso8601>
+Context: <what phase, what decision point>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no  (does work stop without an answer?)
+```
+
+**You'll receive**: `## DIRECTIVE TO DEV-A` blocks from the PM via relay (or relayed by user if relay is down). Acknowledge and act.
+
+## Authority within the plan
+
+You don't need PM permission to:
+- Execute phase-to-phase per the plan
+- Make implementation decisions consistent with the plan and synthesis
+- Choose between the plan's optional micro-cleanups in Phase 3 (the named-constant slice ranges, the `recovery_kdf_input` length-prefix comment) — proceed if they make the code clearer
+- Decide whether to add `wasm.lock(handle)` before `.free()` in `clearCurrent()` (Phase 2 leaves this to your judgment; the plan recommends just `free()` post-Phase-1)
+- Write tests, refactor your own code, fix bugs you introduce
+- Push commits to your feature branch
+
+You **do** escalate to PM when:
+- You discover the Rust toolchain is older than 1.79 (Phase 3 falls back to a runtime `#[test]` for the layout assertion — confirm with PM before switching)
+- You discover the `.free()` audit grep returns more than one match (the plan was drafted expecting one; investigate and report)
+- You discover `queue.test.ts:54` is NOT actually fixed (Phase 4 falls back to a real code change)
+- You discover the `start.sh` launcher requires deeper changes than the four locations the plan describes
+- A test you can't make green after honest debugging (don't fudge — debug)
+- A discovered bug not in your plan
+- Anything destructive (per project rules)
+- Before opening the PR for review
+
+## Final steps before REVIEW-READY
+
+Run the project's full validation:
+
+```bash
+# From the worktree root (/home/alee/Sources/relicario-plan-a):
+cargo test -p relicario-core
+cargo test -p relicario-wasm
+cd extension && npm test && cd ..
+
+# Audit deliverable (record output in PR description):
+grep -rn "\.free\b" extension/src/
+
+# Optional but recommended for the wasm-bindgen-test (requires wasm-pack):
+# wasm-pack test --node crates/relicario-wasm
+
+# Manual launcher checks (Phase 4):
+bash tools/relay/start.sh --manual    # confirm "Open 4 new terminals" + Dev-C prompt path
+# bash tools/relay/start.sh --kitty   # if on a kitty terminal: confirm 4 tabs open
+```
+
+Then push and open the PR:
+
+```bash
+git push -u origin feature/2026-05-04-a-security-polish
+gh pr create --base main --head feature/2026-05-04-a-security-polish --title "docs+fix(arch-followup): Drop impl + recovery_qr docs + relay launcher (Plan A)" --body "$(cat <<'EOF'
+## Summary
+
+Architecture-review followup Plan A (security & docs polish). Source: `docs/superpowers/specs/2026-05-04-security-polish-design.md`.
+
+- **P1.1** — `SessionHandle` now has `impl Drop` so wasm-bindgen's `.free()` actually clears the master key from WASM linear memory. Native + wasm-bindgen tests cover construct → drop → registry-empty.
+- **JS partner fix** — removed the `try { current.free() }` swallow at `extension/src/service-worker/session.ts:26`. Crypto-state-transition errors now propagate.
+- **P1.7** — `crates/relicario-core/src/recovery_qr.rs` documentation pass: module-level `//!`, ASCII layout diagram, doc-comments on the four public items, `production_params` parameter-pinning rationale.
+- **P1.8** — confirmed `tools/relay/queue.test.ts:54` already matches the new role union (committed in `061facd`); `tools/relay/start.sh` extended to discover and launch a fourth Dev-C window in `--manual`, `--tmux`, `--kitty` modes.
+
+## Audit deliverables
+
+`.free()` callsites under `extension/src/` (recorded for future regression baseline):
+
+```
+<paste the grep output here>
+```
+
+## Test plan
+
+- [ ] `cargo test -p relicario-core` passes (recovery_qr tests still green; layout static assertion compiles)
+- [ ] `cargo test -p relicario-wasm` passes including new `Drop` test
+- [ ] `cd extension && npm test` passes including new `clearCurrent()` test
+- [ ] `grep -rn "\.free\b" extension/src/` returns exactly one match (the SW callsite)
+- [ ] `bash tools/relay/start.sh --manual` shows "Open 4 new terminals" and lists the Dev-C prompt path
+
+## Done criteria
+
+Per `docs/superpowers/specs/2026-05-04-security-polish-design.md` Done criteria — every checkbox.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL (post via `post_message`).
+
+## First action
+
+After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created at `/home/alee/Sources/relicario-plan-a`, plan absorbed, on `feature/2026-05-04-a-security-polish`). Post it via `post_message(from="dev-a", to="pm", kind="status", body="...")`. Then start Phase 1 of your plan (Rust `impl Drop for SessionHandle` + tests).

docs/superpowers/coordination/2026-05-04-arch-followup-dev-b-prompt.md

@@ -0,0 +1,207 @@
+# Dev B Kickoff Prompt — arch-followup Plan B
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior developer** owning Plan B for the arch-followup "architecture-review followups" release train.
+
+Plan B is the **CLI restructure** — the "single biggest readability lift" per the synthesis. M-L effort, multi-day. It splits `crates/relicario-cli/src/main.rs` (2641 LOC) into a `commands/` folder + `prompt.rs` + `parse.rs`, then layers on the duplicated git-error UX consolidation, manifest-after-mutation cache discipline, `ParamsFile` dedup, batched purge, and the migration of pure parsers (and a third copy of base32) into `relicario-core` with WASM re-exports. Eight phases.
+
+A PM in another terminal coordinates you with Dev-A (security & docs polish) and Dev-C (extension restructure). With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. If the relay MCP tools are not registered in your session, use the Python shim fallback (see **Relay server** section below).
+
+## Setup (do this first)
+
+```bash
+cd /home/alee/Sources/relicario
+git fetch
+git checkout main
+git pull
+git worktree add ../relicario-plan-b -b feature/2026-05-04-b-cli-restructure
+cd ../relicario-plan-b
+pwd  # should print /home/alee/Sources/relicario-plan-b (or similar absolute path)
+```
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario-plan-b`**. Force-cd subagents into this directory — the project's `CLAUDE.md` memory rule explicitly requires that subagent prompts MUST start with `cd /home/alee/Sources/relicario-plan-b` so subagents don't accidentally commit to main. This is non-negotiable.
+
+Today: 2026-05-04. Project rules in `CLAUDE.md` apply.
+
+## 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-b"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-b"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-b")`. After emitting any status/question block: `post_message(from="dev-b", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-b","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-b"}'
+```
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules (Spanish flourish in chat replies only, capitalization, autonomy defaults, CLI/extension parity philosophy)
+2. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (your scope is **P1.2, P1.3, P1.10 + the in-scope CLI P2s only**)
+3. `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — your plan, execute phase by phase
+4. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — DEV-B's full notes (your primary source for line-level context — the synthesis abbreviates)
+5. `docs/superpowers/reviews/2026-05-04-dev-c-notes.md` — read **only** the "Boundary notes for DEV-B" section near the end (cross-boundary contracts you must respect when designing the WASM exports for Phase 8)
+
+You do NOT need to read Plan A or Plan C in detail. If a coordination question arises, skim Plan C's "Risks → WASM boundary coordination" paragraph (it cites your Phase 8 explicitly).
+
+## Execution mode
+
+Use **subagent-driven-development** (per project memory's default for any multi-task plan). Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per phase, two-stage review between phases.
+
+**Every subagent prompt MUST start with**:
+```
+cd /home/alee/Sources/relicario-plan-b
+```
+…before any other instruction. This is non-negotiable per project memory.
+
+**Sequencing matters.** Phase 1 (the mechanical `main.rs` split) is the precondition for every other phase — phases 2-6 touch files that don't exist yet until phase 1 lands. Do NOT start phase 2 until phase 1's `cargo test --workspace` is green and a checkpoint commit is in place.
+
+## Your scope and boundaries
+
+**In scope:**
+- Phase 1 — Mechanical split of `main.rs` into `commands/{add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr,init,generate,rate}.rs` + `prompt.rs` + `parse.rs`
+- Phase 2 — `helpers::git_run` + sweep of the 16 `bail!("git X failed")` sites
+- Phase 3 — `prompt_or_flag<T>` and `build_*_item` compression
+- Phase 4 — `Vault::after_manifest_change` + sweep of the 7 `refresh_groups_cache` sites
+- Phase 5 — Single canonical `ParamsFile` (one definition shared between init writer and unlock reader)
+- Phase 6 — Batched purge in `cmd_purge` and `cmd_trash_empty` (3 git invocations for an N-item purge instead of 3N)
+- Phase 7 — Migrate `parse_month_year` / `base32_decode_lenient` / `guess_mime` to `relicario-core` + `pub(crate) mod base32` (closes DEV-A's three-base32-impls finding)
+- Phase 8 — WASM exports for the migrated parsers + `extension/src/wasm.d.ts` mirror
+
+**Out of scope:** anything in Plan A (security/docs polish — Drop impl, recovery_qr docs, relay launcher) or Plan C (extension restructure — setup.ts SW migration, vault.ts split, StateHost typing, SW router dedup). The CLI P3 nits (let _ = entry pattern, Lock subcommand visibility, Display for ItemType, helpers::relicario_dir adoption sweep, gitea Client per-call construction, edit_and_history.rs scripted prompts, dead test variable, three-test-env-var macro, cmd_recovery_qr_unwrap empty input check, Task 12 cleanup). Server findings (P2/P3 in DEV-B's relicario-server section). WASM findings beyond the parser exports needed for P1.10 (DEV-B's WASM P2 list — double-lookup, Vec<u8> clone, naming, concurrency primitive split). The 8 "Open architectural decisions". The WASM JS-naming snake_case → camelCase decision (deferred to a separate plan). If you trip over an out-of-scope issue or a new bug, file it via a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- Phase 1 is **mechanical** — no logic changes, no signature changes, no error-message reword. Run `cargo check -p relicario-cli` between every file extraction; existing CLI integration tests at `crates/relicario-cli/tests/*` must stay green throughout. They are the regression budget.
+- Phase 2's `git_run` switches from `.status()` (inherited stderr to TTY) to `.output()` (captured); the captured stderr MUST be printed to the user's stderr unmodified on failure. Do not silently swallow.
+- Phase 5's `ParamsFile` migration is on-disk-format-sensitive. Field names and types MUST match the existing `params.json` shape exactly; the round-trip test against a fixture string is required by the plan's Done criteria.
+- Phase 7 — `MonthYear::new` currently returns `Result<_, &'static str>` (DEV-A's P3 nit). The plan recommends re-wrapping the error in `MonthYear::parse` rather than migrating `new` to `RelicarioError`. If you'd rather migrate `new` for consistency, escalate to PM first — this is a cross-plan coordination concern.
+- Phase 8 keeps **snake_case** JS names (consistent with every existing export). Do not introduce camelCase for the three new exports. The snake_case → camelCase decision is deferred to a separate plan.
+- Phase 8 updates `extension/src/wasm.d.ts` and the new `#[wasm_bindgen]` exports in the same commit. Per DEV-C's boundary note, `wasm.d.ts` is hand-maintained — do not let the two surfaces drift even temporarily.
+- The Steam alphabet at `crates/relicario-core/src/item_types/totp.rs:13` is **intentionally non-RFC-4648** and must NOT move into the new `pub(crate) mod base32`. Add a neighbour comment per the plan.
+- Do not merge your branch to main. The PM owns merges.
+- Do not push `--force` or run `git reset --hard`. Per `CLAUDE.md`: ask first.
+
+## Coordination protocol
+
+You are one of multiple terminals. The relay routes messages between them.
+
+**At every phase boundary** (complete, blocked, or question): call `read_messages(for="dev-b")` first, then post your update via `post_message(from="dev-b", to="pm", kind="status"|"question", body="...")` and also print it here. Use this format:
+
+```
+## STATUS UPDATE — DEV-B
+Time: <iso8601 like 2026-05-04T14:30:00-07:00>
+Branch: feature/2026-05-04-b-cli-restructure
+Task: <phase number / short name>
+Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
+Last commit: <short sha + first line of message>
+Tests: <green | red (which failed) | N/A>
+Notes: <anything PM needs to know — keep to 3 sentences max>
+```
+
+**When you need PM input mid-task**: post via `post_message(kind="question")` with format:
+
+```
+## QUESTION TO PM — DEV-B
+Time: <iso8601>
+Context: <what phase, what decision point>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no  (does work stop without an answer?)
+```
+
+**You'll receive**: `## DIRECTIVE TO DEV-B` blocks from the PM via relay (or relayed by user if relay is down). Acknowledge and act.
+
+## Cross-plan coordination
+
+- **Plan C consumes your Phase 8 WASM exports** (`parse_month_year` / `base32_decode_lenient` / `guess_mime`) — but only as a deferred follow-up, NOT in Plan C's current execution. You ship the seam; Plan C does not wire the SW handlers in this train. Sequence Phase 8 to land before Plan C touches `wasm.d.ts` if both must touch it.
+- **`extension/src/wasm.d.ts` shared touchpoint with Plan C.** Plan C says it likely does NOT need to touch this file (its `create_vault`/`attach_vault` handlers reuse already-declared WASM entries). If Plan C does end up touching it, sequence Plan B's edits first and ask Plan C to rebase.
+- **Plan A's `impl Drop for SessionHandle`** is independent of you. Your `git_run` and parser-migration work doesn't touch the WASM crate's session module. No conflict.
+
+## Authority within the plan
+
+You don't need PM permission to:
+- Execute phase-to-phase per the plan
+- Make implementation decisions consistent with the plan and synthesis
+- Add new tests, refactor your own code, fix bugs you introduce
+- Choose between optional approaches the plan calls out (e.g. whether `Vault::after_manifest_change` calls `save_manifest` internally vs renaming the existing method to `save_manifest_raw`)
+- Push commits to your feature branch
+
+You **do** escalate to PM when:
+- You discover the grep at the top of Phase 7 returns non-CLI consumers of `parse_month_year` / `base32_decode_lenient` / `guess_mime` / `base32_encode` / `decode_base32_totp` (the plan was drafted assuming zero non-CLI consumers; investigate)
+- A `cargo test --workspace` failure you can't reproduce locally
+- You want to deviate on the `MonthYear::new` consistency point (see Hard Rules)
+- You discover the `ParamsFile` round-trip is not field-compatible with the current on-disk format (rename, type change, etc.)
+- A test you can't make green after honest debugging (don't fudge — debug)
+- A discovered bug not in your plan
+- Anything destructive (per project rules)
+- Before opening the PR for review
+
+## Final steps before REVIEW-READY
+
+Run the project's full validation:
+
+```bash
+# From the worktree root (/home/alee/Sources/relicario-plan-b):
+cargo test --workspace
+cargo clippy --workspace --all-targets --no-deps
+cargo build -p relicario-wasm --target wasm32-unknown-unknown
+
+# Done-criteria sanity greps (all should return zero matches):
+grep -n 'bail!("git ' crates/relicario-cli/src/
+grep -n 'refresh_groups_cache' crates/relicario-cli/src/ | grep -v 'session\.rs'
+# These should each return one match:
+grep -n 'struct ParamsFile' crates/relicario-cli/src/
+
+# CLI smoke (post-split, end-to-end):
+cargo run -p relicario-cli -- --help
+```
+
+Then push and open the PR:
+
+```bash
+git push -u origin feature/2026-05-04-b-cli-restructure
+gh pr create --base main --head feature/2026-05-04-b-cli-restructure --title "refactor(cli): split main.rs + git_run helper + parsers→core (Plan B)" --body "$(cat <<'EOF'
+## Summary
+
+Architecture-review followup Plan B (CLI restructure — single biggest readability lift). Source: `docs/superpowers/specs/2026-05-04-cli-restructure-design.md`.
+
+- **P1.2** — `cli/main.rs` split from 2641 LOC into `commands/{add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr,init,generate,rate}.rs` + `prompt.rs` + `parse.rs`. `main.rs` retains clap + dispatch only (~470 lines).
+- **P1.3** — `helpers::git_run(repo, args, context)` captures stderr; 16 duplicated bail sites collapsed.
+- **P1.10** — `parse_month_year` / `base32_decode_lenient` / `guess_mime` migrated to `relicario-core` (`MonthYear::parse`, `pub(crate) mod base32::{encode_rfc4648,decode_rfc4648_lenient}`, `mime::guess_for_extension`); also closes DEV-A's three-base32-impls finding by extracting the shared module. WASM exports added; `extension/src/wasm.d.ts` mirrored.
+- **CLI P2 cluster** — `prompt_or_flag<T>` compression of `build_*_item`; `Vault::after_manifest_change` centralizes the `refresh_groups_cache` discipline (7 sites collapsed); single canonical `ParamsFile` shared between init writer and unlock reader; batched purge — a 50-item `trash empty` is now 3 git invocations instead of 150.
+
+## Test plan
+
+- [ ] `cargo test --workspace` passes
+- [ ] `cargo clippy --workspace` silent
+- [ ] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` clean
+- [ ] `grep -n 'bail!("git ' crates/relicario-cli/src/` returns zero matches
+- [ ] `grep -n 'refresh_groups_cache' crates/relicario-cli/src/` returns zero matches outside `session.rs`
+- [ ] `grep -n 'struct ParamsFile' crates/relicario-cli/src/` returns one match
+- [ ] New test asserts a multi-item `trash empty` produces exactly one new git commit
+- [ ] All existing CLI integration tests at `crates/relicario-cli/tests/*` still pass without modification
+
+## Done criteria
+
+Per `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` Done criteria — every checkbox.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL (post via `post_message`).
+
+## First action
+
+After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created at `/home/alee/Sources/relicario-plan-b`, plan absorbed, on `feature/2026-05-04-b-cli-restructure`). Post it via `post_message(from="dev-b", to="pm", kind="status", body="...")`. Then start Phase 1 of your plan (mechanical split of `cli/main.rs`). Remember: phase 1 is mechanical — `cargo check` between every file extraction.

docs/superpowers/coordination/2026-05-04-arch-followup-dev-c-prompt.md

@@ -0,0 +1,218 @@
+# Dev C Kickoff Prompt — arch-followup Plan C
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior developer** owning Plan C for the arch-followup "architecture-review followups" release train.
+
+Plan C is the **extension restructure** — the largest of the three (multi-day to multi-week). It eliminates the two steepest learning cliffs in the extension. After this plan ships, `setup.ts` no longer imports `relicario-wasm` directly (it isn't the pattern; it was the exception); `vault.ts` shrinks from 1027 LOC to ~200 of routing + state; `shared/state.ts` becomes type-checked end-to-end; the duplicated SW router helpers consolidate into one home each; and the extension closes its last CLI-parity gap (`relicario status` → vault-sidebar status indicator). Six phases.
+
+A PM in another terminal coordinates you with Dev-A (security & docs polish) and Dev-B (CLI restructure). With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. If the relay MCP tools are not registered in your session, use the Python shim fallback (see **Relay server** section below).
+
+## Setup (do this first)
+
+```bash
+cd /home/alee/Sources/relicario
+git fetch
+git checkout main
+git pull
+git worktree add ../relicario-plan-c -b feature/2026-05-04-c-extension-restructure
+cd ../relicario-plan-c
+pwd  # should print /home/alee/Sources/relicario-plan-c (or similar absolute path)
+```
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario-plan-c`**. Force-cd subagents into this directory — the project's `CLAUDE.md` memory rule explicitly requires that subagent prompts MUST start with `cd /home/alee/Sources/relicario-plan-c` so subagents don't accidentally commit to main. This is non-negotiable.
+
+Today: 2026-05-04. Project rules in `CLAUDE.md` apply.
+
+## 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-c"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-c"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-c")`. After emitting any status/question block: `post_message(from="dev-c", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-c","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-c"}'
+```
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules (Spanish flourish in chat replies only, capitalization, autonomy defaults, CLI/extension parity philosophy, security defense-in-depth)
+2. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (your scope is **P1.4, P1.5, P1.6, P1.9 + the in-scope extension P2s + the `relicario status` parity gap only**)
+3. `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` — your plan, execute phase by phase
+4. `docs/superpowers/reviews/2026-05-04-dev-c-notes.md` — DEV-C's full notes (your primary source — the synthesis abbreviates)
+5. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — read **only** the "Boundary notes for DEV-C" section near the end (14 numbered contracts the JS side must respect when interacting with WASM; several inform your scope)
+
+You do NOT need to read Plan A or Plan B in detail. Skim Plan A's Phase 2 (the `service-worker/session.ts:26` swallow removal) and Plan B's Phase 8 (WASM parser exports) only if a coordination question arises.
+
+## Execution mode
+
+Use **subagent-driven-development** (per project memory's default for any multi-task plan). Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per phase, two-stage review between phases.
+
+**Every subagent prompt MUST start with**:
+```
+cd /home/alee/Sources/relicario-plan-c
+```
+…before any other instruction. This is non-negotiable per project memory.
+
+**Sequencing matters.** Phase 1 (typed `StateHost`) is the precondition for phases 3 and 4. Phase 2 (SW storage extraction) is independent and can ship in parallel. Phases 3 and 4 both depend on phase 1. Phase 5 (P2 cluster) and phase 6 (`get_vault_status`) are independent of 3 and 4 — they can run in parallel.
+
+## Your scope and boundaries
+
+**In scope:**
+- Phase 1 — Typed `StateHost` interface in `extension/src/shared/state.ts` (no `any` in public surface) + generic `getState`/`setState` over `keyof PopupState` + double-registration guard + `__resetHostForTests` helper. Includes migration of `View` and `PopupState` from `extension/src/popup/popup.ts` to `extension/src/shared/types.ts` (or a new `shared/popup-state.ts`) to avoid a `popup → shared → popup` circular import.
+- Phase 2 — Extract `extension/src/service-worker/storage.ts` (`loadDeviceSettings`, `loadBlacklist`, `saveBlacklist` from both router files) + move `itemToManifestEntry` to `extension/src/service-worker/vault.ts`.
+- Phase 3 — Setup wizard SW migration: add `create_vault` and `attach_vault` SW messages; rewrite `setup.ts` as UI-only that posts those messages; convert the 6-step procedural wizard to a step-registry pattern; add `clearWizardState()` on `beforeunload` + step-0 reset.
+- Phase 4 — Split `vault.ts` into `vault-shell.ts` / `vault-sidebar.ts` / `vault-list.ts` / `vault-drawer.ts` / `vault-form-wrapper.ts`. Lift `vault_locked` RPC intercept into `shared/state.ts`. Reset `state.drawerOpen` on non-list `renderPane`. Debounce sidebar search (50-100ms).
+- Phase 5 — P2 cluster: inactivity-timer reset on content-callable messages (with documented exclusion set); `state.gitHost` clear on session expiry; teardown helper extraction (`teardownSettingsCommon`); `Promise.allSettled` in devices/trash; MutationObserver debounce in `content/detector.ts`.
+- Phase 6 — `get_vault_status` SW message + vault-sidebar status indicator (closes the `relicario status` parity gap).
+
+**Out of scope:** anything in Plan A (security/docs polish — `impl Drop`, `service-worker/session.ts:26` swallow removal, `.free()` audit, `recovery_qr.rs` docs, server hardening, env-var audit) or Plan B (CLI restructure — `cli/main.rs` split, `git_run`, parser migration to core; you only **consume** the WASM exports as a deferred follow-up). Extension P3s (form-header `isInTab()` redundancy, popup.ts `isInTab()` heuristic, item-form.ts `renderComingSoon` dead code, `types/login.ts` size, `vault.ts:18-26` backup-panel comment, capture/detector/fill username-finder dedup, capture submit-button hook scope, setup.ts passphrase-score `-1` sentinel, `setup.ts:1056-1062` chrome.storage bypass, `setup.ts:1-7` "5-step" header, glyphs.ts partial adoption, `types.ts` TotpKind flat-union, `totp-tools.ts:39-46` swallowed rejections, generator-panel cleanup guard, `item-list.ts` popover listeners, popup `popup.ts:178-181` unconditional teardowns). Other parity items (per-attachment `delete_attachment` SW message, `list --tag` filter doc note). Cross-cutting items not explicitly listed (chrome.storage.local direct reads outside the setup migration, bun test runner doc note, manifest version sync). The 8 "Open architectural decisions". WASM JS-naming snake_case → camelCase (deferred to a separate plan). Anything touching the in-flight uncommitted v0.5.x work. If you trip over an out-of-scope issue or a new bug, file it via a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- **Phase 1 first.** Do NOT start phases 3 or 4 until phase 1 is green and committed. The typed `StateHost` is the contract phases 3 and 4 build against.
+- **`View` / `PopupState` migration is part of phase 1**, not phase 4. Doing it later creates circular imports that surface mid-refactor and waste a day.
+- **Do NOT redo Plan A's `.free()` swallow removal** at `extension/src/service-worker/session.ts:26`. That's Dev-A's. But wherever your refactor *moves* a `.free()` callsite — most notably during phase 3 when `setup.ts`'s `verifiedHandle` retires and the new `create_vault`/`attach_vault` SW handlers acquire their own handles — the new location MUST call `wasm.lock(handle)` first regardless of whether Plan A's Rust-side `impl Drop` has landed yet. Cite Plan A as the source of the policy in your phase 3 commit message.
+- **`extension/src/wasm.d.ts` coordination with Plan B.** Plan B Phase 8 will touch this file for new parser exports. Verify by reading `extension/src/service-worker/vault.ts` whether your `create_vault`/`attach_vault` SW handlers need new WASM entry points — they likely don't (the SW already orchestrates `unlock`/`embed_image_secret`/`register_device`/`manifest_encrypt`). If you DO need new entries, escalate via `## QUESTION TO PM` so the touch order with Plan B can be sequenced.
+- **`create_vault` and `attach_vault` SW handlers must be transactional** — they hold their own internal session reference for the duration of the operation and do NOT consult or reset the user-facing inactivity timer until they return successfully. Document this contract in the handler header comments.
+- **Phase 4 `vault_locked` channel unification** keeps both signals (the SW's `session_expired` event AND the new `shared/state.ts` wrapper's intercept) firing during the migration window. Collapse only after both surfaces are verified consuming from `shared/state.ts`. Add a regression test asserting popup lock screen renders on `session_expired` and vault tab lock screen renders on the SW response intercept.
+- **Round out the WASM stub at `extension/src/__stubs__/relicario_wasm.stub.ts`** as part of phase 3. DEV-C noted only 7 of ~25 exports are stubbed; phase 3's vitest tests for `create_vault`/`attach_vault` need stubs for `embed_image_secret`, `register_device`, `manifest_encrypt`. Add them rather than file a separate ticket.
+- The `recovery_qr_generated_at` direct chrome.storage.local write at `setup.ts:1056-1062` is **out of scope** — leave it as-is; defer to a P3 cleanup.
+- Do not merge your branch to main. The PM owns merges.
+- Do not push `--force` or run `git reset --hard`. Per `CLAUDE.md`: ask first.
+
+## Coordination protocol
+
+You are one of multiple terminals. The relay routes messages between them.
+
+**At every phase boundary** (complete, blocked, or question): call `read_messages(for="dev-c")` first, then post your update via `post_message(from="dev-c", to="pm", kind="status"|"question", body="...")` and also print it here. Use this format:
+
+```
+## STATUS UPDATE — DEV-C
+Time: <iso8601 like 2026-05-04T14:30:00-07:00>
+Branch: feature/2026-05-04-c-extension-restructure
+Task: <phase number / short name>
+Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
+Last commit: <short sha + first line of message>
+Tests: <green | red (which failed) | N/A>
+Notes: <anything PM needs to know — keep to 3 sentences max>
+```
+
+**When you need PM input mid-task**: post via `post_message(kind="question")` with format:
+
+```
+## QUESTION TO PM — DEV-C
+Time: <iso8601>
+Context: <what phase, what decision point>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no  (does work stop without an answer?)
+```
+
+**You'll receive**: `## DIRECTIVE TO DEV-C` blocks from the PM via relay (or relayed by user if relay is down). Acknowledge and act.
+
+## Cross-plan coordination
+
+- **Plan A owns the `.free()` swallow removal** (`service-worker/session.ts:26`) and the Rust `impl Drop for SessionHandle`. Do not redo that work. Do honor the policy where you move callsites (see Hard Rules).
+- **Plan B Phase 8 ships WASM parser exports** (`parse_month_year` / `base32_decode_lenient` / `guess_mime`) that the extension can eventually consume. Consumption (SW message handlers wrapping the new exports) is **explicitly deferred to a future plan** — do NOT design those handlers in this train. The seam exists; nobody is wiring it yet.
+- **`extension/src/wasm.d.ts` shared touchpoint with Plan B.** See Hard Rules — you likely don't need to touch it. If you do, escalate to PM for sequencing.
+
+## Authority within the plan
+
+You don't need PM permission to:
+- Execute phase-to-phase per the plan
+- Make implementation decisions consistent with the plan and synthesis
+- Choose how the typed `StateHost` exposes `setState` (the plan suggests `setState<K extends keyof PopupState>`; pick the variant that gives the cleanest call-site ergonomics)
+- Pick which file `View` and `PopupState` migrate to (`shared/types.ts` vs new `shared/popup-state.ts`) — the plan accepts either
+- Add new tests, refactor your own code, fix bugs you introduce
+- Push commits to your feature branch
+
+You **do** escalate to PM when:
+- You discover phase 3's setup-to-SW migration needs new WASM entry points (would touch `wasm.d.ts` and conflict with Plan B Phase 8)
+- You discover the `view`/`PopupState` migration in phase 1 surfaces more TS errors than the plan estimated (~15-30); if you hit 100+ errors, the surface area is bigger than the plan accounts for
+- You discover a real bug in the existing `vault_locked` channels (e.g. popup currently doesn't actually receive `session_expired` despite the plan's premise)
+- A vitest test you can't make green after honest debugging (don't fudge — debug)
+- A discovered bug not in your plan
+- Anything destructive (per project rules)
+- Before opening the PR for review
+
+## Final steps before REVIEW-READY
+
+Run the project's full validation:
+
+```bash
+# From the worktree root (/home/alee/Sources/relicario-plan-c):
+cd extension
+npm test                      # vitest
+npm run build                 # Chrome build
+npm run build:firefox         # Firefox build
+cd ..
+
+# Done-criteria sanity greps:
+grep -n ': any' extension/src/shared/state.ts        # should return zero
+grep -rn 'relicario-wasm' extension/src/setup/       # should return zero (post-Phase-3)
+wc -l extension/src/setup/setup.ts                   # should be ≤ ~500
+wc -l extension/src/vault/vault.ts                   # should be ~200
+grep -n 'loadDeviceSettings\|loadBlacklist\|saveBlacklist' \
+   extension/src/service-worker/router/popup-only.ts \
+   extension/src/service-worker/router/content-callable.ts  # should be imports only, no defs
+grep -n 'itemToManifestEntry' extension/src/service-worker/router/  # should be imports only
+```
+
+Then push and open the PR:
+
+```bash
+git push -u origin feature/2026-05-04-c-extension-restructure
+gh pr create --base main --head feature/2026-05-04-c-extension-restructure --title "refactor(ext): typed StateHost + setup→SW + vault.ts split (Plan C)" --body "$(cat <<'EOF'
+## Summary
+
+Architecture-review followup Plan C (extension restructure — eliminates the two steepest learning cliffs). Source: `docs/superpowers/specs/2026-05-04-extension-restructure-design.md`.
+
+- **P1.6** — `extension/src/shared/state.ts` now has a concrete `StateHost` interface (no `any` in public surface), `getState`/`setState` generic over `keyof PopupState`, double-registration guard, `__resetHostForTests` helper. `View` and `PopupState` migrated from `popup/popup.ts` to `shared/types.ts` to break circular import.
+- **P1.9** — `service-worker/storage.ts` extracted; `itemToManifestEntry` moved to `service-worker/vault.ts`. Both router files import; no more duplicated definitions.
+- **P1.4** — `setup.ts` no longer imports `relicario-wasm`. New `create_vault` / `attach_vault` SW messages handle vault creation transactionally. Procedural wizard converted to a step-registry pattern (`{ id, render, attach }[]`). `clearWizardState()` on `beforeunload` + step-0 reset wipes sensitive `Uint8Array` material best-effort. `setup.ts` LOC dropped from 1220 to ~500.
+- **P1.5** — `vault.ts` split into `vault-shell.ts` / `vault-sidebar.ts` / `vault-list.ts` / `vault-drawer.ts` / `vault-form-wrapper.ts`. `vault.ts` retained at ~200 LOC (routing + state only). `vault_locked` RPC intercept lifted into `shared/state.ts` so popup and vault tab consume one channel. Drawer auto-closes on non-list views. Sidebar search debounced.
+- **P2 cluster** — inactivity timer resets on all messages except a documented exclusion set; `state.gitHost` clears on session expiry; `teardownSettingsCommon` extracted; `devices.ts`/`trash.ts` use `Promise.allSettled`; `content/detector.ts` MutationObserver debounced.
+- **`get_vault_status`** — closes the `relicario status` parity gap. New SW message returns cached `{ ahead, behind, lastSyncAt, pendingItems }`; vault sidebar renders an indicator on mount + manual refresh.
+
+## Cross-plan coordination respected
+
+- **Plan A** owns the `service-worker/session.ts:26` swallow removal and the Rust `impl Drop`. This PR does NOT redo that work. Wherever this refactor moved a `.free()` callsite (Phase 3 setup-to-SW migration), the new location calls `wasm.lock(handle)` first regardless of Plan A's status.
+- **Plan B Phase 8** WASM parser exports are a seam this PR does NOT consume in this train. Future plan wires the SW handlers.
+- **`extension/src/wasm.d.ts`** not touched by this PR (verified at Phase 3).
+
+## Test plan
+
+- [ ] `cd extension && npm test` passes (vitest including new tests for typed state, SW storage helpers, `clearWizardState`, drawer auto-close, `vault_locked` channel, `get_vault_status`)
+- [ ] `cd extension && npm run build && npm run build:firefox` clean
+- [ ] `grep -n ': any' extension/src/shared/state.ts` returns zero
+- [ ] `grep -rn 'relicario-wasm' extension/src/setup/` returns zero
+- [ ] `wc -l extension/src/setup/setup.ts` ≤ ~500
+- [ ] `wc -l extension/src/vault/vault.ts` ~200
+- [ ] Manual smoke: load extension → setup → unlock → vault tab → drawer behavior → settings → trash
+- [ ] Manual smoke: trigger session expiry, confirm both popup and vault tab show lock screen
+- [ ] Manual smoke: vault sidebar status indicator updates on sync
+
+## Done criteria
+
+Per `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` Done criteria — every checkbox.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL (post via `post_message`).
+
+## First action
+
+After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created at `/home/alee/Sources/relicario-plan-c`, plan absorbed, on `feature/2026-05-04-c-extension-restructure`). Post it via `post_message(from="dev-c", to="pm", kind="status", body="...")`. Then start Phase 1 of your plan (typed `StateHost` + `View`/`PopupState` migration). Remember: phase 1 is the precondition for phases 3 and 4 — do not start them until phase 1 is green.

docs/superpowers/coordination/2026-05-04-arch-followup-pm-prompt.md

@@ -0,0 +1,162 @@
+# PM Kickoff Prompt — arch-followup architecture-review followups
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are the **project manager** for the arch-followup "architecture-review followups" release train. 3 senior developers report to you, each working in their own terminal on a parallel feature branch. The user runs all 4 terminals; a relay MCP server routes messages between you so the user does not need to copy-paste.
+
+## Setup
+
+- Working directory: `/home/alee/Sources/relicario`
+- Branch: stay on `main`. Do not check out feature branches.
+- Today: 2026-05-04. Project rules in `CLAUDE.md` apply.
+
+## 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, dev-c`. Use these instead of asking the user to copy-paste. After sending any directive, call `post_message(from="pm", to="dev-X", kind="directive", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session (this happens when the relay server was not running when your session opened), use the Python shim instead:
+
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"pm","to":"dev-a","kind":"directive","body":"..."}'
+python3 call.py read_messages '{"for":"pm"}'
+```
+
+The shim connects over HTTP and has the same semantics as the MCP tools.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules (Spanish flourish in chat replies only, capitalization, autonomy defaults, never run git-destructive commands without asking)
+2. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — the canonical synthesis that drove all three plans (10 P1s + P2/P3 tail + 8 open architectural decisions)
+3. `docs/superpowers/specs/2026-05-04-security-polish-design.md` — Plan A: security & docs polish (S, independent, ships first)
+4. `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — Plan B: CLI restructure (M-L, multi-day)
+5. `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` — Plan C: extension restructure (L, multi-day to multi-week, largest)
+6. `docs/superpowers/coordination/RELAY.md` — multi-agent paradigm + relay reference (you are inside this paradigm right now)
+
+Skim the per-reviewer notes only if a dev's question forces it: `docs/superpowers/reviews/2026-05-04-dev-a-notes.md` (Rust core), `dev-b-notes.md` (Rust consumers), `dev-c-notes.md` (TypeScript).
+
+## Your authority
+
+- Approve or deny scope changes from devs
+- Review and merge PRs from each dev's feature branch
+- Drive any release-prep work that isn't a feature plan (e.g. CHANGELOG entries per merged PR, version bumps if any) — this is your hands-on work
+- Coordinate sequencing of the cross-plan touch points (see "Cross-plan coordination" below)
+- Tag a milestone (e.g. `arch-followup-complete` or whatever the user prefers) 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 (`git push --force`, `git reset --hard`, `git branch -D`, `rm -rf`).
+
+## Cross-plan coordination (you must enforce)
+
+The three plans were drafted with explicit cross-boundary cites. Hold devs to them:
+
+- **Plan A is fully independent of B and C.** It can ship anytime. There is no merge-order dependency.
+- **Plan B Phase 8 (WASM parser exports + `wasm.d.ts` mirror) is a seam Plan C will eventually consume**, but the consumption (SW message handlers wrapping the new exports) is **explicitly deferred to a future plan**. B does NOT block C, and C does NOT block B during execution. The seam exists; nobody is wiring it yet.
+- **Both B and C touch `extension/src/wasm.d.ts` at most once each.** If both must touch it in the same window, sequence Plan B's edits first and rebase Plan C on top. Plan C's design says it likely does NOT need to touch `wasm.d.ts` (its `create_vault`/`attach_vault` SW handlers reuse already-declared WASM entries) — verify when C reaches Phase 3.
+- **Plan A owns the removal of the `try { current.free() }` swallow** at `extension/src/service-worker/session.ts:26` and the Rust-side `impl Drop for SessionHandle`. Plan C must NOT redo that work, but wherever Plan C *moves* a `.free()` callsite (most notably during the Phase 3 setup-to-SW migration where `setup.ts`'s `verifiedHandle` retires and the new `create_vault`/`attach_vault` handlers acquire their own handles), the new location must call `wasm.lock(handle)` first regardless of Plan A's status.
+
+## Judgment calls in the plans worth flagging
+
+The subagents who drafted the plans flagged these decisions for your awareness:
+
+- **Plan A Phase 4 — `tools/relay/queue.test.ts:54` is already fixed** in commit `061facd` (planning subagent verified). The phase records this as a verification step rather than a code change. Plan A's real Phase 4 work is `tools/relay/start.sh` — both `launch_tmux` and `launch_kitty` still launch only PM/Dev-A/Dev-B (no Dev-C window); the manual-mode banner still says "Open 3 new terminals"; no `*-dev-c-prompt.md` is discovered. That part IS still needed.
+- **Plan A `.free()` audit yielded exactly one callsite** under `extension/src/` (the SW one at `session.ts:26`). The plan records the grep command for reproducibility; if a future surface adds a second callsite, this PR's grep becomes the baseline.
+- **Plan B Phase 7 — `MonthYear::new` currently returns `Result<_, &'static str>`** (DEV-A's P3 nit). Plan B recommends re-wrapping the error in `MonthYear::parse` rather than migrating `new` to `RelicarioError` — keeps Plan B focused. If you'd rather have Plan B address the consistency now, raise it with the user before Dev-B starts Phase 7.
+- **Plan B Phase 8 keeps snake_case naming** for the new WASM exports (consistent with every existing export). The snake_case → camelCase decision (DEV-B/DEV-C P3) is **explicitly deferred to a separate plan**; introducing camelCase only for the three new exports would create a worst-of-both-worlds inconsistency.
+- **Plan C Phase 1 — `View` and `PopupState` currently live in `extension/src/popup/popup.ts`** (lines 70-92). The phase 1 typed `StateHost` interface needs to import them, but doing so directly creates a `popup → shared → popup` circular import. The plan calls for migrating those types to `extension/src/shared/types.ts` (or a new `shared/popup-state.ts`) as part of phase 1 before re-importing. Make sure Dev-C has done this migration before consuming TS errors elsewhere.
+- **Plan C noted only 7 of ~25 WASM exports** are currently stubbed in `extension/src/__stubs__/relicario_wasm.stub.ts`. Plan C Phase 3's vitest tests for `create_vault`/`attach_vault` will need additional stubs (`embed_image_secret`, `register_device`, `manifest_encrypt`) — Dev-C should round those out as part of the phase rather than file a separate ticket.
+
+If any of these conflict with your judgment, raise it with the user before kickoff.
+
+## The 8 "Open architectural decisions"
+
+The synthesis appendix lists 8 decisions that are user-judgement calls, not implementation tasks:
+
+1. Was `impl Drop for SessionHandle` deliberately omitted? — **Plan A confirms it was not**, and ships the fix.
+2. Should CLI parsers migrate to core? — **Plan B Phase 7 says yes** and ships the migration.
+3. Bootstrap rule for missing `devices.json` — **out of scope**, defer.
+4. `Lock` no-op CLI subcommand visibility — **out of scope**, defer.
+5. Task 12 cleanup status (`cmd_backup_export` still reads `devices.json`) — **out of scope**, defer.
+6. `tools/relay/call.py` and `call.ts` tracking — **already tracked** (per `RELAY.md`).
+7. WASM JS naming snake_case → camelCase — **explicitly deferred** to a separate plan (Plan B Phase 8 does NOT take a position).
+8. `.gitea_env_vars` gitignore — **already done** in commit `4a726c2`.
+
+You do not need to act on any of these unless the user reopens one. They're listed so you have the context if a dev surfaces a related question.
+
+## Coordination protocol
+
+You are one of 4 terminals. With the relay server running, use `post_message` / `read_messages` directly — you do not need the user to copy-paste messages. Call `read_messages(for="pm")` before every action. If the relay MCP tools are not registered in your session, fall back to the Python shim (see **Relay server** section above) or ask the user to relay manually.
+
+**You receive:** `## STATUS UPDATE — DEV-<letter>` or `## QUESTION TO PM — DEV-<letter>` blocks, either from the relay inbox or relayed by the user if the relay is down.
+
+**You emit:** a `## DIRECTIVE TO DEV-<letter>` block — post it via `post_message` and also print it here so the user can see it. Format:
+
+```
+## DIRECTIVE TO DEV-<letter>
+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, give a current rollup:
+
+```
+## RELEASE STATUS — arch-followup
+Devs: <per-dev one-line state>
+PM: <what you're working on>
+Blockers: <list, or "none">
+Next milestone: <e.g., "Dev A REVIEW-READY", "Plan A 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 the diff against the spec (synthesis) and the plan's Done criteria checklist
+4. If green: post `Action: MERGE-APPROVED` and run `gh pr merge --merge` (preserve git history; no squash — the project preserves git as audit log per `CLAUDE.md`)
+5. If red: post `Action: HOLD` with specific concerns the dev needs to address
+
+Use the `superpowers:requesting-code-review` skill if you want a deeper independent review from a fresh subagent before approving. For Plan A in particular (defense-in-depth crypto fix), an independent review is worth the cost.
+
+## Per-plan acceptance gating
+
+- **Plan A:** every Done-criteria checkbox in `2026-05-04-security-polish-design.md` checked off; the `.free()` audit grep recorded in PR description; both the wasm-bindgen-test and the native `#[test]` for `Drop` present and passing; `recovery_qr.rs` documentation density visibly matches `crypto.rs` / `imgsecret.rs`.
+- **Plan B:** every Done-criteria checkbox in `2026-05-04-cli-restructure-design.md` checked off; `cargo test --workspace` green; `cargo clippy --workspace` silent; `cargo build -p relicario-wasm --target wasm32-unknown-unknown` clean; the 16 `bail!("git X failed")` sites all collapsed; the 7 `refresh_groups_cache` callsites all using `after_manifest_change`; one canonical `ParamsFile`; batched purge measured (3 git invocations for ≥3 items).
+- **Plan C:** every Done-criteria checkbox in `2026-05-04-extension-restructure-design.md` checked off; vitest green; `bun run build` + `bun run build:firefox` clean; no `any` in `StateHost`; SW router files import the new helpers; `setup.ts` ≤ ~500 LOC and does not import `relicario-wasm`; `vault.ts` ~200 LOC of routing+state only; single `vault_locked` channel.
+
+## Pre-tag checklist
+
+Before tagging or otherwise marking the followup train complete:
+
+- [ ] All three plan branches merged to main
+- [ ] Full test suite green on main: `cargo test --workspace && cd extension && npm test && cd ../tools/relay && bun test`
+- [ ] Standard build green on main: `cargo build && cd extension && npm run build && npm run build:firefox`
+- [ ] User-driven smoke test of the merged result (load extension, exercise unlock + setup + a vault op; run the CLI through `relicario init`/`add`/`list`/`sync`)
+- [ ] Synthesis P2/P3 tail re-evaluated — anything still worth a follow-up plan? If so, draft a one-line tracker.
+- [ ] Explicit user approval to mark the train complete
+
+## First action
+
+1. Call `read_messages(for="pm")` to drain any early inbox messages.
+2. Emit a `## RELEASE STATUS` block confirming you've absorbed the synthesis, all three plans, and the cross-plan coordination notes. Note the judgment calls above for the user's awareness.
+3. Send opening directives to all three devs via `post_message`:
+   - **Dev-A:** start Plan A Phase 1 (Rust `impl Drop` + test). It's S-effort and independent — no waiting on anyone.
+   - **Dev-B:** start Plan B Phase 1 (mechanical split of `cli/main.rs`). Cite that this is the precondition for everything else in B.
+   - **Dev-C:** start Plan C Phase 1 (typed `StateHost` + `View`/`PopupState` migration). Cite that phase 1 is the precondition for phases 3 and 4. Also cite the migration of `View`/`PopupState` to `shared/types.ts` to avoid the circular import.
+4. Wait for acknowledgement STATUS UPDATEs from all devs before clearing them to proceed deeper into their plans.

docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md

@@ -0,0 +1,64 @@
+# CLI Tail — Cycle 2 Coordinator
+
+**Date:** 2026-05-09
+**Status:** Draft (launches once cycle-1 prerequisites land)
+**Theme:** parallelize the post-split tail of Plan B (the CLI restructure) across three independent streams. Plan B's eight phases are already defined in `docs/superpowers/specs/2026-05-04-cli-restructure-design.md`; this coordinator only partitions the remaining phases across cycle-2 streams and records the cross-stream contracts.
+
+## What this is
+
+The cycle-1 four-agent run (`2026-05-04-arch-followup-*`) ships:
+
+- **Stream A** — Plan A (security + docs polish): `impl Drop for SessionHandle`, JS swallow removal, `recovery_qr.rs` docs, `start.sh` fourth-window. Independent of B and C.
+- **Stream B** — Plan B Phases 1 + 2 only (mechanical `main.rs` split + `helpers::git_run` + 16-site sweep). Stops after Phase 2 per a 2026-05-09 user-driven RESCOPE directive.
+- **Stream C** — Plan C (extension restructure). Did not launch in cycle 1 (DEV-C never acked); remains pending and is *not* picked up by cycle 2 (still its own multi-week effort, separate kickoff).
+
+The remaining six Plan B phases (3 through 8) are partitioned across three cycle-2 streams below. Each cycle-2 stream is independent of the other two once cycle-1 Stream B (Phase 1 + 2) has merged to `main`.
+
+## Pre-launch checklist (cycle 2 cannot open until all green)
+
+- [ ] Cycle-1 Stream A merged to `main`
+- [ ] Cycle-1 Stream B PR (Phase 1 + 2 bundle) merged to `main`
+- [ ] Working tree clean on `main`; `git pull` reflects both merges
+- [ ] All cycle-1 worktrees torn down (`git worktree remove ../relicario.arch-followup-stream-a` and `*-stream-b`); cycle-1 branches deleted locally if requested
+- [ ] Relay server still running on `localhost:7331` (check `ss -ltn 'sport = :7331'`)
+- [ ] Cycle-2 kickoff prompts present in `docs/superpowers/coordination/2026-05-09-cli-tail-{pm,dev-a,dev-b,dev-c}-prompt.md`
+
+## Stream partition
+
+| Stream | Branch | Worktree | Plan B phases | Theme |
+|---|---|---|---|---|
+| A | `feature/cli-tail-stream-a-prompt-helpers` | `/home/alee/Sources/relicario.cli-tail-stream-a` | Phase 3 | `prompt_or_flag<T>` + `build_*_item` compression |
+| B | `feature/cli-tail-stream-b-session-manifest` | `/home/alee/Sources/relicario.cli-tail-stream-b` | Phases 4, 5, 6 | `Vault::after_manifest_change`, canonical `ParamsFile`, batched purge |
+| C | `feature/cli-tail-stream-c-core-wasm-seam` | `/home/alee/Sources/relicario.cli-tail-stream-c` | Phases 7, 8 | parser migration to `relicario-core` + base32 dedup + WASM exports |
+
+Phases reference the canonical definitions in `docs/superpowers/specs/2026-05-04-cli-restructure-design.md`. Devs do NOT redesign — they execute against that spec.
+
+## Cross-stream dependencies (cycle 2)
+
+- **Stream A and Stream B**: both touch `crates/relicario-cli/src/commands/*.rs` files but in disjoint ways. Stream A modifies `commands/add.rs` (the seven `build_*_item` builders). Stream B modifies `commands/init.rs` (`ParamsFile`), `commands/trash.rs` (batched purge), and seven manifest-mutation sites scattered across `commands/{add,edit,trash,attach,settings,import}.rs`. Conflict surface is `commands/add.rs` (A modifies builders; B modifies the `after_manifest_change` callsite). Whoever opens their PR second rebases.
+- **Stream B internal sequencing**: Phase 6 (batched purge) depends on Phase 4 (`after_manifest_change` wrapper) — Phase 6's commit message logic uses the wrapper. Phase 5 (`ParamsFile`) is independent of 4 and 6 within Stream B; can ship first, last, or middle.
+- **Stream C**: touches `crates/relicario-core/`, `crates/relicario-wasm/`, and `extension/src/wasm.d.ts` only. Zero overlap with Streams A and B. Internal sequencing: Phase 7 (parser migration to core) before Phase 8 (WASM exports + `wasm.d.ts` mirror).
+- **No cross-stream interface contracts.** All three plans were finalized in cycle 1; the partition does not introduce new contracts.
+
+## Pre-merge checklist (per cycle-2 stream)
+
+Same as cycle 1, plus a narration check:
+
+- [ ] Stream's owned phases all complete per Plan B's "Done criteria"
+- [ ] `cargo test --workspace` green on the stream's worktree
+- [ ] `cargo clippy --workspace` silent
+- [ ] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` clean (always, but Stream C in particular)
+- [ ] No regression in CLI behaviour — existing `crates/relicario-cli/tests/*` tests pass without modification
+- [ ] Narration discipline observed — STATUS UPDATEs include in-flight beats, not just phase boundaries
+- [ ] PR description cross-references the corresponding Plan B phase numbers
+
+## Out of scope for cycle 2
+
+- Plan C (extension restructure) — multi-week effort, scheduled separately when DEV-C bandwidth available
+- The Plan B `helpers::git_run` itself (shipped in cycle 1 Stream B)
+- The cycle-1 P3 nits explicitly out-of-scope in Plan B
+- The eight "Open architectural decisions" from the synthesis
+
+## Tag
+
+No release tag for cycle 2. Same as the cycle-1 architecture-review followup train — these are structural-cleanup bundles, not versioned releases. Each stream merges via `gh pr merge --merge` (preserve history; no squash per project convention).

docs/superpowers/coordination/2026-05-09-cli-tail-dev-a-prompt.md

@@ -0,0 +1,199 @@
+# Dev A Kickoff Prompt — CLI Tail (Cycle 2) Stream A
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior developer** owning Stream A of the CLI-tail cycle-2 release.
+
+Stream A is **Plan B Phase 3** — `prompt_or_flag<T>` helper plus the seven `build_*_item` builder compression in the CLI. Single phase, S-M effort. The phase is defined in `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` under "Phase 3 — `prompt_or_flag<T>` and `build_*_item` compression". Cycle 1 already shipped the mechanical `main.rs` split (Phase 1) and the `helpers::git_run` sweep (Phase 2), so the file tree under `crates/relicario-cli/src/commands/` and `prompt.rs` is in place — your job is to add the helper to `prompt.rs` and refactor the seven builders in `commands/add.rs`.
+
+A PM in another terminal coordinates you with Dev-B (session/manifest discipline — Phases 4, 5, 6) and Dev-C (parser migration + WASM seam — Phases 7, 8). With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed.
+
+## Setup (do this first)
+
+```bash
+cd /home/alee/Sources/relicario
+git fetch
+git checkout main
+git pull
+git worktree add ../relicario.cli-tail-stream-a -b feature/cli-tail-stream-a-prompt-helpers
+cd ../relicario.cli-tail-stream-a
+pwd  # should print /home/alee/Sources/relicario.cli-tail-stream-a
+```
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario.cli-tail-stream-a`**. Force-cd subagents into this directory — `CLAUDE.md` has a memory rule that subagent prompts MUST start with `cd /home/alee/Sources/relicario.cli-tail-stream-a` so subagents don't accidentally commit to main. This is non-negotiable.
+
+Today: 2026-05-09. Project rules in `CLAUDE.md` apply.
+
+## 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-a"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-a"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-a")`. After emitting any status/question block: `post_message(from="dev-a", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-a","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-a"}'
+```
+
+**Cycle-1 lessons baked in (read once):**
+
+- **Prefer single-line `body` content** when posting to the relay. Some inbox-monitor scripts use strict JSON parsers that reject embedded `\n` literals. Use periods between sentences and ` -- ` for stronger breaks; reserve actual newlines for STATUS UPDATEs you're printing locally only.
+- **If you build your own inbox-monitor in Python**: f-strings cannot contain backslash-escaped quotes inside brace expressions. Use single quotes inside: `{m.get('from')}` not `{m.get(\"from\")}`. Cycle-1 dev-a and dev-b both hit this; documenting once here.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` — partition spec; confirms your scope is Phase 3 only
+3. `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — Plan B (your scope is **Phase 3 only**; read the whole plan for context, but execute Phase 3)
+4. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (skim only — your work is fully captured in Plan B)
+5. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — DEV-B's notes; the relevant section is the `build_*_item` discussion (line-level context for the seven builders the synthesis abbreviates)
+
+## Execution mode
+
+Use **subagent-driven-development** (per `CLAUDE.md` memory default for any multi-task plan). Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per sub-step, two-stage review.
+
+**Every subagent prompt MUST start with**:
+
+```
+cd /home/alee/Sources/relicario.cli-tail-stream-a
+```
+
+…before any other instruction. Non-negotiable per project memory.
+
+## Your scope and boundaries
+
+**In scope:** Plan B Phase 3 — adding `prompt_or_flag<T>` (and `prompt_or_flag_optional<T>`) to `crates/relicario-cli/src/prompt.rs`, then refactoring the seven `build_*_item` functions in `crates/relicario-cli/src/commands/add.rs` to use the helper. Per-type bodies should shrink by ~30%.
+
+**Out of scope:**
+- Phases 4, 5, 6 (Dev-B owns) — `Vault::after_manifest_change`, canonical `ParamsFile`, batched purge
+- Phases 7, 8 (Dev-C owns) — parser migration to `relicario-core`, base32 dedup, WASM exports
+- Anything outside Plan B's Phase 3 definition. If you trip over an out-of-scope issue, file a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- Do not change the CLI's external behaviour — all existing `crates/relicario-cli/tests/*` integration tests must pass without modification.
+- Do not merge your branch to main. The PM owns merges.
+- Do not push `--force` or run `git reset --hard`. Per `CLAUDE.md`: ask first.
+
+## Coordination protocol
+
+You are one of four terminals. The user runs all four; the PM in another terminal coordinates you.
+
+**Narration discipline.** STATUS UPDATEs at task boundaries are the floor, not the ceiling. Also emit `Status: IN-PROGRESS` updates at meaningful in-flight moments:
+
+- When you dispatch a subagent (so the user sees what's running)
+- When a subagent returns with a decision worth flagging (an unexpected finding, a trade-off taken, a surprise)
+- When a sub-task completes (e.g. `prompt_or_flag` helper landed; first builder converted)
+- When you change direction or hit something unexpected
+- When you start a new sub-step
+
+The `Notes` field should narrate WHAT happened and WHY — not just "Phase 3 done". Three sentences max. Examples of useful: "subagent reported `build_login_item` already takes Result-wrapped fields, so the conversion is just chain-flattening"; "found one builder uses `prompt_secret`, kept it on raw `prompt_secret` since `prompt_or_flag` doesn't handle the no-echo case." Examples of NOT useful: "builder converted" with no context; "tests pass" with no count.
+
+Print every STATUS UPDATE locally before/after sending it so the user reads it in your own terminal.
+
+**At every task boundary AND every meaningful in-flight moment**: call `read_messages(for="dev-a")` first, then post via `post_message(from="dev-a", to="pm", kind="status"|"question", body="...")` and also print here. Format:
+
+```
+## STATUS UPDATE — DEV-A
+Time: <iso8601>
+Branch: feature/cli-tail-stream-a-prompt-helpers
+Task: <number / short name>
+Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
+Last commit: <short sha + first line of message>
+Tests: <green | red (which failed) | N/A>
+Notes: <WHAT and WHY — 3 sentences max>
+```
+
+**When you need PM input mid-task**: post via `post_message(kind="question")`:
+
+```
+## QUESTION TO PM — DEV-A
+Time: <iso8601>
+Context: <what task, what decision point>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no
+```
+
+**You'll receive**: `## DIRECTIVE TO DEV-A` blocks from the PM.
+
+## Ship-it autonomy + simplify discipline
+
+The project's `.claude/settings.json` allows you to write files, run cargo/npm/bun/python3, commit, push, and open PRs without confirmation prompts. Move at speed.
+
+**Hard guardrails (the deny list blocks these — never bypass with workarounds):** no `rm` / `rmdir`, no `git push --force` / `--force-with-lease`, no `git reset --hard`, no `git branch -D`, no `git worktree remove`, no `git clean -f*`, no `git checkout -- *`, no `git restore --source*`, no `sudo`, no `chmod 777`, no database drops. If you genuinely need one of these, surface a `## QUESTION TO PM` block.
+
+**Speed without spaghetti — required before every REVIEW-READY:**
+
+- Invoke `superpowers:simplify` on the changed code (it reviews for duplicate logic, missed reuse, gratuitous abstraction, half-finished implementations). Either accept its findings (and fix in the same commit) or surface a one-sentence rationale in the STATUS UPDATE Notes for why a flagged issue is intentional.
+- Do not create parallel implementations of an existing helper. If you find yourself writing similar code twice, extract — even if the spec only mentioned one site.
+- Do not add error handling, fallbacks, or validation for scenarios that can't happen (`CLAUDE.md` rule). Trust internal code and framework guarantees.
+- Default to no comments unless the WHY is non-obvious (`CLAUDE.md` rule). Don't explain WHAT well-named code already does.
+- Half-finished implementations are forbidden. Either ship a complete sub-task or surface a `## QUESTION TO PM` block.
+
+## Authority within Phase 3
+
+You don't need PM permission to:
+
+- Execute sub-steps per Plan B's Phase 3
+- Make implementation decisions consistent with Plan B
+- Write tests, refactor your own code, fix bugs you introduce
+- Push commits to your feature branch
+
+You **do** escalate when:
+
+- A scope question outside Plan B Phase 3
+- A test you can't make green after honest debugging
+- A discovered bug not in Plan B
+- Anything destructive (per `CLAUDE.md`)
+- Before opening the PR for review
+
+## Final steps before REVIEW-READY
+
+Run the project's full validation:
+
+```bash
+cd /home/alee/Sources/relicario.cli-tail-stream-a
+cargo test --workspace
+cargo clippy --workspace
+cargo build -p relicario-wasm --target wasm32-unknown-unknown
+```
+
+All three must be green / clean. Then push and open the PR:
+
+```bash
+git push -u origin feature/cli-tail-stream-a-prompt-helpers
+gh pr create --base main --head feature/cli-tail-stream-a-prompt-helpers --title "refactor(cli): prompt_or_flag helper + build_*_item compression (Plan B Phase 3)" --body "$(cat <<'EOF'
+## Summary
+- Adds `prompt_or_flag<T>` and `prompt_or_flag_optional<T>` to `crates/relicario-cli/src/prompt.rs`
+- Refactors the seven `build_*_item` functions in `crates/relicario-cli/src/commands/add.rs` to use the helper
+- Per-type bodies shrink by ~30%; existing CLI integration tests pass without modification
+
+## Plan B Phase 3
+Implements `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` Phase 3.
+See `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` for cycle-2 partition.
+
+## Test plan
+- [x] cargo test --workspace
+- [x] cargo clippy --workspace
+- [x] cargo build -p relicario-wasm --target wasm32-unknown-unknown
+- [x] Existing crates/relicario-cli/tests/* pass without modification
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL.
+
+## First action
+
+After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created, plan absorbed, on `feature/cli-tail-stream-a-prompt-helpers`), then start Phase 3 sub-step 1 (add `prompt_or_flag<T>` to `prompt.rs`).

docs/superpowers/coordination/2026-05-09-cli-tail-dev-b-prompt.md

@@ -0,0 +1,210 @@
+# Dev B Kickoff Prompt — CLI Tail (Cycle 2) Stream B
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior developer** owning Stream B of the CLI-tail cycle-2 release.
+
+Stream B is **Plan B Phases 4, 5, 6** — session/manifest discipline. Three phases, S-M effort each, total mid-day to multi-day:
+
+- **Phase 4** — `Vault::after_manifest_change(&self, manifest: &Manifest)` wrapper that funnels the seven manifest-mutation sites in `commands/{add,edit,trash,attach,settings,import}.rs` through one `save_manifest + groups-cache write` path. Marks `save_manifest` as `pub(crate)` (or renames it `save_manifest_raw`) so callers must use the wrapper.
+- **Phase 5** — Single canonical `ParamsFile` in `crates/relicario-cli/src/session.rs`, replacing the two-definition split between `commands/init.rs` (write side) and `session.rs:114` (read side). Adds `Serialize` + `Deserialize`, `for_new_vault` constructor, `into_kdf_params` inversion. On-disk JSON format must round-trip with current `params.json` files.
+- **Phase 6** — Batched purge in `cmd_purge` and `cmd_trash_empty`. Renames `purge_item` to `purge_item_filesystem` (filesystem mutation only); the callers accumulate paths and run a single `git_run(...["rm", "-rf", "--ignore-unmatch", paths...])` plus `git_run(...["add", "manifest.enc"])` plus one `git_run(...["commit"])` per batch. A 50-item `trash empty` should fire 3 git invocations total, not 150.
+
+The phases are defined in `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` under "Phase 4", "Phase 5", "Phase 6". Internal sequencing: Phase 4 before Phase 6 (Phase 6 uses `after_manifest_change`); Phase 5 is independent of 4 and 6.
+
+A PM in another terminal coordinates you with Dev-A (Plan B Phase 3) and Dev-C (Plan B Phases 7, 8). With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed.
+
+## Setup (do this first)
+
+```bash
+cd /home/alee/Sources/relicario
+git fetch
+git checkout main
+git pull
+git worktree add ../relicario.cli-tail-stream-b -b feature/cli-tail-stream-b-session-manifest
+cd ../relicario.cli-tail-stream-b
+pwd  # should print /home/alee/Sources/relicario.cli-tail-stream-b
+```
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario.cli-tail-stream-b`**. Force-cd subagents into this directory — `CLAUDE.md` has a memory rule that subagent prompts MUST start with `cd /home/alee/Sources/relicario.cli-tail-stream-b` so subagents don't accidentally commit to main. Non-negotiable.
+
+Today: 2026-05-09. Project rules in `CLAUDE.md` apply.
+
+## 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-b"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-b"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-b")`. After emitting any status/question block: `post_message(from="dev-b", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-b","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-b"}'
+```
+
+**Cycle-1 lessons baked in (read once):**
+
+- **Prefer single-line `body` content** when posting to the relay. Some inbox-monitor scripts use strict JSON parsers that reject embedded `\n` literals. Use periods between sentences and ` -- ` for stronger breaks; reserve actual newlines for STATUS UPDATEs you're printing locally only.
+- **If you build your own inbox-monitor in Python**: f-strings cannot contain backslash-escaped quotes inside brace expressions. Use single quotes inside: `{m.get('from')}` not `{m.get(\"from\")}`. Cycle-1 dev-a and dev-b both hit this; documenting once here.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` — partition spec; confirms your scope is Phases 4, 5, 6 only
+3. `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — Plan B (read the whole plan; execute Phases 4, 5, 6)
+4. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (skim only)
+5. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — DEV-B's full notes; the relevant sections are `refresh_groups_cache` discipline, `ParamsFile` dedup, batched purge
+
+## Execution mode
+
+Use **subagent-driven-development**. Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per phase, two-stage review between phases.
+
+**Every subagent prompt MUST start with**:
+
+```
+cd /home/alee/Sources/relicario.cli-tail-stream-b
+```
+
+…before any other instruction.
+
+## Your scope and boundaries
+
+**In scope:** Plan B Phases 4, 5, 6.
+
+**Out of scope:**
+- Phase 3 (Dev-A owns) — `prompt_or_flag<T>` + `build_*_item` compression
+- Phases 7, 8 (Dev-C owns) — parser migration to `relicario-core`, base32 dedup, WASM exports
+- Anything outside Plan B Phases 4-6. If you trip over an out-of-scope issue, file a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- Phase 5 must round-trip with existing on-disk `params.json` — write a fixture-string test that reads a known-current params.json and asserts the canonical struct parses it identically. On-disk format change would break existing vaults.
+- Do not change CLI external behaviour — all existing `crates/relicario-cli/tests/*` integration tests must pass without modification.
+- The `groups.cache` plaintext "failures silently swallowed" doc-comment from current `helpers.rs:90-93` must be preserved on the new `after_manifest_change` wrapper. Don't change the policy.
+- Do not merge your branch to main. The PM owns merges.
+- Do not push `--force` or run `git reset --hard`. Per `CLAUDE.md`: ask first.
+
+**Internal phase sequencing (within Stream B):**
+- Phase 5 (`ParamsFile`) is independent — ship first to get it out of the way, OR last for diff-locality with the session-touching Phase 4. Either is fine; pick whichever reviews more cleanly.
+- Phase 4 (`after_manifest_change`) before Phase 6 (`batched purge`). Phase 6's commit logic relies on the wrapper.
+
+## Coordination protocol
+
+You are one of four terminals. The PM coordinates you with Dev-A and Dev-C.
+
+**Narration discipline.** STATUS UPDATEs at task boundaries are the floor, not the ceiling. Also emit `Status: IN-PROGRESS` updates at meaningful in-flight moments:
+
+- When you dispatch a subagent
+- When a subagent returns with a decision worth flagging (a found-but-unexpected coupling, a trade-off taken)
+- When a sub-task completes (e.g. `after_manifest_change` wrapper landed; first manifest-mutation site converted; `ParamsFile` round-trip test green)
+- When you change direction or hit something unexpected
+- When you start a new phase
+
+The `Notes` field should narrate WHAT and WHY. Three sentences max. Examples of useful: "Phase 5 fixture test caught that `format_version` was previously emitted but never read; preserved the field but kept the read side tolerant"; "found one manifest-mutation site in `commands/import.rs` that did NOT call `refresh_groups_cache` historically (DEV-B notes flagged 7 sites; this is an 8th — surfacing as a question)." Print every STATUS UPDATE locally too.
+
+**At every task boundary AND every meaningful in-flight moment**: call `read_messages(for="dev-b")`, then post and print using:
+
+```
+## STATUS UPDATE — DEV-B
+Time: <iso8601>
+Branch: feature/cli-tail-stream-b-session-manifest
+Task: <phase number / sub-step>
+Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
+Last commit: <short sha + first line>
+Tests: <green | red (which failed) | N/A>
+Notes: <WHAT and WHY — 3 sentences max>
+```
+
+**For PM input mid-task**:
+
+```
+## QUESTION TO PM — DEV-B
+Time: <iso8601>
+Context: <what task, what decision point>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no
+```
+
+## Ship-it autonomy + simplify discipline
+
+The project's `.claude/settings.json` allows you to write files, run cargo/npm/bun/python3, commit, push, and open PRs without confirmation prompts. Move at speed.
+
+**Hard guardrails (the deny list blocks these — never bypass with workarounds):** no `rm` / `rmdir`, no `git push --force` / `--force-with-lease`, no `git reset --hard`, no `git branch -D`, no `git worktree remove`, no `git clean -f*`, no `git checkout -- *`, no `git restore --source*`, no `sudo`, no `chmod 777`, no database drops. If you genuinely need one of these, surface a `## QUESTION TO PM` block.
+
+**Speed without spaghetti — required before every REVIEW-READY:**
+
+- Invoke `superpowers:simplify` on the changed code (it reviews for duplicate logic, missed reuse, gratuitous abstraction, half-finished implementations). Either accept its findings (and fix in the same commit) or surface a one-sentence rationale in the STATUS UPDATE Notes for why a flagged issue is intentional.
+- Do not create parallel implementations of an existing helper. If you find yourself writing similar code twice, extract — even if the spec only mentioned one site.
+- Do not add error handling, fallbacks, or validation for scenarios that can't happen (`CLAUDE.md` rule). Trust internal code and framework guarantees.
+- Default to no comments unless the WHY is non-obvious (`CLAUDE.md` rule). Don't explain WHAT well-named code already does.
+- Half-finished implementations are forbidden. Either ship a complete sub-task or surface a `## QUESTION TO PM` block.
+
+## Authority within Phases 4-6
+
+You don't need PM permission to:
+
+- Execute sub-steps per Plan B's Phases 4, 5, 6
+- Make implementation decisions consistent with Plan B
+- Write tests, refactor your own code, fix bugs you introduce
+- Push commits to your feature branch
+
+You **do** escalate when:
+
+- A scope question outside Plan B Phases 4-6
+- A test you can't make green after honest debugging
+- A discovered bug not in Plan B
+- Anything destructive (per `CLAUDE.md`)
+- Before opening the PR for review
+- If you find an unexpected manifest-mutation site beyond the seven DEV-B notes flagged (likely surfaces in Phase 4)
+
+## Final steps before REVIEW-READY
+
+Run the project's full validation:
+
+```bash
+cd /home/alee/Sources/relicario.cli-tail-stream-b
+cargo test --workspace
+cargo clippy --workspace
+cargo build -p relicario-wasm --target wasm32-unknown-unknown
+```
+
+All three must be green / clean. Then push and open the PR:
+
+```bash
+git push -u origin feature/cli-tail-stream-b-session-manifest
+gh pr create --base main --head feature/cli-tail-stream-b-session-manifest --title "refactor(cli): session/manifest discipline (Plan B Phases 4, 5, 6)" --body "$(cat <<'EOF'
+## Summary
+- Phase 4 — `Vault::after_manifest_change` wrapper funnels seven manifest-mutation sites; `save_manifest` made `pub(crate)` so callers can't bypass the wrapper
+- Phase 5 — Single canonical `ParamsFile` in `session.rs` replaces the two-definition split; on-disk JSON round-trips with existing vaults (fixture-string test)
+- Phase 6 — Batched purge: a 50-item `trash empty` now fires 3 git invocations instead of 150
+
+## Plan B Phases 4-6
+Implements `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` Phases 4, 5, 6.
+See `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` for cycle-2 partition.
+
+## Test plan
+- [x] cargo test --workspace
+- [x] cargo clippy --workspace
+- [x] cargo build -p relicario-wasm --target wasm32-unknown-unknown
+- [x] params.json round-trip test against existing on-disk format
+- [x] `trash empty` with N items produces 1 commit (regression invariant)
+- [x] Existing crates/relicario-cli/tests/* pass without modification
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL.
+
+## First action
+
+After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created, plan absorbed, on `feature/cli-tail-stream-b-session-manifest`), then start Phase 4 (or Phase 5 if you prefer to ship the independent piece first — call it out in the status update).

docs/superpowers/coordination/2026-05-09-cli-tail-dev-c-prompt.md

@@ -0,0 +1,219 @@
+# Dev C Kickoff Prompt — CLI Tail (Cycle 2) Stream C
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior developer** owning Stream C of the CLI-tail cycle-2 release.
+
+Stream C is **Plan B Phases 7 and 8** — the parser migration to `relicario-core` plus the WASM seam. Two phases, M effort:
+
+- **Phase 7** — Migrate `parse_month_year`, `base32_decode_lenient`, `guess_mime` from `crates/relicario-cli/src/parse.rs` into `relicario-core` (`MonthYear::parse` on `time.rs`, new `pub(crate) mod base32` with `encode_rfc4648` / `decode_rfc4648_lenient`, new `mime::guess_for_extension`). Pair with DEV-A's P2 base32 dedup: extract the inline `base32_encode` from `crates/relicario-core/src/item.rs:255-275` and `decode_base32_totp` from `crates/relicario-core/src/import_lastpass.rs:202-220` into the new shared module. Steam's `STEAM_ALPHABET` at `item_types/totp.rs:13` stays untouched (with a neighbour comment). The CLI's `parse.rs` becomes a thin re-export shim — no callsite changes in cycle 2.
+- **Phase 8** — `#[wasm_bindgen]` exports for the three migrated parsers (`parse_month_year`, `base32_decode_lenient`, `guess_mime`) plus the matching declarations in `extension/src/wasm.d.ts`. snake_case JS naming consistent with every existing export. Plan C (extension restructure) does NOT consume these this round — the seam ships in cycle 2; consumption is a future plan.
+
+Phase definitions are canonical in `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` Phases 7 and 8. Internal sequencing: Phase 7 before Phase 8.
+
+A PM in another terminal coordinates you with Dev-A (Plan B Phase 3) and Dev-B (Plan B Phases 4, 5, 6). With the relay server running, you communicate via `post_message` / `read_messages` directly.
+
+## Setup (do this first)
+
+```bash
+cd /home/alee/Sources/relicario
+git fetch
+git checkout main
+git pull
+git worktree add ../relicario.cli-tail-stream-c -b feature/cli-tail-stream-c-core-wasm-seam
+cd ../relicario.cli-tail-stream-c
+pwd  # should print /home/alee/Sources/relicario.cli-tail-stream-c
+```
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario.cli-tail-stream-c`**. Force-cd subagents into this directory — `CLAUDE.md` has a memory rule that subagent prompts MUST start with `cd /home/alee/Sources/relicario.cli-tail-stream-c` so subagents don't accidentally commit to main. Non-negotiable.
+
+Today: 2026-05-09. Project rules in `CLAUDE.md` apply.
+
+## 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-c"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-c"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-c")`. After emitting any status/question block: `post_message(from="dev-c", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-c","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-c"}'
+```
+
+**Cycle-1 lessons baked in (read once):**
+
+- **Prefer single-line `body` content** when posting to the relay. Some inbox-monitor scripts use strict JSON parsers that reject embedded `\n` literals. Use periods between sentences and ` -- ` for stronger breaks; reserve actual newlines for STATUS UPDATEs you're printing locally only.
+- **If you build your own inbox-monitor in Python**: f-strings cannot contain backslash-escaped quotes inside brace expressions. Use single quotes inside: `{m.get('from')}` not `{m.get(\"from\")}`. Cycle-1 DEV-A and DEV-B both hit this; documenting once here so cycle-2 DEV-C does not.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` — partition spec; confirms your scope is Phases 7 + 8 only
+3. `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — Plan B (read the whole plan; execute Phases 7 and 8)
+4. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (skim only — your work is fully captured in Plan B)
+5. `docs/superpowers/reviews/2026-05-04-dev-a-notes.md` — DEV-A's notes; the relevant section is the P2 "three base32 implementations" finding (the dedup that pairs with your Phase 7)
+6. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — DEV-B's notes; the relevant section is the parser-migration P2 (line-level context for `parse_month_year`, `base32_decode_lenient`, `guess_mime`)
+7. `docs/superpowers/reviews/2026-05-04-dev-c-notes.md` — read **only** the "Boundary notes for DEV-B" section (cross-boundary contracts — `wasm.d.ts` is hand-maintained; every change must mirror; BigInt typing care for `attachment_encrypt`-style paths, but your three new exports take only `&str` and return primitives so they avoid that class)
+
+## Execution mode
+
+Use **subagent-driven-development**. Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per phase, two-stage review.
+
+**Every subagent prompt MUST start with**:
+
+```
+cd /home/alee/Sources/relicario.cli-tail-stream-c
+```
+
+…before any other instruction.
+
+## Your scope and boundaries
+
+**In scope:** Plan B Phases 7 and 8 — parser migration to `relicario-core` (paired with DEV-A P2 base32 dedup), then WASM exports + `extension/src/wasm.d.ts` mirror.
+
+**Out of scope:**
+- Phase 3 (Dev-A owns) — `prompt_or_flag<T>` + builder compression
+- Phases 4, 5, 6 (Dev-B owns) — session/manifest discipline
+- Plan C (extension restructure) — consumption of your new WASM exports is explicitly deferred to a future plan; you ship the seam, you do NOT wire SW message handlers in the extension.
+- Anything outside Plan B Phases 7-8. If you trip over an out-of-scope issue (e.g. a fourth base32 implementation surfaces; a parser the CLI uses that wasn't in Plan B's three), file a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- Steam's `STEAM_ALPHABET` at `crates/relicario-core/src/item_types/totp.rs:13` is intentionally non-RFC-4648; do NOT consolidate it into the new shared base32 module. Add a neighbour comment: `// not RFC 4648 — Steam Guard's de-ambiguated alphabet; see crate::base32 for the standard impl.`
+- The CLI's `parse.rs` becomes a thin re-export shim — keep callsite imports unchanged in cycle 2 (no caller-side import churn).
+- WASM JS naming stays snake_case for the three new exports — consistent with every existing `#[wasm_bindgen]` export. Do NOT introduce camelCase here; that decision is explicitly deferred per Plan B.
+- `extension/src/wasm.d.ts` mirror lands in the same commit as the Rust `#[wasm_bindgen]` additions. Both sides updated together; no half-state.
+- Do not change CLI external behaviour — all existing `crates/relicario-cli/tests/*` integration tests must pass without modification.
+- Do not merge your branch to main. The PM owns merges.
+- Do not push `--force` or run `git reset --hard`. Per `CLAUDE.md`: ask first.
+
+**Internal phase sequencing (within Stream C):**
+- Phase 7 (parser migration to core + base32 dedup) before Phase 8 (WASM exports). Phase 8 imports from the new core paths; Phase 7 must compile clean first.
+
+## Coordination protocol
+
+You are one of four terminals. The PM coordinates you with Dev-A and Dev-B.
+
+**Narration discipline.** STATUS UPDATEs at task boundaries are the floor, not the ceiling. Also emit `Status: IN-PROGRESS` updates at meaningful in-flight moments:
+
+- When you dispatch a subagent
+- When a subagent returns with a decision worth flagging (an unexpected coupling, an alternative API shape considered, a found-but-flagged out-of-scope issue)
+- When a sub-task completes (e.g. base32 module landed; `MonthYear::parse` integrated; first WASM export wired)
+- When you change direction or hit something unexpected
+- When you start a new phase
+
+The `Notes` field should narrate WHAT and WHY. Three sentences max. Examples of useful: "subagent surfaced a fourth base32 callsite in `crates/relicario-core/src/manifest.rs:??`; not in DEV-A P2's flagged list — escalating as a question"; "kept `MonthYear::parse` returning `Result<Self, RelicarioError>` rather than touching `MonthYear::new`'s `&'static str` per Plan B's recommendation; `new`-to-`RelicarioError` is DEV-A's separate P3"; "WASM exports compile clean; `wasm.d.ts` mirror passes `tsc --noEmit` in `extension/`." Print every STATUS UPDATE locally too.
+
+**At every task boundary AND every meaningful in-flight moment**: call `read_messages(for="dev-c")` first, then post via `post_message` and print here. Format:
+
+```
+## STATUS UPDATE — DEV-C
+Time: <iso8601>
+Branch: feature/cli-tail-stream-c-core-wasm-seam
+Task: <phase number / sub-step>
+Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
+Last commit: <short sha + first line>
+Tests: <green | red (which failed) | N/A>
+Notes: <WHAT and WHY — 3 sentences max>
+```
+
+**For PM input mid-task**:
+
+```
+## QUESTION TO PM — DEV-C
+Time: <iso8601>
+Context: <what task, what decision point>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no
+```
+
+## Ship-it autonomy + simplify discipline
+
+The project's `.claude/settings.json` allows you to write files, run cargo/npm/bun/python3, commit, push, and open PRs without confirmation prompts. Move at speed.
+
+**Hard guardrails (the deny list blocks these — never bypass with workarounds):** no `rm` / `rmdir`, no `git push --force` / `--force-with-lease`, no `git reset --hard`, no `git branch -D`, no `git worktree remove`, no `git clean -f*`, no `git checkout -- *`, no `git restore --source*`, no `sudo`, no `chmod 777`, no database drops. If you genuinely need one of these, surface a `## QUESTION TO PM` block.
+
+**Speed without spaghetti — required before every REVIEW-READY:**
+
+- Invoke `superpowers:simplify` on the changed code (it reviews for duplicate logic, missed reuse, gratuitous abstraction, half-finished implementations). Either accept its findings (and fix in the same commit) or surface a one-sentence rationale in the STATUS UPDATE Notes for why a flagged issue is intentional.
+- Do not create parallel implementations of an existing helper. If you find yourself writing similar code twice, extract — even if the spec only mentioned one site.
+- Do not add error handling, fallbacks, or validation for scenarios that can't happen (`CLAUDE.md` rule). Trust internal code and framework guarantees.
+- Default to no comments unless the WHY is non-obvious (`CLAUDE.md` rule). Don't explain WHAT well-named code already does.
+- Half-finished implementations are forbidden. Either ship a complete sub-task or surface a `## QUESTION TO PM` block.
+
+## Authority within Phases 7-8
+
+You don't need PM permission to:
+
+- Execute sub-steps per Plan B's Phases 7 and 8
+- Make implementation decisions consistent with Plan B
+- Write tests, refactor your own code, fix bugs you introduce
+- Push commits to your feature branch
+
+You **do** escalate when:
+
+- A scope question outside Plan B Phases 7-8
+- A test you can't make green after honest debugging
+- A discovered bug not in Plan B
+- A fourth base32 implementation or a parser surfaces beyond DEV-A P2 + Plan B's three
+- Anything destructive (per `CLAUDE.md`)
+- Before opening the PR for review
+
+## Final steps before REVIEW-READY
+
+Run the project's full validation:
+
+```bash
+cd /home/alee/Sources/relicario.cli-tail-stream-c
+cargo test --workspace
+cargo clippy --workspace
+cargo build -p relicario-wasm --target wasm32-unknown-unknown
+cd extension && npm run test  # verify wasm.d.ts mirror compiles against TS callers
+```
+
+All four must be green / clean. Then push and open the PR:
+
+```bash
+cd /home/alee/Sources/relicario.cli-tail-stream-c
+git push -u origin feature/cli-tail-stream-c-core-wasm-seam
+gh pr create --base main --head feature/cli-tail-stream-c-core-wasm-seam --title "refactor(core,wasm): migrate parsers + base32 dedup + WASM exports (Plan B Phases 7, 8)" --body "$(cat <<'EOF'
+## Summary
+- Phase 7 — `parse_month_year`, `base32_decode_lenient`, `guess_mime` migrated from CLI to `relicario-core` (`MonthYear::parse`, new `pub(crate) mod base32`, new `mime::guess_for_extension`); base32 dedup folds `crates/relicario-core/src/item.rs:255-275` and `import_lastpass.rs:202-220` into the new shared module (Steam alphabet untouched per neighbour comment)
+- Phase 8 — `#[wasm_bindgen]` exports for the three migrated parsers; `extension/src/wasm.d.ts` mirror updated in the same commit; snake_case JS naming consistent with existing exports
+- The CLI's `parse.rs` is a thin re-export shim; existing CLI callsites unchanged
+
+## Plan B Phases 7-8
+Implements `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` Phases 7 and 8.
+See `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` for cycle-2 partition.
+
+## Test plan
+- [x] cargo test --workspace
+- [x] cargo clippy --workspace
+- [x] cargo build -p relicario-wasm --target wasm32-unknown-unknown
+- [x] cd extension && npm run test (verifies wasm.d.ts compiles)
+- [x] Existing crates/relicario-cli/tests/* pass without modification
+- [x] Existing crates/relicario-core/tests/* pass without modification
+
+## Out of scope (deferred)
+- Extension consumption of the new WASM exports — Plan C territory; no SW message handlers wired in this PR
+- camelCase JS naming for the three new exports — explicitly snake_case per Plan B; the camelCase decision is its own future plan
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL.
+
+## First action
+
+After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created, plan absorbed, on `feature/cli-tail-stream-c-core-wasm-seam`), then start Phase 7 sub-step 1 (create `crates/relicario-core/src/base32.rs` with the unified `encode_rfc4648` / `decode_rfc4648_lenient` shape).

docs/superpowers/coordination/2026-05-09-cli-tail-pm-prompt.md

@@ -0,0 +1,145 @@
+# PM Kickoff Prompt — CLI Tail (Cycle 2)
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are the **project manager** for the CLI-tail cycle-2 release. Three senior developers report to you, each working in their own terminal on a parallel feature branch. The user runs all four terminals.
+
+This release has no version tag — it's the second cycle of the architecture-review structural-cleanup bundle. Cycle 1 shipped Plan A (security + docs polish) and Plan B Phases 1 + 2 (mechanical `main.rs` split + `git_run` helper). Cycle 2 partitions the remaining six Plan B phases (3 through 8) across three independent streams. Plan C (extension restructure) is *not* in cycle 2 — it stays pending until DEV-C bandwidth is available, on its own kickoff.
+
+## Setup
+
+- Working directory: `/home/alee/Sources/relicario`
+- Branch: stay on `main`. Do not check out feature branches.
+- Today: 2026-05-09. Project rules in `CLAUDE.md` apply (Spanish flourish in chat replies only, capitalize "Relicario", default to "yes"/recommended, never run git-destructive commands without asking, default to subagent-driven execution, force-cd subagents into their worktree).
+
+**Pre-launch state assumed:** cycle-1 Stream A merged, cycle-1 Stream B PR (Phase 1 + 2) merged, working tree clean on `main`, relay server alive on `localhost:7331`. Verify with `git log --oneline -5` and `ss -ltn 'sport = :7331'` before sending opening directives. If either is not in place, surface to the user before proceeding.
+
+## Cycle 1 outcomes (read for context — your context starts cold)
+
+The cycle-1 four-agent run (`docs/superpowers/coordination/2026-05-04-arch-followup-*-prompt.md`) produced:
+
+- **Stream A (security + docs polish)** merged to `main`. Key commits: `1e858e1` impl Drop for SessionHandle, `03d0781` SW free() unswallow, `229e483` recovery_qr.rs documentation, `f8296fa` rustdoc warning fix on a private intra-doc link, `0c9387f` start.sh fourth-window. Plan A complete.
+- **Stream B (CLI restructure Phases 1 + 2 only)** merged to `main` per a 2026-05-09 RESCOPE directive that halted Plan B at Phase 2 to enable cycle-2 parallelization. Key commits: `97c8f99` 15-site git_run sweep, `f3cdbed` git_run helper. `main.rs` shipped at 509 LOC (vs spec's ≤500); the 9-LOC overshoot is `#[arg(...)]` attribute density on 9 sub-enums and was accepted at merge — substance criterion (clap surface + dispatch + 2 shim families only) was met. DEV-B chose Plan B's option (b) for `git_run` (capture stderr + replay on failure) over option (a) (terminal-aware streaming).
+- **Stream C (extension restructure)** did NOT launch in cycle 1 (cycle-1 DEV-C never acked). Plan C remains pending and is *not* part of cycle 2 — it is a multi-week effort scheduled separately on its own kickoff.
+- **17 pre-existing extension test failures** on the kickoff baseline `bd3d53f` were documented in cycle-1 Stream A's PR. They sit in `extension/src/{service-worker,popup}/...` (devices/router/settings clusters) and pre-date the architecture review. Treat as the regression baseline: any cycle-2 red test outside this 17-failure cluster is a new regression and a stream's responsibility.
+
+## Lessons learned (bake into your coordination)
+
+Cycle 1 surfaced three operational gotchas worth pre-empting:
+
+- **Prefer single-line relay message bodies.** Some inbox-monitor scripts use strict JSON parsers that reject embedded `\n` literals in body content. Compose `body` fields as a single line with sentences separated by periods; use ` -- ` for stronger breaks. The relay itself accepts multi-line bodies, but the consuming dev's monitor may not.
+- **Python f-string footgun in inbox-monitor scripts.** If a dev reports a `SyntaxError: unexpected character after line continuation character`, their polling script likely uses `print(f"... {m.get(\"from\")} ...")` — Python f-strings cannot contain backslash-escaped quotes inside brace expressions. Fix is single quotes: `m.get('from')`.
+- **Narration policy is non-negotiable.** Cycle 1 added it mid-run; cycle 2 has it baked into every kickoff. Devs MUST emit `Status: IN-PROGRESS` updates at meaningful in-flight moments (subagent dispatch, surprise findings, sub-task complete, phase start), not just at phase boundaries. You MUST narrate to the user in plain prose between tool calls — when a STATUS UPDATE lands, summarize it for the user before deciding; when you send a directive, state the rationale; when you dispatch a subagent, say so. Enforce both.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/coordination/2026-05-09-cli-tail-coordinator.md` — **partition spec for this cycle. The canonical source for who owns what.**
+3. `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — Plan B (phase definitions). Cycle 2 executes Phases 3 through 8.
+4. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — original synthesis (read the P-tags Plan B addresses: P1.2, P1.3, P1.10, plus the four CLI P2s)
+5. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — DEV-B's full notes (line-level context the synthesis abbreviates)
+
+You do NOT need to read Plans A or C in detail — they're out of cycle-2 scope. Skim the partition coordinator's "Cross-stream dependencies" section so you know what conflicts to watch for.
+
+## Stream overview (from coordinator)
+
+| Stream | Branch | Owner | Plan B phases | Theme |
+|---|---|---|---|---|
+| A | `feature/cli-tail-stream-a-prompt-helpers` | DEV-A | Phase 3 | `prompt_or_flag<T>` + `build_*_item` compression |
+| B | `feature/cli-tail-stream-b-session-manifest` | DEV-B | Phases 4, 5, 6 | `Vault::after_manifest_change`, canonical `ParamsFile`, batched purge |
+| C | `feature/cli-tail-stream-c-core-wasm-seam` | DEV-C | Phases 7, 8 | parser migration to core + base32 dedup + WASM exports |
+
+**No interface contracts between streams.** All three are independent once the cycle-1 PRs have merged. Conflict surface: `commands/add.rs` (A modifies builders; B modifies a manifest-mutation callsite). Whichever stream opens its PR second rebases.
+
+## Your authority
+
+- Approve or deny scope changes from devs
+- Review and merge PRs from each stream's feature branch
+- Edit `docs/`, `CLAUDE.md`, or other doc artifacts as needed; do not write feature code
+
+## Your boundaries
+
+- Don't write feature code yourself. Edits to docs / `CLAUDE.md` are fine.
+- Don't deviate from Plan B's phase definitions 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 — no tag planned for this cycle.
+- Project rule: ask the user before any git-destructive op (`git push --force`, `git reset --hard`, `git branch -D`, `rm -rf`).
+
+## 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, dev-c`. Use these instead of asking the user to copy-paste. After sending any directive, call `post_message(from="pm", to="dev-X", kind="directive", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session (this happens when the relay server was not running when your session opened), use the Python shim:
+
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"pm","to":"dev-a","kind":"directive","body":"..."}'
+python3 call.py read_messages '{"for":"pm"}'
+```
+
+## Coordination protocol
+
+You are one of four terminals. Use `post_message` / `read_messages` directly. Call `read_messages(for="pm")` before every action.
+
+**Narrate to the user in plain prose between tool calls.** The user's only window into the release is this terminal output. Don't emit DIRECTIVE blocks silently. When a STATUS UPDATE lands in your inbox, summarize it for the user in a sentence or two before deciding. When you send a directive, state the rationale briefly so the user sees the reasoning, not just the verdict. When you dispatch a subagent (e.g. for plan review or coherence pass), say so. One or two sentences per beat is plenty — the goal is for the user to read this terminal top-to-bottom and understand the release as a story.
+
+**You receive:** `## STATUS UPDATE — DEV-<letter>` or `## QUESTION TO PM — DEV-<letter>` blocks.
+
+**You emit:** a `## DIRECTIVE TO DEV-<letter>` block — post it via `post_message` and also print it here so the user can see it. Format:
+
+```
+## DIRECTIVE TO DEV-<letter>
+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, give a current rollup:
+
+```
+## RELEASE STATUS — CLI Tail (Cycle 2)
+Devs: <per-dev one-line state>
+PM: <what you're working on>
+Blockers: <list, or "none">
+Next milestone: <e.g., "Stream A REVIEW-READY", "all three streams 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 the diff against Plan B's "Done criteria" entries for that stream's phases
+4. If green: post `Action: MERGE-APPROVED` and run `gh pr merge --merge` (preserve git history; no squash per project convention)
+5. If red: post `Action: HOLD` with specific concerns
+
+Use `superpowers:requesting-code-review` if you want a deeper independent review from a fresh subagent before approving.
+
+## Pre-merge checklist (per stream)
+
+Before each `MERGE-APPROVED`:
+
+- [ ] Plan B's "Done criteria" for the stream's owned phases all checked
+- [ ] `cargo test --workspace` green on the stream's worktree
+- [ ] `cargo clippy --workspace` silent
+- [ ] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` clean (always, Stream C especially)
+- [ ] No regression in CLI behaviour — existing `crates/relicario-cli/tests/*` pass without modification
+- [ ] Narration discipline observed in the PR's STATUS UPDATE history
+
+## First action
+
+1. Call `read_messages(for="pm")` to drain any early inbox messages.
+2. Verify pre-launch state: `git log --oneline -5 main`, `git status`, `ss -ltn 'sport = :7331'`. If any check fails, surface to the user before proceeding.
+3. Emit a `## RELEASE STATUS` block confirming context absorbed.
+4. Wait for setup-acknowledge STATUS UPDATEs from all three devs (their kickoff prompts have them post one after creating their worktree). Once all three are in, post opening `PROCEED` directives confirming each stream's plan path and phase scope.
+5. Standing watch: drain inbox before each action; respond to QUESTIONs and STATUS UPDATEs as they arrive.

docs/superpowers/coordination/RELAY.md

@@ -0,0 +1,199 @@
+# RELAY — Multi-Agent Kickoff & Coordination
+
+How to spin up parallel Claude Code sessions that coordinate over a shared MCP relay. One PM, two or more Devs, each in their own terminal, each on their own branch / worktree, exchanging structured messages.
+
+## TL;DR — three commands
+
+```bash
+# 1. Generate kickoff prompts (interactive — answers the design questions)
+#    In any Claude Code session in this repo:
+/multi-agent-kickoff
+
+# 2. Start the relay + open the windows
+bash tools/relay/start.sh --kitty   # or --tmux, or --manual
+
+# 3. In each new Claude window, paste the prompt below the `---` line
+#    from the file the launcher prints (e.g. coordination/<date>-pm-prompt.md)
+```
+
+That's the whole workflow. Everything below is the why and the troubleshooting.
+
+## What this is
+
+The "PM/Senior-Dev paradigm" — one Claude session acts as project manager, two or more Claude sessions act as senior developers, each running its own subagents on a feature branch in its own worktree. They coordinate by sending each other typed messages (status / question / directive / free) through a tiny MCP server running locally.
+
+When to use it:
+
+- You have **2+ implementation plans** that share a release target and want to execute them in parallel under one coordinator.
+- You want each stream isolated (separate worktree, separate branch) so subagents can't accidentally commit to main or step on each other's files.
+- You want one human (the user) to be a relay-of-last-resort but not a router — the PM does the routing.
+
+When NOT to use it: one-off tasks, single-stream plans, anything where the overhead of "spin up four windows" exceeds the work itself. For those, just work in the foreground.
+
+## The pieces
+
+```
+┌──────────────────┐  HTTP/SSE  ┌──────────────────┐
+│  Relay (MCP)     │◀───────────│  PM session      │
+│  tools/relay/    │            │  (Claude Code)   │
+│  port 7331       │            └──────────────────┘
+│                  │            ┌──────────────────┐
+│  Per-role inbox  │◀───────────│  Dev-A session   │
+│  in-memory       │            │  (Claude Code)   │
+│  consume-once    │            └──────────────────┘
+└──────────────────┘            ┌──────────────────┐
+                       ◀────────│  Dev-B session   │
+                                │  (Claude Code)   │
+                                └──────────────────┘
+                       ┌──────── (optional) ───────┐
+                       ◀────────│  Dev-C session    │
+                                └───────────────────┘
+```
+
+- **Relay MCP server** — `tools/relay/server.ts`. HTTP/SSE on `localhost:7331`. Exposes three MCP tools: `post_message`, `read_messages`, `list_pending`. Per-connection MCP server instance prevents routing collisions across concurrent SSE clients.
+- **In-memory queue** — `tools/relay/queue.ts`. Per-role inbox (`pm`, `dev-a`, `dev-b`, `dev-c`). `read` is consume-once (FIFO drain). No TTL, no persistence, no cap — relay is dev-only ephemeral; restart the server to wipe state.
+- **Launcher** — `tools/relay/start.sh`. Three modes (manual / tmux / kitty) that all start the relay and either open the role windows or print the commands for you to open them by hand.
+- **Fallback shim** — `tools/relay/call.py` (Python) and `tools/relay/call.ts` (TS). Direct CLI access to the same MCP tools, for when the in-Claude MCP client isn't loading or you want to script a status check from a regular shell. Both are tracked in the repo and load-bearing for the multi-agent flow — do not delete.
+
+## Invocation
+
+### Step 1 — Generate the kickoff prompts
+
+In any Claude Code session inside this repo, run:
+
+```
+/multi-agent-kickoff
+```
+
+The skill walks you through a short Q&A (release target, branch names per dev, plan-file paths, coordination cadence) and writes four prompt files to `docs/superpowers/coordination/`:
+
+```
+<date>-pm-prompt.md
+<date>-dev-a-prompt.md
+<date>-dev-b-prompt.md
+<date>-dev-c-prompt.md   (only if 3 devs)
+```
+
+Each prompt is self-contained: it tells the receiving session its role, its branch / worktree, the plan it owns, and the coordination protocol (block format, when to send status, who to escalate to). The launcher script discovers the latest `*-pm-prompt.md` / `*-dev-a-prompt.md` / etc. by `mtime`, so the most recently generated set wins automatically.
+
+### Step 2 — Start the relay
+
+Pick a launcher mode that matches your terminal setup.
+
+**`--kitty` (recommended on kitty)**
+
+```bash
+bash tools/relay/start.sh --kitty
+```
+
+Opens 4 (or 5 with dev-c) tabs in the current kitty window: one for the relay log, one per role. Each role tab launches `claude` in the repo root. Paste the corresponding prompt into each role tab to start the session.
+
+**`--tmux` (recommended on non-kitty)**
+
+```bash
+bash tools/relay/start.sh --tmux
+```
+
+Creates a tmux session `relay-lift` with windows `relay`, `pm`, `dev-a`, `dev-b` (and `dev-c` if a fourth prompt is found). Attaches automatically. `Ctrl-b N` to navigate windows. Detach with `Ctrl-b d`.
+
+**`--manual` (for any terminal)**
+
+```bash
+bash tools/relay/start.sh --manual
+```
+
+Starts the relay in the current terminal and prints `cat <path>` commands for each role. Open new terminals yourself and paste the printed commands; this is the most flexible mode for unusual setups (split panes, remote sessions, terminal multiplexers other than tmux).
+
+The launcher uses port **7331**. If it's already in use the script aborts with the kill command — `kill $(lsof -ti:7331)` clears it.
+
+### Step 3 — Drive the coordination
+
+The PM session is the entry point. Talk to PM about goals; PM decides who's working on what and posts directives to the dev sessions via the relay. Each dev reads its inbox, executes, and posts back status / questions. The user (you) is mostly a watcher — PM should self-route.
+
+Common rhythm:
+
+- **PM at start:** posts a directive to each dev describing the first slice.
+- **Dev on completion:** posts status with branch / commit / what shipped.
+- **Dev when blocked:** posts a question; PM unblocks (decision) or escalates to user.
+- **PM end-of-cycle:** asks each dev for a status, summarizes, decides next slice.
+
+Message kinds (`MessageKind` in `queue.ts`):
+
+| Kind | Use when |
+|------|----------|
+| `status` | "I shipped X, branch is at Y, ready for next slice" |
+| `question` | "Should I do A or B? Blocking until I hear back" |
+| `directive` | PM-to-dev: "Next, do X. Constraints are Y. Acceptance is Z." |
+| `free` | Anything that doesn't fit the above (FYI, side-channel chatter) |
+
+Block format inside `body` is freeform markdown. The kickoff prompts include the project's preferred block templates.
+
+## Fallback — when the MCP client misbehaves
+
+If a Claude session can't reach the relay's MCP tools (transient SSE hiccup, MCP server failed to register, sandboxed network), use the shim:
+
+```bash
+# From any shell, with the relay running on 7331:
+python3 tools/relay/call.py read_messages '{"for":"pm"}'
+python3 tools/relay/call.py post_message '{"from":"dev-a","to":"pm","kind":"status","body":"shipped X"}'
+python3 tools/relay/call.py list_pending '{"for":"dev-b"}'
+```
+
+`call.ts` is the same surface in TypeScript (`bun run tools/relay/call.ts ...`) for when you want to script from a TS context. Both shims speak raw MCP over the SSE transport; output is the JSON-RPC response.
+
+The kickoff prompts reference `call.py` by path — if the in-Claude MCP client breaks mid-session, the dev can fall back to `Bash python3 tools/relay/call.py ...` and keep coordinating without restarting.
+
+## Where things live
+
+```
+docs/superpowers/coordination/
+├── RELAY.md                                  ← you are here
+├── <date>-pm-prompt.md                       generated by /multi-agent-kickoff
+├── <date>-dev-a-prompt.md
+├── <date>-dev-b-prompt.md
+├── <date>-dev-c-prompt.md                    (optional, 4-role mode)
+└── archive/                                  older kickoff sets
+
+tools/relay/
+├── start.sh                                  launcher (manual / tmux / kitty)
+├── server.ts                                 MCP server (HTTP/SSE on :7331)
+├── queue.ts                                  in-memory per-role FIFO
+├── queue.test.ts                             node:test — run with `bun test`
+├── call.py                                   Python MCP-client shim (fallback)
+├── call.ts                                   TypeScript MCP-client shim (fallback)
+├── package.json
+└── tsconfig.json
+```
+
+The launcher's prompt-discovery is `ls -t "$COORD_DIR"/*-<role>-prompt.md | head -1` — newest wins. To switch back to a previous kickoff set, either delete the newer files or move them under `archive/`.
+
+## Conventions
+
+- **Roles are fixed strings:** `pm`, `dev-a`, `dev-b`, `dev-c`. Adding a new role means editing `Role` in `queue.ts`, `KNOWN_ROLES`, the `enum` in `server.ts`'s tool schema, and the launcher.
+- **Worktree per dev:** each dev session works in its own git worktree on its own branch. Subagents must `cd` into the worktree first — the multi-agent-kickoff skill bakes this rule into the dev prompts (subagents have been known to commit to `main` if the worktree cwd is only set in a header).
+- **Branch naming follows the release train:** `feature/<release>-<dev>-<scope>`. PM owns the merge order; devs do not merge each other's branches.
+- **No squashing:** the project preserves git history as audit log (per `CLAUDE.md`). Devs commit small and often; PM coordinates rebases at integration time, not before.
+- **The user is not the router.** PM should issue directives directly to devs via the relay. The user steps in only for cross-stream design decisions or when PM explicitly escalates.
+
+## Troubleshooting
+
+- **"port 7331 is already in use"** — another relay is running. `kill $(lsof -ti:7331)`, then re-run `start.sh`.
+- **Launcher can't find a prompt** (`(none found)` in the printed paths) — `/multi-agent-kickoff` hasn't been run yet, or all generated prompts are under `archive/`. Re-run the skill.
+- **Dev session committing to `main` instead of its worktree** — its subagent prompts are missing the force-`cd` header. Regenerate the dev prompt via `/multi-agent-kickoff` (the skill bakes in the cd rule) or hand-edit the prompt to start with `cd <worktree-path>`.
+- **MCP tools don't show up in the Claude session** — restart the session. If it persists, fall back to `call.py`. If `call.py` also fails, check the relay log window for stack traces; the SSE transport sometimes wedges if a client disconnects ungracefully.
+- **`bun test` failing in `tools/relay/`** — relay tests use `node:test` via bun. Run from `tools/relay/`, not the repo root: `cd tools/relay && bun test`. Extension tests use vitest and live elsewhere; don't conflate.
+- **One dev session is silent** — check `python3 tools/relay/call.py list_pending '{"for":"<role>"}'` from any shell. If the dev's inbox has unread messages, they may have crashed or detached. Open the role's window and resume.
+
+## Caveats
+
+- **In-memory queue is dev-only.** Restart the relay = lose all queued messages. There is no persistence by design — coordination is meant to flow forward, not be replayable.
+- **No auth.** The relay binds to `localhost:7331` with no token. Don't expose the port; don't run on a shared machine.
+- **The relay is not a chat history.** `read_messages` drains the inbox. If you need to refer back to what was said, copy-paste into a session note or the PR description; don't expect the relay to remember.
+- **Context costs scale with session count.** Four parallel Claude sessions burn four context windows. Use this paradigm when the parallel speedup justifies the cost — for sequential work, one session is cheaper.
+
+## See also
+
+- `tools/relay/server.ts` — MCP tool definitions (`post_message`, `read_messages`, `list_pending`) and their schemas.
+- `tools/relay/queue.ts` — `Role` / `MessageKind` types; the canonical per-role-inbox semantics.
+- `docs/superpowers/coordination/<date>-pm-prompt.md` — the latest PM kickoff (the actual operational instructions PM runs by).
+- The `multi-agent-kickoff` skill — generates the kickoff prompt set.

docs/superpowers/coordination/architecture-review-dev-a-prompt.md

@@ -0,0 +1,165 @@
+# Dev A Kickoff Prompt — Architecture Review (Rust core)
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior reviewer** owning the Rust core review for Relicario's whole-codebase architecture audit (2026-05-04). You are one of three dev reviewers (A/B/C) reporting to a PM in another terminal. Your scope is `crates/relicario-core/` and its tests.
+
+The user wants to be able to **read and understand this codebase and learn by tinkering**, even though they don't know Rust. Your review lens is therefore *architectural clarity for a smart newcomer*, not just correctness. Naming, layering, comments at non-obvious boundaries, dead code, leaky abstractions, opportunities to simplify — all in scope.
+
+## Setup
+
+- Working directory: `/home/alee/Sources/relicario`
+- Stay on `main`. **Do not check out branches, do not create worktrees, do not modify code.** This is a review-only role.
+- Today: 2026-05-04. Project rules in `CLAUDE.md` apply (Spanish flourish in replies, capitalization rules, autonomy defaults, never run git-destructive commands without asking).
+- The working tree has uncommitted changes (manifest bumps, vault tweaks, relay tooling). Run `git status` once for awareness; otherwise review HEAD as the canonical state. Flag anything weird about the uncommitted state in your notes if it suggests an in-flight architectural issue.
+
+## 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-a"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-a"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each pass: `read_messages(for="dev-a")`. After emitting any status/question block: `post_message(from="dev-a", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session (the relay server was not running when your session opened), use the Python shim:
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-a","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-a"}'
+```
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/specs/2026-04-11-relicario-design.md` — the foundational spec (threat model, crypto pipeline, format)
+3. `crates/relicario-core/src/lib.rs` — public API surface
+4. Then walk every file in `crates/relicario-core/src/` and `crates/relicario-core/tests/` deliberately. The point is depth, not coverage rate.
+
+You are NOT required to read the other crates (DEV-B owns them) or the extension (DEV-C owns it). If something in core only makes sense by looking at how it's consumed, file a `## QUESTION TO PM` rather than crossing the boundary.
+
+## Your scope and boundaries
+
+**In scope:**
+- `crates/relicario-core/src/*.rs` — every file
+- `crates/relicario-core/tests/*.rs` — integration tests
+- `crates/relicario-core/Cargo.toml` — dependencies and features
+
+**Out of scope (other reviewers' territory):**
+- `crates/relicario-cli/`, `crates/relicario-server/`, `crates/relicario-wasm/` — DEV-B
+- `extension/`, `tools/relay/` — DEV-C
+- `docs/` outside the spec link above
+
+**Hard rules:**
+- **No code changes.** Not even trivial doc-comment fixes. Surface in your notes; the user decides what to act on after PM synthesis.
+- No git commits, no branch creation, no destructive ops.
+- If you spend more than ~30 minutes on one file, post a status update with what you've found so far and move on. Cover the whole core, then return for depth.
+
+## What to look for (review lens)
+
+Walk every file in `crates/relicario-core/src/` and assess:
+
+1. **Architectural clarity for a Rust newcomer.** Would a smart person who knows another language be able to follow this? Where are the surprise idioms, the silent assumptions, the "you have to know Rust to read this" cliffs?
+2. **Naming.** Are types, functions, fields named for what they mean? Any cryptic two-letter abbreviations? Names that lie about what they do?
+3. **Layering.** Is `relicario-core` actually platform-agnostic (no fs, no net, no git)? Any leaks? Any types that pretend to be pure data but hide I/O?
+4. **API ergonomics.** Are public types easy to construct and consume? Any footguns (e.g. easy-to-misuse nonces, builders that compile but corrupt)? Are errors descriptive?
+5. **Crypto correctness invariants.** Argon2id params, XChaCha20-Poly1305 nonce uniqueness, key zeroization, AAD usage, version/format gates. Are these enforced by types or by convention? If by convention, is that convention obvious?
+6. **DCT steganography (`imgsecret.rs`).** This is the most magical file. Does it have enough explanation for a reader to map code to spec section?
+7. **Comments.** Where there ARE comments, do they explain *why* (good) or *what* (rot)? Where they're missing, is it because the code is self-explanatory, or because nobody got around to it?
+8. **Tests.** Do they cover happy path AND format/crypto edge cases? Are test helpers well-named? Any dead test cases?
+9. **Dead code, unused features, abandoned experiments.** Use `cargo clippy -p relicario-core` and `cargo +nightly udeps -p relicario-core 2>/dev/null || true` if you have time, but mostly: just notice things.
+10. **Simplification opportunities.** Three similar lines is better than premature abstraction; but six similar match arms might want a helper. Note candidates; don't insist.
+
+You may run `cargo build -p relicario-core`, `cargo test -p relicario-core`, `cargo clippy -p relicario-core` to confirm assumptions, but the review is not gated on green — it's gated on understanding.
+
+## Output
+
+Write your findings to `docs/superpowers/reviews/2026-05-04-dev-a-notes.md`. Create the `reviews/` directory with `mkdir -p` if it doesn't exist.
+
+Structure:
+
+```markdown
+# DEV-A Architecture Review Notes — Rust Core
+
+## Summary
+3-5 sentences: what's the overall architectural shape, what's the strongest part, what's the weakest part.
+
+## Findings (prioritized: P1 = address before more code lands, P2 = soon, P3 = nice-to-have)
+
+### P1 — <short title>
+**File(s):** `crates/relicario-core/src/foo.rs:123`
+**Observation:** <what you saw>
+**Why it matters:** <especially for a Rust newcomer reading the code>
+**Suggested direction:** <one or two sentences; do NOT rewrite — just point>
+
+(repeat for each finding, P1 first, then P2, then P3)
+
+## File-by-file walk (one paragraph each)
+For every file in core, a paragraph: what it does, what's clear, what's not. Brief is fine — this is the appendix.
+
+## Beginner-friendliness assessment
+A paragraph: how readable is this crate for a competent dev who has never written Rust? What single change would help most?
+```
+
+The PM will synthesize your notes (plus DEV-B's and DEV-C's) into the final review doc.
+
+## Coordination protocol
+
+**Before each major pass** (e.g. starting file walk, switching to findings write-up): call `read_messages(for="dev-a")`.
+
+**Status update format** (post via `post_message(from="dev-a", to="pm", kind="status", body="...")`, also print here):
+
+```
+## STATUS UPDATE — DEV-A
+Time: <iso8601>
+Phase: SETUP | READING | WALKING | WRITING | REVIEW-COMPLETE
+Files covered: <e.g. 8/19 src + 0/7 tests>
+Findings so far: <P1: N, P2: N, P3: N>
+Notes: <≤3 sentences>
+```
+
+**Question format** (when you need PM input — e.g. you're unsure if something is in scope, or you suspect a cross-cutting issue):
+
+```
+## QUESTION TO PM — DEV-A
+Time: <iso8601>
+Context: <what file, what concern>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no
+```
+
+You'll receive `## DIRECTIVE TO DEV-A` blocks from the PM via relay. Acknowledge and act.
+
+## Authority
+
+You don't need PM permission to:
+- Decide reading order within scope
+- Decide whether a finding is P1/P2/P3
+- Use subagents to parallelize file reads (force-cd into `/home/alee/Sources/relicario` per project memory rule — every subagent prompt MUST start with `cd /home/alee/Sources/relicario` so the subagent doesn't wander)
+- Run `cargo` commands (build, test, clippy) read-only
+
+You **do** escalate to PM when:
+- You suspect an issue that crosses into DEV-B or DEV-C territory
+- A finding is so severe (e.g. exploitable crypto bug) that it deserves immediate attention
+- You're tempted to fix something inline (don't — escalate and let the PM/user decide)
+
+## REVIEW-COMPLETE criteria
+
+Before posting `Phase: REVIEW-COMPLETE`:
+- [ ] Every file in `crates/relicario-core/src/` walked
+- [ ] Every file in `crates/relicario-core/tests/` walked
+- [ ] Notes written to `docs/superpowers/reviews/2026-05-04-dev-a-notes.md`
+- [ ] At least one paragraph in the beginner-friendliness assessment
+- [ ] No P1 finding left vague — every P1 has a file:line and a suggested direction
+
+## First action
+
+1. Call `read_messages(for="dev-a")`.
+2. Read the project rules and the spec.
+3. Skim `lib.rs` and the file list under `crates/relicario-core/src/`.
+4. Emit a `## STATUS UPDATE` with `Phase: SETUP` confirming spec absorbed and file count to walk.
+5. Begin the file walk. Save findings as you go.

docs/superpowers/coordination/architecture-review-dev-b-prompt.md

@@ -0,0 +1,198 @@
+# Dev B Kickoff Prompt — Architecture Review (Rust consumers: CLI, server, WASM)
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior reviewer** owning the Rust consumer-layer review for Relicario's whole-codebase architecture audit (2026-05-04). You are one of three dev reviewers (A/B/C) reporting to a PM in another terminal. Your scope is the three Rust crates that consume `relicario-core`: `relicario-cli`, `relicario-server`, and `relicario-wasm`.
+
+The user wants to be able to **read and understand this codebase and learn by tinkering**, even though they don't know Rust. Your review lens is therefore *architectural clarity for a smart newcomer*, not just correctness. Naming, layering, where business logic actually lives, comments at non-obvious boundaries, dead code, leaky abstractions, opportunities to simplify — all in scope.
+
+## Setup
+
+- Working directory: `/home/alee/Sources/relicario`
+- Stay on `main`. **Do not check out branches, do not create worktrees, do not modify code.** This is a review-only role.
+- Today: 2026-05-04. Project rules in `CLAUDE.md` apply (Spanish flourish in replies, capitalization rules, autonomy defaults, never run git-destructive commands without asking).
+- The working tree has uncommitted changes (manifest bumps, vault tweaks, relay tooling). Run `git status` once for awareness; otherwise review HEAD as the canonical state. Flag anything weird about the uncommitted state in your notes if it suggests an in-flight architectural issue.
+
+## 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-b"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-b"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each pass: `read_messages(for="dev-b")`. After emitting any status/question block: `post_message(from="dev-b", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-b","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-b"}'
+```
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/specs/2026-04-11-relicario-design.md` — the foundational spec
+3. `crates/relicario-core/src/lib.rs` — **just** the public API surface (you do NOT review core; that's DEV-A — but you must understand what your crates depend on)
+4. Then walk each consumer crate deliberately:
+   - `crates/relicario-cli/src/main.rs` then the rest of `crates/relicario-cli/src/` and `crates/relicario-cli/tests/`
+   - `crates/relicario-server/src/main.rs` and `crates/relicario-server/tests/`
+   - `crates/relicario-wasm/src/lib.rs` then `crates/relicario-wasm/src/`
+
+You are NOT required to read deeply into `relicario-core` internals (DEV-A owns them) or the extension TypeScript (DEV-C owns it). The WASM crate is your boundary with DEV-C; review it from the Rust side, and trust DEV-C to review it from the JS side.
+
+## Your scope and boundaries
+
+**In scope:**
+- `crates/relicario-cli/` — entire crate (src + tests + Cargo.toml)
+- `crates/relicario-server/` — entire crate
+- `crates/relicario-wasm/` — entire crate
+
+**Out of scope (other reviewers' territory):**
+- `crates/relicario-core/` internals — DEV-A
+- `extension/`, `tools/relay/` — DEV-C
+- `docs/` outside the spec link above
+
+**Hard rules:**
+- **No code changes.** Not even trivial. Surface in notes.
+- No git commits, no branch creation, no destructive ops.
+- If you spot a core-internal issue while you're poking at it, file a `## QUESTION TO PM` so DEV-A can be alerted; don't expand your own scope.
+
+## What to look for (review lens)
+
+For each crate, assess:
+
+### relicario-cli (the user-facing binary)
+
+1. **Command surface.** Does the clap structure match the spec's intended UX? Are subcommand names and flags discoverable? Any flags that exist but don't do what their name suggests?
+2. **Where business logic lives.** `relicario-core` should be doing the work; the CLI should be glue (parse args → call core → format output). Any place where the CLI has logic that should be in core?
+3. **Session handling.** `session.rs` holds `UnlockedVault` with the master key in `Zeroizing`. Are session lifetimes clear? Any path where the key outlives its window?
+4. **Filesystem and git.** The CLI is the only place that touches fs and shells out to git. Is `helpers.rs` doing this cleanly? Any path-handling bugs? Any place where `git_command` is invoked with insufficient error mapping?
+5. **Tests.** Integration tests under `crates/relicario-cli/tests/` — do they test the CLI surface or just re-test core? Are fixtures synthetic (per project convention)? Any mocked filesystem leaks?
+6. **Error UX.** When something goes wrong, does the user get a useful message, or does a `RelicarioError` get printed raw?
+
+### relicario-server (Git pre-receive hook)
+
+1. **Surface.** Two subcommands (`verify-commit`, `generate-hook`). Is the contract with Git clear? Does `generate-hook` produce a hook that's actually correct?
+2. **Trust model.** This is the only piece that runs server-side. Does it correctly enforce "the server only sees opaque ciphertext" — i.e. it never tries to decrypt, only verifies signatures/format?
+3. **Failure modes.** What happens if a malformed commit lands? Are rejections actionable for the pushing client?
+
+### relicario-wasm (extension bridge)
+
+1. **JS surface.** What does `#[wasm_bindgen]` actually expose? Is the API minimal and well-typed (`SessionHandle` opaque), or does it leak Rust internals?
+2. **Session handle pattern.** `SessionHandle` → `Zeroizing<[u8;32]>` indirection. Is the lifetime story sound? What happens when JS drops the handle?
+3. **Error mapping.** Rust errors → JS exceptions. Are messages useful on the JS side, or do they just say "internal error"?
+4. **Build target.** Does `cargo build -p relicario-wasm --target wasm32-unknown-unknown` succeed clean? Any feature flags that look gnarly?
+5. **Boundary with DEV-C.** What does the TS side need to know that isn't documented in the WASM crate? Note these for DEV-C cross-reference.
+
+### Cross-cutting (all three crates)
+
+1. **Naming.** Same questions as DEV-A.
+2. **Comments.** Same.
+3. **Layering.** Does each crate import only what it should? Any place where a consumer crate is reaching past `relicario-core`'s public API?
+4. **Dead code, abandoned features.** Notice things.
+5. **Simplification.** Where would a Rust newcomer trip? What's the single change that would help most?
+
+You may run `cargo build`, `cargo test -p relicario-cli`, `cargo test -p relicario-server`, `cargo build -p relicario-wasm --target wasm32-unknown-unknown`, `cargo clippy --workspace`. The review is not gated on green; it's gated on understanding.
+
+## Output
+
+Write your findings to `docs/superpowers/reviews/2026-05-04-dev-b-notes.md`. Create the `reviews/` directory with `mkdir -p` if it doesn't exist.
+
+Structure:
+
+```markdown
+# DEV-B Architecture Review Notes — Rust Consumers (CLI, Server, WASM)
+
+## Summary
+3-5 sentences spanning all three crates: what's the shape of the consumer layer, where is it strongest, where is it weakest.
+
+## Findings (prioritized: P1 / P2 / P3)
+
+Group by crate, P1 first within each:
+
+### relicario-cli
+#### P1 — <short title>
+**File(s):** `crates/relicario-cli/src/main.rs:456`
+**Observation:** ...
+**Why it matters:** ...
+**Suggested direction:** ...
+
+### relicario-server
+...
+
+### relicario-wasm
+...
+
+### Cross-cutting
+Findings that span more than one crate (e.g. an error-handling pattern that's inconsistent across all three).
+
+## File-by-file walk
+One paragraph per file across all three crates. Appendix-grade detail.
+
+## Boundary notes for DEV-C
+What about the WASM JS surface should DEV-C double-check from the TypeScript side?
+
+## Beginner-friendliness assessment
+A paragraph: how readable are these crates for a competent dev who has never written Rust? What single change would help most?
+```
+
+## Coordination protocol
+
+**Before each major pass:** `read_messages(for="dev-b")`.
+
+**Status update format** (post via `post_message(from="dev-b", to="pm", kind="status", body="...")`, also print here):
+
+```
+## STATUS UPDATE — DEV-B
+Time: <iso8601>
+Phase: SETUP | READING | WALKING-CLI | WALKING-SERVER | WALKING-WASM | WRITING | REVIEW-COMPLETE
+Crates covered: <e.g. cli ✓ / server ✓ / wasm ⏳>
+Findings so far: <P1: N, P2: N, P3: N>
+Notes: <≤3 sentences>
+```
+
+**Question format:**
+
+```
+## QUESTION TO PM — DEV-B
+Time: <iso8601>
+Context: <what crate, what concern>
+Options: <A / B / C>
+Recommended: <pick + one-sentence rationale>
+Blocker: yes | no
+```
+
+You'll receive `## DIRECTIVE TO DEV-B` blocks from the PM via relay. Acknowledge and act.
+
+## Authority
+
+You don't need PM permission to:
+- Decide reading order within scope
+- Decide P1/P2/P3 prioritization
+- Use subagents to parallelize crate reads (force-cd into `/home/alee/Sources/relicario` per project memory rule — every subagent prompt MUST start with `cd /home/alee/Sources/relicario`)
+- Run `cargo` commands (build, test, clippy) read-only
+
+You **do** escalate to PM when:
+- An issue spans into DEV-A's core or DEV-C's TS territory
+- A finding is severe enough to deserve immediate attention
+- You're tempted to fix something inline (don't)
+
+## REVIEW-COMPLETE criteria
+
+- [ ] Every src file in cli/server/wasm walked
+- [ ] Every test file walked
+- [ ] Notes written to `docs/superpowers/reviews/2026-05-04-dev-b-notes.md`
+- [ ] Boundary-notes section for DEV-C populated
+- [ ] Every P1 has a file:line and suggested direction
+
+## First action
+
+1. Call `read_messages(for="dev-b")`.
+2. Read project rules and spec.
+3. Skim `relicario-core/src/lib.rs` for the public API your crates depend on.
+4. Emit a `## STATUS UPDATE` with `Phase: SETUP` confirming setup, listing crates+file counts you'll walk.
+5. Begin the walk: cli first, then server, then wasm. Save findings as you go.

docs/superpowers/coordination/architecture-review-dev-c-prompt.md

@@ -0,0 +1,214 @@
+# Dev C Kickoff Prompt — Architecture Review (TypeScript: extension + relay tooling)
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior reviewer** owning the TypeScript review for Relicario's whole-codebase architecture audit (2026-05-04). You are one of three dev reviewers (A/B/C) reporting to a PM in another terminal. Your scope is the browser extension (`extension/`) and the dev tooling (`tools/relay/`).
+
+The user wants to be able to **read and understand this codebase and learn by tinkering**, including the parts they're more comfortable with (TS). Your review lens is therefore *architectural clarity*, with extra attention to:
+- Parity with the CLI (per project memory: CLI/extension parity is a design philosophy — never ship "CLI first, extension follow-up")
+- The popup ↔ service-worker ↔ content script boundary
+- The WASM bridge from the JS side
+- Naming, layering, dead code, simplification opportunities
+
+## Setup
+
+- Working directory: `/home/alee/Sources/relicario`
+- Stay on `main`. **Do not check out branches, do not create worktrees, do not modify code.** This is a review-only role.
+- Today: 2026-05-04. Project rules in `CLAUDE.md` apply (Spanish flourish in replies, capitalization, autonomy defaults, never run git-destructive commands without asking).
+- The working tree has uncommitted changes — note especially: `extension/manifest.json`, `extension/manifest.firefox.json`, `extension/package*.json`, `extension/src/shared/glyphs.ts` and `__tests__/glyphs.test.ts`, `extension/src/vault/vault.css`, `extension/src/vault/vault.ts`, `tools/relay/queue.ts`, `tools/relay/server.ts`, plus untracked `tools/relay/call.py`, `tools/relay/call.ts`, `.gitea_env_vars`. Run `git status` and `git diff` once. Decide whether the uncommitted diff is "in flight, ignore for review" or "already part of the architecture and worth flagging" — note your call in the notes file.
+
+## Relay server
+
+A message-bus MCP server is running on `localhost:7331`. Note that you are reviewing this server itself — but for coordination, you still use it. You have three native tools:
+
+- `post_message(from, to, kind, body)` — push a message; your `from` is always `"dev-c"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-c"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each pass: `read_messages(for="dev-c")`. After emitting any status/question block: `post_message(from="dev-c", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-c","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-c"}'
+```
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules (note especially the CLI/extension parity rule)
+2. `docs/superpowers/specs/2026-04-11-relicario-design.md` — foundational spec (skim, focus on the parts that touch the extension)
+3. `extension/package.json`, `extension/manifest.json`, `extension/manifest.firefox.json` — extension shape
+4. `extension/src/wasm.d.ts` and `extension/src/__stubs__/relicario_wasm.stub.ts` — your WASM boundary
+5. Then walk in this order:
+   - `extension/src/service-worker/` (the trusted core of the extension)
+   - `extension/src/shared/` (shared utilities)
+   - `extension/src/popup/` (popup UI)
+   - `extension/src/vault/` (full-tab vault UI)
+   - `extension/src/content/` (content scripts: detector, fill, capture)
+   - `extension/src/setup/` (setup wizard)
+   - `tools/relay/` (the dev-only message bus, separate concern)
+
+You are NOT required to read deeply into the Rust crates — DEV-A owns core, DEV-B owns CLI/server/WASM. From your side, you only need to understand the WASM JS surface that the extension consumes.
+
+## Your scope and boundaries
+
+**In scope:**
+- `extension/` — entire tree (excluding `node_modules/` and built artifacts)
+- `tools/relay/` — entire tree (excluding `node_modules/`)
+- The WASM JS surface as consumed from TS (`wasm.d.ts`, the stub, every call site)
+
+**Out of scope (other reviewers' territory):**
+- `crates/relicario-core/` internals — DEV-A
+- `crates/relicario-cli/`, `crates/relicario-server/`, `crates/relicario-wasm/` Rust internals — DEV-B
+- `docs/` outside the spec link above
+
+**Hard rules:**
+- **No code changes.** Not even trivial. Surface in notes.
+- No git commits, no branch creation, no destructive ops.
+- If you find a Rust-side issue while looking at the WASM boundary, file a `## QUESTION TO PM` so DEV-B can be alerted; don't expand scope.
+
+## What to look for (review lens)
+
+### Extension architecture
+
+1. **Layering — popup vs service-worker vs content vs vault tab.** Each has a clear role; are the lines clean? Any place where popup is doing trusted work that should live in the service-worker, or vice versa? Any direct WASM calls in content scripts (a security smell)?
+2. **Message-passing.** `extension/src/shared/messages.ts` and the service-worker router — is the typing tight? Are there messages that exist but are never sent, or sent but never handled?
+3. **WASM session handle.** The session handle is a number (an opaque pointer into the Rust session map). Where does it live? Who creates it, who drops it? Is the locked/unlocked state machine obvious from the code?
+4. **CLI/extension parity.** Walk through the CLI's commands (skim `crates/relicario-cli/src/main.rs` for the surface only) and check: for every CLI capability, does the extension have an equivalent UI path? If not, is that a deliberate choice or an oversight? This is a project-philosophy lens — flag any gap as a P1 architectural issue.
+5. **Component organization.** `extension/src/popup/components/` has settings, item-form, item-list, fields, generator-panel, etc. Are component boundaries clean? Any teardown leaks (the project has had teardown bugs before — see commit `ddfb95d` and `8baef5b`)?
+6. **Storage and state.** What lives in `chrome.storage.local`? In `chrome.storage.session`? Any sensitive data persisted that shouldn't be? Any cleartext secrets in DOM that survive teardown?
+7. **Settings architecture.** v0.5.1 just landed a unified left-nav settings (commit `bd6a301`). Is the new structure clean, or are there leftover bits from the old structure?
+
+### Vault tab vs popup
+
+8. **Two render targets, one component.** Settings (and possibly other components) render into both the popup and the vault tab. Is the rendering target abstracted, or are there `if (in popup)` branches? Note any pattern that breaks down.
+9. **Vault tab session timeout.** There's been work on this (per project memory). Is the session-timer logic in `service-worker/session-timer.ts` legible?
+
+### Shared utilities
+
+10. **`shared/types.ts`, `shared/messages.ts`, `shared/state.ts`.** Are these doing what their names suggest? Any `any`-leaking? Any types that should be generated from the WASM bindings instead of hand-maintained?
+11. **`shared/glyphs.ts`.** Per project rules, no inline emoji — all UI glyphs go through this. Is the abstraction tight? (Recent uncommitted edits here — note your read.)
+
+### Relay tooling (`tools/relay/`)
+
+12. **Single-purpose dev tool.** It's the message bus you're using right now. Is it appropriately isolated from the rest of the codebase (no cross-imports, separate package.json)? Is the role enum (`pm`, `dev-a`, `dev-b`, `dev-c`) maintained in lockstep across `queue.ts`, `server.ts`, and any client (`call.py`, `call.ts`)?
+13. **Untracked `call.py` and `call.ts`.** What are these for? Are they the documented fallback shims? Should they be tracked?
+
+### Cross-cutting
+
+14. **Naming.** Are TS names crisp? Any that lie about behavior?
+15. **Dead code.** `bun run build` cleanly? Any imports unused? Any components rendered nowhere?
+16. **Simplification.** Where would a beginner trip? What's the single change that would help most?
+17. **Tests.** `extension/src/**/__tests__/*.test.ts` — meaningful coverage, or smoke-only?
+
+You may run `bun run build`, `bun run build:firefox`, `bun run test`, `cd tools/relay && bun test`, `bun run lint` if available. Review is not gated on green; it's gated on understanding.
+
+## Output
+
+Write your findings to `docs/superpowers/reviews/2026-05-04-dev-c-notes.md`. Create the `reviews/` directory with `mkdir -p` if it doesn't exist.
+
+Structure:
+
+```markdown
+# DEV-C Architecture Review Notes — TypeScript (Extension + Relay)
+
+## Summary
+3-5 sentences: shape of the TS layer, strongest part, weakest part. Note the CLI/extension parity status.
+
+## Findings (prioritized: P1 / P2 / P3)
+
+Group by area, P1 first within each:
+
+### Extension — service-worker
+### Extension — popup + components
+### Extension — vault tab
+### Extension — content scripts
+### Extension — setup
+### Extension — shared utilities
+### WASM boundary (JS side)
+### Relay tooling
+### CLI/extension parity gaps
+### Cross-cutting
+
+(use the same finding format as DEV-A/DEV-B: file:line, observation, why it matters, suggested direction)
+
+## File-by-file walk
+One paragraph per file (or per small group of related files). Appendix-grade.
+
+## CLI/extension parity table
+| CLI capability | Extension equivalent | Notes |
+|----------------|----------------------|-------|
+| ...            | ✓ or ✗ or partial    | ...   |
+
+## Boundary notes for DEV-B
+What about the WASM JS surface (or session handle, error mapping) does DEV-B need to double-check from the Rust side?
+
+## Beginner-friendliness assessment
+A paragraph for the TS side specifically.
+
+## Uncommitted-state read
+A short paragraph: what's in the working tree but not in HEAD, and is any of it architecturally relevant?
+```
+
+## Coordination protocol
+
+**Before each major pass:** `read_messages(for="dev-c")`.
+
+**Status update format** (post via `post_message(from="dev-c", to="pm", kind="status", body="...")`, also print here):
+
+```
+## STATUS UPDATE — DEV-C
+Time: <iso8601>
+Phase: SETUP | READING | WALKING-SW | WALKING-POPUP | WALKING-VAULT | WALKING-CONTENT | WALKING-SETUP | WALKING-SHARED | WALKING-RELAY | WRITING | REVIEW-COMPLETE
+Areas covered: <checklist>
+Findings so far: <P1: N, P2: N, P3: N>
+Notes: <≤3 sentences>
+```
+
+**Question format:**
+
+```
+## QUESTION TO PM — DEV-C
+Time: <iso8601>
+Context: <what file, what concern>
+Options: <A / B / C>
+Recommended: <pick + one-sentence rationale>
+Blocker: yes | no
+```
+
+You'll receive `## DIRECTIVE TO DEV-C` blocks from the PM via relay. Acknowledge and act.
+
+## Authority
+
+You don't need PM permission to:
+- Decide reading order within scope
+- Decide P1/P2/P3 prioritization
+- Use subagents to parallelize area reads (force-cd into `/home/alee/Sources/relicario` per project memory rule — every subagent prompt MUST start with `cd /home/alee/Sources/relicario`)
+- Run `bun` and `cargo` commands read-only
+
+You **do** escalate to PM when:
+- A finding spans into DEV-A's core or DEV-B's Rust crates
+- A finding is severe (e.g. a real security smell, leaked secret in storage)
+- You're tempted to fix something inline (don't)
+
+## REVIEW-COMPLETE criteria
+
+- [ ] Every TS file under `extension/src/` walked (including `__tests__`)
+- [ ] Every TS file under `tools/relay/` walked
+- [ ] Notes written to `docs/superpowers/reviews/2026-05-04-dev-c-notes.md`
+- [ ] CLI/extension parity table populated (every CLI capability either ✓, ✗, or partial)
+- [ ] Boundary-notes section for DEV-B populated
+- [ ] Uncommitted-state read paragraph written
+- [ ] Every P1 has a file:line and suggested direction
+
+## First action
+
+1. Call `read_messages(for="dev-c")`.
+2. Read project rules and spec.
+3. Look at `manifest.json` and skim `wasm.d.ts` so you know your boundaries.
+4. Run `git status` and `git diff` once for awareness of uncommitted state.
+5. Emit a `## STATUS UPDATE` with `Phase: SETUP` confirming setup, listing area buckets you'll walk.
+6. Begin the walk: service-worker first, then shared, then popup, then vault, then content, then setup, then relay tooling. Save findings as you go.

docs/superpowers/coordination/architecture-review-followup-dev-a-prompt.md

@@ -0,0 +1,200 @@
+# Dev A Kickoff Prompt — Architecture Review Followup, Stream A (Security & Docs Polish)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement the plan task-by-task once it lands.
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior developer** owning Stream A for the Relicario architecture-review-followup work. Stream A is the small, security-flavored quick-win PR that goes first: SessionHandle Drop semantics, the matching JS-side audit, recovery_qr.rs documentation density, and the relay launcher fix for the dev-c fourth window. Goal is **under-a-day, all-S effort, ships first**.
+
+A PM in another terminal coordinates you with two other senior devs. With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. **Your plan does not exist yet.** The PM is drafting it as their first action. Set up your worktree, post acknowledgement, and wait for the PM's `PROCEED` directive containing the plan path before starting Task 1.
+
+## Setup (do this first)
+
+```bash
+cd /home/alee/Sources/relicario
+git fetch
+git worktree add /home/alee/Sources/relicario.arch-followup-stream-a -b feature/arch-followup-stream-a-security-polish
+cd /home/alee/Sources/relicario.arch-followup-stream-a
+pwd  # should print /home/alee/Sources/relicario.arch-followup-stream-a
+```
+
+**Note on `git pull`:** main has uncommitted polish changes from in-flight post-v0.5.1 work. The setup above branches from local main HEAD without pulling, which is intentional. If `git fetch` reveals new upstream commits, surface them to the PM before incorporating.
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario.arch-followup-stream-a`**. Every subagent prompt MUST begin with `cd /home/alee/Sources/relicario.arch-followup-stream-a` (project memory rule — without the force-cd, subagents may commit to main).
+
+Today: 2026-05-04. Project rules in `CLAUDE.md` apply (Spanish flourish in replies, capitalize "Relicario", default to "yes"/recommended, never run git-destructive commands without asking).
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (your scope is **P1.1, the JS free-swallow fix, P1.7, P1.8 only**)
+3. `docs/superpowers/reviews/2026-05-04-dev-a-notes.md` — full DEV-A reviewer notes (Rust core; covers recovery_qr.rs context)
+4. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — full DEV-B reviewer notes (covers SessionHandle context on the WASM side)
+5. `docs/superpowers/reviews/2026-05-04-dev-c-notes.md` — full DEV-C reviewer notes (covers the JS free-swallow + start.sh launcher context)
+6. **Your plan (will land at):** `docs/superpowers/specs/2026-05-04-security-polish-design.md` — read once the PM directs you to PROCEED
+
+## Execution mode
+
+Use **superpowers:subagent-driven-development**. Fresh subagent per task, two-stage review between tasks. Every subagent prompt MUST start with:
+```
+cd /home/alee/Sources/relicario.arch-followup-stream-a
+```
+…before any other instruction. This is non-negotiable per project memory.
+
+## Your scope and boundaries
+
+**In scope:**
+- P1.1 — `impl Drop for SessionHandle` in `crates/relicario-wasm/src/lib.rs` (and `session.rs`); `wasm-bindgen-test` for construct → drop → confirm `SESSIONS` registry empty; audit every `.free()` callsite under `extension/src/` to confirm `wasm.lock(handle)` happens first regardless
+- JS partner fix at `extension/src/service-worker/session.ts:26` — remove the `try { current.free() }` swallow; let exceptions propagate or log + counter
+- P1.7 — `crates/relicario-core/src/recovery_qr.rs` documentation pass to match `crypto.rs` / `imgsecret.rs` / `backup.rs` / `tar_safe.rs` density
+- P1.8 — `tools/relay/start.sh:80` launcher fix for the dev-c fourth window (the queue.test.ts assertion is already fixed in `061facd`; only the launcher line remains)
+
+**Out of scope (other DEVs own these):**
+- P1.2, P1.3, P1.10 + the in-scope CLI P2s — DEV-B (Stream B)
+- P1.4, P1.5, P1.6, P1.9 + the in-scope extension P2s — DEV-C (Stream C)
+- Any other P2/P3 not listed in your plan
+- The 8 "Open architectural decisions" at the bottom of the synthesis — those are user-judgement calls
+
+If you trip over an out-of-scope issue or a new bug while doing your work, file a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- **P1.1 is defense-in-depth crypto.** The `wasm-bindgen-test` covering construct → drop → registry-empty is a required acceptance gate. Do not skip or weaken it.
+- **The `.free()` callsite audit is part of P1.1.** Every callsite under `extension/src/` must be checked to confirm `wasm.lock(handle)` is called before `.free()`. Document the audit results in the PR.
+- **Do not remove the JS free-swallow before `impl Drop` lands.** The order matters: Rust fix first (so `.free()` becomes meaningful cleanup), JS swallow removal second (so failures surface).
+- **`recovery_qr.rs` docs must match the existing core standard.** Multi-paragraph module-level `//!` rationale, ASCII diagram of the 109-byte layout, doc-comments on the four public functions, comment or `const` for the `production_params()` divergence. Read `crypto.rs` and `backup.rs` first to absorb the tone.
+- **Test-only Argon2id params stay fast** (m=256, t=1, p=1) per project convention.
+- Synthetic JPEG fixtures only — no binary blobs in the test suite (project rule).
+- Do not merge your branch to main. The PM owns merges.
+- Do not push `--force` or run `git reset --hard`. Per `CLAUDE.md`: ask first.
+
+## 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-a"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-a"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-a")`. After emitting any status/question block: `post_message(from="dev-a", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-a","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-a"}'
+```
+
+## Coordination protocol
+
+You are one of four terminals. Before starting each task, call `read_messages(for="dev-a")` to drain your inbox.
+
+When posting a status update, call `post_message(from="dev-a", to="pm", kind="status", body="...")` with the body:
+
+```
+## STATUS UPDATE — DEV-A
+Time: <iso8601 like 2026-05-04T14:30:00-07:00>
+Branch: feature/arch-followup-stream-a-security-polish
+Task: <number / short name>
+Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
+Last commit: <short sha + first line of message>
+Tests: <green | red (which failed) | N/A>
+Notes: <anything PM needs to know — keep to 3 sentences max>
+```
+
+**When you need PM input mid-task:**
+```
+## QUESTION TO PM — DEV-A
+Time: <iso8601>
+Context: <what task, what decision point>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no
+```
+
+**You'll receive:** `## DIRECTIVE TO DEV-A` blocks from the PM. The first one will say `Action: PROCEED` with the plan path once the PM has drafted it. Acknowledge and start Task 1.
+
+## Authority within the plan
+
+You don't need PM permission to:
+- Execute task-to-task per the plan once you have it
+- Make implementation decisions consistent with the plan and synthesis
+- Write tests, refactor your own code, fix bugs you introduce
+- Push commits to your feature branch
+
+You **do** escalate to PM when:
+- A scope question outside the plan
+- A test you can't make green after honest debugging (don't fudge — debug)
+- A discovered bug not in your plan
+- Anything destructive (per CLAUDE.md)
+- Before opening the PR for review
+
+## Final steps before REVIEW-READY
+
+Run the project's full validation:
+
+```bash
+cd /home/alee/Sources/relicario.arch-followup-stream-a
+cargo test
+cargo build -p relicario-wasm --target wasm32-unknown-unknown
+cd extension && bun run test && bun run build && cd ..
+cd tools/relay && bun test && cd ../..
+```
+
+All four must be green. The wasm-bindgen-test for SessionHandle Drop is the headline acceptance.
+
+Then push and open the PR:
+
+```bash
+git push -u origin feature/arch-followup-stream-a-security-polish
+gh pr create --base main --head feature/arch-followup-stream-a-security-polish \
+  --title "fix(security/docs): SessionHandle Drop + free-swallow + recovery_qr docs + dev-c launcher (Stream A)" \
+  --body "$(cat <<'EOF'
+## Summary
+
+Stream A of the architecture-review-followup. Small security-flavored polish PR addressing four findings from the 2026-05-04 audit:
+
+- **P1.1** — `impl Drop for SessionHandle` so `.free()` becomes a real cleanup safety net (Rust fix); `wasm-bindgen-test` for construct → drop → registry empty; audit of every `.free()` callsite under `extension/src/`
+- **JS free-swallow** — removed `try { current.free() }` at `extension/src/service-worker/session.ts:26` so failures propagate
+- **P1.7** — `crates/relicario-core/src/recovery_qr.rs` brought up to the documentation density of `crypto.rs` / `backup.rs` / `tar_safe.rs`
+- **P1.8** — `tools/relay/start.sh:80` launcher fix for the dev-c fourth window
+
+## Synthesis references
+
+- `docs/superpowers/reviews/2026-05-04-architecture-review.md` — P1.1, P1.7, P1.8
+- `docs/superpowers/specs/2026-05-04-security-polish-design.md` — Plan A
+
+## Test plan
+
+- [x] `cargo test` green
+- [x] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` green
+- [x] `cd extension && bun run test && bun run build` green
+- [x] `cd tools/relay && bun test` green (4-pass after dev-c assertion fix in 061facd)
+- [x] New wasm-bindgen-test: SessionHandle construct → drop → SESSIONS registry empty
+- [x] `.free()` callsite audit under `extension/src/` — every site preceded by `wasm.lock(handle)`
+- [x] `start.sh` opens 4 windows including dev-c
+EOF
+)"
+```
+
+Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL.
+
+## First action
+
+After reading the required inputs and setting up the worktree:
+
+1. Call `read_messages(for="dev-a")` to drain any early inbox messages.
+2. Emit a `## STATUS UPDATE` confirming setup complete:
+   ```
+   ## STATUS UPDATE — DEV-A
+   Time: <iso8601>
+   Branch: feature/arch-followup-stream-a-security-polish
+   Task: setup
+   Status: DONE
+   Last commit: <main HEAD sha + first line>
+   Tests: N/A
+   Notes: Worktree at /home/alee/Sources/relicario.arch-followup-stream-a. Synthesis + reviewer notes absorbed. Awaiting Plan A at docs/superpowers/specs/2026-05-04-security-polish-design.md.
+   ```
+3. **Wait** for the PM's `## DIRECTIVE TO DEV-A` with `Action: PROCEED` and the plan path.
+4. Read the plan, then start Task 1 using `superpowers:subagent-driven-development`.

docs/superpowers/coordination/architecture-review-followup-dev-b-prompt.md

@@ -0,0 +1,242 @@
+# Dev B Kickoff Prompt — Architecture Review Followup, Stream B (CLI Restructure)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement the plan task-by-task once it lands.
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior developer** owning Stream B for the Relicario architecture-review-followup work. Stream B is the **single biggest readability lift** in the bundle (per the synthesis): split the 2641-LOC `crates/relicario-cli/src/main.rs` into a `commands/` folder, centralize the duplicated git-shell error UX, migrate three pure parsers to `relicario-core`, and pick up four in-scope CLI P2s. Multi-day, M-L effort.
+
+A PM in another terminal coordinates you with two other senior devs. With the relay server running, you communicate via `post_message` / `read_messages` directly. **Your plan does not exist yet.** The PM is drafting it as their first action. Set up your worktree, post acknowledgement, and wait for the PM's `PROCEED` directive containing the plan path before starting Task 1.
+
+## Setup (do this first)
+
+```bash
+cd /home/alee/Sources/relicario
+git fetch
+git worktree add /home/alee/Sources/relicario.arch-followup-stream-b -b feature/arch-followup-stream-b-cli-restructure
+cd /home/alee/Sources/relicario.arch-followup-stream-b
+pwd  # should print /home/alee/Sources/relicario.arch-followup-stream-b
+```
+
+**Note on `git pull`:** main has uncommitted polish changes from in-flight post-v0.5.1 work. The setup above branches from local main HEAD without pulling, which is intentional. None of those uncommitted files are in Stream B's scope, so this should not produce conflicts at PR time.
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario.arch-followup-stream-b`**. Every subagent prompt MUST begin with `cd /home/alee/Sources/relicario.arch-followup-stream-b` (project memory rule — without the force-cd, subagents may commit to main).
+
+Today: 2026-05-04. Project rules in `CLAUDE.md` apply (Spanish flourish in replies, capitalize "Relicario", default to "yes"/recommended, never run git-destructive commands without asking).
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (your scope is **P1.2, P1.3, P1.10 + the four in-scope CLI P2s only**)
+3. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — full DEV-B reviewer notes (your stream's primary source)
+4. `docs/superpowers/reviews/2026-05-04-dev-a-notes.md` — full DEV-A reviewer notes (covers the base32 dedup that pairs with P1.10)
+5. `docs/superpowers/reviews/2026-05-04-dev-c-notes.md` — read the **"Boundary notes for DEV-B"** section in particular (covers the parity-relevant cross-references for the parser→core migration and WASM exports)
+6. **Your plan (will land at):** `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — read once the PM directs you to PROCEED
+
+## Execution mode
+
+Use **superpowers:subagent-driven-development**. Fresh subagent per task, two-stage review between tasks. Every subagent prompt MUST start with:
+```
+cd /home/alee/Sources/relicario.arch-followup-stream-b
+```
+…before any other instruction. This is non-negotiable per project memory.
+
+## Your scope and boundaries
+
+**In scope:**
+- P1.2 — split `crates/relicario-cli/src/main.rs` (2641 LOC) into:
+  - `commands/{add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr}.rs`
+  - `prompt.rs` (six `prompt_*` helpers + `prompt_secret`)
+  - `parse.rs` (the three pure parsers, before they migrate to core)
+  - `main.rs` keeps clap definitions + dispatcher (~470 lines)
+- P1.3 — add `helpers::git_run(repo: &Path, args: &[&str], context: &str)` using `.output()` to capture stderr; print captured stderr unmodified on failure; embed a human-readable `context` ("commit add: GitHub", "register device", "purge trashed item"). Sweep ~16 duplicated bail sites listed in the synthesis (`main.rs:601, 602, 610, 986, 988, 1477, 1480, 1767, 1897, 1900, 2432, 2438, 2533, 2540` and others).
+- P1.10 — migrate to `relicario-core`:
+  - `parse_month_year` (already partial in `time.rs`)
+  - `base32_decode_lenient` (rename / fold into a new `pub(crate) mod base32` with `encode_rfc4648` / `decode_rfc4648`; keep Steam's bespoke alphabet untouched in `item_types/totp.rs`)
+  - `guess_mime` → `mime::guess_for_extension`
+  - Re-export the new functions through `relicario-wasm` via `#[wasm_bindgen]` so the extension can consume them in a future round
+  - CLI keeps thin wrappers as needed
+- In-scope CLI P2s:
+  - `build_*_item` helper compression (`main.rs:664-921`) with a `prompt_or_flag<T>` helper
+  - `refresh_groups_cache` discipline via `Vault::after_manifest_change(&self, manifest: &Manifest)` (7 manual sites at `main.rs:641, 998, 1123, 1197, 1414, 1432, 1474`)
+  - `ParamsFile` dedup between `main.rs:2287` (write side, has `aead`/`salt_path`/`format_version`) and `session.rs:114` (read side, only `kdf`)
+  - Batched purge in `cmd_purge` and `cmd_trash_empty` (`main.rs:1476-1480, 1896-1900`) — currently 50-item purge does 150 git invocations
+
+**Out of scope (other DEVs own these):**
+- P1.1, JS free-swallow, P1.7, P1.8 — DEV-A (Stream A)
+- P1.4, P1.5, P1.6, P1.9 + the in-scope extension P2s — DEV-C (Stream C)
+- Any other P2/P3 not listed in your plan
+- WASM JS-naming snake_case → camelCase rename (DEV-B/DEV-C P3) — explicitly deferred to a separate decision
+- Server hardening items from DEV-B's P2 (generate-hook PATH, bootstrap permissiveness, stdin parsing, test gaps) — explicitly deferred
+- Any of the 8 "Open architectural decisions" at the bottom of the synthesis
+
+If you trip over an out-of-scope issue or a new bug while doing your work, file a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- **The P1.2 main.rs split MUST land first.** Every other phase in your plan touches files that don't exist yet until the split happens. Do not interleave.
+- **The split is purely structural — no behavior changes.** Run `cargo test -p relicario-cli` before AND after the split commits to prove parity. Any behavior delta is a bug.
+- **Keep the helper module visibility tight.** `commands/` modules are `pub(crate)` only; `main.rs` dispatches into them.
+- **`helpers::git_run` signature** is `(repo: &Path, args: &[&str], context: &str)` and it captures stderr. The old `git_command` may stay temporarily during the sweep, but Phase B-N (sweep) deletes it.
+- **`base32` extraction** must keep Steam's bespoke alphabet untouched at `item_types/totp.rs`. Add a neighbour comment pointing to the new core module and explaining why Steam stays separate.
+- **WASM re-exports use snake_case** in JS for now (`#[wasm_bindgen]` defaults). Do not rename to camelCase — that's a separate decision (DEV-B/DEV-C P3 at the bottom of the synthesis).
+- **Test-only Argon2id params stay fast** (m=256, t=1, p=1) per project convention.
+- **No binary test fixtures.** Synthetic JPEGs only via `make_test_jpeg()`.
+- **Git history is preserved.** No squash merges (project rule).
+- Do not merge your branch to main. The PM owns merges.
+- Do not push `--force` or run `git reset --hard`. Per `CLAUDE.md`: ask first.
+
+## Coordination with Stream C
+
+Your parser→core migration produces new `relicario-core` functions and re-exports them through `relicario-wasm`. Stream C does NOT need to consume these in this round. Document the new WASM surface in your PR body so a future round can pick it up. If you discover a parser signature change that would break the future extension consumer, raise it via `## QUESTION TO PM` before committing.
+
+## 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-b"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-b"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-b")`. After emitting any status/question block: `post_message(from="dev-b", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-b","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-b"}'
+```
+
+## Coordination protocol
+
+You are one of four terminals. Before starting each task, call `read_messages(for="dev-b")` to drain your inbox.
+
+When posting a status update, call `post_message(from="dev-b", to="pm", kind="status", body="...")` with the body:
+
+```
+## STATUS UPDATE — DEV-B
+Time: <iso8601 like 2026-05-04T14:30:00-07:00>
+Branch: feature/arch-followup-stream-b-cli-restructure
+Task: <number / short name>
+Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
+Last commit: <short sha + first line of message>
+Tests: <green | red (which failed) | N/A>
+Notes: <anything PM needs to know — keep to 3 sentences max>
+```
+
+**When you need PM input mid-task:**
+```
+## QUESTION TO PM — DEV-B
+Time: <iso8601>
+Context: <what task, what decision point>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no
+```
+
+**You'll receive:** `## DIRECTIVE TO DEV-B` blocks from the PM. The first one will say `Action: PROCEED` with the plan path once the PM has drafted it. Acknowledge and start Task 1.
+
+## Authority within the plan
+
+You don't need PM permission to:
+- Execute task-to-task per the plan once you have it
+- Make implementation decisions consistent with the plan and synthesis
+- Write tests, refactor your own code, fix bugs you introduce
+- Push commits to your feature branch
+
+You **do** escalate to PM when:
+- A scope question outside the plan
+- A signature change in the parser→core migration that would affect the future extension consumer
+- A test you can't make green after honest debugging (don't fudge — debug)
+- A discovered bug not in your plan
+- Anything destructive (per CLAUDE.md)
+- Before opening the PR for review
+
+## Final steps before REVIEW-READY
+
+Run the project's full validation:
+
+```bash
+cd /home/alee/Sources/relicario.arch-followup-stream-b
+cargo build
+cargo test
+cargo test -p relicario-core
+cargo test -p relicario-cli --test basic_flows
+cargo test -p relicario-cli --test edit_and_history
+cargo test -p relicario-cli --test attachments
+cargo test -p relicario-cli --test settings
+cargo test -p relicario-cli --test vault_detection
+cargo build -p relicario-wasm --target wasm32-unknown-unknown
+cargo run -p relicario-cli -- --help
+cargo run -p relicario-cli -- generate --length 32
+```
+
+All must be green. The CLI integration suite covers the surface area touched by the split + git_run sweep; pay particular attention to `basic_flows` and `edit_and_history` for regression coverage.
+
+Then push and open the PR:
+
+```bash
+git push -u origin feature/arch-followup-stream-b-cli-restructure
+gh pr create --base main --head feature/arch-followup-stream-b-cli-restructure \
+  --title "refactor(cli): split main.rs into commands/ + git_run helper + parsers→core (Stream B)" \
+  --body "$(cat <<'EOF'
+## Summary
+
+Stream B of the architecture-review-followup. The single biggest readability lift in the bundle:
+
+- **P1.2** — `crates/relicario-cli/src/main.rs` (2641 LOC) split into `commands/{add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr}.rs` + `prompt.rs` + `parse.rs`. `main.rs` keeps clap definitions + dispatcher.
+- **P1.3** — `helpers::git_run(repo, args, context)` with stderr capture; ~16 duplicated bail sites swept.
+- **P1.10** — `parse_month_year`, `base32_decode_lenient` (folded into a new `relicario_core::base32` module alongside DEV-A's P2 dedup), `guess_mime` migrated to `relicario-core`. Re-exported through `relicario-wasm` via `#[wasm_bindgen]` for future extension consumption.
+- **CLI P2 cluster** — `build_*_item` helper compression, `Vault::after_manifest_change`, `ParamsFile` dedup, batched purge.
+
+## Synthesis references
+
+- `docs/superpowers/reviews/2026-05-04-architecture-review.md` — P1.2, P1.3, P1.10 + DEV-B's CLI P2 cluster + DEV-A's base32 dedup
+- `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` — Plan B
+
+## New WASM surface (for future Stream C consumption)
+
+The extension does NOT consume these in this round. A future plan should wire them up via `wasm.d.ts` regeneration:
+- `parse_month_year` — for QR-import / smart-input flows
+- `base32_encode_rfc4648` / `base32_decode_rfc4648` — for TOTP / future QR work
+- `guess_mime_for_extension` — for attachment MIME detection
+
+## Test plan
+
+- [x] `cargo build` green
+- [x] `cargo test` green (workspace-wide)
+- [x] `cargo test -p relicario-core` green (new base32 module + parser tests)
+- [x] `cargo test -p relicario-cli --test basic_flows` green (regression on the split)
+- [x] `cargo test -p relicario-cli --test edit_and_history` green
+- [x] `cargo test -p relicario-cli --test attachments` green
+- [x] `cargo test -p relicario-cli --test settings` green
+- [x] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` green (new exports)
+- [x] `cargo run -p relicario-cli -- --help` displays unchanged surface
+- [x] `cargo run -p relicario-cli -- generate --length 32` smoke
+- [x] git_run sweep: every git failure path now prints captured stderr + context
+- [x] Steam alphabet at `item_types/totp.rs` untouched
+EOF
+)"
+```
+
+Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL.
+
+## First action
+
+After reading the required inputs and setting up the worktree:
+
+1. Call `read_messages(for="dev-b")` to drain any early inbox messages.
+2. Emit a `## STATUS UPDATE` confirming setup complete:
+   ```
+   ## STATUS UPDATE — DEV-B
+   Time: <iso8601>
+   Branch: feature/arch-followup-stream-b-cli-restructure
+   Task: setup
+   Status: DONE
+   Last commit: <main HEAD sha + first line>
+   Tests: N/A
+   Notes: Worktree at /home/alee/Sources/relicario.arch-followup-stream-b. Synthesis + DEV-B/DEV-A notes + DEV-C boundary section absorbed. Awaiting Plan B at docs/superpowers/specs/2026-05-04-cli-restructure-design.md.
+   ```
+3. **Wait** for the PM's `## DIRECTIVE TO DEV-B` with `Action: PROCEED` and the plan path.
+4. Read the plan, then start Task 1 using `superpowers:subagent-driven-development`. Phase 1 is the main.rs split — finish it cleanly before any other phase.

docs/superpowers/coordination/architecture-review-followup-dev-c-prompt.md

@@ -0,0 +1,275 @@
+# Dev C Kickoff Prompt — Architecture Review Followup, Stream C (Extension Restructure)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans` to implement the plan task-by-task once it lands.
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior developer** owning Stream C for the Relicario architecture-review-followup work. Stream C is the **largest plan in the bundle** (multi-day to multi-week): turn `setup.ts` into a UI that posts SW messages instead of orchestrating WASM directly, split `vault.ts` into focused modules, give `shared/state.ts` a real type contract, deduplicate the SW router helpers, and pick up the in-scope extension P2 cluster.
+
+A PM in another terminal coordinates you with two other senior devs. With the relay server running, you communicate via `post_message` / `read_messages` directly. **Your plan does not exist yet.** The PM is drafting it as their first action. Set up your worktree, post acknowledgement, and wait for the PM's `PROCEED` directive containing the plan path before starting Task 1.
+
+## Setup (do this first)
+
+```bash
+cd /home/alee/Sources/relicario
+git fetch
+git worktree add /home/alee/Sources/relicario.arch-followup-stream-c -b feature/arch-followup-stream-c-extension-restructure
+cd /home/alee/Sources/relicario.arch-followup-stream-c
+pwd  # should print /home/alee/Sources/relicario.arch-followup-stream-c
+```
+
+**Note on `git pull`:** main has uncommitted polish changes from in-flight post-v0.5.1 work, including edits to `extension/src/vault/vault.ts`, `vault.css`, and `shared/glyphs.ts` — files Stream C will touch heavily. **Surface this to the PM as a Question before starting Phase 1** so the user can choose to commit/stash the in-flight work, defer Stream C, or proceed and merge at PR time. The setup above branches from local main HEAD without pulling, so your worktree starts clean of those uncommitted edits.
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario.arch-followup-stream-c`**. Every subagent prompt MUST begin with `cd /home/alee/Sources/relicario.arch-followup-stream-c` (project memory rule — without the force-cd, subagents may commit to main).
+
+Today: 2026-05-04. Project rules in `CLAUDE.md` apply (Spanish flourish in replies, capitalize "Relicario", default to "yes"/recommended, never run git-destructive commands without asking).
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — synthesis (your scope is **P1.4, P1.5, P1.6, P1.9 + the in-scope extension P2 cluster only**)
+3. `docs/superpowers/reviews/2026-05-04-dev-c-notes.md` — full DEV-C reviewer notes (your stream's primary source)
+4. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — read the **"Boundary notes for DEV-C"** section in particular (covers the parity-relevant cross-references, especially the new WASM surface that Plan B will produce)
+5. `docs/superpowers/reviews/2026-05-04-dev-a-notes.md` — light skim for context only
+6. **Your plan (will land at):** `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` — read once the PM directs you to PROCEED
+
+## Execution mode
+
+Use **superpowers:subagent-driven-development**. Fresh subagent per task, two-stage review between tasks. Every subagent prompt MUST start with:
+```
+cd /home/alee/Sources/relicario.arch-followup-stream-c
+```
+…before any other instruction. This is non-negotiable per project memory.
+
+## Your scope and boundaries
+
+**In scope:**
+- P1.4 — `extension/src/setup/setup.ts` (1220 LOC):
+  - Add `create_vault` and `attach_vault` SW messages to `service-worker/router/popup-only.ts` + the message-type union in `shared/messages.ts`
+  - Rewrite `setup.ts` as a UI that posts those messages with gathered config + image bytes (no direct `relicario-wasm` import)
+  - Convert the 6-step procedural wizard into a step-registry pattern: `Array<{ id: StepId; render: (host) => void; attach: (host) => () => void }>`
+  - `clearWizardState()` bound to `beforeunload` and to "return to step 0"
+  - Target ~500 LOC after the rewrite (down from 1220)
+- P1.5 — split `extension/src/vault/vault.ts` (1027 LOC) into:
+  - `vault-shell.ts` (init, hash routing)
+  - `vault-sidebar.ts` (sidebar render)
+  - `vault-list.ts` (list pane render)
+  - `vault-drawer.ts` (drawer state + render)
+  - `vault-form-wrapper.ts` (form integration)
+  - `vault.ts` keeps only routing + state coordination
+  - **Lift the `vault_locked` RPC intercept into `shared/state.ts`** (or a wrapper around `sendMessage`) so popup and vault tab use the same channel — closes the synthesis P2 about RPC vs `session_expired` event divergence
+  - Reset `state.drawerOpen` at the start of `renderPane` for non-list views
+- P1.6 — concrete `StateHost` interface in `extension/src/shared/state.ts`:
+  ```ts
+  interface StateHost {
+    state: PopupState;
+    navigate: (view: View) => void;
+    popOutToTab(): void;
+    isInTab(): boolean;
+    openVaultTab(hash?: string): void;
+  }
+  ```
+  - Make `getState`/`setState` generic over `keyof PopupState`
+  - Throw on `registerHost()` re-register
+  - Export `__resetHostForTests()` helper
+- P1.9 — extract from both router files:
+  - `loadDeviceSettings`, `loadBlacklist`, `saveBlacklist` → `extension/src/service-worker/storage.ts`
+  - `itemToManifestEntry` (17-line projection) → `extension/src/service-worker/vault.ts`
+  - Import from both `popup-only.ts` and `content-callable.ts`
+- In-scope extension P2 cluster:
+  - Inactivity-timer reset on content-callable messages (`service-worker/index.ts:76-78`)
+  - Null `state.gitHost` alongside `state.manifest` on session expiry (`service-worker/index.ts:51-58`)
+  - Teardown helper extraction: `settings.ts:56-65` and `settings-vault.ts:15-22` → `teardownSettingsCommon()`
+  - `Promise.allSettled` in `devices.ts:47-50` and `trash.ts:39-46`
+  - MutationObserver debounce in `content/detector.ts:96-103` (`requestIdleCallback` or 200ms timer)
+  - Vault-tab status indicator from new `get_vault_status` SW message returning `{ ahead, behind, lastSyncAt, pendingItems }` (closes the `relicario status` parity gap)
+
+**Out of scope (other DEVs own these):**
+- P1.1, JS free-swallow, P1.7, P1.8 — DEV-A (Stream A). **Note:** if A merges first, you'll inherit `impl Drop for SessionHandle`. That's expected and benign.
+- P1.2, P1.3, P1.10 + the in-scope CLI P2s — DEV-B (Stream B). The new WASM exports (`parse_month_year`, `base32_*`, `guess_mime_for_extension`) that Plan B produces are NOT consumed in this round. Document the future consumer in your plan's "Out of scope" section; a later round wires them up.
+- Other DEV-C P2/P3 not listed in your scope (e.g. shared-utilities response typing, group-autocomplete escaping, restore_backup payload extract, content-script `fillFields()` ack, content/icon outside-click leak) — explicitly deferred to a future round
+- Setup-wizard manifest path constants (`VAULT_PATHS`) — folds into your P1.4 work; if convenient include it, else defer
+- WASM JS-naming snake_case → camelCase rename — explicitly deferred
+- Any of the 8 "Open architectural decisions" at the bottom of the synthesis
+
+If you trip over an out-of-scope issue or a new bug while doing your work, file a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- **P1.6 (state.ts typing) MUST land first internally.** Both P1.4 and P1.5 push through the `StateHost` surface. Plan should call this out as Phase 1.
+- **`setup.ts` MUST stop importing `relicario-wasm` directly after P1.4.** This is the architectural invariant the synthesis is fixing. After P1.4, the only file in `extension/src/` that imports `relicario-wasm` should be the service worker.
+- **New SW message names are `create_vault` and `attach_vault`.** Use these exact names everywhere (`shared/messages.ts`, `service-worker/router/popup-only.ts`, `setup.ts`). The PM's coherence pass on the plans confirms naming consistency.
+- **`vault_locked` unification goes in `shared/state.ts`** (or a wrapper around `sendMessage`). Popup AND vault tab use the same channel after this lands. Two channels for one outcome was the synthesis observation.
+- **No emoji anywhere in `extension/src/`** (existing project rule from v0.5.1). If you see one while editing, replace with the monochrome glyph from `glyphs.ts`.
+- **`glyphs.ts` is single source of truth** for icon characters. No inline Unicode literals at call sites.
+- **Discriminated-union message contract is preserved.** New messages get added to `shared/messages.ts` and the appropriate capability set (`POPUP_ONLY_TYPES` or `CONTENT_CALLABLE_TYPES`). The boundary discipline holds.
+- **WASM remains snake_case in JS** — no `#[wasm_bindgen(js_name = ...)]` renaming. That's a separate decision (DEV-B/DEV-C P3).
+- **Test setup is vitest** for the extension (`extension/package.json: "test": "vitest run"`), `bun test` for `tools/relay/`. Do not change runners.
+- **Synthetic test fixtures only.** No binary blobs.
+- Do not merge your branch to main. The PM owns merges.
+- Do not push `--force` or run `git reset --hard`. Per `CLAUDE.md`: ask first.
+
+## Coordination with Stream B
+
+Stream B will produce new `relicario-wasm` exports (`parse_month_year`, `base32_*`, `guess_mime_for_extension`). You do NOT consume these in this round — your plan's "Out of scope" section should explicitly call this out and reference the future consumer (likely a smart-input / QR-import / attachment-MIME round). If Stream B's WASM signature for any of these would NOT match what the extension would naturally consume, raise a `## QUESTION TO PM` so it can be reconciled before Stream B merges.
+
+If Stream A merges first and you inherit `impl Drop for SessionHandle` plus the JS free-swallow removal: that's benign. Your `.free()` callsites should already be `wasm.lock(handle)` first per DEV-A's audit.
+
+## 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-c"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-c"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-c")`. After emitting any status/question block: `post_message(from="dev-c", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-c","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-c"}'
+```
+
+## Coordination protocol
+
+You are one of four terminals. Before starting each task, call `read_messages(for="dev-c")` to drain your inbox.
+
+When posting a status update, call `post_message(from="dev-c", to="pm", kind="status", body="...")` with the body:
+
+```
+## STATUS UPDATE — DEV-C
+Time: <iso8601 like 2026-05-04T14:30:00-07:00>
+Branch: feature/arch-followup-stream-c-extension-restructure
+Task: <number / short name>
+Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
+Last commit: <short sha + first line of message>
+Tests: <green | red (which failed) | N/A>
+Notes: <anything PM needs to know — keep to 3 sentences max>
+```
+
+**When you need PM input mid-task:**
+```
+## QUESTION TO PM — DEV-C
+Time: <iso8601>
+Context: <what task, what decision point>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no
+```
+
+**You'll receive:** `## DIRECTIVE TO DEV-C` blocks from the PM. The first one will say `Action: PROCEED` with the plan path once the PM has drafted it. Acknowledge and start Task 1.
+
+## Authority within the plan
+
+You don't need PM permission to:
+- Execute task-to-task per the plan once you have it
+- Make implementation decisions consistent with the plan and synthesis
+- Write tests, refactor your own code, fix bugs you introduce
+- Push commits to your feature branch
+
+You **do** escalate to PM when:
+- A scope question outside the plan
+- A WASM signature mismatch with what Stream B is producing
+- A test you can't make green after honest debugging (don't fudge — debug)
+- A discovered bug not in your plan
+- The in-flight uncommitted changes on `vault.ts`/`vault.css`/`glyphs.ts` need resolution before a merge
+- Anything destructive (per CLAUDE.md)
+- Before opening the PR for review
+
+## Final steps before REVIEW-READY
+
+Run the project's full validation:
+
+```bash
+cd /home/alee/Sources/relicario.arch-followup-stream-c
+cd extension
+bun run test
+bun run build
+bun run build:firefox
+cd ..
+cargo build -p relicario-wasm --target wasm32-unknown-unknown
+```
+
+All must be green. Vitest covers the new `StateHost` typing, the message-router dedup, and the wizard step registry.
+
+Then sweep for emoji and in-flight collision:
+
+```bash
+grep -rn '\U0001F\|🔑\|📝\|🪪\|💳\|🗝\|📄\|⏱️\|🖥\|🔐\|📎' /home/alee/Sources/relicario.arch-followup-stream-c/extension/src/ 2>/dev/null
+```
+
+Expected: no output (project rule).
+
+Then push and open the PR:
+
+```bash
+git push -u origin feature/arch-followup-stream-c-extension-restructure
+gh pr create --base main --head feature/arch-followup-stream-c-extension-restructure \
+  --title "refactor(ext): setup-via-SW + vault.ts split + state.ts typing + SW router dedup (Stream C)" \
+  --body "$(cat <<'EOF'
+## Summary
+
+Stream C of the architecture-review-followup. The largest plan in the bundle — turns three "code lies about the architecture" surfaces into uniform readable modules:
+
+- **P1.4** — `extension/src/setup/setup.ts` no longer imports `relicario-wasm` directly. New `create_vault` / `attach_vault` SW messages do the crypto orchestration. The 6-step wizard is now a step registry. ~500 LOC down from 1220.
+- **P1.5** — `extension/src/vault/vault.ts` (1027 LOC) split into `vault-shell.ts` / `vault-sidebar.ts` / `vault-list.ts` / `vault-drawer.ts` / `vault-form-wrapper.ts`. `vault_locked` RPC intercept lifted into `shared/state.ts` so popup and vault tab share one channel.
+- **P1.6** — `extension/src/shared/state.ts` has a concrete `StateHost` interface; `getState`/`setState` are generic over `keyof PopupState`; double-registration guard + `__resetHostForTests` helper.
+- **P1.9** — duplicated SW router helpers extracted: `service-worker/storage.ts` for the three storage helpers, `service-worker/vault.ts` for `itemToManifestEntry`.
+- **Extension P2 cluster** — inactivity-timer reset on content-callable messages, `state.gitHost` clear on session expiry, `teardownSettingsCommon()`, `Promise.allSettled` in devices/trash, MutationObserver debounce in content/detector, vault-tab status indicator (closes `relicario status` parity gap).
+
+## Synthesis references
+
+- `docs/superpowers/reviews/2026-05-04-architecture-review.md` — P1.4, P1.5, P1.6, P1.9 + DEV-C's extension P2 cluster
+- `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` — Plan C
+
+## Future-round consumer (NOT in this PR)
+
+Plan B produces new `relicario-wasm` exports (`parse_month_year`, `base32_*`, `guess_mime_for_extension`). A later round will wire them up via `wasm.d.ts` regeneration and add SW message handlers. Out of scope here.
+
+## Test plan
+
+- [x] `bun run test` green in `extension/`
+- [x] `bun run build` green
+- [x] `bun run build:firefox` green
+- [x] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` green
+- [x] No emoji anywhere in `extension/src/` (grep clean)
+- [x] `setup.ts` no longer imports `relicario-wasm`
+- [x] `vault.ts` LOC dropped substantially; new modules each under ~300 LOC
+- [x] Vault tab and popup both use one channel for `vault_locked` (no RPC intercept divergence)
+- [x] StateHost interface concrete; tests cover double-registration guard and reset helper
+EOF
+)"
+```
+
+Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL.
+
+## First action
+
+After reading the required inputs and setting up the worktree:
+
+1. Call `read_messages(for="dev-c")` to drain any early inbox messages.
+2. Emit a `## STATUS UPDATE` confirming setup complete:
+   ```
+   ## STATUS UPDATE — DEV-C
+   Time: <iso8601>
+   Branch: feature/arch-followup-stream-c-extension-restructure
+   Task: setup
+   Status: DONE
+   Last commit: <main HEAD sha + first line>
+   Tests: N/A
+   Notes: Worktree at /home/alee/Sources/relicario.arch-followup-stream-c. Synthesis + DEV-C notes + DEV-B boundary section absorbed. Awaiting Plan C at docs/superpowers/specs/2026-05-04-extension-restructure-design.md.
+   ```
+3. **Also emit a `## QUESTION TO PM`** about the in-flight uncommitted edits to `vault.ts` / `vault.css` / `glyphs.ts` on main:
+   ```
+   ## QUESTION TO PM — DEV-C
+   Time: <iso8601>
+   Context: setup, before Phase 1
+   Options: A: PM/user commits or stashes the in-flight v0.5.x polish on main before I start, so my worktree has a stable baseline. B: I proceed and rebase/merge those changes at PR time. C: PM defers Stream C until the in-flight work is committed.
+   Recommended: A — clean baseline avoids merge churn during the largest plan in the bundle.
+   Blocker: no — I can read the plan and start Phase 1 (P1.6 state.ts typing) which doesn't touch the in-flight files. Resolution needed before Phase 2 (P1.5 vault.ts split).
+   ```
+4. **Wait** for the PM's `## DIRECTIVE TO DEV-C` with `Action: PROCEED` and the plan path.
+5. Read the plan, then start Task 1 using `superpowers:subagent-driven-development`. Phase 1 is P1.6 (state.ts typing) — finish it cleanly before P1.4 / P1.5.

docs/superpowers/coordination/architecture-review-followup-planning-prompt.md

@@ -0,0 +1,133 @@
+# Planning Kickoff Prompt — Architecture-Review Follow-up
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are an architect drafting **three implementation plans** that follow up on the whole-codebase architecture review committed to `main` on 2026-05-04 (`061facd docs(reviews): whole-codebase architecture audit 2026-05-04`). Three reviewers (DEV-A: Rust core; DEV-B: Rust consumers; DEV-C: TypeScript) walked the codebase; the PM synthesized 10 P1s plus a long P2/P3 tail. Your job is to convert those findings into three discrete, well-scoped plans that the user (or future agents) can execute.
+
+This is **planning-only work.** Do not modify the codebase being planned. Do not commit. Do not ship anything. Each plan is a markdown file in `docs/superpowers/specs/` and that is the only output.
+
+## Setup
+
+- Working directory: `/home/alee/Sources/relicario`
+- Stay on `main`. Do not create branches or worktrees.
+- Today: 2026-05-04. Project rules in `CLAUDE.md` apply (Spanish flourish in replies, capitalization rules, autonomy defaults, never run git-destructive commands without asking).
+- The working tree has uncommitted changes from in-flight v0.5.x work (manifests, vault.ts/css, glyphs, relay tooling, Cargo.toml version bumps). Treat them as "in flight, ignore" — do not include them in any plan.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules (Spanish flourish, capitalization, autonomy)
+2. `docs/superpowers/specs/2026-04-11-relicario-design.md` — foundational design spec (threat model, crypto pipeline, format)
+3. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — **PM synthesis. This is the canonical source. Every plan below must trace its scope back to specific findings here.**
+4. `docs/superpowers/reviews/2026-05-04-dev-a-notes.md` — DEV-A's full notes (Rust core)
+5. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — DEV-B's full notes (CLI/server/WASM), especially the "Boundary notes for DEV-C" section
+6. `docs/superpowers/reviews/2026-05-04-dev-c-notes.md` — DEV-C's full notes (extension + relay), especially the "Boundary notes for DEV-B" section
+
+Also skim two existing plan docs to match the format and tone:
+- `docs/superpowers/specs/2026-05-02-v0.5.0-polish-harden-design.md`
+- `docs/superpowers/specs/2026-05-03-v0.5.x-ux-polish-and-recovery-qr-design.md`
+
+## What to produce
+
+Three plan files, all under `docs/superpowers/specs/`:
+
+### Plan A — Security & docs polish PR
+**Filename:** `docs/superpowers/specs/2026-05-04-security-polish-design.md`
+**Scope (drawn from synthesis):** P1.1 (`SessionHandle` `impl Drop` + Rust `wasm-bindgen-test` + extension `.free()` callsite audit), the partner JS-side fix at `service-worker/session.ts:26` (remove the `try { current.free() }` swallow), P1.7 (`recovery_qr.rs` documentation to match `crypto.rs`/`backup.rs` density), and the launcher fix DEV-C suspected at `tools/relay/start.sh:80` (4-window dev-c support; queue.test.ts assertion already fixed in `061facd`). Goal: one short PR, all-S-effort items, ships in under a day. This is the security-flavored quick win that goes first; nothing in B or C should depend on it.
+
+### Plan B — CLI restructure
+**Filename:** `docs/superpowers/specs/2026-05-04-cli-restructure-design.md`
+**Scope:** P1.2 (split `crates/relicario-cli/src/main.rs` 2641 LOC into `commands/{add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr}.rs` + `prompt.rs` + `parse.rs`, leaving `main.rs` as clap definitions + dispatcher), P1.3 (`helpers::git_run(repo, args, context)` with stderr capture; sweep the ~16 duplicated bail sites), P1.10 (migrate `parse_month_year`, `base32_decode_lenient`, `guess_mime` to `relicario-core` and re-export through `relicario-wasm` for the extension; pair with the core base32 dedup from DEV-A's P2), plus the in-scope CLI P2s (`build_*_item` helper compression, `refresh_groups_cache` discipline via `Vault::after_manifest_change`, `ParamsFile` dedup between `main.rs:2287` and `session.rs:114`, batched purge in `cmd_purge`/`cmd_trash_empty`). Sequencing matters here: the `main.rs` split must land first because every other P2 in this plan touches files that don't exist yet until the split happens. Goal: M-L effort, multi-day plan; "single biggest readability lift" per the synthesis.
+
+### Plan C — Extension restructure
+**Filename:** `docs/superpowers/specs/2026-05-04-extension-restructure-design.md`
+**Scope:** P1.4 (`extension/src/setup/setup.ts` 1220 LOC: add `create_vault` and `attach_vault` SW messages; rewrite setup as a UI that posts those messages with gathered config + image bytes; convert the 6-step procedural wizard into a step-registry pattern `{ id, render, attach }[]`; add `clearWizardState()` on `beforeunload`), P1.5 (split `extension/src/vault/vault.ts` 1027 LOC into `vault-shell.ts` / `vault-sidebar.ts` / `vault-list.ts` / `vault-drawer.ts` / `vault-form-wrapper.ts`; lift the `vault_locked` RPC intercept into `shared/state.ts` so popup and vault use one channel; reset `state.drawerOpen` on non-list `renderPane`), P1.6 (concrete `StateHost` interface in `shared/state.ts` with `state: PopupState`, `navigate`, `popOutToTab`, `isInTab`, `openVaultTab`; generic `getState`/`setState` over `keyof PopupState`; double-registration guard + `__resetHostForTests` helper), P1.9 (extract duplicated SW router helpers — `loadDeviceSettings`/`loadBlacklist`/`saveBlacklist` to `service-worker/storage.ts`; `itemToManifestEntry` to `service-worker/vault.ts`), plus the in-scope extension P2s (inactivity-timer reset on content-callable messages; `state.gitHost` clear on session expiry; teardown helper extraction; `Promise.allSettled` in devices/trash; mutation-observer debounce in content/detector.ts; vault-tab status indicator from `get_vault_status` for the `relicario status` parity gap). Sequencing: P1.6 (state.ts typing) is a precondition for P1.4 and P1.5 because lifting `vault_locked` and adding setup-via-SW both push through that surface. Goal: largest plan, multi-day to multi-week.
+
+## What's explicitly NOT in these three plans
+
+- The full P2/P3 tail outside what's listed above. The synthesis doc is canonical; if a P2 isn't named in one of the three scopes above, it doesn't go in. Future plans can pick those up.
+- WASM JS-naming snake_case → camelCase (DEV-B/DEV-C P3) — defer to a separate decision, not these plans.
+- The 8 "Open architectural decisions" at the bottom of the synthesis — those are user-judgement calls, not implementation tasks.
+- Anything that requires touching the in-flight uncommitted v0.5.x work (manifests, glyphs, vault.css, relay tooling beyond start.sh).
+
+## Plan format (match the existing specs)
+
+Each plan file should have, at minimum:
+
+```markdown
+# <Title> — Design
+
+**Date:** 2026-05-04
+**Status:** Proposed
+**Source:** docs/superpowers/reviews/2026-05-04-architecture-review.md (P1.X, P1.Y, ...)
+**Effort estimate:** S | M | L
+
+## Summary
+2-4 sentences: what this plan accomplishes and why it matters for the user's stated goal ("make this app's architecture logical and readable for someone who doesn't know Rust but wants to learn by tinkering").
+
+## Findings addressed
+Bullet list, each entry citing the synthesis P-tag, the reviewer who found it, and the file:line.
+
+## Approach
+The architectural shape of the work — what gets extracted, what gets created, what gets renamed. Include directory trees / module diagrams if it helps a reader follow the layout change.
+
+## Implementation phases
+Numbered phases. Each phase:
+- **Goal:** one-sentence outcome
+- **Changes:** specific files touched, new files created, with paths
+- **Tests:** what gets added or moved (synthetic fixtures only — no binary blobs, per project convention)
+- **Effort:** S/M/L for the phase
+- **Depends on:** other phases, or "none"
+
+## Risks and mitigations
+What can break, especially across the CLI/extension parity boundary. Cite specific findings.
+
+## Out of scope
+Explicit list of adjacent things this plan does NOT touch.
+
+## Done criteria
+Checklist a reviewer can use to confirm the plan shipped.
+```
+
+Mirror the tone and depth of `2026-05-02-v0.5.0-polish-harden-design.md` and `2026-05-03-v0.5.x-ux-polish-and-recovery-qr-design.md`. Use the same heading conventions.
+
+## Execution approach
+
+**Use subagents.** Per the user's standing preference (CLAUDE.md memory: "Default to subagent-driven execution — for any multi-task plan use subagent-driven mode without asking"), drafting these plans is parallel work. Spawn three `Plan` subagents in parallel (single message, three tool calls), one per plan file. Each subagent reads the same shared inputs (synthesis + relevant notes file(s)), then writes only its assigned plan file. Plan B and Plan C subagents should each receive the relevant cross-boundary section of the *other* reviewer's notes ("Boundary notes for DEV-C" goes to Plan C's drafter; "Boundary notes for DEV-B" goes to Plan B's drafter) so the parity boundary is respected.
+
+After the three subagents return, do a coherence pass yourself:
+- Confirm Plan A doesn't depend on B or C
+- Confirm Plan B's `parse_month_year`/`base32` migration to core is reachable from Plan C's WASM consumers (or note explicitly that Plan C will pick up the WASM exports in a later phase)
+- Confirm Plan C's setup-via-SW migration cites the same `create_vault`/`attach_vault` message names everywhere
+
+Each subagent prompt **must** start with `cd /home/alee/Sources/relicario` (project memory rule — without the force-cd, subagents may write to the wrong tree).
+
+## Hard constraints
+
+- **Read-only on the codebase being planned.** No `cargo`, `bun`, or any other write commands beyond writing the three plan files.
+- **No commits.** The user commits when ready.
+- **No git operations.** Don't even `git status` unless you have a specific reason.
+- **Three files, no fewer, no more.** If a finding doesn't fit any of the three scopes above, leave it out — future plans handle it.
+- **Spanish flourish in replies (1-2 phrases per reply with `[translation]` brackets), per CLAUDE.md.** Do not put Spanish into the plan files themselves — those are project artifacts.
+
+## Done criteria
+
+Before posting your final summary:
+- [ ] All three plan files exist under `docs/superpowers/specs/` with the exact filenames specified above
+- [ ] Each plan cites at least one specific P1 from the synthesis in its "Findings addressed" section
+- [ ] Each plan has phases, each phase has effort, each phase names specific files
+- [ ] Plan A is independent (no dependencies on B or C)
+- [ ] Plan B and Plan C call out the parity-relevant cross-references explicitly
+- [ ] You did NOT modify any code, run any test, or commit anything
+- [ ] You ask the user whether to commit the three plan files (do not commit unprompted)
+
+## First action
+
+1. Read the synthesis (`docs/superpowers/reviews/2026-05-04-architecture-review.md`) end-to-end. Internalize the 10 P1s and the cross-cutting themes.
+2. Skim the three per-reviewer notes files for the file:line context the synthesis abbreviates.
+3. Skim the two existing plan docs above to absorb the format.
+4. Tell the user what you absorbed in 3-5 sentences.
+5. Spawn three `Plan` subagents in parallel with the scopes specified above.
+6. Do the coherence pass.
+7. Ask the user whether to commit the three plan files.

docs/superpowers/coordination/architecture-review-followup-pm-prompt.md

@@ -0,0 +1,211 @@
+# PM Kickoff Prompt — Architecture Review Followup (2026-05-04)
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are the **project manager** for the Relicario architecture-review-followup work. Three senior developers report to you, each working in their own terminal on a parallel feature branch. The user runs all four terminals.
+
+This release has no version tag — it's a structural-cleanup bundle from the 2026-05-04 architecture audit (commit `061facd`). The goal is to make the codebase uniformly readable for a smart developer who doesn't know Rust but wants to learn by tinkering. There is no merge freeze, no CHANGELOG entry needed, and no tag at the end unless the user requests one.
+
+## Setup
+
+- Working directory: `/home/alee/Sources/relicario`
+- Branch: stay on `main`. Do not check out feature branches.
+- Today: 2026-05-04. Project rules in `CLAUDE.md` apply (Spanish flourish in replies, capitalize "Relicario", default to "yes"/recommended, never run git-destructive commands without asking, default to subagent-driven execution).
+- **Working-tree note:** main has uncommitted polish changes from in-flight post-v0.5.1 work (glyphs/vault/relay/manifests/Cargo.toml version bumps, plus the four `architecture-review-*-prompt.md` files this session is generating). The synthesis explicitly tags these "in flight, ignore" — none of the three plans should include them. Also: Stream C touches `extension/src/vault/vault.ts`, `vault.css`, and `shared/glyphs.ts` which currently have uncommitted edits on main. Surface this to the user before unlocking DEV-C; either commit/stash the in-flight changes or note that C will need to merge them in at PR time.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/reviews/2026-05-04-architecture-review.md` — **PM synthesis. This is the canonical source. Every plan must trace its scope back to specific findings here.**
+3. `docs/superpowers/reviews/2026-05-04-dev-a-notes.md` — full DEV-A notes (Rust core)
+4. `docs/superpowers/reviews/2026-05-04-dev-b-notes.md` — full DEV-B notes (CLI/server/WASM), especially the "Boundary notes for DEV-C" section
+5. `docs/superpowers/reviews/2026-05-04-dev-c-notes.md` — full DEV-C notes (extension + relay), especially the "Boundary notes for DEV-B" section
+6. `docs/superpowers/specs/2026-05-02-v0.5.0-polish-harden-design.md` and `docs/superpowers/specs/2026-05-03-v0.5.x-ux-polish-and-recovery-qr-design.md` — format reference for the plan docs you will draft
+
+## Stream overview
+
+| Stream | Branch | Owner | Plan file (to be drafted) | Items |
+|--------|--------|-------|---------------------------|-------|
+| A — Security & docs polish | `feature/arch-followup-stream-a-security-polish` | DEV-A | `docs/superpowers/specs/2026-05-04-security-polish-design.md` | P1.1, JS free-swallow fix, P1.7, P1.8 |
+| B — CLI restructure | `feature/arch-followup-stream-b-cli-restructure` | DEV-B | `docs/superpowers/specs/2026-05-04-cli-restructure-design.md` | P1.2, P1.3, P1.10 + 4 in-scope CLI P2s |
+| C — Extension restructure | `feature/arch-followup-stream-c-extension-restructure` | DEV-C | `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` | P1.4, P1.5, P1.6, P1.9 + in-scope ext P2s |
+
+## Your authority
+
+- Approve or deny scope changes from devs
+- Review and merge PRs from each stream's feature branch
+- **Draft the three plan docs as your first hands-on action.** This is the single biggest piece of work you own personally.
+- Edit `docs/`, `CLAUDE.md`, or other doc artifacts as needed; do not write feature code
+
+## Your boundaries
+
+- Don't write feature code yourself. Edits to docs / `CLAUDE.md` are fine.
+- Don't deviate from the synthesis scope 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 (none planned for this work).
+- Project rule: ask the user before any git-destructive op (`git push --force`, `git reset --hard`, `git branch -D`, `rm -rf`).
+
+## Cross-stream coordination
+
+- **Stream A is independent** — no dependencies on B or C. Merge first if it's ready.
+- **Stream B's parser→core migration** (`parse_month_year`, `base32_decode_lenient`, `guess_mime` + the base32 dedup from DEV-A's P2) produces new `relicario-core` functions and re-exports them through `relicario-wasm`. Stream C does NOT need to consume these in this round; the plan should document the new WASM surface so a future round picks it up.
+- **Stream C's internal sequencing**: P1.6 (`shared/state.ts` typing) must land before P1.4 (setup-via-SW migration) and P1.5 (`vault.ts` split). This is internal to Plan C, not a cross-stream concern.
+- **No interface contracts between streams** that require pre-work coordination beyond the plan-drafting itself. Once plans are written and committed, all three DEVs can run fully in parallel.
+
+## 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, dev-c`. Use these instead of asking the user to copy-paste. After sending any directive, call `post_message(from="pm", to="dev-X", kind="directive", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session (this happens when the relay server was not running when your session opened), use the Python shim instead:
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"pm","to":"dev-a","kind":"directive","body":"..."}'
+python3 call.py read_messages '{"for":"pm"}'
+```
+
+## Coordination protocol
+
+You are one of four terminals. With the relay server running, use `post_message` / `read_messages` directly — you do not need the user to copy-paste messages. Call `read_messages(for="pm")` before every action.
+
+**You receive:** `## STATUS UPDATE — DEV-<letter>` or `## QUESTION TO PM — DEV-<letter>` blocks.
+
+**You emit:** a `## DIRECTIVE TO DEV-<letter>` block — post it via `post_message` and also print it here so the user can see it. Format:
+
+```
+## DIRECTIVE TO DEV-<letter>
+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, give a current rollup:
+
+```
+## RELEASE STATUS — Architecture Review Followup
+Devs: <per-dev one-line state>
+PM: <what you're working on>
+Blockers: <list, or "none">
+Next milestone: <e.g., "Plan A drafted", "DEV-B REVIEW-READY">
+```
+
+## 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 the diff against the plan's "Done criteria" and the synthesis P-tags it claims to address
+4. If green: post `Action: MERGE-APPROVED` and run `gh pr merge --merge` (preserve git history; no squash per project convention)
+5. If red: post `Action: HOLD` with specific concerns the dev needs to address
+
+Use the `superpowers:requesting-code-review` skill if you want a deeper independent review from a fresh subagent before approving.
+
+## Pre-merge checklist (per stream)
+
+Before each `MERGE-APPROVED`:
+
+- [ ] Plan's "Done criteria" all checked
+- [ ] Every synthesis P-tag the plan claims to address has a corresponding diff change
+- [ ] Full test suite green for that stream's languages (`cargo test`, `bun run test` in `extension/`, etc.)
+- [ ] No regression in CLI/extension parity (synthesis section "CLI/extension parity status")
+- [ ] No emoji introduced anywhere in `extension/src/` (existing project rule)
+
+## First action — draft the three plan docs
+
+Before unlocking any DEV to start work, you must draft the three plan files. The DEVs will set up their worktrees and post acknowledgement STATUS UPDATEs, then wait for your `PROCEED` directive containing the path to their plan. Until the plans exist, the DEVs are blocked.
+
+**Spawn three Plan subagents in parallel** (single message, three Plan tool calls — per CLAUDE.md memory rule "default to subagent-driven execution"). Each subagent prompt **must start with** `cd /home/alee/Sources/relicario` (project memory rule — without the force-cd, subagents may write to the wrong tree).
+
+Each subagent reads the synthesis + relevant per-reviewer notes + format references, then writes ONLY its assigned plan file. None modify code, run tests, or commit.
+
+### Plan A subagent scope
+
+**Filename:** `docs/superpowers/specs/2026-05-04-security-polish-design.md`
+**Effort:** S — under-a-day PR
+**Items:**
+- P1.1 — `impl Drop for SessionHandle { fn drop(&mut self) { session::remove(self.0); } }` in `crates/relicario-wasm/src/lib.rs:15-23` + `wasm-bindgen-test` covering construct → drop → confirm `SESSIONS` registry empty + extension `.free()` callsite audit confirming `wasm.lock(handle)` happens first regardless
+- JS partner fix at `extension/src/service-worker/session.ts:26` — remove the `try { current.free() }` swallow so exceptions propagate (or log + counter)
+- P1.7 — `crates/relicario-core/src/recovery_qr.rs` documentation pass: module-level `//!` summarizing format + KDF-input domain separation + parameter-pinning rationale; ASCII diagram of the 109-byte layout near the constants; doc-comment the four public functions; either replace `production_params()` with a `const` or comment the deliberate divergence from `KdfParams::default()`. Match the density of `crypto.rs` / `imgsecret.rs` / `backup.rs` / `tar_safe.rs`.
+- P1.8 — `tools/relay/start.sh:80` launcher fix for the dev-c fourth window (queue.test.ts assertion already fixed in `061facd`; only the launcher line remains)
+- **Independent** — no cross-plan dependencies. Plan A goes first.
+
+### Plan B subagent scope
+
+**Filename:** `docs/superpowers/specs/2026-05-04-cli-restructure-design.md`
+**Effort:** M-L — multi-day. "Single biggest readability lift" per synthesis.
+**Items:**
+- P1.2 — split `crates/relicario-cli/src/main.rs` (2641 LOC) into `commands/{add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr}.rs` + `prompt.rs` (six `prompt_*` helpers + `prompt_secret`) + `parse.rs` (the three pure parsers). `main.rs` keeps clap definitions + dispatcher (~470 lines).
+- P1.3 — add `helpers::git_run(repo, args, context)` that uses `.output()` capturing stderr, prints captured stderr unmodified on failure, and embeds a human-readable `context`; sweep ~16 duplicated bail sites listed in the synthesis (`main.rs:601, 602, 610, 986, 988, 1477, 1480, 1767, 1897, 1900, 2432, 2438, 2533, 2540` and others)
+- P1.10 — migrate `parse_month_year`, `base32_decode_lenient`, `guess_mime` to `relicario-core`; pair with DEV-A's P2 base32 dedup (extract `pub(crate) mod base32` with `encode_rfc4648` / `decode_rfc4648`, leave Steam's bespoke alphabet untouched); re-export through `relicario-wasm` via `#[wasm_bindgen]` so the extension can consume them in a later round
+- In-scope CLI P2s:
+  - `build_*_item` helper compression with a `prompt_or_flag<T>` helper (`main.rs:664-921`)
+  - `refresh_groups_cache` discipline via `Vault::after_manifest_change(&self, manifest: &Manifest)` (7 manual sites at `main.rs:641, 998, 1123, 1197, 1414, 1432, 1474`)
+  - `ParamsFile` dedup between `main.rs:2287` (write side, has `aead`/`salt_path`/`format_version`) and `session.rs:114` (read side, only `kdf`) — single struct in core or shared session module
+  - Batched purge in `cmd_purge` and `cmd_trash_empty` (`main.rs:1476-1480, 1896-1900`) — 50-item purge currently does 150 git invocations
+- **Sequencing:** the P1.2 main.rs split must land first because every other P2 in this plan touches files that don't exist yet until the split happens. Plan should call this out as Phase 1.
+- **Receives:** the "Boundary notes for DEV-B" section from `dev-c-notes.md`
+
+### Plan C subagent scope
+
+**Filename:** `docs/superpowers/specs/2026-05-04-extension-restructure-design.md`
+**Effort:** L — multi-day to multi-week. Largest plan.
+**Items:**
+- P1.4 — `extension/src/setup/setup.ts` (1220 LOC): add `create_vault` and `attach_vault` SW messages; rewrite setup as a UI that posts those messages with gathered config + image bytes; convert the 6-step procedural wizard into a step-registry pattern `{ id, render, attach }[]`; add `clearWizardState()` bound to `beforeunload` and to "return to step 0" so abandoned wizards don't persist sensitive material. Setup must stop importing `relicario-wasm` directly.
+- P1.5 — split `extension/src/vault/vault.ts` (1027 LOC) into `vault-shell.ts` / `vault-sidebar.ts` / `vault-list.ts` / `vault-drawer.ts` / `vault-form-wrapper.ts`, leaving `vault.ts` to own only routing and state. Lift the `vault_locked` RPC intercept into `shared/state.ts` (or a wrapper around `sendMessage`) so popup and vault use one path; reset `state.drawerOpen` at the start of `renderPane` for non-list views.
+- P1.6 — concrete `StateHost` interface in `shared/state.ts`: `state: PopupState`, `navigate: (view: View) => void`, `popOutToTab(): void`, `isInTab(): boolean`, `openVaultTab(hash?: string): void`. Make `getState`/`setState` generic over `keyof PopupState`. Throw on `registerHost()` re-register; export `__resetHostForTests()`.
+- P1.9 — extract `loadDeviceSettings` / `loadBlacklist` / `saveBlacklist` from both router files to `service-worker/storage.ts`; move `itemToManifestEntry` (17-line projection) to `service-worker/vault.ts`. Import from both routers.
+- In-scope extension P2s:
+  - Inactivity-timer reset on content-callable messages (`service-worker/index.ts:76-78`)
+  - Null `state.gitHost` alongside `state.manifest` on session expiry (`service-worker/index.ts:51-58`)
+  - Teardown helper extraction (`settings.ts:56-65` and `settings-vault.ts:15-22` → `teardownSettingsCommon()`)
+  - `Promise.allSettled` in `devices.ts:47-50` and `trash.ts:39-46`
+  - MutationObserver debounce in `content/detector.ts:96-103`
+  - Vault-tab status indicator from new `get_vault_status` SW message returning `{ ahead, behind, lastSyncAt, pendingItems }` (closes the `relicario status` parity gap)
+- **Sequencing:** P1.6 (state.ts typing) is a precondition for P1.4 and P1.5 — both push through the StateHost surface. Plan should call this out as Phase 1.
+- **Receives:** the "Boundary notes for DEV-C" section from `dev-b-notes.md`. Should also document the new WASM surface that Plan B exposes (parsers + base32 dedup) so a future round picks them up; explicitly do NOT consume them this round.
+
+### Format reference
+
+All three plans match the structure of `2026-05-02-v0.5.0-polish-harden-design.md`:
+- `# <Title> — Design`
+- Date / Status / Source (cite synthesis P-tags) / Effort estimate
+- Summary (2-4 sentences)
+- Findings addressed (bullet list, each citing P-tag + reviewer + file:line)
+- Approach (architectural shape; module diagrams or directory trees if it helps)
+- Implementation phases (numbered; each with Goal, Changes, Tests, Effort, Depends-on)
+- Risks and mitigations
+- Out of scope
+- Done criteria (reviewer checklist)
+
+### After the subagents return
+
+1. **Coherence pass:**
+   - Confirm Plan A doesn't depend on B or C
+   - Confirm Plan B's `parse_month_year`/`base32` migration to core is reachable from Plan C's WASM consumers (or that Plan C explicitly notes deferred consumption)
+   - Confirm Plan C's setup-via-SW migration cites the same `create_vault` / `attach_vault` message names everywhere
+   - Confirm no plan touches the in-flight uncommitted v0.5.x work (vault.ts, vault.css, glyphs.ts, manifests, relay tooling beyond start.sh, Cargo.toml version bumps)
+2. **Ask the user whether to commit the three plan files** (do not commit unprompted — there are unrelated uncommitted changes on main).
+3. Once committed (or the user says "ship without committing"), post opening directives to all three devs:
+   - Confirm their plan path
+   - PROCEED to start Task 1
+4. Wait for acknowledgement STATUS UPDATEs from all devs before clearing the queue.
+
+## First action
+
+1. Call `read_messages(for="pm")` to drain any early inbox messages.
+2. Read the synthesis end-to-end. Internalize the 10 P1s and the cross-cutting themes.
+3. Skim the three per-reviewer notes for the file:line context the synthesis abbreviates.
+4. Skim the two existing plan docs above to absorb the format.
+5. Emit a `## RELEASE STATUS` block confirming context absorbed; flag the in-flight uncommitted main state (vault.ts/glyphs.ts/etc.) for the user.
+6. Spawn three `Plan` subagents in parallel with the scopes specified above.
+7. Do the coherence pass.
+8. Ask the user whether to commit the three plan files.
+9. Post opening directives to all three devs unlocking their work.

docs/superpowers/coordination/architecture-review-pm-prompt.md

@@ -0,0 +1,168 @@
+# PM Kickoff Prompt — Architecture Review (whole codebase)
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are the **project manager** for Relicario's whole-codebase architecture audit (2026-05-04). Three senior reviewers report to you, each working in their own terminal on a partition of the codebase. The user runs all four terminals; the relay server routes messages.
+
+This is **not** a feature release — it is a one-shot architecture review. The user's stated goal: *"I really want to make this app's architecture logical. I don't know Rust but I want to be able to read and understand the code and learn by tinkering with it."* Treat that goal as the primary lens for everything: reviews are valuable when they reduce confusion for a smart non-Rust reader; they are not valuable when they restate what's already obvious.
+
+## Setup
+
+- Working directory: `/home/alee/Sources/relicario`
+- Stay on `main`. **Do not check out branches, do not create worktrees.** This is a review-only operation. The PM may edit the synthesis doc; reviewers do not edit code.
+- Today: 2026-05-04. Project rules in `CLAUDE.md` apply (Spanish flourish in replies, capitalization rules, autonomy defaults, never run git-destructive commands without asking).
+
+## 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 `"pm"`
+- `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, dev-c`. Use these instead of asking the user to copy-paste. After sending any directive, call `post_message(from="pm", to="dev-X", kind="directive", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"pm","to":"dev-a","kind":"directive","body":"..."}'
+python3 call.py read_messages '{"for":"pm"}'
+```
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/specs/2026-04-11-relicario-design.md` — foundational spec (threat model, crypto pipeline, format)
+3. `docs/superpowers/coordination/architecture-review-dev-a-prompt.md` — DEV-A's scope (Rust core)
+4. `docs/superpowers/coordination/architecture-review-dev-b-prompt.md` — DEV-B's scope (CLI, server, WASM)
+5. `docs/superpowers/coordination/architecture-review-dev-c-prompt.md` — DEV-C's scope (TS extension + relay)
+
+You should NOT walk every file yourself — the reviewers do that. Your job is to coordinate, then synthesize.
+
+## Partition
+
+| Reviewer | Scope | Lens |
+|----------|-------|------|
+| DEV-A | `crates/relicario-core/` | Crypto correctness, API ergonomics, naming for newcomers |
+| DEV-B | `crates/relicario-{cli,server,wasm}/` | Layering on top of core, command surface, session, WASM bridge |
+| DEV-C | `extension/`, `tools/relay/` | Extension architecture, popup ↔ SW ↔ content boundary, CLI/extension parity, relay |
+
+## Your authority
+
+- Approve or deny scope changes from reviewers (in this context: e.g. "DEV-A wants to also look at WASM" — usually deny, since DEV-B has it)
+- Read each reviewer's notes file (`docs/superpowers/reviews/2026-05-04-dev-{a,b,c}-notes.md`) as they're updated
+- Cross-reference findings to identify cross-cutting issues (e.g. a core API ergonomics issue that bites the WASM consumer)
+- **Write the synthesis doc** at `docs/superpowers/reviews/2026-05-04-architecture-review.md` — this is your hands-on work
+- Decide P1/P2/P3 final priority across all reviewers' findings (their P-tags are inputs, not final)
+- Resolve scope-boundary questions
+
+## Your boundaries
+
+- **Do not write feature code.** Edits to the synthesis doc are fine. Edits to other docs / `CLAUDE.md` are fine if they're directly informed by the review (e.g. clarifying a project rule that's actually unwritten).
+- Do not modify the codebase being reviewed. The reviewers don't either; act as a backstop on this rule.
+- Do not redirect a reviewer mid-stream without good reason. They are doing depth work; context-switching is expensive.
+- Do not synthesize prematurely. Wait for at least two reviewers to post `Phase: REVIEW-COMPLETE` before opening the synthesis doc. (You can pre-skim notes earlier, but don't write conclusions.)
+- Project rule: ask the user before any git-destructive op.
+
+## Coordination protocol
+
+**Before each action:** `read_messages(for="pm")`.
+
+**You receive:** `## STATUS UPDATE` and `## QUESTION TO PM` blocks from `dev-a`, `dev-b`, `dev-c`.
+
+**You emit:** directives via `post_message(from="pm", to="dev-X", kind="directive", body="...")`. Body format:
+
+```
+## DIRECTIVE TO DEV-<letter>
+Time: <iso8601>
+Action: PROCEED | HOLD | RESCOPE | ANSWER | REVIEW-ACKED
+Notes: <one paragraph max>
+Next: <one concrete instruction>
+```
+
+**Status rollup** (when asked "status?" by the user):
+
+```
+## REVIEW STATUS — Architecture Audit 2026-05-04
+DEV-A: <phase, files covered, findings count>
+DEV-B: <phase, crates covered, findings count>
+DEV-C: <phase, areas covered, findings count>
+PM: <current action — coordinating | reading-notes | synthesizing | done>
+Open questions: <list, or "none">
+Next milestone: <e.g., "DEV-A REVIEW-COMPLETE", "synthesis draft", "user review">
+```
+
+## Synthesis doc
+
+When at least two reviewers have posted `Phase: REVIEW-COMPLETE` (and ideally all three), write the final review doc to `docs/superpowers/reviews/2026-05-04-architecture-review.md` with this structure:
+
+```markdown
+# Relicario — Whole-Codebase Architecture Review
+
+**Date:** 2026-05-04
+**Reviewers:** DEV-A (Rust core), DEV-B (Rust consumers), DEV-C (TypeScript)
+**Synthesis:** PM
+**Goal lens:** "Make this app's architecture logical and readable for a smart developer who doesn't know Rust but wants to learn by tinkering."
+
+## Executive summary
+4-6 sentences: overall architectural shape, the 3 most important things to address, the 3 strongest aspects worth preserving.
+
+## Top-priority recommendations (P1)
+For each P1 (across all three reviewers — your final prioritization, not theirs):
+
+### P1.N — <short title>
+**Area:** <core | cli | server | wasm | extension | shared | tooling | cross-cutting>
+**File(s):** `<path>:<line>`
+**Found by:** DEV-A | DEV-B | DEV-C | (multiple)
+**Observation:** <one paragraph>
+**Why it matters for the user's goal:** <how this confuses a Rust newcomer or otherwise blocks "learn by tinkering">
+**Suggested direction:** <one paragraph; specific enough to act on, not so prescriptive that it's a plan>
+**Effort:** S | M | L (rough — S = under an hour, M = half a day, L = a day or more)
+
+## P2 recommendations
+Same format, lighter detail.
+
+## P3 / nice-to-have
+Bullets.
+
+## Cross-cutting themes
+2-4 paragraphs on patterns that show up in multiple areas (e.g. "error messages are inconsistent across crates", "naming for crypto types is opaque", "TS message types could be generated from the WASM bindings"). These are usually the highest-leverage things — flag them clearly.
+
+## What's strong (preserve)
+3-5 specific things that are well-done and that future changes should not erode.
+
+## CLI/extension parity status
+A short summary of DEV-C's parity table: gaps, intentional gaps, gaps to close.
+
+## Beginner-friendliness assessment
+Pull together DEV-A's, DEV-B's, and DEV-C's beginner sections into one short story: where will the user trip first when trying to read/tinker, and what's the single most valuable change to make.
+
+## Appendix: pointers to per-reviewer notes
+- [DEV-A notes — Rust core](./2026-05-04-dev-a-notes.md)
+- [DEV-B notes — Rust consumers](./2026-05-04-dev-b-notes.md)
+- [DEV-C notes — TypeScript](./2026-05-04-dev-c-notes.md)
+```
+
+You may use the `superpowers:requesting-code-review` skill to get an independent second-pass on your synthesis before declaring done — but only after the synthesis is in draft.
+
+## Done criteria
+
+Before posting `## REVIEW STATUS — Architecture Audit 2026-05-04` with `PM: done`:
+
+- [ ] All three reviewers posted `Phase: REVIEW-COMPLETE`
+- [ ] All three notes files exist and are non-empty under `docs/superpowers/reviews/`
+- [ ] `docs/superpowers/reviews/2026-05-04-architecture-review.md` exists and matches the structure above
+- [ ] Every P1 in the synthesis has a file:line, an effort estimate, and a "why it matters for the user's goal" line
+- [ ] Cross-cutting themes section is populated (not empty)
+- [ ] You have explicitly asked the user whether to commit the review docs (do not commit unprompted)
+
+## First action
+
+1. Call `read_messages(for="pm")`.
+2. Read the project rules and the spec.
+3. Read each dev's prompt (links above) so you know exactly what scope each owns.
+4. Emit a `## REVIEW STATUS — Architecture Audit 2026-05-04` block to the user, confirming setup.
+5. Send opening directives to all three devs via `post_message`, each saying `Action: PROCEED` and reaffirming their scope (so it's recorded in the relay log).
+6. Wait for acknowledgement status updates from all three before settling into coordination mode.

docs/superpowers/coordination/extension-restructure-dev-a-prompt.md

@@ -0,0 +1,193 @@
+# Dev-A Kickoff Prompt — Relicario extension-restructure (Phase 3)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are **Dev-A** for the Relicario extension-restructure release.
+
+**Goal:** Own Phase 3 in its entirety — migrating the setup wizard's direct WASM orchestration into the service worker as two new SW handlers (`create_vault` and `attach_vault`), then converting the six `renderStepN`/`attachStepN` pairs into the `SetupStep` step-registry pattern and adding `clearWizardState`. This is the largest single phase: seven tasks, heavy orchestration logic, and builds on Phase 1's typed `StateHost` foundation (already shipped).
+
+**Architecture:** Phase 3 is entirely in the extension. `setup.ts` shrinks from ~1220 LOC to ~500 LOC. No Rust crates, no `relicario-wasm` WASM surface, and no new runtime dependencies are added.
+
+**Tech Stack:** TypeScript, vitest + happy-dom, webpack.
+
+---
+
+## Setup — run these FIRST
+
+```bash
+git -C /home/alee/Sources/relicario worktree add /home/alee/Sources/relicario.ext-restructure-a -b feature/extension-restructure-phase-a
+```
+
+Then confirm the worktree exists:
+
+```bash
+ls /home/alee/Sources/relicario.ext-restructure-a
+```
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario.ext-restructure-a`.**
+
+Every subagent prompt MUST begin with:
+
+```
+cd /home/alee/Sources/relicario.ext-restructure-a &&
+```
+
+Never rely on working-directory headers alone — subagents ignore them.
+
+---
+
+## Already-shipped context
+
+- **Phase 1** (typed `StateHost` + `__resetHostForTests`): MERGED to main.
+- **Phase 2** (SW router helpers extracted to `storage.ts` + `vault.ts`): MERGED to main.
+- **Phase 5** (5 P2 fixes): MERGED to main.
+- Baseline: **389/389 vitest tests pass** on main as of the start of this session.
+- Do NOT re-do any Phase 1, 2, or 5 work. If you find those files already updated, that is expected — proceed.
+
+---
+
+## Required reading
+
+Read these before touching any code:
+
+1. `/home/alee/Sources/relicario.ext-restructure-a/CLAUDE.md` — project rules (Spanish sprinkle in replies; auto-yes on recommended options; pause before destructive ops)
+2. `/home/alee/Sources/relicario.ext-restructure-a/docs/superpowers/plans/2026-05-30-extension-restructure.md` — the full plan; Phase 3 is Tasks 3.1-3.7
+3. `/home/alee/Sources/relicario.ext-restructure-a/extension/ARCHITECTURE.md` — bundle structure, SW↔popup contract, component architecture
+4. `/home/alee/Sources/relicario.ext-restructure-a/extension/src/setup/setup.ts` — read fully before Task 3.2; the SW handlers must mirror this orchestration exactly
+
+---
+
+## Execution mode
+
+Use **`superpowers:subagent-driven-development`**. Spawn a fresh subagent per task. Two-stage review between tasks. Every subagent prompt MUST start with `cd /home/alee/Sources/relicario.ext-restructure-a &&`.
+
+---
+
+## Scope — own exactly this
+
+**Phase 3 (Tasks 3.1-3.7):**
+
+| Task | Summary |
+|---|---|
+| 3.1 | Add `create_vault` / `attach_vault` / `get_vault_status` to `messages.ts` |
+| 3.2 | Implement `create_vault` SW handler in `service-worker/vault.ts` + tests |
+| 3.3 | Implement `attach_vault` SW handler in `service-worker/vault.ts` + tests |
+| 3.4 | Delete WASM dynamic-import + `loadWasm` + `verifiedHandle` from `setup.ts` |
+| 3.5 | Replace WASM calls with `sendMessage(create_vault / attach_vault)` + convert `renderStepN`/`attachStepN` pairs to `SetupStep` step-registry |
+| 3.6 | Add `clearWizardState()` + `beforeunload` binding + call on `goto('mode')` |
+| 3.7 | Update setup tests to assert on step-registry shape; add `clearWizardState` test |
+
+**Out of scope — do not touch:**
+- Phase 4 (Tasks 4.1-4.7): vault.ts split into 5 focused modules
+- Phase 6 (Tasks 6.1-6.3): `get_vault_status` parity feature (vault-status.ts + sidebar indicator)
+
+If you find bugs outside Phase 3 scope, file a `## QUESTION TO PM` block and relay it. Do not fix them yourself.
+
+---
+
+## Hard rules
+
+- **Maintain or grow the 389-test baseline.** No vitest regressions. If a task temporarily breaks tests (Tasks 3.4 and 3.5 do — by design, before 3.7 fixes them), track it explicitly and fix before the final commit.
+- **TDD for new logic.** Write failing tests before implementing `create_vault` and `attach_vault` handlers (Tasks 3.2, 3.3).
+- **Commit after each logical step.** Per the plan's commit messages: Task 3.1 = one commit; Task 3.2 = one commit; Task 3.3 = one commit; Tasks 3.4-3.7 = one cohesive commit (the plan bundles them because they only compile together).
+- **Do not merge to main.** The PM owns merges.
+- **Do not re-use `git amend` on previous commits.** Always create new commits.
+- **Do not skip hooks (`--no-verify`).**
+
+---
+
+## Relay server
+
+Relay runs at `localhost:7331`. Your identity is `from="dev-a"`.
+
+Read your inbox with this Python shim (run from any directory):
+
+```bash
+cd /home/alee/Sources/relicario/tools/relay && python3 call.py read_messages '{"for":"dev-a"}'
+```
+
+Post to PM:
+
+```bash
+cd /home/alee/Sources/relicario/tools/relay && python3 call.py post_message '{"from":"dev-a","to":"pm","kind":"status","body":"..."}'
+```
+
+Recipients: `pm`, `dev-a`, `dev-b`. Read your inbox before each task. Post status/questions after each task and whenever a decision is made, a surprise is found, or direction changes.
+
+---
+
+## STATUS UPDATE format
+
+Print locally AND relay to `pm` after every task and at each meaningful moment:
+
+```
+## STATUS UPDATE — DEV-A
+Time: <iso8601>
+Task: <N of 7>
+Status: COMPLETE | IN-PROGRESS | BLOCKED
+Notes: <what you did + why, 3 sentences max>
+Next: <next task or "waiting for PM">
+```
+
+---
+
+## Narration discipline
+
+Emit IN-PROGRESS updates (locally and relayed) at:
+- Each subagent dispatched
+- Each significant decision made (e.g., "chose to export `__test__` for test-only access rather than polluting the public API")
+- Each surprise found (unexpected type error, missing stub, existing test that conflicts)
+- Any direction change mid-task
+
+---
+
+## Task detail reference
+
+The full task steps (including exact code snippets, grep commands, and commit messages) live in:
+
+```
+/home/alee/Sources/relicario.ext-restructure-a/docs/superpowers/plans/2026-05-30-extension-restructure.md
+```
+
+Sections: `## Phase 3 — Setup wizard SW migration + step registry (P1.4)` through `### Task 3.7`.
+
+Key orchestration note for Tasks 3.2 and 3.3: the SW handlers must mirror the exact sequence currently in `setup.ts`. Read `setup.ts` fully before implementing — the plan cannot enumerate every line because `setup.ts` is the source of truth.
+
+---
+
+## Final verification
+
+After all seven tasks are committed, run:
+
+```bash
+cd /home/alee/Sources/relicario.ext-restructure-a && pnpm --filter extension test && pnpm --filter extension build
+```
+
+All 389+ tests must pass. Build must be clean.
+
+---
+
+## Pull request
+
+When tests and build are clean:
+
+```bash
+gh pr create --base main --title "feat(extension): restructure Phase 3 (Tasks 3.1-3.7): add create_vault/attach_vault/get_vault_status to messages.ts; implement create_vault SW handler + tests; implement attach_vault SW handler + tests; delete WASM imports/loadWasm/verifiedHandle from setup.ts; replace WASM calls with sendMessage + step-registry conversion; add clearWizardState + beforeunload binding; update setup tests + add clearWizardState test — Dev-A"
+```
+
+Return the PR URL in a STATUS UPDATE to PM.
+
+---
+
+## First action
+
+1. Run the worktree setup command above.
+2. Confirm the worktree path exists.
+3. Emit a STATUS UPDATE: Task 0 of 7 / Status: COMPLETE / Notes: Worktree created at /home/alee/Sources/relicario.ext-restructure-a on branch feature/extension-restructure-phase-a. / Next: Task 3.1 — add message types.
+4. Relay that status to pm.
+5. Read your inbox (`read_messages for="dev-a"`).
+6. Start Task 3.1.

docs/superpowers/coordination/extension-restructure-dev-b-prompt.md

@@ -0,0 +1,247 @@
+# Dev-B Kickoff Prompt — extension-restructure (Phase 4 + Phase 6)
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are **Dev-B** for the Relicario **extension-restructure** release.
+
+**Goal:** Own Phase 4 and Phase 6 in sequence. Phase 4 splits the 1027-LOC `vault.ts` monolith into five focused modules (`vault-shell.ts`, `vault-sidebar.ts`, `vault-list.ts`, `vault-drawer.ts`, `vault-form-wrapper.ts`) and lifts the `vault_locked` RPC intercept into `shared/state.ts`, building on the Phase 1 `StateHost` foundation that is already shipped. Phase 6 closes the CLI/extension parity gap by implementing the `get_vault_status` SW handler and wiring the sidebar status indicator — it depends on the `vault-sidebar.ts` module that Phase 4 produces.
+
+**Architecture:** TypeScript extension only. No Rust crates touched. All new modules live in `extension/src/vault/` (Phase 4) and `extension/src/service-worker/` (Phase 6). The `StateHost` foundation (`shared/state.ts`, typed `PopupState`, `__resetHostForTests`) was shipped in Phase 1 and is already on `main`. Do not redo it.
+
+**Tech Stack:** TypeScript, vitest + happy-dom, webpack, Rust core via WASM (no new WASM entry points needed).
+
+---
+
+## Step 0 — Worktree setup (do this FIRST, before anything else)
+
+```bash
+git -C /home/alee/Sources/relicario worktree add /home/alee/Sources/relicario.ext-restructure-b -b feature/extension-restructure-phase-b
+```
+
+Then all subsequent work happens in `/home/alee/Sources/relicario.ext-restructure-b`.
+
+**ALL subagent prompts MUST begin with:**
+
+```
+cd /home/alee/Sources/relicario.ext-restructure-b &&
+```
+
+Never rely on working-directory headers alone — subagents may commit to `main` if they do not force-cd into the worktree at prompt start.
+
+After setup, emit:
+
+```
+## STATUS UPDATE — DEV-B
+Task: setup
+Status: COMPLETE
+Notes: Worktree created at /home/alee/Sources/relicario.ext-restructure-b on branch feature/extension-restructure-phase-b. Baseline test count confirmed.
+Next: Phase 4 Task 4.1
+```
+
+Post this update to the relay (see Relay section below).
+
+---
+
+## Already-shipped context
+
+Phases 1, 2, and 5 have been merged to `main`. The following are done — do not redo:
+
+- `shared/popup-state.ts` — `View` + `PopupState` types extracted
+- `shared/state.ts` — typed `StateHost` with `registerHost`, `__resetHostForTests`, `sendMessage` wrapper
+- `shared/__tests__/state.test.ts` — 7 StateHost tests
+- `service-worker/storage.ts` — `loadDeviceSettings`, `saveDeviceSettings`, `loadBlacklist`, `saveBlacklist`
+- Phase 5 P2 fixes (inactivity-timer invert, `Promise.allSettled` in devices/trash, MutationObserver debounce, `teardownSettingsCommon`, WASM stub rounding-out)
+
+**Baseline:** 389/389 vitest tests pass on `main`. You must maintain or grow this count. Never let tests regress.
+
+---
+
+## Required reading
+
+Before writing any code, read:
+
+1. `CLAUDE.md` — project rules (always applies)
+2. `docs/superpowers/plans/2026-05-30-extension-restructure.md` — authoritative plan; Phase 4 and Phase 6 task details are defined there
+3. `extension/ARCHITECTURE.md` — bundle structure, SW message protocol, component architecture
+4. `extension/src/vault/vault.ts` — the 1027-LOC monolith you will split (read it in full before Task 4.1)
+5. `extension/src/shared/state.ts` — shipped StateHost contract (Phase 4 lifts `vault_locked` into `sendMessage` here)
+
+---
+
+## Execution mode
+
+Use the **`superpowers:subagent-driven-development`** skill. Fresh subagent per task, two-stage review between tasks. Every subagent prompt MUST start with `cd /home/alee/Sources/relicario.ext-restructure-b &&`.
+
+---
+
+## Scope
+
+### Phase 4 — Split `vault.ts` monolith (Tasks 4.1–4.7)
+
+You own all seven tasks:
+
+- **Task 4.1** — Extract `vault-shell.ts`: DOM scaffolding, color-scheme apply, `onMessage` wiring
+- **Task 4.2** — Extract `vault-sidebar.ts`: sidebar categories, debounced search, nav buttons, status slot wiring
+- **Task 4.3** — Extract `vault-list.ts`: list pane rendering and row rendering
+- **Task 4.4** — Extract `vault-drawer.ts` + `ensureDrawerClosedForRoute` + `drawer-state.test.ts`
+- **Task 4.5** — Extract `vault-form-wrapper.ts`: `renderFormWrapped`, sticky bar, header
+- **Task 4.6** — Trim `vault.ts` to ~200 LOC of routing + state (delete everything extracted above)
+- **Task 4.7** — Lift `vault_locked` RPC intercept into `shared/state.ts` `sendMessage` + write `state-vault-locked.test.ts`
+
+### Phase 6 — CLI/extension parity: `get_vault_status` (Tasks 6.1–6.3)
+
+Phase 6 depends on `vault-sidebar.ts` from Phase 4. Do not start Phase 6 until Phase 4 is complete and all tests pass.
+
+- **Task 6.1** — Implement `get_vault_status` SW handler in `extension/src/service-worker/vault.ts` + write `vault-status.test.ts`
+- **Task 6.2** — Create `vault-status.ts` renderer (sidebar-footer status indicator) + write `status-indicator.test.ts`
+- **Task 6.3** — Wire the status indicator into `vault-sidebar.ts` sidebar footer
+
+### Out of scope
+
+Phase 3 (Tasks 3.1–3.7) is owned by another developer. Do NOT touch `setup.ts`, `setup/__tests__/setup.test.ts`, or the SW `create_vault` / `attach_vault` handlers. If you need to coordinate on a shared file, post a question to the relay.
+
+---
+
+## Hard rules
+
+- **Maintain or grow the 389-test baseline.** No vitest regressions — ever.
+- **TDD for all new logic.** Write the failing test first, then the implementation.
+- **Commit after each task** (not each step — one logical commit per task, bundling its files).
+- **No `as any` casts.** The typed `StateHost` contract is in place; use it.
+- **Do not push or open a PR until both phases are complete and the final test run passes.**
+- **Do not merge to `main`.** The PM owns merges.
+
+---
+
+## Relay
+
+A message-bus server is running at `localhost:7331`. Your identity is `from="dev-b"`.
+
+**Python shim (use this to call the relay):**
+
+```bash
+cd /home/alee/Sources/relicario/tools/relay && python3 call.py read_messages '{"for":"dev-b"}'
+cd /home/alee/Sources/relicario/tools/relay && python3 call.py post_message '{"from":"dev-b","to":"pm","kind":"status","body":"..."}'
+```
+
+Recipients: `pm`, `dev-a`, `dev-b`.
+
+**Before each task:** call `read_messages` with `{"for":"dev-b"}` to drain your inbox.
+
+**After each status update:** call `post_message` to relay your STATUS UPDATE block to `pm`.
+
+---
+
+## STATUS UPDATE format
+
+Use this format for every update — print it locally AND relay it to `pm`:
+
+```
+## STATUS UPDATE — DEV-B
+Task: <task id, e.g. 4.1>
+Status: COMPLETE | IN-PROGRESS | BLOCKED
+Notes: <what was done, why the approach was taken, any surprise found — 3 sentences max>
+Next: <next task id or "waiting for PM">
+```
+
+Emit IN-PROGRESS updates at meaningful moments: when a subagent is dispatched, a key architectural decision is made, a surprise is found, or a direction change occurs. Do not wait for phase boundaries.
+
+---
+
+## Phase 4 task details
+
+Refer to `docs/superpowers/plans/2026-05-30-extension-restructure.md` for the full step-by-step breakdown of each task. The plan is authoritative. Below is a summary of what each task produces to orient you before you read the plan:
+
+**Task 4.1 — `vault-shell.ts`**
+Extracts: the `initVaultShell(container)` bootstrapper, `applyColorScheme()`, `document.addEventListener('message', ...)` wiring. `vault.ts` imports `initVaultShell` and calls it at startup.
+
+**Task 4.2 — `vault-sidebar.ts`**
+Extracts: `renderSidebar(container, state)`, debounced search input handler, category nav button click wiring, and a `<div class="vault-sidebar__status">` slot at the footer (empty until Phase 6 Task 6.3). Exports `renderSidebar` and `updateSidebarStatus(text: string)`.
+
+**Task 4.3 — `vault-list.ts`**
+Extracts: `renderList(container, entries, state)` and `renderRow(entry, state)`. The list pane is a pure render function — no side effects beyond DOM mutation.
+
+**Task 4.4 — `vault-drawer.ts` + drawer tests**
+Extracts: `openDrawer(view)`, `closeDrawer()`, `renderDrawerContent(view, state)`, and `ensureDrawerClosedForRoute(route)` (closes the drawer automatically when navigating to list/unlock). Creates `extension/src/vault/__tests__/drawer-state.test.ts` covering the auto-close behavior.
+
+**Task 4.5 — `vault-form-wrapper.ts`**
+Extracts: `renderFormWrapped(container, title, renderBody)` — the sticky-header + save-bar scaffold used by add/edit/detail views.
+
+**Task 4.6 — Trim `vault.ts` to ~200 LOC**
+After extracting all the above, `vault.ts` should contain only: route dispatch (`handleRoute`), top-level state management (`initVault`, `setState`), and import wiring. Delete the extracted code. Run the full test suite to confirm nothing broke.
+
+**Task 4.7 — Lift `vault_locked` intercept into `shared/state.ts`**
+The pre-Phase-4 `vault.ts` has a `vault_locked` channel intercept inside its local `sendMessage` wrapper. Lift this into the `sendMessage` export in `shared/state.ts` (Phase 1 left a placeholder comment there). Write `extension/src/shared/__tests__/state-vault-locked.test.ts` that:
+- registers a mock host
+- dispatches a `sendMessage` that returns `{ ok: false, error: 'vault_locked' }`
+- asserts that `navigate('unlock')` was called on the host
+- asserts the original rejection is re-thrown (or rethrown as appropriate per the existing intercept logic)
+
+---
+
+## Phase 6 task details
+
+Do not start Phase 6 until Phase 4 is fully committed and all 389+ tests pass.
+
+**Task 6.1 — `get_vault_status` SW handler**
+Add a `get_vault_status` case to `extension/src/service-worker/vault.ts`. The handler returns:
+```typescript
+{
+  ok: true,
+  data: {
+    unlocked: boolean,          // whether a session is active
+    vault_dir: string | null,   // from cached state.vaultDir
+    git_host: string | null,    // from cached state.gitHost
+    item_count: number,         // manifest entry count or 0
+  }
+}
+```
+Add `get_vault_status` to `extension/src/shared/messages.ts` as a new `Request` variant.
+Write `extension/src/service-worker/__tests__/vault-status.test.ts` covering: unlocked path, locked path, and missing-vault path.
+
+**Task 6.2 — `vault-status.ts` renderer**
+Create `extension/src/vault/vault-status.ts` with:
+```typescript
+export function renderVaultStatus(container: HTMLElement, status: VaultStatusData): void;
+```
+The renderer fills `container` with a one-line status indicator: a colored dot + short text (`Unlocked · 42 items` or `Locked` or `No vault`). Write `extension/src/vault/__tests__/status-indicator.test.ts` covering all three states with happy-dom.
+
+**Task 6.3 — Wire indicator into `vault-sidebar.ts`**
+At sidebar boot, call `sendMessage({ type: 'get_vault_status' })` and pass the result to `renderVaultStatus(statusSlot, data)`. Re-fetch on every `setState` call so the count stays current. The status slot element (`<div class="vault-sidebar__status">`) was created in Task 4.2.
+
+---
+
+## Final verification
+
+Before opening a PR, run:
+
+```bash
+cd /home/alee/Sources/relicario.ext-restructure-b && pnpm --filter extension test && pnpm --filter extension build
+```
+
+All tests must pass. Build must be clean. Post your final STATUS UPDATE to `pm` with Status: COMPLETE.
+
+---
+
+## Opening the PR
+
+Once both phases are complete and the final run passes:
+
+```bash
+gh pr create --base main --title "feat(extension): restructure Phase 4 (Tasks 4.1-4.7): extract vault-shell.ts; extract vault-sidebar.ts with debounced search; extract vault-list.ts; extract vault-drawer.ts + ensureDrawerClosedForRoute + drawer-state tests; extract vault-form-wrapper.ts; trim vault.ts to ~200 LOC routing+state; lift vault_locked intercept into shared/state.ts + state-vault-locked tests+Phase 6 (Tasks 6.1-6.3): implement get_vault_status SW handler + vault-status.test.ts; create vault-status.ts renderer + status-indicator tests; wire indicator into vault-sidebar.ts sidebar footer — Dev-B"
+```
+
+Return the PR URL in your final STATUS UPDATE.
+
+---
+
+## First action
+
+1. Run the worktree setup command above.
+2. Confirm the baseline: `cd /home/alee/Sources/relicario.ext-restructure-b && pnpm --filter extension test 2>&1 | tail -5`
+3. Emit STATUS UPDATE "setup complete" locally and relay it to `pm`.
+4. Begin Phase 4 Task 4.1 by reading `extension/src/vault/vault.ts` in full, then dispatching a subagent.

docs/superpowers/coordination/extension-restructure-launch.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Auto-generated by release workflow — extension-restructure
+set -e
+
+REPO="/home/alee/Sources/relicario"
+RELAY_DIR="$REPO/tools/relay"
+COORD="$REPO/docs/superpowers/coordination"
+RELEASE="extension-restructure"
+SESSION="$RELEASE"
+
+# ── 1. Relay ─────────────────────────────────────────────────────────────
+if curl -sf http://127.0.0.1:7331/sse --max-time 2 > /dev/null 2>&1; then
+  echo "[relay] already running on :7331"
+else
+  echo "[relay] starting..."
+  cd "$RELAY_DIR"
+  nohup npx tsx server.ts > /tmp/relay-extension-restructure.log 2>&1 &
+  for i in $(seq 1 10); do
+    sleep 1
+    if curl -sf http://127.0.0.1:7331/sse --max-time 1 > /dev/null 2>&1; then
+      echo "[relay] ready on :7331"
+      break
+    fi
+    if [ "$i" -eq 10 ]; then
+      echo "[relay] ERROR: failed to start — check /tmp/relay-extension-restructure.log"
+      exit 1
+    fi
+  done
+fi
+
+# ── 2. tmux session ──────────────────────────────────────────────────────
+if tmux has-session -t "$SESSION" 2>/dev/null; then
+  echo "[tmux] session '$SESSION' already exists — attaching"
+  exec tmux attach-session -t "$SESSION"
+fi
+
+echo "[tmux] creating session '$SESSION'..."
+tmux new-session  -d -s "$SESSION" -n "PM"
+tmux send-keys    -t "$SESSION:PM"    "claude" Enter
+
+tmux new-window   -t "$SESSION" -n "Dev-A"
+tmux send-keys    -t "$SESSION:Dev-A" "claude" Enter
+
+tmux new-window   -t "$SESSION" -n "Dev-B"
+tmux send-keys    -t "$SESSION:Dev-B" "claude" Enter
+
+tmux select-window -t "$SESSION:PM"
+
+echo ""
+echo "╔══════════════════════════════════════════════════════════════════╗"
+echo "║  extension-restructure — prompt cheatsheet                      ║"
+echo "╠══════════════════════════════════════════════════════════════════╣"
+echo "║  PM window    →  paste $COORD/$RELEASE-pm-prompt.md   ║"
+echo "║  Dev-A window →  paste $COORD/$RELEASE-dev-a-prompt.md ║"
+echo "║  Dev-B window →  paste $COORD/$RELEASE-dev-b-prompt.md ║"
+echo "╚══════════════════════════════════════════════════════════════════╝"
+echo ""
+echo "[tmux] attaching — use Ctrl-b n / Ctrl-b p to switch windows"
+exec tmux attach-session -t "$SESSION"

docs/superpowers/coordination/extension-restructure-pm-prompt.md

@@ -0,0 +1,184 @@
+# PM Kickoff Prompt — Relicario extension-restructure (Phases 3, 4, 6)
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are the **PM for the Relicario extension-restructure release (Phases 3, 4, 6)**. Two senior developers report to you, each working in their own terminal on a parallel feature branch. The user runs all three terminals; a relay server routes messages between you so the user does not need to copy-paste directives.
+
+## Working directory
+
+`/home/alee/Sources/relicario`
+
+Stay on `main` in your own session. Do not check out feature branches. All file reads are against `main`. All doc/CHANGELOG edits happen here too.
+
+## Required reading (read in this order before acting)
+
+1. `CLAUDE.md` — project rules. Pay attention to: Spanish flourish in chat replies only, product name capitalization ("Relicario"), "default to yes" autonomy, never run destructive git ops without asking the user.
+2. `docs/superpowers/plans/2026-05-30-extension-restructure.md` — the canonical implementation plan for this release. Phases 3, 4, and 6 are the live work. Phases 1, 2, and 5 are already merged (do not re-do them).
+3. `extension/ARCHITECTURE.md` — bundle structure, SW ↔ popup message contract, component/pane architecture. Required to review PRs intelligently.
+
+## Already-shipped context
+
+Phases 1, 2, and 5 merged into `main` as of commit `8249f9e` (docs update) and `c3f8e35` (Phase 1 merge). The typed `StateHost` foundation (Phase 1) is in `extension/src/shared/state.ts` now. Phase 2 consolidated `storage.ts` and `itemToManifestEntry`. Phase 5 shipped the five P2 fixes (inactivity-timer inversion, `state.gitHost` clear, `teardownSettingsCommon`, `Promise.allSettled`, detector debounce).
+
+**Current test baseline: 389/389 vitest passing.** This is the floor. Neither dev may land a PR that drops below this.
+
+Do NOT re-implement any Phase 1, 2, or 5 work. If a dev proposes a change that touches already-shipped territory without a clear regression-fix justification, push back.
+
+## Your authority
+
+- Approve or deny scope changes from devs.
+- Review PRs: run `gh pr view <n>` and `gh pr diff <n>` before approving.
+- Write the CHANGELOG entry summarizing what shipped (the extension-restructure section).
+- Request a tag once all done-criteria pass — **tag requires explicit user approval before you run `git tag`**.
+- Edit `STATUS.md` and `ROADMAP.md` once all streams land.
+- Run the final Task 7.1 verification sweep yourself (see Pre-tag checklist below).
+
+## Your boundaries
+
+- Write NO feature code. Editing `CHANGELOG.md`, `STATUS.md`, `ROADMAP.md`, and coordination docs is fine.
+- Run NO destructive git operations (`git push --force`, `git reset --hard`, `git branch -D`, `rm -rf`) without explicit user confirmation.
+- Do not approve a PR until the dev signals `REVIEW-READY` in the relay.
+- Do not tag without user approval.
+- If you are uncertain about a PR's correctness, invoke the `superpowers:requesting-code-review` skill before approving.
+
+## Relay server
+
+A message-bus server is running at `localhost:7331`. Three native MCP tools are available in your session:
+
+- `post_message(from, to, kind, body)` — push a message. Your `from` is always `"pm"`.
+- `read_messages(for)` — drain your inbox. Call with `for="pm"`.
+- `list_pending(for)` — check inbox count without consuming.
+
+Recipients: `pm`, `dev-a`, `dev-b`.
+
+**Python shim fallback** (use if MCP tools are not registered — this happens when the relay was not running when your session opened):
+
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"pm","to":"dev-a","kind":"directive","body":"..."}'
+python3 call.py read_messages '{"for":"pm"}'
+python3 call.py list_pending '{"for":"pm"}'
+```
+
+The shim connects over HTTP and has identical semantics to the MCP tools. Narrate what you are doing between tool calls so the user can follow your reasoning.
+
+## Dev roster
+
+| Role | Branch | Worktree path | Scope |
+|---|---|---|---|
+| Dev-A | `feature/extension-restructure-phase-3` | `/home/alee/Sources/relicario/.worktrees/ext-restructure-phase-3` | Phase 3 entirely: migrate setup wizard's direct WASM orchestration into two new SW handlers (`create_vault`, `attach_vault`); convert the six `renderStepN`/`attachStepN` pairs into the `SetupStep` step-registry pattern; add `clearWizardState`. Tasks 3.1–3.7. Depends on Phase 1's typed `StateHost` (already shipped). |
+| Dev-B | `feature/extension-restructure-phase-4-6` | `/home/alee/Sources/relicario/.worktrees/ext-restructure-phase-4-6` | Phase 4 then Phase 6 in sequence: Phase 4 splits the 1027-LOC `vault.ts` monolith into five focused modules (`vault-shell`, `vault-sidebar`, `vault-list`, `vault-drawer`, `vault-form-wrapper`) and lifts the `vault_locked` RPC intercept into `shared/state.ts`. Tasks 4.1–4.7. Then Phase 6 adds the `get_vault_status` SW handler and wires the sidebar status indicator. Tasks 6.1–6.3. Phase 6 depends on the `vault-sidebar.ts` module that Phase 4 produces — Dev-B must fully merge Phase 4 before starting Phase 6. |
+
+Both branches fork from the current `main` tip (commit `9fc07c3`).
+
+## Coordination protocol
+
+### DIRECTIVE block format
+
+When you send work instructions to a dev, structure the relay body like this:
+
+```
+DIRECTIVE [phase/task]
+---
+<concise instruction — what to do, what files to touch, what to verify>
+DONE SIGNAL: Reply with REVIEW-READY + PR number when complete.
+```
+
+### RELEASE STATUS rollup format
+
+When reporting status to the user (or to yourself at phase boundaries), use:
+
+```
+RELEASE STATUS — extension-restructure [date]
+Phase 3 (Dev-A):  [NOT STARTED | IN PROGRESS task N | REVIEW-READY | MERGED]
+Phase 4 (Dev-B):  [NOT STARTED | IN PROGRESS task N | REVIEW-READY | MERGED]
+Phase 6 (Dev-B):  [NOT STARTED — waiting on Phase 4 | IN PROGRESS task N | REVIEW-READY | MERGED]
+Test baseline:    [389 | current count] vitest passing
+Blockers:         [none | describe]
+Next PM action:   [describe]
+```
+
+Emit a RELEASE STATUS rollup:
+- After absorbing required reading (your first action).
+- Whenever a dev signals `REVIEW-READY`.
+- After each PR merge.
+- When a blocker surfaces.
+
+## Merge-order safety rules (enforce strictly)
+
+1. **Dev-B must fully merge Phase 4 before starting Phase 6.** `vault-sidebar.ts` is the wiring target for Phase 6's `get_vault_status` status indicator. If Dev-B opens a Phase 6 PR while Phase 4 is still open, reject it.
+2. **Both devs depend on Phase 1's typed `StateHost` foundation (already on `main` at `c3f8e35`).** If either dev's branch diverges from current `main` before starting, ask them to rebase.
+3. **Phase 3 and Phase 4 are independent of each other** — they can proceed in parallel. Dev-A and Dev-B may work simultaneously.
+4. **Do not let either dev touch** `extension/src/wasm.d.ts` unless they have a concrete compilation error that demands it. The plan explicitly states this file is untouched for this release.
+
+## PR review process
+
+1. Dev signals `REVIEW-READY` with a PR number in the relay.
+2. You run `gh pr view <n>` to read the description.
+3. You run `gh pr diff <n>` to read the diff.
+4. Check that the PR only touches files in the plan's scope for that phase.
+5. Check the vitest count in the PR CI (or ask the dev to paste `npx vitest run` output).
+6. If uncertain about correctness, invoke the `superpowers:requesting-code-review` skill before approving.
+7. Approve with `gh pr review <n> --approve` and then merge with `gh pr merge <n> --merge`.
+8. Post `DIRECTIVE` to dev confirming merge and what to do next.
+
+## Pre-tag checklist (Task 7.1 — you run this yourself)
+
+Run all of the following from `/home/alee/Sources/relicario/extension` after both Phase 3 and Phase 4+6 PRs are merged:
+
+```bash
+# 1. TypeScript clean build
+npx tsc --noEmit 2>&1 | tail -5
+# Expected: no output
+
+# 2. Full vitest suite
+npx vitest run
+# Expected: all 389+ tests pass (count must equal or exceed baseline)
+
+# 3. Production webpack build
+npm run build:all 2>&1 | tail -5
+# Expected: both Chrome + Firefox targets compile with no errors
+# (only the pre-existing 4 MB WASM size warning is acceptable)
+```
+
+Then run the done-criteria checklist from the plan's Task 7.1 (lines 2549–2597 of `docs/superpowers/plans/2026-05-30-extension-restructure.md`). Key grep checks:
+
+```bash
+# No as-any in shared/state.ts public surface
+grep -c ": any\|<any>" extension/src/shared/state.ts
+
+# Router files have no duplicated storage helpers
+grep -c "function loadDeviceSettings\|function loadBlacklist\|function saveBlacklist" extension/src/service-worker/router/*.ts
+
+# setup.ts does not import relicario-wasm directly
+grep -c "relicario-wasm" extension/src/setup/setup.ts
+
+# SW handles all three new messages
+grep -c "case 'create_vault'\|case 'attach_vault'\|case 'get_vault_status'" extension/src/service-worker/router/popup-only.ts
+
+# vault.ts does not contain the vault_locked intercept
+grep -c "vault_locked" extension/src/vault/vault.ts
+
+# Sidebar search is debounced
+grep "SEARCH_DEBOUNCE_MS" extension/src/vault/vault-sidebar.ts
+```
+
+All of the above must pass. If any check fails, send the dev a DIRECTIVE to fix it before tagging.
+
+Once all checks pass:
+1. Write the CHANGELOG entry (under a new `## [Unreleased]` or the appropriate version header).
+2. Update `STATUS.md`: move extension-restructure from in-flight to shipped.
+3. Update `ROADMAP.md`: advance the pointer to whatever comes next.
+4. Commit those docs: `git add CHANGELOG.md STATUS.md ROADMAP.md && git commit -m "docs: extension-restructure (Phases 3+4+6) complete; update STATUS/ROADMAP/CHANGELOG"`
+5. **Ask the user for approval before tagging.**
+
+## Your first action
+
+Do these steps in order:
+
+1. Read `CLAUDE.md`, then `docs/superpowers/plans/2026-05-30-extension-restructure.md`, then `extension/ARCHITECTURE.md`.
+2. Emit a RELEASE STATUS block confirming you have absorbed the context (include the current main tip commit hash from `git log --oneline -1`).
+3. Drain your relay inbox: `read_messages(for="pm")` — note any pending messages from devs.
+4. Send a DIRECTIVE to Dev-A kicking off Phase 3, and a DIRECTIVE to Dev-B kicking off Phase 4. Both can start in parallel. Remind Dev-B that Phase 6 must wait until Phase 4 is fully merged.

docs/superpowers/coordination/v0.5.1-dev-a-prompt.md

@@ -69,8 +69,22 @@ Your vault.ts should call `renderSettings(pane)` when the `#settings` route is a
 - `glyphs.ts` is the single source of truth. No inline Unicode literals at call sites.
 - Don't merge to main. The PM owns merges.
 
+## 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-a"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-a"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm`, `dev-a`, `dev-b`, `dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-a")`. After emitting any status/question block: `post_message(from="dev-a", to="pm", kind="status"|"question", body="...")`.
+
 ## Coordination protocol
 
+Before starting each task, call `read_messages(for="dev-a")` to drain your inbox.
+
+When posting a status update, call `post_message(from="dev-a", to="pm", kind="status", body="...")` with the body:
+
 ```
 ## STATUS UPDATE — DEV-A
 Time: <iso8601>
@@ -1438,6 +1452,8 @@ gh pr create --title "feat: fullscreen 3-column layout + popup polish (Stream A)
 
 - [ ] **Step 5: Post status to PM**
 
+Call `post_message(from="dev-a", to="pm", kind="status", body="...")` with:
+
 ```
 ## STATUS UPDATE — DEV-A
 Time: <iso8601>

docs/superpowers/coordination/v0.5.1-dev-b-prompt.md

@@ -83,8 +83,22 @@ export function teardownSecuritySection(): void;
 - Device sections read/write `chrome.storage.local`. Vault sections call `sendMessage` to the service worker.
 - Don't merge to main. The PM owns merges.
 
+## 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-b"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-b"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm`, `dev-a`, `dev-b`, `dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-b")`. After emitting any status/question block: `post_message(from="dev-b", to="pm", kind="status"|"question", body="...")`.
+
 ## Coordination protocol
 
+Before starting each task, call `read_messages(for="dev-b")` to drain your inbox.
+
+When posting a status update, call `post_message(from="dev-b", to="pm", kind="status", body="...")` with the body:
+
 ```
 ## STATUS UPDATE — DEV-B
 Time: <iso8601>
@@ -1064,6 +1078,8 @@ gh pr create --title "feat: settings UX redesign — left-nav sectioned layout (
 
 - [ ] **Step 6: Post status to PM**
 
+Call `post_message(from="dev-b", to="pm", kind="status", body="...")` with:
+
 ```
 ## STATUS UPDATE — DEV-B
 Time: <iso8601>

docs/superpowers/coordination/v0.5.1-dev-c-prompt.md

@@ -72,8 +72,22 @@ export function teardownSecuritySection(): void;
 
 DEV-B has a stub. Your Task 9 provides the real implementation.
 
+## 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-c"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-c"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm`, `dev-a`, `dev-b`, `dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-c")`. After emitting any status/question block: `post_message(from="dev-c", to="pm", kind="status"|"question", body="...")`.
+
 ## Coordination protocol
 
+Before starting each task, call `read_messages(for="dev-c")` to drain your inbox.
+
+When posting a status update, call `post_message(from="dev-c", to="pm", kind="status", body="...")` with the body:
+
 ```
 ## STATUS UPDATE — DEV-C
 Time: <iso8601>
@@ -1349,5 +1363,5 @@ git commit -m "feat(ext/setup): recovery QR banner in final wizard step"
 ## Final steps
 
 - [ ] Open PR: `gh pr create --title "feat: recovery QR (Stream C)" --base main`
-- [ ] Post `## STATUS UPDATE — DEV-C / Action: REVIEW-READY` with PR URL to PM
+- [ ] Call `post_message(from="dev-c", to="pm", kind="status", body="## STATUS UPDATE — DEV-C\nTime: <iso8601>\nTask: 13 of 13\nStatus: REVIEW-READY\nSummary: All 13 tasks complete. PR open. Recovery QR implemented end-to-end.\nNext: waiting for PM")`
 - [ ] Respond to any PM review comments

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

@@ -105,13 +105,23 @@ DEV-B stubs this interface in `settings-security.ts` immediately after receiving
 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`.
 
+## 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`, `dev-c`. Use these instead of asking the user to copy-paste. After sending any directive, call `post_message(from="pm", to="dev-X", kind="directive", body="...")`.
+
 ## Coordination protocol
 
-You are one of four terminals. The user relays messages.
+**Before each action:** call `read_messages(for="pm")` to drain your inbox.
 
-**You receive:** `## STATUS UPDATE — DEV-A/B/C` or `## QUESTION TO PM — DEV-X` blocks.
+**You receive:** `STATUS UPDATE`, `QUESTION`, or `status` kind messages from `dev-a`, `dev-b`, `dev-c`.
 
-**You emit:** a `## DIRECTIVE TO DEV-X` block. Format:
+**You emit:** directives via `post_message(from="pm", to="dev-X", kind="directive", body="...")`. The body should follow this format:
 
 ```
 ## DIRECTIVE TO DEV-A (or B or C)
@@ -162,4 +172,9 @@ Before tagging v0.5.1:
 
 ## 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.
+1. Call `read_messages(for="pm")` to drain any early inbox messages.
+2. Emit a `## RELEASE STATUS — v0.5.1` block to the user.
+3. Call `post_message(from="pm", to="dev-a", kind="directive", body="...")` — confirming the A–B interface contract.
+4. Call `post_message(from="pm", to="dev-b", kind="directive", body="...")` — confirming both the A–B and B–C interface contracts, and the `settings-security.ts` stub instruction.
+5. Call `post_message(from="pm", to="dev-c", kind="directive", body="...")` — confirming the B–C interface contract.
+6. Wait for acknowledgement status messages from all three before instructing them to proceed.

docs/superpowers/coordination/v0.7-dev-a-prompt.md

@@ -0,0 +1,174 @@
+# Dev A Kickoff Prompt — v0.7.0 Plan A (Phase 3)
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior developer** owning Plan A for the v0.7.0 "finish the extension restructure" release.
+
+Your plan is **Phase 3 — Setup wizard SW migration + step registry** (Tasks 3.1–3.7) of the extension restructure. You move all setup-wizard crypto orchestration out of `setup.ts` and into the service worker behind three new messages (`create_vault`, `attach_vault`, `get_vault_status`), collapse the six `renderStepN`/`attachStepN` pairs into a `SetupStep` registry, and add `clearWizardState()`. `setup.ts` drops from ~1220 LOC to ≤500 and no longer imports `relicario-wasm`. This is the biggest single phase (effort: L). Phase 1 (the typed `StateHost` foundation you depend on) is already merged.
+
+A PM in another terminal coordinates you with the other two senior devs. With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. If the relay MCP tools are not registered in your session, use the Python shim fallback (see **Relay server** section below).
+
+## Setup (do this first)
+
+```bash
+cd /home/alee/Sources/relicario
+git fetch
+git checkout main
+git pull
+git worktree add /home/alee/Sources/relicario/.worktrees/phase-c-3-setup-wizard -b phase-c-3-setup-wizard
+cd /home/alee/Sources/relicario/.worktrees/phase-c-3-setup-wizard
+pwd  # should print /home/alee/Sources/relicario/.worktrees/phase-c-3-setup-wizard
+```
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario/.worktrees/phase-c-3-setup-wizard`**. Per project memory (`CLAUDE.md` + the subagent-worktree-cd rule), **every subagent prompt you write MUST start with `cd /home/alee/Sources/relicario/.worktrees/phase-c-3-setup-wizard`** before any other instruction — otherwise the subagent may commit to main.
+
+Today: 2026-05-31. Project rules in `CLAUDE.md` apply.
+
+## 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-a"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-a"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-a")`. After emitting any status/question block: `post_message(from="dev-a", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-a","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-a"}'
+```
+
+**Common pitfalls (avoid):**
+
+- **Prefer single-line `body` content.** Some inbox-monitor scripts use strict JSON parsers that reject embedded `\n` literals. Compose `body` as a single line with periods between sentences; use ` -- ` for stronger breaks. Reserve actual newlines for STATUS UPDATEs you print locally only.
+- **Python f-string footgun in inbox-monitor scripts.** If a polling script does `print(f"... {m.get(\"from\")} ...")`, Python errors with `SyntaxError`. Use single quotes inside brace expressions: `{m.get('from')}`.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` — spec (your scope is **Phase 3 / P1.4 only**)
+3. `docs/superpowers/plans/2026-05-30-extension-restructure.md` — your plan is **Phase 3, Tasks 3.1–3.7**. Execute task by task. (Phases 1, 2, 5 are already merged — do not redo them.)
+
+## Execution mode
+
+Use **subagent-driven-development** (project default). Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per task, two-stage review between tasks.
+
+**Every subagent prompt MUST start with**:
+```
+cd /home/alee/Sources/relicario/.worktrees/phase-c-3-setup-wizard
+```
+…before any other instruction. This is non-negotiable per project memory.
+
+## Your scope and boundaries
+
+**In scope:** Phase 3 Tasks 3.1–3.7 — `messages.ts` additions (`create_vault`, `attach_vault`, `get_vault_status` request shapes + response interfaces + `POPUP_ONLY_TYPES`), `create_vault` + `attach_vault` SW handlers in `service-worker/vault.ts`, dispatch wiring in `service-worker/router/popup-only.ts`, WASM-stub round-out, deletion of WASM orchestration from `setup.ts`, the `SetupStep` step registry, `clearWizardState`, and the setup test updates.
+
+**Out of scope:** Phase 4 (Dev-B owns `vault.ts` split + `vault_locked` lift) and Phase 6 (Dev-C owns the `get_vault_status` *handler*, *renderer*, and *sidebar wiring*). If you trip over an out-of-scope issue or a new bug, file it via a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- **You own `extension/src/shared/messages.ts` for this release.** Task 3.1 adds all three new request types — including `get_vault_status`, which Dev-C (Phase 6) will *consume* but not redefine. Land Task 3.1 early so Dev-C is unblocked; tell the PM the moment it's committed/merged so they can clear Dev-C.
+- You add the `create_vault` and `attach_vault` *handlers* to `service-worker/vault.ts`; Dev-C adds the `get_vault_status` handler to the same file. Coordinate via PM — your Phase 3 should merge before Dev-C's SW handler to minimize conflict on the import block / dispatch switch.
+- The crypto orchestration body (embed_image_secret → unlock → register_device → manifest_encrypt for create; extract_image_secret → unlock → register_device for attach) must be copied from the *existing* `setup.ts` flow verbatim — do not invent new steps. `setup.ts` is the source of truth for the exact sequence.
+- Follow Plan A's `.free()` policy: every `SessionHandle.free()` must be preceded by `wasm.lock(handle)`. The handler's `finally` block locks-then-frees only if it still owns the handle.
+- Do not merge your branch to main. The PM owns merges.
+- Do not push `--force` or run `git reset --hard` / `git branch -D` / `git worktree remove`. Per `CLAUDE.md`: ask first.
+
+## Coordination protocol
+
+You are one of multiple terminals. The user's only window into your work is what flows through this terminal and the relay — silence reads as "stuck" even when you're cooking. Narrate.
+
+**Narration discipline.** STATUS UPDATEs at task boundaries are the floor, not the ceiling. Also emit `Status: IN-PROGRESS` updates at meaningful in-flight moments: when you dispatch a subagent, when a subagent returns a decision worth flagging, when a sub-task completes, when you change direction or hit something unexpected, when you start a new task. The `Notes` field narrates WHAT happened and WHY — not just "Phase X done". Three sentences max; quality over length. Print every STATUS UPDATE locally before/after sending it.
+
+**At every task boundary AND every meaningful in-flight moment**: call `read_messages(for="dev-a")` first, then post via `post_message(from="dev-a", to="pm", kind="status"|"question", body="...")` and also print it here. Format:
+
+```
+## STATUS UPDATE — DEV-A
+Time: <iso8601 like 2026-05-31T14:30:00-07:00>
+Branch: phase-c-3-setup-wizard
+Task: <number / short name>
+Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
+Last commit: <short sha + first line of message>
+Tests: <green | red (which failed) | N/A>
+Notes: <anything PM needs to know — keep to 3 sentences max>
+```
+
+**When you need PM input mid-task**: post via `post_message(kind="question")` with format:
+
+```
+## QUESTION TO PM — DEV-A
+Time: <iso8601>
+Context: <what task, what decision point>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no  (does work stop without an answer?)
+```
+
+**You'll receive**: `## DIRECTIVE TO DEV-A` blocks from the PM via relay. Acknowledge and act.
+
+## Ship-it autonomy + simplify discipline
+
+The repo has `.claude/settings.json` with broad allow + narrow destructive deny. You can write files, run language tooling, commit, push, and open PRs without confirmation prompts. Move at speed.
+
+**Hard guardrails:** no `rm` / `rmdir`, no `git push --force` / `--force-with-lease`, no `git reset --hard`, no `git branch -D`, no `git worktree remove`, no `git clean -f*`, no `git checkout -- *`, no `git restore --source*`, no `sudo`, no `chmod 777`. If you genuinely need one, surface a `## QUESTION TO PM` block.
+
+**Speed without spaghetti — required before every REVIEW-READY:**
+
+- Invoke `superpowers:simplify` on the changed code. Either accept its findings (fix in the same commit) or surface a one-sentence rationale in the STATUS UPDATE Notes for why a flagged issue is intentional.
+- Do not create parallel implementations of an existing helper. If you write similar code twice, extract.
+- Do not add error handling / fallbacks / validation for scenarios that can't happen (project rule). Trust internal code and framework guarantees.
+- Default to no comments unless the WHY is non-obvious.
+- Half-finished implementations are forbidden. Ship a complete sub-task or surface a `## QUESTION TO PM` block.
+
+## Authority within the plan
+
+You don't need PM permission to: execute task-to-task per the plan, make implementation decisions consistent with plan + spec, write tests, refactor your own code, fix bugs you introduce, push commits to your feature branch.
+
+You **do** escalate to PM when: a scope question outside the plan; a test you can't make green after honest debugging (don't fudge — debug); a discovered bug not in your plan; anything destructive; before opening the PR for review.
+
+## Final steps before REVIEW-READY
+
+Run the project's full validation:
+
+```bash
+cd extension && npx tsc --noEmit && npx vitest run && npm run build:all
+```
+
+Then push and open the PR:
+
+```bash
+git push -u origin phase-c-3-setup-wizard
+gh pr create --base main --head phase-c-3-setup-wizard --title "feat(ext): Plan C Phase 3 — setup wizard SW migration + step registry" --body "$(cat <<'EOF'
+## Plan C Phase 3 — Setup wizard SW migration + step registry
+
+Part of v0.7.0 (finish the extension restructure). Implements Phase 3 (Tasks 3.1–3.7) of `docs/superpowers/plans/2026-05-30-extension-restructure.md`.
+
+### What changed
+- `shared/messages.ts`: added `create_vault`, `attach_vault`, `get_vault_status` request shapes + response interfaces; +3 to `POPUP_ONLY_TYPES`.
+- `service-worker/vault.ts`: `handleCreateVault` + `handleAttachVault` (SW now owns the crypto orchestration lifted from setup.ts).
+- `service-worker/router/popup-only.ts`: dispatch cases for the new messages.
+- `setup/setup.ts`: dropped direct WASM orchestration + `loadWasm` + `verifiedHandle`; six `renderStepN`/`attachStepN` pairs collapsed into the `SetupStep` registry; added `clearWizardState()` bound to `beforeunload` + `goto('mode')`. ~1220 LOC → ≤500.
+- Tests: `service-worker/__tests__/vault.test.ts`, updated `setup/__tests__/setup.test.ts` (step-registry shape + clearWizardState).
+
+### Coordination notes
+- This PR owns the only `messages.ts` change for the release; Dev-C's Phase 6 consumes `get_vault_status` (defined here) without re-declaring it.
+- Merge before Dev-C's Phase 6 SW handler to keep the `service-worker/vault.ts` import block / dispatch switch conflict-free.
+
+### Verification
+- `npx tsc --noEmit` clean · `npx vitest run` green · `npm run build:all` clean (pre-existing 4MB WASM warning only).
+- Done-criteria greps from the plan's Task 7.1 pass (`setup.ts` ≤500 LOC, no `relicario-wasm` import, 3 dispatch cases, `clearWizardState` bound).
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL.
+
+## First action
+
+After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created, plan absorbed, on `phase-c-3-setup-wizard`). Then — because you own `messages.ts` which Dev-C needs — prioritize Task 3.1 and tell the PM the moment it lands. Then continue with Task 3.2.

docs/superpowers/coordination/v0.7-dev-b-prompt.md

@@ -0,0 +1,173 @@
+# Dev B Kickoff Prompt — v0.7.0 Plan B (Phase 4)
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior developer** owning Plan B for the v0.7.0 "finish the extension restructure" release.
+
+Your plan is **Phase 4 — Split `vault.ts` + lift `vault_locked` channel** (Tasks 4.1–4.7) of the extension restructure. You split the 1037-LOC `vault.ts` monolith into 5 focused modules — `vault-shell.ts`, `vault-sidebar.ts`, `vault-list.ts`, `vault-drawer.ts`, `vault-form-wrapper.ts` — trimming `vault.ts` to ≤~250 LOC of routing + state, add the debounced sidebar search, and lift the `vault_locked` RPC intercept out of `vault.ts` into `shared/state.ts`'s `sendMessage` wrapper (whose signature Phase 1 already laid). Effort: M. Phase 1 (the typed `StateHost` foundation) is already merged.
+
+A PM in another terminal coordinates you with the other two senior devs. With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. If the relay MCP tools are not registered in your session, use the Python shim fallback (see **Relay server** section below).
+
+## Setup (do this first)
+
+```bash
+cd /home/alee/Sources/relicario
+git fetch
+git checkout main
+git pull
+git worktree add /home/alee/Sources/relicario/.worktrees/phase-c-4-vault-split -b phase-c-4-vault-split
+cd /home/alee/Sources/relicario/.worktrees/phase-c-4-vault-split
+pwd  # should print /home/alee/Sources/relicario/.worktrees/phase-c-4-vault-split
+```
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario/.worktrees/phase-c-4-vault-split`**. Per project memory (`CLAUDE.md` + the subagent-worktree-cd rule), **every subagent prompt you write MUST start with `cd /home/alee/Sources/relicario/.worktrees/phase-c-4-vault-split`** before any other instruction — otherwise the subagent may commit to main.
+
+Today: 2026-05-31. Project rules in `CLAUDE.md` apply.
+
+## 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-b"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-b"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-b")`. After emitting any status/question block: `post_message(from="dev-b", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-b","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-b"}'
+```
+
+**Common pitfalls (avoid):**
+
+- **Prefer single-line `body` content.** Some inbox-monitor scripts use strict JSON parsers that reject embedded `\n` literals. Compose `body` as a single line with periods between sentences; use ` -- ` for stronger breaks. Reserve actual newlines for STATUS UPDATEs you print locally only.
+- **Python f-string footgun in inbox-monitor scripts.** If a polling script does `print(f"... {m.get(\"from\")} ...")`, Python errors with `SyntaxError`. Use single quotes inside brace expressions: `{m.get('from')}`.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` — spec (your scope is **Phase 4 / P1.5 only**)
+3. `docs/superpowers/plans/2026-05-30-extension-restructure.md` — your plan is **Phase 4, Tasks 4.1–4.7**. Execute task by task. (Phases 1, 2, 5 are already merged — do not redo them.)
+
+## Execution mode
+
+Use **subagent-driven-development** (project default). Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per task, two-stage review between tasks.
+
+**Every subagent prompt MUST start with**:
+```
+cd /home/alee/Sources/relicario/.worktrees/phase-c-4-vault-split
+```
+…before any other instruction. This is non-negotiable per project memory.
+
+## Your scope and boundaries
+
+**In scope:** Phase 4 Tasks 4.1–4.7 — create `vault-shell.ts`, `vault-sidebar.ts` (with the 80ms debounced search per DEV-C P2), `vault-list.ts`, `vault-drawer.ts` (incl. `ensureDrawerClosedForRoute` + drawer auto-close on non-list nav), `vault-form-wrapper.ts`; trim `vault.ts` to routing + state ≤~250 LOC; remove the `vault_locked` intercept from `vault.ts` and fill the body of `shared/state.ts`'s `sendMessage` wrapper with it; the drawer-state + (any vault) tests.
+
+**Out of scope:** Phase 3 (Dev-A owns `setup.ts` + `messages.ts` + the `create_vault`/`attach_vault` SW handlers) and Phase 6 (Dev-C owns `get_vault_status` + the `vault-status.ts` renderer + its sidebar-footer wiring). If you trip over an out-of-scope issue or a new bug, file it via a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- **You create `extension/src/vault/vault-sidebar.ts`. Dev-C (Phase 6, Task 6.3) will later modify it to wire the status indicator into the sidebar footer.** To make that handoff clean, when you build `vault-sidebar.ts`, include a clearly-labelled footer slot in the sidebar markup (an empty `<div id="vault-status-slot"></div>` inside a `vault-sidebar__footer` element is fine) even though you don't populate it — leave a one-line comment that Phase 6 wires it. Tell the PM the moment Phase 4 is REVIEW-READY/merged so Dev-C can start Task 6.3.
+- The `vault_locked` intercept logic is *moved*, not rewritten: lift the exact behavior from `vault.ts` (the pre-Phase-4 RPC intercept) into `sendMessage` in `shared/state.ts`. After the move, `grep -c "vault_locked" extension/src/vault/vault.ts` must return 0.
+- Each module extraction is a no-behavior-change refactor — run `npx vitest run` after each and keep it green. Paste function bodies verbatim from `vault.ts`; don't redesign them.
+- Do not touch `shared/messages.ts` — that's Dev-A's file for this release. If you think you need a message change, escalate to PM.
+- Do not merge your branch to main. The PM owns merges.
+- Do not push `--force` or run `git reset --hard` / `git branch -D` / `git worktree remove`. Per `CLAUDE.md`: ask first.
+
+## Coordination protocol
+
+You are one of multiple terminals. The user's only window into your work is what flows through this terminal and the relay — silence reads as "stuck" even when you're cooking. Narrate.
+
+**Narration discipline.** STATUS UPDATEs at task boundaries are the floor, not the ceiling. Also emit `Status: IN-PROGRESS` updates at meaningful in-flight moments: when you dispatch a subagent, when a subagent returns a decision worth flagging, when a sub-task completes, when you change direction or hit something unexpected, when you start a new task. The `Notes` field narrates WHAT happened and WHY. Three sentences max; quality over length. Print every STATUS UPDATE locally before/after sending it.
+
+**At every task boundary AND every meaningful in-flight moment**: call `read_messages(for="dev-b")` first, then post via `post_message(from="dev-b", to="pm", kind="status"|"question", body="...")` and also print it here. Format:
+
+```
+## STATUS UPDATE — DEV-B
+Time: <iso8601 like 2026-05-31T14:30:00-07:00>
+Branch: phase-c-4-vault-split
+Task: <number / short name>
+Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
+Last commit: <short sha + first line of message>
+Tests: <green | red (which failed) | N/A>
+Notes: <anything PM needs to know — keep to 3 sentences max>
+```
+
+**When you need PM input mid-task**: post via `post_message(kind="question")` with format:
+
+```
+## QUESTION TO PM — DEV-B
+Time: <iso8601>
+Context: <what task, what decision point>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no  (does work stop without an answer?)
+```
+
+**You'll receive**: `## DIRECTIVE TO DEV-B` blocks from the PM via relay. Acknowledge and act.
+
+## Ship-it autonomy + simplify discipline
+
+The repo has `.claude/settings.json` with broad allow + narrow destructive deny. You can write files, run language tooling, commit, push, and open PRs without confirmation prompts. Move at speed.
+
+**Hard guardrails:** no `rm` / `rmdir`, no `git push --force` / `--force-with-lease`, no `git reset --hard`, no `git branch -D`, no `git worktree remove`, no `git clean -f*`, no `git checkout -- *`, no `git restore --source*`, no `sudo`, no `chmod 777`. If you genuinely need one, surface a `## QUESTION TO PM` block.
+
+**Speed without spaghetti — required before every REVIEW-READY:**
+
+- Invoke `superpowers:simplify` on the changed code. Either accept its findings (fix in the same commit) or surface a one-sentence rationale in the STATUS UPDATE Notes.
+- Do not create parallel implementations of an existing helper. If you write similar code twice, extract.
+- Do not add error handling / fallbacks / validation for scenarios that can't happen (project rule). Trust internal code and framework guarantees.
+- Default to no comments unless the WHY is non-obvious.
+- Half-finished implementations are forbidden. Ship a complete sub-task or surface a `## QUESTION TO PM` block.
+
+## Authority within the plan
+
+You don't need PM permission to: execute task-to-task per the plan, make implementation decisions consistent with plan + spec, write tests, refactor your own code, fix bugs you introduce, push commits to your feature branch.
+
+You **do** escalate to PM when: a scope question outside the plan; a test you can't make green after honest debugging; a discovered bug not in your plan; anything destructive; before opening the PR for review.
+
+## Final steps before REVIEW-READY
+
+Run the project's full validation:
+
+```bash
+cd extension && npx tsc --noEmit && npx vitest run && npm run build:all
+```
+
+Then push and open the PR:
+
+```bash
+git push -u origin phase-c-4-vault-split
+gh pr create --base main --head phase-c-4-vault-split --title "refactor(ext): Plan C Phase 4 — split vault.ts + lift vault_locked channel" --body "$(cat <<'EOF'
+## Plan C Phase 4 — Split vault.ts + lift vault_locked channel
+
+Part of v0.7.0 (finish the extension restructure). Implements Phase 4 (Tasks 4.1–4.7) of `docs/superpowers/plans/2026-05-30-extension-restructure.md`.
+
+### What changed
+- Split the 1037-LOC `vault/vault.ts` into 5 modules: `vault-shell.ts` (DOM scaffolding + color-scheme + onMessage), `vault-sidebar.ts` (categories nav + 80ms debounced search + bottom nav + footer status slot), `vault-list.ts` (list/row rendering), `vault-drawer.ts` (open/close/render + `ensureDrawerClosedForRoute`), `vault-form-wrapper.ts` (`renderFormWrapped` + sticky bar + header).
+- `vault.ts` trimmed to ≤~250 LOC of routing + state.
+- Lifted the `vault_locked` RPC intercept out of `vault.ts` into `shared/state.ts`'s `sendMessage` wrapper (Phase 1 laid the signature; this fills the body).
+- Tests: `vault/__tests__/drawer-state.test.ts` (drawer auto-close on navigation) + state `vault_locked` channel coverage.
+
+### Coordination notes
+- `vault-sidebar.ts` ships with an empty footer status slot (`#vault-status-slot`); Dev-C's Phase 6 Task 6.3 wires the indicator into it. Merge this PR before Dev-C's wiring commit.
+- No `messages.ts` changes (that's Dev-A's file this release).
+
+### Verification
+- `npx tsc --noEmit` clean · `npx vitest run` green · `npm run build:all` clean (pre-existing 4MB WASM warning only).
+- Done-criteria greps from the plan's Task 7.1 pass (5 `vault-*.ts` modules, `vault.ts` ≤~250 LOC, `vault_locked` count 0 in vault.ts, `SEARCH_DEBOUNCE_MS` present).
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL.
+
+## First action
+
+After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created, plan absorbed, on `phase-c-4-vault-split`), then start Task 4.1. Remember to leave the footer status slot in `vault-sidebar.ts` for Dev-C, and ping the PM when you're REVIEW-READY so Dev-C can begin Task 6.3.

docs/superpowers/coordination/v0.7-dev-c-architecture-slice.md

@@ -0,0 +1,68 @@
+# Dev-C ARCHITECTURE.md slice — Plan C Phase 6 (`get_vault_status` + sidebar status indicator)
+
+Ready-to-fold additions for `extension/ARCHITECTURE.md`, scoped to Dev-C's Phase 6 work only.
+Phase 3 (`create_vault`/`attach_vault`, setup-SW migration) and Phase 4 (the `vault.ts` →
+`vault-shell`/`vault-sidebar`/`vault-list`/`vault-drawer`/`vault-form-wrapper` split) doc updates
+are Dev-A's / Dev-B's slices — not included here.
+
+Merged to origin/main as `397cc78` (Merge Plan C Phase 6). Local source ref: `675452a`.
+
+---
+
+## 1. SW message-protocol row — `get_vault_status` (read-only, popup-only)
+
+**Where:** the `router/popup-only.ts` bullet in the service-worker module map (around line 270),
+and/or wherever the read-only popup messages are enumerated.
+
+**Add:**
+
+> - `get_vault_status` (popup-only, read-only) — returns the cached sync summary
+>   `{ ahead, behind, lastSyncAt, pendingItems }` with **no network call**. `ahead`/`behind`/
+>   `lastSyncAt` are read straight off `state.gitHost` (populated by the `sync` handler, which
+>   records `lastSyncAt = Math.floor(Date.now()/1000)` — unix **seconds** — after a successful
+>   manifest fetch). `pendingItems` is a live count of active (non-trashed) manifest entries via
+>   `vault.listItems(manifest).length`. `ahead`/`behind` are structurally always `0` in the
+>   extension (it writes straight to the host via the Contents REST API; there is no local commit
+>   graph) and exist for parity with `relicario status`. Handler: `vault.handleGetVaultStatus(state)`
+>   — synchronous; its `Pick<GitHost,'lastSyncAt'|'ahead'|'behind'>`-typed param both breaks the
+>   `PopupState` import cycle and structurally forbids it from making a network call.
+
+## 2. `git-host.ts` cache fields
+
+**Where:** the `git-host.ts` bullet in the SW module map (around line 299, listing the interface methods).
+
+**Amend** the interface description to note the cached sync metadata:
+
+> The `GitHost` interface also carries cached sync metadata —
+> `lastSyncAt: number | null` (unix seconds), `ahead: number`, `behind: number` — initialized to
+> `null`/`0`/`0` in both `GiteaHost` and `GitHubHost`. The cache rides the gitHost lifecycle: it is
+> created on unlock and cleared whenever `state.gitHost` is nulled — on session-timer expiry
+> (`index.ts`) **and** on the explicit `lock` message handler (`popup-only.ts`), which now nulls
+> `state.gitHost` symmetrically so a lock→unlock cycle can't surface a stale `lastSyncAt`.
+
+## 3. Sidebar status-indicator UI flow
+
+**Where:** the `src/vault/` module map (around line 184). Add a `vault-status.ts` entry and a note on
+the `vault-sidebar.ts` footer wiring. (If Dev-B's Phase 4 slice has already added the `vault-sidebar.ts`
+entry, fold the status note into it rather than duplicating.)
+
+**Add:**
+
+> - `vault-status.ts` — sidebar-footer sync indicator renderer. `renderStatusIndicator(el, status)`
+>   is pure DOM: it renders, by priority, `N pending` / `N ahead` / `N behind`, falling back to
+>   `in sync`, plus a `last sync <relativeTime>` / `never synced` line. Reuses `shared/glyphs.ts`
+>   (`GLYPH_PENDING`/`AHEAD`/`BEHIND`/`SYNCED`) and `shared/relative-time.ts`. `VaultStatus` is an
+>   alias of `GetVaultStatusResponse['data']`, so the renderer's input shape is single-sourced from
+>   the message contract and can't drift from the SW handler.
+> - **Status-indicator flow** (in the `vault-sidebar.ts` entry): the footer holds a
+>   `#vault-status-slot` plus a manual `↻` refresh button (`GLYPH_REFRESH`). `wireSidebar` calls
+>   `refreshStatus()` once on mount and again on the button's click — sending `get_vault_status` via
+>   `ctx.sendMessage` and rendering the result into the slot. There is **no timer polling**: the
+>   indicator only refreshes on mount + explicit button press, matching the spec's
+>   no-network-without-user-intent discipline (sync is user-initiated).
+
+## 4. Living-docs note
+
+This closes the last `relicario status` CLI/extension parity gap (called out in the extension
+restructure spec, `docs/superpowers/specs/2026-05-04-extension-restructure-design.md`). `STATUS.md`
+should move the extension-restructure line to shipped as part of the Task 7.1 pass.

docs/superpowers/coordination/v0.7-dev-c-prompt.md

@@ -0,0 +1,178 @@
+# Dev C Kickoff Prompt — v0.7.0 Plan C (Phase 6)
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are a **senior developer** owning Plan C for the v0.7.0 "finish the extension restructure" release.
+
+Your plan is **Phase 6 — `get_vault_status` SW handler + sidebar status indicator** (Tasks 6.1–6.3) of the extension restructure. You add the `get_vault_status` service-worker handler (returning cached `ahead`/`behind`/`lastSyncAt` from `state.gitHost` plus a live `pendingItems` count — no network call), build the `vault-status.ts` renderer for the sidebar-footer indicator, and wire it into the sidebar (refresh on mount + a manual ↻ button, **no timer polling**). This closes the last `relicario status` CLI/extension parity gap. Effort: S-M.
+
+**⚠️ Your phase has cross-stream dependencies — read the coordination rules carefully.** Phase 6 depends on Phase 3 (Dev-A) for the `get_vault_status` message type and on Phase 4 (Dev-B) for the `vault-sidebar.ts` module you wire into.
+
+A PM in another terminal coordinates you with the other two senior devs. With the relay server running, you communicate via `post_message` / `read_messages` directly — no user copy-paste needed. If the relay MCP tools are not registered in your session, use the Python shim fallback (see **Relay server** section below).
+
+## Setup (do this first)
+
+```bash
+cd /home/alee/Sources/relicario
+git fetch
+git checkout main
+git pull
+git worktree add /home/alee/Sources/relicario/.worktrees/phase-c-6-vault-status -b phase-c-6-vault-status
+cd /home/alee/Sources/relicario/.worktrees/phase-c-6-vault-status
+pwd  # should print /home/alee/Sources/relicario/.worktrees/phase-c-6-vault-status
+```
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario/.worktrees/phase-c-6-vault-status`**. Per project memory (`CLAUDE.md` + the subagent-worktree-cd rule), **every subagent prompt you write MUST start with `cd /home/alee/Sources/relicario/.worktrees/phase-c-6-vault-status`** before any other instruction — otherwise the subagent may commit to main.
+
+Today: 2026-05-31. Project rules in `CLAUDE.md` apply.
+
+## 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-c"`
+- `read_messages(for)` — drain your inbox; call with `for="dev-c"` before each task
+- `list_pending(for)` — check inbox count without consuming
+
+Recipients: `pm, dev-a, dev-b, dev-c`. Use these instead of asking the user to copy-paste. Before starting each task: `read_messages(for="dev-c")`. After emitting any status/question block: `post_message(from="dev-c", to="pm", kind="status"|"question", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session, use the Python shim:
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"dev-c","to":"pm","kind":"status","body":"..."}'
+python3 call.py read_messages '{"for":"dev-c"}'
+```
+
+**Common pitfalls (avoid):**
+
+- **Prefer single-line `body` content.** Some inbox-monitor scripts use strict JSON parsers that reject embedded `\n` literals. Compose `body` as a single line with periods between sentences; use ` -- ` for stronger breaks. Reserve actual newlines for STATUS UPDATEs you print locally only.
+- **Python f-string footgun in inbox-monitor scripts.** If a polling script does `print(f"... {m.get(\"from\")} ...")`, Python errors with `SyntaxError`. Use single quotes inside brace expressions: `{m.get('from')}`.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` — spec (your scope is **Phase 6 only**)
+3. `docs/superpowers/plans/2026-05-30-extension-restructure.md` — your plan is **Phase 6, Tasks 6.1–6.3**. Execute task by task. (Phases 1, 2, 5 are already merged — do not redo them.)
+
+## Execution mode
+
+Use **subagent-driven-development** (project default). Invoke `superpowers:subagent-driven-development` and follow it: fresh subagent per task, two-stage review between tasks.
+
+**Every subagent prompt MUST start with**:
+```
+cd /home/alee/Sources/relicario/.worktrees/phase-c-6-vault-status
+```
+…before any other instruction. This is non-negotiable per project memory.
+
+## Your scope and boundaries
+
+**In scope:** Phase 6 Tasks 6.1–6.3 — `handleGetVaultStatus` in `service-worker/vault.ts` + cached `ahead`/`behind`/`lastSyncAt` fields on the git-host state + populating them in the `sync` handler + dispatch wiring in `popup-only.ts`; the `vault-status.ts` renderer + any new glyphs in `shared/glyphs.ts`; wiring the indicator into `vault-sidebar.ts`'s footer (mount + manual refresh). Tests: `service-worker/__tests__/vault-status.test.ts`, `vault/__tests__/status-indicator.test.ts`.
+
+**Out of scope:** Phase 3 (Dev-A owns `setup.ts`, ALL of `messages.ts`, and the `create_vault`/`attach_vault` handlers) and Phase 4 (Dev-B owns the `vault.ts` split, including *creating* `vault-sidebar.ts`). You only *modify* `vault-sidebar.ts` to add the wiring in Task 6.3. If you trip over an out-of-scope issue or a new bug, file it via a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules — sequencing (this is the crux of your phase):**
+
+- **Do NOT touch `shared/messages.ts`.** Dev-A (Phase 3, Task 3.1) defines the `get_vault_status` request type + `GetVaultStatusResponse` interface. You *import* `GetVaultStatusResponse` from `../shared/messages`; you never declare it. **Before you can compile Task 6.1, Dev-A's Task 3.1 must have landed on main** (or be available to merge). Confirm with the PM at kickoff. If it hasn't landed, ask the PM whether to wait or to proceed against a temporary local type and reconcile at merge — prefer waiting if Dev-A is close.
+- **Stage your tasks 6.1 → 6.2 → 6.3.** Tasks 6.1 (SW handler) and 6.2 (renderer) are independent of Phase 4 and you can build them as soon as the `get_vault_status` type exists. **Task 6.3 wires into `vault-sidebar.ts`, which Dev-B (Phase 4) creates — you MUST wait for Dev-B's Phase 4 PR to merge before doing Task 6.3.** Ask the PM to confirm Phase 4 is merged, then pull main into your branch and do the wiring. Dev-B has been told to leave an empty `#vault-status-slot` footer element for you.
+- Your `get_vault_status` handler is additive in `service-worker/vault.ts` alongside Dev-A's `create_vault`/`attach_vault` handlers. Expect a possible small merge conflict on the import block / dispatch switch in `service-worker/vault.ts` + `popup-only.ts`; the PM will sequence your SW handler merge after Dev-A's Phase 3.
+- **No network in `get_vault_status`** — return cached state only. The spec is explicit: sync is user-initiated. **No timer polling** in the wiring — refresh on mount + manual ↻ button only.
+- Do not merge your branch to main. The PM owns merges.
+- Do not push `--force` or run `git reset --hard` / `git branch -D` / `git worktree remove`. Per `CLAUDE.md`: ask first.
+
+## Coordination protocol
+
+You are one of multiple terminals. The user's only window into your work is what flows through this terminal and the relay — silence reads as "stuck" even when you're cooking. Narrate.
+
+**Narration discipline.** STATUS UPDATEs at task boundaries are the floor, not the ceiling. Also emit `Status: IN-PROGRESS` updates at meaningful in-flight moments: when you dispatch a subagent, when a subagent returns a decision worth flagging, when a sub-task completes, when you change direction or hit something unexpected, when you start a new task, **and especially when you are blocked waiting on Dev-A's or Dev-B's merge** (so the PM knows your idle is a dependency wait, not a stall). The `Notes` field narrates WHAT happened and WHY. Three sentences max. Print every STATUS UPDATE locally before/after sending it.
+
+**At every task boundary AND every meaningful in-flight moment**: call `read_messages(for="dev-c")` first, then post via `post_message(from="dev-c", to="pm", kind="status"|"question", body="...")` and also print it here. Format:
+
+```
+## STATUS UPDATE — DEV-C
+Time: <iso8601 like 2026-05-31T14:30:00-07:00>
+Branch: phase-c-6-vault-status
+Task: <number / short name>
+Status: STARTED | IN-PROGRESS | DONE | BLOCKED | REVIEW-READY
+Last commit: <short sha + first line of message>
+Tests: <green | red (which failed) | N/A>
+Notes: <anything PM needs to know — keep to 3 sentences max>
+```
+
+**When you need PM input mid-task** (e.g. "is Phase 3's `get_vault_status` type merged yet?" / "is Phase 4 merged so I can do 6.3?"): post via `post_message(kind="question")` with format:
+
+```
+## QUESTION TO PM — DEV-C
+Time: <iso8601>
+Context: <what task, what decision point>
+Options: <A: ... / B: ... / C: ...>
+Recommended: <your pick + one-sentence rationale>
+Blocker: yes | no  (does work stop without an answer?)
+```
+
+**You'll receive**: `## DIRECTIVE TO DEV-C` blocks from the PM via relay. Acknowledge and act.
+
+## Ship-it autonomy + simplify discipline
+
+The repo has `.claude/settings.json` with broad allow + narrow destructive deny. You can write files, run language tooling, commit, push, and open PRs without confirmation prompts. Move at speed.
+
+**Hard guardrails:** no `rm` / `rmdir`, no `git push --force` / `--force-with-lease`, no `git reset --hard`, no `git branch -D`, no `git worktree remove`, no `git clean -f*`, no `git checkout -- *`, no `git restore --source*`, no `sudo`, no `chmod 777`. If you genuinely need one, surface a `## QUESTION TO PM` block.
+
+**Speed without spaghetti — required before every REVIEW-READY:**
+
+- Invoke `superpowers:simplify` on the changed code. Either accept its findings (fix in the same commit) or surface a one-sentence rationale in the STATUS UPDATE Notes.
+- Do not create parallel implementations of an existing helper (reuse `shared/relative-time.ts` for the timestamp; reuse the existing glyph family in `shared/glyphs.ts`).
+- Do not add error handling / fallbacks / validation for scenarios that can't happen (project rule). Trust internal code and framework guarantees.
+- Default to no comments unless the WHY is non-obvious.
+- Half-finished implementations are forbidden. Ship a complete sub-task or surface a `## QUESTION TO PM` block.
+
+## Authority within the plan
+
+You don't need PM permission to: execute task-to-task per the plan, make implementation decisions consistent with plan + spec, write tests, refactor your own code, fix bugs you introduce, push commits to your feature branch.
+
+You **do** escalate to PM when: a scope question outside the plan; a test you can't make green after honest debugging; a discovered bug not in your plan; anything destructive; **the dependency waits (Phase 3 type / Phase 4 sidebar)**; before opening the PR for review.
+
+## Final steps before REVIEW-READY
+
+Run the project's full validation:
+
+```bash
+cd extension && npx tsc --noEmit && npx vitest run && npm run build:all
+```
+
+Then push and open the PR:
+
+```bash
+git push -u origin phase-c-6-vault-status
+gh pr create --base main --head phase-c-6-vault-status --title "feat(ext): Plan C Phase 6 — get_vault_status + sidebar status indicator" --body "$(cat <<'EOF'
+## Plan C Phase 6 — get_vault_status + sidebar status indicator
+
+Part of v0.7.0 (finish the extension restructure). Implements Phase 6 (Tasks 6.1–6.3) of `docs/superpowers/plans/2026-05-30-extension-restructure.md`. Closes the `relicario status` CLI/extension parity gap.
+
+### What changed
+- `service-worker/vault.ts`: `handleGetVaultStatus` — returns cached `ahead`/`behind`/`lastSyncAt` from `state.gitHost` + live `pendingItems` from the manifest. No network call.
+- `service-worker/git-host.ts`: cached `lastSyncAt`/`ahead`/`behind` fields, populated by the `sync` handler.
+- `service-worker/router/popup-only.ts`: `get_vault_status` dispatch case.
+- `vault/vault-status.ts`: sidebar-footer indicator renderer (in sync / N ahead / N behind / N pending / never synced); reuses `shared/relative-time.ts` + glyph family.
+- `vault/vault-sidebar.ts`: wired the indicator into the footer slot — refresh on mount + manual ↻ button, no timer polling.
+- Tests: `service-worker/__tests__/vault-status.test.ts`, `vault/__tests__/status-indicator.test.ts`.
+
+### Coordination notes
+- Consumes the `get_vault_status` message type defined by Dev-A's Phase 3 (`messages.ts`); does not redefine it.
+- Task 6.3 wiring lands on top of Dev-B's Phase 4 `vault-sidebar.ts` (merged first).
+
+### Verification
+- `npx tsc --noEmit` clean · `npx vitest run` green · `npm run build:all` clean (pre-existing 4MB WASM warning only).
+- Done-criteria greps from the plan's Task 7.1 pass (`get_vault_status` dispatched + rendered, no network in handler, no polling timer).
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+Emit a `## STATUS UPDATE` with `Status: REVIEW-READY` and the PR URL.
+
+## First action
+
+After reading: emit a `## STATUS UPDATE` confirming setup complete (worktree created, plan absorbed, on `phase-c-6-vault-status`). Then immediately ask the PM (via `## QUESTION TO PM`) whether Dev-A's Phase 3 `get_vault_status` type has landed yet — that gates Task 6.1. While you wait, you can prepare the Task 6.2 renderer (`vault-status.ts`) since it only needs the local `VaultStatus` shape, not `messages.ts`.

docs/superpowers/coordination/v0.7-launch.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Auto-generated by multi-agent-kickoff — v0.7.0 (finish the extension restructure)
+# Streams: Dev-A = Phase 3, Dev-B = Phase 4, Dev-C = Phase 6
+set -e
+
+REPO="/home/alee/Sources/relicario"
+RELAY_DIR="$REPO/tools/relay"
+COORD="$REPO/docs/superpowers/coordination"
+RELEASE="v0.7"
+SESSION="$RELEASE"
+
+# ── 1. Relay ─────────────────────────────────────────────────────────────
+if curl -sf http://127.0.0.1:7331/sse --max-time 2 > /dev/null 2>&1; then
+  echo "[relay] already running on :7331"
+else
+  echo "[relay] starting..."
+  cd "$RELAY_DIR"
+  nohup npx tsx server.ts > /tmp/relay-v0.7.log 2>&1 &
+  for i in $(seq 1 10); do
+    sleep 1
+    if curl -sf http://127.0.0.1:7331/sse --max-time 1 > /dev/null 2>&1; then
+      echo "[relay] ready on :7331"
+      break
+    fi
+    if [ "$i" -eq 10 ]; then
+      echo "[relay] ERROR: failed to start — check /tmp/relay-v0.7.log"
+      exit 1
+    fi
+  done
+fi
+
+# ── 2. tmux session ──────────────────────────────────────────────────────
+if tmux has-session -t "$SESSION" 2>/dev/null; then
+  echo "[tmux] session '$SESSION' already exists — attaching"
+  exec tmux attach-session -t "$SESSION"
+fi
+
+echo "[tmux] creating session '$SESSION'..."
+tmux new-session  -d -s "$SESSION" -n "PM"
+tmux send-keys    -t "$SESSION:PM"    "claude" Enter
+
+tmux new-window   -t "$SESSION" -n "Dev-A"
+tmux send-keys    -t "$SESSION:Dev-A" "claude" Enter
+
+tmux new-window   -t "$SESSION" -n "Dev-B"
+tmux send-keys    -t "$SESSION:Dev-B" "claude" Enter
+
+tmux new-window   -t "$SESSION" -n "Dev-C"
+tmux send-keys    -t "$SESSION:Dev-C" "claude" Enter
+
+tmux select-window -t "$SESSION:PM"
+
+echo ""
+echo "╔══════════════════════════════════════════════════════════════════════╗"
+echo "║  v0.7.0 — finish the extension restructure — prompt cheatsheet        ║"
+echo "╠══════════════════════════════════════════════════════════════════════╣"
+echo "║  PM window    →  paste $COORD/v0.7-pm-prompt.md      ║"
+echo "║  Dev-A window →  paste $COORD/v0.7-dev-a-prompt.md   ║"
+echo "║  Dev-B window →  paste $COORD/v0.7-dev-b-prompt.md   ║"
+echo "║  Dev-C window →  paste $COORD/v0.7-dev-c-prompt.md   ║"
+echo "╠══════════════════════════════════════════════════════════════════════╣"
+echo "║  A = Phase 3 (setup wizard SW migration)                              ║"
+echo "║  B = Phase 4 (split vault.ts + vault_locked lift)                     ║"
+echo "║  C = Phase 6 (get_vault_status + status indicator) — deps on A & B    ║"
+echo "╚══════════════════════════════════════════════════════════════════════╝"
+echo ""
+echo "[tmux] attaching — use Ctrl-b n / Ctrl-b p to switch windows"
+exec tmux attach-session -t "$SESSION"

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

@@ -0,0 +1,129 @@
+# PM Kickoff Prompt — v0.7.0 finish the extension restructure
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are the **project manager** for the v0.7.0 "finish the extension restructure" release. 3 senior developers report to you, each working in their own terminal on a parallel feature branch. The user runs all 3+1 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-31. Project rules in `CLAUDE.md` apply.
+
+## 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, dev-c`. Use these instead of asking the user to copy-paste. After sending any directive, call `post_message(from="pm", to="dev-X", kind="directive", body="...")`.
+
+**Fallback:** If the relay MCP tools are not registered in your session (this happens when the relay server was not running when your session opened), use the Python shim instead:
+```bash
+cd /home/alee/Sources/relicario/tools/relay
+python3 call.py post_message '{"from":"pm","to":"dev-a","kind":"directive","body":"..."}'
+python3 call.py read_messages '{"for":"pm"}'
+```
+The shim connects over HTTP and has the same semantics as the MCP tools.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/specs/2026-05-04-extension-restructure-design.md` — the bundle spec
+3. `docs/superpowers/plans/2026-05-30-extension-restructure.md` — the implementation plan. **Phases 1, 2, 5 already merged (2026-05-30).** This release finishes the remaining three:
+   - Plan A (Dev-A) → **Phase 3** (Tasks 3.1–3.7): setup wizard SW migration + step registry + `clearWizardState`
+   - Plan B (Dev-B) → **Phase 4** (Tasks 4.1–4.7): split `vault.ts` into 5 modules + lift the `vault_locked` channel into `shared/state.ts`
+   - Plan C (Dev-C) → **Phase 6** (Tasks 6.1–6.3): `get_vault_status` SW handler + sidebar status indicator
+
+## Your authority
+
+- Approve or deny scope changes from devs
+- Review and merge PRs from each dev's feature branch
+- Drive any release-prep work that isn't a feature plan (Task 7.1 final verification sweep, CHANGELOG, version bumps to v0.7.0, STATUS.md / ROADMAP.md updates) — this is your hands-on work
+- Tag `v0.7.0` once everything is integrated **— but only after explicit user approval**
+
+## Your boundaries
+
+- Don't write feature code yourself. Edits to docs / CHANGELOG / `CLAUDE.md` / STATUS / ROADMAP 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 (`git push --force`, `git reset --hard`, `git branch -D`, `git worktree remove`).
+
+## ⚠️ Critical: cross-stream dependencies (the whole reason you exist this release)
+
+Per the plan's "Notes on execution order": **Phase 4 blocks Phase 6, and Phase 3 owns a file Phase 6 needs.** Your central job is sequencing the merges and arbitrating the two shared edits:
+
+1. **`extension/src/shared/messages.ts`** — Dev-A (Phase 3, Task 3.1) adds all three new request types: `create_vault`, `attach_vault`, **and `get_vault_status`**, plus their response interfaces, plus the three additions to `POPUP_ONLY_TYPES`. Dev-C (Phase 6) *consumes* `get_vault_status` but must NOT redefine it. **Directive at kickoff:** Dev-A owns every `messages.ts` change; Dev-C imports `GetVaultStatusResponse` from `messages.ts` and does not touch that file. If Dev-C starts before Dev-A's Task 3.1 lands, have Dev-C either (a) wait on the type, or (b) work against a local type alias and you reconcile at merge — prefer (a) if Dev-A is close.
+
+2. **`extension/src/vault/vault-sidebar.ts`** — Dev-B (Phase 4, Task 4.2) *creates* this file. Dev-C (Phase 6, Task 6.3) *modifies* it to wire the status indicator into the sidebar footer. **Directive:** Dev-C should land Tasks 6.1 (SW handler) and 6.2 (renderer `vault-status.ts`) — both independent of Phase 4 — first, then HOLD on Task 6.3 until Dev-B's Phase 4 PR merges. Sequence the merges: **Phase 4 merges before Phase 6's wiring commit.**
+
+3. **`extension/src/service-worker/vault.ts`** — Dev-A (Phase 3: `create_vault` / `attach_vault` handlers) and Dev-C (Phase 6: `get_vault_status` handler) both append handlers here, and both add a dispatch case to `service-worker/router/popup-only.ts`. These are additive and shouldn't conflict, but you may get a small merge conflict on the import block / switch statement. Merge Dev-A (Phase 3) before Dev-C's SW handler if possible to minimize churn. A trivial conflict here is expected — resolve it at merge or have the second dev rebase.
+
+**Recommended merge order:** Phase 3 (Dev-A) → Phase 4 (Dev-B) → Phase 6 (Dev-C). Confirm this with the devs at kickoff so Dev-C knows to stage 6.1/6.2 early and 6.3 last.
+
+## Coordination protocol
+
+You are one of 3+1 terminals. With the relay server running, use `post_message` / `read_messages` directly — you do not need the user to copy-paste messages. Call `read_messages(for="pm")` before every action. If the relay MCP tools are not registered in your session, fall back to the Python shim (see **Relay server** section above) or ask the user to relay manually.
+
+**Narrate to the user in plain prose between tool calls.** The user's only window into the release is the PM terminal output. Don't emit DIRECTIVE blocks silently. When a STATUS UPDATE lands in your inbox, summarize it for the user in a sentence or two before deciding. When you send a directive, state the rationale briefly so the user sees the reasoning, not just the verdict. When you dispatch a subagent (e.g. for plan review or coherence pass), say so. One or two sentences per beat is plenty — the goal is for the user to read this terminal top-to-bottom and understand the release as a story.
+
+**You receive:** `## STATUS UPDATE — DEV-<letter>` or `## QUESTION TO PM — DEV-<letter>` blocks, either from the relay inbox or relayed by the user if the relay is down.
+
+**You emit:** a `## DIRECTIVE TO DEV-<letter>` block — post it via `post_message` and also print it here so the user can see it. Format:
+
+```
+## DIRECTIVE TO DEV-<letter>
+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, give a current rollup:
+
+```
+## RELEASE STATUS — v0.7.0
+Devs: <per-dev one-line state>
+PM: <what you're working on>
+Blockers: <list, or "none">
+Next milestone: <e.g., "Dev A REVIEW-READY", "tag v0.7.0">
+```
+
+## 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 the diff against the spec and plan acceptance criteria (the plan's "Final Verification" Task 7.1 lists the exact done-criteria greps — use them)
+4. If green: post `Action: MERGE-APPROVED` and run `gh pr merge --merge` (preserve git history; no squash — project rule: git history is the audit log)
+5. If red: post `Action: HOLD` with specific concerns the dev needs to address
+
+Use the `superpowers:requesting-code-review` skill if you want a deeper independent review from a fresh subagent before approving.
+
+## Pre-tag checklist
+
+Before tagging `v0.7.0`:
+
+- [ ] Every dev branch merged to main (Phases 3, 4, 6)
+- [ ] Task 7.1 done-criteria sweep passes (all greps in the plan's Final Verification section)
+- [ ] `cd extension && npx tsc --noEmit` clean
+- [ ] `cd extension && npx vitest run` green (baseline was 389/389 + new Phase 3/4/6 tests)
+- [ ] `cd extension && npm run build:all` clean (only the pre-existing 4MB WASM warning)
+- [ ] `cargo test` still green (these phases don't touch Rust, but confirm no accidental breakage)
+- [ ] STATUS.md + ROADMAP.md moved extension restructure to "Shipped"; CHANGELOG.md v0.7.0 entry written; version bumped to v0.7.0
+- [ ] User-driven smoke test of the merged result
+- [ ] Explicit user approval to tag
+
+After all PRs merge, run the project's cleanup (CLAUDE.md rule #6): `Workflow({name:"release", args:{action:"cleanup"}})` to remove this lift's worktrees and branches. **Note:** there are also stale `phase-c-1/2/5` worktrees from the previous lift (under `.worktrees/`) that were never cleaned up — flag this to the user; they may want them removed too (destructive op → ask first).
+
+## First action
+
+1. Call `read_messages(for="pm")` to drain any early inbox messages.
+2. Emit a `## RELEASE STATUS` block confirming you've absorbed the spec, the plan, and the cross-stream dependency map above.
+3. Send opening directives to all three devs via `post_message` — at minimum: (a) confirm Dev-A owns ALL of `messages.ts`, (b) confirm the merge order Phase 3 → Phase 4 → Phase 6, (c) tell Dev-C to stage Tasks 6.1/6.2 first and HOLD 6.3 until Phase 4 merges.
+4. Wait for acknowledgement STATUS UPDATEs from all devs before clearing them to proceed.

docs/superpowers/plans/2026-05-30-doc-structure-redesign.md

@@ -0,0 +1,611 @@
+# Doc Structure Redesign 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 (`- [x]`) syntax for tracking.
+
+**Goal:** Rename the three overlapping `ARCHITECTURE.md` files into topic-named docs, move `FORMATS.md` into `docs/`, and pin every tour doc with a scope header + a "Next:" footer so the reading order is canonical and the drift surface shrinks.
+
+**Architecture:** Five sequential commits, each mechanical. No content is rewritten — the drift audit already cleaned the content in `210232d`, `cf7478d`, `fa659eb`. This plan only renames files, adds scope headers + "Next:" footers, fixes incoming links to old paths, and updates `CLAUDE.md`'s living-docs table and discipline rules.
+
+**Tech Stack:** Markdown, `git mv` (so blame/history follow), `grep -rn` for link verification, `git log --follow` for rename verification.
+
+**Source spec:** `docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md` — refer back when ambiguity arises.
+
+---
+
+## File Structure
+
+**Renamed (Task 1):**
+- `ARCHITECTURE.md` → `DESIGN.md` (top-level system tour)
+- `docs/ARCHITECTURE.md` → `docs/CRYPTO.md` (crypto pipeline + flows)
+- `FORMATS.md` → `docs/FORMATS.md` (wire formats)
+
+**Modified (Tasks 2-4):**
+- `README.md` — trim mid-section "Architecture" stub to a one-paragraph pointer, add header + "Next:" footer.
+- `DESIGN.md` — add scope header + "Next:" footer (no content rewrite of the tour itself).
+- `docs/CRYPTO.md` — add scope header + "Next:" footer.
+- `docs/FORMATS.md` — add scope header + "Next:" footer.
+- `docs/SECURITY.md` — add scope header + "Next:" footer.
+- `crates/relicario-core/ARCHITECTURE.md` — add scope header + "Next:" footer.
+- `crates/relicario-cli/ARCHITECTURE.md` — add scope header + "Next:" footer.
+- `extension/ARCHITECTURE.md` — add scope header + "Next:" footer (End of tour).
+- `CLAUDE.md` — update the "Living docs — update discipline" table with new filenames; update the "Planning & design specs" core-references list if it references old paths; add three new discipline rules.
+- Various callsites in `docs/superpowers/specs/*.md` and the per-crate / extension `ARCHITECTURE.md` files that link to old paths.
+
+**Unchanged:** `STATUS.md`, `ROADMAP.md`, `CHANGELOG.md`, `LICENSE`, `docs/superpowers/{specs,plans,audits,coordination,reviews,test-runs,MULTI-AGENT.md}`.
+
+---
+
+## Task 1: Rename files
+
+**Files:**
+- Rename: `ARCHITECTURE.md` → `DESIGN.md`
+- Rename: `docs/ARCHITECTURE.md` → `docs/CRYPTO.md`
+- Rename: `FORMATS.md` → `docs/FORMATS.md`
+
+- [x] **Step 1: Confirm clean working tree (or only known dirt)**
+
+Run: `git status`
+
+Expected: only pre-existing modifications (`.claude/settings.json`, `docs/superpowers/plans/2026-04-22-relicario-extension-1c-beta1.md`, `docs/superpowers/specs/2026-04-11-relicario-design.md`, `extension/src/vault/vault.ts`). No other unstaged changes. If anything else is modified, stop and ask the user.
+
+- [x] **Step 2: Perform the three renames**
+
+Run:
+```bash
+git mv ARCHITECTURE.md DESIGN.md
+git mv docs/ARCHITECTURE.md docs/CRYPTO.md
+git mv FORMATS.md docs/FORMATS.md
+```
+
+Expected: no errors. `git status` should now show three renamed files staged.
+
+- [x] **Step 3: Verify renames are tracked as renames, not delete+add**
+
+Run: `git status --short`
+
+Expected output includes three lines starting with `R` (rename), not `D` (delete) + `??` (new):
+```
+R  ARCHITECTURE.md -> DESIGN.md
+R  docs/ARCHITECTURE.md -> docs/CRYPTO.md
+R  FORMATS.md -> docs/FORMATS.md
+```
+
+If git shows `D` + new file instead, stop and investigate — likely means the file content changed enough that git can't see the rename. (For this commit we changed nothing, so renames should be clean.)
+
+- [x] **Step 4: Commit the renames**
+
+Run:
+```bash
+git commit -m "$(cat <<'EOF'
+docs: rename for doc-structure redesign — DESIGN / CRYPTO / docs/FORMATS
+
+Mechanical renames only; no content changes. Tracked as renames so
+git blame / git log --follow survive intact.
+
+- ARCHITECTURE.md → DESIGN.md (top-level system tour)
+- docs/ARCHITECTURE.md → docs/CRYPTO.md (crypto pipeline)
+- FORMATS.md → docs/FORMATS.md (wire formats; aligns with docs/ layout)
+
+Spec: docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md
+EOF
+)"
+```
+
+Expected: one commit created. Verify with `git log --oneline -1`.
+
+- [x] **Step 5: Verify history follows the rename**
+
+Run: `git log --follow --oneline DESIGN.md | head -5`
+
+Expected: shows the rename commit on top, then commits to the old `ARCHITECTURE.md` underneath. Same idea for `docs/CRYPTO.md` and `docs/FORMATS.md` (`git log --follow --oneline docs/CRYPTO.md | head -5`).
+
+---
+
+## Task 2: Add scope headers + "Next:" footers + trim README architecture section
+
+**Files (all modified):**
+- `README.md`
+- `DESIGN.md`
+- `docs/CRYPTO.md`
+- `docs/FORMATS.md`
+- `docs/SECURITY.md`
+- `crates/relicario-core/ARCHITECTURE.md`
+- `crates/relicario-cli/ARCHITECTURE.md`
+- `extension/ARCHITECTURE.md`
+
+Convention: scope header sits as a blockquote *immediately under the H1 title*, separated by a blank line. The "Next:" footer sits as the very last line of the file (with a blank line above it).
+
+- [x] **Step 1: Add scope header + footer to `README.md`**
+
+Read `README.md` and find the existing H1 (`# Relicario` near top). Insert the scope blockquote on the line immediately after the H1's blank-line separator, then add the footer at the very end of the file.
+
+**Header (insert after H1):**
+```markdown
+> **Audience:** users + evaluators. This doc owns the pitch, security-model summary, quick-start commands, reference-image explanation, recovery-QR overview, and roadmap teaser. Goes no deeper — for the system tour see [DESIGN.md](DESIGN.md), for crypto see [docs/CRYPTO.md](docs/CRYPTO.md).
+```
+
+**Footer (append at very end of file):**
+```markdown
+
+---
+
+**Next:** [DESIGN.md](DESIGN.md) — the system tour.
+```
+
+- [x] **Step 2: Trim README's mid-section "Architecture" stub to a one-paragraph pointer**
+
+In `README.md`, locate the `## Architecture` section (it's the one containing a tree diagram of `relicario/` and references to `docs/architecture/`). Replace the entire section content (from the heading through the end of the tree diagram, but BEFORE the next H2) with:
+
+```markdown
+## Architecture
+
+A short tour of the four codebases and how they fit together lives in [DESIGN.md](DESIGN.md). Crypto pipeline diagrams are in [docs/CRYPTO.md](docs/CRYPTO.md); the wire format reference is [docs/FORMATS.md](docs/FORMATS.md); the threat model is [docs/SECURITY.md](docs/SECURITY.md).
+
+`relicario-core` is the platform-agnostic bytes-in/bytes-out heart — no filesystem, no network. The CLI binary and the browser-extension WASM bridge both consume it. See per-codebase deep-dives in `crates/*/ARCHITECTURE.md` and `extension/ARCHITECTURE.md`.
+```
+
+Do NOT touch the `### Crypto primitives` table or the `### Encrypted file format` block if they come immediately after — those are reader-friendly summaries that belong in the README. Only the codebase tree + the broken `docs/architecture/` reference go.
+
+Verify by reading the README from start to finish to confirm the flow still reads naturally.
+
+- [x] **Step 3: Add scope header + footer to `DESIGN.md`**
+
+Read `DESIGN.md`. Insert this header after its H1 (currently `# Architecture overview — Relicario`):
+
+```markdown
+> **Audience:** anyone wanting to understand the system at the cross-codebase level. This doc owns the four-codebase map, inter-codebase contracts, the secrets map (what secret lives where), the build matrix, and the global code-map index. **Does NOT own:** crypto pipeline details (see [docs/CRYPTO.md](docs/CRYPTO.md)), wire formats (see [docs/FORMATS.md](docs/FORMATS.md)), threat model (see [docs/SECURITY.md](docs/SECURITY.md)), per-crate module maps (see [crates/relicario-core/ARCHITECTURE.md](crates/relicario-core/ARCHITECTURE.md), [crates/relicario-cli/ARCHITECTURE.md](crates/relicario-cli/ARCHITECTURE.md), and [extension/ARCHITECTURE.md](extension/ARCHITECTURE.md)).
+```
+
+Append footer at end of file:
+```markdown
+
+---
+
+**Next:** [docs/CRYPTO.md](docs/CRYPTO.md) — the crypto pipeline that backs this design.
+```
+
+- [x] **Step 4: Add scope header + footer to `docs/CRYPTO.md`**
+
+Read `docs/CRYPTO.md`. Insert this header after its H1 (currently `# Relicario — Architecture`):
+
+```markdown
+> **Audience:** anyone evaluating or auditing the crypto. This doc owns Argon2id parameters and rationale, XChaCha20-Poly1305 rationale, vault creation/unlock flow diagrams, DCT-steganography embed and extract flows, and the high-level encrypted-file-format diagram. **Does NOT own:** byte-level schemas or JSON shapes (see [FORMATS.md](FORMATS.md)), attacker scenarios (see [SECURITY.md](SECURITY.md)), or per-module crypto implementation (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)).
+```
+
+Also update the H1 itself from `# Relicario — Architecture` to `# Relicario — Crypto Pipeline` so the file's title matches its renamed scope.
+
+Append footer at end of file:
+```markdown
+
+---
+
+**Next:** [FORMATS.md](FORMATS.md) — the byte-level wire formats.
+```
+
+- [x] **Step 5: Add scope header + footer to `docs/FORMATS.md`**
+
+Read `docs/FORMATS.md`. Insert this header after its H1 (currently `# Relicario Wire Formats`):
+
+```markdown
+> **Audience:** anyone implementing a compatible client or reading raw vault bytes. This doc owns the `.enc` blob layout, `params.json` / `salt` / `devices.json` / `revoked.json` shapes, the manifest JSON schema, the `.relbak` envelope, item-ID formats, and the settings JSON schema. **Does NOT own:** why these formats look this way (see [CRYPTO.md](CRYPTO.md)), threat model around them (see [SECURITY.md](SECURITY.md)), or Rust struct internals (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)).
+```
+
+The existing intro blockquote (`> Quick-reference for the load-bearing binary and JSON formats. …`) was a partial scope statement — leave it in place as a useful summary sentence, but the new scope blockquote above it is the canonical one. Place the new blockquote between H1 and the existing quick-reference blockquote.
+
+Append footer at end of file:
+```markdown
+
+---
+
+**Next:** [SECURITY.md](SECURITY.md) — the threat model.
+```
+
+- [x] **Step 6: Add scope header + footer to `docs/SECURITY.md`**
+
+Read `docs/SECURITY.md`. Insert this header after its H1 (currently `# Relicario Security Model`):
+
+```markdown
+> **Audience:** auditors and curious users. This doc owns the threat model, attacker-scenarios table, device-authentication model, env-var trust surface, and known limitations. **Does NOT own:** crypto primitive details (see [CRYPTO.md](CRYPTO.md)), wire formats (see [FORMATS.md](FORMATS.md)), or implementation (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)).
+```
+
+Append footer at end of file:
+```markdown
+
+---
+
+**Next:** [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md) — implementation, starting with the platform-agnostic core.
+```
+
+- [x] **Step 7: Add scope header + footer to `crates/relicario-core/ARCHITECTURE.md`**
+
+Read `crates/relicario-core/ARCHITECTURE.md`. Insert this header after its H1 (currently `# Architecture: relicario-core`):
+
+```markdown
+> **Audience:** contributors editing or extending `relicario-core`. This doc owns the module map for this crate, module-level invariants (e.g., no filesystem, no network), key flows at the module level, and the crate's test architecture. **Does NOT own:** crypto primitives or threat model (see [../../docs/CRYPTO.md](../../docs/CRYPTO.md), [../../docs/SECURITY.md](../../docs/SECURITY.md)), wire formats (see [../../docs/FORMATS.md](../../docs/FORMATS.md)).
+```
+
+Append footer at end of file:
+```markdown
+
+---
+
+**Next:** [../relicario-cli/ARCHITECTURE.md](../relicario-cli/ARCHITECTURE.md) — how the CLI wraps the core.
+```
+
+- [x] **Step 8: Add scope header + footer to `crates/relicario-cli/ARCHITECTURE.md`**
+
+Read `crates/relicario-cli/ARCHITECTURE.md`. Insert this header after its H1 (currently `# Architecture: relicario-cli`):
+
+```markdown
+> **Audience:** contributors editing the CLI. This doc owns the CLI module map, the clap command surface, per-command key flows, session/unlock semantics, and helpers. **Does NOT own:** crypto, wire formats, or threat model (see [../../docs/CRYPTO.md](../../docs/CRYPTO.md), [../../docs/FORMATS.md](../../docs/FORMATS.md), [../../docs/SECURITY.md](../../docs/SECURITY.md)).
+```
+
+Append footer at end of file:
+```markdown
+
+---
+
+**Next:** [../../extension/ARCHITECTURE.md](../../extension/ARCHITECTURE.md) — the browser-side surface.
+```
+
+- [x] **Step 9: Add scope header + footer to `extension/ARCHITECTURE.md`**
+
+Read `extension/ARCHITECTURE.md`. Insert this header after its H1 (currently `# Architecture: relicario extension`):
+
+```markdown
+> **Audience:** contributors editing the browser extension. This doc owns the bundle structure (popup, vault tab, background SW, content scripts), the SW ↔ popup message contract, the component / pane architecture, routing, and the build pipeline. **Does NOT own:** WASM crypto internals (see [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md)), wire formats (see [../docs/FORMATS.md](../docs/FORMATS.md)), or threat model (see [../docs/SECURITY.md](../docs/SECURITY.md)).
+```
+
+Append footer at end of file:
+```markdown
+
+---
+
+**End of tour.** For roadmap and in-flight work see [../STATUS.md](../STATUS.md) and [../ROADMAP.md](../ROADMAP.md).
+```
+
+- [x] **Step 10: Verify all eight headers are present**
+
+Run:
+```bash
+grep -l '^> \*\*Audience:\*\*' README.md DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario-core/ARCHITECTURE.md crates/relicario-cli/ARCHITECTURE.md extension/ARCHITECTURE.md
+```
+
+Expected: all eight filenames echoed back. If any file is missing from the output, its header didn't land — go back and add it.
+
+- [x] **Step 11: Verify all "Next:" footers are present**
+
+Run:
+```bash
+grep -l -E '^\*\*(Next|End of tour)' README.md DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario-core/ARCHITECTURE.md crates/relicario-cli/ARCHITECTURE.md extension/ARCHITECTURE.md
+```
+
+Expected: all eight filenames echoed back.
+
+- [x] **Step 12: Verify README architecture section is trimmed**
+
+Run: `grep -n 'docs/architecture/' README.md`
+
+Expected: zero matches (the broken `docs/architecture/` reference is gone).
+
+Also run: `awk '/^## Architecture/,/^## [^A]/' README.md | wc -l` and inspect — the section between `## Architecture` and the next `##` heading should now be small (under ~15 lines), not the old multi-tree diagram.
+
+- [x] **Step 13: Commit**
+
+Run:
+```bash
+git add README.md DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario-core/ARCHITECTURE.md crates/relicario-cli/ARCHITECTURE.md extension/ARCHITECTURE.md
+git commit -m "$(cat <<'EOF'
+docs: add scope headers + Next: footers to all tour docs
+
+Each of the eight tour docs (README, DESIGN, docs/CRYPTO,
+docs/FORMATS, docs/SECURITY, crates/relicario-core/ARCHITECTURE,
+crates/relicario-cli/ARCHITECTURE, extension/ARCHITECTURE) now
+declares its scope in a blockquote under its H1 and ends with a
+single-line "Next:" pointer to the next doc in the canonical
+reading order: README → DESIGN → CRYPTO → FORMATS → SECURITY →
+core → cli → extension.
+
+Also trimmed README's mid-section "Architecture" stub to a one-
+paragraph pointer at DESIGN.md (was duplicating cross-codebase
+content and referencing a non-existent docs/architecture/ tree).
+
+Renamed docs/CRYPTO.md's H1 from "Relicario — Architecture" to
+"Relicario — Crypto Pipeline" to match the file's renamed scope.
+
+Spec: docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md
+EOF
+)"
+```
+
+---
+
+## Task 3: Fix incoming links to old paths
+
+**Files (modified as needed):** `CLAUDE.md`, plus whatever other files reference the old paths.
+
+- [x] **Step 1: Find every reference to old paths in markdown files**
+
+Run:
+```bash
+grep -rn --include='*.md' \
+  -e '](ARCHITECTURE\.md' \
+  -e '](\./ARCHITECTURE\.md' \
+  -e '](docs/ARCHITECTURE\.md' \
+  -e '](FORMATS\.md' \
+  -e '](\./FORMATS\.md' \
+  -e '`ARCHITECTURE\.md`' \
+  -e '`docs/ARCHITECTURE\.md`' \
+  -e '`FORMATS\.md`' \
+  . 2>/dev/null \
+  | grep -v 'docs/superpowers/test-runs/' \
+  | grep -v 'docs/superpowers/audits/' \
+  | grep -v 'docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md' \
+  | grep -v 'docs/superpowers/plans/2026-05-30-doc-structure-redesign.md'
+```
+
+Expected: a list of callsites that need updating. Will definitely include `CLAUDE.md` (the living-docs table and the planning-references list). May include per-crate ARCHITECTURE.md files and some specs in `docs/superpowers/specs/`.
+
+**Important caveat:** the bare token `ARCHITECTURE.md` is also a valid filename suffix for `crates/X/ARCHITECTURE.md` and `extension/ARCHITECTURE.md` (the per-crate docs we are NOT renaming). The grep above uses the `](` (markdown link prefix) and backtick patterns to limit matches to references that look like file paths in prose. If a hit references `crates/<something>/ARCHITECTURE.md` or `extension/ARCHITECTURE.md` — leave that one alone (it's a legitimate per-crate reference).
+
+- [x] **Step 2: For each callsite in the grep output, apply the rewrite rule**
+
+Rewrite rules:
+- `ARCHITECTURE.md` (top-level reference) → `DESIGN.md`
+- `./ARCHITECTURE.md` → `./DESIGN.md`
+- `docs/ARCHITECTURE.md` → `docs/CRYPTO.md`
+- `FORMATS.md` (top-level reference) → `docs/FORMATS.md`
+- `./FORMATS.md` → `./docs/FORMATS.md`
+
+Inside `CLAUDE.md` specifically, **also** the "Living docs — update discipline" table row labels need updating — that's part of Task 4, not Task 3. Task 3 only fixes link references.
+
+For each file with hits, use `Edit` (or `Edit` with `replace_all`) to apply the rewrites. Show your work in a brief summary at the end of this step: "Updated N references across M files."
+
+- [x] **Step 3: Verify zero old-path references remain**
+
+Re-run the grep from Step 1.
+
+Expected: zero matches (modulo the explicitly-excluded test-runs/, audits/, the spec, and this plan).
+
+If any matches remain, examine and fix (or, if you determine a hit is a legitimate per-crate reference that was caught by the regex, document why it's allowed and move on).
+
+- [x] **Step 4: Verify links resolve (no broken paths)**
+
+For every modified link, confirm the target file exists. Quick spot-check:
+```bash
+ls -1 DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario-core/ARCHITECTURE.md crates/relicario-cli/ARCHITECTURE.md extension/ARCHITECTURE.md
+```
+
+Expected: all seven files listed (none missing). For relative links inside non-root docs, mentally trace the relative path or `ls` it.
+
+- [x] **Step 5: Commit**
+
+Run:
+```bash
+git add -u
+git commit -m "$(cat <<'EOF'
+docs: fix incoming links to renamed/moved doc paths
+
+Rewrites every markdown reference to the old paths:
+- ARCHITECTURE.md → DESIGN.md
+- docs/ARCHITECTURE.md → docs/CRYPTO.md
+- FORMATS.md → docs/FORMATS.md
+
+Touches CLAUDE.md (living-docs table + planning-references list),
+per-crate ARCHITECTURE.md cross-refs, and any specs in
+docs/superpowers/specs/ that referenced the old paths. Audit
+history and test-run logs intentionally left untouched.
+
+Spec: docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md
+EOF
+)"
+```
+
+---
+
+## Task 4: Update `CLAUDE.md` living-docs table + add three discipline rules
+
+**Files:**
+- Modify: `CLAUDE.md`
+
+- [x] **Step 1: Read the current `CLAUDE.md` living-docs section**
+
+Read `CLAUDE.md` and locate two sections:
+1. The "Living docs — update discipline" table (the table starting with `| File | What it documents | Update when... |`).
+2. The "Planning & design specs" paragraph + "Core references" bullet list (above the table).
+
+- [x] **Step 2: Update the table to use new filenames**
+
+In the table, apply these row-label rewrites:
+
+| Current row label | New row label |
+|---|---|
+| `` `ARCHITECTURE.md` `` | `` `DESIGN.md` `` |
+| `` `docs/ARCHITECTURE.md` `` | `` `docs/CRYPTO.md` `` |
+| `` `FORMATS.md` `` | `` `docs/FORMATS.md` `` |
+
+The "What it documents" and "Update when..." cells for `DESIGN.md` and `docs/CRYPTO.md` and `docs/FORMATS.md` should be reviewed and lightly polished if they reference the old filename or scope — but the existing wording is already mostly correct, so only edit if a cell explicitly contradicts the new scope. Don't rewrite for the sake of rewriting.
+
+- [x] **Step 3: Update the "Planning & design specs" core-references list**
+
+If the bullet list above the table references `docs/superpowers/specs/<file>.md` with a specific old path or doc name, leave the bullets alone (those are spec citations, not docs being renamed). If the bullet list references `ARCHITECTURE.md`, `docs/ARCHITECTURE.md`, or `FORMATS.md` in prose, apply the same rewrites as Task 3 Step 2.
+
+- [x] **Step 4: Add three new discipline rules**
+
+Add a new section to `CLAUDE.md` immediately *after* the "Living docs — update discipline" table, titled `### Discipline rules`. Insert this content:
+
+```markdown
+### Discipline rules
+
+Three rules to prevent the kind of drift the 2026-05-30 audit found:
+
+1. **Scope-boundary check.** When editing a tour doc, verify the change fits the doc's scope header. If it doesn't, the change belongs in a different doc — move it instead of stretching the scope. Concretely: a sentence about crypto added to `DESIGN.md` belongs in `docs/CRYPTO.md`; a wire-format table added to `docs/CRYPTO.md` belongs in `docs/FORMATS.md`.
+
+2. **Code-constant pinning.** When a tour doc cites a code constant (`VERSION_BYTE = 0x02`, `QUANT_STEP = 50.0`, `MIN_COPIES = 5`, `MANIFEST_SCHEMA_VERSION = 2`, etc.), the doc must cite the source file + line. When the underlying constant changes, grep for the citation pattern and update the docs together with the code change in the same commit. Most drift the audit found was code-constant drift — this rule attacks it at the source.
+
+3. **New-doc rule.** When adding a tour doc, also update (a) `DESIGN.md`'s code-map, (b) the reading-order sequence (the "Next:" footer chain), and (c) the living-docs table above. A new doc that doesn't appear in all three is not done.
+```
+
+- [x] **Step 5: Verify `CLAUDE.md` changes**
+
+Run:
+```bash
+grep -n 'DESIGN.md\|docs/CRYPTO.md\|docs/FORMATS.md' CLAUDE.md
+```
+
+Expected: at least three matches (one for each renamed file in the table). Also:
+
+```bash
+grep -n 'Discipline rules' CLAUDE.md
+```
+
+Expected: one match (the new section heading).
+
+Also verify zero old-path references remain in `CLAUDE.md`:
+```bash
+grep -nE '`ARCHITECTURE\.md`|`docs/ARCHITECTURE\.md`|`FORMATS\.md`' CLAUDE.md | grep -v 'crates/.*ARCHITECTURE\.md' | grep -v 'extension/ARCHITECTURE\.md'
+```
+
+Expected: zero matches.
+
+- [x] **Step 6: Commit**
+
+Run:
+```bash
+git add CLAUDE.md
+git commit -m "$(cat <<'EOF'
+docs(CLAUDE.md): update living-docs table + add discipline rules
+
+Table row labels now reference DESIGN.md / docs/CRYPTO.md /
+docs/FORMATS.md. Adds three new discipline rules attacking the
+structural causes of the 2026-05-30 drift audit findings:
+
+  1. Scope-boundary check — content goes in the doc whose scope
+     header claims it; if it doesn't fit, move it instead of
+     stretching the header.
+  2. Code-constant pinning — docs that cite code constants must
+     cite source file + line; constant changes update doc and
+     code in the same commit.
+  3. New-doc rule — adding a tour doc also requires updating
+     DESIGN's code-map, the Next: footer chain, and this table.
+
+Spec: docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md
+EOF
+)"
+```
+
+---
+
+## Task 5: Final verification gate
+
+**Files:** none modified in this task — pure verification. If a check fails, fix the relevant earlier commit (don't add a new commit just to patch up missing wording from an earlier task).
+
+- [x] **Step 1: Scope-header presence check**
+
+Run:
+```bash
+for f in README.md DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario-core/ARCHITECTURE.md crates/relicario-cli/ARCHITECTURE.md extension/ARCHITECTURE.md; do
+  if grep -q '^> \*\*Audience:\*\*' "$f"; then
+    echo "OK   $f"
+  else
+    echo "FAIL $f (no scope header)"
+  fi
+done
+```
+
+Expected: eight `OK` lines, zero `FAIL`. If any FAIL, fix the file's header and amend the Task 2 commit (or add a follow-up commit if amending would be too disruptive).
+
+- [x] **Step 2: "Next:" footer chain check**
+
+Run:
+```bash
+for f in README.md DESIGN.md docs/CRYPTO.md docs/FORMATS.md docs/SECURITY.md crates/relicario-core/ARCHITECTURE.md crates/relicario-cli/ARCHITECTURE.md; do
+  if grep -q -E '^\*\*Next:\*\*' "$f"; then
+    echo "OK   $f"
+  else
+    echo "FAIL $f (no Next: footer)"
+  fi
+done
+if grep -q -E '^\*\*End of tour' extension/ARCHITECTURE.md; then
+  echo "OK   extension/ARCHITECTURE.md"
+else
+  echo "FAIL extension/ARCHITECTURE.md (no End of tour footer)"
+fi
+```
+
+Expected: eight `OK` lines, zero `FAIL`.
+
+- [x] **Step 3: No old paths remain in living docs**
+
+Run the same grep from Task 3 Step 3:
+```bash
+grep -rn --include='*.md' \
+  -e '](ARCHITECTURE\.md' \
+  -e '](\./ARCHITECTURE\.md' \
+  -e '](docs/ARCHITECTURE\.md' \
+  -e '](FORMATS\.md' \
+  -e '](\./FORMATS\.md' \
+  . 2>/dev/null \
+  | grep -v 'docs/superpowers/test-runs/' \
+  | grep -v 'docs/superpowers/audits/' \
+  | grep -v 'docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md' \
+  | grep -v 'docs/superpowers/plans/2026-05-30-doc-structure-redesign.md'
+```
+
+Expected: zero matches (modulo the excluded paths).
+
+- [x] **Step 4: Renames are git-tracked**
+
+Run:
+```bash
+git log --follow --oneline DESIGN.md | tail -3
+git log --follow --oneline docs/CRYPTO.md | tail -3
+git log --follow --oneline docs/FORMATS.md | tail -3
+```
+
+Expected: each shows commits *before* the rename (i.e., when the file was `ARCHITECTURE.md` / `docs/ARCHITECTURE.md` / `FORMATS.md`). If any shows only the rename commit and nothing else, `git log --follow` is not picking up the history — likely because of how the rename commit was made. Investigate and fix.
+
+- [x] **Step 5: CLAUDE.md table is current**
+
+Run:
+```bash
+grep -nE '\| `(DESIGN|docs/CRYPTO|docs/FORMATS)\.md` \|' CLAUDE.md
+```
+
+Expected: three matches (one for each renamed file). If fewer, the table row was missed in Task 4 Step 2.
+
+Also run:
+```bash
+grep -n '### Discipline rules' CLAUDE.md
+```
+
+Expected: one match.
+
+- [x] **Step 6: README architecture-section trim verification**
+
+Run:
+```bash
+awk '/^## Architecture/,/^## [^A]/' README.md | head -20
+```
+
+Expected: short paragraph (around 5-8 lines of prose), no codebase tree diagram, and a link to `DESIGN.md`. If the old tree diagram still shows, Task 2 Step 2 didn't land — go back and trim.
+
+- [x] **Step 7: Push**
+
+Once all six checks above pass, push all five commits:
+
+```bash
+git push
+```
+
+Expected: push succeeds. Working tree is clean (modulo the pre-existing dirt on `.claude/settings.json` etc.).
+
+- [x] **Step 8: Final summary**
+
+Echo a short summary of what landed: 5 commits, file count by category, anything that needed amending. This is for the user's reading pleasure, not a code change.
+
+---
+
+## Done
+
+Verify with the user that all tour docs flow naturally when read in order: `README → DESIGN → docs/CRYPTO → docs/FORMATS → docs/SECURITY → crates/relicario-core/ARCHITECTURE.md → crates/relicario-cli/ARCHITECTURE.md → extension/ARCHITECTURE.md`. If anything reads awkwardly, that's a content polish for a future pass, not a structural problem with this redesign.

docs/superpowers/reviews/2026-05-04-architecture-review.md

@@ -0,0 +1,265 @@
+# Relicario — Whole-Codebase Architecture Review
+
+**Date:** 2026-05-04
+**Reviewers:** DEV-A (Rust core), DEV-B (Rust consumers — CLI, server, WASM), DEV-C (TypeScript — extension, relay)
+**Synthesis:** PM
+**Goal lens:** "Make this app's architecture logical and readable for a smart developer who doesn't know Rust but wants to learn by tinkering."
+
+## Executive summary
+
+The architecture is fundamentally sound: bytes-in/bytes-out core, no I/O leakage from `relicario-core`, a server that structurally cannot decrypt (no AEAD or KDF crate in its dep graph), a service-worker boundary in the extension that holds (content scripts make zero WASM calls), and CLI/extension parity at 22/23 capabilities. What hurts the goal lens is uneven detail: a few outsized files (`cli/main.rs` 2641 LOC, `extension/src/setup/setup.ts` 1220 LOC, `extension/src/vault/vault.ts` 1027 LOC) absorb concerns that belong in smaller modules, and a couple of cross-cutting boilerplate clusters (16× duplicated git-shell error UX in the CLI; duplicated SW router helpers; hand-maintained `wasm.d.ts`) make a learner re-derive the same pattern repeatedly. The single most important thing to address is a defense-in-depth crypto issue spanning Rust and JS: `SessionHandle` has no `impl Drop`, so the wasm-bindgen-generated `.free()` is a no-op for cleanup — the master key stays in WASM linear memory until JS explicitly calls `lock()`. The strongest aspects worth preserving are the documentation density of the security-critical core files (`crypto.rs`, `imgsecret.rs`, `backup.rs`, `tar_safe.rs` all open with multi-paragraph rationale), the discriminated-union message contract in the extension (`shared/messages.ts` + the popup-only / content-callable capability sets), and the server's structural enforcement of the ciphertext-only invariant via its import surface. These three patterns are the model for what every other surface should look like.
+
+## Top-priority recommendations (P1)
+
+### P1.1 — `SessionHandle` has no `impl Drop`; `.free()` is a cleanup no-op
+**Area:** cross-cutting (wasm + extension)
+**File(s):** `crates/relicario-wasm/src/lib.rs:15-23`, `crates/relicario-wasm/src/session.rs:1-58`, `extension/src/service-worker/session.ts:26`
+**Found by:** DEV-B (Rust side, headline finding); DEV-C (symmetric JS-side concern, originally [P2])
+**Observation:** `SessionHandle` is `pub struct SessionHandle(u32)` with no `Drop` impl. wasm-bindgen's auto-generated JS `.free()` drops a `u32` — i.e. nothing. The `SESSIONS` HashMap entry stays alive with the master key and image_secret in WASM linear memory until JS calls the explicit `lock(handle)` (which calls `session::remove`). DEV-C separately observed `service-worker/session.ts:26` swallows `free()` errors with `try { current.free() }` — that swallow is hiding the fact that the call wasn't doing crypto cleanup anyway.
+**Why it matters for the user's goal:** This is the only finding in the review where the gap between "what the code looks like it does" and "what it actually does" is dangerous. A tinkerer reading `session.ts` reasonably assumes `free()` cleans up the WASM-side key; it does not. Defense-in-depth here is one Rust block and one JS audit.
+**Suggested direction:** Add `impl Drop for SessionHandle { fn drop(&mut self) { session::remove(self.0); } }` to the WASM crate so `.free()` becomes the safety net and `lock()` becomes the explicit "I am done" call. In parallel, remove the `try { ... }` swallow at `service-worker/session.ts:26` (let exceptions propagate or log + counter) and audit every `.free()` callsite under `extension/src/` to ensure `wasm.lock(handle)` happens first regardless. A `wasm-bindgen-test` covering construct → drop → confirm registry empty locks the contract.
+**Effort:** S (Rust fix) + S (JS audit) = ~1-2 hours total
+
+### P1.2 — `crates/relicario-cli/src/main.rs` is a 2641-line monolith
+**Area:** cli
+**File(s):** `crates/relicario-cli/src/main.rs:1-2641`
+**Found by:** DEV-B
+**Observation:** The clap surface (lines 1-455) is a tour of the product and reads beautifully. Past line 456 the file becomes flat: every `cmd_*`, every `build_*_item`, every `edit_*`, six prompt helpers, three parsing helpers, and 24+ git shell-outs all live as peers. `cmd_add` calls 7 different `build_*_item` functions (each ~50-60 lines) with no module boundaries. Searching "where does add work?" requires scrolling, not navigating.
+**Why it matters for the user's goal:** This is the first file a tinkerer opens after `cargo run -p relicario-cli -- --help`. Today they have to scroll through 2200 lines of flat code to follow any one command end-to-end. Splitting this is the precondition for fixing P1.3 and centralizing several other CLI patterns (groups-cache discipline, prompt helpers).
+**Suggested direction:** Keep `main.rs` as clap definitions + the dispatching `match` (~470 lines). Split into `commands/{add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr}.rs`, plus `prompt.rs` (the six `prompt_*` helpers + `prompt_secret`) and `parse.rs` (`parse_month_year`, `base32_decode_lenient`, `guess_mime`). Same LOC, different reading experience.
+**Effort:** M (mechanical split, no logic changes)
+
+### P1.3 — Git invocation boilerplate duplicated 16× with one-line errors
+**Area:** cli
+**File(s):** `crates/relicario-cli/src/main.rs:601, 602, 610, 986, 988, 1477, 1480, 1767, 1897, 1900, 2432, 2438, 2533, 2540` (and others)
+**Found by:** DEV-B
+**Observation:** Every `git_command` invocation that bails uses the same shape: `.args([...]).status()? + if !status.success() { bail!("git foo failed") }`. Child stderr is inherited interactively, but in test runs and noninteractive tooling it's lost, and the bail message is just the verb. When this fires in the wild — pre-receive reject, missing remote, dirty tree, signing-key prompt — the user sees one line and nothing actionable.
+**Why it matters for the user's goal:** This is the *entire* error UX for the git side of the CLI. Failures are common, the diagnostic is uniformly unhelpful, and a learner will hit "git commit failed" with no context the first time they touch a misconfigured remote.
+**Suggested direction:** Add `helpers::git_run(repo, args, context)` that uses `.output()` (capturing stderr), prints captured stderr unmodified on failure, and embeds the human-readable `context` ("commit add: GitHub", "register device", "purge trashed item"). 16 copies become one-liners.
+**Effort:** S (single helper + sweep)
+
+### P1.4 — `extension/src/setup/setup.ts` bypasses the SW and orchestrates WASM directly
+**Area:** extension
+**File(s):** `extension/src/setup/setup.ts:28-37`, `:1118-1120` (and the whole 1220-LOC file)
+**Found by:** DEV-C
+**Observation:** Popup, vault tab, and content scripts all funnel WASM through the service-worker. `setup.ts` is the only surface that imports `relicario-wasm` directly and orchestrates `unlock` / `embed_image_secret` / `register_device` / `manifest_encrypt` itself — duplicating ~400 LOC of crypto orchestration the SW already knows how to do. Side-effect: the setup tab can't be locked by the same session-timer the rest of the extension uses, and `WizardState` (passphrase + JPEG bytes + WASM handle) persists in module scope if the user abandons mid-wizard.
+**Why it matters for the user's goal:** This is the single biggest "code lies about the pattern" surface in the extension. A learner who opens `setup.ts` first will see WASM imported directly and conclude that's how the extension works — it isn't; everywhere else routes through `chrome.runtime.sendMessage`. The file is also a 1220-LOC procedural wizard that could be a step registry.
+**Suggested direction:** Add `create_vault` and `attach_vault` messages to the SW; turn `setup.ts` into a UI that posts those messages with the gathered config + image bytes. Convert the 6-step flow into a `{ id, render, attach }[]` step registry. The 1220 LOC drops to ~500. Add a `clearWizardState()` bound to `beforeunload` and to "return to step 0" so abandoned wizards don't persist sensitive material.
+**Effort:** L (architectural — touches setup, the SW message router, and `wasm.d.ts`/types)
+
+### P1.5 — `extension/src/vault/vault.ts` is a 1027-LOC do-everything file
+**Area:** extension
+**File(s):** `extension/src/vault/vault.ts:1-1027`
+**Found by:** DEV-C
+**Observation:** Single file owns: shell init, hash routing, sidebar render, list render, drawer state, type-picker, form-wrapper, deep-link routing, teardown coupling. Adding a new pane view today is a 5-place edit (`teardownPaneComponents` lines 813-820 is the symptom). Two state-management oddities sit inside: vault tab intercepts `vault_locked` errors via the RPC layer while the popup uses the `session_expired` event (two channels for one outcome), and `state.drawerOpen = true` survives navigation to non-list views.
+**Why it matters for the user's goal:** This is the second steepest cliff for a tinkerer (after `setup.ts`). The vault tab is the user's primary fullscreen experience; the file that drives it should read as orchestration, not implementation.
+**Suggested direction:** Split into `vault-shell.ts`, `vault-sidebar.ts`, `vault-list.ts`, `vault-drawer.ts`, `vault-form-wrapper.ts`, leaving `vault.ts` to own only routing and state. While doing so, lift the `vault_locked` RPC intercept into `shared/state.ts` (or a wrapper around `sendMessage`) so popup and vault use one path; reset `state.drawerOpen` at the start of `renderPane` for non-list views.
+**Effort:** M (mechanical split, plus one channel-unification touch)
+
+### P1.6 — `extension/src/shared/state.ts` is fully `any`-typed
+**Area:** extension (shared)
+**File(s):** `extension/src/shared/state.ts:10-35`
+**Found by:** DEV-C
+**Observation:** `StateHost` is the bridge that lets popup components run inside the vault tab — and it's the bridge most likely to drift between the two render targets — but its entire contract is `any`-typed. TS gives no signal when popup-only state shape diverges from vault-tab expectations. Module-scope `host` singleton additionally has no double-registration guard; tests forget a reset and the leak silently breaks isolation.
+**Why it matters for the user's goal:** Two-render-target reuse is exactly the kind of architecture decision that pays off in maintainability — but only if the contract is type-checked. As-is, the bridge is the weakest learning surface in the extension.
+**Suggested direction:** Define a concrete `StateHost` interface: `state: PopupState`, `navigate: (view: View) => void`, `popOutToTab(): void`, `isInTab(): boolean`, `openVaultTab(hash?: string): void`. Make `getState`/`setState` generic over `keyof PopupState`. Throw on `registerHost()` re-register; export a `__resetHostForTests()` helper.
+**Effort:** S-M (type definitions + sweep through callers)
+
+### P1.7 — `crates/relicario-core/src/recovery_qr.rs` is undocumented
+**Area:** core
+**File(s):** `crates/relicario-core/src/recovery_qr.rs:1-130`
+**Found by:** DEV-A
+**Observation:** No module-level `//!` header. No doc comments on `RecoveryQrPayload`, `generate_recovery_qr`, `unwrap_recovery_qr`, or `recovery_qr_to_svg`. Magic constants (`RREC`, `VERSION = 0x01`, `PAYLOAD_LEN = 109`) sit at the top with no explanation; the 4+1+32+24+48 layout is hand-counted with no struct, diagram, or asserts. The domain-separation prefix `b"relicario-recovery-v1\0"` exists but isn't explained. `production_params()` redeclares `KdfParams::default()` values with no comment on why the recovery format pins them.
+**Why it matters for the user's goal:** Every other security-relevant file in the core (`crypto.rs`, `imgsecret.rs`, `backup.rs`, `tar_safe.rs`) has explanatory framing. A learner hitting `recovery_qr.rs` sees a different style and assumes either it doesn't matter or they've stumbled out of the documented zone. It does matter — this is the vault-key escape hatch — and a misuse here (e.g., reusing `production_params` as `KdfParams::default()` and then changing the default) silently breaks all extant recovery QRs.
+**Suggested direction:** Add a module-level `//!` summarizing the format, the KDF-input domain separation, and the parameter-pinning rationale. Add a short ASCII diagram of the 109-byte layout near the constants. Doc-comment the four public functions. Either replace `production_params()` with a `const` or add a comment explaining the deliberate divergence from `KdfParams::default()`.
+**Effort:** S (documentation only)
+
+### P1.8 — `tools/relay/queue.test.ts` fails on uncommitted state
+**Area:** tooling
+**File(s):** `tools/relay/queue.test.ts:54`
+**Found by:** DEV-C (verified via `bun test` → 1 fail / 4 pass)
+**Observation:** Uncommitted changes added `dev-c` to the `Role` union and `KNOWN_ROLES` set in `queue.ts`, but the test still asserts the old enum: `assert.ok(!isRole("dev-c"))`. One-line fix.
+**Why it matters for the user's goal:** A learner running `bun test` from `tools/relay/` immediately sees a failure and assumes the codebase is broken. The relay is the literal coordination substrate of this review; a green test run is table stakes.
+**Suggested direction:** Update the test assertion to `assert.ok(isRole("dev-c"))` and add a negative case (`assert.ok(!isRole("dev-d"))`). Confirm `start.sh` opens a fourth window for dev-c (DEV-C suspected `:80` still hardcodes "Dev-B" in user-facing output).
+**Effort:** S (one-line edit + one-launcher-line check)
+
+### P1.9 — Duplicated SW router helpers (storage helpers + `itemToManifestEntry`)
+**Area:** extension (service-worker)
+**File(s):** `extension/src/service-worker/router/popup-only.ts:687-703` and `:~169`; `extension/src/service-worker/router/content-callable.ts:187-205` and `:~169`
+**Found by:** DEV-C
+**Observation:** Three identical `chrome.storage.local` helpers (`loadDeviceSettings`, `loadBlacklist`, `saveBlacklist`) and the 17-line `itemToManifestEntry()` projection are duplicated across both router files. Both code paths can mutate the blacklist via different definitions; future drift will silently corrupt one path. Manifest schema refactors will need to be made twice.
+**Why it matters for the user's goal:** A learner reading either router file sees private helpers and assumes that's where they live; finding the same name in the sibling router with a near-identical body is a routine "wait, why is this duplicated?" moment that should not exist in a tightly-typed message-router architecture.
+**Suggested direction:** Extract the three storage helpers to `service-worker/storage.ts`; move `itemToManifestEntry` into `service-worker/vault.ts`. Import from both router files. Pair this with [P1.6] for `shared/state.ts` typing — both are about giving the extension's "shared utilities" a concrete shape.
+**Effort:** S (extract + sweep)
+
+### P1.10 — Pure parsers in CLI that the extension will eventually need
+**Area:** cli → core
+**File(s):** `crates/relicario-cli/src/main.rs:942-980` (`parse_month_year`, `base32_decode_lenient`, `guess_mime`)
+**Found by:** DEV-B
+**Observation:** Three pure parsers producing typed core values currently live only in the CLI. Per the project's CLI/extension parity philosophy (CLAUDE.md memory rule), anything the CLI does in pure logic the extension will eventually need too — QR-import, month-year smart input, attachment MIME detection. There is also a `base32_encode` in `core/item.rs` and a `decode_base32_totp` in `core/import_lastpass.rs` that are inverse pairs in different modules — DEV-A flagged the same shape from the core side ([P2] base32 has three implementations).
+**Why it matters for the user's goal:** Parity is a stated design philosophy, and parser drift between CLI and extension is the most likely place for it to fail silently.
+**Suggested direction:** Migrate to core: `MonthYear::parse` (already partial in `time.rs`), `Totp::parse_secret` (or `ItemCore::parse_totp_seed`), `mime::guess_for_extension`. Pair with extracting a `pub(crate) mod base32` in core with `encode_rfc4648` / `decode_rfc4648`, leaving Steam's bespoke alphabet where it is. The CLI keeps thin wrappers; the WASM crate exposes the new functions; the extension calls them via SW message handlers.
+**Effort:** M (move + adjust CLI callers + add WASM exports)
+
+## P2 recommendations
+
+### Core (Rust)
+- **`extract_with_crop_recovery` is narrower than the spec describes.** `crates/relicario-core/src/imgsecret.rs:849-899`. Spec promises 15% from any edge; impl pins `dx=0, dy=0` and varies only `orig_w`/`orig_h`. Left/top crops won't recover. Either extend the recovery loop or update the spec language to "right/bottom crop tolerance only." (DEV-A)
+- **Stale "in-progress rewrite" headers** in `vault.rs:1-7`, `manifest.rs:1-2`, `attachment.rs:1-4`. Each comment describes work that already shipped. Replace with one-line module summaries. (DEV-A)
+- **Two dead fields in `EmbedRegion`** (`imgsecret.rs:225-229`). `region_width`/`region_height` are computed, stored, and silenced with `#[allow(dead_code)]`. Either delete or comment the future use. (DEV-A)
+- **Three base32 implementations.** `item.rs:255-275`, `import_lastpass.rs:202-220`, `item_types/totp.rs:13` (Steam, intentionally different). Extract a `pub(crate) mod base32`; leave Steam alone with a neighbour comment. (DEV-A; folds into P1.10.)
+- **Backup format embeds the reference JPEG as base64-in-JSON** (`backup.rs:148-152, 274-280, 343-345`). Round-trip works; bloats by ~33% over the binary baseline post-zstd. Defer until backup-size pressure shows up. (DEV-A)
+
+### CLI (Rust)
+- **`build_*_item` functions mix prompting, parsing, and core construction.** `main.rs:664-921`. Compress with a `prompt_or_flag<T>` helper. (DEV-B)
+- **`refresh_groups_cache` invocation discipline is manual at 7 sites.** `main.rs:641, 998, 1123, 1197, 1414, 1432, 1474`. Rule "every mutating handler must call this" is unenforced. Wrap in `Vault::after_manifest_change(&self, manifest: &Manifest)`. (DEV-B)
+- **`ParamsFile` defined twice with mismatching shapes.** Write side `main.rs:2287` has `aead`, `salt_path`, `format_version`; read side `session.rs:114` takes only `kdf`. Single struct in core or shared session module. (DEV-B)
+- **`cmd_purge` and `cmd_trash_empty` duplicate the manifest-add-and-commit dance** (`main.rs:1476-1480, 1896-1900`). 50-item purge does 150 git invocations; batch the staging. (DEV-B)
+
+### Server (Rust)
+- **`generate-hook` assumes `$PATH`.** `relicario-server/src/main.rs:170`. Most Gitea hook environments don't have `/usr/local/bin`; `command not found` is the failure mode. Embed `current_exe()` or emit an explicit `PATH=` line. (DEV-B)
+- **Bootstrap branch is permissive.** `:38-44, 54-57`. Missing `.relicario/devices.json` at `newrev` is treated as bootstrap. An attacker pushing a brand-new branch that strips `.relicario/` could push unsigned commits. Either document the rule or enforce: `oldrev != 0` ⇒ `devices.json` must exist in `newrev`. (DEV-B)
+- **stdin-parsing lives in the shell hook only.** `:130-189`. Wiring up the binary by hand isn't possible without re-implementing the per-line `<old> <new> <ref>` parse. Add `verify-commit --from-stdin` or doc-comment the constraint. (DEV-B)
+- **Test coverage gaps** (`tests/verify_commit.rs`): unsigned-commit, malformed `devices.json`, bootstrap-empty, stripped-`.relicario/`. Each is one extra `#[test]`. (DEV-B)
+
+### WASM (Rust)
+- **Redundant double-lookup pattern.** `lib.rs:73, 84, 92, 103, 111, 122, 160, 172` all do `need_key(handle)?` then `session::with(handle.0, |k| ...).unwrap()` — two HashMap lookups per call. Single-`with` helper that returns `JsError` on miss. (DEV-B)
+- **`Vec<u8>` getters clone on every read.** `EncryptedAttachment::aid` and `bytes` (`lib.rs:141-150`). Document "call once, cache locally" or consume by value. (DEV-B)
+- **`wasm_*_recovery_qr` prefix is inconsistent** with everything else. `lib.rs:497, 510`. Rename to `generate_recovery_qr_svg` and `unwrap_recovery_qr` (and update `extension/src/wasm.d.ts`). Trivial breaking rename — do it before any new caller appears. (DEV-B)
+- **`device.rs` and `session.rs` use different concurrency primitives** (`Lazy<Mutex<...>>` vs `thread_local! { RefCell<...> }`). Pick one. (DEV-B)
+- **`extension/src/wasm.d.ts` is hand-written and explicitly requires manual sync** with `crates/relicario-wasm/src/lib.rs`. Every change to `#[wasm_bindgen]` must be mirrored manually; today they're aligned. Add a CI check comparing `wasm-pack`–generated `.d.ts` against this file, or import the generated file directly. (DEV-C; partner finding to DEV-B's WASM section.)
+
+### Extension — service-worker
+- **Inactivity timer reset skips content-callable messages** (`service-worker/index.ts:76-78`). A user actively autofilling but not opening the popup will be force-locked despite continuous use. Reset on all messages except known read-only content calls. (DEV-C)
+- **Session expiry clears `state.manifest` but leaves `state.gitHost`** (`service-worker/index.ts:51-58`). Cached git-host client survives expiry; rotation could mix with stale connection state. Null `state.gitHost` alongside. (DEV-C)
+- **`try { current.free() }` swallows free errors** (`service-worker/session.ts:26`). See P1.1 — this becomes important once `impl Drop` lands. (DEV-C)
+
+### Extension — popup + components
+- **Duplicated teardown helpers** (`settings.ts:56-65` and `settings-vault.ts:15-22`). After the recent stub-restore commits (`8baef5b`, `ddfb95d`), teardown leaks are a known regression class — duplicated cleanup is exactly the pattern that re-introduces them. Extract a single `teardownSettingsCommon()`. (DEV-C; originally P1, demoted by PM because the leak vector is small but the duplication is real.)
+- **Settings module-scope singletons** (`settings.ts:33-34`). `pendingVaultSettings` and `sessionHandle` survive section navigation. Reset on `renderSection` entry, or scope into a closure per render. (DEV-C)
+- **Item-list popover wires listeners on every render** (`item-list.ts:152-353`) without a reuse path. Cache the DOM and reuse, or use AbortController. (DEV-C)
+- **`Promise.all` without per-promise error handling** (`devices.ts:47-50`, `trash.ts:39-46`). Single rejected RPC fails the whole render. Use `Promise.allSettled`. (DEV-C)
+- **Generator-panel cleanup not idempotent-guarded** (`generator-panel.ts:89-261`). Currently safe by accident. Add `if (!activePanel) return`. (DEV-C)
+- **Popup teardown calls every type module unconditionally** (`popup.ts:178-181`). Track last-mounted type. (DEV-C)
+
+### Extension — vault tab
+- **Vault tab intercepts `vault_locked` via RPC; popup uses `session_expired` event.** `vault/vault.ts:47-74`. See P1.5 — collapse into one mechanism in `shared/state.ts`. (DEV-C)
+- **Drawer doesn't auto-close on non-list view changes** (`vault.ts:495-536`). Reset `state.drawerOpen = false` in `renderPane`. (DEV-C)
+- **Sidebar re-renders on every search keystroke without debounce** (`vault.ts:648-695`). 50-100ms debounce. (DEV-C)
+
+### Extension — content scripts
+- **`fillFields()` returns silently when no password field is found** (`content/fill.ts:50-64`). Dynamic forms can race the listener; user clicks autofill, nothing happens. Send a `fill_failed` ack. (DEV-C)
+- **MutationObserver scan is not debounced** (`content/detector.ts:96-103`). SPA churn re-runs the full scan many times per second. Wrap in `requestIdleCallback` or 200ms timer. (DEV-C)
+- **Outside-click listener leaks on alternate close paths** (`content/icon.ts:169-175`). AbortController scoped to picker open, or remove in every close path. (DEV-C)
+
+### Extension — setup
+- **`setup.ts` 1220-LOC procedural wizard.** Step registry pattern. See P1.4. (DEV-C)
+- **`WizardState` is module-scope; sensitive material persists if user abandons mid-wizard** (`setup.ts:69-94`). Add `clearWizardState()` on `beforeunload` and on returning to step 0. Folds into P1.4. (DEV-C)
+- **Manifest path constants duplicated** between `setup/probe.ts:11-23` and `service-worker/vault.ts`. Define `VAULT_PATHS` in `shared/types.ts` (or `shared/paths.ts`). (DEV-C)
+
+### Extension — shared utilities
+- **Base `Response` is `{ data?: unknown }`; every consumer does hand-written `as ListItemsResponse` casts** (`shared/messages.ts:85-87`). Generic `Response<TKind extends Request['type']>` mapped from a single `MessageMap` table. (DEV-C)
+- **`group-autocomplete.ts:26` builds list HTML via `innerHTML` with only `&quot;` escaping.** Group names are user-entered. `<` and `>` aren't escaped — markup-injection risk. Use `document.createElement('option')`. (DEV-C)
+- **`restore_backup` flattens `newRemote` inline** (`shared/messages.ts:56-66`). Inconsistent with sibling messages. Extract `RestoreBackupPayload`. (DEV-C)
+
+### WASM boundary (JS side)
+- **`__stubs__/relicario_wasm.stub.ts` only stubs 7 of ~25 exports.** Adding a vitest test that touches a new WASM call needs an ad-hoc per-test mock. Round out the stub or provide a `mockWasm({...})` test helper. (DEV-C)
+
+### Relay tooling
+- **`tools/relay/start.sh:80` may still reference "Dev-B"** in user-facing output despite the dev-c expansion. Confirm a fourth window opens for dev-c. (DEV-C)
+- **`tools/relay/call.py` and `call.ts` are untracked but load-bearing** for the multi-agent fallback path (kickoff prompts reference `call.py` by path). Either track them with a one-line header explaining "MCP-fallback shim" or add to `.gitignore`. (DEV-C)
+- **In-memory queue has no TTL, persistence, or cap** (`queue.ts:21-27`). Document the dev-only ephemeral contract or add a per-role cap. (DEV-C)
+
+### Cross-cutting
+- **`#[allow(dead_code)]` without explanation** appears in `cli/device.rs`, `cli/gitea.rs`, and `wasm/device.rs`. Each is either "API completeness" or "scar tissue." Annotate with `// TODO(<plan>):` or delete. (DEV-B)
+- **Direct `chrome.storage.local` reads from popup components** (`settings-security.ts:112-113`, `setup.ts:1056-1062`). Every other module routes via `sendMessage`. Pick one paradigm and document the exception. (DEV-C)
+- **`bun test` is not the project's intended runner** (`extension/package.json:13` is `vitest run`; `tools/relay/` uses `node:test` via `bun test`). README clarification. (DEV-C)
+- **Error formatting is inconsistent** across all three Rust crates: CLI mixes sentence-case and lowercase fragments; server is `eprintln!("REJECT: ...")` *except* the malformed-devices.json path; WASM ranges from explicit messages to `RelicarioError::Display` passthrough. Short style note + audit pass. (DEV-B)
+
+## P3 / nice-to-have
+
+A long tail of style sweeps and small ergonomic wins. Pulling the most representative; full lists in the per-reviewer notes.
+
+- Inconsistent error types and constant styles in core (`MonthYear::new -> Result<_, &'static str>`; `pub const MAGIC: [u8;4]` vs `const MAGIC: &[u8;4]`; empty `[dev-dependencies]`). (DEV-A)
+- Mid-file `use` blocks in `item.rs:117-122` and `attachment.rs:43-46`. (DEV-A)
+- `r#type` field on `Item` and `ManifestEntry` — rename to `item_type` with `#[serde(rename = "type")]`. (DEV-A)
+- BIP39 minimum word count of 3 is misleading vs. the 128-bit-security framing — restrict to canonical sets or rename to "BIP39-wordlist passphrase generator." (DEV-A)
+- `STEAM_ALPHABET` source comment contradicts its own test about the '5' character. (DEV-A)
+- `let _ = entry;` newcomer-hostile pattern repeated 6× in CLI. (DEV-B)
+- `cmd_recovery_qr_unwrap` doesn't check empty input before base64 decode; QR ASCII and "NOT been saved" mixed on stdout (pipe-unfriendly). (DEV-B)
+- `Lock` CLI subcommand is a visible no-op; either `#[command(hide = true)]` or document the parity rationale. (DEV-B)
+- Three test-only env vars duplicated under `#[cfg(debug_assertions)]/#[cfg(not(debug_assertions))]` — one macro flattens ~30 lines. (DEV-B)
+- WASM exports use snake_case in JS (`manifest_encrypt`); JS idiom is camelCase. Decide once via `#[wasm_bindgen(js_name = ...)]`. (DEV-B/DEV-C)
+- Glyph-rule partial adoption — six popup files use raw glyph literals (`⧉`, `↻`, `▸`, `▾`, `≡`, `⤓`) inline despite the `glyphs.ts` abstraction. Add the missing constants and migrate. (DEV-C)
+- `TotpKind = 'totp' | 'steam' | { hotp: { counter: number } }` mixed string/object union — flat discriminated union reads cheaper. (DEV-C)
+- `void tick()` in `totp-tools.ts:39-46` swallows promise rejections. (DEV-C)
+- `setup.ts:1-7` header says "5-step flow"; code is 6 steps (0..5). (DEV-C)
+- `helpers.rs:37 #[allow(dead_code)] pub fn relicario_dir()` has no callers but several `vault_dir.join(".relicario")` sites should use it. (DEV-B)
+- `gitea.rs` constructs a fresh `reqwest::blocking::Client::new()` per method call — make it a struct field. (DEV-B)
+
+## Cross-cutting themes
+
+**1. The "where the work happens" boundary holds, but two surfaces lie about it.** `relicario-core` is genuinely platform-agnostic (no fs, no net, no git) and the server provably cannot decrypt (no AEAD/KDF crate present). The extension's content scripts make zero direct WASM calls. These are excellent structural invariants. The two surfaces that break the pattern are `extension/src/setup/setup.ts` (loads WASM and orchestrates crypto directly, bypassing the SW) and the `SessionHandle` `.free()` non-cleanup contract on the WASM/JS boundary. Both are P1; both are also single-surface fixes. The architecture is one P1.1 + one P1.4 away from being uniform.
+
+**2. Duplication concentrates at boundaries, not inside modules.** The two router files duplicate storage helpers and `itemToManifestEntry` (P1.9). The CLI duplicates git-shell error UX 16× (P1.3). Three base32 implementations live in core (P2). Two `ParamsFile` definitions disagree (P2). `parse_month_year` / `base32_decode_lenient` / `guess_mime` live only in the CLI but the extension will need them (P1.10). The pattern: every time a concept crosses a module/crate boundary, the second crossing copies the first instead of importing it. The remedy is small extractions (one helper module per cluster), not refactors. None of these are individually expensive; together they account for a meaningful fraction of total findings.
+
+**3. Three files account for most of the readability cost.** `cli/main.rs` (2641 LOC), `setup.ts` (1220 LOC), `vault.ts` (1027 LOC). Each carries multiple concerns that belong in sibling modules. Splitting all three is cumulative ~M-L effort and unlocks several smaller cleanups (centralizing groups-cache discipline depends on splitting `main.rs`; the SW message-routing fix depends on extracting `setup.ts`'s WASM orchestration; lifting the `vault_locked` channel depends on splitting `vault.ts`). For the user's stated learning-by-tinkering goal, these three splits are the highest-leverage architectural moves available.
+
+**4. Documentation density is uneven in exactly one place.** Core's security-critical files (`crypto.rs`, `imgsecret.rs`, `backup.rs`, `tar_safe.rs`) open with multi-paragraph rationale walking through the *why*. `recovery_qr.rs` does not — and it's the user-visible last-resort recovery mechanism. Bringing one file up to the existing standard is a P1.7 effort of S. Beyond that one file, the core doc story is genuinely strong; preserve it.
+
+## What's strong (preserve)
+
+- **`crypto.rs`, `imgsecret.rs`, `backup.rs`, `tar_safe.rs`: documentation density.** Each opens with multi-paragraph rationale (XChaCha20 vs AES-GCM, QIM with QUANT_STEP=50, length-prefixed concatenation, tar-bomb defenses). This is the model the rest of the crate should be measured against.
+- **`relicario-server` trust-model enforcement via the import surface.** The server cannot decrypt the vault even in principle: no AEAD or KDF crate in its dep graph; the entire `relicario-core` import surface is `DeviceEntry`, `RevokedEntry`, `fingerprint`, and (in tests) `generate_keypair` — all plaintext device metadata. This is structural, not by convention.
+- **Discriminated-union message contract in the extension.** `shared/messages.ts` + the `POPUP_ONLY_TYPES` / `CONTENT_CALLABLE_TYPES` capability sets give every router handler typed dispatch with origin-aware gating. Content scripts make zero WASM calls and re-validate origin in `fill.ts:32-38`. The boundary discipline holds.
+- **Test design across the codebase.** Synthetic JPEGs via `make_test_jpeg()` (no binary fixtures), raw-byte tar bombs that bypass the tar crate's sanitizer, RFC6238 vector for TOTP, an independent reference impl cross-check for Steam, ~30 LastPass importer cases, NFC/NFD round-trips, day-boundary tests for retention. The tests are themselves a documentation artifact.
+- **Helpers.rs in the CLI.** Small, focused, tested, and the doc-comment at `:90-93` explaining the plaintext `groups.cache` trade-off is admirably explicit. The git-command hardening (`core.hooksPath=/dev/null`, `commit.gpgsign=false`, `core.editor=true`) is exactly the right kind of comment to leave for a learner.
+
+## CLI/extension parity status
+
+Per DEV-C's full table: **22 of 23 CLI subcommands have a clean extension equivalent**.
+
+- **Clean parity (✓)**: `init`, `add` (all 7 item kinds), `get`, `list` (with all filters), `edit`, `history`, `rm` (soft delete), `restore`, `purge`, `trash list`/`empty`, `backup export`/`restore`, `import lastpass`, `attach`, `attachments`, `extract`, `generate`, `settings *`, `sync`, `lock`, `rate`, `device add`/`revoke`/list, `recovery-qr generate`/`unwrap`. The settings unification under v0.5.1's left-nav (commit `bd6a301`) is the right shape.
+- **Partial (✗ish)**: `detach <item> <aid>`. Extension uses a roundtrip through `update_item` with the `attachments[]` mutated client-side. Functional but racy if two devices edit at once. **Suggested fix**: add a `delete_attachment` SW message that does the surgical remove server-side. (P3.)
+- **True gap (✗)**: `relicario status`. CLI shows pending sync state, ahead/behind, dirty-tree summary; extension surfaces nothing comparable. **Suggested fix**: `get_vault_status` message returning `{ ahead, behind, lastSyncAt, pendingItems }` plus a small status indicator in the vault sidebar. (P2.)
+- **Browser-only (by design)**: `get_autofill_candidates`, `get_credentials`, `check_credential`, `blacklist_site`, `capture_save_login`, `fill_credentials`, `ack_autofill_origin`, `get_blacklist`, `remove_blacklist`, `get_active_tab_url`, `update_settings` for `DeviceSettings`. No CLI counterpart needed.
+- **CLI-only (by design)**: `completions <shell>`. n/a.
+
+**No "CLI first, extension follow-up" violations found** under this lens. The parity philosophy is intact; the one gap and the one partial are surgical fixes, not architectural debt.
+
+## Beginner-friendliness assessment
+
+Three reviewers converge on a consistent story for a smart developer who's never written Rust but wants to learn by tinkering.
+
+**Where the floor is high already:**
+- `crates/relicario-core/` reads beautifully: bytes-in/bytes-out boundary holds, public API is enumerated in one `lib.rs`, module names map directly to vault concepts (`item`, `manifest`, `attachment`, `settings`, `generators`, `vault`, `backup`, `device`, `recovery_qr`), and the algorithmically dense `imgsecret.rs` is the most heavily commented. A reader can land in `crypto.rs`, follow `derive_master_key` → `encrypt` → `vault::encrypt_item`, and reach `tests/integration.rs::full_workflow_login_and_note` in one sitting.
+- `relicario-server` is 189 lines, one trust-model question, every dependency is plaintext metadata. Readable end-to-end in under ten minutes.
+- The extension's discriminated-union message contract (`shared/messages.ts` + `types.ts`) gives the entire vocabulary in 500 lines. The per-type item form modules (`popup/components/types/login.ts` and siblings) are small parallel surfaces — once one clicks, the others read as variations.
+
+**Where the cliff is:**
+- **`cli/main.rs`** at 2641 LOC is the first real wall. A reader following `cmd_add` finds 7 peer `build_*_item` functions plus 6 prompt helpers plus 3 parsers, all in a flat file. (P1.2.)
+- **`extension/src/setup/setup.ts`** at 1220 LOC is the second wall, and it's worse because it lies about the architecture: a reader who opens this file first sees WASM imported directly and concludes that's the pattern — it isn't. (P1.4.)
+- **`extension/src/vault/vault.ts`** at 1027 LOC is the third. The vault tab is the user's primary surface; the orchestrator file shouldn't also be the implementation file. (P1.5.)
+- **`shared/state.ts`** is the weakest learning surface in the extension — `any`-typed bridge between popup and vault tab, no double-registration guard. (P1.6.)
+- **`recovery_qr.rs`** in core is the one file where a reader will hit a wall in an otherwise-well-documented crate. (P1.7.)
+
+**The single most valuable change** for the user's stated goal: split `cli/main.rs` into a `commands/` folder (P1.2). It's the first file a tinkerer opens, the change is mechanical, and it unlocks several smaller cleanups (centralized git error UX, unified groups-cache discipline). After that, in order: bring `recovery_qr.rs` to the existing core doc standard (P1.7), extract `setup.ts`'s WASM orchestration into SW messages (P1.4), and split `vault.ts` (P1.5). The four together turn "this is mostly readable" into "this is uniformly readable."
+
+## Open architectural decisions (escalated by reviewers; user judgement)
+
+Pulled from DEV-B's question list and DEV-C's flags. None are blockers for the synthesis; each is a one-paragraph user decision.
+
+1. **Was `impl Drop for SessionHandle` deliberately omitted?** (e.g. to avoid double-free if JS holds two refs.) PM verdict at synthesis: not deliberate; it's the headline fix (P1.1). User: confirm.
+2. **Should CLI `parse_month_year`, `base32_decode_lenient`, `guess_mime` migrate to core?** PM verdict: yes, for parity (P1.10). User: confirm timing.
+3. **Is "missing `.relicario/devices.json` = bootstrap = accept" intended in perpetuity?** Or should it tighten once a repo has any non-empty devices.json in history? (DEV-B P2.) User: pick a rule.
+4. **Is the `Lock` no-op CLI subcommand worth keeping visible in `--help` for parity?** Or hide behind `#[command(hide = true)]`? (DEV-B P3.) User: pick.
+5. **Has Task 12 shipped?** `cmd_backup_export` still reads `devices.json` per a "Task 12 will remove" TODO at `main.rs:1535-1537`. (DEV-B P3.) User: confirm and clean up.
+6. **Track `tools/relay/call.py` and `call.ts`, or `.gitignore` them?** They're load-bearing for the multi-agent fallback path. (DEV-C P2.) PM verdict: track them — they're documented in coordination prompts.
+7. **WASM JS naming: snake_case (current) or camelCase?** Trivial breaking rename via `#[wasm_bindgen(js_name = ...)]`, but only if done before the surface grows. (DEV-B/DEV-C P3.) User: pick once.
+8. **`.gitea_env_vars` is untracked.** Name suggests local credentials. PM verdict: should be `.gitignore`d if it isn't already. User: confirm.
+
+## Appendix: pointers to per-reviewer notes
+
+- [DEV-A notes — Rust core](./2026-05-04-dev-a-notes.md)
+- [DEV-B notes — Rust consumers (CLI, server, WASM)](./2026-05-04-dev-b-notes.md)
+- [DEV-C notes — TypeScript (extension + relay)](./2026-05-04-dev-c-notes.md)

docs/superpowers/reviews/2026-05-04-dev-a-notes.md

@@ -0,0 +1,191 @@
+# DEV-A Architecture Review Notes — Rust Core
+
+Scope: `crates/relicario-core/src/**` (17 source files, ~5.5 kLOC) and `crates/relicario-core/tests/**` (9 integration suites). HEAD reviewed; the only uncommitted change in core is a version bump (`0.2.0 → 0.5.0` in `Cargo.toml`), nothing semantic.
+
+## Summary
+
+The crate has a clear, well-shaped architecture: a thin `lib.rs` re-exporting one concept per module, a unified `RelicarioError` enum, and a strict bytes-in/bytes-out posture (no fs, no net, no git anywhere — the boundary is held). The strongest part is the documentation density of the security-critical files: `crypto.rs`, `imgsecret.rs`, `backup.rs`, and `tar_safe.rs` each open with multi-paragraph rationale that walks a reader through the *why* (XChaCha20 vs AES-GCM, QIM with QUANT_STEP=50, length-prefixed concatenation, tar-bomb defenses) — exactly the "legibility-as-security" philosophy the README aspires to. Tests are excellent: RFC6238 vector for TOTP, an independent reference impl cross-check for Steam, NFC/NFD round-trips, raw-byte tar bombs that bypass the tar crate's sanitiser, and ~30 LastPass importer cases. The weakest part is unevenness — `recovery_qr.rs` is essentially undocumented despite being the user-visible last-resort recovery mechanism, and three modules (`vault.rs`, `manifest.rs`, `attachment.rs`) still carry "during this rewrite" / "added later in Task 22" headers from work that has long since shipped, which will mislead a newcomer about what's load-bearing.
+
+`cargo clippy -p relicario-core --all-targets --no-deps` runs clean (no warnings).
+
+## Findings (prioritized)
+
+### P1 — `recovery_qr.rs` doc gap is conspicuous against the rest of the crate
+
+**File(s):** `crates/relicario-core/src/recovery_qr.rs:1-130` (whole file)
+**Observation:** No module-level `//!` header. No doc comments on `RecoveryQrPayload`, `generate_recovery_qr`, `unwrap_recovery_qr`, or `recovery_qr_to_svg`. Magic constants (`RREC`, `VERSION = 0x01`, `PAYLOAD_LEN = 109`) sit at top with no explanation, and the 4+1+32+24+48 layout is hand-counted with no struct, no diagram, and no asserts. The domain-separation prefix `b"relicario-recovery-v1\0"` exists but isn't explained. `production_params()` redeclares the same values as `KdfParams::default()` with no comment on why the recovery format pins them.
+**Why it matters:** Every other security-relevant file (`crypto.rs`, `imgsecret.rs`, `backup.rs`, `tar_safe.rs`) has the explanatory framing this codebase rewards readers for. A newcomer hitting `recovery_qr.rs` sees a different style and assumes either it doesn't matter or they've stumbled out of the documented zone. It does matter — this is a vault-key escape hatch — and a misuse here (e.g., reusing `production_params` as `KdfParams::default()` and then changing the default) silently breaks all extant recovery QRs.
+**Suggested direction:** Add a module-level `//!` summarizing the format, the KDF-input domain separation, and the parameter-pinning rationale. Add a short ASCII diagram of the 109-byte layout near the constants. Doc-comment the four public functions. Either replace `production_params()` with a `const` or add a comment explaining the deliberate divergence from `KdfParams::default()`.
+
+### P2 — Stale "in-progress rewrite" headers in three core files
+
+**File(s):**
+- `crates/relicario-core/src/vault.rs:1-7` ("v1 helpers ... intentionally NOT carried forward. The CLI rewrite in Plan 1B switches to the new helpers.")
+- `crates/relicario-core/src/manifest.rs:1-2` ("Lives next to the old entry.rs Manifest during this rewrite; entry.rs is deleted in Task 25.")
+- `crates/relicario-core/src/attachment.rs:1-4` ("Encryption helpers ... are added later in Task 22 once the crypto module is settled.")
+
+**Observation:** Each comment describes work that has already shipped. Task 22 added the helpers (they're 30 lines below in the same file). `entry.rs` is gone. Plan 1B is merged. The text reads as if there's a sibling file or a future change to wait for.
+**Why it matters:** A newcomer trying to understand the manifest will go looking for `entry.rs` to compare. A newcomer reading `attachment.rs` will read past the helpers thinking "those are coming later." These are the cheapest possible cleanup — comment edits — and they each remove a tripwire.
+**Suggested direction:** Replace with a one-line description of what the module *is*, not what it was during the rewrite.
+
+### P2 — `extract_with_crop_recovery` is narrower than the spec describes
+
+**File(s):** `crates/relicario-core/src/imgsecret.rs:849-899`
+**Observation:** The design spec (`docs/superpowers/specs/2026-04-11-relicario-design.md` §imgsecret extraction step 3) says crop recovery iterates `(dx, dy)` from -15% to +15% stepping by 8 px (~16,800 candidates for 4000×3000). The code only varies assumed original `orig_w`/`orig_h` while pinning `dx = 0, dy = 0`. The successful-crop test at `imgsecret.rs:1108-1137` only crops the *right* edge, where dx=0 happens to be the correct offset.
+**Why it matters:** Crops from the *left* or *top* (e.g. an Instagram square crop centered on a portrait, or any social-media platform that re-frames around faces) won't recover. The spec promises "15% from any edge"; the implementation delivers ~15% from the right and bottom only. Either the spec is wrong (which is allowed — the spec is marked historical) or the implementation has a quiet hole in the recovery surface. If the user ever uploads their reference JPEG to a service that left-crops, recovery will fail and the failure mode looks like "your image is wrong" rather than "we don't try that crop direction."
+**Suggested direction:** Either (a) extend the recovery loop with a small dx/dy search bounded by the 15% margin, or (b) update the spec language and the user-facing docs to say "right/bottom crop tolerance only." A third option is to add a test that left-crops a watermarked image and currently fails — that captures the gap and lets future work close it.
+
+### P2 — Two dead fields in `EmbedRegion`
+
+**File(s):** `crates/relicario-core/src/imgsecret.rs:225-229`
+**Observation:** `region_width` and `region_height` are computed in `compute_region`, stored in the struct, and silenced with `#[allow(dead_code)]`. Nothing reads them — downstream code uses `blocks_x` / `blocks_y` and `BLOCK_SIZE`.
+**Why it matters:** The `#[allow(dead_code)]` is an explicit "I know this is unused" — a newcomer reasonably assumes the fields are load-bearing and will hunt for the consumers, finding nothing. Either they're pre-positioned for a future feature (in which case a comment saying so would help) or they should go.
+**Suggested direction:** Delete both fields and the allow attributes, or add a one-line comment explaining the future use. (The struct is private, so removal is risk-free.)
+
+### P2 — Three base32 implementations live in one crate
+
+**File(s):**
+- `crates/relicario-core/src/item.rs:255-275` (`base32_encode`, RFC 4648 alphabet)
+- `crates/relicario-core/src/import_lastpass.rs:202-220` (`decode_base32_totp`, same alphabet)
+- `crates/relicario-core/src/item_types/totp.rs:13` (`STEAM_ALPHABET`, *different* alphabet — by design)
+
+**Observation:** The first two are inverses of each other but live in different modules with no shared helper. The third is intentionally different (Steam Guard's de-ambiguated alphabet). They all hand-roll the bit-packing loop.
+**Why it matters:** A reader who finds one of the three has to grep to discover whether there are others, and whether they agree. A future change to the RFC 4648 path (e.g., padding behavior) needs to be applied in two places.
+**Suggested direction:** Extract a small `pub(crate) mod base32` with `encode_rfc4648`, `decode_rfc4648`, leaving Steam's bespoke alphabet where it is (with a `// not RFC 4648 — Steam Guard's de-ambiguated alphabet` neighbour comment).
+
+### P2 — Backup format embeds the reference JPEG as base64-in-JSON
+
+**File(s):** `crates/relicario-core/src/backup.rs:148-152, 274-280, 343-345`
+**Observation:** The `Envelope.vault.reference_jpg: Option<String>` carries the JPEG as base64-encoded JSON string. After zstd (which can't compress JPEG), a 4 MB reference photo bloats by ~33% from base64 plus JSON overhead.
+**Why it matters:** Backup files for users who bundle the reference image will be substantially larger than necessary. Round-trip works (covered by `tests/backup.rs:96-106`), so this is a footprint concern, not a correctness one. Worth flagging if backup size ever shows up in a complaint.
+**Suggested direction:** Bump `FORMAT_VERSION` and put `reference_jpg` and `git_archive` in a binary tail outside the JSON envelope, base64 only the small bytes. Defer until there's actual user pressure on backup size.
+
+### P3 — Inconsistent error types and constant styles
+
+**Observations (all small, batched here):**
+- `crates/relicario-core/src/time.rs:18` — `MonthYear::new` returns `Result<Self, &'static str>` instead of `RelicarioError`. Every other constructor in the crate uses the unified error type.
+- `crates/relicario-core/src/backup.rs:30` declares `pub const MAGIC: [u8; 4] = *b"RBAK";`; `crates/relicario-core/src/recovery_qr.rs:7` declares `const MAGIC: &[u8; 4] = b"RREC";`. Two different idioms for the same concept in adjacent files.
+- `crates/relicario-core/Cargo.toml:36` has an empty `[dev-dependencies]` table (delete the header).
+- `crates/relicario-core/src/crypto.rs:248-261` `derive_master_key_raw` is `pub` but only consumed by `recovery_qr.rs` inside this crate (verified via grep). `pub(crate)` would prevent accidental external misuse.
+
+**Why it matters:** Each is trivial in isolation, but for a Rust newcomer reading the crate front-to-back, every inconsistency is a moment of "wait, why is this one different?" — and the answer is almost always "no reason, just historical."
+**Suggested direction:** Pick one form for each pattern, sweep.
+
+### P3 — Mid-file `use` blocks in `item.rs` and `attachment.rs`
+
+**File(s):** `crates/relicario-core/src/item.rs:117-122`, `crates/relicario-core/src/attachment.rs:43-46`
+**Observation:** Both files have `use` statements partway down the file (in `item.rs`, after `Section`; in `attachment.rs`, after `AttachmentSummary`). Idiomatic Rust hoists all `use` to the top.
+**Why it matters:** Newcomer expectation; trivial to fix.
+
+### P3 — `derive_icon_hint` only handles `Login` with no comment about other types
+
+**File(s):** `crates/relicario-core/src/manifest.rs:84, 92-99`
+**Observation:** Only `ItemCore::Login` produces a hostname hint; `_ => None` for the other six. No comment explaining why card-brand / favicon-from-URL / etc aren't derived for other types.
+**Suggested direction:** One-line `// only Login items have a URL today; other types don't have an obvious icon source.` (Or implement card-brand / identity-favicon if the popup UI wants them.)
+
+### P3 — `attachment.rs` has WHAT-comments on a deref pattern
+
+**File(s):** `crates/relicario-core/src/attachment.rs:60-63, 83-85`
+**Observation:** Two "Call-site adaptation" sections explain `&**master_key` in prose. The pattern is idiomatic Rust deref-coercion; the comment explains *what* not *why*.
+**Suggested direction:** Delete both comment blocks. The code is self-documenting; if anything, the cognitive load is in the comment, not the deref.
+
+### P3 — TOTP dynamic-truncation extraction is reproduced four times
+
+**File(s):** `crates/relicario-core/src/item_types/totp.rs:75-99` (3 algorithm arms each duplicate the DT slice math), `217-228` (test reference impl reproduces it again).
+**Suggested direction:** Extract a `fn dt(hmac_out: &[u8]) -> u32` helper. The test would still need its own copy as the cross-check.
+
+### P3 — `STEAM_ALPHABET` source comment contradicts its own test
+
+**File(s):** `crates/relicario-core/src/item_types/totp.rs:13` and `:287-291`
+**Observation:** Source comment says "excludes ambiguous glyphs (0/O, 1/I/L, S/5, A/Z)". Test docstring at line 287 says "Note: '5' IS in the alphabet — S is excluded, so 5 is unambiguous." The test is right; the source comment is wrong about '5'.
+**Suggested direction:** Fix the source comment to match the test (and the actual alphabet).
+
+### P3 — `device.rs::sign` and `verify` share an extraction pattern that begs for a helper
+
+**File(s):** `crates/relicario-core/src/device.rs:64-72, 86-94`
+**Observation:** Both functions do `key_data.ed25519().ok_or(...)?.try_into::<[u8; 32]>().map_err(...)?`. Five-line copy.
+**Suggested direction:** A `fn ed25519_bytes_from_private(...) -> Result<[u8; 32]>` and a `fn ed25519_bytes_from_public(...)` would each fold the extraction. Minor; not worth a refactor on its own but a free win if the file is being touched.
+
+### P3 — `imgsecret.rs::read_block`'s `.unwrap()` deserves a one-liner
+
+**File(s):** `crates/relicario-core/src/imgsecret.rs:315-319`
+**Observation:** `read_block_abs(...).unwrap()` is safe because `compute_region` guarantees the block lies inside the embed region, but the invariant isn't stated.
+**Suggested direction:** `// safe: compute_region ensures (start_x, start_y) + 8 fits within the image`. Same idea as the existing `expect("ascii-only charset")` in `generators.rs:64`.
+
+### P3 — `r#type` field on `Item` and `ManifestEntry`
+
+**File(s):** `crates/relicario-core/src/item.rs:134`, `crates/relicario-core/src/manifest.rs:23`
+**Observation:** Using `r#type` (raw identifier) because `type` is a reserved keyword. Functional but jarring; a Rust newcomer doesn't know what `r#` means and won't immediately realize it's a field name not a type prefix.
+**Suggested direction:** Rename to `item_type` with `#[serde(rename = "type")]` to keep wire format. Minor ergonomic win.
+
+### P3 — BIP39 minimum word count of 3 is misleading
+
+**File(s):** `crates/relicario-core/src/generators.rs:79-86`
+**Observation:** `word_count` accepted range is `3..=12`. BIP39 spec proper starts at 12 words. 3-word output has only ~33 bits of entropy and would never pass `validate_passphrase_strength` for security uses, but the API permits it. The comment "This gives full-entropy sourcing even for short passphrases" elides that effective entropy is `word_count * log2(2048) = 11 * word_count`, not 128 bits.
+**Suggested direction:** Either restrict to BIP39's actual word counts (12, 15, 18, 21, 24) or document that this is a *passphrase generator inspired by BIP39* (using its wordlist) rather than a BIP39 mnemonic generator. The latter is honest about what the code actually does.
+
+### P3 — `StrengthEstimate::guesses_log10` uses base-10 while the spec talks bits
+
+**File(s):** `crates/relicario-core/src/generators.rs:111-113`
+**Observation:** `guesses_log10: f64` is base-10 log of guess count; the design spec discusses entropy in bits. Mild domain-translation friction for callers.
+**Suggested direction:** Add a one-line comment showing the bits conversion (`bits ≈ guesses_log10 * log2(10) ≈ guesses_log10 * 3.32`), or expose a `bits_estimate()` accessor.
+
+## File-by-file walk
+
+**`lib.rs` (99 lines).** Crate-level docs are tight and accurate; the crypto pipeline diagram in the header is the right thing to greet a newcomer with. Public re-exports surface every meaningful type from one location. Clear.
+
+**`error.rs` (195 lines).** Single error enum with thiserror. Every variant carries helpful context (item id, byte counts, found/expected version) except `Decrypt` which is opaque on purpose (audit M4). Tests exercise the public message format. Reads well.
+
+**`crypto.rs` (437 lines).** The cornerstone. Module-level doc explains why XChaCha over AES-GCM and the binary layout. `derive_master_key` does NFC normalization + length-prefixed concatenation, both with explicit "audit H1" provenance comments. `decrypt_v1` rejection is tested. `derive_master_key_raw` is the seam used by the recovery QR. Solid.
+
+**`ids.rs` (161 lines).** `ItemId`/`FieldId` are 64-bit random hex; `AttachmentId` is content-addressed (SHA-256 truncated to 128 bits). `is_valid()` provides a path-traversal guard (tested for `../../etc`). Header comment cites the audit IDs (M8, I2/B4) that motivated the entropy bumps from v1 — that traceability is great.
+
+**`time.rs` (63 lines).** `now_unix()` and `MonthYear`. Only blemish is `MonthYear::new -> Result<_, &'static str>`; everything else returns `RelicarioError`.
+
+**`vault.rs` (90 lines).** Six typed encrypt/decrypt wrappers (item / manifest / settings) that JSON-roundtrip through the crypto layer. Mechanical and correct. Stale module header (P2).
+
+**`item.rs` (497 lines).** Defines the Item envelope, Field/FieldKind/FieldValue, Section, FieldHistoryEntry. Kind/value invariant enforced at construction and `validate()` post-deserialization. `set_field_value` captures history for password/concealed/totp kinds with kind-change rejection. `prune_history` honors LastN/Days/Forever. Mid-file `use` block (P3). Inline `base32_encode` (P2 above). Otherwise solid; the test at `set_field_value_captures_history_for_password` is exactly the right shape.
+
+**`manifest.rs` (159 lines).** Browse-without-decrypt index v2. `upsert`/`remove`/`get`/`search`. `derive_icon_hint` only handles Login (P3). `r#type` field (P3). Stale header (P2).
+
+**`attachment.rs` (166 lines).** `AttachmentRef` (carried on Item) and `AttachmentSummary` (carried in Manifest) plus `encrypt_attachment`/`decrypt_attachment`. The cap check fires before any crypto work — good order. Stale header + WHAT-comments (P2 + P3).
+
+**`settings.rs` (184 lines).** `VaultSettings` with `TrashRetention`, `HistoryRetention`, `GeneratorRequest`, `AttachmentCaps`, plus the autofill TOFU ack map. Defaults match the design spec. `should_purge` is tested at the day-boundary. Clear.
+
+**`generators.rs` (269 lines).** CSPRNG passwords (rejection-sampled via `Uniform::from`) and BIP39 passphrases (with capitalization variants) plus a zxcvbn-backed strength gate. Solid except the BIP39 lower-bound and `guesses_log10` ergonomics (both P3).
+
+**`imgsecret.rs` (1138 lines).** The novel component. Documentation is excellent — DCT, QIM, EMBED_POSITIONS, MAX_DIMENSION rejection, JPEG header peek (audit M3), even an inline ITU-R BT.601 derivation. Tests cover round-trip, recompression to Q85, 10% crop, oversized-header rejection, and synthetic JPEG generation. Three real concerns: dead `region_width`/`region_height` (P2), narrower-than-spec crop recovery (P2), unannotated `unwrap()` in `read_block` (P3). The 1100-line size is fine — the algorithm warrants it.
+
+**`backup.rs` (348 lines).** `.relbak` container: magic + version + salt + nonce + zstd(JSON envelope). Pinned Argon2id params. Schema/format versioning is paranoid in the right places. Reference-JPEG embedding is base64-in-JSON (P2). Otherwise solid.
+
+**`device.rs` (168 lines).** ed25519 keypair generation in OpenSSH format, sign/verify, and SHA-256 fingerprint. The ssh-key + ed25519-dalek choreography is awkward but unavoidable. Sign/verify share an extraction pattern (P3). Tests cover sign, verify, wrong-data, wrong-key, and fingerprint format/determinism — comprehensive.
+
+**`recovery_qr.rs` (129 lines).** The doc-gap finding (P1). Mechanically correct: domain-separated KDF input, AEAD wrap of the 32-byte image_secret, 109-byte payload that fits a QR v40 at EcLevel::M, SVG render via `qrcode`. But the documentation density doesn't match the rest of the crate.
+
+**`import_lastpass.rs` (220 lines).** Header validation is strict (column count + order). Per-row failures degrade gracefully into `ImportWarning` rather than aborting. SecureNote vs Login dispatch via the `http://sn` sentinel matches the spec (D10). Custom base32 decoder (P2). Otherwise clean.
+
+**`tar_safe.rs` (138 lines).** Replaces `tar::Archive::unpack` with a validated extractor. Rejects `..`, absolute paths, Windows prefixes, symlinks, hardlinks, oversized claimed sizes, and cumulative-size bombs. Returns `(PathBuf, Vec<u8>)` to the caller. Surgical and well-scoped.
+
+**`item_types/mod.rs` (127 lines).** `ItemType` and `ItemCore` enums plus a `pub use` of every per-type core. The `// INVARIANT: no *Core struct may have a field serialized as "type"` comment at line 38 is exactly the kind of cross-cutting note that earns its keep — preserving that convention is what `ItemCore`'s tag-based serde works against. Comprehensive round-trip test at `item_core_round_trips_for_all_seven_types`.
+
+**`item_types/login.rs` (63 lines).** Username/password/url/totp, all Optional, password Zeroizing. `omitted_fields_dont_appear_in_json` is the right shape for a serde test.
+
+**`item_types/secure_note.rs` (30 lines).** Just a Zeroizing body. Right-sized.
+
+**`item_types/identity.rs` (45 lines).** Five Optional fields. `empty_identity_omits_all_fields` round-trips to `{}` — clean.
+
+**`item_types/card.rs` (68 lines).** Number/holder/expiry/cvv/pin/kind. `CardKind` defaults to `Credit`. `MonthYear` reused from `time.rs`.
+
+**`item_types/key.rs` (42 lines).** Key material as Zeroizing string + label/public_key/algorithm. Loose schema (algorithm is a free string), which is appropriate for "any kind of key material."
+
+**`item_types/document.rs` (40 lines).** Filename + mime + AttachmentId pointer to the primary blob. The actual bytes live in the attachment store, not the item.
+
+**`item_types/totp.rs` (293 lines).** TotpCore + the shared TotpConfig (also reused as a field on Login). RFC6238 SHA1 vector check, an independent reference impl for Steam, an alphabet exhaustiveness sweep. HOTP is rejected with a typed error rather than silently mis-counted — the right choice for a stateless library. DT extraction duplicated four times (P3). Source vs test comment disagreement on the '5' character (P3).
+
+**Tests folder (9 files, ~1.1 kLOC).** `integration.rs` covers the full encrypt/decrypt pipeline plus two-factor independence. `format_v2.rs` pins the version byte, the v1-rejection error type, and the length-prefix domain separation. `field_history.rs` covers capture, prune, and survival across encrypt/decrypt. `attachments.rs` covers round-trip + AID determinism + cap. `backup.rs` is thorough — round-trip with and without reference image / git archive, bad magic, unsupported version, wrong passphrase, truncation, tag tamper, NFC/NFD passphrase round-trip. `generators.rs` does class-balance statistics across 10k chars (well-documented why aggregating, since per-call cap is 128). `import_lastpass.rs` is the single largest suite (~30 cases) and exercises every column-mapping edge. `recovery_qr.rs` is minimal but covers the essentials. `safe_unpack.rs` builds raw-byte tars by hand to bypass `tar::Builder`'s sanitizer — exactly the right way to test a security boundary. The `fast_params()` helper is repeated across most files; a `tests/common/mod.rs` could DRY it but it's not a real cost.
+
+## Beginner-friendliness assessment
+
+For a competent dev who has never written Rust, this crate is unusually approachable. The boundary discipline is consistent (no I/O anywhere), the public surface is enumerated in one place (`lib.rs`), the module names map directly to vault concepts a reader already understands (item, manifest, attachment, settings, generators, vault, backup, device, recovery_qr), and the most algorithmically dense file (`imgsecret.rs`) is the most heavily commented. A reader can land in `crypto.rs`, follow `derive_master_key` → `encrypt` → `vault::encrypt_item`, and reach `tests/integration.rs::full_workflow_login_and_note` to see the whole pipeline run, all in one sitting. The Rust idioms that would trip up a newcomer (deref-coercion, `r#type` raw identifiers, `Zeroizing` wrappers, `&**master_key`) are all present, but they cluster in patterns a reader will see often enough to absorb.
+
+The single change that would help most: write `recovery_qr.rs` to the same documentation standard as `crypto.rs` and `backup.rs`. It's the only file where a learning reader will hit a wall. Closing that gap brings the floor up to the ceiling and makes the "read it like a security proof" pitch true everywhere, not just in 16 of 17 files.

docs/superpowers/reviews/2026-05-04-dev-b-notes.md

@@ -0,0 +1,240 @@
+# DEV-B Architecture Review Notes — Rust Consumers (CLI, Server, WASM)
+
+**Date:** 2026-05-04
+**Scope:** `crates/relicario-cli/`, `crates/relicario-server/`, `crates/relicario-wasm/`
+**Out of scope:** `relicario-core` internals (DEV-A), `extension/` and `tools/relay/` (DEV-C)
+**Method:** read-only walk of every src + test file; `cargo check` and `cargo clippy` per crate; `cargo build --target wasm32-unknown-unknown` for the WASM crate.
+
+## Summary
+
+The consumer layer is in good shape conceptually but uneven in execution. **`relicario-server` is the highlight**: 189 lines, one obvious responsibility, every dependency on `relicario-core` is plaintext device metadata only — the "server only ever sees ciphertext" invariant is structurally enforced by the import surface, not just by convention. **`relicario-wasm` is small and clean but has one real Rust-side defect**: `SessionHandle` lacks an `impl Drop`, so when wasm-bindgen's auto-generated `.free()` runs, the master key stays in WASM linear memory until `lock()` is also called explicitly — defense-in-depth that is currently missing. **`relicario-cli` does its job correctly but is hard to read**: `src/main.rs` is a 2641-line file with no submodule boundaries between the clap surface, item builders, edit handlers, prompt helpers, and parsers — the single biggest readability blocker in the consumer layer. Across all three crates, naming and module structure are good; what hurts is duplicated boilerplate and the absence of a few obvious helpers.
+
+---
+
+## Findings
+
+### relicario-cli
+
+#### P1 — `main.rs` is a 2641-line monolith with no submodule boundaries
+**File(s):** `crates/relicario-cli/src/main.rs:1-2641`
+**Observation:** every subcommand handler, every per-type item builder, every per-type edit handler, prompt helpers, parsing helpers, the `ParamsFile` shape, the clap surface, and 24+ git shell-outs all live in one file. The clap surface (lines 1-455) reads as a tour of the product and is excellent; lines 456-2641 are a flat sequence of `cmd_*`, `build_*_item`, `edit_*`, prompt helpers, and parse helpers, all peers. A newcomer searching "where does add work?" finds `cmd_add` calling 7 different `build_*_item` functions (each ~50-60 lines) with no module boundaries.
+**Why it matters:** this is the first file a newcomer opens. Today they have to scroll, not navigate.
+**Suggested direction:** keep `main.rs` as clap definitions + `match` dispatcher only (~470 lines). Split into `commands/{add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr}.rs`, plus `prompt.rs` (the six `prompt_*` helpers + `prompt_secret`) and `parse.rs` (`parse_month_year`, `base32_decode_lenient`, `guess_mime`). Same LOC, completely different reading experience.
+
+#### P1 — Git invocation boilerplate duplicated ~16× with one-line errors
+**File(s):** `crates/relicario-cli/src/main.rs:601, 602, 610, 986, 988, 1477, 1480, 1767, 1897, 1900, 2432, 2438, 2533, 2540` (and others)
+**Observation:** every `git_command` invocation that bails uses the same shape: `git_command(repo).args([...]).status()? + if !status.success() { bail!("git foo failed") }`. Child stderr is inherited to the parent tty (which helps interactively) but in test runs and noninteractive tooling it is lost, and the bail message is just the verb (`"git commit failed"`). When this fires in the wild — pre-receive reject, missing remote, dirty tree, signing-key prompt — the user sees one line of "$verb failed" and nothing else.
+**Why it matters:** this is the entire error UX for the git side of the CLI. Failure modes are common; the diagnostic is actively unhelpful.
+**Suggested direction:** add `helpers::git_run(repo, args, context)` that uses `.output()` (capturing stderr), prints captured stderr unmodified on failure, and includes the human-readable `context` ("commit add: GitHub", "register device", "purge trashed item"). Replaces 16 copies with one-liners.
+
+#### P2 — `build_*_item` functions mix prompting, parsing, and core construction
+**File(s):** `crates/relicario-cli/src/main.rs:664-921`
+Each `build_*` does its own prompt-or-flag fallback (`title.map(Ok).unwrap_or_else(|| prompt("Title"))?`), parses domain values (URL, MonthYear, base32 TOTP), then constructs an `ItemCore`. Adding a new item type is currently 50-80 lines of mechanical code. A `prompt_or_flag<T>` helper plus per-type builders that take already-validated values would compress this materially.
+
+#### P2 — Pure parsers belong in core, not the CLI
+**File(s):** `crates/relicario-cli/src/main.rs:942-980`
+`base32_decode_lenient` and `parse_month_year` are pure parsing producing typed core values. Per the user's CLI/extension parity philosophy, these need to be reachable from WASM too — the extension will want them when it gets QR-import / month-year smart input. `MonthYear::parse` and an `ItemCore::parse_totp_seed` (or `Totp::parse_secret`) on the core side would avoid future duplication.
+
+#### P2 — `refresh_groups_cache` invocation discipline is manual at 7 sites
+**File(s):** `crates/relicario-cli/src/main.rs:641, 998, 1123, 1197, 1414, 1432, 1474` (and `helpers.rs:90-93` for the doc comment)
+The plaintext `groups.cache` is updated by-hand after every manifest mutation. The "failures are silently swallowed" rationale is documented at `main.rs:462`, but the rule "every mutating handler must call this" is not enforced — easy to forget on a new command. Either invoke from `Vault::save_manifest` (couples session to cache layout — maybe wrong) or wrap in `Vault::after_manifest_change(&self, manifest: &Manifest)`.
+
+#### P2 — `ParamsFile` is defined twice with mismatching shapes
+**File(s):** `crates/relicario-cli/src/main.rs:2287` (write) vs `crates/relicario-cli/src/session.rs:114` (read)
+The write side has `aead`, `salt_path`, `format_version`; the read side takes only `kdf`. Two definitions of the on-disk `params.json` shape, in different files, with overlapping but non-equal fields. A single `Params` struct in `relicario-core` (or in `session.rs`) used by both readers and writers would eliminate the drift risk.
+
+#### P2 — `cmd_purge` and `cmd_trash_empty` duplicate the manifest-add-and-commit dance
+**File(s):** `crates/relicario-cli/src/main.rs:1476-1480, 1896-1900`
+Same three lines, same error strings, same git rm + git add + git commit per item. `cmd_trash_empty` invokes `purge_item` per item, each of which is its own three-git-invocation loop. Batching the staging would reduce a 50-item purge from 150 git invocations to 3.
+
+#### P3 — Selection of the `let _ = entry;` pattern, repeated 6×
+**File(s):** `crates/relicario-cli/src/main.rs:1170, 1407, 1426, 1469, 1913, 2030`
+Drop-the-borrow-before-reborrow-mutably is a Rust newcomer's worst surprise. A NLL-friendly refactor (clone `id` and `title` eagerly, let the borrow end naturally) would make these lines disappear.
+
+#### P3 — Other nits
+- `cmd_recovery_qr_unwrap` does not check for empty input before base64 decode (`main.rs:2625-2630`)
+- `cmd_recovery_qr_generate` mixes the QR ASCII and a "NOT been saved to disk" message both on stdout — pipe-unfriendly (`main.rs:2612-2614`)
+- `Lock` subcommand is a no-op but visible in `--help`; either `#[command(hide = true)]` or accept the parity-with-extension argument and document why (`main.rs:445`, doc-comment at `:166`)
+- `tests/attachments.rs:69-76` has a dead variable (`blob_path`) kept "to avoid an unused warning" — delete
+- Three test-only env vars (`RELICARIO_TEST_PASSPHRASE`, `RELICARIO_TEST_ITEM_SECRET`, `RELICARIO_TEST_BACKUP_PASSPHRASE`) each duplicated under `#[cfg(debug_assertions)]/#[cfg(not(debug_assertions))]` — one macro would flatten ~30 lines
+- `cmd_backup_export` still reads `devices.json` (with `[]` fallback) per a "Task 12 will remove" TODO at `:1535-1537`. If Task 12 has shipped, this code can simplify
+- `format!("{:?}", e.r#type)` for the TYPE column at `main.rs:1158` — Debug-format for user-facing output. Add `Display` to `ItemType` in core
+- `helpers.rs:37 #[allow(dead_code)] pub fn relicario_dir()` — helper has no callers but several `vault_dir.join(".relicario")` sites in main.rs should be using it
+- `device.rs:94, 103, 120` and `gitea.rs:24, 26, 47, 77, 94, 101` have `#[allow(dead_code)]` markers without explanation. Either wire up or add `// TODO(<plan>):` so a newcomer knows whether they're scaffolding or scar tissue
+- `gitea.rs` constructs a fresh `reqwest::blocking::Client::new()` per method call (3 sites) — make it a struct field
+- `tests/edit_and_history.rs` writes hardcoded prompt sequences (`["", "", "", "", "", "y"]`) blindly; if main.rs reorders prompts, tests hang silently. A scripted-test layer (`expect_prompt("Title"); respond("");`) would survive refactors
+
+---
+
+### relicario-server
+
+#### Trust-model assessment (the headline question)
+**The server respects the "ciphertext only" invariant. Confirmed.** The crate's entire `relicario-core` import surface is `DeviceEntry`, `RevokedEntry`, `fingerprint` (and `generate_keypair` in tests) — every one of those is plaintext-only device metadata. There is no import of `vault`, `crypto`, `imgsecret`, `item`, `manifest`, or `settings`. A grep over `crates/relicario-server/` for `decrypt|wrapped|encrypted|vault::` returns nothing. The Cargo.toml dep surface (`anyhow`, `clap`, `serde_json`, `tempfile`, `regex`) confirms it: there is no AEAD or KDF crate present. The server cannot decrypt the vault even in principle — it never reads the passphrase, the reference image, the salt, or the params.
+
+The two on-disk files the server reads from the commit tree are `.relicario/devices.json` and `.relicario/revoked.json` (`main.rs:38, 48`), both plaintext metadata. All other operations are `git` subprocesses (`git show`, `git verify-commit --raw`, `git show -s --format=%ct`) plus local fingerprint computation. `generate-hook` emits a pure shell script that re-invokes `relicario-server verify-commit` per commit; it embeds no secret material. **No P1 findings.**
+
+#### P2 — `generate-hook` assumes `$PATH`
+**File(s):** `crates/relicario-server/src/main.rs:170`
+The emitted script calls `relicario-server verify-commit "$commit"` with no path. Most Gitea deployments do not put `/usr/local/bin` on the hook process's `$PATH`, so this will fail with "command not found" or silently no-op. Either embed `std::env::current_exe()` at hook-generation time, or document an explicit `PATH=` line in the emitted script. There is no test that the generated hook actually executes.
+
+#### P2 — Bootstrap branch is permissive
+**File(s):** `crates/relicario-server/src/main.rs:38-44, 54-57`
+A missing `.relicario/devices.json` at `newrev` is treated as bootstrap and accepted. Combined with "devices empty AND revoked empty → OK", an attacker who pushes a brand-new branch with no `.relicario/` directory could push arbitrary unsigned commits. There's no test for "second push to an established repo where devices.json was stripped." Worth either documenting the rule (first push wins; once devices.json exists in history, it can never be removed) or enforcing it: `oldrev != 0` should imply `devices.json` exists in `newrev`.
+
+#### P2 — stdin-parsing lives in the shell hook only; binary alone is not hook-shaped
+**File(s):** `crates/relicario-server/src/main.rs:130-189` (`generate_hook`)
+The Rust binary's `verify-commit` takes a single SHA argument; the per-line `<old> <new> <ref>` parsing is delegated to bash in `generate_hook`. Defensible split, but means anyone wiring up a hook by hand cannot use the binary alone. A `verify-commit --from-stdin` mode (or at least a doc comment on `VerifyCommit` calling this out) would help.
+
+#### P2 — Test coverage gaps vs. trust-model
+**File(s):** `crates/relicario-server/tests/verify_commit.rs`
+Tests cover: accepted, unregistered → reject, revoked-after → reject, revoked-before → accept. Missing: unsigned commit (no signature at all), malformed `devices.json` (parse error path on `:46`), bootstrap-empty-devices acceptance (`:54`), and one of the two stripped-`.relicario/` cases. Each is one extra `#[test]`.
+
+#### P3 — Server nits
+- Regex compiled per call at `main.rs:85` — use `LazyLock` or `once_cell::sync::Lazy`; the `expect("static regex")` comment hints the author knew
+- The malformed-devices.json path at `:46` returns an `anyhow` chain on stderr without the consistent `REJECT: ...` prefix the rest of the file uses — ops parsing logs for `REJECT:` will miss it
+- No `--version` flag exposed in clap (small ops courtesy)
+- `generate-hook` doesn't tell users to `chmod +x` the result (one-line comment header in the emitted script would help)
+
+---
+
+### relicario-wasm
+
+#### P1 — `SessionHandle` has no `impl Drop`; master key leaks on JS GC / `.free()`
+**File(s):** `crates/relicario-wasm/src/lib.rs:15-23` and `crates/relicario-wasm/src/session.rs:1-58`
+**Observation:** `SessionHandle` is `pub struct SessionHandle(u32)` with no `Drop` impl. wasm-bindgen auto-generates a JS-side `.free()` that, on the Rust side, drops the `SessionHandle` wrapper — i.e. drops a `u32`, a no-op. The `SESSIONS` HashMap entry stays alive **with the master key + image_secret still in WASM linear memory** until JS calls the explicit `lock(handle)` function (which calls `session::remove`). I confirmed via `grep -n "impl Drop" crates/relicario-wasm/src/*.rs` — empty.
+**Why it matters:** every `.free()` callsite that does not also call `lock()` first is a key-residency window of unbounded duration. wasm-bindgen does **not** auto-call `free()` on JS GC, but JS code that does call `.free()` reasonably expects the Rust side to clean up. The current contract requires JS to call `lock()` *and then* `free()`, which is asymmetric and easy to get wrong on the JS side (see boundary notes for DEV-C).
+**Suggested direction:** add
+```rust
+impl Drop for SessionHandle {
+    fn drop(&mut self) { session::remove(self.0); }
+}
+```
+to `lib.rs`. `lock()` becomes the explicit "I am done now" call; `.free()` (auto or manual on the JS side) is the safety net. Defense in depth — the cost is one impl block. Worth a `wasm-bindgen-test` covering construct → drop → confirm registry empty.
+
+#### P2 — Redundant `need_key` + `with(...).unwrap()` double-lookup
+**File(s):** `crates/relicario-wasm/src/lib.rs:73, 84, 92, 103, 111, 122, 160, 172`
+Every per-call op does `need_key(handle)?` and then `session::with(handle.0, |k| ...).unwrap()`. Two HashMap lookups per call, with the second `.unwrap()` justified only because the first proved the key existed. Single-threaded WASM makes this safe today, but if anyone ever introduces a reentrant path (`Serializer` callback that calls back into WASM), the assumption breaks. Refactor to a single `session::with(...).ok_or_else(|| JsError::new("invalid or locked session handle"))?` helper.
+
+#### P2 — `Vec<u8>` getters clone on every read
+**File(s):** `crates/relicario-wasm/src/lib.rs:141-150` (`EncryptedAttachment::aid` and `bytes`)
+Each call clones the whole field. JS can call `enc.bytes` repeatedly without realising. For attachment payloads (potentially MB-sized), that's a real cost. Either consume by value or document "call once, cache locally."
+
+#### P2 — Naming: `wasm_*_recovery_qr` prefix is inconsistent with everything else
+**File(s):** `crates/relicario-wasm/src/lib.rs:497, 510`
+`wasm_generate_recovery_qr` and `wasm_unwrap_recovery_qr` are the only exports with the `wasm_` prefix. Rename to `generate_recovery_qr_svg` and `unwrap_recovery_qr` (and update `extension/src/wasm.d.ts` accordingly). Trivial breaking rename, do it before any new caller appears.
+
+#### P2 — `device.rs` and `session.rs` use different concurrency primitives
+**File(s):** `crates/relicario-wasm/src/device.rs` (`Lazy<Mutex<...>>`) vs `crates/relicario-wasm/src/session.rs:14-17` (`thread_local! { RefCell<HashMap<...>> }`)
+Both work in single-threaded WASM. The inconsistency hurts readability — pick one pattern. `thread_local! + RefCell` is fine and avoids `Mutex` overhead; `Mutex` over `Lazy` is closer to typical Rust idioms. Either is defensible; consistency is the win.
+
+#### P3 — WASM nits
+- All `#[wasm_bindgen]` exports use snake_case (`manifest_encrypt`, `parse_lastpass_csv_json`); JS idiom is camelCase. The `wasm.d.ts` mirrors snake_case verbatim, so it's consistent — but if DEV-C ever wants idiomatic JS naming, `#[wasm_bindgen(js_name = "manifestEncrypt")]` is the path. Decide once, cite the decision in the module doc
+- `lib.rs:50` comment "Subsequent wasm_bindgen fns added in Tasks 19-21" is stale historical scaffolding; remove
+- `device.rs:18 #[allow(dead_code)] deploy_private` — wire it or remove it
+- `session.rs:24 if *n == 0 { *n = 1; }` runs on every insert; logically only matters after wraparound — move into the `wrapping_add` returned-zero branch
+- `session_tests` mod inside `lib.rs:522-591` covers session + lastpass; rename or split
+- `SessionHandle` doc-comment says "opaque to JS" but `value()` getter (`:21-22`) makes the u32 visible — align the comment with the API
+- `pack_backup_json` does six `b64.decode().map_err(...)` blocks (`lib.rs:387-410`) — a small `b64_decode(s) -> Result<Vec<u8>, JsError>` helper would compress ~20 lines
+- `get_field_history` walks sections and constructs `serde_json::json!` manually rather than serializing a typed struct (`lib.rs:262-295`); the `_ => String::new()` fallback at `:277` silently swallows future `FieldValue` variants. Use exhaustive match
+
+---
+
+### Cross-cutting (all three crates)
+
+1. **Pure parsers / formatters belong in core.** `parse_month_year`, `base32_decode_lenient`, `guess_mime` (CLI), and `get_field_history`'s walk (WASM) are all examples of logic that today lives in a consumer crate but logically belongs in `relicario-core` so all consumers share it. The CLI/extension parity philosophy makes this concrete: anything the CLI does in pure logic, the extension will eventually need too.
+
+2. **Error formatting is inconsistent.** CLI uses `anyhow::bail!` with a mix of sentence-case ("Settings updated.") and lowercase fragments ("git commit failed"). Server is uniformly `eprintln!("REJECT: ...")` *except* for the malformed-devices.json path that surfaces an anyhow chain. WASM uses `JsError::new(&e.to_string())` mostly, but the messages range from "salt must be exactly 32 bytes" to whatever `RelicarioError::Display` produces. A short style note ("user-facing errors lead with sentence-case context, internal errors use lowercase") plus an audit pass would unify these.
+
+3. **`#[allow(dead_code)]` without explanation appears in cli/device.rs, cli/gitea.rs, and wasm/device.rs.** Each one is either "API completeness for a feature that hasn't shipped" or "scar tissue from a refactor." A newcomer cannot tell which. Either delete or annotate with `// TODO(<plan>):`.
+
+4. **Layering is correct.** None of the three consumer crates reaches past `relicario-core`'s public API. The CLI doesn't import from server or wasm; server doesn't import from CLI or wasm; wasm doesn't import from CLI or server. The only shared concept (device entries, fingerprints) is correctly a core export. ¡Chido! [cool!]
+
+5. **Workspace `Cargo.toml` working-tree changes are cosmetic** (version bumps `0.2.0 → 0.5.0` on cli/core/wasm). No structural concern. Worth committing or reverting before the next merge to keep `git status` quiet.
+
+---
+
+## File-by-file walk
+
+### relicario-cli
+
+- **`Cargo.toml`** — 18 runtime + 4 dev deps, all reasonable. `arboard` (clipboard), `rqrr` (QR decode), `qrcode` (QR encode), `image`, `rpassword`, `dirs`, `reqwest` blocking + JSON for Gitea, `data-encoding`, `tar`. Platform concerns ferried correctly away from core.
+- **`src/main.rs`** — entrypoint, dispatcher, **and** every command handler, item builder, edit handler, prompt helper, parse helper. 2641 lines, 71 functions. Clap surface (lines 1-455) is itself a tour of the product and is excellent. Past line 456 the file becomes flat; see P1 #1.
+- **`src/helpers.rs`** — the cleanest file. ~239 lines: `vault_dir`, `git_command` (with `core.hooksPath=/dev/null`, `commit.gpgsign=false`, `core.editor=true` hardening — newcomers should read the comment at `:42-45`), `iso8601`, `humanize_age`, `groups_cache_path`, `sanitize_for_commit`, `decode_totp_qr`. Has its own `#[cfg(test)] mod tests` covering `humanize_age`, `sanitize_for_commit`, `iso8601`. `find_vault_dir_from` walks parents. Plaintext `groups.cache` is a deliberate trade-off and the doc-comment at `:90-93` is admirably explicit.
+- **`src/session.rs`** — short and clear (~151 lines). `UnlockedVault { root, master_key: Zeroizing<[u8; 32]> }` plus `load_*`/`save_*` for Item, Manifest, VaultSettings. `unlock_interactive()` does passphrase prompt → image extract → KDF. `key()` accessor returns `&Zeroizing<...>` used at 4 call sites; consider passing through `encrypt_attachment`/`decrypt_attachment` methods so the key never leaves this module. `read_params` defines an inner `ParamsFile` struct that mismatches the writer in `main.rs:2287` — see P2.
+- **`src/device.rs`** — ~169 lines. ed25519 keypair storage under `~/.config/relicario/devices/<name>/`. `configure_git_signing` runs four `git config` calls. Three `#[allow(dead_code)]` items (`load_signing_key`, `load_deploy_key`, `delete_device_keys`) — API completeness without callers.
+- **`src/gitea.rs`** — ~117 lines. Plain blocking reqwest client. `create_deploy_key` parses the JSON response into `DeployKey { id, title, key }` (latter two `#[allow(dead_code)]`). `delete_deploy_key` treats 404 as success — sensible. Each method allocates a fresh `reqwest::blocking::Client::new()`.
+- **`tests/basic_flows.rs`** — 137 lines. Tests at the right level: spawn binary via `assert_cmd`, assert on stdout/stderr/exit. `init_creates_expected_layout`, `add_login_then_list_shows_it`, `get_masks_by_default_shows_with_flag`, `rm_restore_purge_cycle`, `generate_random_and_bip39`. Solid CLI-surface coverage.
+- **`tests/edit_and_history.rs`** — 191 lines. Most subtle test, interactive `edit` flow. `run_edit_with_pw_change` and `run_edit_totp` write hardcoded prompt sequences (`["", "", "", "", "", "y"]`) to stdin — fragile to prompt reordering. See P3.
+- **`tests/attachments.rs`** — 106 lines. Round-trip attach → extract → detach. Has a dead variable kept "to avoid an unused warning" (P3). `attach_rejects_over_cap` exercises only the per-attachment cap, not per-item or per-vault — coverage gap.
+- **`tests/settings.rs`** — 158 lines. `settings_roundtrip_trash_retention`, conflicting-flags rejection, generator-defaults end-to-end, `status` command coverage including `last_backup` round-trip. Solid.
+- **`tests/backup.rs`** — 142 lines. Export/restore round-trip, `--include-image`, `--no-history`, refusal of non-empty target, wrong-passphrase failure. Excellent coverage.
+- **`tests/import_lastpass.rs`** — 127 lines. Importer integration: success, single-commit guarantee, zero-items rejection, header validation, duplicate-import-IDs-are-unique invariant.
+- **`tests/smart_inputs.rs`** — 210 lines. Completion-script smoke tests, groups-cache write/suppress, `rate` command (strong/weak/`-` stdin), `--totp-qr` via in-process synthesized QR PNG (`make_test_qr`) — adheres to "synthetic fixtures, no binary blobs."
+- **`tests/vault_detection.rs`** — 59 lines. `list_refuses_without_vault_marker`, `get_finds_vault_in_parent_dir`, `v1_vault_is_rejected_with_clear_error` (`.idfoto/` ignored because lookup is for `.relicario/`).
+- **`tests/common/mod.rs`** — 132 lines. `TestVault` harness; `init()` creates a `TempDir`, generates synthetic JPEG via `make_test_jpeg`, runs binary with `RELICARIO_TEST_PASSPHRASE` set. `run`, `run_with_input`, `run_with_backup_pass` variants. No shared global state — parallel-test safe.
+
+### relicario-server
+
+- **`src/main.rs`** — 189 lines, very legible. Two clap subcommands cleanly mapped. `verify_commit` reads devices.json + revoked.json from the commit's tree (`git show`), spawns `git verify-commit --raw` with a dynamically-built allowed-signers file injected via `GIT_CONFIG_*` env vars (a clever touch — chido [cool] — avoids touching user gitconfig), parses the SHA-256 fingerprint from stderr, then enforces revocation-first then registration logic. Uses committer timestamp (not author) for revocation cutoff (`:115-123`) — correct for non-rebased histories. All rejection paths use `eprintln!("REJECT: ...")` with actionable context (commit SHA, fingerprint, reason) and exit 1 — visible to the pushing client via `git push` stderr. `generate_hook` emits a clean bash script handling branch creation (`oldrev = 000...`) and branch deletion (`newrev = 000...`).
+- **`tests/verify_commit.rs`** — 230 lines, four named scenarios mapping to audit S1. Each test stands up a tempdir git repo, generates real ed25519 keypairs via `relicario_core::device::generate_keypair`, signs a commit with explicit committer date, and shells out to the cargo-built binary via `assert_cmd`. Coverage gaps noted in P2.
+- **`Cargo.toml`** — minimal, no surprises. Importantly: no AEAD or KDF crate, which structurally guarantees the server cannot decrypt.
+
+### relicario-wasm
+
+- **`Cargo.toml`** — 27 lines. Right deps. `getrandom = { features = ["js"] }` correctly enabled for browser entropy routing. `image` is dev-only — good. `relicario-core/Cargo.toml` does NOT enable the `js` getrandom feature (correct: core stays platform-agnostic), and the wasm crate "lifts" the feature flag for the dep graph.
+- **`src/lib.rs`** — 591 lines, the bulk of the surface. Module doc-comment is concise. Imports are sprinkled mid-file (`:52, :138, :180, :310, :340, :469, :491`) instead of clustered at the top — historical from incremental authoring per Task 19/20/21 markers. Consolidating saves scroll. Sections are demarcated by `// ── ... ──` dividers which help.
+- **`src/session.rs`** — 57 lines. `SessionData { master_key, image_secret }` stored in `thread_local! { RefCell<HashMap<u32, _>> }`, monotonic `NEXT_HANDLE` u32 (skips 0 on wraparound). `insert`, `with`, `with_image_secret`, `remove`, `clear` (test-only). Missing `impl Drop for SessionHandle` — see P1.
+- **`src/device.rs`** — 71 lines. Clean. `Zeroizing<String>` for private keys (correct — `String::zeroize` wipes the heap allocation). Uses `Lazy<Mutex<DeviceState>>` (different pattern from `session.rs` — see P2).
+
+### Build / clippy
+
+- `cargo check -p relicario-cli` — clean
+- `cargo check -p relicario-server` — clean
+- `cargo check -p relicario-wasm` — clean
+- `cargo build -p relicario-wasm --target wasm32-unknown-unknown` — clean, finishes in ~6s, zero warnings
+- `cargo clippy --workspace` — silent (per subagent reports)
+
+---
+
+## Boundary notes for DEV-C
+
+These are the items that look fine from the Rust side but DEV-C must verify on the TypeScript side:
+
+1. **CRITICAL — every `.free()` callsite on a `SessionHandle`.** wasm-bindgen's auto-generated `.free()` does NOT remove the entry from the Rust-side `SESSIONS` registry today, because there is no `impl Drop for SessionHandle` (P1 above). Until that lands, every `.free()` callsite in TypeScript that does not first call `wasm.lock(handle)` is a master-key residency window in WASM linear memory of unbounded duration. Audit `extension/src` for every `.free()` on a `SessionHandle`. The Rust-side fix is preferred (defense in depth); DEV-C should also confirm that every TS-side lock path calls `wasm.lock(handle)` before `.free()` regardless.
+2. **Verify every `.free()` callsite, full stop.** Same principle applies to `EncryptedAttachment.free()` and `TotpCode.free()`. wasm-bindgen will not call `free` automatically when the JS object is GC'd — JS GC does not trigger Rust drop. Any handle that goes out of scope without explicit `.free()` leaks in WASM linear memory.
+3. **`unlock()` failure semantics.** When unlock throws (bad passphrase, bad params_json, salt wrong length, image_secret extract failure), no `SessionHandle` is created. TS callers should not wrap in `try { ... } finally { handle.free() }` because the handle var will be undefined.
+4. **`manifest_decrypt`/`item_decrypt`/`settings_decrypt` return `JsValue` typed as `unknown` in TS.** Rust uses `serde_wasm_bindgen::Serializer::new().serialize_maps_as_objects(true)` (`lib.rs:65`). Verify TS doesn't assume `Map` semantics anywhere — should be plain JS objects. Binary fields decode to `Uint8Array`; confirm TS doesn't try to `JSON.stringify` a decrypted item containing binary.
+5. **`*_encrypt` functions take `*_json: string`.** TS must `JSON.stringify` before calling. wasm-bindgen TS bindings will catch this at compile time, but verify no `as any` casts bypass.
+6. **`totp_compute(_, now_unix_seconds: bigint)` and `attachment_encrypt(_, _, max_bytes: bigint)`** — TS must use `BigInt(...)`, not `number`. wasm-bindgen throws at runtime on mismatch.
+7. **`Uint8Array` arguments are copied into WASM linear memory.** TS doesn't need defensive copies. But a `Uint8Array` view onto a `SharedArrayBuffer` may behave differently — verify TS isn't passing those.
+8. **`EncryptedAttachment.aid` and `.bytes` clone on every read** (P2). TS code that does `enc.bytes` twice does double work + double copy. Cache locally.
+9. **`SessionHandle.value` getter is exposed.** It's a u32 monotonic counter. If TS ever logs it (telemetry/debug), it's a session correlation identifier that survives across handles.
+10. **`get_field_history` returns JS objects with snake_case keys** (`field_id`, `field_name`, `current_value`, `changed_at`). Verify TS components consume these names — easy mismatch with TS-side camelCase conventions.
+11. **`register_device`/`sign_for_git`/`get_device_info`/`clear_device` are global, not per-session** — backed by `static DEVICE_STATE` (`Lazy<Mutex<>>`). Single SW = single state, fine. If TS ever instantiates multiple WASM modules (e.g. one per offscreen doc), each gets its own state — verify TS uses one shared init path.
+12. **Naming inconsistency**: only `wasm_generate_recovery_qr` and `wasm_unwrap_recovery_qr` carry the `wasm_` prefix. If DEV-C maintains a name-mapping table or auto-generated wrappers, flag for a rename pass.
+13. **`parse_lastpass_csv_json` returns `string` (JSON-encoded), not a `JsValue`.** TS must `JSON.parse` the result — different shape from `manifest_decrypt` which returns already-deserialized `unknown`. Verify `import_lastpass.ts` does `JSON.parse(...)` on the result.
+14. **All exports are snake_case in JS.** If DEV-C ever wants idiomatic camelCase, the mechanism is `#[wasm_bindgen(js_name = "...")]` per export. Decide once, before the surface grows.
+
+---
+
+## Beginner-friendliness assessment
+
+For a competent dev who's never written Rust:
+
+- **Server is ideal.** 189 lines, one trust-model question, every dependency is plaintext metadata. A newcomer can read it end-to-end in under ten minutes and walk away understanding what the server does and does not do. The single change that would help most is a paragraph-length module-level comment near the top of `main.rs` explaining *why* the server only verifies signatures (because the vault is encrypted client-side, the server has no key, the hook's only job is to gate writes by device authenticity). That paragraph would make the trust story self-evident on first contact.
+
+- **WASM is approachable but has one cliff.** 720 lines across 3 files; `lib.rs` reads top-to-bottom okay; the doc-comment on `SessionHandle` is clear about the opaque-handle contract; the section dividers help. The cliff is the missing `Drop` impl: a beginner reasonably assumes wasm-bindgen handles registry cleanup automatically (it does not). A short comment in `session.rs` saying "**Drop the SessionHandle ≠ remove from registry; you must call `lock()`**" would prevent that mistake — but better to fix the missing `Drop` so the comment isn't needed.
+
+- **CLI has one big roadblock and a lot of small ones.** `helpers.rs`, `session.rs`, `device.rs`, `gitea.rs` all read like real code: small modules, focused responsibilities, doc-comment headers, sensible names. `helpers.rs`'s tests double as documentation. The clap surface in `main.rs:1-455` is itself a product tour. Past line 456, `main.rs` becomes a 2200-line flat file with no submodule boundaries. A newcomer searching "where does add work?" finds `cmd_add` calling 7 different `build_*_item` functions (each ~50-60 lines) plus 6 prompt helpers, all peers. Plus the Rust-specific tripwires — the `let _ = entry;` pattern repeated 6×, the `Zeroizing` newtype, the `Option<Foo>::map(Ok).unwrap_or_else(...)?` chain at every builder — compound the unfamiliarity.
+
+**Single biggest change across the consumer layer:** split `crates/relicario-cli/src/main.rs` into a folder. Keep `main.rs` as clap definitions + dispatcher (~470 lines, very readable). Move every `cmd_*` to `commands/<name>.rs`, prompts to `prompt.rs`, parsers to `parse.rs`. Same LOC, completely different reading experience — and this is the precondition for fixing the duplicated git boilerplate (CLI P1 #2) and centralizing `refresh_groups_cache`.
+
+---
+
+## Open questions for DEV-B (escalated to PM separately)
+
+1. Was `impl Drop for SessionHandle` deliberately omitted (e.g. to avoid double-free if JS holds two refs to the same handle)? If yes, document it; if no, this is the headline fix.
+2. CLI `parse_month_year`, `base32_decode_lenient`, `guess_mime` — should they migrate to `relicario-core` for CLI/extension parity?
+3. Is "missing `.relicario/devices.json` = bootstrap = accept" intended in perpetuity, or should it be tightened once a repo has any non-empty devices.json in history?
+4. Is the `Lock` no-op CLI subcommand worth keeping visible in `--help` for parity with the extension, or hide behind `#[command(hide = true)]`?
+5. `cmd_backup_export` still reads `devices.json` per a "Task 12 will remove" TODO. Is Task 12 landed, deferred, or abandoned?

docs/superpowers/reviews/2026-05-04-dev-c-notes.md

@@ -0,0 +1,343 @@
+# DEV-C Architecture Review Notes — TypeScript (Extension + Relay)
+
+**Reviewer:** dev-c (TypeScript scope) **Date:** 2026-05-04 **Branch:** main (read-only review)
+
+## Summary
+
+The TypeScript layer is **soundly organized but unevenly distributed**: a tight discriminated-union message contract (`shared/messages.ts`) and a clean Manifest V3 trust split (popup/setup/content/SW) anchor a codebase that earns its complexity from the two-factor unlock UX. The strongest part is the **service-worker router**: every popup/content message has a typed handler with origin-aware gating, and content scripts never touch WASM. The weakest parts are **two oversized modules that pre-empt the otherwise-clean component model**: `extension/src/setup/setup.ts` (1220 LOC) bypasses the SW and orchestrates WASM directly, and `extension/src/vault/vault.ts` (1027 LOC) inlines shell, sidebar, list, drawer, type-picker, form-wrapper and routing into one file. **CLI/extension parity is excellent overall** — every CLI subcommand has a UI path through the unified left-nav settings (v0.5.1) or vault tab — with two real gaps: explicit per-attachment detach (extension does it via `update_item`) and a vault-status surface equivalent to `relicario status`. One **broken test** in uncommitted relay code (`tools/relay/queue.test.ts:54`) blocks `bun test` from going green.
+
+## Findings (prioritized: P1 / P2 / P3)
+
+### Extension — service-worker
+
+**[P1] router/popup-only.ts:687–703 & router/content-callable.ts:187–205 — duplicated storage helpers (`loadDeviceSettings`, `loadBlacklist`, `saveBlacklist`)**
+WHY: Three identical chrome.storage.local helpers in both router files; both code paths can mutate blacklist via different definitions, so future drift will silently corrupt one path.
+DIRECTION: Extract to `service-worker/storage.ts`; import from both routers.
+
+**[P1] router/popup-only.ts:~169 & router/content-callable.ts:~169 — `itemToManifestEntry()` duplicated**
+WHY: Identical 17-line manifest projection in both router files; refactors of the manifest schema will need to be made twice.
+DIRECTION: Move into `service-worker/vault.ts` and import.
+
+**[P2] service-worker/index.ts:76–78 — inactivity timer reset skips content-callable messages**
+WHY: Only popup/vault sends reset the timer; a user who is actively autofilling but never opens the popup will eventually be force-locked despite continuous use. Conversely, "every_time" mode is fine.
+DIRECTION: Reset on all messages except known read-only content calls (`get_autofill_candidates`); document the exclusion in the timer module.
+
+**[P2] service-worker/index.ts:51–58 — session expiry clears `state.manifest` but leaves `state.gitHost`**
+WHY: After expiry, the cached git-host client survives; the next unlock could mix with stale connection state if a remote was rotated.
+DIRECTION: Null `state.gitHost` alongside `state.manifest` in the expiry callback; the initializer rebuilds it on demand.
+
+**[P2] service-worker/session.ts:26 — `try { current.free() }` swallows free errors**
+WHY: A double-free or invalid-handle on the WASM session would be silently ignored, masking a lifecycle bug that could leave the master key zeroed but the JS handle dangling.
+DIRECTION: Let exceptions propagate (or log + counter); silent swallow is the wrong default for crypto state transitions.
+
+**[P3] service-worker/index.ts:61–65 — chrome.storage.local.get on startup swallows errors**
+WHY: A typo or storage quota event leaves the timer in default state with no signal in the logs.
+DIRECTION: Surface failure via console.warn with the key name.
+
+**[P3] service-worker/git-host.ts vs github.ts/gitea.ts — deploy-key API only on Gitea side**
+WHY: The interface is asymmetric; either GitHub doesn't need it (document) or it's an unimplemented feature.
+DIRECTION: Add a doc comment on `GitHost` explaining the asymmetry, or add the GitHub op.
+
+### Extension — popup + components
+
+**[P1] settings.ts:56–65 & settings-vault.ts:15–22 — duplicated teardown helpers**
+WHY: After the stub-restore commits (`8baef5b`, `ddfb95d`), teardown leaks are a known regression class; duplicated cleanup is exactly the shape that re-introduces them.
+DIRECTION: Extract `teardownSettingsCommon()` into a single helper; have each settings section call it on unmount.
+
+**[P2] popup.ts:178–181 — teardown calls every type module unconditionally**
+WHY: Cycling views runs all 7 type teardowns on each transition; harmless today, but makes the lifecycle hard to reason about and hides which module was actually mounted.
+DIRECTION: Track last-mounted type and tear down only that one (or use a registry of `() => teardown` returned by mount).
+
+**[P2] settings.ts:33–34 — `pendingVaultSettings` and `sessionHandle` are module-scope singletons**
+WHY: Section navigation can leave stale `pendingVaultSettings` from a previous section in scope; the current code is safe by accident, not by design.
+DIRECTION: Reset to `null` on each `renderSection` entry, or scope into a closure per render.
+
+**[P2] item-list.ts:152–353 — settings-picker popover wires listeners on every render without a reuse path**
+WHY: Open/close cycles attach + detach listeners cleanly today, but rapid re-opens with throttled `setTimeout` cleanup are exactly the pattern teardown bugs hide in.
+DIRECTION: Cache the popover DOM and reuse, or use AbortController for the listeners with an explicit `signal` per open.
+
+**[P2] devices.ts:47–50 & trash.ts:39–46 — `Promise.all` without per-promise error handling**
+WHY: A single rejected RPC fails the whole render; the second response is discarded even when its data was fetched successfully.
+DIRECTION: `Promise.allSettled`, then check `.ok` per response.
+
+**[P2] generator-panel.ts:89–261 — module-scope `activePanel`; `closeGeneratorPanel()` not idempotent-guarded**
+WHY: The cleanup is currently a no-op when called twice, but the contract is implicit.
+DIRECTION: Add `if (!activePanel) return` at top.
+
+**[P3] form-header.ts:20 + types/login.ts — `isInTab()` checked twice (header + caller)**
+WHY: Redundant coupling; the popout button visibility decision happens in two places.
+DIRECTION: Pass `showPopout: boolean` into `renderFormHeader` once.
+
+**[P3] popup.ts:36–38 — `isInTab()` heuristic is `window.location.search.length > 0`**
+WHY: Any query string on `popup.html` triggers tab mode; brittle if popup is ever opened with diagnostic params.
+DIRECTION: Parse a specific param (`?view=tab` or check `window.location.pathname.endsWith('vault.html')`).
+
+**[P3] item-form.ts:95–104 — `renderComingSoon()` defined but unused**
+WHY: Document type now has a real form (`types/document.ts`); the placeholder is dead code.
+DIRECTION: Delete or leave a one-line comment explaining future use.
+
+**[P3] types/login.ts ~700 LOC — `renderForm` mixes HTML, wiring, password-strength, TOTP-ticker, and section editor**
+WHY: The reference implementation for the other 6 type modules; size makes the per-affordance lifecycle hard to follow for a learner.
+DIRECTION: Extract `wireUrlField`, `wirePasswordField`, `wireTotpField` from the body of `renderForm`. Other type modules already follow simpler patterns.
+
+### Extension — vault tab
+
+**[P1] vault/vault.ts (1027 LOC) — single file owns shell + sidebar + list + drawer + type-picker + form-wrapper + routing + teardown**
+WHY: A learner opening this file faces all responsibilities at once; teardown coupling (`teardownPaneComponents` lines 813–820) makes adding a new pane view a 5-place edit.
+DIRECTION: Split into `vault-shell.ts`, `vault-sidebar.ts`, `vault-list.ts`, `vault-drawer.ts`, `vault-form-wrapper.ts`, leaving `vault.ts` to own only routing and state.
+
+**[P2] vault/vault.ts:47–74 — vault tab intercepts `vault_locked` errors via the RPC layer; popup uses only the `session_expired` event**
+WHY: Two different mechanisms reach the same outcome; popup-targeted components running in the vault tab don't know which channel will fire first.
+DIRECTION: Lift the RPC `vault_locked` intercept into `shared/state.ts` (or a wrapper around `sendMessage`) so both surfaces use one path.
+
+**[P2] vault/vault.ts:495–536 — drawer doesn't auto-close on non-list view changes**
+WHY: Selecting an item opens the drawer; navigating to Trash via the sidebar leaves `state.drawerOpen = true` even though the drawer is no longer rendered.
+DIRECTION: `state.drawerOpen = false` at the start of `renderPane`, or when a non-list view becomes active.
+
+**[P2] vault/vault.ts:648–695 — sidebar categories re-render on every search keystroke without debounce**
+WHY: Counts and active state must sync, but at hundreds of items the keystroke path stamps the whole sidebar.
+DIRECTION: 50–100ms debounce on the search input handler before re-rendering.
+
+**[P3] vault/vault.ts:18–26 — backup-panel and import-panel are `vault/components/`-only by design**
+WHY: Correct call (popup has no room for these), but worth noting in the file header so a contributor doesn't try to import them into popup.
+DIRECTION: Add a short comment in `vault/components/index.ts` (or top of each file) explaining the vault-tab-only scope.
+
+### Extension — content scripts
+
+**[P2] content/fill.ts:50–64 — `fillFields()` returns silently when no password field is found**
+WHY: Dynamic forms (React/SPA mounting after `document_idle`) can race the fill listener; user clicks autofill, nothing visible happens, no error reaches the popup.
+DIRECTION: Send a `{type: 'fill_failed', reason: 'no_password_field'}` ack back to SW so the icon can flash an error glyph.
+
+**[P2] content/detector.ts:96–103 — MutationObserver `scan()` is not debounced**
+WHY: SPA churn fires DOM mutations many times per second; the detector re-runs the full scan each time. WeakSet stops icon double-injection, but the scan cost is wasted.
+DIRECTION: Wrap `scan()` in `requestIdleCallback` or a 200ms timer.
+
+**[P2] content/icon.ts:169–175 — outside-click listener registered in `setTimeout(0)` not removed on alternate close paths**
+WHY: Picker can close via Escape or programmatic destroy; the doc-level listener for outside-click leaks unless `closeOverlay()` is the close path.
+DIRECTION: Store the handler reference and `removeEventListener` in every close path; or `AbortController` scoped to picker open.
+
+**[P3] capture.ts vs detector.ts vs fill.ts — username-finder logic copy-pasted three ways**
+WHY: `findUsernameField`, `findUsernameForFill`, `findUsernameValue` are three forks of the same heuristic.
+DIRECTION: Extract a shared `getUsernameField(pwField, scope, { valueOnly?: boolean })`.
+
+**[P3] capture.ts:269–299 — submit-button hook scope is `form ?? pwField.parentElement`**
+WHY: A submit button outside the form (e.g. a custom React `<button onClick={...}>` siblings to the form) won't trigger capture; the user never sees the save prompt.
+DIRECTION: Walk up to the nearest form ancestor and listen for `keydown.Enter` on the password field as a fallback.
+
+**[Positive note] content scripts make zero direct WASM calls and re-validate origin in `fill.ts:32–38`** — boundary discipline holds.
+
+### Extension — setup
+
+**[P1] setup/setup.ts:28–37, 1118–1120 — WASM is loaded and called directly inside the setup wizard, bypassing the service-worker abstraction the rest of the codebase uses**
+WHY: Popup, vault tab, and content all funnel WASM through the SW; setup is the only surface that imports `relicario-wasm` and orchestrates `unlock`/`embed_image_secret`/`register_device`/`manifest_encrypt` itself. This duplicates ~400 LOC of crypto orchestration that the SW already knows how to do, and it means the setup tab can't be locked by the same session-timer the rest of the extension uses.
+DIRECTION: Add `create_vault` and `attach_vault` messages to the SW; turn `setup.ts` into a UI that posts those messages with the gathered config + image bytes. This collapses ~600 LOC into ~200 and unifies the crypto state machine.
+
+**[P2] setup/setup.ts (1220 LOC) — render/attach pairs per step are inlined**
+WHY: 6 steps × (renderStepN, attachStepN) = a switch statement that reads procedurally; adding a step means edits to the renderer, the attacher, and the wizard state.
+DIRECTION: Step registry: `{ id: 0, render: () => string, attach: (root) => Teardown }[]` keyed by mode. The 1220 LOC drops to ~500 after the WASM extraction in [P1] above and this restructure.
+
+**[P2] setup/setup.ts:69–94 — `WizardState` is module-scope; passphrase + JPEG bytes + WASM handle persist if the user abandons mid-wizard**
+WHY: A user who closes the setup tab mid-flow leaves sensitive material in JS memory until the page is unloaded. The handle isn't `free()`d.
+DIRECTION: Add a `clearWizardState()` called on `beforeunload` and on returning to step 0; explicitly `Zeroize`-equivalent for the byte arrays where possible.
+
+**[P2] setup/probe.ts:11–23 vs service-worker/vault.ts — manifest path constants duplicated (`.relicario/salt`, `.relicario/params.json`, `manifest.enc`)**
+WHY: Two sources of truth; if the metadata layout ever moves, probe and vault disagree about whether a remote is initialized.
+DIRECTION: Define `VAULT_PATHS` in `shared/types.ts` (or a new `shared/paths.ts`) and import into both.
+
+**[P3] setup/setup.ts:56, 82–83 — passphrase score uses `-1` as "not yet scored" sentinel**
+WHY: The score is conflated with strength label index 0..4; `-1` magic number is checked in two places.
+DIRECTION: Use `{ scored: false } | { scored: true; score: number; guessesLog10: number }`.
+
+**[P3] setup/setup.ts:1056–1062 — `recovery_qr_generated_at` written directly to `chrome.storage.local`, bypassing `WizardState`**
+WHY: One piece of setup result state lives outside the wizard's own state model.
+DIRECTION: Add it to `WizardState`, persist on a single `finishSetup` storage write.
+
+**[P3] setup/setup.ts:1–7 — header comment says "5-step flow"; code is 6 steps (0..5)**
+WHY: Cosmetic but actively misleading; line 42 even has a comment about the renumber.
+DIRECTION: Update header.
+
+### Extension — shared utilities
+
+**[P1] shared/state.ts:10–35 — entire `StateHost` contract is `any`-typed**
+WHY: This is the bridge that lets popup components run in the vault tab; it's also the bridge most likely to drift between the two render targets, and TS gives no signal when it does.
+DIRECTION: Define a concrete `StateHost` interface with `state: PopupState`, `navigate: (view: View) => void`, `popOutToTab(): void`, `isInTab(): boolean`, `openVaultTab(hash?: string): void`. Make `getState`/`setState` generic over `keyof PopupState`.
+
+**[P1] shared/state.ts:20 — module-scope `host` singleton with no double-registration guard**
+WHY: A second `registerHost()` call silently overwrites; in tests, the leak from a previous test breaks isolation if `beforeEach` forgets a reset.
+DIRECTION: Throw on re-register; export a `__resetHostForTests()` helper for vitest.
+
+**[P2] shared/messages.ts:85–87 — base `Response` is `{ data?: unknown }`; every consumer casts via `Extract<Response, { ok: true }>` plus `data: ...`**
+WHY: The pattern works but every call site has a hand-written `as ListItemsResponse` cast; the discriminated-union narrowing the rest of the file relies on stops at `ok: true`.
+DIRECTION: Generic `Response<TKind extends Request['type']>` mapped from a single `MessageMap` table, so the response type is inferred at the send site.
+
+**[P2] shared/form-affordances/group-autocomplete.ts:26 — `list.innerHTML = ...map(g => …).join('')` with only `replace(/"/g, '&quot;')` sanitization**
+WHY: Group names come from user-entered item data. `<` and `>` are not escaped; a malicious / mistaken group name could inject markup into the autocomplete list.
+DIRECTION: `document.createElement('option')` per group with `option.value = g; list.appendChild(option)`.
+
+**[P2] shared/messages.ts:56–66 — `restore_backup` flattens `newRemote` inline; other multi-field messages factor out a payload type**
+WHY: Inconsistent shape vs sibling messages; harder to reuse the type for the form that posts it.
+DIRECTION: Extract `RestoreBackupPayload` and intersect with `{ type: 'restore_backup' }`.
+
+**[P3] glyphs.ts vs popup/components — raw glyph literals (`⧉`, `↻`, `▸`, `▾`, `≡`, `⤓`) appear inline in `item-form.ts`, `item-list.ts`, `settings.ts`, `generator-panel.ts`, `attachments-disclosure.ts`, `fields.ts`**
+WHY: The whole point of `glyphs.ts` is the no-inline-emoji rule; partial adoption defeats the audit story.
+DIRECTION: Add the missing constants (`GLYPH_COLLAPSE`, `GLYPH_EXPAND`, `GLYPH_ATTACHMENT`, `GLYPH_REGENERATE`, `GLYPH_OVERFLOW`, `GLYPH_DOWNLOAD`) and migrate the call sites. Pair with `extension/src/shared/__tests__/glyphs.test.ts` to lock it in.
+
+**[P3] shared/types.ts:82 — `TotpKind = 'totp' | 'steam' | { hotp: { counter: number } }`**
+WHY: Mixed string/object union forces every consumer to do `typeof k === 'string' ? k : k.hotp`; a flat discriminated union is cheaper to read.
+DIRECTION: `{ kind: 'totp' } | { kind: 'steam' } | { kind: 'hotp'; counter: number }` with serde rename if the wire format must stay.
+
+**[P3] shared/form-affordances/totp-tools.ts:39–46 — `void tick()` swallows promise rejections**
+WHY: TOTP preview RPC can fail (e.g., decrypt error); the user sees a frozen ticker with no signal.
+DIRECTION: `try { await tick() } catch (e) { renderError(row, e) }`.
+
+### WASM boundary (JS side)
+
+**[P2] extension/src/wasm.d.ts — declarations are hand-written and explicitly require manual sync with `crates/relicario-wasm/src/lib.rs`**
+WHY: Comment at top of the file says so; this is exactly the kind of contract that drifts when one side adds a new export. (Today, declarations and the Rust signatures are aligned.)
+DIRECTION: Add a CI check that compares `crates/relicario-wasm/pkg/relicario_wasm.d.ts` (wasm-pack output) against `extension/src/wasm.d.ts`, or import the generated `.d.ts` directly via `wasm-pack build --target web` and the runtime loader. Note for DEV-B in boundary section.
+
+**[P2] extension/src/__stubs__/relicario_wasm.stub.ts — only 7 of ~25 exports are stubbed; the rest will throw `wasm stub: X not mocked`**
+WHY: Adding a vitest test that touches a new WASM call needs an ad-hoc mock per test; central stub is incomplete.
+DIRECTION: Either round out the stub with throwing stubs for the full surface, or provide a `mockWasm({ unlock, item_decrypt, ... })` test helper.
+
+### Relay tooling
+
+**[P1] tools/relay/queue.test.ts:54 — `assert.ok(!isRole("dev-c"))` fails (verified: `bun test` → 1 fail)**
+WHY: Uncommitted change added `dev-c` to the `Role` union and `KNOWN_ROLES` set in `queue.ts`, but the test still asserts the old enum. This is a P1 because it's a real test failure on uncommitted code, blocking a green test run.
+DIRECTION: Update the test assertion to `assert.ok(isRole("dev-c"))` and add a negative case (`assert.ok(!isRole("dev-d"))`).
+
+**[P1] tools/relay/start.sh — kitty mode launches Dev-C window? Verify against the script**
+WHY: The 4-role refactor (pm/dev-a/dev-b/dev-c) needs a fourth window in the launcher. Per the subagent's read, `start.sh:80` still hardcodes "Dev-B" in user-facing output.
+DIRECTION: Update the launcher prints to mention all 4 roles and confirm a 4th `--type=tab --hold` window is opened with the dev-c prompt.
+
+**[P2] tools/relay/call.py and tools/relay/call.ts — untracked, no .gitignore policy**
+WHY: Coordination prompts (including this one's "Fallback" section) reference `call.py` by path — it's load-bearing for the multi-agent flow, not an experiment. Untracked load-bearing files are a coordination footgun (a fresh checkout breaks the fallback).
+DIRECTION: Track both with a one-line header explaining "MCP-fallback shim for the relay; see docs/superpowers/coordination/...". If either is genuinely scratch, add to `.gitignore` instead — but pick one.
+
+**[P2] tools/relay/queue.ts:21–27 — in-memory queue with no TTL, persistence, or cap**
+WHY: A long-running relay accumulates messages indefinitely; if a session sleeps for a day, the queue is the only audit trail and could grow unbounded.
+DIRECTION: Document the dev-only ephemeral contract at the top of `queue.ts`, or add a per-role cap (e.g., last 1000 messages).
+
+**[P3] tools/relay/server.ts:115–127 — `makeServer()` factory pattern is correct but unexplained**
+WHY: The diff swap from a global `mcpServer` to per-connection factories is load-bearing for concurrent client isolation, but a future contributor might revert it as "unnecessary complexity".
+DIRECTION: One-line comment above `makeServer`: "Per-connection MCP server prevents routing collisions across concurrent SSE clients."
+
+### CLI/extension parity gaps
+
+**[P2] No equivalent to `relicario status`** — CLI shows pending sync state, ahead/behind, dirty-tree summary; extension surfaces nothing comparable. The vault-tab footer or a sidebar badge would be the natural home.
+DIRECTION: Add a `get_vault_status` message returning `{ ahead: n, behind: n, lastSyncAt: ts, pendingItems: n }` and a small status indicator in the vault sidebar.
+
+**[P3] No explicit per-attachment detach message** — CLI has `relicario detach <item> <aid>`; extension forces a roundtrip through `update_item` with the `attachments[]` mutated client-side. Functional, but it's racy if two devices edit at once.
+DIRECTION: Add a `delete_attachment` message that does the surgical remove on the SW side.
+
+**[P3] CLI `list --tag X` filter** — extension does tag filtering client-side after `list_items`; that's fine for the family-vault scale spec but may surprise a learner who reads the CLI side first.
+DIRECTION: Document the choice in `messages.ts` near `list_items`.
+
+### Cross-cutting
+
+**[P2] Direct `chrome.storage.local` reads from popup components** — `settings-security.ts:112–113` and `setup.ts:1056–1062` read storage directly while every other popup module routes via `sendMessage`. Inconsistency makes the data-flow story split across two paradigms.
+DIRECTION: Pick one: either every storage read goes through `get_settings`/`get_session_config`, or document explicitly that `setup` and `settings-security` are SW-bypass code paths for stated reasons.
+
+**[P2] `bun test` is not the project's intended runner** — `extension/package.json:13` defines `test: vitest run`, but `tools/relay/` uses `node:test` via `bun test`. A learner will hit failures running `bun test` from the repo root because `bun` doesn't load `happy-dom`.
+DIRECTION: Add a top-level README note: "extension uses `cd extension && npm run test`; relay uses `cd tools/relay && bun test`."
+
+**[P3] Manifest version 0.5.0** — both `extension/manifest.json` and `manifest.firefox.json` show `0.5.0`, while `package.json` is also `0.5.0`. The roadmap is at v0.5.1-dev; uncommitted bumps to package.json/manifest may be coming. Worth a quick PM check.
+
+## File-by-file walk
+
+### `extension/src/wasm.d.ts` and `__stubs__/relicario_wasm.stub.ts`
+Hand-written ambient module declarations mirroring `crates/relicario-wasm/src/lib.rs`. 25+ exports cover unlock/lock, manifest+item+settings encrypt/decrypt, attachment encrypt/decrypt, ID generation, password/passphrase generation + zxcvbn rate, image-secret embed/extract, TOTP compute, device register/sign/get/clear, recovery-QR. The stub used by vitest covers only 7 exports — every other call throws "not mocked" at test time.
+
+### `extension/src/shared/`
+`types.ts` (286 LOC) is the canonical TS view of the Rust core schema; well-commented mappings to serde. `messages.ts` (207 LOC) is the discriminated-union message contract and the `POPUP_ONLY_TYPES` / `CONTENT_CALLABLE_TYPES` capability sets that the router uses for sender gating. `state.ts` (62 LOC) is the popup-vs-vault host indirection — currently `any`-typed. `glyphs.ts` (39 LOC, recently edited) is the centralized monospace glyph set. `color-scheme.ts`, `error-copy.ts`, `base32.ts`, `password-coloring.ts`, `toast.ts` are tight focused utilities. `form-affordances/` holds 5 input-behavior wirings (group autocomplete, notes mono toggle, password reveal/strength/QR, TOTP preview/QR, URL fill) plus a tiny `index.ts`.
+
+### `extension/src/service-worker/`
+`index.ts` is the entry point: WASM load on first message, RouterState construction, session-timer wiring, `chrome.runtime.onMessage` listener. `vault.ts` (397 LOC) is the encrypted I/O layer — every WASM call passes the `SessionHandle`, never a raw key. `session.ts` is the single-handle store; `session-timer.ts` implements both `inactivity` and `every_time` modes. `devices.ts` reads/writes `.relicario/devices.json` and `revoked.json`. `gitea.ts` and `github.ts` mirror each other (Gitea has deploy-key ops; GitHub doesn't); `git-host.ts` is the abstraction. `router/index.ts` classifies the sender and dispatches to `popup-only.ts` (40+ handlers) or `content-callable.ts` (5 handlers).
+
+### `extension/src/popup/`
+`popup.ts` (entry) wires the host registration, view router, and lock/unlock flow. `index.html` is a single `#popup-app` container. `styles.css` carries the popup theme. `components/` holds the visible widgets: `unlock`, `item-list`, `item-detail`, `item-form`, `form-header`, `fields`, `field-history`, `attachments-disclosure`, `generator-panel`, `devices`, `trash`, plus the new `settings.ts` / `settings-vault.ts` / `settings-security.ts` left-nav (v0.5.1). `components/types/` holds the 7 type-specific item modules — `login.ts` is the reference, the others (secure-note, identity, card, key, document, totp) are smaller variants.
+
+### `extension/src/vault/`
+`vault.html` (12 LOC) loads `vault.css` + `vault.js`. `vault.css` (~2200 LOC) carries the dark/gold theme + 3-column layout. `vault.ts` (1027 LOC) orchestrates everything: shell init, hash routing, sidebar, list, drawer, type-picker, form-wrapper, deep-link routing, teardown. `components/backup-panel.ts` and `components/import-panel.ts` are vault-tab-only (high-risk operations need fullscreen affordances). Tests: `form-wrapper.test.ts`, `sidebar-glyphs.test.ts`.
+
+### `extension/src/content/`
+`detector.ts` finds password fields and injects icons via a MutationObserver. `fill.ts` receives `fill_credentials`, re-validates the page hostname, and uses the native-setter trick to set values past React/Vue. `capture.ts` hooks form submits and shows a closed-Shadow-DOM save prompt. `icon.ts` renders the in-page icon and credentials picker. `shadow.ts` is the closed-Shadow-DOM helper. **Zero WASM calls; clean boundary.**
+
+### `extension/src/setup/`
+`setup.ts` (1220 LOC) is the 6-step (0..5) wizard: mode pick → remote config → image select / passphrase → derive+verify or create+embed → device register → recovery QR. Imports WASM directly. `setup-helpers.ts` (84 LOC) is a clean utility module (escapeHtml, debounced rate, strength labels). `probe.ts` (23 LOC) checks for an existing vault on the configured remote.
+
+### `tools/relay/`
+`server.ts` is the MCP server with HTTP/SSE transport (per-connection `makeServer()`). `queue.ts` is the in-memory FIFO with `Role` enum and `isRole()` guard. `queue.test.ts` is `node:test` based (4 pass / 1 fail on uncommitted state). `call.py` and `call.ts` are the MCP-fallback shims (untracked). `start.sh` launches manual / tmux / kitty modes. `package.json`, `tsconfig.json` keep the relay self-contained.
+
+## CLI/extension parity table
+
+| CLI capability | Extension equivalent | Notes |
+|---|---|---|
+| `init --image --output` | `save_setup` + setup wizard step 3-new | ✓ (parity via setup.ts; see [P1] about routing through SW) |
+| `add login/secure_note/identity/card/key/document/totp` | `add_item` + `types/<kind>.ts` form | ✓ |
+| `get <query> [--show] [--copy]` | `get_item` + popup detail; clipboard via `navigator.clipboard` | ✓ |
+| `list [--type] [--group] [--tag] [--trashed]` | `list_items`, `list_trashed`, client-side filter; `list_groups` for autocomplete | ✓ |
+| `edit <query> [--totp-qr]` | `update_item` + `wireTotpQr` (jsQR lazy import) | ✓ |
+| `history <query>` | `get_field_history` + `field-history.ts` | ✓ |
+| `rm <query>` (soft) | `delete_item` | ✓ |
+| `restore <query>` | `restore_item` | ✓ |
+| `purge <query>` | `purge_item` | ✓ |
+| `trash list / empty` | `list_trashed` / `purge_all_trash` + `trash.ts` | ✓ |
+| `backup export` | `export_backup` + `backup-panel.ts` | ✓ |
+| `backup restore` | `restore_backup` + `backup-panel.ts` (restore path) | ✓ |
+| `import lastpass <csv>` | `parse_lastpass_csv` + `import_lastpass_commit` + `import-panel.ts` | ✓ |
+| `attach <query> <file>` | `upload_attachment` | ✓ |
+| `attachments <query>` | `AttachmentRef[]` already inside `get_item` | ✓ (no separate message; same data) |
+| `extract <query> <aid>` | `download_attachment` | ✓ |
+| `detach <query> <aid>` | (no message) — done via `update_item` with mutated `attachments[]` | **partial / ✗** |
+| `generate --length / --bip39 …` | `generate_password` / `generate_passphrase` + `generator-panel.ts` | ✓ |
+| `settings trash-retention / history-retention / attachment-cap / generator-defaults` | `get_vault_settings` / `update_vault_settings` + `settings-vault.ts` | ✓ |
+| `sync` | `sync` | ✓ |
+| `status` | (no message) | **✗ — gap** |
+| `lock` | `lock` | ✓ |
+| `completions <shell>` | N/A (CLI-only) | n/a |
+| `rate <passphrase>` | `rate_passphrase` (zxcvbn gate) | ✓ |
+| `device add / revoke` (+ list) | `add_device` / `register_this_device` / `revoke_device` / `list_devices` / `list_revoked` + `devices.ts` | ✓ |
+| `recovery-qr generate / unwrap` | `generate_recovery_qr` / `unwrap_recovery_qr` + `settings-security.ts` | ✓ |
+| (browser-only autofill) | `get_autofill_candidates`, `get_credentials`, `check_credential`, `blacklist_site`, `capture_save_login`, `fill_credentials`, `ack_autofill_origin`, `get_blacklist`, `remove_blacklist`, `get_active_tab_url` | extension-only (no CLI counterpart, by design) |
+| (browser-only device UX) | `get_settings` / `update_settings` (DeviceSettings: captureEnabled, captureStyle) | extension-only |
+
+**Summary:** 22/23 CLI capabilities have a clean extension path; `status` is the one true gap, and `detach` is partial. No "CLI first, extension follow-up" violations under this lens.
+
+## Boundary notes for DEV-B
+
+1. **`extension/src/wasm.d.ts` is hand-maintained** — every change to `crates/relicario-wasm/src/lib.rs`'s `#[wasm_bindgen]` surface must be mirrored manually. Worth a CI guardrail comparing the wasm-pack–generated `.d.ts` against this file. (See [P2] in WASM boundary.)
+
+2. **The session handle is opaque on the JS side** (`SessionHandle.value: number`, `free()`). DEV-B owns the Rust-side lifecycle: confirm that double-`free()` from JS is a no-op rather than a panic, since `service-worker/session.ts:26` currently swallows free errors silently. If the Rust side could panic on double-free, the silent swallow becomes a crash mask.
+
+3. **`attachment_encrypt(handle, plaintext, max_bytes: bigint)`** — the JS side passes `BigInt` for `max_bytes`. Confirm the Rust binding accepts `u64` and that the conversion is loss-free. The extension is going to push this with γ₁ enforcement (per project memory).
+
+4. **`register_device(name)` returns `{ signing_public_key, deploy_public_key }`** as a plain object (not a class). Setup wizard relies on both being hex strings (`device.public_key` lookup paths). Confirm the device key types stay strings on the Rust side rather than ever moving to `Uint8Array`.
+
+5. **`generate_recovery_qr(handle, passphrase) → string`** and `unwrap_recovery_qr(payload_b64, passphrase) → Uint8Array` — the QR payload format is a contract between this surface and the CLI's `recovery-qr` subcommand. If DEV-B is reviewing recovery-QR end-to-end, confirm that re-deriving from a recovery QR produces the same `master_key` regardless of which side (CLI vs extension) generated it.
+
+6. **`extract_image_secret(image_bytes) → Uint8Array` and `embed_image_secret(carrier, secret) → Uint8Array`** — the central-embed DCT scheme has `MAX_DIMENSION` and `QUANT_STEP = 50.0` constants on the Rust side. The setup wizard does no client-side dimension check before passing the image; if a >MAX_DIMENSION JPEG is selected, the failure message bubbles up generically. DEV-B may want a more specific Rust-side error variant the extension can re-render.
+
+## Beginner-friendliness assessment (TS side)
+
+**Reading order recommendation:** start with `extension/src/shared/messages.ts` and `types.ts` — they tell you the entire vocabulary in 500 lines. Then `service-worker/router/index.ts` to see how messages get routed. Then pick **one** vertical to follow end-to-end: `popup/components/types/login.ts` → `service-worker/router/popup-only.ts` (the `add_item`/`update_item` handlers) → `service-worker/vault.ts`. After that, `content/detector.ts` + `content/fill.ts` + the corresponding `content-callable.ts` handlers cover the autofill story.
+
+**Trip wires:** the two oversized files (`vault.ts` 1027 LOC, `setup.ts` 1220 LOC) are the steepest cliffs. A learner who opens `setup.ts` first will see WASM imported directly and conclude that's the pattern — it isn't; that file is the exception. Adding a short `EXTENSION_ARCH.md` (or a comment block at the top of `setup.ts`) noting "WASM is loaded directly here only because vault creation predates the SW; everywhere else, route through `chrome.runtime.sendMessage`" would save half a day.
+
+**Strongest learning surfaces:** the discriminated-union message contract, the per-type item form modules (small, parallel, easy to diff), and `service-worker/router/router.test.ts`. The shared form-affordances are also a model of pure-function wiring with explicit teardown — once those patterns click, the rest of the popup is "more of the same."
+
+**Weakest learning surface:** `shared/state.ts` — it's the bridge between popup and vault tab, but the `any` typing tells you nothing about what flows through it. Tightening this is a high-leverage change.
+
+## Uncommitted-state read
+
+The working tree has substantial uncommitted changes. Architecturally relevant:
+
+- **`extension/src/vault/vault.ts` (+151/−99) and `vault.css` (+238/−99)** — appear to be active work on the form wrapper sticky bar, drawer field grid, and gold-rebrand color palette (Phase 2B). Treat these as **in flight, ignore for this review** — they don't change the architectural shape, only the visual surface.
+- **`extension/src/shared/glyphs.ts` (+/−2) and `__tests__/glyphs.test.ts` (+/−2)** — small additions, likely a new glyph constant. Doesn't affect the [P3] glyph adoption finding (the inline-literal call sites would still need migration).
+- **`extension/manifest.json` and `manifest.firefox.json` (+/−2)** — likely a version bump in flight; PM should decide whether v0.5.1-dev gets a synced bump in `package.json` too.
+- **`tools/relay/queue.ts`, `server.ts`, `start.sh` (modified) + `call.py`, `call.ts` (untracked)** — these are **architecturally relevant**: the dev-c role expansion is real, and `call.py`/`call.ts` are documented-but-untracked fallback shims. The broken test (`queue.test.ts:54`) is the P1 the rest of this review flags. **Do not ignore.**
+- **`Cargo.lock`, `crates/*/Cargo.toml`** — out of scope; flag to DEV-A/DEV-B if not already on their list.
+- **`.gitea_env_vars` (untracked)** — name suggests local credentials; should be `.gitignore`d if not already (PM check).
+- **`docs/superpowers/coordination/v0.5.1-*` and `architecture-review-*`** — coordination prompt evolution; not architectural.
+
+**My call:** vault/vault.css/glyphs/manifest changes are in-flight and shouldn't change findings. The relay changes ARE architecturally on-the-table because the new dev-c role + factory pattern are visible in the running review process. The relay test failure is treated as a P1 because it blocks `bun test` from going green and the kickoff prompt explicitly says "Review is not gated on green; it's gated on understanding" — but this is one cheap fix away from a green test run, and a learner running `bun test` first will assume the codebase is broken.

docs/superpowers/specs/2026-05-04-cli-restructure-design.md

@@ -0,0 +1,215 @@
+# CLI Restructure — Design
+
+**Date:** 2026-05-04
+**Status:** Proposed
+**Source:** `docs/superpowers/reviews/2026-05-04-architecture-review.md` (P1.2, P1.3, P1.10) + folded P2s from DEV-B's CLI section + DEV-A's P2 base32 dedup
+**Effort estimate:** M-L
+
+## Summary
+
+Plan B is the single biggest readability lift in the whole-codebase architecture review. `crates/relicario-cli/src/main.rs` is a 2641-line flat file: every `cmd_*`, every `build_*_item`, every `edit_*`, six prompt helpers, three pure parsers, the `ParamsFile` writer, and 24+ git shell-outs all live as peers. This plan splits that file into a `commands/` folder plus `prompt.rs` and `parse.rs`, then builds on top of that split to centralize the duplicated git-error UX, unify the manifest-after-mutation cache discipline, deduplicate the on-disk `params.json` shape, batch the `cmd_purge` git invocations, and finally migrate the pure parsers (and a third copy of base32) into `relicario-core` so the extension can consume them through new WASM exports. After the file is navigable rather than scrollable, a tinkerer who opens `cmd_add` can follow it end-to-end in one screenful — which is the user's stated learning-by-tinkering goal.
+
+## Findings addressed
+
+- **P1.2** — `crates/relicario-cli/src/main.rs:1-2641` is a 2641-line monolith with no submodule boundaries (DEV-B). The clap surface (lines 1-455) is excellent; lines 456-2641 are flat code.
+- **P1.3** — Git invocation boilerplate duplicated ~16× with one-line `bail!("git X failed")` errors at `crates/relicario-cli/src/main.rs:601, 602, 610, 986, 988, 1477, 1480, 1767, 1897, 1900, 2432, 2438, 2533, 2540` (and others) (DEV-B).
+- **P1.10** — Pure parsers (`parse_month_year`, `base32_decode_lenient`, `guess_mime`) live only in the CLI at `crates/relicario-cli/src/main.rs:942-980` despite the extension needing them (DEV-B). Pairs with DEV-A's P2 finding that three base32 implementations live in core (`crates/relicario-core/src/item.rs:255-275`, `crates/relicario-core/src/import_lastpass.rs:202-220`, and intentionally separate Steam at `crates/relicario-core/src/item_types/totp.rs:13`).
+- **CLI P2 — `build_*_item` complexity** at `crates/relicario-cli/src/main.rs:664-921` (DEV-B). Each builder mixes prompting, parsing, and core construction.
+- **CLI P2 — `refresh_groups_cache` discipline** at `crates/relicario-cli/src/main.rs:641, 998, 1123, 1197, 1414, 1432, 1474` (DEV-B). The "every mutating handler must call this" rule is unenforced.
+- **CLI P2 — `ParamsFile` defined twice with mismatching shapes** at `crates/relicario-cli/src/main.rs:2287` (writer with `aead`, `salt_path`, `format_version`) versus `crates/relicario-cli/src/session.rs:114` (reader with only `kdf`) (DEV-B).
+- **CLI P2 — Batched purge needed** at `crates/relicario-cli/src/main.rs:1476-1480` and `:1896-1900` (DEV-B). A 50-item `trash empty` currently fires 150 git invocations.
+
+## Approach
+
+The architectural shape is "one file per top-level subcommand, plus two cross-cutting helpers, plus a thin dispatcher." The clap definitions stay at the top of `main.rs` because they read like a tour of the product and that's exactly what a learner wants to land on first; everything past the dispatcher moves out. Each new module becomes self-contained enough that a tinkerer following a single command does not need to scroll through neighbours.
+
+Post-split layout under `crates/relicario-cli/src/`:
+
+```
+src/
+├── main.rs              # clap surface (Cli, Commands, AddKind, …) + dispatch match (~470 lines)
+├── helpers.rs           # vault_dir, git_command, git_run (NEW), iso8601, humanize_age,
+│                        # groups_cache_path, sanitize_for_commit, decode_totp_qr
+├── session.rs           # UnlockedVault, ParamsFile (single canonical), after_manifest_change (NEW)
+├── device.rs            # ed25519 keypair storage, configure_git_signing
+├── gitea.rs             # GiteaClient (deploy-key API)
+├── prompt.rs            # NEW — prompt, prompt_optional, prompt_secret, prompt_or_flag<T>,
+│                        #       and the four other small prompt_* helpers
+├── parse.rs             # NEW — thin wrappers around the migrated core parsers
+│                        #       (until phase 7, the parsers themselves live here)
+└── commands/
+    ├── mod.rs           # NEW — pub use re-exports for the dispatcher
+    ├── add.rs           # cmd_add + the seven build_*_item helpers
+    ├── get.rs           # cmd_get
+    ├── list.rs          # cmd_list, cmd_history, resolve_query
+    ├── edit.rs          # cmd_edit + per-type edit_* helpers
+    ├── trash.rs         # cmd_rm, cmd_restore, cmd_purge, cmd_trash, cmd_trash_empty,
+    │                    #   purge_item
+    ├── backup.rs        # cmd_backup, cmd_backup_export, cmd_backup_restore
+    ├── import.rs        # cmd_import (LastPass)
+    ├── attach.rs        # cmd_attach, cmd_attachments, cmd_extract, cmd_detach
+    ├── settings.rs      # cmd_settings (and its subaction handlers)
+    ├── sync.rs          # cmd_sync (push/pull/fetch)
+    ├── status.rs        # cmd_status (vault state summary)
+    ├── device.rs        # cmd_device + register/revoke/list, load_gitea_client
+    ├── recovery_qr.rs   # cmd_recovery_qr, cmd_recovery_qr_generate, cmd_recovery_qr_unwrap
+    ├── init.rs          # cmd_init  (also writes ParamsFile via session module)
+    ├── generate.rs      # cmd_generate
+    └── rate.rs          # cmd_rate
+```
+
+Rationale for the boundaries:
+
+- **One file per top-level subcommand** is the navigation invariant: `relicario add` ⇒ `commands/add.rs`. `cmd_add` and the seven `build_*_item` helpers it calls are the ~260-line vertical slice a tinkerer wants in front of them at once. Same shape for every other subcommand.
+- **`prompt.rs` is the input layer**: every command that reads from the user funnels through one module, so swapping in a different prompt strategy (richer TTY widgets, scripted-test mode) is a one-file change. The `prompt_or_flag<T>` helper introduced in phase 3 lives here.
+- **`parse.rs` is the validation layer** during phases 1–6 — it owns `parse_month_year`, `base32_decode_lenient`, `guess_mime`. In phase 7 the bodies move to `relicario-core` and `parse.rs` becomes a thin re-export so callers don't have to change imports twice.
+- **`helpers.rs` keeps `git_command` (the hardened `Command` builder) and gains `git_run`** (the bail-on-failure wrapper). Both are flat utilities; they belong with `vault_dir` and `iso8601`.
+- **`session.rs` keeps `UnlockedVault` and absorbs the canonical `ParamsFile`** so the on-disk shape has one definition, not two. The `after_manifest_change` wrapper introduced in phase 4 also lives here, because it's logically a session method.
+- **`commands/mod.rs`** re-exports each `cmd_*` so the dispatch match in `main.rs` reads as `Commands::Add { kind } => commands::add::cmd_add(kind)` — the dispatch surface still fits on one screen.
+
+Boundary discipline: every `cmd_*` becomes `pub fn` in its module file; every `build_*_item` and `edit_*` stays `pub(super)` (only its sibling dispatcher needs it). Helpers shared across `commands/` (e.g. `commit_paths`, `resolve_query`) live in `commands/mod.rs` as `pub(crate)`. The compile error if a sibling moves and a caller forgets the visibility bump is exactly the safety net we want.
+
+**WASM/extension parity seam (P1.10).** The three CLI parsers move into `relicario-core` in phase 7, get re-exported as `#[wasm_bindgen]` functions in phase 8, and the `extension/src/wasm.d.ts` file is updated in the same commit (per DEV-C's boundary note, that file is hand-maintained — every export change must be mirrored manually). Plan C (extension restructure) then wires SW message handlers that call those WASM exports; **the SW handlers themselves are not designed in this plan** — phase 8 only delivers the seam Plan C consumes.
+
+## Implementation phases
+
+### Phase 1 — Mechanical split of `main.rs`
+
+- **Goal:** turn 2641 LOC of flat code into a navigable directory tree without changing any behaviour.
+- **Changes:**
+  - New: `crates/relicario-cli/src/commands/{mod,add,get,list,edit,trash,backup,import,attach,settings,sync,status,device,recovery_qr,init,generate,rate}.rs`.
+  - New: `crates/relicario-cli/src/prompt.rs` (lifts `prompt`, `prompt_optional`, `prompt_secret` from `main.rs:508-940`).
+  - New: `crates/relicario-cli/src/parse.rs` (lifts `parse_month_year`, `base32_decode_lenient`, `guess_mime` from `main.rs:942-980`).
+  - Modified: `crates/relicario-cli/src/main.rs` — keeps `mod` declarations, the clap `Cli`/`Commands`/`AddKind` enums (lines 1-455), the dispatch `match` (lines 405-454), the three `test_*_override()` shims (lines 475-503), and the `refresh_groups_cache` shim (lines 457-473) until phase 4 collapses it.
+  - Modified: every other file that referenced `crate::session::UnlockedVault::unlock_interactive`, `crate::helpers::*`, `crate::test_passphrase_override` keeps working unchanged (visibility bumps only).
+- **Tests:** the existing CLI integration tests at `crates/relicario-cli/tests/{basic_flows,attachments,backup,edit_and_history,settings,smart_inputs,vault_detection,import_lastpass}.rs` are the regression budget. They test from the binary surface (via `assert_cmd`), so a pure relocation must not change a single assertion. Run between every sub-step. No new tests in this phase; logic is unchanged.
+- **Effort:** M (largest single phase by LOC moved; mechanical).
+- **Depends on:** none.
+
+### Phase 2 — `helpers::git_run` and the 16-site sweep
+
+- **Goal:** replace 16 `bail!("git X failed")` one-liners with `git_run(repo, args, context)?`, so a failing git subprocess prints actionable stderr instead of just the verb.
+- **Changes:**
+  - Modified: `crates/relicario-cli/src/helpers.rs` — adds `pub fn git_run(repo: &Path, args: &[&str], context: &str) -> Result<()>` that uses `.output()` (capturing stderr), prints the captured stderr unmodified to the user's stderr on failure, and bails with `"<context>: git failed (status N)"`. Keeps `git_command` for the rare interactive callsite that needs a `Command` (phase decides per call).
+  - Modified: `crates/relicario-cli/src/commands/init.rs` — three sites collapse (`main.rs:601, 602, 610` post-split). Contexts: `"init: git init"`, `"init: git add"`, `"init: git commit"`.
+  - Modified: `crates/relicario-cli/src/commands/add.rs` — two sites in `commit_paths` (`main.rs:986, 988` post-split moves to `commands/mod.rs`). Context: `"add: git add <id>"`, `"add: git commit"`.
+  - Modified: `crates/relicario-cli/src/commands/trash.rs` — `cmd_purge` and `cmd_trash_empty` sites (`main.rs:1477, 1480, 1897, 1900` post-split). Contexts include the item title for trace clarity. (Phase 6 batches them further.)
+  - Modified: `crates/relicario-cli/src/commands/edit.rs` — `main.rs:1767` site post-split. Context: `"edit: git commit"`.
+  - Modified: `crates/relicario-cli/src/commands/sync.rs` — `main.rs:2432, 2438, 2533, 2540` sites post-split. Contexts: `"sync: git fetch"`, `"sync: git pull"`, `"sync: git push"`.
+  - Modified: any other `git_command(...).status()? + bail!` site identified by grep during phase 1 (DEV-B's "and others" list).
+- **Tests:** add a unit test in `crates/relicario-cli/src/helpers.rs`'s `mod tests` that invokes `git_run` against a deliberately-failing git subcommand in a `tempfile::TempDir` and asserts both that the bail message contains the context string and that the captured stderr is reproduced. Existing integration tests must still pass.
+- **Effort:** S.
+- **Depends on:** Phase 1.
+
+### Phase 3 — `prompt_or_flag<T>` and `build_*_item` compression
+
+- **Goal:** collapse the seven `build_*_item` builders so each one takes already-validated values, with a single `prompt_or_flag<T>` helper handling the "use this flag if Some, otherwise prompt" pattern.
+- **Changes:**
+  - Modified: `crates/relicario-cli/src/prompt.rs` — adds `pub fn prompt_or_flag<T>(flag: Option<T>, label: &str, parser: impl FnOnce(&str) -> Result<T>) -> Result<T>` and a `prompt_or_flag_optional<T>` sibling for fields where the empty-string case maps to `None`.
+  - Modified: `crates/relicario-cli/src/commands/add.rs` — every `build_*_item` (post-split locations of `main.rs:664-921`) drops its `Option<T>::map(Ok).unwrap_or_else(|| prompt(...))?` chains in favour of `prompt_or_flag(title, "Title", |s| Ok(s.into()))?` etc. Per-type bodies shrink by ~30%.
+- **Tests:** existing `tests/basic_flows.rs::add_login_then_list_shows_it`, `tests/smart_inputs.rs` cover the prompt path; `tests/attachments.rs` covers the document builder. Add one focused test: `prompt_or_flag_uses_flag_value_when_some` and `prompt_or_flag_prompts_when_none` (synthetic stdin via `Cursor`).
+- **Effort:** S-M.
+- **Depends on:** Phase 1.
+
+### Phase 4 — `Vault::after_manifest_change` and the seven-site sweep
+
+- **Goal:** make "every mutating handler must call `refresh_groups_cache`" a compile-time invariant rather than a discipline rule.
+- **Changes:**
+  - Modified: `crates/relicario-cli/src/session.rs` — adds `pub fn after_manifest_change(&self, manifest: &Manifest) -> Result<()>` that calls `self.save_manifest(manifest)?` and then writes the groups cache. Marks the existing `save_manifest` as `pub(crate)` (or renames to `save_manifest_raw` and makes it `pub(crate)`) so callers funnel through the wrapper. Cache writing logic moves out of `main.rs:457-473` into this method.
+  - Modified: `crates/relicario-cli/src/commands/{add,edit,trash,attach,settings,import}.rs` — the seven sites (`main.rs:641, 998, 1123, 1197, 1414, 1432, 1474` post-split) collapse from `vault.save_manifest(&manifest)?; refresh_groups_cache(vault.root(), &manifest);` to `vault.after_manifest_change(&manifest)?;`.
+  - Removed: the standalone `refresh_groups_cache` function in `main.rs:463`. The cache-write closure inside `after_manifest_change` keeps the existing "failures are silently swallowed" semantics (preserve the `let _ =` and the doc comment from `main.rs:457-462`).
+- **Tests:** `tests/smart_inputs.rs::groups_cache_*` already exercises the write/suppress paths from the binary surface; rerun. Add a unit test in `session.rs` confirming `after_manifest_change` writes both the manifest and the cache file.
+- **Effort:** S.
+- **Depends on:** Phase 1.
+
+### Phase 5 — Single canonical `ParamsFile`
+
+- **Goal:** one definition of the on-disk `params.json` shape, used by both the `init` writer and the `unlock_interactive` reader.
+- **Changes:**
+  - Modified: `crates/relicario-cli/src/session.rs` — promotes the inner `ParamsFile` struct (`session.rs:114`) to a module-level `pub(crate) struct ParamsFile { pub format_version: u32, pub kdf: KdfParams, pub aead: String, pub salt_path: String }`. Adds `Serialize` + `Deserialize` derives. Provides constructors: `ParamsFile::for_new_vault(params: &KdfParams) -> Self` and inversion `pub fn into_kdf_params(self) -> KdfParams`. Verifies field-rename compatibility against the existing on-disk JSON (read a temp `params.json` written by current `main.rs` to confirm round-trip).
+  - Modified: `crates/relicario-cli/src/commands/init.rs` — replaces the inline `ParamsFile`/`ParamsKdf` structs at the post-split equivalent of `main.rs:2287-2301` with `session::ParamsFile::for_new_vault(&params)`. Removes the duplicate writer-side definition.
+  - Decision note in the module doc-comment: keep `ParamsFile` in `session.rs` rather than `relicario-core`. Rationale: the struct describes a *file on disk*, and `relicario-core` is bytes-in/bytes-out (no filesystem). The `KdfParams` value inside is core's already; the envelope is the CLI's I/O concern.
+- **Tests:** add `tests/common/mod.rs` (or extend an existing test) round-trip: write via `ParamsFile::for_new_vault`, parse via `read_params`, confirm the resulting `KdfParams` matches the input. The on-disk schema must not change (`tests/basic_flows.rs::init_creates_expected_layout` indirectly covers this).
+- **Effort:** S.
+- **Depends on:** Phase 1.
+
+### Phase 6 — Batched purge in `cmd_purge` and `cmd_trash_empty`
+
+- **Goal:** a 50-item `trash empty` should fire 3 git invocations total, not 150.
+- **Changes:**
+  - Modified: `crates/relicario-cli/src/commands/trash.rs` — `purge_item` (post-split of `main.rs:1450-1462`) is renamed `purge_item_filesystem` and **only** mutates the working tree + manifest (filesystem `remove_file`/`remove_dir_all`, manifest `remove`). It does **not** invoke `git rm`. Returns `Vec<String>` of the paths it removed (so the caller can stage them).
+  - `cmd_purge` (post-split `main.rs:1464-1482`): collects the paths from `purge_item_filesystem`, calls `vault.after_manifest_change(&manifest)?`, then a single `git_run(vault.root(), &["rm", "-rf", "--ignore-unmatch", … paths …, "manifest.enc"], "purge: git rm")?` followed by `git_run(... ["add", "manifest.enc"], "purge: git add")?` (manifest is staged separately because it was rewritten not removed) and `git_run(... ["commit", "-m", &msg], "purge: git commit")?`. Three invocations, fixed.
+  - `cmd_trash_empty` (post-split `main.rs:1885-1903`): same pattern over the loop of purgeables — accumulate all paths, then one `git rm`, one `git add manifest.enc`, one `git commit`. The commit message keeps `"trash empty: purged N item(s)"`.
+- **Tests:** existing `tests/basic_flows.rs::rm_restore_purge_cycle` covers the single-item purge contract. Add `tests/basic_flows.rs::trash_empty_batches_git_invocations` (or extend `tests/settings.rs`) — purge ≥3 items via `trash empty`, then assert via `git log --oneline --since=…` that exactly **one** new commit appeared (a strict invariant that catches accidental re-introduction of per-item commits). Synthetic fixtures only; no binary blobs.
+- **Effort:** S-M.
+- **Depends on:** Phases 1, 2, 4 (uses `git_run` and `after_manifest_change`).
+
+### Phase 7 — Migrate parsers to `relicario-core` + `pub(crate) mod base32`
+
+- **Goal:** close DEV-A's three-base32-implementations finding and DEV-B's parsers-in-CLI-only finding in one stroke. The CLI keeps thin wrappers (no caller-side import changes); core becomes the single source of truth.
+- **Changes:**
+  - Modified: `crates/relicario-core/src/time.rs` — adds `impl MonthYear { pub fn parse(s: &str) -> Result<Self, RelicarioError> { … } }` accepting `MM/YYYY`, `MM-YYYY`, and `MM/YY` (lifts the body of `parse_month_year` from `crates/relicario-cli/src/parse.rs`). Note: `MonthYear::new` currently returns `Result<_, &'static str>` (DEV-A P3); this phase has the option to either bring `new` to `RelicarioError` for consistency, or leave it and have `parse` call `new` and re-wrap. Recommendation: re-wrap only — the `new` migration is DEV-A's P3 to keep this plan focused.
+  - New: `crates/relicario-core/src/base32.rs` — `pub(crate) mod base32 { pub fn encode_rfc4648(bytes: &[u8]) -> String; pub fn decode_rfc4648_lenient(s: &str) -> Result<Vec<u8>, RelicarioError>; }`. Body lifted/unified from `crates/relicario-core/src/item.rs:255-275` (the encoder) and `crates/relicario-core/src/import_lastpass.rs:202-220` (the decoder), plus the lenient input handling (case-insensitive, padding-optional, whitespace-stripped) from `crates/relicario-cli/src/parse.rs`. Steam's `STEAM_ALPHABET` at `crates/relicario-core/src/item_types/totp.rs:13` stays put with a neighbour comment: `// not RFC 4648 — Steam Guard's de-ambiguated alphabet; see crate::base32 for the standard impl.`
+  - Modified: `crates/relicario-core/src/item.rs` — removes the inline `base32_encode` (lines 255-275); call sites switch to `crate::base32::encode_rfc4648`.
+  - Modified: `crates/relicario-core/src/import_lastpass.rs` — removes the inline `decode_base32_totp` (lines 202-220); call sites switch to `crate::base32::decode_rfc4648_lenient`.
+  - New: `crates/relicario-core/src/item_types/totp.rs` — adds `impl TotpConfig { pub fn parse_secret(s: &str) -> Result<Zeroizing<Vec<u8>>, RelicarioError> { Ok(Zeroizing::new(crate::base32::decode_rfc4648_lenient(s)?)) } }`. The `Zeroizing` wrap is the value-add over a raw base32 call.
+  - New: `crates/relicario-core/src/mime.rs` — `pub fn guess_for_extension(filename: &str) -> &'static str` (lifts `guess_mime` from CLI). Default `application/octet-stream`. The match is small enough that exhaustive enum tagging (PDF/PNG/JPEG/TXT/JSON) is overkill; keep the string-match shape.
+  - Modified: `crates/relicario-core/src/lib.rs` — re-exports `MonthYear` (already exported), `mime`, `base32` (`pub(crate)` only, not in the public API surface). `Totp::parse_secret` is reachable via `ItemCore::Totp(_).parse_secret(...)` already.
+  - Modified: `crates/relicario-cli/src/parse.rs` — becomes a thin shim re-exporting the new core API. `pub fn parse_month_year(s: &str) -> Result<MonthYear, RelicarioError> { MonthYear::parse(s) }` (so the existing CLI callsites need zero edits in this phase). Same for `base32_decode_lenient` and `guess_mime`. Once Plan C lands and consumers have all migrated, a follow-up plan can delete `parse.rs` entirely.
+  - Verification step: before phase 7, grep `grep -RIn "parse_month_year\|base32_decode_lenient\|guess_mime\|base32_encode\|decode_base32_totp" crates/ extension/` to confirm the only consumers are the CLI files about to be touched. The Cargo workspace currently has no other consumer.
+- **Tests:** move CLI's existing parser unit tests (if any) into `crates/relicario-core/src/`. Add: `MonthYear::parse` round-trip for `01/2026`, `12/30`, `12-2026`, plus error cases (`13/2026`, `01/1999`, `garbage`); `base32::encode_rfc4648`/`decode_rfc4648_lenient` round-trip on a known TOTP vector (the RFC 6238 test vector already lives in `item_types/totp.rs`); `mime::guess_for_extension` table — `pdf.PDF`, `image.jpg`, `image.jpeg`, `unknown.xyz`. Keep `tests/import_lastpass.rs` green (it'll go through the new shared decoder). Existing CLI integration tests at `crates/relicario-cli/tests/*` must still pass; the public CLI surface is unchanged.
+- **Effort:** M.
+- **Depends on:** Phase 1.
+
+### Phase 8 — WASM exports for the migrated parsers + wasm.d.ts mirror
+
+- **Goal:** make the new core parsers reachable from the extension via the SW. Deliver only the seam; Plan C wires the SW handlers.
+- **Changes:**
+  - Modified: `crates/relicario-wasm/src/lib.rs` — adds three `#[wasm_bindgen]` exports:
+    - `pub fn parse_month_year(s: &str) -> Result<JsValue, JsError>` returning the serialized `MonthYear` (`{ month, year }` plain object via the existing `Serializer::new().serialize_maps_as_objects(true)` pattern; reuse `js_value_for`).
+    - `pub fn base32_decode_lenient(s: &str) -> Result<Vec<u8>, JsError>` returning the decoded bytes as a `Uint8Array` on the JS side (wasm-bindgen converts `Vec<u8>` into a `Uint8Array` copy — same convention as `attachment_decrypt`).
+    - `pub fn guess_mime(filename: &str) -> String`.
+  - Modified: `extension/src/wasm.d.ts` — adds the three matching declarations under the existing `declare module 'relicario-wasm'` block. Per DEV-C's boundary note, this file is hand-maintained; this commit must update both files together. Suggested placement: directly after `extract_image_secret`/`embed_image_secret` (line ~60), grouped under a `// Pure parsers (no session needed)` comment so the extension-side reader sees they require no `SessionHandle`.
+  - Naming convention call-out: phase 8 keeps **snake_case** JS names (consistent with every existing export, e.g. `manifest_encrypt`, `extract_image_secret`). The snake_case → camelCase decision (DEV-B/DEV-C P3) is **explicitly deferred to a separate plan**; introducing camelCase only for the three new exports would create a worst-of-both-worlds inconsistency.
+- **Tests:** add `wasm-bindgen-test` cases (or extend the existing `session_tests` mod at `crates/relicario-wasm/src/lib.rs:522-591`) covering the three new exports — at minimum, a round-trip for `base32_decode_lenient` against a known input, an error case for `parse_month_year("not-a-date")`, and a `guess_mime("doc.pdf") == "application/pdf"` smoke. Confirm `cargo build -p relicario-wasm --target wasm32-unknown-unknown` is clean.
+- **Cross-boundary cite:** **after Phase 8 ships, Plan C can wire SW message handlers** for `parse_month_year`, `base32_decode_lenient`, and `guess_mime` (e.g. messages `parse_month_year`, `decode_totp_secret`, `guess_attachment_mime` in `extension/src/shared/messages.ts`, dispatched by `extension/src/service-worker/router/popup-only.ts`). This plan does **not** design those handlers; phase 8 only delivers the WASM seam Plan C consumes. Coordinate the wasm.d.ts update commit with Plan C so both crates' callers see the new surface in the same merge.
+- **Effort:** S.
+- **Depends on:** Phase 7.
+
+## Risks and mitigations
+
+- **Mechanical splits drift if a function calls a sibling that moved.** Mitigation: `cargo check -p relicario-cli` between every sub-step of phase 1 (i.e. between every file-extraction); explicit `pub(crate)` discipline so the compiler enforces visibility. The integration tests at `crates/relicario-cli/tests/*` are the regression budget — they exercise the binary surface, not internal modules, so a pure relocation cannot break them silently.
+- **`helpers::git_run` semantic change: switching from `.status()` (inherited stderr to TTY) to `.output()` (captured) means interactive flows lose live stderr streaming.** A user who runs `relicario sync` in a terminal sees git's progress today; with `git_run` they see only the captured chunk on failure. Mitigation options: (a) `git_run` could keep `inherit` semantics by detecting `stderr.is_terminal()` and switching strategy; (b) accept the trade — captured-and-printed-on-failure is uniformly better for the CI/test/scripted-tooling case which is the failure-mode that matters. Recommendation: option (b) for phase 2, with a follow-up TODO if the live-streaming loss is reported. Keep `git_command` available for the rare site that needs a manual `Command` (pipe/stdin/etc.) so neither contract has to be perfect.
+- **`Vault::after_manifest_change` adds a method to the session module; risk that callers forget to use the wrapper.** Mitigation: in phase 4, mark `save_manifest` as `pub(crate)` (or rename to `save_manifest_raw`) so all `commands/*` files are forced through `after_manifest_change`. The clap dispatcher calls only `cmd_*` functions, none of which need the raw method.
+- **`ParamsFile` migration is on-disk-format-sensitive.** A change in the `Serialize` derive's field order or a missed `Deserialize` field tolerance would break existing vaults. Mitigation: phase 5's test round-trip reads a `params.json` written by the current code (committed as a fixture *string literal* in the test, not a binary blob) and confirms the new code parses it identically. Field names match exactly (`format_version`, `kdf`, `aead`, `salt_path`); the existing `read_params` only reads `kdf`, so adding tolerance for the other fields is the natural step.
+- **Parser migration to core changes the public API surface of `relicario-core`.** Any in-flight work consuming the old CLI helpers must adapt. Mitigation: the grep step at the top of phase 7 confirms zero non-CLI consumers exist today; the CLI's `parse.rs` shim keeps callsites unchanged through phases 1–6, so this is a one-pass migration with no follow-up required from other plans. The Steam alphabet stays untouched (intentional non-RFC-4648 alphabet) with a neighbour comment.
+- **WASM export rename / addition could break the extension at the `wasm.d.ts` boundary.** Per DEV-C's boundary notes, `extension/src/wasm.d.ts` is hand-maintained; every change to `crates/relicario-wasm/src/lib.rs`'s `#[wasm_bindgen]` surface must be mirrored manually. Mitigation: phase 8 updates both files in the same commit; a future CI guard (DEV-C's WASM P2 — comparing wasm-pack–generated `.d.ts` against the hand-maintained one) is out of scope here but would close this hole permanently. The boundary notes also flag the BigInt typing care that `attachment_encrypt` already requires (DEV-B item 3 in DEV-C's boundary notes); the three new exports take only `&str` and return primitives, so they avoid that class of footgun.
+- **Cross-plan coupling.** Phase 8 lands a wasm.d.ts change; Plan C will land SW handlers consuming it. If the merge order interleaves — e.g. Plan C ships its handler stub before phase 8 lands the WASM export — the extension build breaks. Mitigation: phase 8 ships first; Plan C's SW-handler phase explicitly depends on phase 8's WASM exports (cite this seam in Plan C). The user's release-train coordination is the enforcement mechanism.
+
+## Out of scope
+
+- **Plan A** (security/docs polish) and **Plan C** (extension restructure) entirely.
+- **All CLI P3 nits** that DEV-B enumerates: `let _ = entry;` pattern (`main.rs:1170, 1407, 1426, 1469, 1913, 2030`); `Lock` subcommand visibility; `Display` for `ItemType` (the `format!("{:?}", e.r#type)` site at `main.rs:1158`); `helpers::relicario_dir` adoption sweep; `gitea::GiteaClient` per-call construction; scripted-prompt test layer for `tests/edit_and_history.rs`; dead `blob_path` variable in `tests/attachments.rs:69-76`; the three-test-env-var macro consolidation; `cmd_recovery_qr_unwrap` empty-input check; `cmd_recovery_qr_generate` stdout/stderr split; the Task-12 `cmd_backup_export` cleanup. Each is a one-line edit appropriate for a follow-up sweep, not for this M-L plan.
+- **Server findings** (P2/P3 in DEV-B's relicario-server section): `generate-hook` `$PATH`, bootstrap-branch tightening, `verify-commit --from-stdin`, server test coverage gaps. These belong in a server-focused plan.
+- **WASM findings beyond the parser exports needed for P1.10**: DEV-B's WASM P2 list (`need_key`/`with(...).unwrap()` double-lookup, `Vec<u8>` getter clones, `wasm_*_recovery_qr` rename, `device.rs`/`session.rs` concurrency-primitive split). Not in this plan.
+- **The 8 "Open architectural decisions"** in the synthesis appendix.
+- **WASM JS-naming** (snake_case → camelCase) — defer to a separate plan, as called out in phase 8.
+- **In-flight uncommitted v0.5.x work** (`extension/src/vault/vault.ts`, `vault.css`, `glyphs.ts`, manifest version bumps, relay `queue.ts`/`server.ts`/`start.sh`). Treat as in-flight; this plan touches none of them.
+
+## Done criteria
+
+A reviewer can confirm Plan B has shipped by checking, in order:
+
+- [ ] `crates/relicario-cli/src/main.rs` is ≤ 500 LOC and contains only the clap surface, the dispatch `match`, and the `mod` declarations + `test_*_override` shims.
+- [ ] The `crates/relicario-cli/src/commands/` directory contains the 17 files listed in the post-split tree, each owning exactly one top-level subcommand or a tightly-scoped helper.
+- [ ] `crates/relicario-cli/src/prompt.rs` and `crates/relicario-cli/src/parse.rs` exist, with the 6 prompt helpers and the 3 parser shims respectively.
+- [ ] `cargo test --workspace` passes (CLI integration tests, core unit tests, server tests, wasm `wasm-bindgen-test`s).
+- [ ] `cargo clippy --workspace` is silent.
+- [ ] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` is clean.
+- [ ] The 16 `bail!("git X failed")` sites listed in P1.3 (and any others surfaced by grep) are now `git_run(repo, args, "<context>")?` one-liners. `grep -n 'bail!("git ' crates/relicario-cli/src/` returns zero matches.
+- [ ] The 7 `refresh_groups_cache` callsites all collapse to `vault.after_manifest_change(&manifest)?`. `grep -n 'refresh_groups_cache' crates/relicario-cli/src/` returns zero matches outside `session.rs`.
+- [ ] One canonical `ParamsFile` definition in `crates/relicario-cli/src/session.rs`. `grep -n 'struct ParamsFile' crates/relicario-cli/src/` returns one match.
+- [ ] A 50-item `relicario trash empty` produces exactly **one** new git commit (verified by `git log --oneline` in the test); a single-item `relicario purge` produces exactly one commit. Per-purge git invocations: 3 (rm + add manifest + commit), down from 3-per-item.
+- [ ] `MonthYear::parse`, `Totp::parse_secret`, `mime::guess_for_extension` exist in `relicario-core`. `crates/relicario-core/src/base32.rs` is `pub(crate)` and is the only RFC-4648 implementation in the crate (Steam alphabet at `item_types/totp.rs:13` stays, with a neighbour comment).
+- [ ] `crates/relicario-wasm/src/lib.rs` exports `parse_month_year`, `base32_decode_lenient`, `guess_mime`. `extension/src/wasm.d.ts` mirrors the three declarations.
+- [ ] All existing CLI integration tests at `crates/relicario-cli/tests/*` still pass without modification (regression budget held).

docs/superpowers/specs/2026-05-04-extension-restructure-design.md

@@ -0,0 +1,368 @@
+# Extension Restructure — Design
+
+**Date:** 2026-05-04
+**Status:** Proposed
+**Source:** docs/superpowers/reviews/2026-05-04-architecture-review.md (P1.4, P1.5, P1.6, P1.9) + folded P2s from DEV-C's extension sections + the `relicario status` parity gap
+**Effort estimate:** L
+
+## Summary
+
+This is the largest of the three architecture-review followups — multi-day to multi-week — and it eliminates the two steepest learning cliffs in the extension. After this plan ships, a tinkerer who opens `extension/src/setup/setup.ts` no longer sees WASM imported directly (it isn't the pattern; it was the exception); a tinkerer who opens `extension/src/vault/vault.ts` sees ~200 LOC of routing and state instead of 1027 LOC of shell + sidebar + list + drawer + form-wrapper inlined together; the `shared/state.ts` bridge between popup and vault tab becomes type-checked end to end; and the duplicated service-worker router helpers consolidate into one home each. As a side effect, the extension closes its last CLI-parity gap (`relicario status` → vault-sidebar status indicator).
+
+## Findings addressed
+
+- **P1.4** (DEV-C; `extension/src/setup/setup.ts:28-37`, `:1118-1120`, whole 1220-LOC file) — setup wizard imports `relicario-wasm` directly and orchestrates `unlock` / `embed_image_secret` / `register_device` / `manifest_encrypt` itself, bypassing the SW abstraction every other surface uses; ~400 LOC of crypto orchestration duplicated.
+- **P1.5** (DEV-C; `extension/src/vault/vault.ts:1-1027`) — single 1027-LOC file owns shell + hash routing + sidebar + list + drawer + type-picker + form-wrapper + deep-link routing + teardown. Contains the `vault_locked` RPC intercept (lines 47-74) and the drawer-state leak (lines 495-536, 648-695).
+- **P1.6** (DEV-C; `extension/src/shared/state.ts:10-35`) — `StateHost` contract is fully `any`-typed; `host` singleton has no double-registration guard.
+- **P1.9** (DEV-C; `extension/src/service-worker/router/popup-only.ts:687-703`, `:~169`; `extension/src/service-worker/router/content-callable.ts:187-205`, `:~169`) — `loadDeviceSettings`, `loadBlacklist`, `saveBlacklist`, and `itemToManifestEntry` duplicated across both router files.
+- **P2 — inactivity-timer reset on content-callable messages** (DEV-C; `extension/src/service-worker/index.ts:76-78`) — active autofiller never opens popup, gets force-locked despite continuous use.
+- **P2 — `state.gitHost` clear on session expiry** (DEV-C; `extension/src/service-worker/index.ts:51-58`) — expiry callback clears manifest but leaves the cached git-host client.
+- **P2 — duplicated teardown helpers** (DEV-C; `extension/src/popup/components/settings.ts:56-65` and `settings-vault.ts:15-22`) — two near-identical cleanup paths in a regression class with known prior leaks.
+- **P2 — `Promise.all` without per-promise error handling** (DEV-C; `extension/src/popup/components/devices.ts:47-50`, `trash.ts:39-46`) — single rejected RPC fails the whole render.
+- **P2 — MutationObserver `scan()` not debounced** (DEV-C; `extension/src/content/detector.ts:96-103`) — SPA churn re-runs the full scan many times per second.
+- **CLI/extension parity gap — no equivalent to `relicario status`** (DEV-C parity table; PM kickoff) — extension surfaces nothing comparable to ahead/behind/lastSyncAt/pendingItems.
+
+## Approach
+
+Architectural shape: **types first, then extract, then split**. The extension already has a clean message-router/SW boundary; this plan finishes the job for the three surfaces that don't yet honor it (state.ts, setup.ts, vault.ts) and pulls duplicated SW helpers into one home.
+
+### Post-split `extension/src/vault/`
+
+```
+extension/src/vault/
+├── vault.html                  (unchanged)
+├── vault.css                   (unchanged)
+├── vault.ts                    (~200 LOC; routing + state only — owns
+│                                hash parsing, RouterState, render() entry,
+│                                imports the modules below)
+├── vault-shell.ts              (DOM scaffolding, color-scheme apply,
+│                                onMessage wiring, applyShellViewClass)
+├── vault-sidebar.ts            (renderSidebarCategories, search input
+│                                wiring with 50-100ms debounce, nav buttons,
+│                                global keydown shortcuts)
+├── vault-list.ts               (renderListPane, row rendering, type icons)
+├── vault-drawer.ts             (openDrawer/closeDrawer, renderDrawer,
+│                                drawer field grid, drawer event wiring;
+│                                state.drawerOpen reset is owned here)
+├── vault-form-wrapper.ts       (renderFormWrapped, sticky bar, header;
+│                                __test__ export migrates with it)
+├── vault-status.ts             (NEW — renders the get_vault_status indicator
+│                                in the sidebar; phase 6)
+└── components/
+    ├── backup-panel.ts         (unchanged)
+    └── import-panel.ts         (unchanged)
+```
+
+Rationale: each module owns one concern that has its own teardown, its own DOM rectangle, and its own subset of `RouterState`. Adding a new pane view today is a 5-place edit (`teardownPaneComponents` lines 813-820 is the symptom DEV-C flagged); after the split, it is one new module + one entry in `vault.ts`'s render switch. The `vault_locked` RPC intercept at lines 47-74 lifts out entirely (see `shared/state.ts` below).
+
+### Post-split `extension/src/service-worker/`
+
+```
+extension/src/service-worker/
+├── index.ts                    (entry point — onMessage, initWasm,
+│                                inactivity-timer wiring; phase 5 touches
+│                                the content-callable timer-reset rule
+│                                and the gitHost clear-on-expiry)
+├── session.ts                  (unchanged in scope; Plan A removes the
+│                                try{free()} swallow at :26)
+├── session-timer.ts            (unchanged; phase 5 documents the
+│                                exclusion list inline)
+├── storage.ts                  (NEW — phase 2: loadDeviceSettings,
+│                                loadBlacklist, saveBlacklist, plus the
+│                                config + image-base64 + setup-state loaders
+│                                if natural; both router files import here)
+├── vault.ts                    (gains: itemToManifestEntry (moved from
+│                                both routers; phase 2), create_vault and
+│                                attach_vault handlers (phase 3), and the
+│                                get_vault_status handler (phase 6))
+├── git-host.ts                 (unchanged)
+├── github.ts / gitea.ts        (unchanged)
+├── devices.ts                  (unchanged)
+└── router/
+    ├── index.ts                (unchanged)
+    ├── popup-only.ts           (imports from ../storage and ../vault;
+                                  duplicated definitions deleted)
+    └── content-callable.ts     (imports from ../storage and ../vault;
+                                  duplicated definitions deleted)
+```
+
+Rationale: `service-worker/storage.ts` becomes the single source for `chrome.storage.local` reads/writes the SW does. `service-worker/vault.ts` already owns vault-tier WASM orchestration, so `itemToManifestEntry`, `create_vault`, `attach_vault`, and `get_vault_status` all belong there.
+
+### `StateHost` interface contract (P1.6)
+
+```ts
+// extension/src/shared/state.ts (post-rewrite)
+import type { Request, Response } from './messages';
+import type { PopupState, View } from '../popup/popup';
+
+export interface StateHost {
+  getState(): PopupState;
+  setState(partial: Partial<PopupState>): void;
+  navigate(view: View, extras?: Partial<PopupState>): void;
+  sendMessage(request: Request): Promise<Response>;
+  escapeHtml(s: string): string;
+  popOutToTab(): void;
+  isInTab(): boolean;
+  openVaultTab(hash?: string): void;
+}
+
+let host: StateHost | null = null;
+
+export function registerHost(h: StateHost): void {
+  if (host) throw new Error('state host already registered');
+  host = h;
+}
+
+/** Test-only — vitest beforeEach() calls this to break inter-test leakage. */
+export function __resetHostForTests(): void { host = null; }
+
+export function getState(): PopupState {
+  if (!host) throw new Error('No state host registered');
+  return host.getState();
+}
+
+export function setState<K extends keyof PopupState>(
+  partial: Pick<PopupState, K> | Partial<PopupState>,
+): void {
+  if (!host) throw new Error('No state host registered');
+  host.setState(partial);
+}
+
+// navigate / sendMessage / escapeHtml / popOutToTab / isInTab / openVaultTab
+// keep their generic-friendly signatures (View, Request, Response).
+//
+// vault_locked unification: shared/state.ts wraps sendMessage so a
+// `{ ok: false, error: 'vault_locked' }` response (for any request other
+// than is_unlocked / unlock) flips host state to locked + dispatches a
+// `session_expired`-equivalent event the popup also listens for.
+// Both popup.ts and vault.ts consume from this single channel — the
+// vault.ts:47-74 RPC intercept is removed in phase 4.
+```
+
+Note `View` and `PopupState` are currently defined in `extension/src/popup/popup.ts`. To avoid a popup→shared circular import, they migrate to `extension/src/shared/types.ts` (or `extension/src/shared/popup-state.ts`) before `state.ts` re-imports them. This migration is part of phase 1.
+
+### Setup wizard step-registry shape (P1.4)
+
+```ts
+// extension/src/setup/setup.ts (post-rewrite)
+interface StepContext {
+  state: WizardState;
+  rerender: () => void;
+  goto: (id: StepId) => void;
+}
+
+interface SetupStep {
+  id: StepId;
+  /** Pure render — returns innerHTML for #setup-step-host. */
+  render: (ctx: StepContext) => string;
+  /** Wire DOM events; return a teardown the wizard runs on step change. */
+  attach: (root: HTMLElement, ctx: StepContext) => () => void;
+}
+
+type StepId = 'mode' | 'host' | 'connection' | 'vault' | 'device' | 'done';
+
+const STEPS: ReadonlyArray<SetupStep> = [
+  modeStep, hostStep, connectionStep, vaultStep, deviceStep, doneStep,
+];
+
+/** Cleared on `beforeunload` and on `goto('mode')`. */
+function clearWizardState(): void {
+  // Best-effort wipe: zero-fill Uint8Arrays before drop where reachable;
+  // null out passphrase + token strings (JS strings are GC-only — see Risks).
+  if (state.carrierImageBytes) state.carrierImageBytes.fill(0);
+  if (state.referenceImageBytes) state.referenceImageBytes.fill(0);
+  if (state.referenceImageBytesAttach) state.referenceImageBytesAttach.fill(0);
+  // Reset every field of `state` to its initial value.
+  // NOTE: setup no longer holds a SessionHandle (the SW does); the
+  // phase 1 sweep deletes `verifiedHandle` from WizardState entirely.
+}
+```
+
+`setup.ts` no longer imports `relicario-wasm` and no longer touches `wasm.lock` / `.free()`. The two new SW handlers do that work (see Plan A coordination below).
+
+The 1220 LOC drops to ~500: the ~400 LOC of crypto orchestration (image-secret extract / embed, KDF gating, manifest_encrypt, attachment_encrypt) moves to the SW; the remaining UI logic compresses by ~300 LOC because the step-registry pattern collapses the six `renderStepN` / `attachStepN` pairs into six `SetupStep` objects.
+
+### New SW message handlers
+
+Added to `extension/src/shared/messages.ts`:
+
+```ts
+| { type: 'create_vault'; config: VaultConfig; passphrase: string;
+    carrierImageBytes: ArrayBuffer; deviceName: string }
+| { type: 'attach_vault'; config: VaultConfig; passphrase: string;
+    referenceImageBytes: ArrayBuffer; deviceName: string }
+| { type: 'get_vault_status' }
+```
+
+Both `create_vault` and `attach_vault` are added to `POPUP_ONLY_TYPES`. `get_vault_status` joins the same set. Response shapes:
+
+```ts
+export interface CreateVaultResponse extends Extract<Response, { ok: true }> {
+  data: { referenceImageBytes: Uint8Array; deviceName: string;
+          recoveryQrAvailable: true };
+}
+export interface AttachVaultResponse extends Extract<Response, { ok: true }> {
+  data: { deviceName: string };
+}
+export interface GetVaultStatusResponse extends Extract<Response, { ok: true }> {
+  data: { ahead: number; behind: number; lastSyncAt: number | null;
+          pendingItems: number };
+}
+```
+
+The SW handlers live in `service-worker/vault.ts`. `create_vault` and `attach_vault` hold their own internal session reference for the duration of the operation — they do not depend on the user-facing inactivity timer (see Risks).
+
+## Implementation phases
+
+Each phase keeps the existing vitest test suite green throughout. Regression budget per phase: **zero** test failures introduced; new tests added per phase (synthetic fixtures only, no binary blobs — `make_test_jpeg` style equivalents on the JS side).
+
+### Phase 1 — `StateHost` typing + `__resetHostForTests` (P1.6)
+
+- **Goal:** Make `extension/src/shared/state.ts` type-checked end to end so phases 3 and 4 can refactor against a real contract.
+- **Changes:**
+  - Move `View` and `PopupState` from `extension/src/popup/popup.ts` to `extension/src/shared/types.ts` (or new `extension/src/shared/popup-state.ts`).
+  - Rewrite `extension/src/shared/state.ts` to the snippet in **Approach**: typed `StateHost`, generic `getState`/`setState`, double-registration throw, `__resetHostForTests` export. No `any` in the public surface.
+  - Sweep all callers of `getState()` / `setState()` / `navigate()`. Existing `as any` casts surface as TS errors and get fixed (typed access where the field is known; an explicit narrowing where it isn't).
+  - The `vault_locked` channel collapse is **not** in this phase — the wrapper around `sendMessage` lands here as a no-op signature change; its body (the RPC intercept) lifts in phase 4.
+- **Tests:**
+  - New `extension/src/shared/__tests__/state.test.ts` covering: register-then-getState round-trip; double-register throws; `__resetHostForTests` clears the singleton; `getState()` without a registered host throws.
+  - Adjust any existing test that accidentally relied on a leaked host (none expected; the existing suites already register-then-tear-down per-test).
+- **Effort:** S-M
+- **Depends on:** none
+
+### Phase 2 — Extract `service-worker/storage.ts` + move `itemToManifestEntry` (P1.9)
+
+- **Goal:** Eliminate the duplicated SW helpers so blacklist mutations and manifest-projection refactors happen in one place.
+- **Changes:**
+  - Create `extension/src/service-worker/storage.ts` exporting `loadDeviceSettings`, `saveDeviceSettings`, `loadBlacklist`, `saveBlacklist`. Migrate the bodies from `extension/src/service-worker/router/popup-only.ts:687-703` (and `saveDeviceSettings` from the same file) and delete the `loadDeviceSettings` / `loadBlacklist` / `saveBlacklist` definitions in `extension/src/service-worker/router/content-callable.ts:187-205`.
+  - Move `itemToManifestEntry` from both router files (`popup-only.ts:707` and `content-callable.ts:169`) into `extension/src/service-worker/vault.ts` as a named export. Both routers import it from there.
+  - Optionally also fold `loadConfig` / `loadImageBase64` / `loadSetupState` into `storage.ts` since they're chrome.storage.local readers; keep the boundary clean.
+- **Tests:**
+  - New `extension/src/service-worker/__tests__/storage.test.ts` covering load/save round-trips for each helper, default-value fallback when the key is absent.
+  - The existing `extension/src/service-worker/router/__tests__/router.test.ts` keeps passing; the dispatch behavior is unchanged.
+- **Effort:** S
+- **Depends on:** none (independent of phase 1; can ship parallel)
+
+### Phase 3 — Setup wizard SW migration + step registry (P1.4)
+
+- **Goal:** Setup wizard becomes UI-only. SW owns `create_vault` and `attach_vault` end to end. Wizard restructures to a step-registry pattern. Sensitive material clears on abandon.
+- **Changes:**
+  - Add `create_vault` and `attach_vault` types to `extension/src/shared/messages.ts` (request union, response interfaces, capability set).
+  - Implement handlers in `extension/src/service-worker/vault.ts`. Each handler:
+    1. Computes salt + params, calls `unlock` (create) or verifies (attach), calls `embed_image_secret` / `extract_image_secret`, calls `register_device`, calls `manifest_encrypt` for the empty manifest, writes the resulting bytes to the configured remote via the existing `git-host` abstraction.
+    2. Holds its own `SessionHandle` for the duration. On success, transitions the SW into the unlocked state (replaces the popup-driven `unlock` path's outcome); on failure, calls `wasm.lock(handle)` then `.free()` (see Plan A coordination).
+    3. Returns the reference image bytes (`create_vault`) or just the device name (`attach_vault`) so the wizard's "Done" step can offer a download.
+  - Rewrite `extension/src/setup/setup.ts`:
+    - Delete the WASM dynamic-import block at lines 28-37; delete the `loadWasm()` helper; delete the `wasm` module variable; delete `verifiedHandle` from `WizardState`.
+    - Convert each of the six `renderStepN` / `attachStepN` pairs into a `SetupStep` object (`modeStep`, `hostStep`, `connectionStep`, `vaultStep`, `deviceStep`, `doneStep`) per the step-registry snippet in **Approach**. The wizard's render loop becomes `STEPS[state.step].render(ctx)` + `STEPS[state.step].attach(root, ctx)`.
+    - Replace direct WASM orchestration in the vault step with `sendMessage({ type: 'create_vault', ... })` / `sendMessage({ type: 'attach_vault', ... })`.
+    - Add `clearWizardState()` per the snippet; bind to `window.addEventListener('beforeunload', clearWizardState)` and call from the `goto('mode')` path.
+  - Update `extension/src/wasm.d.ts` only if the new SW handlers need a WASM entry point that isn't already declared (verify by reading `extension/src/service-worker/vault.ts` — they likely don't, since `unlock`/`embed_image_secret`/`register_device`/`manifest_encrypt` are already declared; the SW just orchestrates them). If no new WASM entry, this file is **not touched** by Plan C.
+  - The `recovery_qr_generated_at` direct chrome.storage.local write at `setup.ts:1056-1062` is **out of scope** per the kickoff (defer to a P3 cleanup) — it stays as-is in this phase.
+- **Tests:**
+  - Update `extension/src/setup/__tests__/setup.test.ts` to assert on the step registry shape (each `SetupStep.id`, `render` returns non-empty HTML, `attach` returns a callable teardown).
+  - New SW-side test in `extension/src/service-worker/__tests__/vault.test.ts` (or extend an existing one) covering `create_vault` happy path with a stubbed `git-host` and the WASM stub from `__stubs__/relicario_wasm.stub.ts` (round out the stub for `embed_image_secret`, `register_device`, `manifest_encrypt` if they aren't there yet — DEV-C P2 noted only 7 of ~25 are stubbed).
+  - New test for `clearWizardState`: simulate `beforeunload`, assert `Uint8Array` contents are zero-filled.
+- **Effort:** L
+- **Depends on:** Phase 1 (the wizard's UI uses `getState`/`setState` against a typed `StateHost`)
+
+### Phase 4 — Split `vault.ts` + lift `vault_locked` channel (P1.5)
+
+- **Goal:** `extension/src/vault/vault.ts` shrinks to ~200 LOC of routing + state. Each pane concern lives in its own module. The `vault_locked` RPC intercept disappears from vault.ts and runs in `shared/state.ts` instead.
+- **Changes:**
+  - Create the five new files (`vault-shell.ts`, `vault-sidebar.ts`, `vault-list.ts`, `vault-drawer.ts`, `vault-form-wrapper.ts`) per the directory tree in **Approach**. Migrate the corresponding code blocks from the existing `vault.ts` into them. Each module exports a `render*` function plus, where stateful, an explicit `teardown()`.
+  - In `vault.ts`, retain only: `RouterState` declaration, hash parsing (`parseHash`, `setHash`), `loadManifest`, the `render()` entry point, the `renderPane()` switch, and the imports that wire the modules together.
+  - In `vault-drawer.ts`: include an `ensureDrawerClosedForRoute(route)` helper that the `renderPane` switch calls before any non-list view. This implements the P2 fix for `vault.ts:495-536` (drawer state no longer leaks across navigation).
+  - In `vault-sidebar.ts`: wrap the search input handler in a 50-100ms debounce (DEV-C P2 — `vault.ts:648-695`).
+  - Lift the `vault_locked` RPC intercept (`vault.ts:47-74`) into the `sendMessage` wrapper in `extension/src/shared/state.ts` (the wrapper signature landed in phase 1; phase 4 fills the body). Both popup and vault now consume the same `session_expired`-equivalent flow. **Migration discipline:** keep both signals firing for one merge cycle (the SW continues to dispatch `session_expired` and the wrapper still fires the intercept) until both surfaces have been verified as consuming from `shared/state.ts`; then collapse.
+- **Tests:**
+  - Existing `extension/src/vault/__tests__/form-wrapper.test.ts` and `sidebar-glyphs.test.ts` continue to pass (the symbols they import move from `vault.ts` to `vault-form-wrapper.ts` / `vault-sidebar.ts`; update import paths).
+  - New `extension/src/vault/__tests__/drawer-state.test.ts` covering: drawer auto-closes when navigating from list to trash/devices/settings.
+  - New `extension/src/shared/__tests__/state-vault-locked.test.ts` covering: a `{ ok: false, error: 'vault_locked' }` response (for a request other than `is_unlocked`/`unlock`) flips host state to locked.
+- **Effort:** M
+- **Depends on:** Phase 1 (uses the typed `StateHost` surface and the `sendMessage` wrapper)
+
+### Phase 5 — Extension P2 cluster
+
+- **Goal:** Sweep five small extension P2s that share the same "small fix, real correctness win" shape.
+- **Changes:**
+  - **Inactivity timer reset on content-callable messages** (`extension/src/service-worker/index.ts:76-78`): invert the current condition. Reset on **all** messages except a small documented exclusion set (`get_autofill_candidates` is the only known read-only content call). Define `READ_ONLY_CONTENT_CALLABLE` in `service-worker/session-timer.ts` with a doc comment listing each excluded type and the rationale; `index.ts` consults that set.
+  - **`state.gitHost` clear on session expiry** (`extension/src/service-worker/index.ts:51-58`): in the `sessionTimer.onExpired` callback, also set `state.gitHost = null`. The initializer rebuilds it on demand.
+  - **Teardown helper extraction** (`extension/src/popup/components/settings.ts:56-65` and `settings-vault.ts:15-22`): extract `teardownSettingsCommon()` exported from `settings.ts` (or a new `settings-shared.ts`); both `settings.ts:teardownSettings` and `settings-vault.ts:teardown` call it. Single source for the closeGeneratorPanel + activeKeyHandler removal pattern.
+  - **`Promise.allSettled` in devices/trash** (`extension/src/popup/components/devices.ts:47-50`, `trash.ts:39-46`): swap `Promise.all` for `Promise.allSettled`; render each settled response defensively (`.status === 'fulfilled' && r.value.ok`); fall back to "couldn't load" copy per failed slot.
+  - **MutationObserver debounce** (`extension/src/content/detector.ts:96-103`): wrap the existing `() => scan()` callback in a 200ms trailing-edge debounce (or `requestIdleCallback` if available; `setTimeout(..., 200)` fallback). Reset on every observer fire.
+- **Tests:**
+  - Existing `extension/src/service-worker/__tests__/session-timer.test.ts` extended with a "popup-only message resets, content-callable message does not reset (except listed exclusions)" case.
+  - Existing `extension/src/popup/components/__tests__/devices.test.ts` and `trash.test.ts` extended with a "one RPC fails, the other still renders" case.
+  - Existing `extension/src/popup/components/__tests__/settings.test.ts` and `settings-vault.test.ts` extended to confirm both call paths invoke `teardownSettingsCommon`.
+- **Effort:** M
+- **Depends on:** none (all five are independent of phases 1-4)
+
+### Phase 6 — `get_vault_status` SW message + vault-sidebar status indicator
+
+- **Goal:** Close the last CLI/extension parity gap (`relicario status` ↔ extension status indicator).
+- **Changes:**
+  - Add `{ type: 'get_vault_status' }` to `extension/src/shared/messages.ts` and to `POPUP_ONLY_TYPES`. Add `GetVaultStatusResponse` per the **Approach** snippet.
+  - Implement the handler in `extension/src/service-worker/vault.ts`. It returns `{ ahead, behind, lastSyncAt, pendingItems }` from cached state on `state.gitHost` (no actual sync). A "last sync" timestamp is recorded in `service-worker/index.ts` (or `state.gitHost`) on each successful `sync` handler return.
+  - Create `extension/src/vault/vault-status.ts` rendering a small indicator in the sidebar footer: glyph + "in sync" / "N ahead" / "N pending" / "last sync 2m ago". Polls on sidebar mount and on a manual refresh button (NOT every render — see Risks).
+- **Tests:**
+  - New `extension/src/service-worker/__tests__/vault-status.test.ts` covering the four state combinations and the no-sync invariant (handler does not touch the network).
+  - New `extension/src/vault/__tests__/status-indicator.test.ts` for the renderer.
+- **Effort:** S-M
+- **Depends on:** Phase 4 (the indicator lives inside the new `vault-sidebar.ts` boundary)
+
+### Future / deferred (Plan B coordination)
+
+Plan B (CLI restructure) migrates `parse_month_year`, `base32_decode_lenient`, and `guess_mime` from the CLI into `relicario-core`, then re-exports them through `relicario-wasm`. Once those WASM exports land, the extension can consume them via new SW message handlers (e.g. `parse_month_year`, `decode_totp_secret`, `guess_mime_for_filename`) — this is a natural follow-up and explicitly **deferred to a future plan**. The seam to consume them is `extension/src/service-worker/vault.ts` (or a new `service-worker/parse.ts`) plus a new entry in `extension/src/wasm.d.ts`. Plan C does **not** design those handlers in detail.
+
+## Risks and mitigations
+
+- **State.ts typing changes ripple.** Every consumer of `getState`/`setState` becomes type-checked; existing `as any` casts will surface as TS errors. *Mitigation:* phase 1 includes a sweep + targeted TS error fix as part of the phase, not as a follow-up. Run `tsc --noEmit` per file class to triage; expect ~15-30 errors clustered in `popup/components/*.ts` and `vault/*.ts`.
+- **Setup-via-SW migration changes the crypto state machine.** Today setup orchestrates WASM directly; after phase 3, the SW owns vault creation. If the SW's user-facing inactivity timer fires mid-creation, the user could lose progress. *Mitigation:* design `create_vault` / `attach_vault` to be transactional from the SW's perspective — they hold their own internal session reference for the duration of the operation and do not consult or reset the user-facing inactivity timer until they return successfully. Document this contract in the handler header comments.
+- **`vault.ts` split + `vault_locked` channel unification.** The popup currently uses `session_expired` event; vault tab uses RPC intercept. Unifying onto one channel means popup behavior must continue to work after phase 4. *Mitigation:* keep both signals firing during phase 4 (the SW continues to dispatch `session_expired`; the new wrapper in `shared/state.ts` also fires the intercept); collapse only after both surfaces are verified to consume from `shared/state.ts` in the same merge cycle. Add a regression test asserting the popup's lock screen renders on `session_expired` and the vault tab's lock screen renders on the SW response intercept.
+- **`.free()` callsite policy.** Plan A (security/docs polish) handles the Rust-side `impl Drop for SessionHandle` and removes the `try { current.free() }` swallow at `extension/src/service-worker/session.ts:26`. Plan C does **not** redo that work, but wherever this refactor *moves* a `.free()` callsite — most notably during the phase 3 setup-to-SW migration where `setup.ts`'s `verifiedHandle` retires and the new `create_vault` / `attach_vault` handlers acquire their own handles — the new location must call `wasm.lock(handle)` first regardless of whether Plan A's Rust-side `impl Drop` lands. Cite Plan A as the source of the policy.
+- **WASM boundary coordination.** Plan B (CLI restructure) will touch `extension/src/wasm.d.ts` for the new parser exports (`parse_month_year`, `base32_decode_lenient`, `guess_mime`) once they land in `relicario-wasm`. Plan C should **not** touch `extension/src/wasm.d.ts` unless `create_vault` / `attach_vault` need WASM entry points that aren't already declared (verify by reading `service-worker/vault.ts`; the SW already orchestrates `unlock`/`embed_image_secret`/`register_device`/`manifest_encrypt`, so likely no new entries needed). If both plans must touch `wasm.d.ts`, sequence Plan B's edits first and rebase Plan C on top.
+- **`clearWizardState()` semantics.** Clearing on `beforeunload` is best-effort in browsers (the event can be skipped if the tab crashes or is killed). JS strings (passphrase, API token) are also GC-only — there is no `Zeroize` for them. *Mitigation:* explicit zero-fill of `Uint8Array` fields where possible (carrier image bytes, reference image bytes); document the best-effort contract in the function header comment; do not over-promise in user docs. The same caveat already applies to existing strings in `WizardState` today, so this is a maintenance of the existing contract, not a regression.
+- **`get_vault_status` design.** Needs to call into the git-host abstraction without triggering an actual sync. *Mitigation:* cache the last-sync state in `state.gitHost` (add `lastSyncAt: number | null`, `ahead: number`, `behind: number` fields populated by the existing `sync` handler) and have `get_vault_status` read those cached values; the sidebar indicator polls on mount + on a manual refresh button rather than on every render. Any UI element that wants live status calls `sync` explicitly.
+- **Phase ordering risk.** Phase 1 is the blocker — phases 3 and 4 both depend on the typed `StateHost`. If phase 1 takes longer than estimated, run phase 2 (independent) and phase 5 (independent) in parallel to avoid total stall.
+
+## Out of scope
+
+Plan C does NOT touch:
+
+- Anything in **Plan A** (security/docs polish): Rust `impl Drop for SessionHandle`, the `service-worker/session.ts:26` swallow removal, `.free()` callsite audit, `recovery_qr.rs` documentation, server hardening, env-var audit.
+- Anything in **Plan B** (CLI restructure): `cli/main.rs` split, git-shell error UX helper, `parse_month_year`/`base32_decode_lenient`/`guess_mime` migration to core (Plan C only consumes them, deferred to a future phase).
+- Extension P3s: form-header `isInTab()` redundancy, popup.ts `isInTab()` heuristic, item-form.ts `renderComingSoon` dead code, `types/login.ts` size, `vault.ts:18-26` backup-panel comment, capture/detector/fill username-finder dedup, capture submit-button hook scope, setup.ts passphrase-score `-1` sentinel, `setup.ts:1056-1062` chrome.storage bypass, `setup.ts:1-7` "5-step" header comment, glyphs.ts partial adoption, `types.ts` `TotpKind` flat-union refactor, `totp-tools.ts:39-46` swallowed rejections, generator-panel cleanup idempotence guard, `item-list.ts` popover listener reuse path, popup `popup.ts:178-181` unconditional teardowns.
+- Other CLI/extension parity items: per-attachment `delete_attachment` SW message (P3), `list --tag` filter doc note (P3) — only `get_vault_status` is in scope.
+- Cross-cutting items not explicitly listed: `chrome.storage.local` direct reads outside the setup migration (e.g. `settings-security.ts:112-113`), `bun test` runner doc note, manifest version sync.
+- The full P2/P3 tail outside the items folded above.
+- The 8 "Open architectural decisions" from the synthesis appendix.
+- WASM JS-naming snake_case → camelCase decision (defer to a separate plan).
+- Anything touching the in-flight uncommitted v0.5.x work (vault.ts +151/-99, vault.css +238/-99, manifest version, glyphs additions). Plan C executes against committed `main` post-061facd.
+
+## Done criteria
+
+A reviewer confirms the plan shipped by checking each item:
+
+- [ ] `extension/src/shared/state.ts` `StateHost` interface defines every field; no `any` in the public surface.
+- [ ] `getState` returns `PopupState`; `setState` is generic over `keyof PopupState`.
+- [ ] `registerHost` throws on second registration; `__resetHostForTests` is exported and used in vitest setup.
+- [ ] `extension/src/service-worker/router/popup-only.ts` and `content-callable.ts` no longer contain `loadDeviceSettings` / `loadBlacklist` / `saveBlacklist` definitions (only imports from `service-worker/storage.ts`).
+- [ ] `itemToManifestEntry` defined once in `extension/src/service-worker/vault.ts`, imported by both router files.
+- [ ] `extension/src/setup/setup.ts` LOC ≤ ~500.
+- [ ] `extension/src/setup/setup.ts` does not import `relicario-wasm` (no dynamic import, no `loadWasm`, no module-level `wasm` binding).
+- [ ] SW handles `create_vault` and `attach_vault` messages (entries in `messages.ts`, `POPUP_ONLY_TYPES`, and `service-worker/vault.ts`).
+- [ ] `clearWizardState()` exists, is bound to `beforeunload`, and is called from the `goto('mode')` path; sensitive `Uint8Array` fields are zero-filled.
+- [ ] `extension/src/vault/vault.ts` is split into `vault.ts` + `vault-shell.ts` + `vault-sidebar.ts` + `vault-list.ts` + `vault-drawer.ts` + `vault-form-wrapper.ts`; `vault.ts` is ~200 LOC of routing + state only.
+- [ ] Single `vault_locked` channel: the RPC intercept is in `extension/src/shared/state.ts`'s `sendMessage` wrapper; `vault.ts` no longer contains the intercept block at the old lines 47-74.
+- [ ] Drawer auto-closes on navigation to non-list views (`state.drawerOpen = false` reset in `renderPane` / `ensureDrawerClosedForRoute`).
+- [ ] Sidebar search input is debounced (50-100ms).
+- [ ] Inactivity timer resets on **all** messages except a documented exclusion set (currently `get_autofill_candidates`); the exclusion set is defined and commented in `service-worker/session-timer.ts`.
+- [ ] `state.gitHost = null` runs alongside `state.manifest = null` in the `sessionTimer.onExpired` callback.
+- [ ] One `teardownSettingsCommon` helper exists; both `settings.ts` and `settings-vault.ts` call it.
+- [ ] `devices.ts` and `trash.ts` use `Promise.allSettled` and render each settled response defensively.
+- [ ] `extension/src/content/detector.ts` MutationObserver `scan()` is debounced (200ms or `requestIdleCallback`).
+- [ ] `get_vault_status` SW message and response interface exist; vault sidebar renders an indicator on mount and on manual refresh.
+- [ ] All existing vitest tests under `extension/src/**/__tests__/` pass; new tests added per phase pass.
+- [ ] No `extension/src/wasm.d.ts` change introduced by Plan C unless coordinated with Plan B (verify the file's diff is empty post-merge, or coordinated explicitly with Plan B's parser exports).
+- [ ] Every `.free()` callsite moved by this plan is preceded by `wasm.lock(handle)` (per Plan A's policy, regardless of whether Plan A's Rust `impl Drop` has landed).

docs/superpowers/specs/2026-05-04-security-polish-design.md

@@ -0,0 +1,135 @@
+# Security & Docs Polish — Design
+
+**Date:** 2026-05-04
+**Status:** Proposed
+**Source:** `docs/superpowers/reviews/2026-05-04-architecture-review.md` (P1.1, P1.7, P1.8)
+**Effort estimate:** S (whole-PR; phase totals below)
+
+## Summary
+
+This is the one-day security and documentation PR that ships first in the v0.5.x architecture-followup train, independent of Plan B (CLI restructure) and Plan C (extension restructure). It closes the single defense-in-depth crypto gap the review flagged (`SessionHandle` has no `impl Drop`, so wasm-bindgen's `.free()` is a cleanup no-op while the master key sits in WASM linear memory), removes the JS-side error swallow that was masking that fact, brings the one undocumented security-critical core file (`recovery_qr.rs`) up to the documentation density of `crypto.rs` / `imgsecret.rs` / `backup.rs` / `tar_safe.rs`, and confirms the relay test/launcher polish items. Together these are mechanical, low-risk changes that fix the only finding in the review where "what the code looks like it does" diverges dangerously from "what it actually does" — which is exactly the wall a tinkerer learning Rust would hit hardest.
+
+## Findings addressed
+
+- **P1.1 — `SessionHandle` has no `impl Drop`; `.free()` is a cleanup no-op** — DEV-B (Rust headline) + DEV-C (JS partner finding). Files: `crates/relicario-wasm/src/lib.rs:15-23`, `crates/relicario-wasm/src/session.rs:1-58`, `extension/src/service-worker/session.ts:26`.
+- **Partner JS swallow** — DEV-C P2 in service-worker. File: `extension/src/service-worker/session.ts:26` (the `try { current.free(); } catch { /* already freed */ }` block).
+- **P1.7 — `recovery_qr.rs` is undocumented relative to the rest of core** — DEV-A. File: `crates/relicario-core/src/recovery_qr.rs:1-130`.
+- **P1.8 — `tools/relay/queue.test.ts` assertion update** — DEV-C. File: `tools/relay/queue.test.ts:54`. Confirmed during planning: **already fixed in `061facd`** — line 54 now reads `assert.ok(isRole("dev-c"));` and the negative case `assert.ok(!isRole("dev-d"));` is on line 55. No code work remains; the plan tracks this as a verification step.
+- **Launcher follow-up — `tools/relay/start.sh` still references three roles** — DEV-C P2. File: `tools/relay/start.sh:30-86`. Confirmed during planning: **not yet fixed.** Both `launch_tmux` and `launch_kitty` open only PM, Dev-A, Dev-B (no Dev-C); the manual-mode banner still says "Open 3 new terminals"; the post-launch summary lines (`:61, :81`) print "3 windows (PM, Dev-A, Dev-B)"; no `*-dev-c-prompt.md` is discovered or used. This phase is real.
+
+## Approach
+
+The PR is mechanical and uniform across four phases:
+
+- **Adds** one `impl Drop for SessionHandle` block in `crates/relicario-wasm/src/lib.rs`, one Rust test that exercises construct → drop → registry-empty, one module-level `//!` doc-block in `recovery_qr.rs`, one ASCII layout diagram next to the magic constants there, four per-function doc-comments on the public API there, and one `DEV_C_PROMPT` discovery line + a fourth window in each launcher mode of `start.sh`.
+- **Removes** the `try { current.free(); } catch { /* already freed */ }` swallow at `extension/src/service-worker/session.ts:26`.
+- **Verifies** every `.free()` callsite under `extension/src/` (the audit deliverable for P1.1's JS side; today the audit itself is small — only one match — but the deliverable is the recorded grep + a check that every code path that holds a `SessionHandle` calls `wasm.lock(handle)` before `free()`).
+- **Confirms in passing** that `tools/relay/queue.test.ts:54` already matches the new role union (it does — committed in `061facd`).
+
+No public API changes on the Rust side beyond the `Drop` impl (which is observably equivalent to "calling `lock(handle)` was previously the only way to clean up"). No JS public API changes. No file moves. No new dependencies (`wasm-bindgen-test` is already in `[dev-dependencies]` for the wasm crate).
+
+## Implementation phases
+
+### Phase 1 — Rust-side `impl Drop for SessionHandle` + test
+
+- **Goal:** make wasm-bindgen's auto-generated `.free()` actually clear the master key from WASM linear memory, regardless of whether JS also called `lock(handle)`.
+- **Changes:**
+  - `crates/relicario-wasm/src/lib.rs` — add `impl Drop for SessionHandle { fn drop(&mut self) { let _ = session::remove(self.0); } }` immediately after the existing `#[wasm_bindgen] impl SessionHandle { ... value() ... }` block (around line 23). Update the doc-comment on `SessionHandle` (line 15) to document the contract: "Dropping (or `.free()` from JS) removes the entry from the session registry and zeroizes the wrapped key/image_secret. `lock(handle)` remains available as the explicit early-cleanup path; `Drop` is the safety net."
+  - `crates/relicario-wasm/src/session.rs` — no functional change required, but add a one-line module-level note above `pub fn remove(...)` explicitly stating that `Drop for SessionHandle` is the second caller of this function alongside `lock()`, so that a future reader removing `lock()` doesn't accidentally orphan the cleanup path.
+- **Tests:**
+  - Add a `#[wasm_bindgen_test]` (the `wasm-bindgen-test` crate is already in `[dev-dependencies]`, line 25 of `Cargo.toml`) under `crates/relicario-wasm/tests/session_drop.rs`. The test constructs a `SessionHandle` (via the public `unlock` path with synthetic JPEG + tiny `KdfParams` for fast key derivation, mirroring the existing native `session_tests::manifest_round_trip_via_handle` shape), records the underlying handle id via `handle.value()`, drops the handle, then asserts `session::with(id, |_| ()).is_none()`. The `session::with` symbol must be re-exported from `tests/` scope; if it isn't, expose `pub fn with_for_tests(handle: u32) -> bool` on the `session` module guarded by `#[cfg(test)]` so the test does not need to reach into thread-locals.
+  - As a fallback / belt-and-suspenders, add a parallel native `#[test]` under the existing `mod session_tests` in `lib.rs` that constructs a `SessionHandle(session::insert(...))`, drops it explicitly with `drop(handle)`, then asserts `session::with(h, |_| ()).is_none()`. Native tests run on every `cargo test`; the wasm-bindgen-test runs only when someone invokes `wasm-pack test`, so the native variant is the one that catches regressions in CI.
+- **Effort:** S
+- **Depends on:** none
+
+### Phase 2 — JS-side `.free()` audit + remove the swallow
+
+- **Goal:** make the JS side stop hiding crypto-state-transition errors, and prove (via a recorded audit) that there are no other `.free()` callsites on `SessionHandle` (or on `EncryptedAttachment` / `TotpCode`) that bypass `wasm.lock(handle)` first.
+- **Changes:**
+  - `extension/src/service-worker/session.ts:24-28` — replace the body of `clearCurrent()` so that `current.free()` is called unconditionally (no `try`/`catch`) and `current` is set to `null` afterwards. The doc-block at the top of the file (lines 1-9) gets one extra paragraph noting that with `impl Drop` on the Rust side (Phase 1), `free()` now removes the registry entry — `lock(handle)` becomes a redundant early-cleanup option, but the SW currently does not call it. Document whether to keep `clearCurrent()` minimal (just `free()`) or add an explicit `wasm.lock(current.value)` immediately before `free()` for symmetry with the CLI's session lifecycle. Recommended: just `free()` post-Phase-1 — calling `lock` first is now belt-and-suspenders that adds a redundant HashMap remove. Document the rationale in the comment.
+  - **Audit deliverable:** run `grep -rn "\.free\b" extension/src/` and record the result in the PR description. Today this returns exactly one match (`extension/src/service-worker/session.ts:26`), confirming the SW is the only surface that calls `.free()` on a wasm-bindgen handle. If a future surface (e.g. an offscreen document, a future setup-flow refactor) adds a second callsite, this PR's grep becomes the baseline that flags the new one.
+  - **Lifecycle audit (no code change required, but record findings in PR description):** confirm every code path that constructs a `SessionHandle` via `unlock(...)` ultimately reaches `clearCurrent()`. The two paths are (a) explicit user lock via the popup `lock` action → `service-worker/router/popup-only.ts` `lock` handler → `clearCurrent()`, and (b) inactivity timer expiry → `service-worker/index.ts:51-58` session-expired callback → `clearCurrent()`. Both are already wired; this audit just records that the wiring is complete.
+- **Tests:**
+  - Vitest in `extension/`: add a small unit test in `extension/src/service-worker/__tests__/session.test.ts` (create if absent) that asserts `clearCurrent()` is a no-op when `current` is `null`, calls `setCurrent({ free: spy, value: 1 } as unknown as SessionHandle)` then `clearCurrent()`, and asserts `spy` was called exactly once and `getCurrent()` returns `null`. Use the existing `__stubs__/relicario_wasm.stub.ts` pattern for the handle shape if convenient.
+  - Optionally extend the lifecycle test: a second case where `free()` throws — assert the exception now propagates out of `clearCurrent()` (regression coverage for the swallow removal).
+- **Effort:** S
+- **Depends on:** Phase 1 (the swallow removal is only safe once the Rust side actually does the cleanup work that `.free()` is now supposed to do)
+
+### Phase 3 — `recovery_qr.rs` documentation pass
+
+- **Goal:** raise `crates/relicario-core/src/recovery_qr.rs` to the documentation density of `crypto.rs` / `imgsecret.rs` / `backup.rs` / `tar_safe.rs` so a reader landing in the file does not assume it is out-of-the-documented-zone scratch code.
+- **Changes:** all in `crates/relicario-core/src/recovery_qr.rs`:
+  - **Module-level `//!` header** at the top of the file (above the `use` block on line 1). Three short paragraphs: (1) *what* the module produces (a 109-byte payload encoded as a QR v40 EcLevel::M SVG that, given the same passphrase, recovers the 32-byte image_secret); (2) *why the format is structured this way* — XChaCha20-Poly1305 wrapping over an Argon2id-derived "wrap key" derived from the recovery passphrase (`b"relicario-recovery-v1\0"` domain-separation prefix prevents the wrap key from ever colliding with a vault master key, even if the user reuses their vault passphrase here); (3) *parameter-pinning rationale* — `production_params()` deliberately re-states `KdfParams::default()`'s values rather than referencing them, because changing the default at the type level must not silently invalidate every recovery QR a user has printed.
+  - **ASCII layout diagram** above the magic-constant block (lines 7-9):
+    ```
+    //  byte    field           length
+    //  ------  --------------  ------
+    //  0..4    MAGIC = "RREC"  4
+    //  4..5    VERSION = 0x01  1
+    //  5..37   kdf_salt        32   (random per QR)
+    //  37..61  wrap_nonce      24   (random per QR)
+    //  61..109 ciphertext      48   (32 image_secret + 16 AEAD tag)
+    //  ------------------------------
+    //  total                   109
+    ```
+    Pair the diagram with a `const _: () = assert!(PAYLOAD_LEN == 4 + 1 + 32 + 24 + 48);` static assertion so a future edit that changes the layout cannot drift from the documented total without a compile error.
+  - **Doc-comments on the four public items:**
+    - `RecoveryQrPayload` (line 11): one-paragraph summary; note that `as_bytes()` is the only accessor and that the bytes are an opaque sealed package — they should travel together (printing them as a QR is the supported transport, but a hex string also works for paranoid sneakernet).
+    - `generate_recovery_qr` (line 45): documents inputs (passphrase, image_secret), output (the 109-byte payload), and the security properties (random kdf_salt + random wrap_nonce per call ⇒ two QRs from the same passphrase + image_secret are different bytes). Cross-reference `recovery_qr_to_svg` for rendering.
+    - `unwrap_recovery_qr` (line 81): documents inputs/output, return-type rationale (`Zeroizing<[u8; 32]>` so the recovered image_secret zeroes when dropped), and the error vocabulary (`RecoveryQr` for format errors, `Decrypt` for AEAD failure / wrong passphrase — the deliberate non-distinguishing rejection from audit M4).
+    - `recovery_qr_to_svg` (line 122): documents the rendering choice (QR v40, EcLevel::M, 140×140 minimum dimension) and the rationale (109 bytes fits comfortably in v40 at M, leaving recovery-error-correction headroom for a smudged print).
+  - **`production_params` (line 32):** add a doc-comment explaining the deliberate divergence-tolerance from `KdfParams::default()` — wording: "Pinned at QR-format authoring time. `KdfParams::default()` may evolve as we re-tune Argon2 cost; this function MUST NOT change values that have ever shipped, because doing so silently invalidates every recovery QR printed under a previous parameter set." Either keep the function-with-comment shape, or per the synthesis suggestion, replace it with a `const RECOVERY_PRODUCTION_PARAMS: KdfParams = KdfParams { argon2_m: 65536, argon2_t: 3, argon2_p: 4 };` if `KdfParams` is `const`-constructible (it is — checked via `crypto.rs`). Either is acceptable; the `const` form is preferred because it makes the "this is not derived from defaults" property visible at the use site.
+  - **Optional micro-cleanups while in the file** (cite explicitly so they aren't surprising in code review):
+    - Replace the hand-counted `payload_bytes[5..37]`, `[37..61]`, `[61..109]` slice indices with named constants (`KDF_SALT_RANGE`, `WRAP_NONCE_RANGE`, `CIPHERTEXT_RANGE`) derived from the layout offsets. Improves diff-readability if the layout ever extends.
+    - Add a one-line comment to `recovery_kdf_input` documenting that the length-prefix on `nfc_bytes` mirrors the same convention as `crypto::derive_master_key` (audit H1 in the design spec) — this is the connective tissue that explains "why is there a `(len as u64).to_be_bytes()` here too?"
+- **Tests:**
+  - No new test logic needed — the existing `tests/recovery_qr.rs` and the `RecoveryQr`/`Decrypt` round-trips in `tests/integration.rs` already pin behaviour.
+  - The `const _: () = assert!(...)` static assertion is itself the contract test for the layout diagram.
+- **Effort:** S
+- **Depends on:** none
+
+### Phase 4 — Relay launcher (queue.test.ts already done in `061facd`)
+
+- **Goal:** confirm the test fix that already shipped, and bring the launcher script up to the four-role world.
+- **Changes:**
+  - `tools/relay/queue.test.ts` — **no change.** Confirmed during planning: line 54 is already `assert.ok(isRole("dev-c"));` and line 55 is already `assert.ok(!isRole("dev-d"));` (committed in `061facd`). This phase records the verification step in the PR description so a reviewer can see the file was checked.
+  - `tools/relay/start.sh` — real changes:
+    - Add a `DEV_C_PROMPT` discovery line at lines 30-33 alongside the existing `PM_PROMPT` / `DEV_A_PROMPT` / `DEV_B_PROMPT` definitions: `DEV_C_PROMPT="$(ls -t "$COORD_DIR"/*-dev-c-prompt.md 2>/dev/null | head -1 || echo "(none found)")"`.
+    - Manual mode (`print_manual_instructions`, lines 35-51) — change "Open 3 new terminals" to "Open 4 new terminals" and add the `Terminal 4 (Dev C): cat '$DEV_C_PROMPT'` line.
+    - tmux mode (`launch_tmux`, lines 53-69) — add a fourth `tmux new-window -t "$SESSION:" -n "dev-c" "cd '$REPO_ROOT' && claude"` line; update the summary print on line 61 from "4 windows: relay, pm, dev-a, dev-b" to "5 windows: relay, pm, dev-a, dev-b, dev-c"; add `Dev C: $DEV_C_PROMPT` to the prompts list (currently lines 64-66).
+    - kitty mode (`launch_kitty`, lines 71-86) — add a fourth `kitty @ launch --type=tab --tab-title "Dev-C" --hold -- bash -l -i -c "cd '$REPO_ROOT' && claude"` line; update the summary print on line 81 from "3 windows (PM, Dev-A, Dev-B)" to "4 windows (PM, Dev-A, Dev-B, Dev-C)"; add `Dev C: $DEV_C_PROMPT` to the prompts list.
+- **Tests:** none directly. The relay launcher has no automated tests; verification is "run `bash tools/relay/start.sh --manual` and confirm the banner mentions four terminals + the Dev-C prompt path; run `bash tools/relay/start.sh --kitty` on a kitty terminal and confirm a fourth tab opens." Both checks belong in the PR's manual-test plan.
+- **Effort:** S
+- **Depends on:** none
+
+## Risks and mitigations
+
+- **Adding `impl Drop` could change observable behaviour for any JS code that today holds two references to the same `SessionHandle` and frees one of them.** wasm-bindgen does not in fact let JS hold two refs to the same Rust struct without explicit cloning — the `SessionHandle` is moved into JS at construction and `.free()` consumes the handle pointer. The audit in Phase 2 confirmed only one `.free()` callsite under `extension/src/`. The CLI does not touch the WASM crate at all (Rust-side; the CLI uses `relicario-core` directly). So the realistic blast radius is exactly the one SW callsite this plan also touches. Mitigation: Phase 1's native test explicitly covers "drop the handle, registry is empty," and Phase 2's vitest covers "free is called exactly once."
+- **Removing the `try { current.free() } catch { /* already freed */ }` swallow could expose latent bugs that were silently tolerated.** Specifically, if any code path today double-frees the handle (calls `clearCurrent()` twice without a `setCurrent()` in between), the catch is currently hiding it. Reading the SW lifecycle: `clearCurrent()` is called from (a) the `lock` message handler, (b) the inactivity-timer session-expired callback, and (c) potentially the unlock-failure cleanup path. The current `if (!current) return;` early-out at line 25 already guards the simplest double-free case (calling `clearCurrent()` twice in a row is safe because the second call no-ops). The only way the catch fires today is if something in WASM raises during `free()` — which post-Phase-1 should be impossible (Drop is infallible; `session::remove` returns a bool, not a Result). Mitigation: the swallow removal happens *after* Phase 1's Drop lands, so the catch should now have nothing to catch. If a regression test surfaces a real bug, the right fix is to find and fix the bug, not re-add the swallow.
+- **The `recovery_qr.rs` static assertion (`const _: () = assert!(PAYLOAD_LEN == ...);`) requires Rust 1.79+** for `const` panic in test position. The workspace's `rust-toolchain.toml` (if present) or the `Cargo.toml` `rust-version` field needs to be checked; if the repo is on an older toolchain, fall back to a runtime `#[test] fn payload_len_matches_layout() { assert_eq!(PAYLOAD_LEN, 4 + 1 + 32 + 24 + 48); }` — same effect, slightly less elegant. Verify during implementation; not a blocker.
+- **Phase 4's launcher change is untested by automation.** A typo in the kitty/tmux command lines won't surface until someone runs `start.sh --kitty` or `start.sh --tmux`. Mitigation: the PR description includes an explicit manual-test plan ("run all three modes and confirm 4 windows + Dev-C prompt resolution") and the change pattern is symmetric to the existing Dev-A/Dev-B lines, minimizing typo surface.
+- **The `wasm-bindgen-test` variant in Phase 1 only runs under `wasm-pack test --node`, which is not part of the project's default `cargo test` cycle.** The native `#[test]` in `mod session_tests` is the one that protects against regressions in CI. The wasm-bindgen-test is included for symmetry and to exercise the actual WASM target's Drop behaviour — it should be invoked at least once during PR review and added to a follow-up CI workflow if the project's test infrastructure ever expands to wasm-pack.
+
+## Out of scope
+
+This plan deliberately does not address, and explicitly leaves to other plans or the P2/P3 tail:
+
+- Plan B's CLI restructure work in its entirety (P1.2 main.rs split, P1.3 git-shell error UX, P1.10 parser migration to core, plus the CLI P2/P3 entries). These touch `crates/relicario-cli/` and are independent of this PR.
+- Plan C's extension restructure work in its entirety (P1.4 setup.ts WASM extraction, P1.5 vault.ts split, P1.6 shared/state.ts typing, P1.9 SW router helper extraction, plus the extension P2/P3 entries). These touch `extension/src/` and are independent of this PR — except for the single SW file that Phase 2 of this plan touches, which is small and disjoint from Plan C's surfaces.
+- The P2 WASM cleanups DEV-B flagged: redundant `need_key + with(...).unwrap()` double-lookup, `Vec<u8>` getter clones, the `wasm_*_recovery_qr` naming inconsistency, and the `device.rs` vs `session.rs` concurrency-primitive split. Each is independently correct and worth doing, but each is its own one-paragraph change and the PR is already covering its theme.
+- DEV-C's other relay P2s: queue TTL/persistence/cap, the `tools/relay/call.py` and `call.ts` tracking decision, `server.ts` per-connection factory comment. None block this PR.
+- The eight "Open architectural decisions" at the bottom of the synthesis (deliberate-Drop-omission, parser migration timing, bootstrap rule, `Lock` subcommand visibility, Task 12 status, call.py tracking, snake_case-vs-camelCase WASM naming, `.gitea_env_vars` gitignore). Most are user-judgement calls; this PR confirms #1 (the omission was not deliberate; the fix lands here) but takes no position on #2-#8.
+- Anything touching the in-flight uncommitted v0.5.x work — manifests, glyphs, vault.css, relay tooling beyond `start.sh`. Those changes are on parallel branches and are explicitly hands-off for this PR.
+
+## Done criteria
+
+A reviewer can confirm this plan shipped by checking:
+
+- [ ] `crates/relicario-wasm/src/lib.rs` contains `impl Drop for SessionHandle` whose body removes the registry entry.
+- [ ] `crates/relicario-wasm/tests/session_drop.rs` (or equivalent native `#[test]` inside `mod session_tests`) asserts that dropping a `SessionHandle` removes its handle id from the session registry. `cargo test -p relicario-wasm` passes the new test.
+- [ ] `extension/src/service-worker/session.ts` no longer contains `try { current.free(); } catch`. The body of `clearCurrent()` calls `current.free()` unconditionally, then sets `current = null`.
+- [ ] `grep -rn "\.free\b" extension/src/` returns exactly one match (the SW callsite). PR description records this audit.
+- [ ] `extension/src/service-worker/__tests__/session.test.ts` covers `clearCurrent()` with both the no-op (no current handle) and the propagating-throw cases. `npm test` from `extension/` passes.
+- [ ] `crates/relicario-core/src/recovery_qr.rs` has a module-level `//!` header explaining format + domain-separation + parameter-pinning, an ASCII layout diagram next to the magic constants, doc-comments on `RecoveryQrPayload`, `generate_recovery_qr`, `unwrap_recovery_qr`, and `recovery_qr_to_svg`, plus either a `const RECOVERY_PRODUCTION_PARAMS` or a doc-commented `production_params()` explaining why it deliberately diverges from `KdfParams::default()`. `cargo test -p relicario-core` still passes.
+- [ ] `tools/relay/queue.test.ts:54-55` verified to already match the new role union (no change required, recorded in PR description).
+- [ ] `tools/relay/start.sh` discovers a `*-dev-c-prompt.md`, opens a fourth window/terminal in tmux and kitty modes, and the manual-mode banner mentions all four roles. `bash tools/relay/start.sh --manual` shows "Open 4 new terminals" and lists the Dev-C prompt path.

docs/superpowers/specs/2026-05-23-vault-tab-management-surfaces-revamp-design.md

@@ -0,0 +1,466 @@
+# Vault-tab management surfaces revamp
+
+**Date:** 2026-05-23
+**Status:** Spec, awaiting review
+**Surface:** Browser extension management panes — `extension/src/popup/components/` (shared between popup and vault tab)
+
+## Problem
+
+Four "management" surfaces in the extension — **Settings**, **Devices**, **Trash**, and **field history** — all shipped in the 1C-β₂ / device-auth waves but in the *pre-fullscreen-redesign* visual language. They read as popup-derived forms stretched across the vault tab, with inconsistent typography, no glyph buttons, no focus rings, and no visual section grouping. Several functional gaps remain alongside the visual debt:
+
+- **Settings**: per-device session-timeout config UI was specced in the vault-tab design (2026-04-27) but never built; the only way to change session behavior today is to edit `chrome.storage.local` directly.
+- **Devices**: revocation works via a plain text "revoke" button + browser `confirm()` dialog — functional but inconsistent with the rest of the extension's UX. Device entries don't expose the SHA256 fingerprint (used for verifying against the server-side `devices.json`) or the `added_by` field that's already in `DeviceEntry`.
+- **Trash**: per-item purge countdown isn't shown — users see "trashed N days ago" but have to mentally add the retention window to figure out when it'll be gone.
+- **History**: the per-item field-history viewer (`field-history.ts`) is only reachable from an item detail page; there's no entry point to discover *which* items have history.
+
+This spec applies the fullscreen visual-language tokens to all four panes and closes the gaps above. It deliberately stays small and ships in the v0.5.x train, in the current `vault.ts` shell — Phase 3 shell rearchitecture is out of scope.
+
+## Goals
+
+- All four management panes adopt the fullscreen visual language: glyph buttons, focus ring, uppercase section headers with 1px bottom rule, accent tokens, required-field pill where applicable.
+- Close the four functional gaps above (session timeout UI, revoke button surfacing, fingerprint + added-by display, purge countdown, history index).
+- Add **one new pane** — "items with history" index — reachable from a new `◷ history` slot in the sidebar bottom-nav.
+- Zero core or wasm changes; zero data-model changes; zero new schema versions.
+
+## Non-goals
+
+- **Phase 3 shell rearchitecture** (three-pane layout, `shell/three-pane.ts`, `keymap.ts`) — separate effort, separate spec.
+- **Phase 4 command palette** — deferred to its own brainstorm round.
+- **Item-level snapshot history** — option B/C from brainstorm; this spec uses option A (aggregate existing `field_history` per item; no new core storage).
+- **Settings as a hub with sub-tabs** — would introduce sub-tab pattern not used elsewhere; defer.
+- **Trash polish**: hover-preview, multi-select bulk-restore — defer.
+- **Devices polish**: rotate-key flow, "last seen" detail (would need new data) — defer.
+- **History polish**: diff view between historical values — defer.
+
+## Scope summary
+
+| Surface | Files touched | New? |
+|---|---|---|
+| Settings | `popup/components/settings-vault.ts`, `vault.css`/`popup.css` | modify |
+| Devices | `popup/components/devices.ts`, new `shared/ssh-fingerprint.ts` | modify + 1 new util |
+| Trash | `popup/components/trash.ts` | modify |
+| History — index | `popup/components/item-history-index.ts` | **NEW** |
+| History — per-item | `popup/components/field-history.ts` | polish only (no rename) |
+| Glyph constants | `shared/glyphs.ts` | depends-on-or-creates |
+| Time helper | `shared/relative-time.ts` | **NEW** (extracted from 3 call sites) |
+| Routing | `vault/vault.ts` | add `#history` + `#history/<itemId>` routes |
+| Nav | sidebar bottom-nav | grows 3 → 4 (`▦ trash · ⌬ devices · ⚙ settings · ◷ history`) |
+
+---
+
+## Architecture
+
+### Component map
+
+```
+extension/src/
+├── shared/
+│   ├── glyphs.ts                 ← depends on (or creates if absent):
+│   │                                GLYPH_TRASH ▦, GLYPH_DEVICES ⌬,
+│   │                                GLYPH_SETTINGS ⚙, GLYPH_LOCK ⏻,
+│   │                                GLYPH_HISTORY ◷, GLYPH_REVOKE ⊘,
+│   │                                GLYPH_RESTORE ⤺, GLYPH_REVEAL ⊙,
+│   │                                GLYPH_COPY ⧉
+│   └── relative-time.ts          ← NEW (small util — inlined in 3 places today)
+├── popup/components/
+│   ├── settings-vault.ts         ← rewrite layout; add session-timeout row
+│   ├── devices.ts                ← add fingerprint, "added by"; surface revoke button
+│   ├── trash.ts                  ← add per-item purge countdown
+│   ├── field-history.ts          ← visual polish only (filename kept)
+│   └── item-history-index.ts     ← NEW: "items with history" index
+└── vault/
+    ├── vault.ts                  ← add #history routes + bottom-nav slot
+    ├── vault.css                 ← four shared utility classes (below)
+    └── popup.css                 ← same classes (shared components render in both)
+```
+
+### SW message protocol — 99% reuse
+
+| Capability | Message | Status |
+|---|---|---|
+| Read/write vault settings | `get_vault_settings` / `update_vault_settings` | exists |
+| Read/write session timeout (per-device) | `get_session_config` / `update_session_config` | exists |
+| List active + revoked devices | `list_devices` / `list_revoked` | exists |
+| Register / revoke device | `register_this_device` / `revoke_device` | exists |
+| List trashed, restore, purge | `list_trashed` / `restore_item` / `purge_item` / `purge_all_trash` | exists |
+| Per-item field history | `get_field_history` | exists (reused for index + per-item) |
+
+**No SW shape changes.** Fingerprint is computed client-side in `devices.ts` via `crypto.subtle.digest('SHA-256', …)` against the base64-decoded ed25519 key blob from `DeviceEntry.public_key`. Result is formatted as `SHA256:<base64-no-pad>` to match the SSH convention (and what `relicario device list` prints from `core::device::fingerprint()`). Pure extension change — no message round-trip, no WASM export, no Rust change.
+
+### Shared CSS utility classes
+
+Defined in `vault.css` and `popup.css` (shared because components render in both contexts):
+
+```css
+.section-header {
+  text-transform: uppercase;
+  font-weight: 500;
+  letter-spacing: 1px;
+  color: var(--text-muted);
+  border-bottom: 1px solid var(--border-subtle);
+  padding-bottom: 4px;
+  margin-bottom: 10px;
+}
+
+.glyph-btn {
+  min-width: 28px;
+  font-family: ui-monospace, monospace;
+  background: transparent;
+  color: var(--text-muted);
+  border: 1px solid var(--border-subtle);
+  border-radius: 3px;
+  padding: 2px 6px;
+  cursor: pointer;
+}
+.glyph-btn:hover { color: var(--text); background: var(--bg-input); }
+.glyph-btn:focus-visible { box-shadow: var(--focus-ring); outline: none; }
+.glyph-btn[data-danger]:hover { color: var(--danger); border-color: var(--danger); }
+
+.kv-row {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  padding: 4px 0;
+}
+.kv-row > .k { color: var(--text-muted); }
+.kv-row > .v { color: var(--text); font-variant-numeric: tabular-nums; }
+
+.fingerprint {
+  font-family: ui-monospace, monospace;
+  color: var(--text-muted);
+  font-size: 11px;
+  word-break: break-all;     /* wraps to two lines in popup (~360px) */
+}
+```
+
+### Visual language reference
+
+All tokens come from the existing fullscreen UX redesign spec (`2026-04-30-relicario-fullscreen-ux-redesign-design.md`, "Visual language" section). No new tokens introduced. New glyph constants added to `shared/glyphs.ts` if not already present: `GLYPH_HISTORY ◷`, `GLYPH_REVOKE ⊘`, `GLYPH_RESTORE ⤺`, `GLYPH_REVEAL ⊙`, `GLYPH_COPY ⧉`.
+
+---
+
+## A. Settings pane
+
+Two-tier section grouping makes the storage distinction explicit: **VAULT SETTINGS · synced** lives in the encrypted vault (replicated via git), **THIS DEVICE · local** lives in `chrome.storage.local` (per-device, not synced). **ACTIONS** is destructive/expensive operations.
+
+```
+◀ settings
+unsaved · ⌘+S to save                                      no changes
+
+
+VAULT SETTINGS · synced
+─────────────────────────────────────────────────────────────
+
+┌──────────────────────────┐  ┌──────────────────────────┐
+│ RETENTION                │  │ GENERATOR                │
+│ trash       [30 days  ▾] │  │ length      24           │
+│ history     [last 5   ▾] │  │ words        4           │
+│                          │  │ [ configure defaults ↻ ] │
+└──────────────────────────┘  └──────────────────────────┘
+
+┌──────────────────────────┐
+│ ATTACHMENTS              │
+│ max size    [25 MB    ▾] │
+└──────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│ AUTOFILL ORIGINS                                        │
+│ github.com               acknowledged 2d ago        ⊘   │
+│ gitlab.adlee.work        acknowledged 5d ago        ⊘   │
+└─────────────────────────────────────────────────────────┘
+
+
+THIS DEVICE · local
+─────────────────────────────────────────────────────────────
+
+┌──────────────────────────┐
+│ SESSION                  │
+│ ○ lock every time        │
+│ ● after inactivity       │
+│       [15 min        ▾]  │
+└──────────────────────────┘
+
+
+ACTIONS
+─────────────────────────────────────────────────────────────
+
+  [ backup & restore ]   [ import from… ]
+```
+
+### Decisions
+
+- **Two-tier grouping** with `· synced` / `· local` muted suffixes makes storage scope unambiguous without being preachy.
+- **Two-column where fields are small** (Retention ↔ Generator; Attachments standalone in row 2). Collapses to single-column under 720px viewport — same rule the login form uses.
+- **Session timeout** wires the existing `get_session_config` / `update_session_config` SW messages to a radio (`every_time` / `inactivity`) + minutes dropdown (5/15/30/60). Already-validated config shape from the vault-tab spec.
+- **Form header** reuses the "unsaved · ⌘+S to save" / "no changes" subtitle from the form-layout spec — gives Settings the same dirty-state feedback as item edits.
+- **Generator section** keeps the current "configure defaults" button opening the popover from Phase 2A — no inline expansion.
+- **Actions** uses text-labelled buttons (not glyph buttons) since they open dedicated panes; text is clearer than icons for navigation-style actions.
+
+---
+
+## B. Devices pane
+
+Single column (this is a list, not a form). Three-line per-entry rhythm: name (+ `← you` marker or `⊘` revoke glyph), full SHA256 fingerprint, then `added X ago · by Y`.
+
+```
+◀ devices
+
+
+ACTIVE · 3
+─────────────────────────────────────────────────────────────
+
+⌬  Aaron's laptop                                ← you
+   SHA256:8f3a:c7d2:1e44:9b08:6f55:a201:de9c:4477
+   added 2 months ago · by Aaron
+
+⌬  Aaron's phone                                       ⊘
+   SHA256:9c11:e4f8:2a91:db32:7c0e:51bb:e8a4:1f6d
+   added 3 weeks ago · by Aaron's laptop
+
+⌬  work-laptop                                         ⊘
+   SHA256:b277:35aa:c1e0:8f44:62b9:0d3e:7c1f:5d92
+   added 8 days ago · by Aaron's laptop
+
+
+REVOKED · 1
+─────────────────────────────────────────────────────────────
+▸ show 1 revoked device
+```
+
+### Revoke confirmation — inline two-step
+
+Clicking `⊘` expands a confirmation panel in place (no modal):
+
+```
+⌬  Aaron's phone
+   SHA256:9c11:e4f8:2a91:db32:…
+   added 3 weeks ago · by Aaron's laptop
+
+   ┌─────────────────────────────────────────────────────┐
+   │ Revoke this device? It won't be able to sign        │
+   │ commits or push changes after revocation.           │
+   │                                                     │
+   │              [ cancel ]    [ revoke ]               │
+   └─────────────────────────────────────────────────────┘
+```
+
+### Unregistered state — top banner
+
+```
+◀ devices
+
+┌─────────────────────────────────────────────────────────┐
+│ This device isn't registered.                           │
+│ Registering generates an ed25519 keypair and adds the   │
+│ public key to .relicario/devices.json on the remote.    │
+│                                                         │
+│ [ register this device ]                                │
+└─────────────────────────────────────────────────────────┘
+
+ACTIVE · 2
+─────────────────────────────────────────────────────────────
+…
+```
+
+### Decisions
+
+- **Full fingerprint shown** (no truncation): verifiability against `.relicario/devices.json` is the whole point of displaying it. Popup-width wrapping handled by `.fingerprint { word-break: break-all }` — wraps to two lines under ~360px.
+- **`by Y` semantics**: `DeviceEntry.added_by` — the name of the device that signed the registration commit. Already in the data model, just unsurfaced today.
+- **Inline two-step revoke** keeps the lightness of the rest of the extension's UX; modal would feel disproportionate. The current device gets no revoke button (the CLI keeps the "revoke self" escape hatch since that needs different post-revoke handling).
+- **Revoked section** collapsed by default with count; expanded entries get the same three-line rhythm minus the revoke button, plus `revoked X ago · by Y`.
+- **Unregistered banner**: fleshed-out copy explaining what registration *does* (current one-liner feels mysterious per memory of past confusion). Same flow underneath — click → modal with device-name input → `register_this_device` SW message.
+
+---
+
+## C. Trash pane
+
+```
+◀ trash
+
+3 items · oldest purges in 22 days
+
+
+─────────────────────────────────────────────────────────────
+
+🔑  GitHub login                                       ⤺
+    trashed 8 days ago · purges in 22 days
+
+📝  Recovery note                                      ⤺
+    trashed 12 days ago · purges in 18 days
+
+🔑  old-aws-root                                       ⤺
+    trashed 18 days ago · purges in 12 days
+
+─────────────────────────────────────────────────────────────
+
+                                           [ empty trash ]
+```
+
+### Decisions
+
+- **Two-line per-entry**: type icon + name + `⤺` restore glyph; muted second line `trashed X ago · purges in Y days`.
+- **Per-item purge countdown** computed client-side from `trashed_at + retention_seconds - now` and formatted via `shared/relative-time.ts`. Updates on pane render (no live timer — sub-day precision unnecessary).
+- **Header summary stays** ("3 items · oldest purges in 22 days") — useful at-a-glance.
+- **Destructive empty button anchored bottom-right** — separated from per-row restore buttons to reduce mis-clicks. Confirmation flow unchanged from today.
+- **Sort**: trashed-date descending (newest first). Defer "sort by purge urgency" toggle — not strongly requested and adds toolbar real estate.
+- **Type icons** stay as today (emoji per item type) — the global glyph treatment is for *action* buttons; type icons are content-classification and read better as the existing emoji set.
+
+---
+
+## D. History — index pane (NEW)
+
+Reachable from a new `◷ history` bottom-nav slot. Sorted by most-recent-change descending.
+
+```
+◀ history
+
+5 items have field history
+
+
+─────────────────────────────────────────────────────────────
+
+🔑  GitHub login
+    3 changes · last 2 days ago
+
+🔑  AWS prod
+    1 change · last 2 weeks ago
+
+📝  Recovery note
+    2 changes · last 3 weeks ago
+
+🔑  Cloudflare
+    1 change · last 1 month ago
+
+🌐 personal-email
+    4 changes · last 2 months ago
+```
+
+### Decisions
+
+- **Implementation**: iterate manifest entries, fetch + decrypt each item (already cached in session state where decrypted), inspect `field_history` map; emit entries that have ≥1 history-tracked field with non-empty history. Count = sum of `field_history[*].length`. Last-changed = max `replaced_at` across all history entries.
+- **Click row** → routes to `#history/<itemId>` (per-item view below).
+- **Empty state** when no items have history: *"No field history yet. Edits to passwords, TOTP secrets, and concealed fields will appear here."*
+- **No excerpts** in the index — keeping it lean; the per-item view is one click away.
+
+---
+
+## E. History — per-item view (existing, polished)
+
+Existing component (`field-history.ts`, filename kept). Visual polish only — apply the section-header rule, glyph buttons, focus ring, accent tokens. **No structural changes to content layout.**
+
+```
+◀ history · GitHub login
+
+
+PASSWORD · 3 entries
+─────────────────────────────────────────────────────────────
+
+   current      ●●●●●●●●●●●●●●●●●●●●●●●●     ⊙   ⧉
+                set 2 days ago
+   ───
+   previous     ●●●●●●●●●●●●●●●●●●●          ⊙   ⧉
+                3 weeks ago
+   ───
+   previous     ●●●●●●●●●●●●●●●●             ⊙   ⧉
+                2 months ago
+
+
+TOTP_SECRET · 1 entry
+─────────────────────────────────────────────────────────────
+
+   current      ●●●●●●●●●●●●●●●●●●●●●●●●     ⊙   ⧉
+                set 1 month ago
+   ───
+   previous     ●●●●●●●●●●●●●●●●●●●          ⊙   ⧉
+                (created · 3 months ago)
+```
+
+### Decisions
+
+- **Filename kept** as `field-history.ts` per user feedback during brainstorm.
+- **Routing**: continues to be reachable from item-detail "view history" button (`#history/<itemId>`). Now also reachable by drilling into the history index pane.
+- **Reveal/copy glyphs** updated to `⊙ ⧉` constants from `shared/glyphs.ts`.
+- **Per-field uppercase header** + 1px rule applied — matches the new visual rhythm.
+- **Values stay concealed by default** (existing behavior). Reveal toggle and copy button per entry. Values held in component-local `valueStore` map (not DOM attributes) — existing security pattern preserved.
+
+---
+
+## Routing & sidebar nav changes
+
+### `vault.ts` `VaultView` union changes
+
+```ts
+type VaultView =
+  | 'list' | 'detail' | 'add' | 'edit'
+  | 'trash' | 'devices' | 'settings' | 'settings-vault'
+  | 'field-history'        // existing — per-item view (internal dispatch key kept)
+  | 'history'              // NEW — index pane only
+  | 'backup' | 'import'
+```
+
+The user-facing hash changes (`#history` is the new entry point, `#history/<id>` is the per-item view), but the internal dispatch keeps `'field-history'` for the per-item view to minimize the diff to working code. Normalization happens in `parseHash`:
+
+- `#history` → `{ view: 'history' }` → index pane (`item-history-index.ts`)
+- `#history/<itemId>` → `{ view: 'field-history', id: <itemId> }` → per-item view (`field-history.ts`)
+- `#field-history/<itemId>` → rewritten to `#history/<itemId>` in the address bar, then resolved as above (one release of backward compat for any bookmarked URLs)
+
+### Sidebar bottom-nav
+
+```
+▦ trash · ⌬ devices · ⚙ settings · ◷ history · ⏻ lock
+```
+
+Five glyph buttons in a row at ~240px sidebar width: comfortable at 1ch each + padding. Verified.
+
+---
+
+## Testing
+
+UI work — verification is mostly manual smoke:
+
+- Each pane loads, renders, round-trips edits
+- Settings round-trip: change retention/session/attachments → reload → values persist; session-timeout actually fires lock after configured minutes
+- Devices: fingerprint string matches `relicario device list` CLI output; revoke happy path + cancel; unregistered banner → register flow → confirm
+- Trash: per-item purge countdown updates correctly; empty trash → confirms then purges
+- History: index sorted by recency; click drills in; empty state when no history; both `#history/<id>` and the item-detail entry point reach the same view
+- Cross-context: each shared component renders correctly in both popup (~360px) and vault tab (full)
+
+**Unit tests** — only where logic warrants:
+- `shared/relative-time.ts` — table-driven test of fixture timestamps → strings
+- Purge-countdown formatting
+
+No new test infrastructure. Extension currently has no snapshot tests per inventory; not adding any here.
+
+---
+
+## Rollout
+
+- Single PR, v0.5.x train.
+- No data-model migration, no schema change, no core or wasm changes.
+- Purely `extension/src/`: one new shared util, one new pane file, four modified components, CSS additions, two routing additions.
+- Doc updates: `STATUS.md` move-to-recent on land; `extension/ARCHITECTURE.md` note the new `◷ history` route + 4th sidebar slot.
+
+---
+
+## Risks
+
+| Risk | Mitigation |
+|---|---|
+| Bottom-nav crowding (4 + lock = 5 items at ~240px sidebar) | Glyphs are 1ch each; ample room verified, but confirm at narrowest viewport during smoke |
+| Fingerprint length in popup context (~330px monospace) | CSS `word-break: break-all` on `.fingerprint`; no truncation |
+| `shared/glyphs.ts` may not exist yet | Spec creates it if absent (called out in §1) — depends-on-or-creates |
+| Decrypting all items for the history index pane | Most items are already cached after a session warm-up; cost is per-pane-load not per-event; acceptable for family-vault item counts |
+| Inline revoke confirmation could be missed (no modal blocker) | Two-step pattern matches other extension confirmations (delete item, empty trash); copy is explicit about consequence |
+
+---
+
+## Out of scope (deferred to future rounds)
+
+- Phase 3 shell rearchitecture (three-pane layout, command palette, drag-resize panes)
+- Phase 4 command palette
+- Item-level snapshot history (option B/C)
+- Settings-as-hub with sub-tabs
+- Trash multi-select / bulk-restore / hover preview
+- Devices rotate-key flow / "last seen" detail
+- History diff view between adjacent values
+- Whole-revamp animations or transitions

docs/superpowers/specs/2026-05-30-doc-structure-redesign-design.md

@@ -0,0 +1,245 @@
+# Doc Structure Redesign — Design
+
+**Date:** 2026-05-30
+**Status:** Proposed
+**Source:** Drift audit run on this same date (three parallel agents over the living docs) + follow-up brainstorm with the user.
+**Effort estimate:** S (one focused afternoon — renames + headers + link-fixes, no content rewrites).
+
+## Summary
+
+The living docs split into roughly thirteen files spread across the repo root, `docs/`, `crates/*`, and `extension/`. Three of them are called `ARCHITECTURE.md` and overlap in scope, which is exactly where the drift audit clustered (top-level called `0x01` while code shipped `0x02`, `FORMATS.md` listed 16-hex AttachmentIds while code used 32, per-crate maps missed five public modules and several CLI commands). This design keeps the file count roughly the same but **renames docs by topic, pins each doc to an explicit scope, and chains them into a single reading order**. A contributor (or future-you after a long break) lands on `README`, gets walked through `DESIGN → docs/CRYPTO → docs/FORMATS → docs/SECURITY → crates/*/ARCHITECTURE.md → extension/ARCHITECTURE.md`, never sees two files with the same name, and never has to guess which doc owns a given fact.
+
+The drift fixes themselves landed in three commits earlier today (`210232d`, `cf7478d`, `fa659eb`). This redesign attacks the *structural* causes of the drift so the next audit has less to find.
+
+## Findings addressed
+
+The drift audit produced a punch list across three themes. The structural causes this redesign attacks are:
+
+- **Three files named `ARCHITECTURE.md` at three levels with overlapping scope.** Top-level vs `docs/ARCHITECTURE.md` overlap drove the `0x01`-vs-`0x02` divergence and the `MIN_COPIES` confusion. Renaming the top-level to `DESIGN.md` and the `docs/` one to `docs/CRYPTO.md` eliminates the name collision and makes each doc's topic obvious from its filename.
+- **No scope boundaries between docs.** When the wire-format byte changed in code, there was no rule saying "the version-byte diagram lives in `docs/CRYPTO.md`, not in `FORMATS.md` or `DESIGN.md`," so the diagrams in two docs drifted apart. Adding explicit scope headers to each tour doc makes "where does this fact go?" unambiguous.
+- **No reading order signposts.** A cold reader couldn't tell whether to start at README, top-level ARCHITECTURE, or `docs/ARCHITECTURE.md`. "Next:" footers on every tour doc make a single canonical path.
+- **`FORMATS.md` sitting at the repo root while every other reference doc sits in `docs/`.** Asymmetry adds cognitive load. Moving it to `docs/FORMATS.md` aligns with the rest.
+- **`CLAUDE.md`'s "Living docs — update discipline" table is the only place the scope-rules are written.** It lists *when* to update each doc but not *what each doc owns vs does not own*. The new scope headers act as on-doc enforcement; the CLAUDE.md table is updated to point at the new filenames and adds three new discipline rules.
+
+Out of scope (intentionally): STATUS.md drift habit (a behavioural problem, not structural); per-crate `main.rs:NNNN` line-number citations going stale when handlers move (a habit nudge — cite by function name, not line — but cross-cutting and worth its own pass).
+
+## Goals
+
+- A cold reader can flow from `README → DESIGN → docs/CRYPTO → docs/FORMATS → docs/SECURITY → crates/*/ARCHITECTURE.md → extension/ARCHITECTURE.md` without ping-ponging or guessing which doc owns what.
+- Every tour doc declares its scope in a 1-2 sentence header at the top and points at the next doc in a single-line footer at the bottom.
+- The drift surface shrinks: no two docs claim to own the same fact.
+- Migration is mechanical (renames + header additions + link fixes); no content is rewritten. The drift audit already cleaned the content.
+
+## Non-goals
+
+- Renaming per-crate or extension `ARCHITECTURE.md` files. Their nesting (`crates/X/`, `extension/`) already disambiguates them.
+- Adding new ARCHITECTURE.md files for `relicario-server` or `relicario-wasm`. Both crates are small enough that a per-crate doc would be more maintenance than help. Add later if either grows.
+- Touching `STATUS.md`, `ROADMAP.md`, `CHANGELOG.md`. Their roles are well-defined and the audit found no structural issue there.
+- Touching `docs/superpowers/specs/` or `docs/superpowers/plans/`. Intentionally accumulating.
+- Adding `CONTRIBUTING.md`. The "me + Claude, contributor-ready" audience choice means we keep the docs welcoming but don't bolt on contributor-onboarding pages we don't need yet.
+
+## Target structure
+
+```
+README.md                            Front door (already great). Trim its mid-section
+                                     "Architecture" stub to a one-paragraph pointer at
+                                     DESIGN.md. Pitch + security model + quick-start +
+                                     reference image + recovery + roadmap teaser stay.
+
+DESIGN.md                            NEW NAME (replaces top-level ARCHITECTURE.md).
+                                     The system tour: four codebases, contracts between
+                                     them, secrets map, build matrix, global code-map index.
+
+docs/
+├── CRYPTO.md                        NEW NAME (renamed from docs/ARCHITECTURE.md).
+│                                    Crypto pipeline + vault flows + DCT embedding +
+│                                    high-level encrypted-file-format diagram.
+│
+├── FORMATS.md                       MOVED from repo root.
+│                                    Wire formats: .enc blob layout, params.json,
+│                                    devices.json, manifest schema, .relbak envelope,
+│                                    ID formats, settings JSON schema.
+│
+└── SECURITY.md                      UNCHANGED LOCATION.
+                                     Threat model, attacker scenarios, device auth,
+                                     env-var trust surface.
+
+crates/
+├── relicario-core/ARCHITECTURE.md   UNCHANGED (nesting disambiguates).
+├── relicario-cli/ARCHITECTURE.md    UNCHANGED.
+├── relicario-server/                No doc — too small.
+└── relicario-wasm/                  No doc — too small.
+
+extension/ARCHITECTURE.md            UNCHANGED.
+
+(unchanged: STATUS / ROADMAP / CHANGELOG / CLAUDE / LICENSE / docs/superpowers/)
+```
+
+**Reading order:**
+
+```
+README → DESIGN → docs/CRYPTO → docs/FORMATS → docs/SECURITY
+       → crates/relicario-core/ARCHITECTURE.md
+       → crates/relicario-cli/ARCHITECTURE.md
+       → extension/ARCHITECTURE.md
+```
+
+Realized by two conventions on every tour doc:
+
+1. **Scope header (top, 1-2 sentences):** *"This doc owns X. See Y for Z."*
+2. **"Next:" footer:** a one-line pointer to the next doc in the tour.
+
+## Per-file scope definitions
+
+The exact scope headers + "Next:" footers to be pasted at the top and bottom of each tour doc.
+
+### `README.md`
+
+> **Audience:** users + evaluators. This doc owns the pitch, security-model summary, quick-start commands, reference-image explanation, recovery-QR overview, and roadmap teaser. Goes no deeper — for the system tour see [DESIGN.md](DESIGN.md), for crypto see [docs/CRYPTO.md](docs/CRYPTO.md).
+
+Existing-content delta: the current "Architecture" section gets trimmed to one paragraph pointing at `DESIGN.md`. Quick start / Reference image / Recovery / Roadmap sections stay.
+
+Footer: `Next: [DESIGN.md](DESIGN.md) — the system tour.`
+
+### `DESIGN.md` *(new name; replaces top-level `ARCHITECTURE.md`)*
+
+> **Audience:** anyone wanting to understand the system at the cross-codebase level. This doc owns the four-codebase map, inter-codebase contracts, the secrets map (what secret lives where), the build matrix, and the global code-map index. **Does NOT own:** crypto pipeline details (see `docs/CRYPTO.md`), wire formats (see `docs/FORMATS.md`), threat model (see `docs/SECURITY.md`), per-crate module maps (see `crates/*/ARCHITECTURE.md` and `extension/ARCHITECTURE.md`).
+
+Footer: `Next: [docs/CRYPTO.md](docs/CRYPTO.md) — the crypto pipeline that backs this design.`
+
+### `docs/CRYPTO.md` *(new name; renamed from `docs/ARCHITECTURE.md`)*
+
+> **Audience:** anyone evaluating or auditing the crypto. This doc owns Argon2id parameters and rationale, XChaCha20-Poly1305 rationale, vault creation/unlock flow diagrams, DCT-steganography embed and extract flows, and the high-level encrypted-file-format diagram. **Does NOT own:** byte-level schemas or JSON shapes (see `docs/FORMATS.md`), attacker scenarios (see `docs/SECURITY.md`), or per-module crypto implementation (see `crates/relicario-core/ARCHITECTURE.md`).
+
+Footer: `Next: [FORMATS.md](FORMATS.md) — the byte-level wire formats.`
+
+### `docs/FORMATS.md` *(moved from repo root)*
+
+> **Audience:** anyone implementing a compatible client or reading raw vault bytes. This doc owns the `.enc` blob layout, `params.json` / `salt` / `devices.json` / `revoked.json` shapes, the manifest JSON schema, the `.relbak` envelope, item-ID formats, and the settings JSON schema. **Does NOT own:** why these formats look this way (see `docs/CRYPTO.md`), threat model around them (see `docs/SECURITY.md`), or Rust struct internals (see `crates/relicario-core/ARCHITECTURE.md`).
+
+Footer: `Next: [SECURITY.md](SECURITY.md) — the threat model.`
+
+### `docs/SECURITY.md` *(unchanged location)*
+
+> **Audience:** auditors and curious users. This doc owns the threat model, attacker-scenarios table, device-authentication model, env-var trust surface, and known limitations. **Does NOT own:** crypto primitive details (see `docs/CRYPTO.md`), wire formats (see `docs/FORMATS.md`), or implementation (see `crates/*/ARCHITECTURE.md`).
+
+Footer: `Next: [../crates/relicario-core/ARCHITECTURE.md](../crates/relicario-core/ARCHITECTURE.md) — implementation, starting with the platform-agnostic core.`
+
+### `crates/relicario-core/ARCHITECTURE.md`
+
+> **Audience:** contributors editing or extending `relicario-core`. This doc owns the module map for this crate, module-level invariants (e.g., no filesystem, no network), key flows at the module level, and the crate's test architecture. **Does NOT own:** crypto primitives or threat model (see `docs/CRYPTO.md`, `docs/SECURITY.md`), wire formats (see `docs/FORMATS.md`).
+
+Footer: `Next: [../relicario-cli/ARCHITECTURE.md](../relicario-cli/ARCHITECTURE.md) — how the CLI wraps the core.`
+
+### `crates/relicario-cli/ARCHITECTURE.md`
+
+> **Audience:** contributors editing the CLI. This doc owns the CLI module map, the clap command surface, per-command key flows, session/unlock semantics, and helpers. **Does NOT own:** crypto, wire formats, or threat model (see `docs/`).
+
+Footer: `Next: [../../extension/ARCHITECTURE.md](../../extension/ARCHITECTURE.md) — the browser-side surface.`
+
+### `extension/ARCHITECTURE.md`
+
+> **Audience:** contributors editing the browser extension. This doc owns the bundle structure (popup, vault tab, background SW, content scripts), the SW ↔ popup message contract, the component / pane architecture, routing, and the build pipeline. **Does NOT own:** WASM crypto internals (see `crates/relicario-core/ARCHITECTURE.md`), wire formats (see `docs/FORMATS.md`), or threat model (see `docs/SECURITY.md`).
+
+Footer: `End of tour. For roadmap and in-flight work see [../STATUS.md](../STATUS.md) and [../ROADMAP.md](../ROADMAP.md).`
+
+## Migration
+
+Five sequential commits. Each is mechanical; no content is rewritten.
+
+### Commit 1 — Renames
+
+```bash
+git mv ARCHITECTURE.md DESIGN.md
+git mv docs/ARCHITECTURE.md docs/CRYPTO.md
+git mv FORMATS.md docs/FORMATS.md
+```
+
+No content changes. Git tracks the renames so `git blame` / `git log --follow` survive.
+
+### Commit 2 — Scope headers + "Next:" footers on the eight tour docs
+
+Add the headers and footers verbatim as listed in the **Per-file scope definitions** section above. Also trim `README.md`'s current "Architecture" section to a one-paragraph pointer at `DESIGN.md` in the same commit.
+
+### Commit 3 — Fix incoming links to old paths
+
+Greppable list of paths to update:
+
+| Old path | New path |
+|---|---|
+| `ARCHITECTURE.md` (top-level reference) | `DESIGN.md` |
+| `docs/ARCHITECTURE.md` | `docs/CRYPTO.md` |
+| `FORMATS.md` (top-level reference) | `docs/FORMATS.md` |
+
+Known callsites to update:
+
+- `CLAUDE.md` — the "Living docs — update discipline" table + the "Planning & design specs" core-references list.
+- `README.md` — the architecture tree on line ~160 shows `docs/architecture/` which doesn't exist; fix in this pass.
+- `crates/*/ARCHITECTURE.md` and `extension/ARCHITECTURE.md` — cross-references to top-level ARCHITECTURE.md or FORMATS.md.
+- `docs/superpowers/specs/*.md` — some specs reference the old paths; update those whose specs are still load-bearing.
+
+Verification command (run before this commit):
+
+```bash
+grep -rn --include='*.md' -E '(\bARCHITECTURE\.md\b|\bdocs/ARCHITECTURE\.md\b|\b/FORMATS\.md\b|^FORMATS\.md\b)' . \
+  | grep -v docs/superpowers/test-runs/ \
+  | grep -v docs/superpowers/audits/
+```
+
+The grep should return zero matches after this commit (modulo intentional references in audit / test-run history, which we leave alone).
+
+### Commit 4 — Update `CLAUDE.md`
+
+Two changes to `CLAUDE.md`:
+
+1. Update the "Living docs — update discipline" table with the new filenames (`DESIGN.md`, `docs/CRYPTO.md`, `docs/FORMATS.md`).
+2. Add three new rules (see **Maintenance discipline** below).
+3. Update the "Planning & design specs" core-references list to point at `docs/CRYPTO.md` / `docs/FORMATS.md` if it currently points elsewhere.
+
+### Commit 5 — Verification
+
+A read-through commit (no content changes; this is just where we confirm the work). The verification checklist in the **Verification** section below runs cleanly. If it doesn't, fix and amend the relevant commit.
+
+## Maintenance discipline
+
+Three rules added to `CLAUDE.md` to prevent the kind of drift the audit found:
+
+1. **Scope-boundary check.** When editing a tour doc, verify the change fits the doc's scope header. If it doesn't, the change belongs in a different doc — move it instead of stretching the scope. (Concretely: a sentence about crypto added to `DESIGN.md` belongs in `docs/CRYPTO.md`; a wire-format table added to `docs/CRYPTO.md` belongs in `docs/FORMATS.md`.)
+
+2. **Code-constant pinning.** When a tour doc cites a code constant (`VERSION_BYTE = 0x02`, `QUANT_STEP = 50.0`, `MIN_COPIES = 5`, `MANIFEST_SCHEMA_VERSION = 2`, etc.), the doc must cite the source file + line. When the underlying constant changes, grep for the citation pattern and update the docs together with the code change in the same commit. Most of the drift the audit found was code-constant drift; this rule attacks it at the source.
+
+3. **New-doc rule.** When adding a tour doc, also update (a) `DESIGN.md`'s code-map, (b) the reading-order sequence (the "Next:" footer chain), and (c) the `CLAUDE.md` living-docs table. A new doc that doesn't appear in all three is not done.
+
+## Verification
+
+Run as part of Commit 5. All checks must pass.
+
+1. **Scope-header presence.** Every tour doc (`README`, `DESIGN`, `docs/CRYPTO`, `docs/FORMATS`, `docs/SECURITY`, `crates/relicario-core/ARCHITECTURE`, `crates/relicario-cli/ARCHITECTURE`, `extension/ARCHITECTURE`) has its scope header at the top, matching the wording in this spec.
+
+2. **"Next:" footer chain.** Each tour doc except `extension/ARCHITECTURE.md` ends with a `Next:` footer pointing at the next doc in the canonical order. `extension/ARCHITECTURE.md` ends with the "End of tour" pointer at STATUS/ROADMAP.
+
+3. **No broken links.** Every link in every tour doc resolves to an existing file. Verified with a markdown link checker or by hand-grepping for `](./` / `](../` references and confirming the target exists.
+
+4. **No old paths remain.** The grep in Commit 3 returns zero matches outside `docs/superpowers/test-runs/` and `docs/superpowers/audits/`.
+
+5. **`CLAUDE.md` table is current.** The "Living docs — update discipline" table lists the new filenames; the three new discipline rules are present.
+
+6. **Renames are git-tracked.** `git log --follow DESIGN.md` shows history continuous from the old `ARCHITECTURE.md`. Same for `docs/CRYPTO.md` and `docs/FORMATS.md`.
+
+7. **README architecture section trimmed.** `README.md`'s mid-section "Architecture" is at most one paragraph and points at `DESIGN.md`.
+
+## Out-of-scope safeties
+
+Things this design intentionally does *not* address; flagging for honesty:
+
+- **STATUS.md drift habit** (shipped work lingering as "in progress"): a behavioural issue, not structural. The audit caught it; the fix was manual. A future pass might add a release-checklist hook or a pre-tag CI gate.
+- **Per-crate `ARCHITECTURE.md` line-citation drift** (e.g., `main.rs:NNNN` references stale after handlers moved into `commands/`): partially addressed by rule 2 (code-constant pinning), but not fully. A future habit nudge — cite by function name, not by line number — is worth landing later but is cross-cutting and out of scope here.
+- **`docs/superpowers/specs/` and `plans/` accumulation**: intentional. Not touched.
+
+## Footnote — alternative approaches considered
+
+Three approaches were brainstormed before settling on this design (full details in the conversation that produced this spec, archived nowhere because that's how brainstorms work):
+
+- **Approach B — README expands; supporting docs collapse.** Fold the top-level `ARCHITECTURE.md` and `docs/ARCHITECTURE.md` into one big doc (or into README). Rejected: the combined doc gets long, and "organic flow" suffers when one doc covers from quick-start to crypto pipeline to module boundaries. README starts to do too much.
+- **Approach C — Keep current files, add reading paths.** Add a top-level `READING-ORDER.md` and grow scope headers on each existing doc. Rejected: doesn't fix the three-files-named-`ARCHITECTURE.md` cognitive cost. The drift surface stays the same; we just navigate it better.
+- **Approach A — Tour-shaped + topic-named** *(chosen).* Filenames carry meaning, linear flow is unambiguous, drift surface shrinks by killing the 3× `ARCHITECTURE.md` overload.