feat(ext/setup): wizard Style C progress track, glyph mode icons, recovery QR banner

- Replace dot-based progress indicator with colored horizontal segment track
  (completed=green, active=gold, pending=border) via renderProgressTrack()
- Add SETUP_STEP_NAMES constant for track segment titles
- Update Step 0 mode cards with glyph icons (◈ create, ⌥ attach)
- Add recovery QR banner in Step 5 (new-vault only, verifiedHandle present)
  with Generate now / Skip buttons wired in attachStep5()
- Add CSS for .setup-progress-track, .setup-progress-segment variants,
  and .recovery-qr-banner to styles.css

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

.claude/settings.json

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

.gitignore

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

CHANGELOG.md

@@ -0,0 +1,218 @@
+# Changelog
+
+## v0.5.0 — 2026-05-02
+
+Three release trains roll into one tag — backup/restore + LastPass
+import (originally v0.3.0), device authentication (originally v0.4.0),
+and the v0.5.0 polish + harden bundle (security fixes + UX fixes +
+two confirmed bugs).
+
+### Security
+
+- **Pre-receive hook now actually verifies signatures (audit S1, HIGH).**
+  Earlier `relicario-server` builds accepted any commit with a
+  `Good signature` line on stderr regardless of which key signed it —
+  device-auth was a no-op. The hook now builds an `allowed_signers`
+  file from `devices.json` at the commit (via `GIT_CONFIG_*` env, no
+  global git-config mutation), parses the SSH SHA-256 fingerprint out
+  of `git verify-commit --raw` stderr, and rejects unregistered keys or
+  revoked keys whose committer-date is at or after the revocation
+  timestamp. Bootstrap mode is preserved only when **both**
+  `devices.json` AND `revoked.json` are empty (closes an
+  empty-devices.json privilege-escalation route).
+- **Backup-restore tar unpacking hardened (audit S2).** `relicario
+  backup restore` no longer trusts `tar::Archive::unpack`'s defaults.
+  A new `relicario_core::safe_unpack_git_archive` validates each
+  entry's path components (rejects `..`, absolute paths, Windows
+  drive prefixes), rejects symlinks/hardlinks, and caps total
+  uncompressed size at the lower of 100×compressed-bytes or 1 GiB.
+  The CLI restore path adds a paranoid `dest.starts_with(.git/)`
+  check after path-joining as defense-in-depth.
+- **`RELICARIO_*` env-var surface audited (audit S3).** `docs/SECURITY.md`
+  gains a per-variable trust table. `RELICARIO_NO_GROUPS_CACHE` (a
+  developer escape hatch, not a user knob) is now
+  `cfg(debug_assertions)`-gated and is a no-op in `--release` builds;
+  the env-var lookup is removed from the binary by the optimiser.
+
+### Fixed
+
+- **Strength meter no longer goes stale after the regenerate button (B1).**
+  Programmatic `input.value = newPassword` doesn't fire `input`
+  events; the regenerate handler now dispatches a synthetic
+  `InputEvent('input', { bubbles: true })` so the meter listener
+  re-rates the new value.
+- **Snake_case error codes no longer leak into the UI (B2 / P4).**
+  Errors like `vault_locked`, `origin_mismatch`, `unauthorized_sender`
+  used to render verbatim in the fullscreen vault tab and (in some
+  cases) the popup. New `extension/src/shared/error-copy.ts` central
+  registry maps every service-worker error code to friendly
+  title/body/CTA copy; the popup and fullscreen tab consume the
+  same map. The fullscreen lock screen's `vault_locked` block now
+  reads `Vault locked / Unlock your vault to continue. / [Unlock
+  vault]`. A generated test enumerates the live error codes via
+  grep so the registry can't drift.
+
+### Added
+
+- **Sidebar logo in the fullscreen vault tab.** The
+  `vault-sidebar__header` now renders the 16-optimized SVG logo
+  inline before the "Relicario" wordmark (20×20 px, `flex-shrink: 0`
+  so it survives narrow-pane wraps). Popup unaffected.
+- **Password coloring (P1).** Revealed passwords in the popup
+  item-detail, fullscreen item view, field-history viewer, and
+  generator preview render digits and symbols in distinct colors.
+  Defaults: blue digits, red symbols. Users can override via the
+  new Display section in settings (color pickers + live preview
+  swatch + reset). Defaults round-trip via
+  `chrome.storage.sync.password_display_scheme`; cross-device when
+  Chrome sync is enabled.
+- **Setup wizard hands off to the fullscreen vault tab on completion
+  (P2).** Both create-new and attach-existing flows now open
+  `vault.html` in a new tab and best-effort close the setup tab
+  after device registration succeeds — replaces the prior
+  setup-tab-stays-open terminal screen.
+- **Sync now button** in the extension settings view — surfaces the
+  previously hidden `{ type: 'sync' }` SW message to users with success /
+  error feedback.
+- **Device registration from the popup.** The "Register this device"
+  button on the devices view now opens an inline name input and (on
+  confirm) generates a keypair via WASM, persists the private key + name
+  locally, and writes the device to the remote — no setup-wizard detour.
+  Backed by a new `register_this_device` SW message.
+- **`relicario settings generator-defaults`** — view-and-edit access to the
+  generator defaults stored in `VaultSettings`. Flags: `--random` /
+  `--bip39` to switch mode, `--length`, `--words`, `--symbols`,
+  `--separator` to update fields of the active mode.
+- **`relicario edit` now supports TOTP items.** Issuer, label, and secret
+  rotation work; rotated secrets are pushed to `field_history` (key:
+  `core:totp_secret`).
+- **`relicario history <query>`** — view captured field history. Values
+  are masked by default; `--show` reveals them; `--field <name>` filters
+  to one synthetic key (e.g. `login_password`, `totp_secret`).
+- **`relicario detach <query> <aid>`** — remove an individual attachment
+  from an item. Refuses to drop a Document item's primary attachment
+  (use `purge` instead).
+- **`relicario status`** — vault summary: root path, item count
+  (active / trashed), attachment count + total bytes, registered device
+  count, last commit (`%h %s`).
+- **Backup & restore.** New `relicario backup export <out.relbak>` and
+  `relicario backup restore <in.relbak> [<dir>]` commands. The `.relbak`
+  format is a single encrypted file: Argon2id-derived key from a
+  user-chosen backup passphrase (independent of the vault factor),
+  XChaCha20-Poly1305 ciphertext, zstd-compressed JSON envelope.
+  Reference image and `.git/` history are opt-in inclusions
+  (`--include-image`, `--no-history`).
+- **Vault-tab Backup & Restore panel.** Export downloads the
+  `.relbak` via `chrome.downloads`. Restore takes a file + backup
+  passphrase + new-remote config and writes the vault into a fresh
+  empty repo (refuses to clobber existing). Git history is never
+  bundled from the extension — CLI is the source of full backups.
+- **LastPass CSV import.** New `relicario import lastpass <csv>`
+  command + vault-tab Import panel (`vault.html#import`).
+  Logins map to `Login` items; rows with `url == "http://sn"`
+  map to `SecureNote` (extra column → body verbatim, structured
+  data preserved as-is for manual re-categorization). TOTP
+  secrets in the `totp` column are base32-decoded into
+  `LoginCore.totp`; bad base32 surfaces a warning and the login
+  is imported without TOTP. Failed rows (missing `name`, missing
+  password on a login) are skipped with a per-row warning.
+  Each row gets a freshly-minted ID — re-running the import
+  creates duplicates rather than corrupting state.
+- **Popup deep link to the Import panel.** `settings-vault`
+  gains an "import" section with a `LastPass CSV →` button
+  next to the existing `Backup & restore →` button.
+- **`relicario status` shows last export age.** New `Last export:
+  <human-readable>` line reading `.relicario/last_backup` (a marker
+  file `cmd_backup_export` writes on success). Reads "never" for
+  fresh vaults, "4 days ago" otherwise.
+
+### Changed
+
+- **Form layout in the fullscreen vault tab is now visually consistent
+  (P3).** Notes, custom-fields disclosure, attachments disclosure, and
+  form-actions in fullscreen logins now sit inside a `.form-lower`
+  wrapper with the same `max-width: 960px; margin: 0 auto` envelope as
+  the `.form-grid` cards above. Removes the visual rhythm break at the
+  2-col → full-width transition. The popup surface is unchanged.
+- **Documentation refreshed for v0.5.0 (doc audit, 14 findings).**
+  `docs/architecture/overview.md` now describes four codebases (the
+  `relicario-server` pre-receive hook crate is no longer invisible);
+  `CLAUDE.md` project tree and roadmap reflect current state;
+  `docs/SECURITY.md` names the server crate and its `verify-commit` /
+  `generate-hook` subcommands and notes the without-the-hook-it's-
+  advisory caveat; `docs/ARCHITECTURE.md` shows `settings.enc` as a
+  parallel artifact in the vault-creation flow; the foundational
+  design spec gains a "historical" status banner pointing readers at
+  the current docs.
+- `relicario generate` now consults `VaultSettings.generator_defaults` when
+  invoked inside an initialized vault. Explicit flags (`--length`,
+  `--bip39`, `--words`, `--symbols`, `--separator`) override the vault
+  default. Outside a vault, behavior is unchanged (length 20, safe symbol
+  set, 5 BIP39 words, space separator).
+
+### Known limitations
+
+- **Mid-restore failure leaves the target remote in a half-written
+  state.** `cmd_backup_restore` and the vault-tab Restore panel both
+  write artifacts sequentially via `writeFileCreateOnly`. If the
+  process is interrupted partway, a retry against the same remote
+  refuses to clobber. Workaround: delete the partial repo and retry.
+- **Cross-tool backup compatibility.** CLI-exported backups stored
+  attachments at `<item_id>/<aid>.enc`; extension stores at flat
+  `<aid>.bin`. The `.relbak` envelope canonicalizes to `<item_id>/<aid>`
+  keys and each tool translates at the boundary. Round-trip works in
+  both directions.
+
+### Internal
+
+- 5 stale local feature branches and 3 worktrees pruned (audit C1).
+- Pre-existing clippy warnings cleaned up across `relicario-{core,cli}`
+  (deref operators, `Option::is_none_or` over `map_or(true, ...)`,
+  `iter_mut().enumerate()` patterns, `div_ceil()`) so the workspace
+  builds clean under `-D warnings`.
+- `Cargo.lock` regenerated and committed; was stale since the
+  `--totp-qr` commit.
+- Refactored `cmd_add` and `cmd_edit` in the CLI: each `ItemCore` variant
+  now has its own `build_*_item` / `edit_*` helper. Pure mechanical
+  extraction; behavior unchanged. The dispatcher matches and delegates.
+- Extracted pure helpers (`escapeHtml`, `ratePassphrase`, `scheduleRate`,
+  `entropyText`, `STRENGTH_LABELS`) from `extension/src/setup/setup.ts`
+  into `setup-helpers.ts`. State-coupled `updateStrengthUi` stays in
+  `setup.ts` since it walks live wizard state. Setup.ts went from
+  1205 → 1137 lines.
+
+## v0.2.0 — 2026-04-27
+
+### Fixed
+
+- **Setup wizard could silently overwrite an existing vault.** Pointing the
+  wizard at a remote that already contained a Relicario vault would clobber
+  `manifest.enc`, `.relicario/salt`, and friends with no warning. The wizard
+  now probes the remote after the connection test and refuses to create a
+  new vault on top of an existing one. Affected users whose vault was wiped
+  by this bug should restore from the git history of the affected repo
+  (`git log` + `git checkout <pre-init-sha> -- .`).
+- **New devices registered during initial setup were silently dropped.** The
+  wizard's Step 5 fired `add_device` over a service-worker channel that
+  required an unlocked vault, which is unavailable mid-wizard. Device pubkeys
+  now write directly to `.relicario/devices.json` from the wizard.
+- **Wizard-created vaults were missing `settings.enc`.** The CLI's `init`
+  writes a default-`VaultSettings` `settings.enc` alongside `manifest.enc`,
+  but the wizard skipped it, causing every `get_vault_settings` SW call to
+  404. The wizard now encrypts and writes `settings.enc` using a new
+  `default_vault_settings_json` WASM helper that keeps defaults in sync
+  with Rust core.
+
+### Added
+
+- **Attach this device to an existing vault — purely from the GUI.** New
+  Step 0 mode picker splits the wizard into "create new vault" and "attach
+  this device." The attach path takes a passphrase + reference image, fetches
+  the existing manifest, verifies the credentials by decrypting it, and only
+  then registers a new device key. No CLI required for multi-device setup.
+- `GitHost.lastCommit(path)` and `GitHost.writeFileCreateOnly(path, ...)`.
+- `default_vault_settings_json()` WASM export.
+
+## v0.1.0 — 2026-04-22
+
+Initial release.

CLAUDE.md

@@ -1,8 +1,15 @@
-# CLAUDE.md — relicario
+# CLAUDE.md — Relicario
+
+## Working with the user
+
+- **Default to "yes" / the recommended option.** When asking the user a multiple-choice or yes/no decision, pick the recommended answer and proceed without prompting. Optional follow-ups in checklists: do them. Subagent dispatch / running tests / writing code: proceed without checking.
+- **Always pause and ask** before: `rm`, `rm -rf`, `git push --force`, `git reset --hard`, `git branch -D`, deleting files via Bash, dropping tables, force-pushing to main. The system-prompt's "executing actions with care" guidance still applies — this preference does not override that.
+- This rule does not override genuine intent-discovery: brainstorming-skill clarifying questions about *what to build* still need user input, because picking a default would mean designing the wrong product.
+- **Sprinkle Mexican Spanish into replies.** Drop 1–2 Spanish words, slang, exclamations, or idioms per reply (replies only — never in code, file contents, commit messages, or other project artifacts), each followed by `[translation]` in square brackets. Mexican flavor is preferred: ¡órale! [alright!], ¡híjole! [yikes!], ¿qué onda? [what's up?], chido [cool], ahorita [right now / in a bit], no manches [no way], ni modo [oh well], no hay bronca [no problem], ¡ya estuvo! [it's done], etc. Skip in one-word acknowledgements where the flourish would feel awkward.
 
 ## What is this
 
-relicario is a git-backed, self-hostable password manager with a Rust core. Two-factor vault decryption: passphrase + a reference JPEG carrying a 256-bit secret embedded via DCT steganography. The server only ever sees opaque ciphertext.
+Relicario is a git-backed, self-hostable password manager with a Rust core. Two-factor vault decryption: passphrase + a reference JPEG carrying a 256-bit secret embedded via DCT steganography. The server only ever sees opaque ciphertext.
 
 ## Build and test
 
@@ -41,9 +48,11 @@ crates/
 │   ├── src/helpers.rs      # vault_dir, git_command, iso8601
 │   ├── src/session.rs      # UnlockedVault (master key in Zeroizing)
 │   └── tests/              # basic_flows, edit_and_history, attachments, settings, vault_detection
-└── relicario-wasm/            # WASM bindings for the extension
-    ├── src/lib.rs          # #[wasm_bindgen] surface
-    └── src/session.rs      # opaque SessionHandle → Zeroizing<[u8;32]>
+├── relicario-wasm/            # WASM bindings for the extension
+│   ├── src/lib.rs          # #[wasm_bindgen] surface
+│   └── src/session.rs      # opaque SessionHandle → Zeroizing<[u8;32]>
+└── relicario-server/          # `relicario-server` binary (pre-receive Git hook)
+    └── src/main.rs         # verify-commit + generate-hook subcommands
 ```
 
 ## Key design decisions
@@ -69,7 +78,7 @@ passphrase (UTF-8 bytes) || image_secret (32 bytes from reference JPEG)
 
 - Tests use fast Argon2id params (m=256, t=1, p=1) so they don't take forever.
 - Test JPEGs are generated synthetically via `make_test_jpeg()` — no binary test fixtures.
-- Item IDs are random 8-char hex strings.
+- Item IDs and Field IDs are random 16-char hex strings (64 bits of OsRng entropy). AttachmentIds are content-addressed: first 32 hex chars of SHA-256 over the plaintext (128 bits).
 - Git history is preserved as an audit log — no squashing.
 - The CLI shells out to `git` for sync — no libgit2/gitoxide dependency.
 
@@ -83,4 +92,4 @@ Full threat model, entropy analysis, and architecture: `docs/superpowers/specs/2
 
 ## Roadmap
 
-Next: WASM build + Chrome MV3 browser extension (Plan 2). Then mobile (Rust core compiles to ARM).
+Next: v0.5.0 polish + harden (in progress). After that, Phases 3/4 of the fullscreen UX redesign (vault-tab shell + command palette), Plan 1C-γ (attachments + Document + trash/history/device UI), and the LastPass importer. Mobile (Rust core compiles to ARM) and recovery QR remain on the roadmap.

Cargo.toml

@@ -4,4 +4,5 @@ members = [
     "crates/relicario-core",
     "crates/relicario-cli",
     "crates/relicario-wasm",
+    "crates/relicario-server",
 ]

README.md

@@ -1,8 +1,8 @@
 <p align="center">
-  <img src="extension/icons/relicario-logo.svg" alt="relicario" width="128" height="128">
+  <img src="extension/icons/relicario-logo.svg" alt="Relicario" width="128" height="128">
 </p>
 
-# relicario
+# Relicario
 
 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.
 
@@ -23,7 +23,7 @@ Your reference photo (something you have)
    your device                                                         (opaque ciphertext)
 ```
 
-At vault creation, relicario embeds a random 256-bit secret into a carrier JPEG using DCT steganography. This photo becomes your **reference image** — a second factor that lives on your devices (and optionally as a "dead drop" on social media, since it survives JPEG re-encoding and mild cropping).
+At vault creation, Relicario embeds a random 256-bit secret into a carrier JPEG using DCT steganography. This photo becomes your **reference image** — a second factor that lives on your devices (and optionally as a "dead drop" on social media, since it survives JPEG re-encoding and mild cropping).
 
 To unlock the vault, you provide your passphrase and point the client at the reference image. The client extracts the hidden secret, concatenates it with your passphrase, and runs Argon2id to derive the master key. Everything else follows from there.
 
@@ -33,7 +33,9 @@ To unlock the vault, you provide your passphrase and point the client at the ref
 
 A git repository containing:
 - `manifest.enc` — opaque binary blob
-- `entries/*.enc` — more opaque binary blobs
+- `items/*.enc` — more opaque binary blobs
+- `attachments/<item-id>/*.enc` — encrypted attachment blobs
+- `settings.enc` — encrypted vault settings
 - `.relicario/salt` — a random 32-byte value (not secret)
 - `.relicario/params.json` — Argon2id parameters (not secret)
 - `.relicario/devices.json` — authorized device public keys
@@ -58,7 +60,7 @@ No single point of failure. The two-factor design means the passphrase alone can
 | LastPass | ~40-60 bits (master password only) | 1 |
 | Bitwarden | ~40-60 bits (master password only) | 1 |
 | 1Password | password + 128-bit Secret Key | 2 |
-| **relicario** | **password + 256-bit image secret** | **2** |
+| **Relicario** | **password + 256-bit image secret** | **2** |
 
 ### What we don't protect against
 
@@ -114,12 +116,23 @@ relicario/
 │   ├── 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
-│   │   ├── entry.rs     # Entry, Manifest data model (serde)
-│   │   └── vault.rs     # Encrypt/decrypt entries and manifests
-│   └── relicario-cli/      # CLI binary: filesystem, git, terminal I/O
+│   │   ├── 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 specification with full threat model
+        └── specs/         # Design specifications with full threat model
 ```
 
 `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).
@@ -144,17 +157,22 @@ Every write generates a fresh random nonce. The version byte allows future forma
 
 ```
 my-vault.git/
-├── manifest.enc          # Encrypted entry index (names, URLs, timestamps)
-├── entries/
-│   ├── a1b2c3d4.enc     # One encrypted entry per file
-│   └── e5f6a7b8.enc
+├── manifest.enc          # Encrypted item index (names, URLs, timestamps)
+├── settings.enc          # Encrypted vault settings (retention, caps, generator defaults)
+├── items/
+│   ├── a1b2c3d4e5f6a7b8.enc   # One encrypted item per file
+│   └── …
+├── attachments/
+│   └── <item-id>/
+│       └── <aid>.enc     # Content-addressed encrypted attachment blob
 └── .relicario/
     ├── salt              # 32-byte random salt (not secret)
     ├── params.json       # KDF parameters
-    └── devices.json      # Authorized device public keys
+    ├── devices.json      # Authorized device public keys
+    └── revoked.json      # Revoked device records (when device auth is enabled)
 ```
 
-Entry IDs are random hex strings. Git history is preserved — every add/edit/delete is a commit. "When was this password last rotated?" is answered by `git log`.
+Item IDs are random 16-char hex strings (64 bits of entropy). Git history is preserved — every add/edit/delete is a commit. "When was this password last rotated?" is answered by `git log` and by the per-item field history.
 
 ## Device management
 
@@ -183,13 +201,17 @@ The binary is at `target/release/relicario`.
 
 ## Roadmap
 
-- [ ] WASM build + Chrome browser extension (inline crypto, no native messaging)
-- [ ] Secure notes (free-form encrypted text entries)
-- [ ] Secure document storage (encrypted file attachments up to 5-10 MB)
+- [x] WASM build + Chrome MV3 browser extension (inline crypto, no native messaging)
+- [x] Firefox WebExtension build
+- [x] Typed items: Login, SecureNote, Identity, Card, Key, Document, TOTP
+- [x] Secure document storage (encrypted file attachments)
+- [x] Backup & restore (`.relbak` encrypted envelope)
+- [x] LastPass CSV import
+- [x] Device authentication (ed25519 commit signing + pre-receive hook)
+- [ ] Import from Bitwarden / 1Password
 - [ ] `relicario unlock` daemon (ssh-agent-style, holds master key for a TTL)
 - [ ] Android/iOS clients (Rust core compiles to ARM)
-- [ ] Import from LastPass/Bitwarden/1Password
-- [ ] Firefox/Safari extensions
+- [ ] Safari extension
 
 ## License
 

crates/relicario-cli/ARCHITECTURE.md

@@ -0,0 +1,539 @@
+# Architecture: relicario-cli
+
+## What this crate is for
+
+The `relicario` binary is the platform layer for `relicario-core`: it adds
+filesystem layout, a hardened `git` shell-out, interactive `rpassword` prompts,
+clipboard handoff, and a clap-based command surface. The crate has two design
+roles. First, it is the developer / power-user surface that exposes everything
+the core can do (every `ItemCore` variant, every `VaultSettings` knob, history
+inspection, device key management). Second, it is the only working interface
+during disaster recovery — the extension may be uninstalled, the device may be
+new — so it intentionally maintains feature parity with the extension's vault
+tab. It deliberately shells out to `git` rather than depending on libgit2 /
+gitoxide; this keeps the dep tree slim, lets the user override `git` config
+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`** (`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/session.rs`** (`session.rs:1-152`) — `UnlockedVault` lifecycle. Holds
+  the derived master key in `Zeroizing<[u8; 32]>` for one CLI invocation; the
+  key wipes via `Zeroize` on scope exit (`session.rs:22-25`). Owns the
+  `unlock_interactive` flow (vault root walk → salt read → params read →
+  reference image extract → passphrase prompt → KDF) at `session.rs:33-59`,
+  the typed `load_*` / `save_*` accessors for `Item` / `Manifest` /
+  `VaultSettings`, the `read_salt` / `read_params` helpers, the
+  `RELICARIO_IMAGE` lookup, and `atomic_write` (`session.rs:144-151`) which
+  every disk write to a vault file goes through. Owns the env-var escape
+  hatches `RELICARIO_TEST_PASSPHRASE` (`session.rs:42`) and `RELICARIO_IMAGE`
+  (`session.rs:125`) that integration tests use to bypass the TTY.
+
+- **`src/helpers.rs`** (`helpers.rs:1-101`) — pure, no-state plumbing:
+  `find_vault_dir_from` (`helpers.rs:14-28`) walks up parent directories
+  looking for a `.relicario/` marker; `vault_dir` and `relicario_dir` wrap it
+  for `cwd`-rooted callers; `git_command` (`helpers.rs:45-55`) is the
+  hardened-`git` factory that every git invocation in the crate (production
+  code, not tests) goes through; `iso8601` (`helpers.rs:60-64`) formats Unix
+  seconds for human-readable output (audit M11). The hardening is
+  load-bearing — see Invariants & Gotchas below.
+
+## Invariants & contracts
+
+These are the load-bearing rules the crate relies on. Each has been verified
+in code; cite the line if you change it.
+
+- **Every vault-mutating command unlocks via `UnlockedVault`.** The struct
+  holds the master key in `Zeroizing<[u8; 32]>` and drops via `Zeroize` on
+  scope exit (`session.rs:22-25`). No command bypasses this except
+  `cmd_generate` outside a vault dir and `cmd_init` (which derives the key
+  inline before there is a vault to unlock).
+
+- **Every `git` invocation in production code goes through
+  `helpers::git_command`.** A grep for `Command::new("git")` outside
+  `helpers.rs` finds zero hits in `src/`; the only other match is in
+  `tests/edit_and_history.rs:18`, which is test-side verification of the git
+  log and is exempt by design. `git_command` injects
+  `core.hooksPath=/dev/null`, `commit.gpgsign=false`, and `core.editor=true`
+  via `-c` flags (`helpers.rs:48-52`). Direct `Command::new("git")` would
+  bypass the hardening — don't.
+
+- **Every file write to a vault file uses `atomic_write`.** `atomic_write`
+  (`session.rs:144-151`) writes `<path>.tmp` then renames over `<path>`; a
+  partial write never appears as the live file. All `UnlockedVault::save_*`
+  helpers route through it. (`cmd_init` writes pre-creation files via
+  `fs::write` at `main.rs:373-393`; that path doesn't need atomicity because
+  the vault doesn't exist yet — failure leaves a half-built vault that the
+  next run rejects via `relicario_dir.exists()` at `main.rs:326`.)
+
+- **Every commit during a mutating command uses `commit_paths`.**
+  `commit_paths` (`main.rs:767-775`) does `git add <paths> && git commit -m
+  <msg>` through the hardened wrapper. Commit message convention is
+  `<verb>: <title> (<id>)` — `add:`, `edit:`, `trash:`, `restore:`, `purge:`,
+  `attach:`, `detach:`, `settings: update`, `device: add <name>`, `device:
+  revoke <name>`, `init: new relicario vault (format v2)`, `trash empty:
+  purged N item(s)`. `cmd_purge` and `cmd_trash_empty` and `cmd_device` use
+  `git_command` directly (not `commit_paths`) because they need a slightly
+  different add/commit pattern; they still go through the hardened wrapper.
+
+- **`cmd_generate` is the only command that runs without unlock — and only
+  when invoked outside a vault directory.** Inside a vault,
+  `cmd_generate` unlocks to read `settings.generator_defaults`
+  (`main.rs:1440-1445`); explicit flags override the stored defaults. This is
+  why the smoke-test `cargo run -p relicario-cli -- generate --length 32`
+  works without any setup.
+
+- **Item IDs are minted by core.** The CLI never constructs an `ItemId`
+  directly; `Item::new` (called inside every `build_*_item`) does it via
+  `relicario-core::ids::new_item_id`. `ItemId`s are 8-char hex.
+
+- **Manifest is always saved last.** Within a single command, the order is:
+  write item file → mutate manifest → save manifest → commit. If the process
+  dies between step 1 and step 3, the next run sees an item file with no
+  manifest entry; `cmd_status` / `cmd_list` ignore it because they read the
+  manifest, not the directory. (Recovery would manually re-`add` to surface
+  it.)
+
+- **Vault root is always discovered, never assumed to be `cwd`.**
+  `helpers::vault_dir` walks up from `cwd` looking for `.relicario/`, so any
+  command run from a subdirectory of the vault works (verified by
+  `vault_detection.rs:23-40`). v1 vaults using `.idfoto/` are naturally
+  rejected because they don't contain `.relicario/` — no compat shim needed
+  (`vault_detection.rs:42-59`).
+
+- **`prompt_secret` reads `RELICARIO_TEST_ITEM_SECRET` before falling back to
+  `rpassword`.** This is the only way integration tests can drive the
+  per-item secret prompts (Login password, Card number, TOTP secret rotation,
+  Key material) without a real TTY. The check is at `main.rs:308-313`.
+
+## Key flows
+
+### Vault init (`cmd_init`, `main.rs:315-418`)
+
+1. Refuse if `.relicario/` already exists (`main.rs:326-328`).
+2. Read passphrase twice (or once via `RELICARIO_TEST_PASSPHRASE`); confirm
+   they match; run `validate_passphrase_strength` (zxcvbn-backed) and bail
+   with audit-H3 message on weak input (`main.rs:331-348`).
+3. Generate a 32-byte random `image_secret` via `OsRng`, embed it into the
+   carrier JPEG via `imgsecret::embed`, write the stego output to `--output`
+   (`main.rs:351-360`).
+4. Generate a 32-byte salt and pin `KdfParams { argon2_m: 65536, argon2_t: 3,
+   argon2_p: 4 }` (production-grade) at `main.rs:363-365`.
+5. `derive_master_key(passphrase, image_secret, salt, params)` →
+   `Zeroizing<[u8;32]>` (`main.rs:368`).
+6. Create `.relicario/`, `items/`, `attachments/` dirs; write
+   `.relicario/{salt, params.json, devices.json}`; encrypt and write
+   `manifest.enc` (empty `Manifest::new()`) and `settings.enc`
+   (`VaultSettings::default()`) (`main.rs:370-393`).
+7. Write `.gitignore` listing the reference image filename (so the second
+   factor never accidentally ends up in git) (`main.rs:396-400`).
+8. `git init` then initial commit `init: new relicario vault (format v2)`
+   via `git_command` (`main.rs:403-412`). Note the initial commit does NOT
+   go through `commit_paths` — it precedes the existence of an
+   `UnlockedVault`, so the path list is hand-spelled.
+
+### Vault unlock (`UnlockedVault::unlock_interactive`, `session.rs:33-59`)
+
+1. `vault_dir()` walks up from cwd to find `.relicario/`; bails with the
+   "run `relicario init` first" message on miss (`helpers.rs:21-26`).
+2. `read_salt` reads `.relicario/salt` (32 bytes; rejects any other length).
+3. `read_params` deserializes `.relicario/params.json` and extracts the
+   nested `kdf` sub-object as `KdfParams` (`session.rs:110-121`). The nested
+   shape exists because `params.json` also stores `format_version`, `aead`,
+   and `salt_path` for forward-compat probing.
+4. `get_image_path` honours `RELICARIO_IMAGE`, then a `<vault>/reference.jpg`
+   convention, then prompts (`session.rs:124-140`).
+5. Read the reference image bytes; `imgsecret::extract` runs the DCT
+   majority-vote decode to recover the 32-byte image secret
+   (`session.rs:38-40`).
+6. Read the passphrase via `RELICARIO_TEST_PASSPHRASE` or `rpassword`
+   (`session.rs:42-49`).
+7. `derive_master_key` produces the master key; `UnlockedVault { root,
+   master_key }` is returned and lives until the command function returns.
+
+### Item add (`cmd_add`, `main.rs:419-456`)
+
+1. Unlock the vault and load the manifest.
+2. Match on the `AddKind` variant and dispatch to the matching
+   `build_<type>_item` helper (`main.rs:423-438`). Seven variants → seven
+   builders; only `build_document_item` takes `&UnlockedVault` because it
+   needs `attachment_caps` and writes the encrypted blob alongside the item.
+3. The builder returns a fully-populated `Item` (with title, group, tags,
+   favorite-flag, primary attachment if any).
+4. Common wrap-up: `vault.save_item(&item)`, `manifest.upsert(&item)`,
+   `vault.save_manifest(&manifest)`.
+5. Build the path list — `items/<id>.enc`, `manifest.enc`, plus one
+   `attachments/<id>/<aid>.enc` per attachment — and call `commit_paths`
+   with message `add: <title> (<id>)` (`main.rs:444-452`).
+
+### Item edit (`cmd_edit`, `main.rs:938-977`)
+
+1. Unlock, load manifest, resolve query → item id, load the item.
+2. Universally-editable fields (title, group, tags) are prompted via
+   `prompt_keep` / `prompt_keep_opt` first; blank input keeps the current
+   value (`main.rs:952-956`).
+3. Borrow `&mut item.field_history` once into a local `history` binding
+   (`main.rs:958`), then `match` on `&mut item.core` and dispatch to the
+   per-type `edit_<type>` helper (`main.rs:959-967`). The history-tracking
+   editors (`edit_login`, `edit_secure_note`, `edit_card`, `edit_key`,
+   `edit_totp`) take `&mut FieldHistory`; the others (`edit_identity`,
+   `edit_document_message`) don't.
+4. Each editor that mutates a tracked secret calls `push_history(history,
+   "<key>", old_value)` (`main.rs:1095-1109`) — see the History flow below
+   for the synthetic-key convention.
+5. `item.modified = now_unix()`, save, upsert manifest, commit
+   `edit: <title> (<id>)`.
+
+`edit_document_message` (`main.rs:1050-1052`) just prints "use `attach` /
+`extract` instead" — Document items can't be field-edited; they're
+attachment-shaped.
+
+The `FieldHistory` type alias (`main.rs:983-986`) is purely cosmetic; it
+exists so the editor signatures don't have to spell out the full
+`HashMap<FieldId, Vec<FieldHistoryEntry>>`.
+
+### History capture and view (`push_history` + `cmd_history`)
+
+`push_history` (`main.rs:1095-1109`) records an old value under a synthetic
+`FieldId(format!("core:{key}"))`. The `core:` prefix namespaces these keys so
+they can never collide with real custom-field UUIDs from the typed-item
+custom-fields work. The keys used in the codebase are:
+
+- `core:login_password` (`main.rs:998`)
+- `core:secure_note_body` (`main.rs:1012`)
+- `core:card_number` (`main.rs:1031`)
+- `core:key_material` (`main.rs:1045`)
+- `core:totp_secret` (`main.rs:1063`)
+
+`cmd_history` (`main.rs:1111-1159`) reads `item.field_history`, sorts the
+keys, strips the `core:` prefix for display, and prints each entry list
+masked or revealed depending on `--show`. The `--field <name>` filter
+matches against either the stripped name (`login_password`) or the raw key
+(`core:login_password`) so both forms work (`main.rs:1126-1129`). The
+`relicario history bank --field totp_secret` form is what
+`edit_and_history.rs` exercises.
+
+### Trash & purge (`cmd_rm` / `cmd_restore` / `cmd_purge` / `cmd_trash_empty`)
+
+- `cmd_rm` (`main.rs:1161-1176`) calls `Item::soft_delete()` (sets
+  `trashed_at`), saves, upserts manifest, commits `trash:`.
+- `cmd_restore` (`main.rs:1178-1193`) is the inverse: `Item::restore()`,
+  same wrap-up, commit `restore:`.
+- `cmd_purge` (`main.rs:1220-1237`) calls `purge_item` (`main.rs:1197-1218`)
+  which removes the item file, the attachment dir, the manifest entry, and
+  `git rm -rf --ignore-unmatch`s the paths. Then a single `git add
+  manifest.enc` + commit `purge: <title> (<id>)`.
+- `cmd_trash_empty` (`main.rs:1246-1282`) is the only multi-item mutating
+  command. It loads settings once, iterates all items past their
+  `trash_retention` window, calls `purge_item` for each, then does a single
+  `git add manifest.enc` + commit `trash empty: purged N item(s)`. The
+  single-unlock-per-batch shape was the fix in commit `b5015b3` — the
+  earlier version re-prompted for the passphrase per item.
+
+### Attach / detach / extract
+
+- `cmd_attach` (`main.rs:1283-1339`) loads `attachment_caps` from settings
+  and rejects if the item has hit `per_item_max_count`. `encrypt_attachment`
+  enforces `per_attachment_max_bytes`. The encrypted blob lands at
+  `attachments/<item_id>/<aid>.enc`; the `aid` is content-addressed by core.
+  Commit message: `attach: <file> → <title> (<id>)`.
+- `cmd_detach` (`main.rs:1376-1424`, added in `3f0f5b1`) removes one
+  attachment from the item, deletes the encrypted blob, rewrites the item.
+  Refuses if the target `aid` is a `Document` item's `primary_attachment`
+  (`main.rs:1392-1400`) — that would orphan the item; use `purge` instead.
+  Commit message: `detach: <filename> from <title> (<id>)`.
+- `cmd_extract` (`main.rs:1354-1375`) decrypts the blob and writes the
+  plaintext to `--out` or to `<filename>` in cwd. Read-only: no commit, no
+  state mutation.
+- `cmd_attachments` (`main.rs:1341-1352`) lists `aid`, size, mime, filename
+  — read-only.
+
+### Generate (`cmd_generate`, `main.rs:1426-1489`)
+
+Has two distinct modes:
+
+- **Outside a vault** — `vault_dir()` returns `Err`; `vault_defaults` stays
+  `None`; defaults are hard-coded (`length: 20`, `symbols: SafeOnly`,
+  `words: 5`, `separator: " "`, `Capitalization::Lower`). No unlock prompt.
+- **Inside a vault** — `vault_dir()` succeeds; full unlock; load
+  `settings.generator_defaults`. Explicit flags override the stored defaults
+  field-by-field. `--bip39` flips mode; absent that flag, the mode is
+  whatever the stored default is. Tests:
+  `settings.rs::generate_uses_vault_default_length` (length-tracking) and
+  `basic_flows.rs::generate_random_and_bip39` (no-vault smoke).
+
+The two-mode shape is deliberate (see Gotchas) and is why `cmd_generate` is
+the only command outside `cmd_init` that touches `helpers::vault_dir()`
+directly instead of going through `UnlockedVault::unlock_interactive()`.
+
+### Sync (`cmd_sync`, `main.rs:1582-1590`)
+
+`git pull --rebase` then `git push`, both via the hardened wrapper. No
+unlock — sync moves opaque ciphertext, the master key is never needed. This
+is the only command that fails on conflict; it doesn't try to resolve.
+Resolution happens manually in the user's git tooling.
+
+### Status (`cmd_status`, `main.rs:1592-1631`, added in `3f0f5b1`)
+
+Unlocks; loads manifest; counts items (active vs trashed), attachments
+(count + total bytes), devices (parsed from `devices.json`); shells out to
+`git log -1 --pretty=format:%h %s` for the last-commit summary line. All
+read-only — no commit, no state change.
+
+### Device management (`cmd_device`, `main.rs:1632-1702`)
+
+Add: generate ed25519 keypair via `OsRng`, append `{name, public_key}` to
+`.relicario/devices.json`, write the secret signing key to
+`<config_dir>/relicario/devices/<name>.key` with `0o600` on Unix, commit
+`device: add <name>`. List: print `name pubkey_hex`. Revoke: filter by name,
+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)
+
+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.
+
+## Cross-cutting concerns
+
+- **Error model.** Every `cmd_*` returns `anyhow::Result<()>`. Core errors
+  bubble up through `?` from `RelicarioError`. Per-step context is added
+  via `with_context(|| ...)` chains, e.g. `format!("failed to read {}",
+  path.display())`. AEAD authentication failures intentionally surface as
+  the ambiguous "wrong passphrase or corrupt vault" message from core — the
+  CLI does not differentiate. clap argument errors are produced by clap
+  (e.g., `--days` and `--forever` together fail at the
+  `SettingsAction::TrashRetention` arm in `main.rs:1504-1510`).
+
+- **Atomicity.** Every disk write to a vault file goes through
+  `session.rs::atomic_write` (`session.rs:144-151`): write `<path>.tmp`, then
+  rename over `<path>`. Manifest is the single source of truth and is
+  always written *last* in any multi-file operation, so a process kill
+  between item-write and manifest-write leaves an orphan item file (which
+  doesn't appear in `list`/`status`) but never a manifest pointing to a
+  missing file.
+
+- **Git history as audit log.** Per-action commits, never amended, never
+  squashed. The verb prefix on commit subjects (`add:`, `edit:`, `trash:`,
+  `restore:`, `purge:`, `attach:`, `detach:`, `settings:`, `device:`,
+  `init:`) makes `git log --oneline` a literal audit trail. Tests verify
+  this by greping `git log` directly (e.g., `edit_and_history.rs:18-22`).
+
+- **Where secrets live.**
+  - Master key — `UnlockedVault.master_key: Zeroizing<[u8; 32]>`
+    (`session.rs:24`). Wipes on drop.
+  - Image secret — `Zeroizing<[u8; 32]>`, lives only inside
+    `unlock_interactive` until the KDF call (`session.rs:40`).
+  - Passphrase — `Zeroizing<String>` from `rpassword::prompt_password` or
+    the env var (`session.rs:42-49`, `main.rs:333-342`).
+  - Item secrets — `Zeroizing<String>` for `Login.password`, `Card.number`,
+    `Card.cvv`, `Card.pin`, `Key.key_material`, `SecureNote.body`, and
+    `Zeroizing<Vec<u8>>` for `TotpCore.config.secret` (decoded from
+    base32). All flow through core types.
+  - Clipboard copy — `Zeroizing<String>` cloned into the detached 30s
+    auto-clear thread (`main.rs:873-889`).
+
+- **Test escape hatches.** Three env vars exist for integration tests; all
+  are read at exactly one site each:
+  - `RELICARIO_TEST_PASSPHRASE` — `session.rs:42` (unlock) and
+    `main.rs:333,338` (init).
+  - `RELICARIO_IMAGE` — `session.rs:125` (image path resolution).
+  - `RELICARIO_TEST_ITEM_SECRET` — `main.rs:309` (`prompt_secret` only).
+  None of them have a production fall-through; absent the var, the code
+  always prompts. They are safe in production binaries because the user
+  would have to set them explicitly.
+
+- **Generate-without-unlock is intentional.** It is NOT an oversight.
+  `relicario generate --length 32` is the documented smoke test (see the
+  repo's CLAUDE.md) and works as a standalone CSPRNG password generator
+  outside any vault. Inside a vault it does require unlock — see Gotchas.
+
+## Test architecture
+
+All tests are integration tests; there are no `#[cfg(test)]` modules in
+`src/main.rs` or `src/session.rs`. `helpers.rs` has four unit tests
+(`helpers.rs:67-100`) that exercise vault-dir walking and `iso8601`
+formatting in isolation. Everything else is `tests/`.
+
+- **`tests/common/mod.rs`** (`117 lines`) — the harness. `TestVault::init()`
+  spins up a fresh `TempDir`, generates a 400×300 JPEG via
+  `make_test_jpeg()` (deterministic noise; no binary fixtures), runs
+  `relicario init --image carrier.jpg --output reference.jpg` with
+  `RELICARIO_TEST_PASSPHRASE` set, and stashes the passphrase + reference
+  image path on the struct. `run` and `run_with_input` are the two ways to
+  invoke the binary against the test vault: both inherit
+  `RELICARIO_IMAGE` + `RELICARIO_TEST_PASSPHRASE`; the latter pipes extra
+  newlines into stdin (used for interactive prompts that aren't
+  `rpassword`-driven). The note at the top warns Task 23 implementers
+  about the new-item-password rpassword path; the fix landed as
+  `RELICARIO_TEST_ITEM_SECRET` in commit `20350d5`.
+
+- **`tests/basic_flows.rs`** (`136 lines`) — covers the init layout
+  (`.relicario/{salt,params.json,devices.json}`, `manifest.enc`,
+  `settings.enc`, `reference.jpg`, `.gitignore`, `.git`); the `params.json`
+  v2 shape; `add login` + `list`; `get` masking semantics (with and
+  without `--show`); the rm/restore/purge cycle including `list --trashed`;
+  and the two-mode `generate` smoke (random length + bip39 word count) run
+  outside a vault.
+
+- **`tests/edit_and_history.rs`** (`191 lines`) — drives `edit` end-to-end
+  by piping stdin lines (blank to keep, `y` to confirm) plus
+  `RELICARIO_TEST_ITEM_SECRET` for the rpassword leg. `edit_password_*`
+  verifies the item file is rewritten and the `edit: bank` commit lands.
+  The four `history_command_*` tests cover masked listing, `--show`
+  reveal, "no history captured" output, and per-field filtering. The
+  `edit_totp_rotates_secret_and_captures_history` test (added 2026-04-27
+  in commit `3f0f5b1` — fixes a stub at the old `main.rs:925`) drives the
+  full TOTP edit including issuer / label / secret rotation.
+
+- **`tests/attachments.rs`** (`106 lines`) — `attach`/`attachments`/
+  `extract` round-trip (verifies the bytes survive the encrypt-decrypt
+  hop); `detach` removes both the attachment ref and the encrypted blob
+  on disk; `detach` rejects an unknown `aid`; `attach` rejects payloads
+  over `per_attachment_max_bytes`. The detach test (`detach_*`) and the
+  cap test were added in `3f0f5b1` / `20350d5` respectively.
+
+- **`tests/settings.rs`** (`135 lines`) — `settings show` and
+  `settings trash-retention --days 60` round-trip; the conflicting-flags
+  rejection (`--days` + `--forever`); the
+  `generate_uses_vault_default_length` test that verifies (a) default
+  vault length is 20, (b) updating `settings generator-defaults --length
+  32` changes the default, (c) explicit `--length 8` overrides the stored
+  default; the multi-shape `cmd_status` smoke; and the
+  `generate_works_outside_vault` test that verifies the no-unlock path
+  works in a bare `TempDir` with no `.relicario/`.
+
+- **`tests/vault_detection.rs`** (`59 lines`) — three tests covering audit
+  L8: `list` refuses without a marker; `list` from a nested subdirectory
+  finds the parent `.relicario/`; a v1 `.idfoto/` directory is rejected
+  with the `.relicario` hint in the error message.
+
+The whole test suite uses `assert_cmd` to spawn the real binary against a
+real temp directory, so they exercise actual fs / git / KDF code paths.
+The KDF runs with the production-grade `m=64MiB, t=3, p=4` parameters in
+the test path (`main.rs:365`), which is why init takes a noticeable beat
+in the test runner. The core's "fast Argon2id for tests" CLAUDE.md note
+applies to `relicario-core` unit tests, not these CLI integration tests.
+
+## Gotchas & non-obvious decisions
+
+- **`cmd_generate` runs without unlock outside a vault, but with unlock
+  inside.** This is two ergonomic guarantees in one command. Outside, it's
+  a fast standalone CSPRNG tool — useful for smoke tests, scripts, and any
+  user who installed `relicario` just for the generator. Inside, it
+  consults `settings.generator_defaults` so the user gets the policy they
+  configured. The branch is the `vault_dir().is_ok()` check at
+  `main.rs:1440`. Tests pin both behaviours.
+
+- **TOTP edit pushes history under the synthetic key `core:totp_secret`,
+  not `core:totp` or anything else.** This is what `relicario history
+  <query> --field totp_secret` matches against. The naming convention
+  ("type underscore field") is shared across all five history-tracked
+  fields (see Invariants). If you add a new history-tracked field, pick a
+  matching `<type>_<field>` form so the user-facing `--field` filter
+  stays predictable.
+
+- **`detach` refuses a Document item's primary attachment.**
+  (`main.rs:1392-1400`) Document items model "this item *is* a file"; the
+  primary blob isn't optional. The error directs the user to `purge`
+  instead. Non-primary attachments on a Document (e.g., a scanned
+  contract with an addendum) detach normally.
+
+- **Per-type `build_*_item` / `edit_*` helpers exist by design after the
+  `3f0f5b1` refactor.** Before the refactor, `cmd_add` and `cmd_edit`
+  carried 217-line `match` arms. The split-out functions are easier to
+  read, easier to test individually (the existing integration tests still
+  drive them through the same paths), and easier to grow when a new
+  `ItemCore` variant lands. Keep this shape — don't fold them back.
+
+- **Why the CLI shells out to `git`, not libgit2 / gitoxide.** Three
+  reasons. (1) Dep tree: pulling in libgit2 doubles compile time and
+  adds a C dependency. (2) Override surface: users can put any
+  `~/.gitconfig` they want and it Just Works (subject to the hardening
+  flags). (3) Recovery: when something is wrong with a vault, the user
+  can poke around with `git log`, `git show`, `git fsck` directly; the
+  CLI's git interactions are not opaque.
+
+- **The hardened-`git` injection set is load-bearing.** `git_command`
+  prepends three `-c` flags before the user-supplied args
+  (`helpers.rs:48-52`):
+  - `core.hooksPath=/dev/null` — a malicious or buggy hook in a cloned
+    vault could otherwise run arbitrary code on every commit. Master key
+    is in memory at the time of commit; this matters.
+  - `commit.gpgsign=false` — if the user has global GPG signing on, the
+    GPG agent prompt would block on `git commit` and hold the master
+    key alive in memory until the user types the passphrase. Disable it
+    for relicario commits.
+  - `core.editor=true` — `true(1)` exits 0 with no output. If `git`
+    decides to drop into `$EDITOR` (rebase conflict markers, missing
+    `-m`), this neutralises it without crashing the rebase. We pass
+    `-m <msg>` ourselves; this flag is the seatbelt.
+  All three were added together in audit H4. A user can still run
+  `git` themselves with their own config to inspect or repair the
+  vault — the hardening only applies to relicario's invocations.
+
+- **`cmd_init` uses production-grade `KdfParams { m: 65536, t: 3, p: 4
+  }`** (`main.rs:365`), even in tests. `RELICARIO_TEST_PASSPHRASE`
+  bypasses the prompt but does not lower the KDF cost. This is a
+  trade-off: integration tests pay the full Argon2id cost (~half a
+  second per init on a modern machine), but the same code path runs in
+  production. Don't lower the params here — the core's test-only fast
+  params are for `relicario-core` unit tests.
+
+- **`params.json` has a nested `kdf` object, not a flat one.**
+  `read_params` (`session.rs:110-121`) deserializes via a private
+  `ParamsFile { kdf: KdfParams }` struct. The nesting exists so
+  `format_version`, `aead`, and `salt_path` can co-exist in the same
+  file for forward-compat. An earlier version of `read_params` tried
+  to deserialize the whole file as `KdfParams` and failed silently —
+  that bug was fixed in commit `b263c27`.
+
+- **`commit_paths` is the convention but not always the call site.**
+  `cmd_purge`, `cmd_trash_empty`, and `cmd_device` use `git_command`
+  directly because their add/commit pattern doesn't quite fit
+  `commit_paths(vault, msg, &[paths...])`. They still use the
+  hardened wrapper, just at one level lower. If you find yourself
+  writing a new command with the same shape, prefer `commit_paths`;
+  reach for `git_command` directly only when you need the slightly
+  different control flow these three have.
+
+- **Initial commit at `cmd_init` does not use `commit_paths`.**
+  Reason: `commit_paths` takes `&UnlockedVault`, but `cmd_init` doesn't
+  construct one — it uses the master key inline before the vault
+  exists. The init commit goes through `git_command` directly
+  (`main.rs:403-412`). This is the only production code site outside
+  `commit_paths` that does so.
+
+- **`Lock` is a no-op (`main.rs:301`).** The CLI doesn't cache a
+  session — every command re-derives the master key. The command
+  exists only for UX parity with the extension, where `lock` actually
+  evicts a cached session. Printed message: `no cached session to
+  lock`.
+
+- **`resolve_query` accepts an item id or a case-insensitive title
+  substring** (`main.rs:855-871`). Exact id-match wins; otherwise it
+  defers to `Manifest::search`. Multi-hit substring matches are
+  rejected with an "ambiguous" error listing the matched titles. This
+  is why every `cmd_*` that takes a `query: String` (get, edit,
+  history, rm, restore, purge, attach, attachments, extract, detach)
+  works the same way.

crates/relicario-cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "relicario-cli"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 description = "CLI for relicario password manager"
 
@@ -17,17 +17,21 @@ arboard = "3"
 chrono = { version = "0.4", default-features = false, features = ["clock"] }
 dirs = "5"
 hex = "0.4"
-ed25519-dalek = { version = "2", features = ["rand_core"] }
 rand = "0.8"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 zeroize = "1"
 url = "2"
 data-encoding = "2"
+tar = { version = "0.4", default-features = false }
+clap_complete = "4"
+image = { version = "0.25", default-features = false, features = ["jpeg", "png"] }
+rqrr = "0.7"
+reqwest = { version = "0.12", features = ["blocking", "json"] }
+qrcode = { version = "0.14", features = ["svg"] }
 
 [dev-dependencies]
 assert_cmd = "2"
 predicates = "3"
 tempfile = "3"
-image = { version = "0.25", default-features = false, features = ["jpeg"] }
 serde_json = "1"

crates/relicario-cli/src/device.rs

@@ -0,0 +1,169 @@
+//! Local device key storage and git signing configuration.
+//!
+//! Keys live under `~/.config/relicario/devices/<device-name>/`:
+//!   signing.key   — ed25519 private key (OpenSSH, 0600)
+//!   signing.pub   — ed25519 public key (OpenSSH single line)
+//!   deploy.key    — ed25519 private key for git push (OpenSSH, 0600)
+//!   deploy.pub    — ed25519 public key registered as Gitea deploy key
+//!   gitea_key_id  — numeric Gitea deploy key ID for later revocation
+//!
+//! The file `~/.config/relicario/devices/current` holds the active device name
+//! (one plain-text line).
+
+use std::fs::{self, Permissions};
+use std::path::PathBuf;
+
+use anyhow::{Context, Result};
+use zeroize::Zeroizing;
+
+/// `~/.config/relicario/devices/`
+pub fn devices_dir() -> Result<PathBuf> {
+    let config = dirs::config_dir()
+        .ok_or_else(|| anyhow::anyhow!("no config directory available"))?;
+    Ok(config.join("relicario").join("devices"))
+}
+
+/// `~/.config/relicario/devices/<name>/`
+pub fn device_dir(name: &str) -> Result<PathBuf> {
+    Ok(devices_dir()?.join(name))
+}
+
+/// Read the current device name from `devices/current`, or `None` if not set.
+pub fn current_device() -> Result<Option<String>> {
+    let path = devices_dir()?.join("current");
+    if !path.exists() {
+        return Ok(None);
+    }
+    let name = fs::read_to_string(&path)
+        .context("read current device")?
+        .trim()
+        .to_string();
+    if name.is_empty() {
+        Ok(None)
+    } else {
+        Ok(Some(name))
+    }
+}
+
+/// Write the active device name to `devices/current`.
+pub fn set_current_device(name: &str) -> Result<()> {
+    let dir = devices_dir()?;
+    fs::create_dir_all(&dir).context("create devices dir")?;
+    fs::write(dir.join("current"), format!("{name}\n"))
+        .context("write current device")?;
+    Ok(())
+}
+
+/// Store all keys for a device, applying restrictive permissions on private
+/// key files on Unix.
+pub fn store_device_keys(
+    name: &str,
+    signing_private: &str,
+    signing_public: &str,
+    deploy_private: &str,
+    deploy_public: &str,
+    gitea_key_id: u64,
+) -> Result<()> {
+    let dir = device_dir(name)?;
+    fs::create_dir_all(&dir).context("create device dir")?;
+
+    fs::write(dir.join("signing.key"), signing_private)
+        .context("write signing.key")?;
+    fs::write(dir.join("signing.pub"), signing_public)
+        .context("write signing.pub")?;
+    fs::write(dir.join("deploy.key"), deploy_private)
+        .context("write deploy.key")?;
+    fs::write(dir.join("deploy.pub"), deploy_public)
+        .context("write deploy.pub")?;
+    fs::write(dir.join("gitea_key_id"), gitea_key_id.to_string())
+        .context("write gitea_key_id")?;
+
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        fs::set_permissions(dir.join("signing.key"), Permissions::from_mode(0o600))
+            .context("chmod signing.key")?;
+        fs::set_permissions(dir.join("deploy.key"), Permissions::from_mode(0o600))
+            .context("chmod deploy.key")?;
+    }
+
+    Ok(())
+}
+
+/// Load the signing private key for a device.
+#[allow(dead_code)]
+pub fn load_signing_key(name: &str) -> Result<Zeroizing<String>> {
+    let path = device_dir(name)?.join("signing.key");
+    let key = fs::read_to_string(&path)
+        .with_context(|| format!("read signing key for device '{name}'"))?;
+    Ok(Zeroizing::new(key))
+}
+
+/// Load the deploy private key for a device.
+#[allow(dead_code)]
+pub fn load_deploy_key(name: &str) -> Result<Zeroizing<String>> {
+    let path = device_dir(name)?.join("deploy.key");
+    let key = fs::read_to_string(&path)
+        .with_context(|| format!("read deploy key for device '{name}'"))?;
+    Ok(Zeroizing::new(key))
+}
+
+/// Load the Gitea deploy key ID for a device.
+pub fn load_gitea_key_id(name: &str) -> Result<u64> {
+    let path = device_dir(name)?.join("gitea_key_id");
+    let id_str = fs::read_to_string(&path)
+        .with_context(|| format!("read Gitea key ID for device '{name}'"))?;
+    id_str.trim().parse().context("parse Gitea key ID")
+}
+
+/// Delete the local key directory for a device.
+#[allow(dead_code)]
+pub fn delete_device_keys(name: &str) -> Result<()> {
+    let dir = device_dir(name)?;
+    if dir.exists() {
+        fs::remove_dir_all(&dir)
+            .with_context(|| format!("delete device dir for '{name}'"))?;
+    }
+    Ok(())
+}
+
+/// Configure git in `vault_root` to:
+///  - sign commits with the device's signing key (SSH format)
+///  - push via SSH using the device's deploy key
+pub fn configure_git_signing(vault_root: &std::path::Path, name: &str) -> Result<()> {
+    let dir = device_dir(name)?;
+    let signing_key = dir.join("signing.key");
+    let deploy_key = dir.join("deploy.key");
+
+    // gpg.format = ssh so git uses SSH-format signing
+    crate::helpers::git_command(vault_root, &["config", "gpg.format", "ssh"])
+        .status()
+        .context("git config gpg.format")?;
+
+    // user.signingkey = path to the private key file
+    crate::helpers::git_command(
+        vault_root,
+        &["config", "user.signingkey", &signing_key.to_string_lossy()],
+    )
+    .status()
+    .context("git config user.signingkey")?;
+
+    // commit.gpgsign = true
+    crate::helpers::git_command(vault_root, &["config", "commit.gpgsign", "true"])
+        .status()
+        .context("git config commit.gpgsign")?;
+
+    // core.sshCommand — use only the deploy key for push
+    let ssh_cmd = format!(
+        "ssh -i {} -o IdentitiesOnly=yes",
+        deploy_key.display()
+    );
+    crate::helpers::git_command(
+        vault_root,
+        &["config", "core.sshCommand", &ssh_cmd],
+    )
+    .status()
+    .context("git config core.sshCommand")?;
+
+    Ok(())
+}

crates/relicario-cli/src/gitea.rs

@@ -0,0 +1,117 @@
+//! Gitea API client for deploy key management.
+
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone)]
+pub struct GiteaClient {
+    api_url: String,
+    token: String,
+    owner: String,
+    repo: String,
+}
+
+#[derive(Debug, Serialize)]
+struct CreateKeyRequest<'a> {
+    title: &'a str,
+    key: &'a str,
+    read_only: bool,
+}
+
+#[derive(Debug, Deserialize)]
+pub struct DeployKey {
+    pub id: u64,
+    #[allow(dead_code)]
+    pub title: String,
+    #[allow(dead_code)]
+    pub key: String,
+}
+
+impl GiteaClient {
+    pub fn new(api_url: &str, token: &str, owner: &str, repo: &str) -> Self {
+        Self {
+            api_url: api_url.trim_end_matches('/').to_string(),
+            token: token.to_string(),
+            owner: owner.to_string(),
+            repo: repo.to_string(),
+        }
+    }
+
+    /// Create a deploy key, returning its ID.
+    pub fn create_deploy_key(&self, title: &str, public_key: &str) -> Result<u64> {
+        let url = format!(
+            "{}/repos/{}/{}/keys",
+            self.api_url, self.owner, self.repo
+        );
+
+        let client = reqwest::blocking::Client::new();
+        let resp = client
+            .post(&url)
+            .header("Authorization", format!("token {}", self.token))
+            .header("Content-Type", "application/json")
+            .json(&CreateKeyRequest {
+                title,
+                key: public_key,
+                read_only: false,
+            })
+            .send()
+            .context("Gitea API request failed")?;
+
+        if !resp.status().is_success() {
+            let status = resp.status();
+            let body = resp.text().unwrap_or_default();
+            anyhow::bail!("Gitea API error {}: {}", status, body);
+        }
+
+        let key: DeployKey = resp.json().context("parse deploy key response")?;
+        Ok(key.id)
+    }
+
+    /// Delete a deploy key by ID.
+    pub fn delete_deploy_key(&self, key_id: u64) -> Result<()> {
+        let url = format!(
+            "{}/repos/{}/{}/keys/{}",
+            self.api_url, self.owner, self.repo, key_id
+        );
+
+        let client = reqwest::blocking::Client::new();
+        let resp = client
+            .delete(&url)
+            .header("Authorization", format!("token {}", self.token))
+            .send()
+            .context("Gitea API request failed")?;
+
+        if !resp.status().is_success() && resp.status().as_u16() != 404 {
+            let status = resp.status();
+            let body = resp.text().unwrap_or_default();
+            anyhow::bail!("Gitea API error {}: {}", status, body);
+        }
+
+        Ok(())
+    }
+
+    /// List all deploy keys.
+    #[allow(dead_code)]
+    pub fn list_deploy_keys(&self) -> Result<Vec<DeployKey>> {
+        let url = format!(
+            "{}/repos/{}/{}/keys",
+            self.api_url, self.owner, self.repo
+        );
+
+        let client = reqwest::blocking::Client::new();
+        let resp = client
+            .get(&url)
+            .header("Authorization", format!("token {}", self.token))
+            .send()
+            .context("Gitea API request failed")?;
+
+        if !resp.status().is_success() {
+            let status = resp.status();
+            let body = resp.text().unwrap_or_default();
+            anyhow::bail!("Gitea API error {}: {}", status, body);
+        }
+
+        let keys: Vec<DeployKey> = resp.json().context("parse deploy keys response")?;
+        Ok(keys)
+    }
+}

crates/relicario-cli/src/helpers.rs

@@ -34,6 +34,7 @@ pub fn vault_dir() -> Result<PathBuf> {
 }
 
 /// Path to the `.relicario/` configuration directory within the vault.
+#[allow(dead_code)]
 pub fn relicario_dir() -> Result<PathBuf> {
     Ok(vault_dir()?.join(".relicario"))
 }
@@ -63,6 +64,103 @@ pub fn iso8601(unix_seconds: i64) -> String {
         .unwrap_or_else(|| format!("invalid-timestamp:{unix_seconds}"))
 }
 
+/// Format a duration (in seconds) as a coarse human-readable string:
+/// "just now" / "5 minutes ago" / "4 days ago" / "3 months ago".
+pub fn humanize_age(seconds: i64) -> String {
+    if seconds < 60 { return "just now".to_string(); }
+    if seconds < 3600 { return format!("{} minute{} ago", seconds / 60, plural(seconds / 60)); }
+    if seconds < 86_400 { return format!("{} hour{} ago", seconds / 3600, plural(seconds / 3600)); }
+    if seconds < 86_400 * 30 {
+        let d = seconds / 86_400;
+        return format!("{d} day{} ago", plural(d));
+    }
+    if seconds < 86_400 * 365 {
+        let m = seconds / (86_400 * 30);
+        return format!("{m} month{} ago", plural(m));
+    }
+    let y = seconds / (86_400 * 365);
+    format!("{y} year{} ago", plural(y))
+}
+
+fn plural(n: i64) -> &'static str { if n == 1 { "" } else { "s" } }
+
+/// Path to the plaintext `groups.cache` file used by shell completion to
+/// enumerate `--group <TAB>` candidates without unlocking the vault.
+///
+/// **Plaintext leak:** group names land on disk in cleartext alongside the
+/// vault directory. This is intentional — the file feeds shell completion,
+/// which cannot prompt for a passphrase. In debug builds, set
+/// `RELICARIO_NO_GROUPS_CACHE=1` to suppress the write.
+pub fn groups_cache_path(vault_dir: &Path) -> PathBuf {
+    vault_dir.join(".relicario").join("groups.cache")
+}
+
+/// 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
+/// var is ignored.
+pub fn write_groups_cache(
+    vault_dir: &Path,
+    groups: &std::collections::BTreeSet<String>,
+) -> std::io::Result<()> {
+    if cfg!(debug_assertions) && std::env::var_os("RELICARIO_NO_GROUPS_CACHE").is_some() {
+        return Ok(());
+    }
+    let path = groups_cache_path(vault_dir);
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    let mut body = String::new();
+    for g in groups {
+        body.push_str(g);
+        body.push('\n');
+    }
+    std::fs::write(path, body)
+}
+
+/// Sanitize a string for use in a git commit message subject line.
+///
+/// Removes all Unicode control characters (U+0000–U+001F, U+007F, and higher
+/// control planes) so that newlines and escape sequences cannot corrupt `git
+/// log` output. Truncates to 50 characters so the subject line stays within
+/// the conventional limit.
+///
+/// Audit I1: item titles are user-supplied and may contain arbitrary bytes.
+pub fn sanitize_for_commit(s: &str) -> String {
+    s.chars()
+        .filter(|c| !c.is_control())
+        .take(50)
+        .collect()
+}
+
+/// Decode a QR image at `path`. Returns the otpauth secret (base32) if the
+/// QR decodes to an `otpauth://...` URI with a `secret` query param.
+pub fn decode_totp_qr(path: &std::path::Path) -> anyhow::Result<String> {
+    let img = image::open(path)
+        .map_err(|e| anyhow::anyhow!("failed to read image: {e}"))?
+        .to_luma8();
+    let mut prepared = rqrr::PreparedImage::prepare(img);
+    let grids = prepared.detect_grids();
+    let grid = grids
+        .into_iter()
+        .next()
+        .ok_or_else(|| anyhow::anyhow!("no QR code found in image"))?;
+    let (_meta, content) = grid
+        .decode()
+        .map_err(|e| anyhow::anyhow!("QR decode failed: {e}"))?;
+    if !content.starts_with("otpauth://") {
+        return Err(anyhow::anyhow!("not a TOTP URI (expected otpauth://...)"));
+    }
+    let parsed =
+        url::Url::parse(&content).map_err(|e| anyhow::anyhow!("invalid otpauth URI: {e}"))?;
+    let secret = parsed
+        .query_pairs()
+        .find(|(k, _)| k == "secret")
+        .map(|(_, v)| v.to_string())
+        .ok_or_else(|| anyhow::anyhow!("otpauth URI missing `secret` parameter"))?;
+    Ok(secret)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -98,4 +196,44 @@ mod tests {
         // 2026-04-19T00:00:00Z = 1776556800
         assert_eq!(iso8601(1_776_556_800), "2026-04-19T00:00:00Z");
     }
+
+    #[test]
+    fn sanitize_for_commit_strips_control_chars() {
+        assert_eq!(sanitize_for_commit("line1\nline2"), "line1line2");
+        assert_eq!(sanitize_for_commit("a\tb"), "ab");
+        assert_eq!(sanitize_for_commit("normal"), "normal");
+        assert_eq!(sanitize_for_commit("cr\r\nline"), "crline");
+        // ESC (U+001B) is control and gets stripped; bracket sequences are printable
+        assert_eq!(sanitize_for_commit("\x1b[31mred\x1b[0m"), "[31mred[0m");
+    }
+
+    #[test]
+    fn sanitize_for_commit_truncates_to_50() {
+        let long = "a".repeat(60);
+        assert_eq!(sanitize_for_commit(&long).len(), 50);
+        assert_eq!(sanitize_for_commit(&long), "a".repeat(50));
+    }
+
+    #[test]
+    fn sanitize_for_commit_allows_unicode() {
+        assert_eq!(sanitize_for_commit("cafe\u{0301}"), "cafe\u{0301}");
+        assert_eq!(sanitize_for_commit("emoji \u{1F4AA}"), "emoji \u{1F4AA}");
+    }
+
+    #[test]
+    fn humanize_age_buckets() {
+        assert_eq!(humanize_age(0), "just now");
+        assert_eq!(humanize_age(59), "just now");
+        assert_eq!(humanize_age(60), "1 minute ago");
+        assert_eq!(humanize_age(120), "2 minutes ago");
+        assert_eq!(humanize_age(3_599), "59 minutes ago");
+        assert_eq!(humanize_age(3_600), "1 hour ago");
+        assert_eq!(humanize_age(7_200), "2 hours ago");
+        assert_eq!(humanize_age(86_400), "1 day ago");
+        assert_eq!(humanize_age(86_400 * 2), "2 days ago");
+        assert_eq!(humanize_age(86_400 * 30), "1 month ago");
+        assert_eq!(humanize_age(86_400 * 60), "2 months ago");
+        assert_eq!(humanize_age(86_400 * 365), "1 year ago");
+        assert_eq!(humanize_age(86_400 * 365 * 3), "3 years ago");
+    }
 }

crates/relicario-cli/src/session.rs

@@ -39,7 +39,7 @@ impl UnlockedVault {
             .with_context(|| format!("failed to read reference image {}", image_path.display()))?;
         let image_secret = Zeroizing::new(imgsecret::extract(&image_bytes)?);
 
-        let passphrase = if let Ok(p) = std::env::var("RELICARIO_TEST_PASSPHRASE") {
+        let passphrase = if let Some(p) = crate::test_passphrase_override() {
             Zeroizing::new(p)
         } else {
             Zeroizing::new(
@@ -50,7 +50,7 @@ impl UnlockedVault {
 
         let master_key = derive_master_key(
             passphrase.as_bytes(),
-            &*image_secret,
+            &image_secret,
             &salt,
             &params,
         )?;

crates/relicario-cli/tests/attachments.rs

@@ -29,6 +29,67 @@ fn attach_list_extract_round_trip() {
     assert_eq!(std::fs::read(out_path).unwrap(), b"attached-bytes");
 }
 
+#[test]
+fn detach_removes_attachment_and_blob() {
+    let v = TestVault::init();
+    v.run(&["add", "login", "--title", "thing",
+           "--username", "u", "--password", "p"]);
+
+    let payload_path = v.path().join("payload.txt");
+    std::fs::write(&payload_path, b"attached-bytes").unwrap();
+    let attach = v.run(&["attach", "thing", payload_path.to_str().unwrap()]);
+    assert!(attach.status.success());
+
+    let list = v.run(&["attachments", "thing"]);
+    let stdout = String::from_utf8(list.stdout).unwrap();
+    let aid = stdout.lines()
+        .find(|l| l.contains("payload.txt"))
+        .and_then(|l| l.split_whitespace().next())
+        .expect("aid token")
+        .to_string();
+
+    // Detach removes the attachment from the item AND deletes the blob.
+    let out = v.run(&["detach", "thing", &aid]);
+    assert!(
+        out.status.success(),
+        "detach failed:\nstdout: {}\nstderr: {}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr),
+    );
+
+    // Item no longer lists the attachment.
+    let list2 = v.run(&["attachments", "thing"]);
+    let stdout2 = String::from_utf8(list2.stdout).unwrap();
+    assert!(
+        !stdout2.contains("payload.txt"),
+        "attachment still listed after detach: {stdout2}"
+    );
+
+    // Encrypted blob file is gone.
+    let blob_path = v.path()
+        .join("attachments")
+        .join("");
+    let item_attach_dir = std::fs::read_dir(v.path().join("attachments"))
+        .unwrap().next().unwrap().unwrap().path();
+    let blob = item_attach_dir.join(format!("{aid}.enc"));
+    assert!(!blob.exists(), "blob still on disk: {}", blob.display());
+    let _ = blob_path; // keep the variable to avoid an unused warning
+}
+
+#[test]
+fn detach_refuses_unknown_aid() {
+    let v = TestVault::init();
+    v.run(&["add", "login", "--title", "thing",
+           "--username", "u", "--password", "p"]);
+
+    let out = v.run(&["detach", "thing", "deadbeef"]);
+    assert!(!out.status.success(), "expected failure: {:?}", out);
+    assert!(
+        String::from_utf8_lossy(&out.stderr).to_lowercase().contains("no attachment"),
+        "expected 'no attachment' error in stderr"
+    );
+}
+
 #[test]
 fn attach_rejects_over_cap() {
     let v = TestVault::init();

crates/relicario-cli/tests/backup.rs

@@ -0,0 +1,142 @@
+mod common;
+use common::TestVault;
+use std::process::Command;
+use assert_cmd::cargo::CommandCargoExt;
+
+const BACKUP_PASS: &str = "strong-backup-pass-test-2026";
+
+#[test]
+fn export_then_restore_round_trip() {
+    let v = TestVault::init();
+
+    v.run(&["add", "login", "--title", "GitHub", "--username", "alice", "--password", "p"]);
+    v.run(&["add", "login", "--title", "Email", "--username", "bob", "--password", "q"]);
+
+    let backup_path = v.path().join("vault.relbak");
+    let out = v.run_with_backup_pass(
+        &["backup", "export", backup_path.to_str().unwrap()],
+        BACKUP_PASS,
+    );
+    assert!(out.status.success(), "export failed: {:?}", String::from_utf8_lossy(&out.stderr));
+    assert!(backup_path.exists());
+    assert!(v.path().join(".relicario/last_backup").exists());
+
+    // Restore into a fresh dir.
+    let restore_dir = tempfile::TempDir::new().unwrap();
+    let out = Command::cargo_bin("relicario")
+        .unwrap()
+        .current_dir(restore_dir.path())
+        .env("RELICARIO_TEST_BACKUP_PASSPHRASE", BACKUP_PASS)
+        .args(["backup", "restore", backup_path.to_str().unwrap(), "."])
+        .output()
+        .unwrap();
+    assert!(out.status.success(), "restore failed: {:?}", String::from_utf8_lossy(&out.stderr));
+
+    // Vault should be unlockable in the restore dir using the same passphrase + image.
+    // Since the original vault didn't include the image, we copy it in manually
+    // (the standard restore-without-image flow expects the user to keep their
+    // reference image separately).
+    std::fs::copy(&v.reference_image, restore_dir.path().join("reference.jpg")).unwrap();
+
+    let out = Command::cargo_bin("relicario")
+        .unwrap()
+        .current_dir(restore_dir.path())
+        .env("RELICARIO_TEST_PASSPHRASE", &v.passphrase)
+        .env("RELICARIO_IMAGE", restore_dir.path().join("reference.jpg"))
+        .args(["list"])
+        .output()
+        .unwrap();
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    assert!(stdout.contains("GitHub"));
+    assert!(stdout.contains("Email"));
+}
+
+#[test]
+fn restore_refuses_non_empty_target() {
+    let v = TestVault::init();
+    let backup_path = v.path().join("vault.relbak");
+    v.run_with_backup_pass(&["backup", "export", backup_path.to_str().unwrap()], BACKUP_PASS);
+
+    let out = Command::cargo_bin("relicario")
+        .unwrap()
+        .current_dir(v.path())   // already has a .relicario/
+        .env("RELICARIO_TEST_BACKUP_PASSPHRASE", BACKUP_PASS)
+        .args(["backup", "restore", backup_path.to_str().unwrap(), "."])
+        .output()
+        .unwrap();
+    assert!(!out.status.success());
+    let err = String::from_utf8(out.stderr).unwrap();
+    assert!(err.contains("already contains a Relicario vault"), "stderr: {err}");
+}
+
+#[test]
+fn export_with_include_image_round_trips_the_image() {
+    let v = TestVault::init();
+    let backup_path = v.path().join("vault.relbak");
+    v.run_with_backup_pass(
+        &["backup", "export", backup_path.to_str().unwrap(), "--include-image"],
+        BACKUP_PASS,
+    );
+
+    let restore_dir = tempfile::TempDir::new().unwrap();
+    let out = Command::cargo_bin("relicario")
+        .unwrap()
+        .current_dir(restore_dir.path())
+        .env("RELICARIO_TEST_BACKUP_PASSPHRASE", BACKUP_PASS)
+        .args(["backup", "restore", backup_path.to_str().unwrap(), "."])
+        .output()
+        .unwrap();
+    assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
+    assert!(restore_dir.path().join("reference.jpg").exists(),
+        "image should be restored when --include-image was used");
+}
+
+#[test]
+fn export_with_no_history_skips_git_dir() {
+    let v = TestVault::init();
+    let backup_path = v.path().join("vault.relbak");
+    v.run_with_backup_pass(
+        &["backup", "export", backup_path.to_str().unwrap(), "--no-history"],
+        BACKUP_PASS,
+    );
+
+    let restore_dir = tempfile::TempDir::new().unwrap();
+    let out = Command::cargo_bin("relicario")
+        .unwrap()
+        .current_dir(restore_dir.path())
+        .env("RELICARIO_TEST_BACKUP_PASSPHRASE", BACKUP_PASS)
+        .args(["backup", "restore", backup_path.to_str().unwrap(), "."])
+        .output()
+        .unwrap();
+    assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
+
+    // .git/ should exist but contain only the "restore from backup ..." commit.
+    assert!(restore_dir.path().join(".git").is_dir());
+    let out = std::process::Command::new("git")
+        .current_dir(restore_dir.path())
+        .args(["log", "--oneline"])
+        .output()
+        .unwrap();
+    let log = String::from_utf8(out.stdout).unwrap();
+    assert_eq!(log.lines().count(), 1, "expected one commit, got: {log}");
+    assert!(log.contains("restore from backup"));
+}
+
+#[test]
+fn wrong_backup_passphrase_fails() {
+    let v = TestVault::init();
+    let backup_path = v.path().join("vault.relbak");
+    v.run_with_backup_pass(&["backup", "export", backup_path.to_str().unwrap()], BACKUP_PASS);
+
+    let restore_dir = tempfile::TempDir::new().unwrap();
+    let out = Command::cargo_bin("relicario")
+        .unwrap()
+        .current_dir(restore_dir.path())
+        .env("RELICARIO_TEST_BACKUP_PASSPHRASE", "definitely-wrong")
+        .args(["backup", "restore", backup_path.to_str().unwrap(), "."])
+        .output()
+        .unwrap();
+    assert!(!out.status.success());
+    let err = String::from_utf8(out.stderr).unwrap();
+    assert!(err.contains("wrong backup passphrase"), "stderr: {err}");
+}

crates/relicario-cli/tests/basic_flows.rs

@@ -8,7 +8,8 @@ fn init_creates_expected_layout() {
     let v = TestVault::init();
     assert!(v.path().join(".relicario/salt").exists());
     assert!(v.path().join(".relicario/params.json").exists());
-    assert!(v.path().join(".relicario/devices.json").exists());
+    // devices.json removed — device key system was security theater
+    assert!(!v.path().join(".relicario/devices.json").exists());
     assert!(v.path().join("manifest.enc").exists());
     assert!(v.path().join("settings.enc").exists());
     assert!(v.path().join("reference.jpg").exists());

crates/relicario-cli/tests/common/mod.rs

@@ -78,6 +78,21 @@ impl TestVault {
         cmd.output().unwrap()
     }
 
+    #[allow(dead_code)]
+    pub fn run_with_backup_pass(&self, args: &[&str], backup_pass: &str) -> std::process::Output {
+        let mut cmd = Command::cargo_bin("relicario").unwrap();
+        cmd.current_dir(self.dir.path())
+            .env("RELICARIO_IMAGE", &self.reference_image)
+            .env("RELICARIO_TEST_PASSPHRASE", &self.passphrase)
+            .env("RELICARIO_TEST_BACKUP_PASSPHRASE", backup_pass)
+            .args(args)
+            .stdin(Stdio::null())
+            .stdout(Stdio::piped())
+            .stderr(Stdio::piped());
+        cmd.output().unwrap()
+    }
+
+    #[allow(dead_code)]
     pub fn run_with_input(&self, args: &[&str], extra: &[&str]) -> std::process::Output {
         let mut cmd = Command::cargo_bin("relicario").unwrap();
         cmd.current_dir(self.dir.path())

crates/relicario-cli/tests/edit_and_history.rs

@@ -57,3 +57,135 @@ fn run_edit_with_pw_change(v: &TestVault, query: &str, new_pw: &str) -> std::pro
     }
     child.wait_with_output().unwrap()
 }
+
+#[test]
+fn history_command_lists_per_field_entries() {
+    let v = TestVault::init();
+    v.run(&["add", "login", "--title", "bank",
+           "--username", "u", "--password", "first-pw"]);
+    let out = run_edit_with_pw_change(&v, "bank", "second-pw");
+    assert!(out.status.success(), "edit failed: {:?}", out);
+
+    // `history <query>` should list the captured field and a count.
+    let out = v.run(&["history", "bank"]);
+    assert!(
+        out.status.success(),
+        "history failed:\nstdout: {}\nstderr: {}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr),
+    );
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    assert!(
+        stdout.contains("login_password"),
+        "expected login_password key, got: {stdout}"
+    );
+    // Default (no --show) hides values.
+    assert!(
+        !stdout.contains("first-pw"),
+        "values should be masked without --show: {stdout}"
+    );
+    assert!(
+        stdout.contains("****"),
+        "expected masked value indicator: {stdout}"
+    );
+}
+
+#[test]
+fn history_command_show_reveals_prior_values() {
+    let v = TestVault::init();
+    v.run(&["add", "login", "--title", "bank",
+           "--username", "u", "--password", "first-pw"]);
+    let out = run_edit_with_pw_change(&v, "bank", "second-pw");
+    assert!(out.status.success());
+
+    let out = v.run(&["history", "bank", "--show"]);
+    assert!(out.status.success(), "history --show failed: {:?}", out);
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    assert!(
+        stdout.contains("first-pw"),
+        "expected old value 'first-pw' in --show output: {stdout}"
+    );
+}
+
+#[test]
+fn history_command_reports_empty_when_nothing_changed() {
+    let v = TestVault::init();
+    v.run(&["add", "login", "--title", "untouched",
+           "--username", "u", "--password", "pw"]);
+
+    let out = v.run(&["history", "untouched"]);
+    assert!(out.status.success(), "history failed: {:?}", out);
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    assert!(
+        stdout.to_lowercase().contains("no history"),
+        "expected 'no history' message, got: {stdout}"
+    );
+}
+
+#[test]
+fn edit_totp_rotates_secret_and_captures_history() {
+    let v = TestVault::init();
+    v.run(&[
+        "add", "totp",
+        "--title", "github",
+        "--issuer", "github.com",
+        "--label", "alice",
+        "--secret", "JBSWY3DPEHPK3PXP",
+    ]);
+
+    // Edit: change issuer, label, then rotate the secret to a new base32 value.
+    let out = run_edit_totp(&v, "github", "github-new.com", "alice@new", "NB2W45DFOIZA");
+    assert!(
+        out.status.success(),
+        "edit failed:\nstdout: {}\nstderr: {}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr)
+    );
+
+    // Verify the issuer and label changes persisted by reading the item back.
+    let out = v.run(&["get", "github"]);
+    assert!(out.status.success(), "get failed: {:?}", out);
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    assert!(
+        stdout.contains("github-new.com"),
+        "expected new issuer in get output, got: {stdout}"
+    );
+    assert!(
+        stdout.contains("alice@new"),
+        "expected new label in get output, got: {stdout}"
+    );
+}
+
+/// Drives the interactive `edit` flow for a TOTP item with secret rotation.
+/// Stdin order: Title, Group, Tags (all blank to keep), Issuer, Label,
+/// then "y" to "Change TOTP secret?" The new secret comes from
+/// RELICARIO_TEST_ITEM_SECRET.
+fn run_edit_totp(
+    v: &TestVault,
+    query: &str,
+    new_issuer: &str,
+    new_label: &str,
+    new_secret_b32: &str,
+) -> std::process::Output {
+    use assert_cmd::cargo::CommandCargoExt;
+    use std::io::Write;
+    use std::process::{Command, Stdio};
+
+    let mut cmd = Command::cargo_bin("relicario").unwrap();
+    cmd.current_dir(v.path())
+        .env("RELICARIO_IMAGE", &v.reference_image)
+        .env("RELICARIO_TEST_PASSPHRASE", &v.passphrase)
+        .env("RELICARIO_TEST_ITEM_SECRET", new_secret_b32)
+        .args(["edit", query])
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped());
+    let mut child = cmd.spawn().unwrap();
+    {
+        let stdin = child.stdin.as_mut().unwrap();
+        for line in ["", "", "", new_issuer, new_label, "y"] {
+            writeln!(stdin, "{line}").unwrap();
+        }
+    }
+    child.wait_with_output().unwrap()
+}

crates/relicario-cli/tests/fixtures/lastpass-sample.csv

@@ -0,0 +1,17 @@
+url,username,password,totp,extra,name,grouping,fav
+https://github.com/login,alice@example.com,hunter2-strong,GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ,One-time URL: https://github.com/recover,GitHub,Work,1
+https://gmail.com,bob@example.com,p@ssw0rd-2026,,,Gmail,Personal,
+https://news.ycombinator.com,charlie,hn-secret,,,Hacker News,,
+https://aws.console,d-user,aws-pass,!!!not-base32!!!,,AWS,Work,
+http://sn,,,,Wifi password: hunter2hunter2,Home Wifi,Personal,
+http://sn,,,,"NoteType:Credit Card
+Number:4111111111111111
+Expiry:01/2030
+CVV:123",Visa Card,Personal,
+https://日本語.example,user,pass,,,日本語サイト,,
+not-a-real-url,user,pass,,,Bad URL,,
+,,,,,,,
+https://x,user,,,,No Password,,
+https://example.com,user,p,,"multi
+line
+notes",Multiline,,

crates/relicario-cli/tests/import_lastpass.rs

@@ -0,0 +1,127 @@
+mod common;
+use common::TestVault;
+
+const FIXTURE: &str = "tests/fixtures/lastpass-sample.csv";
+
+fn fixture_path() -> std::path::PathBuf {
+    // Manifest dir = crates/relicario-cli; the fixture is relative to it.
+    std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join(FIXTURE)
+}
+
+#[test]
+fn imports_logins_secure_notes_and_warns_on_skipped() {
+    let v = TestVault::init();
+
+    let out = v.run(&["import", "lastpass", fixture_path().to_str().unwrap()]);
+    assert!(
+        out.status.success(),
+        "import failed:\nstdout: {}\nstderr: {}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr),
+    );
+
+    let stderr = String::from_utf8(out.stderr).unwrap();
+    // 9 items expected (see fixture comment).
+    assert!(stderr.contains("Imported 9"), "stderr: {stderr}");
+    assert!(stderr.contains("skipped 2"), "stderr: {stderr}");
+
+    // Each warning surfaces.
+    assert!(stderr.contains("invalid base32 TOTP"), "TOTP warning missing");
+    assert!(stderr.contains("invalid URL"),         "URL warning missing");
+    assert!(stderr.contains("missing `name`"),      "name-missing warning missing");
+    assert!(stderr.contains("missing `password`"),  "password-missing warning missing");
+}
+
+#[test]
+fn list_after_import_shows_imported_titles() {
+    let v = TestVault::init();
+    v.run(&["import", "lastpass", fixture_path().to_str().unwrap()]);
+
+    let out = v.run(&["list"]);
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    assert!(stdout.contains("GitHub"));
+    assert!(stdout.contains("Gmail"));
+    assert!(stdout.contains("Home Wifi"));
+    assert!(stdout.contains("Visa Card"));
+    assert!(stdout.contains("日本語サイト"));
+    // Skipped rows must NOT appear.
+    assert!(!stdout.contains("No Password"),
+        "row with no password should have been skipped");
+}
+
+#[test]
+fn import_creates_a_single_git_commit() {
+    let v = TestVault::init();
+
+    // Count commits before.
+    let before = std::process::Command::new("git")
+        .arg("-C").arg(v.path())
+        .args(["rev-list", "--count", "HEAD"])
+        .output().unwrap();
+    let before_n: u32 = String::from_utf8(before.stdout).unwrap().trim().parse().unwrap();
+
+    v.run(&["import", "lastpass", fixture_path().to_str().unwrap()]);
+
+    let after = std::process::Command::new("git")
+        .arg("-C").arg(v.path())
+        .args(["rev-list", "--count", "HEAD"])
+        .output().unwrap();
+    let after_n: u32 = String::from_utf8(after.stdout).unwrap().trim().parse().unwrap();
+
+    assert_eq!(after_n, before_n + 1, "expected exactly one new commit");
+
+    // Commit message includes the count + "LastPass".
+    let log = std::process::Command::new("git")
+        .arg("-C").arg(v.path())
+        .args(["log", "-1", "--pretty=%s"])
+        .output().unwrap();
+    let subject = String::from_utf8(log.stdout).unwrap();
+    assert!(subject.contains("9 items"));
+    assert!(subject.contains("LastPass"));
+}
+
+#[test]
+fn import_with_zero_items_exits_nonzero() {
+    let v = TestVault::init();
+
+    // Header-only CSV with one bad row → 0 items.
+    let bad_csv = v.path().join("empty.csv");
+    std::fs::write(
+        &bad_csv,
+        "url,username,password,totp,extra,name,grouping,fav\n,,,,,,,\n",
+    ).unwrap();
+
+    let out = v.run(&["import", "lastpass", bad_csv.to_str().unwrap()]);
+    assert!(!out.status.success(), "expected non-zero exit on zero items");
+    let stderr = String::from_utf8(out.stderr).unwrap();
+    assert!(stderr.contains("imported 0 items"), "stderr: {stderr}");
+}
+
+#[test]
+fn import_rejects_unrecognized_header() {
+    let v = TestVault::init();
+    let bad_csv = v.path().join("wrong.csv");
+    std::fs::write(&bad_csv, "name,url,user,pass\nA,https://x,u,p\n").unwrap();
+
+    let out = v.run(&["import", "lastpass", bad_csv.to_str().unwrap()]);
+    assert!(!out.status.success());
+    let stderr = String::from_utf8(out.stderr).unwrap();
+    assert!(
+        stderr.contains("LastPass") || stderr.contains("expected"),
+        "stderr: {stderr}",
+    );
+}
+
+#[test]
+fn imported_items_keep_unique_ids_across_runs() {
+    // Decision D12: two imports of the same CSV must not collide.
+    let v = TestVault::init();
+    v.run(&["import", "lastpass", fixture_path().to_str().unwrap()]);
+    v.run(&["import", "lastpass", fixture_path().to_str().unwrap()]);
+
+    let out = v.run(&["list"]);
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    // Each title imported twice — count occurrences of "GitHub" must be 2.
+    let github_count = stdout.matches("GitHub").count();
+    assert_eq!(github_count, 2, "stdout: {stdout}");
+}

crates/relicario-cli/tests/settings.rs

@@ -21,3 +21,138 @@ fn settings_rejects_conflicting_retention_flags() {
     let out = v.run(&["settings", "trash-retention", "--days", "30", "--forever"]);
     assert!(!out.status.success());
 }
+
+#[test]
+fn generate_uses_vault_default_length() {
+    let v = TestVault::init();
+
+    // Default vault settings: GeneratorRequest::Random { length: 20, ... }.
+    let out = v.run(&["generate"]);
+    assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
+    let pw = String::from_utf8(out.stdout).unwrap();
+    assert_eq!(
+        pw.trim().chars().count(),
+        20,
+        "expected 20 chars at default, got {pw:?}"
+    );
+
+    // Update the vault default length to 32.
+    let out = v.run(&["settings", "generator-defaults", "--length", "32"]);
+    assert!(
+        out.status.success(),
+        "set generator-defaults failed: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+
+    // `generate` (no flags) should now produce 32 chars.
+    let out = v.run(&["generate"]);
+    assert!(out.status.success(), "{:?}", String::from_utf8_lossy(&out.stderr));
+    let pw = String::from_utf8(out.stdout).unwrap();
+    assert_eq!(
+        pw.trim().chars().count(),
+        32,
+        "expected 32 chars after update, got {pw:?}"
+    );
+
+    // Explicit flag overrides the vault default.
+    let out = v.run(&["generate", "--length", "8"]);
+    assert!(out.status.success());
+    let pw = String::from_utf8(out.stdout).unwrap();
+    assert_eq!(
+        pw.trim().chars().count(),
+        8,
+        "explicit flag should override vault default, got {pw:?}"
+    );
+}
+
+#[test]
+fn status_reports_item_and_attachment_counts() {
+    let v = TestVault::init();
+    v.run(&["add", "login", "--title", "active",
+           "--username", "u", "--password", "p"]);
+    v.run(&["add", "login", "--title", "to-trash",
+           "--username", "u", "--password", "p"]);
+    v.run(&["rm", "to-trash"]);
+
+    let payload = v.path().join("payload.txt");
+    std::fs::write(&payload, b"hello-world").unwrap();
+    v.run(&["attach", "active", payload.to_str().unwrap()]);
+
+    let out = v.run(&["status"]);
+    assert!(
+        out.status.success(),
+        "status failed:\nstdout: {}\nstderr: {}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr),
+    );
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    let lower = stdout.to_lowercase();
+
+    // 1 active + 1 trashed = 2 items total.
+    assert!(lower.contains("items"), "missing items section: {stdout}");
+    assert!(stdout.contains('2') || stdout.contains("2 ")
+            || lower.contains("active: 1") || lower.contains("1 active"),
+            "expected item counts in output: {stdout}");
+    assert!(lower.contains("trash"), "missing trash count: {stdout}");
+
+    // 1 attachment, 11 bytes.
+    assert!(lower.contains("attachment"), "missing attachment section: {stdout}");
+    assert!(stdout.contains("11"), "expected 11-byte size in output: {stdout}");
+
+    // device count line removed — device key system was security theater (audit B1).
+
+    // Last-commit line.
+    assert!(
+        lower.contains("last commit") || lower.contains("commit"),
+        "missing last-commit info: {stdout}",
+    );
+}
+
+#[test]
+fn status_shows_last_backup_line() {
+    let v = TestVault::init();
+    let out = v.run(&["status"]);
+    assert!(out.status.success());
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    assert!(stdout.contains("Last export:"), "missing last export line: {stdout}");
+    assert!(stdout.contains("never"), "fresh vault should report 'never': {stdout}");
+}
+
+#[test]
+fn status_shows_recent_backup_after_export() {
+    let v = TestVault::init();
+    let backup_path = v.path().join("v.relbak");
+    v.run_with_backup_pass(
+        &["backup", "export", backup_path.to_str().unwrap()],
+        "test-backup-pass-2026",
+    );
+    let out = v.run(&["status"]);
+    let stdout = String::from_utf8(out.stdout).unwrap();
+    assert!(stdout.contains("Last export:"), "{stdout}");
+    assert!(!stdout.contains("never"), "should NOT say 'never' after export: {stdout}");
+}
+
+#[test]
+fn generate_works_outside_vault() {
+    use assert_cmd::cargo::CommandCargoExt;
+    use std::process::{Command, Stdio};
+    use tempfile::TempDir;
+
+    let tmp = TempDir::new().unwrap();
+    let out = Command::cargo_bin("relicario")
+        .unwrap()
+        .current_dir(tmp.path())
+        .args(["generate", "--length", "12"])
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .output()
+        .unwrap();
+    assert!(
+        out.status.success(),
+        "no-vault generate failed: {}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+    let pw = String::from_utf8(out.stdout).unwrap();
+    assert_eq!(pw.trim().chars().count(), 12);
+}

crates/relicario-cli/tests/smart_inputs.rs

@@ -0,0 +1,210 @@
+mod common;
+
+use assert_cmd::Command;
+use predicates::prelude::PredicateBooleanExt;
+use predicates::str::contains;
+
+#[test]
+fn completions_bash_emits_script() {
+    Command::cargo_bin("relicario").unwrap()
+        .args(["completions", "bash"])
+        .assert()
+        .success()
+        .stdout(contains("_relicario"))
+        .stdout(contains("complete -F"));
+}
+
+#[test]
+fn completions_zsh_emits_script() {
+    Command::cargo_bin("relicario").unwrap()
+        .args(["completions", "zsh"])
+        .assert()
+        .success()
+        .stdout(contains("#compdef relicario"));
+}
+
+#[test]
+fn completions_fish_emits_script() {
+    Command::cargo_bin("relicario").unwrap()
+        .args(["completions", "fish"])
+        .assert()
+        .success()
+        .stdout(contains("complete -c relicario"));
+}
+
+#[test]
+fn list_command_refreshes_groups_cache() {
+    let v = common::TestVault::init();
+
+    let out = v.run(&[
+        "add", "login",
+        "--title", "T",
+        "--username", "u",
+        "--group", "work",
+        "--password", "hunter2",
+    ]);
+    assert!(out.status.success(), "add failed: {:?}", out);
+
+    let out = v.run(&["list"]);
+    assert!(out.status.success(), "list failed: {:?}", out);
+
+    let cache_path = v.path().join(".relicario/groups.cache");
+    let cache = std::fs::read_to_string(&cache_path)
+        .unwrap_or_else(|e| panic!("groups.cache not found at {}: {e}", cache_path.display()));
+    assert!(
+        cache.lines().any(|l| l == "work"),
+        "expected 'work' in groups.cache, got: {cache:?}"
+    );
+}
+
+#[test]
+fn no_groups_cache_env_var_suppresses_write() {
+    use std::process::{Command as StdCommand, Stdio};
+    use assert_cmd::cargo::CommandCargoExt as _;
+
+    let v = common::TestVault::init();
+
+    // Add with the env var set so no cache is created by add either.
+    let out = StdCommand::cargo_bin("relicario").unwrap()
+        .current_dir(v.path())
+        .env("RELICARIO_IMAGE", &v.reference_image)
+        .env("RELICARIO_TEST_PASSPHRASE", &v.passphrase)
+        .env("RELICARIO_NO_GROUPS_CACHE", "1")
+        .args([
+            "add", "login",
+            "--title", "T2",
+            "--username", "u",
+            "--group", "personal",
+            "--password", "hunter2",
+        ])
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .output()
+        .unwrap();
+    assert!(out.status.success(), "add failed: {:?}", out);
+
+    // Run list with RELICARIO_NO_GROUPS_CACHE=1 — cache must NOT be written.
+    let out = StdCommand::cargo_bin("relicario").unwrap()
+        .current_dir(v.path())
+        .env("RELICARIO_IMAGE", &v.reference_image)
+        .env("RELICARIO_TEST_PASSPHRASE", &v.passphrase)
+        .env("RELICARIO_NO_GROUPS_CACHE", "1")
+        .args(["list"])
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .output()
+        .unwrap();
+    assert!(out.status.success(), "list failed: {:?}", out);
+
+    let cache_path = v.path().join(".relicario/groups.cache");
+    assert!(
+        !cache_path.exists(),
+        "groups.cache should not exist when RELICARIO_NO_GROUPS_CACHE=1"
+    );
+}
+
+#[test]
+fn rate_strong_passphrase_prints_score_and_guesses() {
+    Command::cargo_bin("relicario").unwrap()
+        .args(["rate", "correct horse battery staple table cocoa rocket spirit ferment"])
+        .assert()
+        .success()
+        .stdout(contains("score:"))
+        .stdout(contains("guesses:"))
+        .stdout(contains("strong"));
+}
+
+#[test]
+fn rate_weak_passphrase_exits_zero_with_weak_label() {
+    // `rate` is informational — does NOT exit nonzero on weak input.
+    // The hard gate lives at `init` (Plan 2B Task 10).
+    Command::cargo_bin("relicario").unwrap()
+        .args(["rate", "password"])
+        .assert()
+        .success()
+        .stdout(contains("very weak").or(contains("weak")));
+}
+
+#[test]
+fn rate_reads_from_stdin_when_arg_is_dash() {
+    Command::cargo_bin("relicario").unwrap()
+        .args(["rate", "-"])
+        .write_stdin("correcthorsebatterystaple\n")
+        .assert()
+        .success()
+        .stdout(contains("score:"));
+}
+
+fn make_test_qr(uri: &str, dest: &std::path::Path) {
+    use image::{ImageBuffer, Luma};
+    let code = qrcode::QrCode::new(uri).expect("QR encode failed");
+    let img: ImageBuffer<Luma<u8>, Vec<u8>> = code
+        .render::<Luma<u8>>()
+        .module_dimensions(8, 8)
+        .build();
+    img.save(dest).expect("save QR PNG");
+}
+
+#[test]
+fn add_login_totp_qr_decodes_otpauth_uri() {
+    use tempfile::TempDir;
+    let tmp = TempDir::new().unwrap();
+    let qr_path = tmp.path().join("test.png");
+    make_test_qr(
+        "otpauth://totp/Example:alice?secret=JBSWY3DPEHPK3PXP&issuer=Example",
+        &qr_path,
+    );
+
+    let v = common::TestVault::init();
+
+    let out = v.run(&[
+        "add", "login",
+        "--title", "TotpTest",
+        "--password", "hunter2",
+        "--totp-qr", qr_path.to_str().unwrap(),
+    ]);
+    assert!(out.status.success(), "add failed:\nstdout: {}\nstderr: {}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr));
+
+    let out = v.run(&["get", "TotpTest", "--show"]);
+    assert!(out.status.success(), "get failed:\nstdout: {}\nstderr: {}",
+        String::from_utf8_lossy(&out.stdout),
+        String::from_utf8_lossy(&out.stderr));
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    // BASE32.encode(BASE32.decode("JBSWY3DPEHPK3PXP")) should round-trip.
+    // The secret bytes from JBSWY3DPEHPK3PXP decode to specific bytes,
+    // then re-encode to JBSWY3DPEHPK3PXP====; we check for the core chars.
+    assert!(
+        stdout.contains("JBSWY3DPEHPK3PXP"),
+        "expected TOTP secret in get output, got:\n{stdout}"
+    );
+}
+
+#[test]
+fn add_login_totp_qr_errors_on_non_otpauth_qr() {
+    use tempfile::TempDir;
+    let tmp = TempDir::new().unwrap();
+    let qr_path = tmp.path().join("nottotp.png");
+    make_test_qr("https://example.com", &qr_path);
+
+    let v = common::TestVault::init();
+
+    let out = v.run(&[
+        "add", "login",
+        "--title", "BadQR",
+        "--password", "hunter2",
+        "--totp-qr", qr_path.to_str().unwrap(),
+    ]);
+    assert!(
+        !out.status.success(),
+        "expected nonzero exit for non-otpauth QR, but command succeeded"
+    );
+    let stderr = String::from_utf8_lossy(&out.stderr);
+    assert!(
+        stderr.contains("not a TOTP URI"),
+        "expected 'not a TOTP URI' in stderr, got:\n{stderr}"
+    );
+}

crates/relicario-core/ARCHITECTURE.md

@@ -0,0 +1,514 @@
+# Architecture: relicario-core
+
+## What this crate is for
+
+`relicario-core` is the platform-agnostic cryptographic and data-model heart of the
+relicario password manager. It is strictly **bytes-in / bytes-out**: every public
+function takes byte slices or owned typed structs and returns byte vectors or typed
+structs. The crate performs no filesystem I/O, no network I/O, no git operations,
+and no time-of-day reads beyond `chrono::Utc::now()` for timestamping items
+(`time.rs:6`). This boundary is what lets the same compiled artifact serve the
+native CLI (`relicario-cli`), a `wasm32-unknown-unknown` build embedded in the
+Chrome MV3 / Firefox WebExtension popup (`relicario-wasm`), and (eventually) ARM
+mobile builds — without conditional compilation. Anything that touches a
+`Path`, opens a socket, or shells out belongs in `relicario-cli` or the
+extension layer, never here. The historical rationale is in
+`docs/superpowers/specs/2026-04-11-relicario-design.md` (sections "Crypto
+Pipeline" and "Crate Layout").
+
+## Module map
+
+- **`lib.rs`** — Public API surface. Re-exports the symbols that callers actually
+  need (`encrypt_item`, `derive_master_key`, `Item`, `ItemCore`, etc.). The
+  module list here is the contract; everything else is internal.
+- **`error.rs`** — `RelicarioError` (a `thiserror`-derived enum) plus the crate
+  alias `Result<T> = std::result::Result<T, RelicarioError>`. One error type
+  for the whole crate so FFI / WASM bindings and CLI handlers each have a single
+  exhaustive `match` to maintain. `Decrypt` is intentionally opaque (no inner
+  detail string) — see "Cross-cutting concerns".
+- **`crypto.rs`** — KDF (`derive_master_key`, Argon2id with NFC-normalized,
+  length-prefixed inputs) and AEAD (`encrypt`, `decrypt`, XChaCha20-Poly1305
+  with `VERSION_BYTE = 0x02`). Owns the on-disk ciphertext layout. The KDF
+  parameters (`KdfParams`) are an owned struct that callers persist however
+  they like (CLI puts them in `.relicario/params.json`); the crate has no
+  opinion about storage.
+- **`ids.rs`** — `ItemId`, `FieldId` (random 64-bit hex from `OsRng`,
+  `ids.rs:26-32`, `ids.rs:38-49`) and content-addressed `AttachmentId`
+  (first 8 bytes of `SHA-256(plaintext)`, `ids.rs:51-57`). Three separate
+  newtypes rather than `String` so misuses can't compile.
+- **`time.rs`** — `now_unix()` and `MonthYear` (the validated 1..=12 / 2000..=2099
+  card-expiry type). Trivially small; broken out only because every other module
+  needs `now_unix()` and `MonthYear` is used by both `item.rs` and
+  `item_types/card.rs`.
+- **`item_types/mod.rs`** — `ItemType` enum (snake-case wire tag) and `ItemCore`
+  (internally tagged `#[serde(tag = "type")]` enum), with one variant per item
+  type. The "extension via match exhaustiveness" pattern is documented at
+  `item_types/mod.rs:1-7`: adding an item type is a `cargo check` walk through
+  every match arm. Re-exports each per-type core.
+- **`item_types/login.rs`** — `LoginCore` (username, password as
+  `Zeroizing<String>`, optional `Url`, optional `TotpConfig`).
+- **`item_types/secure_note.rs`** — `SecureNoteCore` (single `Zeroizing<String>`
+  body).
+- **`item_types/identity.rs`** — `IdentityCore` (full name, address, phone,
+  email, DOB; all optional, none `Zeroizing` — they're personal data, not
+  secret material).
+- **`item_types/card.rs`** — `CardCore` plus `CardKind` (Credit/Debit/Gift/
+  Loyalty/Other). `number`, `cvv`, `pin` are `Zeroizing`; `holder` is plain
+  `String`.
+- **`item_types/key.rs`** — `KeyCore`: opaque `Zeroizing<String>` `key_material`
+  with optional label / public key / algorithm. Used for SSH keys, GPG keys,
+  arbitrary blobs.
+- **`item_types/document.rs`** — `DocumentCore`: filename + mime + a single
+  `AttachmentId` pointing at the primary blob. The body lives in the
+  attachment store, not the item.
+- **`item_types/totp.rs`** — `TotpCore`, `TotpConfig`, `TotpAlgorithm`
+  (Sha1/Sha256/Sha512), `TotpKind` (Totp / Hotp{counter} / Steam), and the
+  `compute_totp_code()` function. Includes the Steam Mobile Authenticator
+  5-character alphabet and its conversion (`item_types/totp.rs:103-110`).
+  The same `TotpConfig` is reused as a sub-struct of `LoginCore` (so a Login
+  item can carry its own TOTP without spawning a separate item).
+- **`item.rs`** — The `Item` envelope. Holds the parallel `FieldKind` /
+  `FieldValue` enums (kept parallel so callers can ask the kind without
+  inspecting the value, `item.rs:1-6`), `Field`, `Section`, `FieldHistoryEntry`,
+  and the `Item` struct itself with its `set_field_value` / `soft_delete` /
+  `restore` / `prune_history` mutators. Custom-fields and field-history live
+  here, not in the per-type cores.
+- **`attachment.rs`** — `AttachmentRef` (full record carried on `Item`),
+  `AttachmentSummary` (compact form carried in `Manifest`),
+  `EncryptedAttachment`, and the `encrypt_attachment` / `decrypt_attachment`
+  helpers. The size cap is enforced **before** any crypto work (`attachment.rs:69-74`).
+- **`manifest.rs`** — The browse-without-decrypt index: `Manifest`,
+  `ManifestEntry`, `MANIFEST_SCHEMA_VERSION = 2`. `upsert(&item)` rebuilds the
+  entry from the item — there is no path for the manifest to drift from the
+  source-of-truth item file. Includes case-insensitive title/tag search
+  (`manifest.rs:59-68`) and Login icon-hint derivation (host of the URL,
+  `manifest.rs:93-99`).
+- **`settings.rs`** — `VaultSettings` and its sub-types: `TrashRetention`,
+  `HistoryRetention`, `GeneratorRequest` (`Random` or `Bip39`),
+  `AttachmentCaps`, plus the `autofill_origin_acks` map for the extension's
+  TOFU prompt.
+- **`generators.rs`** — Random-password and BIP-39 passphrase generation, both
+  driven by `GeneratorRequest` from `settings.rs`. zxcvbn-backed
+  `rate_passphrase` and the `validate_passphrase_strength` gate that rejects
+  any score < 3.
+- **`vault.rs`** — Typed wrappers around `crypto::{encrypt, decrypt}`:
+  `encrypt_item`/`decrypt_item`, `encrypt_manifest`/`decrypt_manifest`,
+  `encrypt_settings`/`decrypt_settings`. Each does
+  `serde_json::to_vec → encrypt` (or the inverse). The plaintext `Vec<u8>` is
+  wrapped in `Zeroizing` between serde and the cipher
+  (`vault.rs:18-19`, `vault.rs:24-26`).
+- **`imgsecret.rs`** — Self-contained DCT-based steganography for the second
+  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`.
+
+## Invariants & contracts
+
+- **No filesystem, no network, no git, no spawn.** Verified by inspecting
+  imports; the only I/O-shaped types in use are in-memory `Cursor<&[u8]>`
+  for image decoding (`imgsecret.rs:243`).
+- **No `unsafe`.** Confirmed by `grep` over `src/`. The crate compiles to WASM
+  unmodified for that reason.
+- **No `async`.** All operations are pure compute on byte slices. Async lives
+  in `relicario-cli` (process spawning) and in the extension's service worker
+  (message channels), not here.
+- **`VERSION_BYTE = 0x02`** (`crypto.rs:59`). Every blob produced by
+  `encrypt()` starts with this byte; `decrypt()` rejects any other value with
+  `RelicarioError::UnsupportedFormatVersion { found, expected }`
+  (`crypto.rs:127-132`). v1 blobs (the pre-rewrite format) are explicitly
+  tested for rejection (`tests/format_v2.rs:28-42`).
+- **AEAD blob layout** is fixed at `version(1) || nonce(24) || ciphertext+tag(≥16)`
+  (`crypto.rs:18-32`). Minimum valid blob length is 41 bytes
+  (`crypto.rs:118-124`).
+- **Nonces are always fresh from `OsRng`** (`crypto.rs:87-89`). There is no
+  caller-supplied nonce path. With 192 bits of randomness, collision risk is
+  negligible across the lifetime of any vault.
+- **`MANIFEST_SCHEMA_VERSION = 2`** (`manifest.rs:12`). v1 manifests (which
+  predate typed items) are not handled here and are rejected at the JSON-parse
+  step.
+- **KDF input is length-prefixed.** `derive_master_key` builds the password
+  buffer as `u64_be(len(passphrase)) || passphrase || u64_be(32) || image_secret`
+  (`crypto.rs:229-236`). This eliminates the (`"abc"`, `0x44…`) vs (`"abcD"`,
+  `…`) collision, and is exercised in
+  `crypto.rs:352-368` and `tests/format_v2.rs:44-54`.
+- **Passphrases are NFC-normalized before hashing.** Bytes that aren't valid
+  UTF-8 pass through unchanged (`crypto.rs:223-227`). This keeps "café"
+  (precomposed) and "café" (combining acute) from producing different keys
+  (`crypto.rs:370-385`).
+- **Master key only ever lives in `Zeroizing<[u8; 32]>`.** Returned that way
+  by `derive_master_key` (`crypto.rs:212`) and accepted that way by
+  `encrypt_item` / `encrypt_attachment` / friends. No public function in
+  `vault.rs` or `attachment.rs` accepts a raw `[u8; 32]`.
+- **Plaintext is wrapped in `Zeroizing` between serde and the cipher.** See
+  `vault.rs:18-19`, `vault.rs:24-26`, `vault.rs:31-32`, `vault.rs:37-38`,
+  `vault.rs:44-45`, `vault.rs:50-51`. The serde JSON intermediate buffer is the
+  most exposed point, so it is wiped on drop.
+- **`AttachmentId` is content-addressed** to the first 8 bytes (= 16 hex chars)
+  of `SHA-256(plaintext)` (`ids.rs:51-57`). Identical plaintexts deduplicate
+  in git automatically — proven in `tests/attachments.rs:28-35`. The 64-bit
+  prefix is used (rather than the full digest) to keep filenames short; the
+  collision space is still adequate for the expected vault size.
+- **`ItemId` and `FieldId` are 16 hex chars** = 64 bits of `OsRng` entropy
+  (`ids.rs:25-32`, `ids.rs:38-49`). The audit (M8) bumped them from the
+  original 8-char / 32-bit format.
+- **Field kind/value discriminants must agree.** `Field::new` derives `kind`
+  from `value` (`item.rs:85-94`); `Field::validate` (called after deserialize)
+  rejects any mismatch (`item.rs:97-107`). `set_field_value` further refuses
+  to change a field's kind (`item.rs:184-189`).
+- **Field-history capture is restricted to three kinds:** `Password`,
+  `Concealed`, `Totp` (`item.rs:68-71`). Any other kind's update silently
+  skips history. The TOTP secret is base32-encoded for the history entry
+  (`item.rs:245-249`) so a user reading their history sees a recognizable
+  string.
+- **History captures the *previous* value, not the new one** (`item.rs:190-197`):
+  `set_field_value` serializes `field.value` *before* assigning the new value.
+- **`hidden_by_default` is set automatically** when the field's kind is
+  `Password` or `Concealed` (`item.rs:92`). The extension and CLI both honor
+  this hint when rendering.
+- **Attachment cap is checked before encryption** (`attachment.rs:69-74`).
+  An oversize blob fails with `RelicarioError::AttachmentTooLarge { size, max }`
+  without ever calling `encrypt`. The CLI/extension are expected to read the
+  cap from `VaultSettings::attachment_caps`.
+- **`Item::soft_delete` does not erase data.** It sets `trashed_at` and bumps
+  `modified` (`item.rs:205-208`). Purging is the caller's responsibility,
+  driven by `TrashRetention::should_purge` (`settings.rs:38-44`).
+- **`prune_history` is idempotent and explicit.** Items keep all history until
+  the caller invokes it with a `HistoryRetention` policy (`item.rs:219-237`).
+  Last-N drops oldest first; Days drops anything older than `now - days·86400`.
+- **`item_type()` is the single source of truth** for the type tag stored on
+  `Item`. `Item::new` derives `r#type` from the supplied `ItemCore`
+  (`item.rs:159-164`). Manual construction can violate this — the JSON
+  round-trip does not re-validate beyond serde's tag matching.
+- **Reserved serde key:** no `*Core` may have a JSON-serialized field named
+  `"type"` — that name is reserved for serde's discriminator on `ItemCore`
+  (`item_types/mod.rs:38-40`). Use `"kind"` instead (see `CardKind`,
+  `TotpKind`).
+- **`MAX_DIMENSION = 10_000`** for imgsecret (`imgsecret.rs:71`). Enforced via
+  a header-only peek (`imgsecret.rs:127-176`) at the entry of both `embed` and
+  `extract` so an attacker-supplied 32000×32000 JPEG is rejected without
+  decoding pixels (audit M3).
+- **`MIN_DIMENSION = 100`** plus a "must hold ≥5 redundant copies" floor
+  (`imgsecret.rs:66`, `imgsecret.rs:78`, `imgsecret.rs:682-689`). Smaller
+  carriers are rejected with `ImageTooSmall`.
+- **Strength gate is `score >= 3`** (`generators.rs:124-130`). Vault-creation
+  callers must invoke `validate_passphrase_strength` themselves; the crate
+  does not internally call it inside `derive_master_key` (since that path is
+  also used to derive the key for *unlock*, not just create).
+- **`SymbolCharset::Custom` must be ASCII-only** (`generators.rs:46-52`).
+  Non-ASCII custom charsets are rejected with `RelicarioError::Format`.
+
+## Key flows
+
+### Vault unlock — key derivation
+
+1. Caller obtains `passphrase: &[u8]` (UTF-8) and `image_secret: &[u8; 32]`
+   (typically from `imgsecret::extract` over the user's reference JPEG).
+2. Caller loads `salt: [u8; 32]` and `KdfParams` from out-of-band storage
+   (CLI: `.relicario/salt` and `.relicario/params.json`).
+3. `derive_master_key(passphrase, &image_secret, &salt, &params)` —
+   `crypto.rs:207-244`:
+   - NFC-normalize the passphrase if it parses as UTF-8 (`crypto.rs:223-227`).
+   - Build the length-prefixed password buffer in a `Zeroizing<Vec<u8>>`
+     (`crypto.rs:229-236`).
+   - Run `Argon2id` with `Algorithm::Argon2id`, `Version::V0x13`,
+     output length 32 (`crypto.rs:213-221`, `crypto.rs:238-241`).
+4. Returns `Zeroizing<[u8; 32]>` — automatically wiped on drop.
+
+A wrong passphrase or wrong image produces a *different* derived key. The crate
+cannot tell them apart at this stage; the caller learns "wrong factor" only
+when subsequent `decrypt_*` returns `RelicarioError::Decrypt`.
+
+### Item write
+
+1. Caller mutates an `Item` (e.g. `item.set_field_value(&fid, new_value)` —
+   `item.rs:181-203`). `set_field_value` captures previous value into
+   `field_history` if the kind is history-tracked, then bumps `modified`.
+2. Caller calls `encrypt_item(&item, &master_key)` — `vault.rs:16-20`:
+   `serde_json::to_vec(item)` → wrap in `Zeroizing` → `crypto::encrypt`.
+3. Caller calls `manifest.upsert(&item)` (`manifest.rs:45-48`) to refresh the
+   browse-index entry; then `encrypt_manifest(&manifest, &master_key)`
+   (`vault.rs:29-33`).
+4. The two ciphertext blobs are returned to the caller, who writes them to disk
+   (or commits them, or sends them over a sync channel).
+
+### Item read (browse-without-decrypt path)
+
+1. Caller calls `decrypt_manifest(&manifest_blob, &master_key)`
+   (`vault.rs:35-40`). One AEAD decryption gets the entire searchable index.
+2. `Manifest::search(query)` does a case-insensitive substring match over title
+   and tags (`manifest.rs:59-68`). `manifest.items.values()` gives every
+   `ManifestEntry` with `title`, `tags`, `favorite`, `group`, `icon_hint`,
+   `modified`, `trashed_at`, and `attachment_summaries` — enough to render a
+   list UI without touching any item file.
+3. When the user picks an entry, the caller reads `entries/<id>.enc` and calls
+   `decrypt_item(&blob, &master_key)` (`vault.rs:22-27`) to get the full
+   `Item` including secret fields and `field_history`.
+
+### Attachment encryption
+
+1. Caller has `plaintext: &[u8]`, the `master_key`, and the active
+   `VaultSettings::attachment_caps.per_attachment_max_bytes`.
+2. `encrypt_attachment(plaintext, &master_key, max_bytes)` —
+   `attachment.rs:64-78`:
+   - If `plaintext.len() > max_bytes`, return `AttachmentTooLarge` *immediately*
+     before any crypto.
+   - `AttachmentId::from_plaintext(plaintext)` (SHA-256, `ids.rs:51-57`).
+   - `crypto::encrypt(master_key, plaintext)`.
+3. Returns `EncryptedAttachment { id, bytes }`. The caller persists `bytes` at
+   `attachments/<id>.enc` and adds an `AttachmentRef { id, filename, mime_type,
+   size, created }` (`attachment.rs:11-20`) to the owning `Item`. On
+   `Manifest::upsert`, an `AttachmentSummary` (no `created` field) is derived
+   automatically (`manifest.rs:87`).
+
+### Field-history capture
+
+1. Triggered exclusively by `Item::set_field_value` (`item.rs:181-203`). Direct
+   mutation of `field.value` bypasses history — the type system does not
+   prevent this.
+2. The check `field.value.is_history_tracked()` runs *on the existing value*
+   (`item.rs:190`), so adding the *first* password value to a previously-empty
+   field does not create a history entry; updating an already-set password
+   does.
+3. The previous value is serialized via `serialize_history_value`
+   (`item.rs:241-253`):
+   - `Password(p)` and `Concealed(c)` clone the inner string into a fresh
+     `Zeroizing<String>`.
+   - `Totp(cfg)` base32-encodes the raw secret bytes
+     (`item.rs:245-249`, `item.rs:256-275`).
+   - Any other kind would error (`item.rs:250`), but is unreachable because
+     `is_history_tracked` already gated the call.
+4. Pruning is *not* automatic. Callers (CLI commit hook, extension save handler)
+   call `item.prune_history(&settings.field_history_retention, now_unix())`
+   when they want to enforce the policy.
+
+### imgsecret embed
+
+1. Caller passes a JPEG byte slice and a 32-byte secret to
+   `imgsecret::embed(carrier_jpeg, &secret)` (`imgsecret.rs:666-726`).
+2. `enforce_dimension_cap` walks JPEG markers (`imgsecret.rs:127-161`) to read
+   the SOF dimensions; rejects > 10_000 × 10_000 before any pixel decode.
+3. `extract_y_channel` decodes via `image::ImageReader` and converts each pixel
+   to BT.601 luminance (`imgsecret.rs:242-265`).
+4. `central_region` picks the inner 70% of the image as the embed region; the
+   15% margin per side is the "crumple zone" for crops
+   (`imgsecret.rs:268-293`).
+5. `compute_embed_positions` / `select_embed_blocks` lay out
+   `num_copies × BLOCKS_PER_COPY` 8×8 blocks evenly across the region, with
+   `num_copies` = `min(50, total_blocks / 22)` (`imgsecret.rs:530-575`).
+6. For each block: 2D DCT (`dct2_8x8`, `imgsecret.rs:393-412`) → embed 12 bits
+   into the 12 mid-frequency coefficients listed in `EMBED_POSITIONS`
+   (zig-zag positions 6–17, `imgsecret.rs:105-118`) via QIM with
+   `QUANT_STEP = 50.0` (`imgsecret.rs:462-467`) → 2D inverse DCT → write
+   back into Y.
+7. `reconstruct_jpeg` (`imgsecret.rs:590-640`) re-derives Cb/Cr per pixel from
+   the original RGB (so chrominance is preserved), combines with the modified
+   Y, and re-encodes at JPEG quality 92.
+
+### imgsecret extract (with crop recovery)
+
+1. `extract(jpeg_bytes)` enforces the dimension cap, then delegates to
+   `extract_with_crop_recovery` (`imgsecret.rs:738-741`,
+   `imgsecret.rs:849-899`).
+2. **Try 1** — assume uncropped: `try_extract_with_layout(&y, w, h, 0, 0)`.
+   This is the hot path; for a freshly embedded image it always succeeds.
+3. **Try 2** — width-only crop, block-aligned: iterate `orig_w` from current
+   width up to `1.20 × current_w` in 8-px steps, with `dx = 0`
+   (assume right-edge crop).
+4. **Try 3** — height-only crop, block-aligned: same strategy on the vertical
+   axis.
+5. **Try 4** — width crops at non-block-aligned 1-px steps, skipping any
+   already covered in Try 2.
+6. `try_extract_with_layout` (`imgsecret.rs:754-834`) tallies QIM votes for
+   each of the 256 bit positions across all `num_copies` copies. Each bit
+   must reach **≥60% confidence** (`imgsecret.rs:824`); below that, the
+   whole extraction fails with `ExtractionFailed` (no partial result is
+   ever returned).
+7. The 60% threshold is per-bit, not aggregate — a single unconfident bit
+   aborts the whole try. This makes false-positive extractions from
+   never-embedded images vanishingly unlikely.
+
+## Cross-cutting concerns
+
+- **Error model.** `RelicarioError` (`error.rs:15-89`) is a single
+  `thiserror`-derived enum. `Decrypt` is the deliberately-opaque "wrong key
+  or tampered ciphertext" variant (audit M4 — `error.rs:28-30`,
+  `tests/integration.rs:99-111`): the message is just `"decryption failed"`
+  with no inner string, and it does not distinguish wrong-passphrase from
+  wrong-image-secret from corrupted ciphertext. `Format` is the
+  "input bytes don't make sense" variant (e.g. blob too short, schema
+  mismatch). `UnsupportedFormatVersion` is the structured "wrong version
+  byte" variant — separate from `Format` because callers want to react to
+  it differently (offer migration, etc.).
+- **Where secrets live.** Every secret type wraps `Zeroizing<...>`:
+  - The derived master key: `Zeroizing<[u8; 32]>` (`crypto.rs:212`).
+  - Field values: `FieldValue::Password(Zeroizing<String>)` and
+    `FieldValue::Concealed(Zeroizing<String>)` (`item.rs:39-40`).
+  - `FieldHistoryEntry::value`: `Zeroizing<String>` (`item.rs:127`).
+  - Per-type cores: `LoginCore::password`, `CardCore::{number,cvv,pin}`,
+    `KeyCore::key_material`, `SecureNoteCore::body`, `TotpConfig::secret`
+    (a `Zeroizing<Vec<u8>>` of the raw HMAC key).
+  - Decrypted attachment plaintext: `Zeroizing<Vec<u8>>`
+    (`attachment.rs:88-92`).
+  - Argon2id input buffer (`crypto.rs:232`) and JSON serialization buffers in
+    `vault.rs` are wrapped in `Zeroizing` to wipe the intermediate plaintext.
+- **Format versioning.** Three independent version channels exist, each
+  gating something different:
+  - `crypto::VERSION_BYTE = 0x02` (`crypto.rs:59`) — gates the AEAD blob
+    layout. Bumped if the nonce length, header layout, or cipher changes.
+    A v1 blob is rejected with a typed
+    `UnsupportedFormatVersion { found: 0x01, expected: 0x02 }`.
+  - `manifest::MANIFEST_SCHEMA_VERSION = 2` (`manifest.rs:12`) — gates the
+    JSON-level shape of the manifest. v1 manifests had a different layout
+    and would fail to parse against the current `Manifest` struct.
+  - The `.relbak` import/export format defined in
+    `docs/superpowers/specs/2026-04-27-relicario-import-export-design.md`
+    will introduce a third version channel for backups; that surface lives
+    outside this crate.
+- **KDF parameter handling.** `KdfParams` (`crypto.rs:156-168`) is just a
+  serializable struct. The crate has no opinion about where it is stored,
+  how it is rotated, or who increments it. `Default` gives the production
+  values (`m=65536`, `t=3`, `p=4` — `crypto.rs:175-183`) calibrated for
+  ~0.5–1 s on a modern desktop. Tests universally use the fast triplet
+  `(m=256, t=1, p=1)` defined as a `fn fast_params()` near the top of every
+  test file.
+- **NFC normalization is the only Unicode op.** All passphrase canonicalization
+  happens in one place (`crypto.rs:223-227`). Item titles, field labels,
+  tags, etc. are stored verbatim — only the passphrase fed to the KDF is
+  normalized.
+- **No per-entry subkeys.** Every encrypted blob (item, manifest, settings,
+  attachment) is encrypted with the *same* master key. The design rationale
+  is in `docs/superpowers/specs/2026-04-11-relicario-design.md` lines 66:
+  per-entry subkey derivation would add complexity for no real-world benefit
+  given the expected family-vault size.
+- **CSPRNG is `OsRng` everywhere.** `ItemId::new`, `FieldId::new`,
+  `derive_master_key` (no-op — the salt is caller-supplied),
+  `crypto::encrypt` (nonce), `generators::random_password`,
+  `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.
+
+## Test architecture
+
+All `tests/` files use the fast Argon2id triplet `m=256, t=1, p=1` so the
+suite runs in seconds, not minutes. Test JPEGs are synthesized at runtime via
+`make_test_jpeg(width, height)` (`imgsecret.rs:908-924`) — a deterministic RGB
+pattern at quality 92 — so no binary fixtures live in git.
+
+- **`tests/integration.rs`** — End-to-end vault workflows: encrypt+decrypt a
+  Login and a SecureNote through `Manifest`/`VaultSettings`, two-factor
+  independence (different passphrase or different image_secret yields
+  different keys), field-history surviving an encrypt/decrypt round-trip,
+  and the wrong-key-→-`Decrypt` opaqueness contract.
+- **`tests/attachments.rs`** — Round-trip a 5 KB blob, prove identical
+  plaintexts produce identical `AttachmentId`s (despite different ciphertext
+  bytes due to fresh nonces), and exercise the cap boundary at exactly the
+  max byte and one over.
+- **`tests/field_history.rs`** — Sequential `set_field_value` calls accumulate
+  history in oldest→newest order; `prune_history(LastN(3))` keeps the most
+  recent 3; field-history survives `encrypt_item` →`decrypt_item`.
+- **`tests/format_v2.rs`** — `VERSION_BYTE == 0x02`, fresh ciphertext starts
+  with `0x02`, a v1-shaped blob (`[0x01][24 nonce][16 tag]`) is rejected with
+  the typed `UnsupportedFormatVersion`, and the length-prefix construction
+  prevents `("abc", 0x44…)` / `("abcD", …)` collisions.
+- **`tests/generators.rs`** — Aggregates 80 × 128 = 10,240 chars from
+  `generate_password` to assert per-character-class proportions are within
+  ±5 pp of the expected uniform distribution; verifies that 5-word BIP-39
+  passes the strength gate while common weak passwords ("password",
+  "12345678", "letmein", "qwertyui", "hunter2") all fail; asserts uniqueness
+  across 1000 default-config calls. The opening doc comment
+  (`tests/generators.rs:1-13`) explains why the original "10,000-char single
+  call" plan switched to aggregation: `generate_password` enforces
+  `length ≤ 128`.
+
+In-module `#[cfg(test)] mod tests` blocks cover unit-level invariants (kind/
+value mismatches, snake-case serde tags, base32 round-trips, `MonthYear`
+constructor bounds, the Steam alphabet ambiguity audit). The `imgsecret`
+test block additionally proves DCT round-tripping, QIM noise tolerance below
+`Q/4 = 12.5`, embed→Q85-recompress→extract round-trip, embed→10%-crop→extract
+round-trip, and the oversized-image-header rejection path.
+
+## Gotchas & non-obvious decisions
+
+- **`QUANT_STEP = 50.0` is intentionally double the academic value of 25**
+  (`imgsecret.rs:62`). Higher quantization steps make the watermark more robust
+  to JPEG recompression at Q85 and below — at the cost of more visible
+  artifacts in the carrier. The reference image is a personal photo, not a
+  publication, so the trade-off favors robustness.
+- **The embed region is the *central 70%* (15% margin per side, "crumple
+  zone")** — `imgsecret.rs:212-218`, `imgsecret.rs:276-293`. Anything in the
+  outer 15% is sacrificed so that mild edge crops (e.g. social-media platform
+  trims) leave the embedded data intact. Tested up to 10% crop in
+  `imgsecret.rs:1108-1137`.
+- **Per-bit majority voting with a 60% confidence floor.**
+  `try_extract_with_layout` tallies votes from every redundant copy and
+  fails the entire extraction if any single bit position is below 60%
+  agreement (`imgsecret.rs:824`). This is more conservative than a global
+  threshold and is what makes false positives from never-embedded images
+  essentially zero — see `extract_from_non_embedded_image_fails`
+  (`imgsecret.rs:1041-1045`).
+- **Number of redundant copies is capped at 50** (`imgsecret.rs:536`,
+  `imgsecret.rs:692-693`). Beyond that, per-block visual artifacts compound
+  faster than the error-correction benefit grows.
+- **`peek_jpeg_dimensions` walks JPEG markers manually instead of using the
+  `image` crate.** `imgsecret.rs:127-161`. A full `ImageReader::decode` of an
+  attacker-supplied 30 000 × 30 000 JPEG would allocate ~3.6 GB of pixel
+  buffer in the WASM service worker before failing — the manual walk reads
+  only the SOF segment and bails in O(marker-count) (audit M3).
+- **`bip39` always generates 128 bits of entropy** (12 mnemonic words) and
+  truncates to `word_count` (`generators.rs:82-89`). This is because
+  `bip39 v2` rejects entropy below 128 bits, but we want to support 3–12 word
+  passphrases. Truncation preserves the per-word independence — the words
+  the user sees still come from a uniformly-sampled-then-truncated 12-word
+  draw.
+- **Steam TOTP output is exactly 5 characters from a 26-glyph alphabet,
+  regardless of the `digits` field on `TotpConfig`** (`item_types/totp.rs:103-110`,
+  asserted in `item_types/totp.rs:240-253`). The alphabet
+  (`23456789BCDFGHJKMNPQRTVWXY`) excludes `0/O`, `1/I/L`, `S` (so `5` is
+  unambiguous), `A`, `E`, `U`, `Z` — all glyphs Valve considered ambiguous
+  in the Steam Mobile Authenticator. Verified at
+  `item_types/totp.rs:274-283`.
+- **`ItemCore` is internally-tagged with `#[serde(tag = "type")]`** — the
+  outer JSON object gets a `"type"` key. This means *no* `*Core` struct may
+  have a field literally named `type`. The convention chosen for
+  type-discriminant fields *inside* a core is `kind` — see `CardKind`,
+  `TotpKind` (`item_types/mod.rs:38-40`).
+- **The TOTP base32 in field-history strips padding.** `base32_encode`
+  (`item.rs:256-275`) is RFC-4648 with no `=` padding — appropriate because
+  the value is for human display in history, not for re-decoding.
+- **`AttachmentId::from_plaintext` uses only the first 8 bytes (= 16 hex
+  chars) of the SHA-256 digest** (`ids.rs:51-57`). 64 bits of collision
+  resistance is sufficient for a personal-vault attachment count; it keeps
+  filenames short. If a future use case demands collision resistance against
+  motivated adversaries (e.g. dedup across untrusted vaults), this width is
+  the lever.
+- **`Field::new` derives `kind` from `value`, but the public struct still
+  stores both** (`item.rs:73-94`). The duplication exists so callers can
+  match on `kind` without inspecting (and potentially decrypting / cloning)
+  `value`. `validate()` is the safety net that runs after deserialization.
+- **`set_field_value` refuses to change a field's kind** (`item.rs:184-189`).
+  The intent is that fields are conceptually fixed-shape after creation;
+  changing a `Text` to a `Password` should be done by deleting the old field
+  and creating a new one (so history doesn't get confused).
+- **`hidden_by_default` is *not* `Zeroize`.** It's purely a UI hint — the
+  rendering layer (CLI output, popup card) decides whether to mask the value
+  on initial display. Secrecy at rest is enforced by the `Zeroizing` wrappers
+  on the value itself, not this flag.
+- **`Manifest::upsert` rebuilds the entry from scratch every call**
+  (`manifest.rs:45-48`, `manifest.rs:75-89`). There is no "patch the
+  existing entry" path. This means the manifest can never carry a stale
+  `icon_hint` or `attachment_summaries` — they are derived freshly from the
+  source `Item` each time.
+- **The strength gate is *not* called inside `derive_master_key`.** It must
+  be invoked separately by the caller during *vault creation* only — not
+  during unlock, where calling it would let an attacker probe whether a
+  wrong passphrase happens to be "strong enough" before the Argon2id work
+  even starts. See `generators.rs:124-130`.
+- **`now_unix()` is `chrono::Utc::now().timestamp()` and is the single time
+  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`.

crates/relicario-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "relicario-core"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 description = "Core library for relicario password manager"
 
@@ -15,6 +15,7 @@ sha2 = "0.10"
 sha1 = "0.10"
 hmac = "0.12"
 ed25519-dalek = { version = "2", features = ["rand_core"] }
+ssh-key = { version = "0.6", features = ["ed25519", "std"] }
 image = { version = "0.25", default-features = false, features = ["jpeg"] }
 
 # Typed-item additions
@@ -26,5 +27,10 @@ chrono = { version = "0.4", default-features = false, features = ["serde", "cloc
 hex = "0.4"
 url = { version = "2", features = ["serde"] }
 getrandom = "0.2"
+zstd = { version = "0.13", default-features = false }
+tar = { version = "0.4", default-features = false }
+base64 = "0.22"
+csv = "1"
+qrcode = { version = "0.14", default-features = false, features = ["svg"] }
 
 [dev-dependencies]

crates/relicario-core/src/backup.rs

@@ -0,0 +1,348 @@
+//! Backup container — encrypted, compressed, single-file archive of a vault.
+//!
+//! ## Format (v1)
+//!
+//! ```text
+//! [magic "RBAK" 4 bytes][version 0x01 1 byte][salt 32 bytes][nonce 24 bytes][ciphertext+tag]
+//! ```
+//!
+//! After AEAD decryption, the plaintext is zstd-compressed bytes whose
+//! decompressed form is a UTF-8 JSON document — see [`Envelope`].
+//!
+//! The backup container key is **independent** of any vault master key.
+//! The user picks a backup passphrase at export and types it at restore.
+//! Argon2id parameters are pinned to v1-of-this-format (m=64MiB, t=3, p=4)
+//! so a v1 reader does not need to negotiate them.
+
+use argon2::{Algorithm, Argon2, Params, Version};
+use base64::Engine;
+use chacha20poly1305::{
+    aead::{Aead, KeyInit},
+    XChaCha20Poly1305, XNonce,
+};
+use rand::{rngs::OsRng, RngCore};
+use serde::{Deserialize, Serialize};
+use zeroize::Zeroizing;
+
+use crate::error::{RelicarioError, Result};
+
+/// File-level magic. Four bytes so a `file(1)` rule can identify it.
+pub const MAGIC: [u8; 4] = *b"RBAK";
+
+/// Container format version. Bumped if the on-disk layout of the
+/// salt/nonce/ciphertext header or the AEAD primitive changes.
+pub const FORMAT_VERSION: u8 = 0x01;
+
+/// JSON envelope schema version. Bumped if the JSON shape changes
+/// without an underlying-format change (e.g. new optional fields whose
+/// absence v1 readers can tolerate would NOT bump this; renames or
+/// removals would).
+pub const SCHEMA_VERSION: u32 = 1;
+
+const SALT_LEN: usize = 32;
+const NONCE_LEN: usize = 24;
+const TAG_LEN: usize = 16;
+const HEADER_LEN: usize = 4 + 1 + SALT_LEN + NONCE_LEN; // magic + version + salt + nonce
+
+const ARGON2_M_KIB: u32 = 65_536;     // 64 MiB
+const ARGON2_T: u32 = 3;
+const ARGON2_P: u32 = 4;
+
+/// Zstd compression level. 3 is the speed/size sweet spot.
+const ZSTD_LEVEL: i32 = 3;
+
+/// Inputs to [`pack_backup`]. Borrow-only — the caller retains ownership of
+/// every byte slice.
+pub struct BackupInput<'a> {
+    /// Raw 32-byte vault salt (`.relicario/salt` contents).
+    pub salt: &'a [u8],
+    /// Verbatim string contents of `.relicario/params.json`.
+    pub params_json: &'a str,
+    /// Verbatim string contents of `.relicario/devices.json`.
+    pub devices_json: &'a str,
+    /// Encrypted manifest bytes (verbatim `manifest.enc`).
+    pub manifest_enc: &'a [u8],
+    /// Encrypted vault settings bytes (verbatim `settings.enc`).
+    pub settings_enc: &'a [u8],
+    /// One entry per item file (verbatim ciphertext).
+    pub items: Vec<BackupItem<'a>>,
+    /// One entry per attachment blob (verbatim ciphertext).
+    pub attachments: Vec<BackupAttachment<'a>>,
+    /// Reference JPEG bytes — included iff caller wants to bundle the
+    /// second factor.
+    pub reference_jpg: Option<&'a [u8]>,
+    /// Tarred `.git/` directory — included iff caller wants the audit log.
+    /// The caller (CLI) does the actual tarring; core just transports the
+    /// opaque bytes.
+    pub git_archive: Option<&'a [u8]>,
+}
+
+/// One vault item ciphertext, keyed by the item id (16-char hex).
+pub struct BackupItem<'a> {
+    pub id: String,
+    pub ciphertext: &'a [u8],
+}
+
+/// One attachment blob, keyed by `<item_id>/<attachment_id>` so the
+/// per-item directory layout round-trips.
+pub struct BackupAttachment<'a> {
+    pub item_id: String,
+    pub attachment_id: String,
+    pub ciphertext: &'a [u8],
+}
+
+/// Output of [`unpack_backup`]. Owned bytes — the caller decides where to
+/// persist them.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackupOutput {
+    pub salt: [u8; 32],
+    pub params_json: String,
+    pub devices_json: String,
+    pub manifest_enc: Vec<u8>,
+    pub settings_enc: Vec<u8>,
+    pub items: Vec<UnpackedItem>,
+    pub attachments: Vec<UnpackedAttachment>,
+    pub reference_jpg: Option<Vec<u8>>,
+    pub git_archive: Option<Vec<u8>>,
+    pub created_at: i64,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UnpackedItem {
+    pub id: String,
+    pub ciphertext: Vec<u8>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct UnpackedAttachment {
+    pub item_id: String,
+    pub attachment_id: String,
+    pub ciphertext: Vec<u8>,
+}
+
+#[derive(Serialize, Deserialize)]
+struct Envelope {
+    schema_version: u32,
+    created_at: i64,
+    vault: VaultEnvelope,
+}
+
+#[derive(Serialize, Deserialize)]
+struct VaultEnvelope {
+    /// base64-encoded 32-byte vault salt.
+    salt: String,
+    /// Verbatim params.json contents (string, not nested object — keeps
+    /// forward-compat with future params.json schema changes opaque to
+    /// the backup format).
+    params: String,
+    /// Verbatim devices.json contents (string for the same reason).
+    devices: String,
+    /// base64-encoded ciphertext of `manifest.enc`.
+    manifest: String,
+    /// base64-encoded ciphertext of `settings.enc`.
+    settings: String,
+    /// Map of `item_id` → base64-encoded item ciphertext.
+    items: std::collections::BTreeMap<String, String>,
+    /// Map of `<item_id>/<attachment_id>` → base64-encoded ciphertext.
+    attachments: std::collections::BTreeMap<String, String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    reference_jpg: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    git_archive: Option<String>,
+}
+
+/// Pack a vault into the `.relbak` container.
+///
+/// Generates fresh 32-byte salt + 24-byte nonce via OsRng. Derives a
+/// 32-byte key via Argon2id with the format-pinned parameters, then
+/// XChaCha20-Poly1305 encrypts the zstd-compressed JSON envelope.
+pub fn pack_backup(input: BackupInput<'_>, passphrase: &str) -> Result<Vec<u8>> {
+    let mut salt = [0u8; SALT_LEN];
+    OsRng.fill_bytes(&mut salt);
+    let mut nonce_bytes = [0u8; NONCE_LEN];
+    OsRng.fill_bytes(&mut nonce_bytes);
+
+    let key = derive_backup_key(passphrase.as_bytes(), &salt)?;
+
+    let envelope = build_envelope(input, crate::time::now_unix())?;
+    let json = serde_json::to_vec(&envelope)?;
+
+    let compressed = zstd::encode_all(&json[..], ZSTD_LEVEL)
+        .map_err(|e| RelicarioError::Format(format!("zstd compress: {e}")))?;
+
+    let cipher = XChaCha20Poly1305::new((&*key).into());
+    let nonce = XNonce::from(nonce_bytes);
+    let ciphertext = cipher
+        .encrypt(&nonce, compressed.as_slice())
+        .map_err(|e| RelicarioError::Encrypt(e.to_string()))?;
+
+    let mut out = Vec::with_capacity(HEADER_LEN + ciphertext.len());
+    out.extend_from_slice(&MAGIC);
+    out.push(FORMAT_VERSION);
+    out.extend_from_slice(&salt);
+    out.extend_from_slice(&nonce_bytes);
+    out.extend_from_slice(&ciphertext);
+    Ok(out)
+}
+
+/// Unpack a `.relbak` container, verifying magic + version, decrypting,
+/// decompressing, and parsing the JSON envelope.
+pub fn unpack_backup(data: &[u8], passphrase: &str) -> Result<BackupOutput> {
+    if data.len() < HEADER_LEN + TAG_LEN {
+        return Err(RelicarioError::Format(
+            "backup file truncated".into(),
+        ));
+    }
+    if data[0..4] != MAGIC {
+        return Err(RelicarioError::BackupBadMagic);
+    }
+    let version = data[4];
+    if version != FORMAT_VERSION {
+        return Err(RelicarioError::BackupUnsupportedVersion {
+            found: version,
+            expected: FORMAT_VERSION,
+        });
+    }
+
+    let mut salt = [0u8; SALT_LEN];
+    salt.copy_from_slice(&data[5..5 + SALT_LEN]);
+    let nonce_start = 5 + SALT_LEN;
+    let nonce_bytes: &[u8] = &data[nonce_start..nonce_start + NONCE_LEN];
+    let ciphertext = &data[HEADER_LEN..];
+
+    let key = derive_backup_key(passphrase.as_bytes(), &salt)?;
+
+    let cipher = XChaCha20Poly1305::new((&*key).into());
+    let nonce = XNonce::from_slice(nonce_bytes);
+    let compressed = cipher
+        .decrypt(nonce, ciphertext)
+        .map_err(|_| RelicarioError::Decrypt)?;
+
+    let json_bytes = zstd::decode_all(compressed.as_slice())
+        .map_err(|e| RelicarioError::Format(format!("zstd decompress: {e}")))?;
+
+    let env: Envelope = serde_json::from_slice(&json_bytes)?;
+    if env.schema_version != SCHEMA_VERSION {
+        return Err(RelicarioError::BackupSchemaMismatch {
+            found: env.schema_version,
+            expected: SCHEMA_VERSION,
+        });
+    }
+
+    let b64 = base64::engine::general_purpose::STANDARD;
+    let mut salt_out = [0u8; 32];
+    let salt_decoded = b64
+        .decode(&env.vault.salt)
+        .map_err(|e| RelicarioError::Format(format!("base64 salt: {e}")))?;
+    if salt_decoded.len() != 32 {
+        return Err(RelicarioError::Format(format!(
+            "salt length: expected 32, got {}",
+            salt_decoded.len()
+        )));
+    }
+    salt_out.copy_from_slice(&salt_decoded);
+
+    let manifest_enc = b64
+        .decode(&env.vault.manifest)
+        .map_err(|e| RelicarioError::Format(format!("base64 manifest: {e}")))?;
+    let settings_enc = b64
+        .decode(&env.vault.settings)
+        .map_err(|e| RelicarioError::Format(format!("base64 settings: {e}")))?;
+
+    let mut items = Vec::with_capacity(env.vault.items.len());
+    for (id, b64_ct) in env.vault.items {
+        let ct = b64
+            .decode(&b64_ct)
+            .map_err(|e| RelicarioError::Format(format!("base64 item {id}: {e}")))?;
+        items.push(UnpackedItem { id, ciphertext: ct });
+    }
+
+    let mut attachments = Vec::with_capacity(env.vault.attachments.len());
+    for (combined, b64_ct) in env.vault.attachments {
+        let (item_id, attachment_id) = combined
+            .split_once('/')
+            .map(|(a, b)| (a.to_string(), b.to_string()))
+            .ok_or_else(|| {
+                RelicarioError::Format(format!("bad attachment key '{combined}'"))
+            })?;
+        let ct = b64
+            .decode(&b64_ct)
+            .map_err(|e| RelicarioError::Format(format!("base64 attachment {combined}: {e}")))?;
+        attachments.push(UnpackedAttachment { item_id, attachment_id, ciphertext: ct });
+    }
+
+    let reference_jpg = env
+        .vault
+        .reference_jpg
+        .as_deref()
+        .map(|s| b64.decode(s))
+        .transpose()
+        .map_err(|e| RelicarioError::Format(format!("base64 reference_jpg: {e}")))?;
+    let git_archive = env
+        .vault
+        .git_archive
+        .as_deref()
+        .map(|s| b64.decode(s))
+        .transpose()
+        .map_err(|e| RelicarioError::Format(format!("base64 git_archive: {e}")))?;
+
+    Ok(BackupOutput {
+        salt: salt_out,
+        params_json: env.vault.params,
+        devices_json: env.vault.devices,
+        manifest_enc,
+        settings_enc,
+        items,
+        attachments,
+        reference_jpg,
+        git_archive,
+        created_at: env.created_at,
+    })
+}
+
+fn derive_backup_key(passphrase: &[u8], salt: &[u8]) -> Result<Zeroizing<[u8; 32]>> {
+    use unicode_normalization::UnicodeNormalization;
+
+    // NFC normalize passphrase (matches derive_master_key in crypto.rs)
+    let nfc_passphrase: Vec<u8> = match std::str::from_utf8(passphrase) {
+        Ok(s) => s.nfc().collect::<String>().into_bytes(),
+        Err(_) => passphrase.to_vec(),
+    };
+
+    let params = Params::new(ARGON2_M_KIB, ARGON2_T, ARGON2_P, Some(32))
+        .map_err(|e| RelicarioError::Kdf(format!("argon2 params: {e}")))?;
+    let argon = Argon2::new(Algorithm::Argon2id, Version::V0x13, params);
+    let mut key = Zeroizing::new([0u8; 32]);
+    argon
+        .hash_password_into(&nfc_passphrase, salt, key.as_mut_slice())
+        .map_err(|e| RelicarioError::Kdf(format!("argon2 hash: {e}")))?;
+    Ok(key)
+}
+
+fn build_envelope(input: BackupInput<'_>, created_at: i64) -> Result<Envelope> {
+    let b64 = base64::engine::general_purpose::STANDARD;
+    let mut items = std::collections::BTreeMap::new();
+    for it in input.items {
+        items.insert(it.id, b64.encode(it.ciphertext));
+    }
+    let mut attachments = std::collections::BTreeMap::new();
+    for a in input.attachments {
+        let key = format!("{}/{}", a.item_id, a.attachment_id);
+        attachments.insert(key, b64.encode(a.ciphertext));
+    }
+    Ok(Envelope {
+        schema_version: SCHEMA_VERSION,
+        created_at,
+        vault: VaultEnvelope {
+            salt: b64.encode(input.salt),
+            params: input.params_json.to_string(),
+            devices: input.devices_json.to_string(),
+            manifest: b64.encode(input.manifest_enc),
+            settings: b64.encode(input.settings_enc),
+            items,
+            attachments,
+            reference_jpg: input.reference_jpg.map(|b| b64.encode(b)),
+            git_archive: input.git_archive.map(|b| b64.encode(b)),
+        },
+    })
+}

crates/relicario-core/src/crypto.rs

@@ -243,6 +243,23 @@ pub fn derive_master_key(
     Ok(output)
 }
 
+/// Like `derive_master_key` but takes an already-assembled `input` byte slice directly,
+/// allowing callers to apply their own domain separation before KDF.
+pub fn derive_master_key_raw(
+    input: &[u8],
+    salt: &[u8; 32],
+    params: &KdfParams,
+) -> Result<Zeroizing<[u8; 32]>> {
+    let argon2_params = Params::new(params.argon2_m, params.argon2_t, params.argon2_p, Some(32))
+        .map_err(|e| RelicarioError::Kdf(e.to_string()))?;
+    let argon2 = Argon2::new(Algorithm::Argon2id, Version::V0x13, argon2_params);
+    let mut output = Zeroizing::new([0u8; 32]);
+    argon2
+        .hash_password_into(input, salt, output.as_mut())
+        .map_err(|e| RelicarioError::Kdf(e.to_string()))?;
+    Ok(output)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -408,7 +425,7 @@ mod tests {
         blob.extend_from_slice(&[0u8; 16]);
 
         let key = Zeroizing::new([0u8; 32]);
-        let err = decrypt(&*key, &blob).expect_err("v1 blob should fail decrypt");
+        let err = decrypt(&key, &blob).expect_err("v1 blob should fail decrypt");
         match err {
             RelicarioError::UnsupportedFormatVersion { found, expected } => {
                 assert_eq!(found, 0x01);

crates/relicario-core/src/device.rs

@@ -0,0 +1,168 @@
+//! Device identity: ed25519 keypairs in OpenSSH format, signing and verification.
+
+use ed25519_dalek::{Signature, Signer, SigningKey, Verifier, VerifyingKey};
+use serde::{Deserialize, Serialize};
+use ssh_key::{LineEnding, PrivateKey, PublicKey};
+use zeroize::Zeroizing;
+
+use crate::error::{RelicarioError, Result};
+
+/// A registered device entry in devices.json.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DeviceEntry {
+    pub name: String,
+    /// OpenSSH public key format: "ssh-ed25519 AAAA..."
+    pub public_key: String,
+    pub added_at: i64,
+    pub added_by: String,
+}
+
+/// A revoked device entry in revoked.json.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct RevokedEntry {
+    pub name: String,
+    pub public_key: String,
+    pub revoked_at: i64,
+    pub revoked_by: String,
+}
+
+/// Generate a new ed25519 keypair, returning (private_openssh, public_openssh).
+pub fn generate_keypair() -> Result<(Zeroizing<String>, String)> {
+    use ssh_key::private::{Ed25519Keypair, Ed25519PrivateKey, KeypairData};
+    use ssh_key::public::Ed25519PublicKey;
+
+    let signing_key = SigningKey::generate(&mut rand::rngs::OsRng);
+    let verifying_key = signing_key.verifying_key();
+
+    // Build ssh-key types from raw bytes
+    let ed_private = Ed25519PrivateKey::from_bytes(signing_key.as_bytes());
+    let ed_public = Ed25519PublicKey(*verifying_key.as_bytes());
+    let keypair = Ed25519Keypair { public: ed_public, private: ed_private };
+    let keypair_data = KeypairData::Ed25519(keypair);
+
+    let ssh_private = PrivateKey::new(keypair_data, "")
+        .map_err(|e| RelicarioError::DeviceKey(format!("private key create: {e}")))?;
+    let ssh_public = ssh_private.public_key();
+
+    let private_pem = ssh_private
+        .to_openssh(LineEnding::LF)
+        .map_err(|e| RelicarioError::DeviceKey(format!("private key encode: {e}")))?;
+    let public_line = ssh_public
+        .to_openssh()
+        .map_err(|e| RelicarioError::DeviceKey(format!("public key encode: {e}")))?;
+
+    Ok((Zeroizing::new(private_pem.to_string()), public_line))
+}
+
+/// Sign data with an OpenSSH private key, returning base64 signature.
+pub fn sign(private_key_openssh: &str, data: &[u8]) -> Result<String> {
+    use base64::Engine;
+
+    let private = PrivateKey::from_openssh(private_key_openssh)
+        .map_err(|e| RelicarioError::DeviceKey(format!("parse private key: {e}")))?;
+
+    let key_data = private
+        .key_data()
+        .ed25519()
+        .ok_or_else(|| RelicarioError::DeviceKey("not an ed25519 key".into()))?;
+
+    let secret_slice: &[u8] = key_data.private.as_ref();
+    let secret_bytes: [u8; 32] = secret_slice
+        .try_into()
+        .map_err(|_| RelicarioError::DeviceKey("invalid key length".into()))?;
+
+    let signing_key = SigningKey::from_bytes(&secret_bytes);
+    let signature = signing_key.sign(data);
+    Ok(base64::engine::general_purpose::STANDARD.encode(signature.to_bytes()))
+}
+
+/// Verify a signature against an OpenSSH public key.
+pub fn verify(public_key_openssh: &str, data: &[u8], signature_b64: &str) -> Result<bool> {
+    use base64::Engine;
+
+    let public = PublicKey::from_openssh(public_key_openssh)
+        .map_err(|e| RelicarioError::DeviceKey(format!("parse public key: {e}")))?;
+
+    let key_data = public
+        .key_data()
+        .ed25519()
+        .ok_or_else(|| RelicarioError::DeviceKey("not an ed25519 key".into()))?;
+
+    let pub_slice: &[u8] = key_data.as_ref();
+    let pub_bytes: [u8; 32] = pub_slice
+        .try_into()
+        .map_err(|_| RelicarioError::DeviceKey("invalid key length".into()))?;
+
+    let verifying_key = VerifyingKey::from_bytes(&pub_bytes)
+        .map_err(|e| RelicarioError::DeviceKey(format!("invalid public key: {e}")))?;
+
+    let sig_bytes = base64::engine::general_purpose::STANDARD
+        .decode(signature_b64)
+        .map_err(|e| RelicarioError::DeviceKey(format!("decode signature: {e}")))?;
+
+    let signature = Signature::from_slice(&sig_bytes)
+        .map_err(|e| RelicarioError::DeviceKey(format!("parse signature: {e}")))?;
+
+    Ok(verifying_key.verify(data, &signature).is_ok())
+}
+
+/// Compute the OpenSSH SHA-256 fingerprint of a public key.
+/// Output format matches `ssh-keygen -lf` and `git verify-commit --raw`:
+/// `SHA256:<43-char base64 without padding>`.
+pub fn fingerprint(public_key_openssh: &str) -> Result<String> {
+    use ssh_key::HashAlg;
+    let public = PublicKey::from_openssh(public_key_openssh)
+        .map_err(|e| RelicarioError::DeviceKey(format!("parse public key: {e}")))?;
+    Ok(public.fingerprint(HashAlg::Sha256).to_string())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn generate_and_sign_verify_roundtrip() {
+        let (private, public) = generate_keypair().unwrap();
+        let data = b"hello world";
+        let sig = sign(&private, data).unwrap();
+        assert!(verify(&public, data, &sig).unwrap());
+    }
+
+    #[test]
+    fn verify_rejects_wrong_data() {
+        let (private, public) = generate_keypair().unwrap();
+        let sig = sign(&private, b"hello").unwrap();
+        assert!(!verify(&public, b"world", &sig).unwrap());
+    }
+
+    #[test]
+    fn verify_rejects_wrong_key() {
+        let (private, _) = generate_keypair().unwrap();
+        let (_, other_public) = generate_keypair().unwrap();
+        let sig = sign(&private, b"hello").unwrap();
+        assert!(!verify(&other_public, b"hello", &sig).unwrap());
+    }
+
+    #[test]
+    fn fingerprint_matches_ssh_keygen_format() {
+        let (_, public) = generate_keypair().unwrap();
+        let fp = fingerprint(&public).unwrap();
+        assert!(fp.starts_with("SHA256:"), "fingerprint should start with SHA256: prefix, got {fp}");
+        let body = fp.strip_prefix("SHA256:").unwrap();
+        assert_eq!(body.len(), 43, "SHA-256 fingerprint body is 43 base64 chars (no padding)");
+        assert!(body.chars().all(|c| c.is_ascii_alphanumeric() || c == '+' || c == '/'));
+    }
+
+    #[test]
+    fn fingerprint_is_deterministic() {
+        let (_, public) = generate_keypair().unwrap();
+        assert_eq!(fingerprint(&public).unwrap(), fingerprint(&public).unwrap());
+    }
+
+    #[test]
+    fn fingerprint_differs_per_key() {
+        let (_, p1) = generate_keypair().unwrap();
+        let (_, p2) = generate_keypair().unwrap();
+        assert_ne!(fingerprint(&p1).unwrap(), fingerprint(&p2).unwrap());
+    }
+}

crates/relicario-core/src/error.rs

@@ -1,4 +1,4 @@
-//! Unified error type for the relicario-core crate.
+//! Unified error type for the Relicario core crate.
 //!
 //! Every fallible function in this crate returns [`Result<T>`], which is an alias
 //! for `std::result::Result<T, RelicarioError>`. Using a single error enum keeps the
@@ -7,7 +7,7 @@
 
 use thiserror::Error;
 
-/// All errors that can originate from relicario-core operations.
+/// All errors that can originate from Relicario core operations.
 ///
 /// Variants are ordered roughly by the pipeline stage where they occur:
 /// KDF -> encryption -> decryption -> format parsing -> item lookup -> image
@@ -39,6 +39,33 @@ pub enum RelicarioError {
     #[error("unsupported vault format version: found 0x{found:02x}, expected 0x{expected:02x}")]
     UnsupportedFormatVersion { found: u8, expected: u8 },
 
+    /// Backup file's first 4 bytes don't match the "RBAK" magic.
+    #[error("not a Relicario backup file")]
+    BackupBadMagic,
+
+    /// Backup format version is newer than this binary supports.
+    #[error("backup created by a newer Relicario; upgrade required")]
+    BackupUnsupportedVersion { found: u8, expected: u8 },
+
+    /// Backup envelope schema version doesn't match.
+    #[error("backup envelope schema v{found}; this Relicario reads v{expected}")]
+    BackupSchemaMismatch { found: u32, expected: u32 },
+
+    /// An error during backup restore (e.g., tar safety validation failure).
+    #[error("backup restore: {0}")]
+    BackupRestore(String),
+
+    /// CSV header doesn't match the LastPass column layout.
+    #[error("unrecognized CSV header — expected LastPass export format ({0})")]
+    ImportCsvHeader(String),
+
+    /// CSV body could not be parsed (mismatched quoting, encoding, etc.).
+    /// Per-row record errors that the importer recovers from become
+    /// `ImportWarning` entries — this variant is reserved for failures
+    /// that abort the whole import.
+    #[error("CSV parse failed: {0}")]
+    ImportCsvFormat(String),
+
     /// An item was looked up by ID but does not exist in the manifest.
     #[error("item not found: {0}")]
     ItemNotFound(String),
@@ -86,6 +113,16 @@ pub enum RelicarioError {
     /// rotating the passphrase or reference image.
     #[error("device key error: {0}")]
     DeviceKey(String),
+
+    /// HOTP requires incrementing and persisting the counter after each use.
+    /// Without vault-save machinery in compute_totp_code, HOTP would desync
+    /// immediately. Use TOTP instead.
+    #[error("HOTP is not supported: counter persistence requires vault save after each use")]
+    HotpNotSupported,
+
+    /// Recovery QR generation or parsing failed.
+    #[error("recovery QR: {0}")]
+    RecoveryQr(String),
 }
 
 /// Crate-wide result alias, reducing boilerplate in function signatures.
@@ -130,4 +167,29 @@ mod tests {
         assert!(s.contains("01") || s.contains("1"));
         assert!(s.contains("02") || s.contains("2"));
     }
+
+    #[test]
+    fn backup_errors_carry_useful_messages() {
+        let bad = RelicarioError::BackupBadMagic;
+        assert!(format!("{}", bad).contains("not a Relicario backup file"));
+
+        let ver = RelicarioError::BackupUnsupportedVersion { found: 0x02, expected: 0x01 };
+        let s = format!("{}", ver);
+        assert!(s.contains("newer"));
+
+        let schema = RelicarioError::BackupSchemaMismatch { found: 2, expected: 1 };
+        let s = format!("{}", schema);
+        assert!(s.contains("v2") && s.contains("v1"));
+    }
+
+    #[test]
+    fn import_errors_carry_useful_messages() {
+        let h = RelicarioError::ImportCsvHeader("missing 'name' column".into());
+        assert!(format!("{}", h).contains("LastPass"));
+        assert!(format!("{}", h).contains("missing 'name'"));
+
+        let f = RelicarioError::ImportCsvFormat("unterminated quote at line 12".into());
+        assert!(format!("{}", f).contains("CSV parse failed"));
+        assert!(format!("{}", f).contains("unterminated quote"));
+    }
 }

crates/relicario-core/src/ids.rs

@@ -2,8 +2,9 @@
 //!
 //! - `ItemId` and `FieldId` are random 16-char hex strings (64 bits of entropy)
 //!   generated via `OsRng` (audit M8: bumped from the v1 8-char/32-bit format).
-//! - `AttachmentId` is the first 16 hex chars of `sha256(plaintext)` —
+//! - `AttachmentId` is the first 32 hex chars of `sha256(plaintext)` (128 bits) —
 //!   content-addressed so identical plaintext blobs deduplicate naturally in git.
+//!   (audit I2/B4: bumped from 8-byte/64-bit format to prevent birthday collisions)
 
 use rand::rngs::OsRng;
 use rand::RngCore;
@@ -29,6 +30,12 @@ impl ItemId {
         Self(hex::encode(bytes))
     }
     pub fn as_str(&self) -> &str { &self.0 }
+
+    /// Returns true if this ID is valid for filesystem paths.
+    /// Valid ItemIds are 16 lowercase hex chars.
+    pub fn is_valid(&self) -> bool {
+        self.0.len() == 16 && self.0.chars().all(|c| c.is_ascii_hexdigit())
+    }
 }
 
 impl Default for ItemId {
@@ -51,9 +58,15 @@ impl Default for FieldId {
 impl AttachmentId {
     pub fn from_plaintext(plaintext: &[u8]) -> Self {
         let digest = Sha256::digest(plaintext);
-        Self(hex::encode(&digest[..8]))
+        Self(hex::encode(&digest[..16])) // 16 bytes = 128 bits
     }
     pub fn as_str(&self) -> &str { &self.0 }
+
+    /// Returns true if this ID is valid for filesystem paths.
+    /// Valid AttachmentIds are 32 lowercase hex chars.
+    pub fn is_valid(&self) -> bool {
+        self.0.len() == 32 && self.0.chars().all(|c| c.is_ascii_hexdigit())
+    }
 }
 
 #[cfg(test)]
@@ -106,12 +119,36 @@ mod tests {
     }
 
     #[test]
-    fn attachment_id_is_16_hex_chars() {
+    fn attachment_id_is_32_hex_chars() {
         let id = AttachmentId::from_plaintext(b"any bytes");
-        assert_eq!(id.0.len(), 16);
+        assert_eq!(id.0.len(), 32); // 16 bytes = 32 hex chars = 128 bits
         assert!(id.0.chars().all(|c| c.is_ascii_hexdigit()));
     }
 
+    #[test]
+    fn item_id_is_valid_for_normal_ids() {
+        let id = ItemId::new();
+        assert!(id.is_valid());
+    }
+
+    #[test]
+    fn item_id_is_invalid_for_traversal() {
+        let bad = ItemId("../../../etc".to_string());
+        assert!(!bad.is_valid());
+    }
+
+    #[test]
+    fn attachment_id_is_valid_for_normal_ids() {
+        let id = AttachmentId::from_plaintext(b"test");
+        assert!(id.is_valid());
+    }
+
+    #[test]
+    fn attachment_id_is_invalid_for_traversal() {
+        let bad = AttachmentId("../../passwd".to_string());
+        assert!(!bad.is_valid());
+    }
+
     #[test]
     fn ids_serialize_as_bare_strings() {
         let item = ItemId("abcdef0123456789".to_string());

crates/relicario-core/src/imgsecret.rs

@@ -83,7 +83,7 @@ const BITS_PER_BLOCK: usize = 12; // EMBED_POSITIONS.len()
 
 /// Number of 8x8 blocks needed to hold one complete copy of the 256-bit secret.
 /// ceil(256 / 12) = 22 blocks per copy.
-const BLOCKS_PER_COPY: usize = (SECRET_BITS + BITS_PER_BLOCK - 1) / BITS_PER_BLOCK; // 22
+const BLOCKS_PER_COPY: usize = SECRET_BITS.div_ceil(BITS_PER_BLOCK); // 22
 
 /// Mid-frequency DCT coefficient positions for embedding, specified as
 /// (row, col) indices into the 8x8 DCT coefficient matrix.
@@ -302,9 +302,9 @@ fn read_block_abs(y: &YChannel, px: usize, py: usize) -> Option<[[f64; 8]; 8]> {
         return None;
     }
     let mut block = [[0.0f64; 8]; 8];
-    for row in 0..8 {
-        for col in 0..8 {
-            block[row][col] = y.get(px + col, py + row);
+    for (row, block_row) in block.iter_mut().enumerate() {
+        for (col, cell) in block_row.iter_mut().enumerate() {
+            *cell = y.get(px + col, py + row);
         }
     }
     Some(block)
@@ -323,9 +323,9 @@ fn read_block(y: &YChannel, bx: usize, by: usize, region: &EmbedRegion) -> [[f64
 fn write_block(y: &mut YChannel, bx: usize, by: usize, region: &EmbedRegion, block: &[[f64; 8]; 8]) {
     let start_x = region.x_offset + bx * BLOCK_SIZE;
     let start_y = region.y_offset + by * BLOCK_SIZE;
-    for row in 0..8 {
-        for col in 0..8 {
-            y.set(start_x + col, start_y + row, block[row][col]);
+    for (row, block_row) in block.iter().enumerate() {
+        for (col, &cell) in block_row.iter().enumerate() {
+            y.set(start_x + col, start_y + row, cell);
         }
     }
 }
@@ -349,17 +349,17 @@ fn write_block(y: &mut YChannel, bx: usize, by: usize, region: &EmbedRegion, blo
 /// where c(0) = sqrt(1/8) and c(k) = sqrt(2/8) for k > 0.
 fn dct1d(input: &[f64; 8]) -> [f64; 8] {
     let mut output = [0.0f64; 8];
-    for k in 0..8 {
+    for (k, out_k) in output.iter_mut().enumerate() {
         let ck = if k == 0 {
             (1.0 / 8.0_f64).sqrt()
         } else {
             (2.0 / 8.0_f64).sqrt()
         };
         let mut sum = 0.0;
-        for i in 0..8 {
-            sum += input[i] * ((2 * i + 1) as f64 * k as f64 * PI / 16.0).cos();
+        for (i, &x) in input.iter().enumerate() {
+            sum += x * ((2 * i + 1) as f64 * k as f64 * PI / 16.0).cos();
         }
-        output[k] = ck * sum;
+        *out_k = ck * sum;
     }
     output
 }
@@ -370,17 +370,17 @@ fn dct1d(input: &[f64; 8]) -> [f64; 8] {
 ///   x[i] = sum_{k=0}^{7} c(k) * X[k] * cos((2i+1)*k*pi/16)
 fn idct1d(input: &[f64; 8]) -> [f64; 8] {
     let mut output = [0.0f64; 8];
-    for i in 0..8 {
+    for (i, out_i) in output.iter_mut().enumerate() {
         let mut sum = 0.0;
-        for k in 0..8 {
+        for (k, &x) in input.iter().enumerate() {
             let ck = if k == 0 {
                 (1.0 / 8.0_f64).sqrt()
             } else {
                 (2.0 / 8.0_f64).sqrt()
             };
-            sum += ck * input[k] * ((2 * i + 1) as f64 * k as f64 * PI / 16.0).cos();
+            sum += ck * x * ((2 * i + 1) as f64 * k as f64 * PI / 16.0).cos();
         }
-        output[i] = sum;
+        *out_i = sum;
     }
     output
 }
@@ -501,7 +501,7 @@ fn bytes_to_bits(bytes: &[u8]) -> Vec<u8> {
 ///
 /// Pads the last byte with zeros if the bit count is not a multiple of 8.
 fn bits_to_bytes(bits: &[u8]) -> Vec<u8> {
-    let mut bytes = Vec::with_capacity((bits.len() + 7) / 8);
+    let mut bytes = Vec::with_capacity(bits.len().div_ceil(8));
     for chunk in bits.chunks(8) {
         let mut byte = 0u8;
         for (i, &bit) in chunk.iter().enumerate() {

crates/relicario-core/src/import_lastpass.rs

@@ -0,0 +1,220 @@
+//! LastPass CSV importer.
+//!
+//! Pure: takes CSV bytes, returns a vector of `Item` (with freshly-minted
+//! IDs and timestamps) plus a vector of `ImportWarning` for skipped or
+//! partially-imported rows. Failed rows never abort the whole import;
+//! the only fatal error is a missing or malformed header.
+//!
+//! Spec: docs/superpowers/specs/2026-04-27-relicario-import-export-design.md
+//! (D10–D13 + the LastPass field-mapping table).
+
+use serde::{Deserialize, Serialize};
+use url::Url;
+use zeroize::Zeroizing;
+
+use crate::error::{RelicarioError, Result};
+use crate::item::Item;
+use crate::item_types::{ItemCore, LoginCore, SecureNoteCore};
+
+/// LastPass column order. The header row must contain these exact column
+/// names in this exact order.
+pub const EXPECTED_HEADER: &[&str] =
+    &["url", "username", "password", "totp", "extra", "name", "grouping", "fav"];
+
+/// A row that was skipped, or partially imported with a downgrade
+/// (e.g., login imported without TOTP).
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ImportWarning {
+    /// 1-indexed row number in the CSV body (the header is row 0).
+    pub row: usize,
+    /// Title from the row's `name` column, if present and non-empty.
+    pub title: Option<String>,
+    /// Human-readable explanation, suitable for stderr / inline UI.
+    pub message: String,
+}
+
+/// Parse a LastPass CSV export.
+///
+/// Returns the parsed items (with fresh IDs and timestamps) and any
+/// per-row warnings. The function only fails if the header is missing
+/// or doesn't match `EXPECTED_HEADER`.
+pub fn parse_lastpass_csv(csv_bytes: &[u8]) -> Result<(Vec<Item>, Vec<ImportWarning>)> {
+    let mut reader = csv::ReaderBuilder::new()
+        .has_headers(true)
+        .flexible(false)
+        .from_reader(csv_bytes);
+
+    // Validate header.
+    let headers = reader
+        .headers()
+        .map_err(|e| RelicarioError::ImportCsvFormat(format!("read header: {e}")))?
+        .clone();
+    if headers.len() != EXPECTED_HEADER.len()
+        || headers.iter().zip(EXPECTED_HEADER).any(|(got, want)| got != *want)
+    {
+        return Err(RelicarioError::ImportCsvHeader(format!(
+            "expected `{}`, got `{}`",
+            EXPECTED_HEADER.join(","),
+            headers.iter().collect::<Vec<_>>().join(",")
+        )));
+    }
+
+    let mut items = Vec::new();
+    let mut warnings = Vec::new();
+
+    for (idx, record) in reader.records().enumerate() {
+        let row_num = idx + 1;
+        let record = match record {
+            Ok(r) => r,
+            Err(e) => {
+                warnings.push(ImportWarning {
+                    row: row_num,
+                    title: None,
+                    message: format!("CSV parse error — skipped: {e}"),
+                });
+                continue;
+            }
+        };
+
+        let (item, warn) = map_row(&record, row_num);
+        if let Some(it) = item { items.push(it); }
+        if let Some(w)  = warn  { warnings.push(w); }
+    }
+
+    Ok((items, warnings))
+}
+
+/// Map a single CSV record. Returns:
+/// - `(Some(item), None)` for a fully-imported row.
+/// - `(Some(item), Some(warn))` for a partially-imported row (e.g.,
+///   bad TOTP base32 — login imported without TOTP).
+/// - `(None, Some(warn))` for a skipped row (missing required field).
+fn map_row(
+    record: &csv::StringRecord,
+    row: usize,
+) -> (Option<Item>, Option<ImportWarning>) {
+    let url      = record.get(0).unwrap_or("").trim();
+    let username = record.get(1).unwrap_or("").trim();
+    // password and extra are deliberately NOT trimmed: leading/trailing
+    // whitespace is significant inside passwords and free-form notes.
+    let password = record.get(2).unwrap_or("");
+    let totp_raw = record.get(3).unwrap_or("").trim();
+    let extra    = record.get(4).unwrap_or("");
+    let name     = record.get(5).unwrap_or("").trim();
+    let group    = record.get(6).unwrap_or("").trim();
+    let fav      = record.get(7).unwrap_or("").trim();
+
+    if name.is_empty() {
+        return (None, Some(ImportWarning {
+            row,
+            title: None,
+            message: "missing `name` — skipped".into(),
+        }));
+    }
+
+    // SecureNote marker: LastPass exports notes with `url` set to "http://sn".
+    // The `extra` column carries the body verbatim.
+    if url == "http://sn" {
+        let mut item = Item::new(
+            name.to_string(),
+            ItemCore::SecureNote(SecureNoteCore {
+                body: Zeroizing::new(extra.to_string()),
+            }),
+        );
+        item.group    = if group.is_empty() { None } else { Some(group.to_string()) };
+        item.favorite = fav == "1";
+        return (Some(item), None);
+    }
+
+    if password.is_empty() {
+        return (None, Some(ImportWarning {
+            row,
+            title: Some(name.to_string()),
+            message: "missing `password` — skipped".into(),
+        }));
+    }
+
+    let mut warning: Option<ImportWarning> = None;
+
+    let parsed_url = if url.is_empty() {
+        None
+    } else {
+        match Url::parse(url) {
+            Ok(u) => Some(u),
+            Err(_) => {
+                // Login still imports — URL becomes None, with a warning.
+                if warning.is_none() {
+                    warning = Some(ImportWarning {
+                        row,
+                        title: Some(name.to_string()),
+                        message: format!("invalid URL `{url}` — login imported without URL"),
+                    });
+                }
+                None
+            }
+        }
+    };
+
+    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 {
+                secret: Zeroizing::new(bytes),
+                algorithm: crate::item_types::TotpAlgorithm::Sha1,
+                digits: 6,
+                period_seconds: 30,
+                kind: crate::item_types::TotpKind::Totp,
+            }),
+            _ => {
+                if warning.is_none() {
+                    warning = Some(ImportWarning {
+                        row,
+                        title: Some(name.to_string()),
+                        message: "invalid base32 TOTP secret — login imported without TOTP"
+                            .into(),
+                    });
+                }
+                None
+            }
+        }
+    };
+
+    let mut item = Item::new(
+        name.to_string(),
+        ItemCore::Login(LoginCore {
+            username: if username.is_empty() { None } else { Some(username.to_string()) },
+            password: Some(Zeroizing::new(password.to_string())),
+            url: parsed_url,
+            totp,
+        }),
+    );
+    item.group    = if group.is_empty() { None } else { Some(group.to_string()) };
+    item.favorite = fav == "1";
+    item.notes    = if extra.is_empty() { None } else { Some(extra.to_string()) };
+
+    (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_types/totp.rs

@@ -8,6 +8,10 @@ use zeroize::Zeroizing;
 
 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).
+const STEAM_ALPHABET: &[u8] = b"23456789BCDFGHJKMNPQRTVWXY";
+
 #[derive(Debug, Clone, Serialize, Deserialize, Default)]
 pub struct TotpCore {
     pub config: TotpConfig,
@@ -48,26 +52,23 @@ pub enum TotpAlgorithm {
     Sha512,
 }
 
-#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
 #[serde(rename_all = "snake_case")]
 pub enum TotpKind {
+    #[default]
     Totp,
     Hotp { counter: u64 },
     Steam,
 }
 
-impl Default for TotpKind {
-    fn default() -> Self { TotpKind::Totp }
-}
-
-/// Compute a TOTP/HOTP/Steam code for `config` at the given Unix timestamp.
+/// Compute a TOTP/Steam code for `config` at the given Unix timestamp.
 ///
 /// For TOTP and Steam: counter = `now_unix_seconds / period_seconds`.
-/// For HOTP: uses the `counter` carried in the variant.
+/// HOTP is not supported — returns [`RelicarioError::HotpNotSupported`].
 pub fn compute_totp_code(config: &TotpConfig, now_unix_seconds: u64) -> Result<String> {
     let counter = match config.kind {
         TotpKind::Totp => now_unix_seconds / config.period_seconds as u64,
-        TotpKind::Hotp { counter } => counter,
+        TotpKind::Hotp { .. } => return Err(RelicarioError::HotpNotSupported),
         TotpKind::Steam => now_unix_seconds / config.period_seconds as u64,
     };
     let counter_bytes = counter.to_be_bytes();
@@ -96,6 +97,16 @@ pub fn compute_totp_code(config: &TotpConfig, now_unix_seconds: u64) -> Result<S
                   | ((hmac_out[offset + 1] as u32)        << 16)
                   | ((hmac_out[offset + 2] as u32)        << 8)
                   |  (hmac_out[offset + 3] as u32);
+    if matches!(config.kind, TotpKind::Steam) {
+        let mut t = truncated;
+        let mut out = String::with_capacity(5);
+        for _ in 0..5 {
+            out.push(STEAM_ALPHABET[(t % 26) as usize] as char);
+            t /= 26;
+        }
+        return Ok(out);
+    }
+
     let modulus = 10u32.pow(config.digits as u32);
     Ok(format!("{:0width$}", truncated % modulus, width = config.digits as usize))
 }
@@ -151,7 +162,7 @@ mod tests {
     }
 
     #[test]
-    fn hotp_carries_counter() {
+    fn hotp_kind_roundtrips_through_json() {
         let cfg = TotpConfig { kind: TotpKind::Hotp { counter: 42 }, ..TotpConfig::default() };
         let json = serde_json::to_string(&cfg).unwrap();
         let parsed: TotpConfig = serde_json::from_str(&json).unwrap();
@@ -159,6 +170,18 @@ mod tests {
             TotpKind::Hotp { counter } => assert_eq!(counter, 42),
             other => panic!("expected Hotp, got {:?}", other),
         }
+        // Note: compute_totp_code will reject this — HOTP not supported
+    }
+
+    #[test]
+    fn hotp_returns_not_supported_error() {
+        let cfg = TotpConfig {
+            secret: Zeroizing::new(b"12345678901234567890".to_vec()),
+            kind: TotpKind::Hotp { counter: 0 },
+            ..TotpConfig::default()
+        };
+        let result = compute_totp_code(&cfg, 0);
+        assert!(matches!(result, Err(RelicarioError::HotpNotSupported)));
     }
 
     #[test]
@@ -168,3 +191,103 @@ mod tests {
         assert!(json.contains("steam"));
     }
 }
+
+#[cfg(test)]
+mod steam_tests {
+    use super::*;
+
+    /// Reference implementation of the Steam 5-character output, per the
+    /// Steam Mobile Authenticator (and WinAuth's Steam-Guard adapter).
+    /// Used by tests below to cross-check the production impl without
+    /// requiring a third-party vector. The algorithm is short enough to
+    /// be reproduced here in isolation.
+    fn steam_output_reference(truncated: u32) -> String {
+        const ALPHA: &[u8] = b"23456789BCDFGHJKMNPQRTVWXY";
+        let mut t = truncated;
+        let mut out = String::with_capacity(5);
+        for _ in 0..5 {
+            out.push(ALPHA[(t % 26) as usize] as char);
+            t /= 26;
+        }
+        out
+    }
+
+    /// Compute the dynamic-truncated u32 the same way `compute_totp_code`
+    /// does internally — used to drive the reference impl.
+    fn truncated_for(secret: &[u8], counter: u64) -> u32 {
+        use hmac::{Hmac, Mac};
+        use sha1::Sha1;
+        let mut mac = Hmac::<Sha1>::new_from_slice(secret).unwrap();
+        mac.update(&counter.to_be_bytes());
+        let bytes = mac.finalize().into_bytes();
+        let offset = (bytes[bytes.len() - 1] & 0x0F) as usize;
+        ((bytes[offset]     as u32 & 0x7F) << 24)
+        | ((bytes[offset + 1] as u32)        << 16)
+        | ((bytes[offset + 2] as u32)        << 8)
+        |  (bytes[offset + 3] as u32)
+    }
+
+    #[test]
+    fn steam_output_matches_reference_impl() {
+        let secret = b"12345678901234567890".to_vec();
+        let cfg = TotpConfig {
+            secret: Zeroizing::new(secret.clone()),
+            algorithm: TotpAlgorithm::Sha1,
+            digits: 5,
+            period_seconds: 30,
+            kind: TotpKind::Steam,
+        };
+        let code_at_30  = compute_totp_code(&cfg, 30).unwrap();
+        let code_at_60  = compute_totp_code(&cfg, 60).unwrap();
+        let code_at_120 = compute_totp_code(&cfg, 120).unwrap();
+        assert_eq!(code_at_30,  steam_output_reference(truncated_for(&secret, 1)));
+        assert_eq!(code_at_60,  steam_output_reference(truncated_for(&secret, 2)));
+        assert_eq!(code_at_120, steam_output_reference(truncated_for(&secret, 4)));
+    }
+
+    #[test]
+    fn steam_output_is_exactly_5_chars_regardless_of_digits() {
+        let secret = b"hello world!".to_vec();
+        for digits in [4u8, 5, 6, 7, 8] {
+            let cfg = TotpConfig {
+                secret: Zeroizing::new(secret.clone()),
+                algorithm: TotpAlgorithm::Sha1,
+                digits,
+                period_seconds: 30,
+                kind: TotpKind::Steam,
+            };
+            let code = compute_totp_code(&cfg, 0).unwrap();
+            assert_eq!(code.len(), 5, "Steam output must be 5 chars (digits={})", digits);
+        }
+    }
+
+    #[test]
+    fn steam_output_uses_only_alphabet_chars() {
+        const ALPHA: &str = "23456789BCDFGHJKMNPQRTVWXY";
+        let secret = b"hello world!".to_vec();
+        let cfg = TotpConfig {
+            secret: Zeroizing::new(secret),
+            algorithm: TotpAlgorithm::Sha1,
+            digits: 5,
+            period_seconds: 30,
+            kind: TotpKind::Steam,
+        };
+        for t in 0u64..1000 {
+            let code = compute_totp_code(&cfg, t * 30).unwrap();
+            for ch in code.chars() {
+                assert!(ALPHA.contains(ch), "char {ch:?} not in Steam alphabet (t={t})");
+            }
+        }
+    }
+
+    #[test]
+    fn steam_alphabet_excludes_ambiguous_glyphs() {
+        // Authoritative Steam Guard alphabet from Valve's Steam Mobile
+        // Authenticator: 26 chars, excludes 0/O, 1/I/L, S, A, E, U, Z.
+        // (Note: '5' IS in the alphabet — S is excluded, so 5 is unambiguous.)
+        const ALPHA: &str = "23456789BCDFGHJKMNPQRTVWXY";
+        for ch in ['0', 'O', '1', 'I', 'L', 'S', 'A', 'Z'] {
+            assert!(!ALPHA.contains(ch), "ambiguous glyph {ch:?} must not be in alphabet");
+        }
+    }
+}

crates/relicario-core/src/lib.rs

@@ -1,6 +1,6 @@
 //! # relicario-core
 //!
-//! Platform-agnostic core library for the relicario password manager.
+//! Platform-agnostic core library for the Relicario password manager.
 //!
 //! This crate is intentionally **bytes-in/bytes-out** -- it performs no filesystem
 //! access, no network I/O, and no git operations. All inputs arrive as byte slices
@@ -77,3 +77,23 @@ pub use vault::{
 };
 
 pub mod imgsecret;
+
+pub mod backup;
+pub use backup::{pack_backup, unpack_backup, BackupInput, BackupOutput, BackupItem, BackupAttachment};
+
+pub mod import_lastpass;
+pub use import_lastpass::{parse_lastpass_csv, ImportWarning};
+
+pub mod device;
+pub use device::{fingerprint, DeviceEntry, RevokedEntry, generate_keypair, sign, verify};
+
+pub mod tar_safe;
+pub use tar_safe::{safe_unpack_git_archive, DEFAULT_MAX_UNCOMPRESSED};
+
+pub mod recovery_qr;
+pub use recovery_qr::{
+    generate_recovery_qr, generate_recovery_qr_with_params,
+    recovery_qr_to_svg,
+    unwrap_recovery_qr, unwrap_recovery_qr_with_params,
+    RecoveryQrPayload,
+};

crates/relicario-core/src/recovery_qr.rs

@@ -0,0 +1,129 @@
+use chacha20poly1305::{XChaCha20Poly1305, Key, KeyInit, aead::Aead};
+use rand::RngCore;
+use unicode_normalization::UnicodeNormalization;
+use zeroize::Zeroizing;
+use crate::{crypto::KdfParams, error::{RelicarioError, Result}};
+
+const MAGIC: &[u8; 4] = b"RREC";
+const VERSION: u8 = 0x01;
+const PAYLOAD_LEN: usize = 4 + 1 + 32 + 24 + 48; // 109
+
+pub struct RecoveryQrPayload {
+    bytes: [u8; PAYLOAD_LEN],
+}
+
+impl RecoveryQrPayload {
+    pub fn as_bytes(&self) -> &[u8; PAYLOAD_LEN] {
+        &self.bytes
+    }
+}
+
+fn recovery_kdf_input(passphrase: &str) -> Vec<u8> {
+    let nfc: String = passphrase.nfc().collect();
+    let nfc_bytes = nfc.as_bytes();
+    let prefix = b"relicario-recovery-v1\0";
+    let mut input = Vec::with_capacity(prefix.len() + 8 + nfc_bytes.len());
+    input.extend_from_slice(prefix);
+    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],
+    params: &KdfParams,
+) -> Result<Zeroizing<[u8; 32]>> {
+    let input = recovery_kdf_input(passphrase);
+    crate::crypto::derive_master_key_raw(&input, kdf_salt, params)
+}
+
+pub fn generate_recovery_qr(
+    passphrase: &str,
+    image_secret: &[u8; 32],
+) -> Result<RecoveryQrPayload> {
+    generate_recovery_qr_with_params(passphrase, image_secret, &production_params())
+}
+
+#[doc(hidden)]
+pub fn generate_recovery_qr_with_params(
+    passphrase: &str,
+    image_secret: &[u8; 32],
+    params: &KdfParams,
+) -> Result<RecoveryQrPayload> {
+    let mut kdf_salt = [0u8; 32];
+    rand::rngs::OsRng.fill_bytes(&mut kdf_salt);
+
+    let mut wrap_nonce = [0u8; 24];
+    rand::rngs::OsRng.fill_bytes(&mut wrap_nonce);
+
+    let wrap_key = derive_wrap_key(passphrase, &kdf_salt, params)?;
+    let cipher = XChaCha20Poly1305::new(Key::from_slice(wrap_key.as_ref()));
+    let nonce = chacha20poly1305::XNonce::from_slice(&wrap_nonce);
+    let ciphertext = cipher.encrypt(nonce, image_secret.as_ref())
+        .map_err(|_| RelicarioError::RecoveryQr("wrap encrypt failed".into()))?;
+
+    let mut bytes = [0u8; PAYLOAD_LEN];
+    let mut pos = 0;
+    bytes[pos..pos+4].copy_from_slice(MAGIC);     pos += 4;
+    bytes[pos] = VERSION;                           pos += 1;
+    bytes[pos..pos+32].copy_from_slice(&kdf_salt); pos += 32;
+    bytes[pos..pos+24].copy_from_slice(&wrap_nonce); pos += 24;
+    bytes[pos..pos+48].copy_from_slice(&ciphertext);
+
+    Ok(RecoveryQrPayload { bytes })
+}
+
+pub fn unwrap_recovery_qr(
+    payload_bytes: &[u8],
+    passphrase: &str,
+) -> Result<Zeroizing<[u8; 32]>> {
+    unwrap_recovery_qr_with_params(payload_bytes, passphrase, &production_params())
+}
+
+#[doc(hidden)]
+pub fn unwrap_recovery_qr_with_params(
+    payload_bytes: &[u8],
+    passphrase: &str,
+    params: &KdfParams,
+) -> Result<Zeroizing<[u8; 32]>> {
+    if payload_bytes.len() != PAYLOAD_LEN {
+        return Err(RelicarioError::RecoveryQr(
+            format!("payload must be {PAYLOAD_LEN} bytes, got {}", payload_bytes.len())
+        ));
+    }
+    if &payload_bytes[0..4] != MAGIC {
+        return Err(RelicarioError::RecoveryQr("bad magic".into()));
+    }
+    if payload_bytes[4] != VERSION {
+        return Err(RelicarioError::RecoveryQr(
+            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 wrap_key = derive_wrap_key(passphrase, kdf_salt, params)?;
+    let cipher = XChaCha20Poly1305::new(Key::from_slice(wrap_key.as_ref()));
+    let nonce = chacha20poly1305::XNonce::from_slice(wrap_nonce);
+    let plaintext = cipher.decrypt(nonce, ciphertext)
+        .map_err(|_| RelicarioError::Decrypt)?;
+
+    let mut out = Zeroizing::new([0u8; 32]);
+    out.copy_from_slice(&plaintext);
+    Ok(out)
+}
+
+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)
+        .expect("109 bytes fits well within QR v40 capacity at EcLevel::M");
+    code.render::<qrcode::render::svg::Color>()
+        .min_dimensions(140, 140)
+        .build()
+}

crates/relicario-core/src/tar_safe.rs

@@ -0,0 +1,138 @@
+//! Safe tar unpacking for backup restore.
+//!
+//! The standard `tar::Archive::unpack` has no guards against path traversal,
+//! absolute paths, symlinks, hardlinks, or tar bombs. This module replaces it
+//! with `safe_unpack_git_archive`, which validates every entry before returning
+//! `(relative_path, bytes)` pairs to the caller.
+
+use std::io::Read;
+use std::path::{Component, PathBuf};
+
+use tar::EntryType;
+
+use crate::error::{RelicarioError, Result};
+
+/// Default cap on total uncompressed bytes extracted in one restore (1 GiB).
+pub const DEFAULT_MAX_UNCOMPRESSED: u64 = 1024 * 1024 * 1024;
+
+/// Decode `tar_bytes` and return `(relative_path, file_bytes)` pairs for
+/// regular files only.
+///
+/// # Errors
+///
+/// Returns `Err(RelicarioError::BackupRestore(...))` if:
+///
+/// - Any path component is `..` (`Component::ParentDir`) — "path traversal blocked".
+/// - Any path starts with `/` (`Component::RootDir`) — "path traversal blocked".
+/// - Any path has a Windows drive prefix (`Component::Prefix`) — "path traversal blocked".
+/// - An entry is a symlink or hardlink — "symlink/link rejected".
+/// - An entry's declared size exceeds `max_uncompressed_bytes` — "size cap exceeded".
+/// - The running total of all entry sizes exceeds `max_uncompressed_bytes` — "size cap exceeded".
+/// - An entry has an unexpected type (not regular file, not directory) — "unexpected entry type".
+pub fn safe_unpack_git_archive(
+    tar_bytes: &[u8],
+    max_uncompressed_bytes: u64,
+) -> Result<Vec<(PathBuf, Vec<u8>)>> {
+    let mut archive = tar::Archive::new(tar_bytes);
+    let entries = archive
+        .entries()
+        .map_err(|e| RelicarioError::BackupRestore(format!("failed to read tar entries: {e}")))?;
+
+    let mut result: Vec<(PathBuf, Vec<u8>)> = Vec::new();
+    let mut cumulative: u64 = 0;
+
+    for entry in entries {
+        let mut entry = entry.map_err(|e| {
+            RelicarioError::BackupRestore(format!("failed to read tar entry: {e}"))
+        })?;
+
+        let header = entry.header();
+        let entry_type = header.entry_type();
+
+        // Reject symlinks and hardlinks.
+        match entry_type {
+            EntryType::Symlink => {
+                return Err(RelicarioError::BackupRestore(
+                    "symlink entry rejected".to_string(),
+                ));
+            }
+            EntryType::Link => {
+                return Err(RelicarioError::BackupRestore(
+                    "hardlink entry rejected".to_string(),
+                ));
+            }
+            EntryType::Directory => {
+                // Directories are implicit — skip without reading body.
+                continue;
+            }
+            EntryType::Regular | EntryType::Continuous | EntryType::GNUSparse => {
+                // These are normal file types; fall through to path checks.
+            }
+            _ => {
+                return Err(RelicarioError::BackupRestore(format!(
+                    "unexpected entry type: {:?}",
+                    entry_type
+                )));
+            }
+        }
+
+        // Validate the path.
+        let path = entry.path().map_err(|e| {
+            RelicarioError::BackupRestore(format!("invalid path in tar entry: {e}"))
+        })?;
+        let path = path.into_owned();
+
+        for component in path.components() {
+            match component {
+                Component::ParentDir => {
+                    return Err(RelicarioError::BackupRestore(
+                        "path traversal blocked: entry contains '..' component".to_string(),
+                    ));
+                }
+                Component::RootDir => {
+                    return Err(RelicarioError::BackupRestore(
+                        "path traversal blocked: entry has absolute path".to_string(),
+                    ));
+                }
+                Component::Prefix(_) => {
+                    return Err(RelicarioError::BackupRestore(
+                        "path traversal blocked: entry has Windows drive prefix".to_string(),
+                    ));
+                }
+                Component::Normal(_) | Component::CurDir => {
+                    // Acceptable components.
+                }
+            }
+        }
+
+        // Check declared size before reading body.
+        let claimed = header.size().map_err(|e| {
+            RelicarioError::BackupRestore(format!("could not read entry size: {e}"))
+        })?;
+
+        if claimed > max_uncompressed_bytes {
+            return Err(RelicarioError::BackupRestore(format!(
+                "size cap exceeded: entry claims {claimed} bytes (cap {max_uncompressed_bytes})"
+            )));
+        }
+
+        let new_total = cumulative.saturating_add(claimed);
+        if new_total > max_uncompressed_bytes {
+            return Err(RelicarioError::BackupRestore(format!(
+                "size cap exceeded: cumulative size would reach {new_total} bytes (cap {max_uncompressed_bytes})"
+            )));
+        }
+
+        // Read the file body.
+        let mut body = Vec::with_capacity(claimed as usize);
+        entry.read_to_end(&mut body).map_err(|e| {
+            RelicarioError::BackupRestore(format!("failed to read entry body: {e}"))
+        })?;
+
+        cumulative += body.len() as u64;
+
+        result.push((path, body));
+    }
+
+    Ok(result)
+}

crates/relicario-core/src/time.rs

@@ -19,7 +19,7 @@ impl MonthYear {
         if !(1..=12).contains(&month) {
             return Err("month must be 1..=12");
         }
-        if year < 2000 || year > 2099 {
+        if !(2000..=2099).contains(&year) {
             return Err("year must be 2000..=2099");
         }
         Ok(Self { month, year })

crates/relicario-core/tests/backup.rs

@@ -0,0 +1,215 @@
+//! Backup container round-trip + error-path coverage.
+
+use relicario_core::backup::{pack_backup, unpack_backup, BackupInput};
+
+fn empty_input() -> BackupInput<'static> {
+    BackupInput {
+        salt: &[0u8; 32],
+        params_json: r#"{"format_version":2,"kdf":{"argon2_m":256,"argon2_t":1,"argon2_p":1},"aead":"xchacha20poly1305","salt_path":".relicario/salt"}"#,
+        devices_json: "[]",
+        manifest_enc: &[],
+        settings_enc: &[],
+        items: vec![],
+        attachments: vec![],
+        reference_jpg: None,
+        git_archive: None,
+    }
+}
+
+#[test]
+fn empty_vault_round_trip() {
+    let out = pack_backup(empty_input(), "test-passphrase-1234").unwrap();
+    assert_eq!(&out[..4], b"RBAK", "magic header");
+    assert_eq!(out[4], 0x01, "format version");
+
+    let unpacked = unpack_backup(&out, "test-passphrase-1234").unwrap();
+    assert_eq!(unpacked.salt, [0u8; 32]);
+    assert!(unpacked.devices_json.contains("[]"));
+    assert!(unpacked.items.is_empty());
+    assert!(unpacked.attachments.is_empty());
+    assert!(unpacked.reference_jpg.is_none());
+    assert!(unpacked.git_archive.is_none());
+}
+
+use relicario_core::backup::{BackupAttachment, BackupItem};
+
+#[test]
+fn populated_vault_round_trip() {
+    let manifest_enc = vec![0xDE, 0xAD, 0xBE, 0xEF, 0x42];
+    let settings_enc = vec![0x01, 0x02, 0x03];
+    let item_a_ct = vec![0xAA; 100];
+    let item_b_ct = vec![0xBB; 200];
+    let attach_x_ct = vec![0xCC; 4096];
+    let attach_y_ct = vec![0xDD; 8192];
+
+    let input = BackupInput {
+        salt: &[0x77u8; 32],
+        params_json: r#"{"format_version":2,"kdf":{"argon2_m":256,"argon2_t":1,"argon2_p":1},"aead":"xchacha20poly1305","salt_path":".relicario/salt"}"#,
+        devices_json: r#"[{"name":"laptop","public_key":"deadbeef"}]"#,
+        manifest_enc: &manifest_enc,
+        settings_enc: &settings_enc,
+        items: vec![
+            BackupItem { id: "1111111111111111".to_string(), ciphertext: &item_a_ct },
+            BackupItem { id: "2222222222222222".to_string(), ciphertext: &item_b_ct },
+        ],
+        attachments: vec![
+            BackupAttachment {
+                item_id: "1111111111111111".to_string(),
+                attachment_id: "aaaa1111".to_string(),
+                ciphertext: &attach_x_ct,
+            },
+            BackupAttachment {
+                item_id: "2222222222222222".to_string(),
+                attachment_id: "bbbb2222".to_string(),
+                ciphertext: &attach_y_ct,
+            },
+        ],
+        reference_jpg: None,
+        git_archive: None,
+    };
+
+    let out = pack_backup(input, "another-strong-passphrase").unwrap();
+    let unpacked = unpack_backup(&out, "another-strong-passphrase").unwrap();
+
+    assert_eq!(unpacked.salt, [0x77u8; 32]);
+    assert!(unpacked.devices_json.contains("laptop"));
+    assert_eq!(unpacked.manifest_enc, manifest_enc);
+    assert_eq!(unpacked.settings_enc, settings_enc);
+
+    assert_eq!(unpacked.items.len(), 2);
+    let by_id: std::collections::HashMap<_, _> =
+        unpacked.items.iter().map(|i| (i.id.as_str(), &i.ciphertext)).collect();
+    assert_eq!(by_id.get("1111111111111111").unwrap(), &&item_a_ct);
+    assert_eq!(by_id.get("2222222222222222").unwrap(), &&item_b_ct);
+
+    assert_eq!(unpacked.attachments.len(), 2);
+    let by_aid: std::collections::HashMap<_, _> = unpacked
+        .attachments
+        .iter()
+        .map(|a| ((a.item_id.as_str(), a.attachment_id.as_str()), &a.ciphertext))
+        .collect();
+    assert_eq!(by_aid.get(&("1111111111111111", "aaaa1111")).unwrap(), &&attach_x_ct);
+    assert_eq!(by_aid.get(&("2222222222222222", "bbbb2222")).unwrap(), &&attach_y_ct);
+}
+
+#[test]
+fn round_trip_with_reference_image() {
+    let jpg_bytes: Vec<u8> = (0u8..=255).cycle().take(1024 * 64).collect(); // 64 KiB
+    let mut input = empty_input();
+    input.reference_jpg = Some(&jpg_bytes);
+
+    let out = pack_backup(input, "p").unwrap();
+    let unpacked = unpack_backup(&out, "p").unwrap();
+
+    assert_eq!(unpacked.reference_jpg.as_deref(), Some(jpg_bytes.as_slice()));
+    assert!(unpacked.git_archive.is_none());
+}
+
+#[test]
+fn round_trip_with_git_archive() {
+    let tar_bytes: Vec<u8> = b"FAKE TAR BYTES; core treats opaquely".repeat(50);
+    let mut input = empty_input();
+    input.git_archive = Some(&tar_bytes);
+
+    let out = pack_backup(input, "p").unwrap();
+    let unpacked = unpack_backup(&out, "p").unwrap();
+
+    assert_eq!(unpacked.git_archive.as_deref(), Some(tar_bytes.as_slice()));
+}
+
+#[test]
+fn no_history_produces_strict_subset() {
+    let mut a = empty_input();
+    a.git_archive = Some(b"some-tar-bytes");
+    let with = pack_backup(a, "p").unwrap();
+
+    let without = pack_backup(empty_input(), "p").unwrap();
+
+    // The "without" file is strictly smaller (one fewer base64-encoded blob in JSON).
+    assert!(without.len() < with.len(),
+        "no-history backup should be smaller: with={}, without={}",
+        with.len(), without.len()
+    );
+}
+
+use relicario_core::RelicarioError;
+
+#[test]
+fn bad_magic_rejected() {
+    let mut bytes = pack_backup(empty_input(), "p").unwrap();
+    bytes[0] = b'X';
+    match unpack_backup(&bytes, "p") {
+        Err(RelicarioError::BackupBadMagic) => {}
+        other => panic!("expected BackupBadMagic, got {other:?}"),
+    }
+}
+
+#[test]
+fn unsupported_version_rejected() {
+    let mut bytes = pack_backup(empty_input(), "p").unwrap();
+    bytes[4] = 0xFF;
+    match unpack_backup(&bytes, "p") {
+        Err(RelicarioError::BackupUnsupportedVersion { found, expected }) => {
+            assert_eq!(found, 0xFF);
+            assert_eq!(expected, 0x01);
+        }
+        other => panic!("expected BackupUnsupportedVersion, got {other:?}"),
+    }
+}
+
+#[test]
+fn wrong_passphrase_rejected_as_decrypt_error() {
+    let bytes = pack_backup(empty_input(), "right-passphrase").unwrap();
+    match unpack_backup(&bytes, "wrong-passphrase") {
+        Err(RelicarioError::Decrypt) => {}
+        other => panic!("expected Decrypt (opaque), got {other:?}"),
+    }
+}
+
+#[test]
+fn truncated_file_rejected() {
+    let bytes = pack_backup(empty_input(), "p").unwrap();
+    let truncated = &bytes[..bytes.len().min(60)]; // shorter than HEADER_LEN + TAG_LEN
+    match unpack_backup(truncated, "p") {
+        Err(RelicarioError::Format(_)) => {}
+        other => panic!("expected Format(truncated), got {other:?}"),
+    }
+}
+
+#[test]
+fn tampered_ciphertext_rejected_as_decrypt_error() {
+    let mut bytes = pack_backup(empty_input(), "p").unwrap();
+    let last = bytes.len() - 1;
+    bytes[last] ^= 0xFF; // flip a byte in the auth-tag region
+    match unpack_backup(&bytes, "p") {
+        Err(RelicarioError::Decrypt) => {}
+        other => panic!("expected Decrypt for tampered tag, got {other:?}"),
+    }
+}
+
+#[test]
+fn backup_roundtrip_with_nfd_passphrase() {
+    // "café" in NFD (decomposed: e + combining acute accent)
+    let nfd_passphrase = "caf\u{0065}\u{0301}";
+    // "café" in NFC (precomposed é)
+    let nfc_passphrase = "caf\u{00E9}";
+
+    let input = BackupInput {
+        salt: &[0u8; 32],
+        params_json: r#"{"format_version":2,"kdf":{"argon2_m":256,"argon2_t":1,"argon2_p":1},"aead":"xchacha20poly1305","salt_path":".relicario/salt"}"#,
+        devices_json: "[]",
+        manifest_enc: &[1, 2, 3],
+        settings_enc: &[4, 5, 6],
+        items: vec![],
+        attachments: vec![],
+        reference_jpg: None,
+        git_archive: None,
+    };
+
+    // Pack with NFD passphrase
+    let packed = pack_backup(input, nfd_passphrase).unwrap();
+
+    // Unpack with NFC passphrase — should work after fix
+    let unpacked = unpack_backup(&packed, nfc_passphrase).unwrap();
+    assert_eq!(unpacked.manifest_enc, vec![1, 2, 3]);
+}

crates/relicario-core/tests/import_lastpass.rs

@@ -0,0 +1,276 @@
+//! LastPass CSV importer — parser coverage.
+
+use relicario_core::import_lastpass::{parse_lastpass_csv, ImportWarning};
+use relicario_core::item_types::{TotpAlgorithm, TotpKind};
+use relicario_core::ItemCore;
+
+const HEADER: &str = "url,username,password,totp,extra,name,grouping,fav";
+
+#[test]
+fn single_login_row_round_trips() {
+    let csv = format!(
+        "{HEADER}\n\
+         https://github.com/login,alice,hunter2,,,GitHub,,",
+    );
+    let (items, warnings) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert_eq!(items.len(), 1, "one item expected");
+    assert!(warnings.is_empty(), "no warnings expected");
+
+    let item = &items[0];
+    assert_eq!(item.title, "GitHub");
+    assert!(!item.favorite);
+    assert!(item.group.is_none());
+    match &item.core {
+        ItemCore::Login(l) => {
+            assert_eq!(l.username.as_deref(), Some("alice"));
+            assert_eq!(l.password.as_deref().map(String::as_str), Some("hunter2"));
+            assert_eq!(l.url.as_ref().map(|u| u.as_str()), Some("https://github.com/login"));
+            assert!(l.totp.is_none());
+        }
+        other => panic!("expected Login, got {:?}", other),
+    }
+}
+
+#[test]
+fn item_id_is_freshly_minted() {
+    // Decision D12: title collisions don't dedupe; each row gets a fresh ID.
+    let csv = format!("{HEADER}\nhttps://x,u,p,,,Same,,\nhttps://x,u,p,,,Same,,");
+    let (items, _) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert_eq!(items.len(), 2);
+    assert_ne!(items[0].id, items[1].id, "IDs must be unique even for identical names");
+}
+
+// Assertion helper used by later tests.
+#[allow(dead_code)]
+fn first_warning_message(warnings: &[ImportWarning]) -> String {
+    warnings.first().expect("expected at least one warning").message.clone()
+}
+
+#[test]
+fn grouping_maps_to_item_group() {
+    let csv = format!("{HEADER}\nhttps://x,u,p,,,Bank,Finance,");
+    let (items, warnings) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert!(warnings.is_empty());
+    assert_eq!(items[0].group.as_deref(), Some("Finance"));
+}
+
+#[test]
+fn empty_grouping_yields_none() {
+    let csv = format!("{HEADER}\nhttps://x,u,p,,,Bank,,");
+    let (items, _) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert!(items[0].group.is_none());
+}
+
+#[test]
+fn fav_one_marks_favorite() {
+    let csv = format!("{HEADER}\nhttps://x,u,p,,,Bank,,1");
+    let (items, _) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert!(items[0].favorite);
+}
+
+#[test]
+fn fav_zero_or_blank_not_favorite() {
+    let csv = format!(
+        "{HEADER}\n\
+         https://x,u,p,,,Zero,,0\n\
+         https://x,u,p,,,Blank,,",
+    );
+    let (items, _) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert_eq!(items.len(), 2);
+    assert!(!items[0].favorite);
+    assert!(!items[1].favorite);
+}
+
+#[test]
+fn extra_becomes_notes_for_login() {
+    let csv = format!("{HEADER}\nhttps://x,u,p,,a hint,Bank,,");
+    let (items, _) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert_eq!(items[0].notes.as_deref(), Some("a hint"));
+}
+
+#[test]
+fn multiline_extra_round_trips_via_quoting() {
+    // CSV double-quotes escape embedded newlines.
+    let csv = format!(
+        "{HEADER}\n\
+         https://x,u,p,,\"line1\nline2\nline3\",Bank,,",
+    );
+    let (items, warnings) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert!(warnings.is_empty(), "multi-line extra should parse cleanly");
+    assert_eq!(items[0].notes.as_deref(), Some("line1\nline2\nline3"));
+}
+
+#[test]
+fn login_with_valid_totp_secret_attaches_config() {
+    // RFC 4648 base32 of b"12345678901234567890" → "GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ".
+    let csv = format!(
+        "{HEADER}\n\
+         https://github.com/login,alice,hunter2,GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ,,GitHub,,",
+    );
+    let (items, warnings) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert!(warnings.is_empty());
+    match &items[0].core {
+        ItemCore::Login(l) => {
+            let totp = l.totp.as_ref().expect("expected TOTP config");
+            assert_eq!(totp.algorithm, TotpAlgorithm::Sha1);
+            assert_eq!(totp.digits, 6);
+            assert_eq!(totp.period_seconds, 30);
+            assert_eq!(totp.kind, TotpKind::Totp);
+            assert_eq!(totp.secret.as_slice(), b"12345678901234567890");
+        }
+        other => panic!("expected Login, got {:?}", other),
+    }
+}
+
+#[test]
+fn login_with_bad_totp_secret_imports_without_totp_and_warns() {
+    let csv = format!(
+        "{HEADER}\n\
+         https://github.com/login,alice,hunter2,!!!!not-base32!!!!,,GitHub,,",
+    );
+    let (items, warnings) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert_eq!(items.len(), 1, "login should still import");
+    match &items[0].core {
+        ItemCore::Login(l) => assert!(l.totp.is_none(), "TOTP must be dropped"),
+        other => panic!("expected Login, got {:?}", other),
+    }
+    assert_eq!(warnings.len(), 1);
+    let w = &warnings[0];
+    assert_eq!(w.title.as_deref(), Some("GitHub"));
+    assert!(w.message.contains("TOTP"), "message: {}", w.message);
+    assert!(w.message.contains("invalid") || w.message.contains("base32"));
+}
+
+#[test]
+fn login_with_lowercase_base32_totp_is_accepted() {
+    // RFC 4648 is case-insensitive; LastPass exports may use either case.
+    let csv = format!(
+        "{HEADER}\n\
+         https://x,u,p,gezdgnbvgy3tqojqgezdgnbvgy3tqojq,,Acme,,",
+    );
+    let (items, warnings) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert!(warnings.is_empty(), "lowercase base32 must parse");
+    match &items[0].core {
+        ItemCore::Login(l) => assert!(l.totp.is_some()),
+        _ => unreachable!(),
+    }
+}
+
+#[test]
+fn url_http_sn_maps_to_secure_note() {
+    let csv = format!(
+        "{HEADER}\n\
+         http://sn,,,,The body of the note,My Note,,",
+    );
+    let (items, warnings) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert!(warnings.is_empty());
+    assert_eq!(items.len(), 1);
+    assert_eq!(items[0].title, "My Note");
+    match &items[0].core {
+        ItemCore::SecureNote(sn) => assert_eq!(sn.body.as_str(), "The body of the note"),
+        other => panic!("expected SecureNote, got {:?}", other),
+    }
+}
+
+#[test]
+fn secure_note_does_not_require_password() {
+    // SecureNote rows have empty password; that must not trigger the
+    // `missing password` skip path (which is Login-only).
+    let csv = format!("{HEADER}\nhttp://sn,,,,note text,Title,,");
+    let (items, warnings) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert!(warnings.is_empty(), "{:?}", warnings);
+    assert_eq!(items.len(), 1);
+}
+
+#[test]
+fn secure_note_passes_through_grouping_and_favorite() {
+    let csv = format!("{HEADER}\nhttp://sn,,,,body,Title,Personal,1");
+    let (items, _) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert_eq!(items[0].group.as_deref(), Some("Personal"));
+    assert!(items[0].favorite);
+}
+
+#[test]
+fn secure_note_preserves_structured_extra_verbatim() {
+    // LastPass packs structured note data (e.g. credit cards) into `extra`
+    // using their own key:value format. We do NOT auto-parse it — verbatim
+    // pass-through, per spec D10.
+    let csv_body = "NoteType:Credit Card\nNumber:4111111111111111\nCVV:123";
+    let csv = format!(
+        "{HEADER}\n\
+         http://sn,,,,\"{csv_body}\",Visa,,",
+        csv_body = csv_body,
+    );
+    let (items, _) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    match &items[0].core {
+        ItemCore::SecureNote(sn) => assert_eq!(sn.body.as_str(), csv_body),
+        _ => unreachable!(),
+    }
+}
+
+#[test]
+fn login_with_unparseable_url_imports_with_url_none_and_warns() {
+    let csv = format!(
+        "{HEADER}\n\
+         not-a-real-url,alice,hunter2,,,Site,,",
+    );
+    let (items, warnings) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert_eq!(items.len(), 1);
+    match &items[0].core {
+        ItemCore::Login(l) => assert!(l.url.is_none()),
+        _ => unreachable!(),
+    }
+    assert_eq!(warnings.len(), 1);
+    assert!(warnings[0].message.contains("URL"), "msg: {}", warnings[0].message);
+    assert_eq!(warnings[0].title.as_deref(), Some("Site"));
+}
+
+#[test]
+fn header_with_extra_column_is_rejected() {
+    let bad = "url,username,password,totp,extra,name,grouping,fav,EXTRA\nhttps://x,u,p,,,T,,";
+    let err = parse_lastpass_csv(bad.as_bytes()).unwrap_err();
+    let msg = format!("{err}");
+    assert!(msg.contains("LastPass") || msg.contains("expected"), "msg: {msg}");
+}
+
+#[test]
+fn header_with_wrong_column_order_is_rejected() {
+    let swapped = "name,url,username,password,totp,extra,grouping,fav\nT,https://x,u,p,,,,";
+    let err = parse_lastpass_csv(swapped.as_bytes()).unwrap_err();
+    assert!(format!("{err}").contains("expected"));
+}
+
+#[test]
+fn quoted_comma_in_extra_parses() {
+    let csv = format!(
+        "{HEADER}\n\
+         https://x,u,p,,\"hint with, a comma\",Site,,",
+    );
+    let (items, warnings) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert!(warnings.is_empty());
+    assert_eq!(items[0].notes.as_deref(), Some("hint with, a comma"));
+}
+
+#[test]
+fn unicode_title_round_trips() {
+    let csv = format!("{HEADER}\nhttps://x,u,p,,,Müllerstraße — café ☕,,");
+    let (items, _) = parse_lastpass_csv(csv.as_bytes()).unwrap();
+    assert_eq!(items[0].title, "Müllerstraße — café ☕");
+}
+
+#[test]
+fn empty_csv_after_header_returns_empty_vecs() {
+    let (items, warnings) = parse_lastpass_csv(HEADER.as_bytes()).unwrap();
+    assert!(items.is_empty());
+    assert!(warnings.is_empty());
+}
+
+#[test]
+fn missing_header_is_rejected() {
+    // Empty input — csv reader treats first row as header (which doesn't exist).
+    let err = parse_lastpass_csv(b"").unwrap_err();
+    let msg = format!("{err}");
+    // Either ImportCsvHeader (header didn't match) or ImportCsvFormat (read
+    // failed). Both are acceptable; we just need a clear error.
+    assert!(msg.contains("LastPass") || msg.contains("CSV"), "msg: {msg}");
+}

crates/relicario-core/tests/recovery_qr.rs

@@ -0,0 +1,60 @@
+use relicario_core::{
+    crypto::KdfParams,
+    generate_recovery_qr_with_params, recovery_qr_to_svg, unwrap_recovery_qr_with_params,
+};
+
+fn fast_params() -> KdfParams {
+    KdfParams { argon2_m: 256, argon2_t: 1, argon2_p: 1 }
+}
+
+fn test_secret() -> [u8; 32] {
+    let mut s = [0u8; 32];
+    for (i, b) in s.iter_mut().enumerate() { *b = i as u8; }
+    s
+}
+
+#[test]
+fn roundtrip_recovers_image_secret() {
+    let passphrase = "correct-horse-battery-staple";
+    let secret = test_secret();
+    let payload = generate_recovery_qr_with_params(passphrase, &secret, &fast_params())
+        .expect("generate ok");
+    let recovered = unwrap_recovery_qr_with_params(payload.as_bytes(), passphrase, &fast_params())
+        .expect("unwrap ok");
+    assert_eq!(recovered.as_ref(), &secret);
+}
+
+#[test]
+fn wrong_passphrase_fails_decrypt() {
+    let secret = test_secret();
+    let payload = generate_recovery_qr_with_params("right-pass", &secret, &fast_params())
+        .expect("generate ok");
+    let result = unwrap_recovery_qr_with_params(payload.as_bytes(), "wrong-pass", &fast_params());
+    assert!(result.is_err());
+}
+
+#[test]
+fn payload_is_109_bytes() {
+    let secret = test_secret();
+    let payload = generate_recovery_qr_with_params("test", &secret, &fast_params())
+        .expect("generate ok");
+    assert_eq!(payload.as_bytes().len(), 109);
+}
+
+#[test]
+fn svg_output_is_non_empty_xml() {
+    let secret = test_secret();
+    let payload = generate_recovery_qr_with_params("test", &secret, &fast_params())
+        .expect("generate ok");
+    let svg = recovery_qr_to_svg(&payload);
+    assert!(svg.contains("<svg"), "SVG output should contain <svg tag");
+    assert!(!svg.is_empty());
+}
+
+#[test]
+fn bad_magic_returns_error() {
+    let mut bad = [0u8; 109];
+    bad[0..4].copy_from_slice(b"NOPE");
+    let result = unwrap_recovery_qr_with_params(&bad, "pass", &fast_params());
+    assert!(result.is_err());
+}

crates/relicario-core/tests/safe_unpack.rs

@@ -0,0 +1,187 @@
+use std::path::PathBuf;
+use tar::{Builder, Header, EntryType};
+use relicario_core::safe_unpack_git_archive;
+
+/// Craft a raw POSIX ustar tar with a single entry using the given raw path bytes.
+/// The tar crate's `Builder` sanitises paths, so we write the 512-byte header
+/// manually to produce truly malicious archives.
+fn raw_tar_with_path(raw_path: &[u8], content: &[u8]) -> Vec<u8> {
+    let mut buf = vec![0u8; 512]; // one header block
+
+    // Bytes 0-99: name field (null-padded)
+    let name_len = raw_path.len().min(100);
+    buf[..name_len].copy_from_slice(&raw_path[..name_len]);
+
+    // Bytes 100-107: mode = "0000644\0"
+    buf[100..108].copy_from_slice(b"0000644\0");
+
+    // Bytes 108-115: uid
+    buf[108..116].copy_from_slice(b"0000000\0");
+
+    // Bytes 116-123: gid
+    buf[116..124].copy_from_slice(b"0000000\0");
+
+    // Bytes 124-135: size (octal, 11 digits + null)
+    let size_str = format!("{:011o}\0", content.len());
+    buf[124..136].copy_from_slice(size_str.as_bytes());
+
+    // Bytes 136-147: mtime
+    buf[136..148].copy_from_slice(b"00000000000\0");
+
+    // Bytes 148-155: checksum placeholder (spaces during compute)
+    buf[148..156].copy_from_slice(b"        ");
+
+    // Byte 156: typeflag = '0' (regular file)
+    buf[156] = b'0';
+
+    // Bytes 257-262: magic "ustar\0"
+    buf[257..263].copy_from_slice(b"ustar\0");
+    // Bytes 263-264: version "00"
+    buf[263..265].copy_from_slice(b"00");
+
+    // Compute checksum (sum of all bytes, checksum field treated as spaces).
+    let checksum: u32 = buf.iter().map(|&b| b as u32).sum();
+    let cksum_str = format!("{:06o}\0 ", checksum);
+    buf[148..156].copy_from_slice(cksum_str.as_bytes());
+
+    // Append padded content blocks.
+    let mut out = buf;
+    if !content.is_empty() {
+        out.extend_from_slice(content);
+        // Pad to 512-byte boundary.
+        let remainder = content.len() % 512;
+        if remainder != 0 {
+            out.extend(vec![0u8; 512 - remainder]);
+        }
+    }
+
+    // Two zero blocks = end-of-archive.
+    out.extend(vec![0u8; 1024]);
+    out
+}
+
+/// Build a tar with a raw symlink entry (typeflag = '2').
+fn raw_symlink_tar() -> Vec<u8> {
+    let mut buf = vec![0u8; 512];
+
+    // name
+    buf[..9].copy_from_slice(b"evil_link");
+    // mode
+    buf[100..108].copy_from_slice(b"0000755\0");
+    // uid/gid
+    buf[108..116].copy_from_slice(b"0000000\0");
+    buf[116..124].copy_from_slice(b"0000000\0");
+    // size = 0
+    buf[124..136].copy_from_slice(b"00000000000\0");
+    // mtime
+    buf[136..148].copy_from_slice(b"00000000000\0");
+    // checksum placeholder
+    buf[148..156].copy_from_slice(b"        ");
+    // typeflag = '2' (symlink)
+    buf[156] = b'2';
+    // linkname
+    let target = b"/etc/passwd";
+    buf[157..157 + target.len()].copy_from_slice(target);
+    // magic
+    buf[257..263].copy_from_slice(b"ustar\0");
+    buf[263..265].copy_from_slice(b"00");
+
+    // Compute checksum.
+    let checksum: u32 = buf.iter().map(|&b| b as u32).sum();
+    let cksum_str = format!("{:06o}\0 ", checksum);
+    buf[148..156].copy_from_slice(cksum_str.as_bytes());
+
+    let mut out = buf;
+    out.extend(vec![0u8; 1024]); // end-of-archive
+    out
+}
+
+fn build_normal_tar() -> Vec<u8> {
+    let mut buf = Vec::new();
+    {
+        let mut builder = Builder::new(&mut buf);
+        let content = b"hello";
+        let mut header = Header::new_gnu();
+        header.set_entry_type(EntryType::Regular);
+        header.set_size(content.len() as u64);
+        header.set_cksum();
+        builder
+            .append_data(&mut header, "subdir/hello.txt", content.as_ref())
+            .unwrap();
+        builder.finish().unwrap();
+    }
+    buf
+}
+
+fn build_oversize_tar() -> Vec<u8> {
+    // Actual 2048-byte body; test will use cap=1024
+    let mut buf = Vec::new();
+    {
+        let mut builder = Builder::new(&mut buf);
+        let content = vec![0u8; 2048];
+        let mut header = Header::new_gnu();
+        header.set_entry_type(EntryType::Regular);
+        header.set_size(content.len() as u64);
+        header.set_cksum();
+        builder
+            .append_data(&mut header, "bigfile.bin", content.as_slice())
+            .unwrap();
+        builder.finish().unwrap();
+    }
+    buf
+}
+
+#[test]
+fn restore_rejects_path_traversal() {
+    // Craft a tar with "../../escaped.txt" using raw bytes (Builder sanitises paths).
+    let bytes = raw_tar_with_path(b"../../escaped.txt", b"evil content");
+    let err = safe_unpack_git_archive(&bytes, 1024 * 1024).unwrap_err();
+    let msg = format!("{err:#}");
+    assert!(
+        msg.contains("path traversal") || msg.contains(".."),
+        "got: {msg}"
+    );
+}
+
+#[test]
+fn restore_rejects_absolute_path() {
+    // Craft a tar with "/etc/escaped.txt" using raw bytes.
+    let bytes = raw_tar_with_path(b"/etc/escaped.txt", b"evil content");
+    let err = safe_unpack_git_archive(&bytes, 1024 * 1024).unwrap_err();
+    let msg = format!("{err:#}");
+    assert!(
+        msg.contains("path traversal") || msg.contains("absolute"),
+        "got: {msg}"
+    );
+}
+
+#[test]
+fn restore_rejects_symlink() {
+    let bytes = raw_symlink_tar();
+    let err = safe_unpack_git_archive(&bytes, 1024 * 1024).unwrap_err();
+    let msg = format!("{err:#}");
+    assert!(
+        msg.contains("symlink") || msg.contains("link"),
+        "got: {msg}"
+    );
+}
+
+#[test]
+fn restore_rejects_size_bomb() {
+    let bytes = build_oversize_tar(); // actual 2048-byte entry
+    let err = safe_unpack_git_archive(&bytes, 1024).unwrap_err(); // cap = 1024 bytes
+    let msg = format!("{err:#}");
+    assert!(
+        msg.contains("size") || msg.contains("cap") || msg.contains("too large"),
+        "got: {msg}"
+    );
+}
+
+#[test]
+fn restore_accepts_normal_files() {
+    let buf = build_normal_tar();
+    let entries = safe_unpack_git_archive(&buf, 1024 * 1024).expect("happy path");
+    assert_eq!(entries.len(), 1);
+    assert_eq!(entries[0].0, PathBuf::from("subdir/hello.txt"));
+    assert_eq!(entries[0].1, b"hello");
+}

crates/relicario-server/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "relicario-server"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+relicario-core = { path = "../relicario-core" }
+anyhow = "1"
+clap = { version = "4", features = ["derive"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tempfile = "3"
+regex = "1"
+
+[dev-dependencies]
+assert_cmd = "2"
+predicates = "3"
+tempfile = "3"

crates/relicario-server/src/main.rs

@@ -0,0 +1,189 @@
+//! relicario-server -- pre-receive hook for signature verification.
+
+use std::fs;
+use std::process::Command;
+
+use anyhow::{Context, Result};
+use clap::{Parser, Subcommand};
+use relicario_core::device::{DeviceEntry, RevokedEntry};
+
+#[derive(Parser)]
+#[command(name = "relicario-server")]
+struct Cli {
+    #[command(subcommand)]
+    command: Commands,
+}
+
+#[derive(Subcommand)]
+enum Commands {
+    /// Verify a commit's signature against devices.json.
+    VerifyCommit {
+        /// The commit SHA to verify.
+        commit: String,
+    },
+    /// Generate a pre-receive hook script.
+    GenerateHook,
+}
+
+fn main() -> Result<()> {
+    let cli = Cli::parse();
+
+    match cli.command {
+        Commands::VerifyCommit { commit } => verify_commit(&commit),
+        Commands::GenerateHook => generate_hook(),
+    }
+}
+
+fn verify_commit(commit: &str) -> Result<()> {
+    let devices_json = match git_show(commit, ".relicario/devices.json") {
+        Ok(json) => json,
+        Err(_) => {
+            eprintln!("OK: commit {commit} (bootstrap - no devices.json)");
+            return Ok(());
+        }
+    };
+    let devices: Vec<DeviceEntry> = serde_json::from_str(&devices_json)
+        .context("parse devices.json")?;
+
+    let revoked: Vec<RevokedEntry> = git_show(commit, ".relicario/revoked.json")
+        .ok()
+        .and_then(|s| serde_json::from_str(&s).ok())
+        .unwrap_or_default();
+
+    // True bootstrap: no devices ever registered and none revoked.
+    if devices.is_empty() && revoked.is_empty() {
+        eprintln!("OK: commit {commit} (bootstrap - no devices registered)");
+        return Ok(());
+    }
+
+    // Build temp allowed-signers file from registered devices.
+    let tmp = tempfile::tempdir().context("create tempdir")?;
+    let allowed_path = tmp.path().join("allowed_signers");
+    let mut allowed_body = String::new();
+    for d in &devices {
+        allowed_body.push_str("relicario ");
+        allowed_body.push_str(d.public_key.trim());
+        allowed_body.push('\n');
+    }
+    fs::write(&allowed_path, &allowed_body).context("write allowed_signers")?;
+
+    // Run git verify-commit --raw. Capture both exit code and stderr.
+    // NOTE: we do NOT short-circuit on non-zero exit here because even for
+    // unregistered keys git still outputs "Good ... key SHA256:..." on stderr.
+    let output = Command::new("git")
+        .args(["verify-commit", "--raw", commit])
+        .env("GIT_CONFIG_COUNT", "1")
+        .env("GIT_CONFIG_KEY_0", "gpg.ssh.allowedSignersFile")
+        .env("GIT_CONFIG_VALUE_0", allowed_path.as_os_str())
+        .output()
+        .context("git verify-commit")?;
+
+    let stderr = String::from_utf8_lossy(&output.stderr);
+
+    // Parse the SHA-256 fingerprint from stderr.
+    // SSH signature output: "Good "git" signature ... with ED25519 key SHA256:<base64>"
+    let re = regex::Regex::new(r"key (SHA256:[A-Za-z0-9+/]+)").expect("static regex");
+    let signing_fp = match re.captures(&stderr).and_then(|c| c.get(1)) {
+        Some(m) => m.as_str().to_string(),
+        None => {
+            // No fingerprint in stderr = unsigned or completely malformed signature.
+            eprintln!(
+                "REJECT: commit {commit} — no valid signature found (stderr: {})",
+                stderr.trim()
+            );
+            std::process::exit(1);
+        }
+    };
+
+    // Build fingerprint → entry maps.
+    let mut device_by_fp: std::collections::HashMap<String, &DeviceEntry> =
+        std::collections::HashMap::new();
+    for d in &devices {
+        if let Ok(fp) = relicario_core::device::fingerprint(&d.public_key) {
+            device_by_fp.insert(fp, d);
+        }
+    }
+
+    let mut revoked_by_fp: std::collections::HashMap<String, &RevokedEntry> =
+        std::collections::HashMap::new();
+    for r in &revoked {
+        if let Ok(fp) = relicario_core::device::fingerprint(&r.public_key) {
+            revoked_by_fp.insert(fp, r);
+        }
+    }
+
+    // Get committer date (NOT author date).
+    let ct_out = Command::new("git")
+        .args(["show", "-s", "--format=%ct", commit])
+        .output()
+        .context("git show committer date")?;
+    let committer_ts: i64 = String::from_utf8_lossy(&ct_out.stdout)
+        .trim()
+        .parse()
+        .context("parse committer timestamp")?;
+
+    // Check revocation FIRST (revoked entries may not be in devices anymore).
+    if let Some(r) = revoked_by_fp.get(&signing_fp) {
+        if committer_ts >= r.revoked_at {
+            eprintln!(
+                "REJECT: commit {commit} — signed by revoked device '{}' \
+                 (committer ts {committer_ts} >= revoked_at {})",
+                r.name, r.revoked_at
+            );
+            std::process::exit(1);
+        }
+        // Historical commit: committer_ts < revoked_at → was valid when signed.
+        eprintln!(
+            "OK: commit {commit} — historical commit signed by '{}' before revocation",
+            r.name
+        );
+        return Ok(());
+    }
+
+    // Not revoked — must be in active devices.
+    if !device_by_fp.contains_key(&signing_fp) {
+        eprintln!(
+            "REJECT: commit {commit} — signed by unregistered device (fingerprint {signing_fp})"
+        );
+        std::process::exit(1);
+    }
+
+    eprintln!("OK: commit {commit} verified (signed by '{}')", device_by_fp[&signing_fp].name);
+    Ok(())
+}
+
+fn generate_hook() -> Result<()> {
+    print!(
+        r#"#!/bin/bash
+# Relicario pre-receive hook -- verify all commits are signed by registered devices
+
+while read oldrev newrev refname; do
+  [ "$newrev" = "0000000000000000000000000000000000000000" ] && continue
+
+  if [ "$oldrev" = "0000000000000000000000000000000000000000" ]; then
+    commits=$(git rev-list "$newrev")
+  else
+    commits=$(git rev-list "$oldrev..$newrev")
+  fi
+
+  for commit in $commits; do
+    relicario-server verify-commit "$commit" || exit 1
+  done
+done
+"#
+    );
+    Ok(())
+}
+
+fn git_show(commit: &str, path: &str) -> Result<String> {
+    let output = Command::new("git")
+        .args(["show", &format!("{}:{}", commit, path)])
+        .output()
+        .context("git show")?;
+
+    if !output.status.success() {
+        anyhow::bail!("git show {}:{} failed", commit, path);
+    }
+
+    Ok(String::from_utf8(output.stdout)?)
+}

crates/relicario-server/tests/verify_commit.rs

@@ -0,0 +1,230 @@
+//! Acceptance tests for `relicario-server verify-commit`.
+//!
+//! Four scenarios from audit S1:
+//! 1. Registered non-revoked key → exit 0
+//! 2. Unregistered key → exit 1 (stderr contains "unregistered")
+//! 3. Revoked key, commit AFTER revoked_at → exit 1 (stderr contains "revoked")
+//! 4. Revoked key, commit BEFORE revoked_at (historical) → exit 0
+
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+use assert_cmd::Command as AssertCommand;
+use predicates::prelude::*;
+use relicario_core::device::{generate_keypair, DeviceEntry, RevokedEntry};
+use tempfile::TempDir;
+
+fn write_keypair(dir: &Path, name: &str) -> (PathBuf, PathBuf, String) {
+    let (priv_pem, pub_line) = generate_keypair().expect("generate keypair");
+    let priv_path = dir.join(format!("{name}.key"));
+    let pub_path = dir.join(format!("{name}.pub"));
+    fs::write(&priv_path, priv_pem.as_str()).unwrap();
+    fs::write(&pub_path, &pub_line).unwrap();
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        fs::set_permissions(&priv_path, fs::Permissions::from_mode(0o600)).unwrap();
+    }
+    (priv_path, pub_path, pub_line)
+}
+
+fn git(repo: &Path, args: &[&str], extra_env: &[(&str, &str)]) {
+    let mut cmd = Command::new("git");
+    cmd.current_dir(repo).args(args);
+    for (k, v) in extra_env {
+        cmd.env(k, v);
+    }
+    let status = cmd.status().expect("spawn git");
+    assert!(status.success(), "git {args:?} failed");
+}
+
+fn init_repo(repo: &Path) {
+    git(repo, &["init", "-q", "-b", "main"], &[]);
+    git(repo, &["config", "user.email", "test@test"], &[]);
+    git(repo, &["config", "user.name", "test"], &[]);
+    git(repo, &["commit", "--allow-empty", "-q", "-m", "init"], &[]);
+}
+
+fn sign_commit(
+    repo: &Path,
+    signing_key: &Path,
+    allowed_signers: &Path,
+    committer_unix: i64,
+    msg: &str,
+    file_path: &str,
+    file_content: &str,
+) -> String {
+    fs::write(repo.join(file_path), file_content).unwrap();
+    git(repo, &["add", file_path], &[]);
+    let date = format!("@{committer_unix} +0000");
+    git(
+        repo,
+        &[
+            "-c", "gpg.format=ssh",
+            "-c", &format!("user.signingkey={}", signing_key.display()),
+            "-c", &format!("gpg.ssh.allowedSignersFile={}", allowed_signers.display()),
+            "commit", "-S", "-q", "-m", msg,
+        ],
+        &[
+            ("GIT_AUTHOR_DATE", &date),
+            ("GIT_COMMITTER_DATE", &date),
+        ],
+    );
+    let out = Command::new("git")
+        .current_dir(repo)
+        .args(["rev-parse", "HEAD"])
+        .output()
+        .unwrap();
+    String::from_utf8(out.stdout).unwrap().trim().to_string()
+}
+
+fn write_device_files(repo: &Path, devices: &[DeviceEntry], revoked: &[RevokedEntry]) {
+    let dir = repo.join(".relicario");
+    fs::create_dir_all(&dir).unwrap();
+    fs::write(dir.join("devices.json"), serde_json::to_string_pretty(devices).unwrap()).unwrap();
+    fs::write(dir.join("revoked.json"), serde_json::to_string_pretty(revoked).unwrap()).unwrap();
+    git(repo, &["add", ".relicario"], &[]);
+    git(repo, &["commit", "-q", "-m", "device files"], &[]);
+}
+
+#[test]
+fn registered_non_revoked_key_accepted() {
+    let tmp = TempDir::new().unwrap();
+    let repo = tmp.path();
+    init_repo(repo);
+
+    let (priv_a, _, pub_a) = write_keypair(repo, "alice");
+    write_device_files(
+        repo,
+        &[DeviceEntry {
+            name: "alice".into(),
+            public_key: pub_a.clone(),
+            added_at: 1_700_000_000,
+            added_by: "bootstrap".into(),
+        }],
+        &[],
+    );
+
+    let allowed = repo.join("test_allowed_signers");
+    fs::write(&allowed, format!("relicario {}\n", pub_a.trim())).unwrap();
+
+    let sha = sign_commit(repo, &priv_a, &allowed, 1_710_000_000, "x", "a.txt", "hi");
+
+    AssertCommand::cargo_bin("relicario-server")
+        .unwrap()
+        .current_dir(repo)
+        .args(["verify-commit", &sha])
+        .assert()
+        .success();
+}
+
+#[test]
+fn unregistered_key_rejected() {
+    let tmp = TempDir::new().unwrap();
+    let repo = tmp.path();
+    init_repo(repo);
+
+    let (_, _, pub_a) = write_keypair(repo, "alice");
+    let (priv_evil, _, pub_evil) = write_keypair(repo, "evil");
+
+    // Only Alice is registered.
+    write_device_files(
+        repo,
+        &[DeviceEntry {
+            name: "alice".into(),
+            public_key: pub_a.clone(),
+            added_at: 1_700_000_000,
+            added_by: "bootstrap".into(),
+        }],
+        &[],
+    );
+
+    // Evil signs against a file containing both keys so git commit signing works,
+    // but the binary's allowed-signers (from devices.json) only has Alice.
+    let allowed = repo.join("test_allowed_signers");
+    fs::write(
+        &allowed,
+        format!("relicario {}\nrelicario {}\n", pub_a.trim(), pub_evil.trim()),
+    )
+    .unwrap();
+
+    let sha = sign_commit(repo, &priv_evil, &allowed, 1_710_000_000, "evil", "a.txt", "hi");
+
+    AssertCommand::cargo_bin("relicario-server")
+        .unwrap()
+        .current_dir(repo)
+        .args(["verify-commit", &sha])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("unregistered"));
+}
+
+#[test]
+fn revoked_key_after_revoked_at_rejected() {
+    let tmp = TempDir::new().unwrap();
+    let repo = tmp.path();
+    init_repo(repo);
+
+    let (priv_a, _, pub_a) = write_keypair(repo, "alice");
+
+    // Alice's entry is only in revoked.json (was removed from devices.json after revocation).
+    write_device_files(
+        repo,
+        &[],
+        &[RevokedEntry {
+            name: "alice".into(),
+            public_key: pub_a.clone(),
+            revoked_at: 1_705_000_000,
+            revoked_by: "admin".into(),
+        }],
+    );
+
+    let allowed = repo.join("test_allowed_signers");
+    fs::write(&allowed, format!("relicario {}\n", pub_a.trim())).unwrap();
+
+    // Commit dated AFTER revocation.
+    let sha = sign_commit(repo, &priv_a, &allowed, 1_710_000_000, "post", "a.txt", "hi");
+
+    AssertCommand::cargo_bin("relicario-server")
+        .unwrap()
+        .current_dir(repo)
+        .args(["verify-commit", &sha])
+        .assert()
+        .failure()
+        .stderr(predicate::str::contains("revoked"));
+}
+
+#[test]
+fn revoked_key_before_revoked_at_accepted_historical() {
+    let tmp = TempDir::new().unwrap();
+    let repo = tmp.path();
+    init_repo(repo);
+
+    let (priv_a, _, pub_a) = write_keypair(repo, "alice");
+
+    // Same as above: Alice only in revoked.json.
+    write_device_files(
+        repo,
+        &[],
+        &[RevokedEntry {
+            name: "alice".into(),
+            public_key: pub_a.clone(),
+            revoked_at: 1_705_000_000,
+            revoked_by: "admin".into(),
+        }],
+    );
+
+    let allowed = repo.join("test_allowed_signers");
+    fs::write(&allowed, format!("relicario {}\n", pub_a.trim())).unwrap();
+
+    // Commit dated BEFORE revocation -- historical case must pass.
+    let sha = sign_commit(repo, &priv_a, &allowed, 1_700_000_000, "historical", "a.txt", "hi");
+
+    AssertCommand::cargo_bin("relicario-server")
+        .unwrap()
+        .current_dir(repo)
+        .args(["verify-commit", &sha])
+        .assert()
+        .success();
+}

crates/relicario-wasm/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "relicario-wasm"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 description = "WASM bindings for relicario password manager"
 
@@ -15,6 +15,11 @@ serde_json = "1"
 serde = { version = "1", features = ["derive"] }
 zeroize = "1"
 getrandom = { version = "0.2", features = ["js"] }
+ed25519-dalek = { version = "2", features = ["rand_core"] }
+base64 = "0.22"
+hex = "0.4"
+rand = "0.8"
+once_cell = "1"
 
 [dev-dependencies]
 wasm-bindgen-test = "0.3"

crates/relicario-wasm/src/device.rs

@@ -0,0 +1,71 @@
+//! WASM device key management -- private keys never cross to JS.
+
+use std::sync::Mutex;
+
+use once_cell::sync::Lazy;
+use zeroize::Zeroizing;
+
+use relicario_core::device as core_device;
+
+/// In-memory device key storage (private keys held in WASM linear memory).
+static DEVICE_STATE: Lazy<Mutex<Option<DeviceState>>> = Lazy::new(|| Mutex::new(None));
+
+struct DeviceState {
+    name: String,
+    signing_private: Zeroizing<String>,
+    signing_public: String,
+    /// Deploy key stored for future SSH git operations; not yet used for signing.
+    #[allow(dead_code)]
+    deploy_private: Zeroizing<String>,
+    deploy_public: String,
+}
+
+/// Register a new device, storing the keypairs internally and returning
+/// only the public keys. Private keys never leave WASM memory.
+pub fn register_device(name: &str) -> Result<(String, String), String> {
+    let (signing_priv, signing_pub) =
+        core_device::generate_keypair().map_err(|e| e.to_string())?;
+    let (deploy_priv, deploy_pub) =
+        core_device::generate_keypair().map_err(|e| e.to_string())?;
+
+    let state = DeviceState {
+        name: name.to_string(),
+        signing_private: signing_priv,
+        signing_public: signing_pub.clone(),
+        deploy_private: deploy_priv,
+        deploy_public: deploy_pub.clone(),
+    };
+
+    *DEVICE_STATE.lock().unwrap() = Some(state);
+
+    Ok((signing_pub, deploy_pub))
+}
+
+/// Sign `data` using the registered device's signing key.
+/// Returns a base64-encoded signature.
+pub fn sign_for_git(data: &[u8]) -> Result<String, String> {
+    let guard = DEVICE_STATE.lock().unwrap();
+    let state = guard
+        .as_ref()
+        .ok_or_else(|| "no device registered".to_string())?;
+
+    core_device::sign(&state.signing_private, data).map_err(|e| e.to_string())
+}
+
+/// Return current device info: (name, signing_public_key, deploy_public_key).
+/// Returns None if no device has been registered in this session.
+pub fn get_device_info() -> Option<(String, String, String)> {
+    let guard = DEVICE_STATE.lock().unwrap();
+    guard.as_ref().map(|s| {
+        (
+            s.name.clone(),
+            s.signing_public.clone(),
+            s.deploy_public.clone(),
+        )
+    })
+}
+
+/// Clear device state (call on logout or before re-registration).
+pub fn clear_device() {
+    *DEVICE_STATE.lock().unwrap() = None;
+}

crates/relicario-wasm/src/lib.rs

@@ -5,8 +5,10 @@
 //! looked up per call via a u32 handle. JS cannot read key bytes.
 
 mod session;
+mod device;
 
 use wasm_bindgen::prelude::*;
+use zeroize::Zeroizing;
 
 use relicario_core::{derive_master_key, imgsecret, KdfParams};
 
@@ -35,7 +37,8 @@ pub fn unlock(
         .map_err(|_| JsError::new("salt must be exactly 32 bytes"))?;
     let master_key = derive_master_key(passphrase.as_bytes(), &image_secret, salt_arr, &params)
         .map_err(|e| JsError::new(&e.to_string()))?;
-    let handle = session::insert(master_key);
+    let stored_secret = Zeroizing::new(image_secret);
+    let handle = session::insert(master_key, stored_secret);
     Ok(SessionHandle(handle))
 }
 
@@ -120,6 +123,16 @@ pub fn settings_encrypt(handle: &SessionHandle, settings_json: &str) -> Result<V
         .map_err(|e| JsError::new(&e.to_string()))
 }
 
+/// Returns the JSON for `VaultSettings::default()`. Used by the setup
+/// wizard to encrypt and write a default settings.enc on new-vault setup.
+/// Keeping this in WASM (instead of hand-encoding in TS) prevents drift
+/// when the default VaultSettings shape changes in Rust.
+#[wasm_bindgen]
+pub fn default_vault_settings_json() -> Result<String, JsError> {
+    let s = VaultSettings::default();
+    serde_json::to_string(&s).map_err(|e| JsError::new(&e.to_string()))
+}
+
 // ── Task 20: attachment / generator / imgsecret / ID / TOTP bridges ─────────
 
 use relicario_core::{decrypt_attachment, encrypt_attachment, FieldId, ItemId};
@@ -196,6 +209,91 @@ pub fn rate_passphrase(p: &str) -> Result<JsValue, JsError> {
     }))
 }
 
+/// Register a new device, generating ed25519 keypairs for signing and deploy.
+/// Returns JSON: { "signing_public_key": "ssh-ed25519 ...", "deploy_public_key": "ssh-ed25519 ..." }
+/// Private keys are kept internal to WASM and never cross to JS.
+#[wasm_bindgen]
+pub fn register_device(name: &str) -> Result<JsValue, JsError> {
+    let (signing_pub, deploy_pub) =
+        device::register_device(name).map_err(|e| JsError::new(&e))?;
+
+    js_value_for(&serde_json::json!({
+        "signing_public_key": signing_pub,
+        "deploy_public_key": deploy_pub,
+    }))
+}
+
+/// Sign `data` using the registered device's signing key.
+/// Returns JSON: { "signature": "<base64>" }
+/// Errors if no device has been registered via register_device().
+#[wasm_bindgen]
+pub fn sign_for_git(data: &[u8]) -> Result<JsValue, JsError> {
+    let signature = device::sign_for_git(data).map_err(|e| JsError::new(&e))?;
+
+    js_value_for(&serde_json::json!({
+        "signature": signature,
+    }))
+}
+
+/// Get the current device's name and public keys.
+/// Returns JSON: { "name": "...", "signing_public_key": "...", "deploy_public_key": "..." }
+/// Returns null if no device is registered in this session.
+#[wasm_bindgen]
+pub fn get_device_info() -> Result<JsValue, JsError> {
+    match device::get_device_info() {
+        Some((name, signing_pub, deploy_pub)) => js_value_for(&serde_json::json!({
+            "name": name,
+            "signing_public_key": signing_pub,
+            "deploy_public_key": deploy_pub,
+        })),
+        None => Ok(JsValue::NULL),
+    }
+}
+
+/// Clear the in-memory device state (call on logout or before re-registration).
+#[wasm_bindgen]
+pub fn clear_device() {
+    device::clear_device();
+}
+
+/// Extract field history from a decrypted item JSON.
+/// Returns JSON array of { field_id, field_name, current_value, entries: [{ value, changed_at }] }
+#[wasm_bindgen]
+pub fn get_field_history(item_json: &str) -> Result<JsValue, JsError> {
+    let item: Item = serde_json::from_str(item_json)
+        .map_err(|e| JsError::new(&format!("item json: {e}")))?;
+
+    let mut results = Vec::new();
+
+    // Only section fields are tracked in field_history (set_field_value operates on sections).
+    for section in &item.sections {
+        for field in &section.fields {
+            if field.value.is_history_tracked() {
+                if let Some(entries) = item.field_history.get(&field.id) {
+                    if !entries.is_empty() {
+                        let current = match &field.value {
+                            relicario_core::FieldValue::Password(v) => v.as_str().to_owned(),
+                            relicario_core::FieldValue::Concealed(v) => v.as_str().to_owned(),
+                            _ => String::new(),
+                        };
+                        results.push(serde_json::json!({
+                            "field_id": field.id.as_str(),
+                            "field_name": &field.label,
+                            "current_value": current,
+                            "entries": entries.iter().map(|e| serde_json::json!({
+                                "value": e.value.as_str(),
+                                "changed_at": e.replaced_at,
+                            })).collect::<Vec<_>>(),
+                        }));
+                    }
+                }
+            }
+        }
+    }
+
+    js_value_for(&results)
+}
+
 #[wasm_bindgen]
 pub fn extract_image_secret(image_bytes: &[u8]) -> Result<Vec<u8>, JsError> {
     let s = imgsecret::extract(image_bytes).map_err(|e| JsError::new(&e.to_string()))?;
@@ -237,6 +335,190 @@ pub fn totp_compute(
     Ok(TotpCode { code, expires_at })
 }
 
+// ── Backup container bridge ─────────────────────────────────────────────────
+
+use base64::Engine;
+
+use relicario_core::backup::{
+    pack_backup as core_pack_backup,
+    unpack_backup as core_unpack_backup,
+    BackupInput, BackupItem, BackupAttachment,
+};
+
+/// Pack a vault into a `.relbak` byte vector.
+///
+/// `input_json` shape:
+/// ```json
+/// {
+///   "salt": "<base64>",
+///   "params_json": "...",
+///   "devices_json": "...",
+///   "manifest_enc": "<base64>",
+///   "settings_enc": "<base64>",
+///   "items": [{"id": "<hex>", "ciphertext": "<base64>"}, ...],
+///   "attachments": [{"item_id": "<hex>", "attachment_id": "<hex>", "ciphertext": "<base64>"}, ...],
+///   "reference_jpg": "<base64>" | null,
+///   "git_archive": "<base64>" | null
+/// }
+/// ```
+#[wasm_bindgen]
+pub fn pack_backup_json(input_json: &str, passphrase: &str) -> Result<Vec<u8>, JsError> {
+    #[derive(serde::Deserialize)]
+    struct InJson {
+        salt: String,
+        params_json: String,
+        devices_json: String,
+        manifest_enc: String,
+        settings_enc: String,
+        items: Vec<InItem>,
+        attachments: Vec<InAttachment>,
+        reference_jpg: Option<String>,
+        git_archive: Option<String>,
+    }
+    #[derive(serde::Deserialize)]
+    struct InItem { id: String, ciphertext: String }
+    #[derive(serde::Deserialize)]
+    struct InAttachment { item_id: String, attachment_id: String, ciphertext: String }
+
+    let parsed: InJson = serde_json::from_str(input_json)
+        .map_err(|e| JsError::new(&format!("backup input: {e}")))?;
+
+    let b64 = base64::engine::general_purpose::STANDARD;
+    let salt = b64.decode(&parsed.salt).map_err(|e| JsError::new(&e.to_string()))?;
+    let manifest = b64.decode(&parsed.manifest_enc).map_err(|e| JsError::new(&e.to_string()))?;
+    let settings = b64.decode(&parsed.settings_enc).map_err(|e| JsError::new(&e.to_string()))?;
+    let items_bytes: Vec<(String, Vec<u8>)> = parsed.items.iter()
+        .map(|i| {
+            let ct = b64.decode(&i.ciphertext).map_err(|e| JsError::new(&e.to_string()))?;
+            Ok((i.id.clone(), ct))
+        })
+        .collect::<Result<Vec<_>, JsError>>()?;
+    let attach_bytes: Vec<(String, String, Vec<u8>)> = parsed.attachments.iter()
+        .map(|a| {
+            let ct = b64.decode(&a.ciphertext).map_err(|e| JsError::new(&e.to_string()))?;
+            Ok((a.item_id.clone(), a.attachment_id.clone(), ct))
+        })
+        .collect::<Result<Vec<_>, JsError>>()?;
+
+    let ref_bytes = parsed.reference_jpg.as_deref()
+        .map(|s| b64.decode(s))
+        .transpose()
+        .map_err(|e| JsError::new(&e.to_string()))?;
+    let git_bytes = parsed.git_archive.as_deref()
+        .map(|s| b64.decode(s))
+        .transpose()
+        .map_err(|e| JsError::new(&e.to_string()))?;
+
+    let items_refs: Vec<BackupItem> = items_bytes.iter()
+        .map(|(id, ct)| BackupItem { id: id.clone(), ciphertext: ct })
+        .collect();
+    let attach_refs: Vec<BackupAttachment> = attach_bytes.iter()
+        .map(|(iid, aid, ct)| BackupAttachment {
+            item_id: iid.clone(),
+            attachment_id: aid.clone(),
+            ciphertext: ct,
+        })
+        .collect();
+
+    let input = BackupInput {
+        salt: &salt,
+        params_json: &parsed.params_json,
+        devices_json: &parsed.devices_json,
+        manifest_enc: &manifest,
+        settings_enc: &settings,
+        items: items_refs,
+        attachments: attach_refs,
+        reference_jpg: ref_bytes.as_deref(),
+        git_archive: git_bytes.as_deref(),
+    };
+    core_pack_backup(input, passphrase).map_err(|e| JsError::new(&e.to_string()))
+}
+
+/// Unpack `.relbak` bytes; returns the JSON shape that mirrors `BackupOutput`,
+/// with binary fields base64-encoded.
+#[wasm_bindgen]
+pub fn unpack_backup_json(bytes: &[u8], passphrase: &str) -> Result<String, JsError> {
+    let out = core_unpack_backup(bytes, passphrase)
+        .map_err(|e| JsError::new(&e.to_string()))?;
+
+    let b64 = base64::engine::general_purpose::STANDARD;
+    let json = serde_json::json!({
+        "salt": b64.encode(out.salt),
+        "params_json": out.params_json,
+        "devices_json": out.devices_json,
+        "manifest_enc": b64.encode(&out.manifest_enc),
+        "settings_enc": b64.encode(&out.settings_enc),
+        "items": out.items.iter().map(|i| serde_json::json!({
+            "id": i.id,
+            "ciphertext": b64.encode(&i.ciphertext),
+        })).collect::<Vec<_>>(),
+        "attachments": out.attachments.iter().map(|a| serde_json::json!({
+            "item_id": a.item_id,
+            "attachment_id": a.attachment_id,
+            "ciphertext": b64.encode(&a.ciphertext),
+        })).collect::<Vec<_>>(),
+        "reference_jpg": out.reference_jpg.as_ref().map(|b| b64.encode(b)),
+        "git_archive": out.git_archive.as_ref().map(|b| b64.encode(b)),
+        "created_at": out.created_at,
+    });
+    Ok(json.to_string())
+}
+
+// ── LastPass CSV importer bridge ────────────────────────────────────────────
+
+use relicario_core::import_lastpass::parse_lastpass_csv as core_parse_lastpass_csv;
+
+/// Parse a LastPass CSV into `{ items: [Item], warnings: [ImportWarning] }`.
+///
+/// Items are returned as full `Item` JSON objects with freshly-minted IDs
+/// and timestamps already populated. The SW caller is responsible for
+/// encrypting + writing them; this bridge stays pure so the preview UI
+/// can render counts without committing anything.
+#[wasm_bindgen]
+pub fn parse_lastpass_csv_json(csv_bytes: &[u8]) -> Result<String, JsError> {
+    let (items, warnings) = core_parse_lastpass_csv(csv_bytes)
+        .map_err(|e| JsError::new(&e.to_string()))?;
+
+    let json = serde_json::json!({
+        "items": items,
+        "warnings": warnings,
+    });
+    Ok(json.to_string())
+}
+
+// ── Recovery QR bindings ─────────────────────────────────────────────────────
+
+use relicario_core::{generate_recovery_qr, recovery_qr_to_svg, unwrap_recovery_qr};
+
+/// Generate a recovery QR SVG for the current session.
+/// Returns the SVG string. The passphrase wraps the image_secret under a
+/// separate key (domain-separated from the master key derivation).
+#[wasm_bindgen]
+pub fn wasm_generate_recovery_qr(
+    handle: &SessionHandle,
+    passphrase: &str,
+) -> Result<String, JsError> {
+    let payload = session::with_image_secret(handle.0, |s| generate_recovery_qr(passphrase, s))
+        .ok_or_else(|| JsError::new("invalid or locked session handle"))?
+        .map_err(|e| JsError::new(&e.to_string()))?;
+    Ok(recovery_qr_to_svg(&payload))
+}
+
+/// Unwrap a recovery QR payload (base64-encoded 109-byte blob) using the passphrase.
+/// Returns the raw image_secret bytes (32 bytes).
+#[wasm_bindgen]
+pub fn wasm_unwrap_recovery_qr(
+    payload_b64: &str,
+    passphrase: &str,
+) -> Result<Vec<u8>, JsError> {
+    use base64::{engine::general_purpose::STANDARD, Engine};
+    let bytes = STANDARD.decode(payload_b64)
+        .map_err(|e| JsError::new(&format!("base64: {e}")))?;
+    let recovered = unwrap_recovery_qr(&bytes, passphrase)
+        .map_err(|e| JsError::new(&e.to_string()))?;
+    Ok(recovered.to_vec())
+}
+
 #[cfg(test)]
 mod session_tests {
     use super::*;
@@ -245,7 +527,7 @@ mod session_tests {
     #[test]
     fn insert_then_remove_clears_entry() {
         session::clear();
-        let h = session::insert(Zeroizing::new([0x11u8; 32]));
+        let h = session::insert(Zeroizing::new([0x11u8; 32]), Zeroizing::new([0u8; 32]));
         assert_ne!(h, 0);
         assert!(session::remove(h));
         assert!(!session::remove(h));   // second remove false
@@ -254,7 +536,7 @@ mod session_tests {
     #[test]
     fn with_yields_key_only_while_session_lives() {
         session::clear();
-        let h = session::insert(Zeroizing::new([0x22u8; 32]));
+        let h = session::insert(Zeroizing::new([0x22u8; 32]), Zeroizing::new([0u8; 32]));
         let byte = session::with(h, |k| k[0]);
         assert_eq!(byte, Some(0x22));
         session::remove(h);
@@ -266,7 +548,7 @@ mod session_tests {
     fn manifest_round_trip_via_handle() {
         use relicario_core::{Manifest, decrypt_manifest};
         session::clear();
-        let h = session::insert(Zeroizing::new([0x55u8; 32]));
+        let h = session::insert(Zeroizing::new([0x55u8; 32]), Zeroizing::new([0u8; 32]));
         let handle = SessionHandle(h);
         let key = Zeroizing::new([0x55u8; 32]);
         let empty = Manifest::new();
@@ -279,4 +561,31 @@ mod session_tests {
         let bytes2 = manifest_encrypt(&handle, &serde_json::to_string(&empty).unwrap()).unwrap();
         assert_ne!(bytes, bytes2, "nonces must differ");
     }
+
+    #[test]
+    fn parse_lastpass_csv_json_returns_items_and_warnings() {
+        // Row 1 imports cleanly; row 2 has an empty `name` and is skipped
+        // with a warning.
+        let csv = "url,username,password,totp,extra,name,grouping,fav\n\
+                   https://x,alice,hunter2,,,GitHub,Work,1\n\
+                   https://y,bob,hunter2,,,,,";
+        let json = super::parse_lastpass_csv_json(csv.as_bytes()).unwrap();
+        let v: serde_json::Value = serde_json::from_str(&json).unwrap();
+        assert_eq!(v["items"].as_array().unwrap().len(), 1);
+        assert_eq!(v["warnings"].as_array().unwrap().len(), 1);
+        assert!(v["warnings"][0]["message"].as_str().unwrap().contains("name"));
+        // The item's title round-trips as a plain JSON string.
+        assert_eq!(v["items"][0]["title"].as_str().unwrap(), "GitHub");
+    }
+
+    #[test]
+    fn parse_lastpass_csv_json_propagates_header_errors() {
+        // Test the underlying core function directly since native tests
+        // can't call wasm_bindgen functions.
+        use relicario_core::import_lastpass::parse_lastpass_csv;
+        let bad = "name,user,pass\nA,u,p\n";
+        let err = parse_lastpass_csv(bad.as_bytes());
+        // Should fail with a header validation error.
+        assert!(err.is_err());
+    }
 }

crates/relicario-wasm/src/session.rs

@@ -6,12 +6,17 @@ use std::cell::RefCell;
 use std::collections::HashMap;
 use zeroize::Zeroizing;
 
+pub struct SessionData {
+    pub master_key: Zeroizing<[u8; 32]>,
+    pub image_secret: Zeroizing<[u8; 32]>,
+}
+
 thread_local! {
-    static SESSIONS: RefCell<HashMap<u32, Zeroizing<[u8; 32]>>> = RefCell::new(HashMap::new());
+    static SESSIONS: RefCell<HashMap<u32, SessionData>> = RefCell::new(HashMap::new());
     static NEXT_HANDLE: RefCell<u32> = const { RefCell::new(1) };
 }
 
-pub fn insert(key: Zeroizing<[u8; 32]>) -> u32 {
+pub fn insert(master_key: Zeroizing<[u8; 32]>, image_secret: Zeroizing<[u8; 32]>) -> u32 {
     let handle = NEXT_HANDLE.with(|n| {
         let mut n = n.borrow_mut();
         let h = *n;
@@ -19,15 +24,26 @@ pub fn insert(key: Zeroizing<[u8; 32]>) -> u32 {
         if *n == 0 { *n = 1; } // avoid reserving 0 as a valid handle
         h
     });
-    SESSIONS.with(|s| { s.borrow_mut().insert(handle, key); });
+    SESSIONS.with(|s| {
+        s.borrow_mut().insert(handle, SessionData { master_key, image_secret });
+    });
     handle
 }
 
+/// Access the master key for a handle. Preserves original `with` signature for all existing callers.
 pub fn with<F, R>(handle: u32, f: F) -> Option<R>
 where
     F: FnOnce(&Zeroizing<[u8; 32]>) -> R,
 {
-    SESSIONS.with(|s| s.borrow().get(&handle).map(f))
+    SESSIONS.with(|s| s.borrow().get(&handle).map(|d| f(&d.master_key)))
+}
+
+/// Access the image_secret for a handle (used by recovery QR).
+pub fn with_image_secret<F, R>(handle: u32, f: F) -> Option<R>
+where
+    F: FnOnce(&Zeroizing<[u8; 32]>) -> R,
+{
+    SESSIONS.with(|s| s.borrow().get(&handle).map(|d| f(&d.image_secret)))
 }
 
 pub fn remove(handle: u32) -> bool {

docs/ARCHITECTURE.md

@@ -1,4 +1,4 @@
-# relicario — Architecture
+# Relicario — Architecture
 
 ## System Overview
 
@@ -42,15 +42,19 @@
 ┌──────────────────────────────────────────────────────────────────┐
 │                     GIT SERVER (untrusted)                        │
 │                                                                   │
-│  relicario-vault.git/                                                │
-│  ├── manifest.enc        ← opaque ciphertext                     │
-│  ├── entries/                                                     │
-│  │   ├── a1b2c3d4.enc   ← opaque ciphertext                     │
-│  │   └── e5f6a7b8.enc   ← opaque ciphertext                     │
-│  └── .relicario/                                                     │
+│  relicario-vault.git/                                             │
+│  ├── manifest.enc        ← opaque ciphertext                      │
+│  ├── settings.enc        ← opaque ciphertext                      │
+│  ├── items/                                                       │
+│  │   ├── a1b2c3d4e5f6a7b8.enc   ← opaque ciphertext               │
+│  │   └── …                                                        │
+│  ├── attachments/                                                 │
+│  │   └── <item-id>/<aid>.enc    ← opaque ciphertext               │
+│  └── .relicario/                                                  │
 │      ├── salt            ← 32 bytes (not secret)                  │
 │      ├── params.json     ← KDF params (not secret)                │
-│      └── devices.json    ← device public keys (not secret)        │
+│      ├── devices.json    ← device public keys (not secret)        │
+│      └── revoked.json    ← revoked device records (not secret)    │
 │                                                                   │
 │  The server sees NOTHING useful. No keys, no plaintext,           │
 │  no metadata about what's inside.                                 │
@@ -79,8 +83,9 @@ vault_salt ────────►│                  │
 
                     ┌──────────────────┐
 master_key ────────►│  XChaCha20-      │──────► manifest.enc
-empty manifest ────►│  Poly1305        │
-                    └──────────────────┘
+empty manifest ────►│  Poly1305        │        settings.enc
+default settings ──►│  encrypt (×2)    │        (parallel artifacts;
+                    └──────────────────┘         independent nonces)
 
                     ┌──────────────────┐
                     │  git init        │──────► vault repo
@@ -88,6 +93,14 @@ empty manifest ────►│  Poly1305        │
                     └──────────────────┘
 ```
 
+Item creation, the typed-item envelope (`Item` + per-type `ItemCore`),
+attachment encryption, and field-history tracking are not shown above —
+they are described in [`crates/relicario-core/ARCHITECTURE.md`](../crates/relicario-core/ARCHITECTURE.md).
+The flow above covers only the crypto-pipeline shape that vault init
+establishes; the per-item lifecycle reuses the same `master_key` +
+XChaCha20-Poly1305 primitives against `items/<id>.enc` and
+`attachments/<item-id>/<aid>.enc`.
+
 ## Unlock Flow (every vault operation)
 
 ```
@@ -217,21 +230,23 @@ Input JPEG (possibly re-encoded or cropped)
                        │ uses
                        ▼
 ┌────────────────────────────────────────────────────────────┐
-│                    relicario-core                              │
+│                    relicario-core                           │
 │  Platform-agnostic: bytes in, bytes out                     │
 │  No filesystem, no network, no git                          │
 │                                                             │
-│  ┌──────────┐  ┌──────────┐  ┌─────────┐  ┌────────────┐  │
-│  │ crypto   │  │ imgsecret│  │ entry   │  │ vault      │  │
-│  │          │  │          │  │         │  │            │  │
-│  │ KDF      │  │ DCT      │  │ Entry   │  │ encrypt_   │  │
-│  │ encrypt  │  │ embed    │  │ Manifest│  │ entry()    │  │
-│  │ decrypt  │  │ extract  │  │ search  │  │ decrypt_   │  │
-│  │          │  │ QIM      │  │         │  │ manifest() │  │
-│  └──────────┘  └──────────┘  └─────────┘  └────────────┘  │
+│  ┌──────────┐  ┌──────────┐  ┌─────────┐  ┌────────────┐   │
+│  │ crypto   │  │ imgsecret│  │ item +  │  │ vault      │   │
+│  │          │  │          │  │ types   │  │            │   │
+│  │ KDF      │  │ DCT      │  │ Item    │  │ encrypt_   │   │
+│  │ encrypt  │  │ embed    │  │ Manifest│  │ item()     │   │
+│  │ decrypt  │  │ extract  │  │ Settings│  │ decrypt_   │   │
+│  │          │  │ QIM      │  │ Backup  │  │ manifest() │   │
+│  │          │  │          │  │ Device  │  │ ...        │   │
+│  └──────────┘  └──────────┘  └─────────┘  └────────────┘   │
 │                                                             │
-│  Future: relicario-wasm wraps this for browser extension       │
-│  Future: JNI/Swift wrappers for Android/iOS                 │
+│  Consumed by: relicario-cli, relicario-wasm (extension),    │
+│               relicario-server (pre-receive hook).          │
+│  Future: JNI/Swift wrappers for Android/iOS.                │
 └────────────────────────────────────────────────────────────┘
 ```
 

docs/SECURITY.md

@@ -0,0 +1,104 @@
+# Relicario Security Model
+
+## Cryptographic Protection
+
+Relicario uses two-factor vault decryption:
+1. **Passphrase** — user-memorized, zxcvbn score ≥3 required
+2. **Reference image** — JPEG carrying 256-bit secret via DCT steganography
+
+Key derivation: Argon2id (64 MiB memory, 3 iterations, 4 parallelism)
+Encryption: XChaCha20-Poly1305 (192-bit nonce, 256-bit key)
+
+## Manifest Integrity
+
+The manifest (`manifest.enc`) is encrypted with AEAD, which provides:
+
+- **Confidentiality**: Contents unreadable without master key
+- **Integrity**: Any modification detected and rejected on decrypt
+- **Authenticity**: Only master key holders can create valid ciphertexts
+
+### What AEAD Does NOT Protect
+
+- **Item deletion**: An attacker with write access can delete `.enc` files
+  or git-revert commits. The manifest decrypts successfully but won't
+  contain the deleted items.
+
+- **Rollback attacks**: An attacker can replace `manifest.enc` with an
+  older valid version. AEAD accepts any ciphertext created with the key.
+
+### Mitigation
+
+Item deletion and rollback are detectable via **git history**:
+
+```bash
+git log --oneline items/
+```
+
+For environments where git history could be rewritten (force-push):
+
+1. Enable device authentication (commit signing + pre-receive hook)
+2. Use a git server that rejects non-fast-forward pushes
+3. Regular backups with `relicario backup export`
+
+## Device Authentication
+
+When enabled, device authentication provides:
+
+- **Commit authorship**: All commits signed by registered device keys
+- **Push access control**: Deploy keys managed via Gitea API
+- **Instant revocation**: One command cuts off both signing and push
+
+Enforcement requires deploying the `relicario-server` pre-receive hook
+on the vault remote. The crate provides two subcommands:
+
+- `relicario-server generate-hook` — emits the hook script to install at
+  `<repo>/hooks/pre-receive`
+- `relicario-server verify-commit <sha>` — checks one commit's signature
+  against `.relicario/devices.json` and `.relicario/revoked.json` as of
+  that commit; the hook calls this for every pushed ref
+
+Without the server hook, signed commits provide authorship metadata only
+— any process with push access can land an unsigned commit, since
+verification is otherwise advisory.
+
+See `docs/superpowers/specs/2026-05-02-device-authentication-design.md`.
+
+## Access Control
+
+Without device authentication, access control is transport-layer only:
+
+- **CLI**: SSH key authentication to git remote
+- **Extension**: Git credentials in browser storage
+
+Device registration is optional but recommended for shared vaults.
+
+## Configuration env vars
+
+Relicario reads the following environment variables. Each is a trust
+boundary: an attacker who can set them in the user's environment can
+influence Relicario's behavior. They are listed here for security
+reviewers to audit the surface in one place.
+
+### User-facing (active in all builds)
+
+| Variable | Purpose | Trust |
+|---|---|---|
+| `RELICARIO_IMAGE` | Override the reference-image JPEG path used during vault unlock. | Trusted: filesystem path under the user's control. Read-only; its bytes feed `imgsecret::extract_secret`. |
+| `RELICARIO_GITEA_URL` | Gitea API base URL for `relicario device add`. Equivalent to `--gitea-url`. | Trusted: HTTPS URL. Used only in the device-add code path. |
+| `RELICARIO_GITEA_TOKEN` | Gitea personal-access token. Equivalent to `--gitea-token`. | **Secret**: anyone who can read this env var can manage the user's deploy keys via the Gitea API. The CLI never logs it. |
+| `RELICARIO_GITEA_OWNER` | Gitea repository owner (e.g. `alee`). Equivalent to `--owner`. | Trusted: opaque string. |
+| `RELICARIO_GITEA_REPO` | Gitea repository name (e.g. `vault`). Equivalent to `--repo`. | Trusted: opaque string. |
+
+### Debug-only (compiled out of `cargo build --release`)
+
+The following variables are gated behind `cfg(debug_assertions)` and
+are **no-ops** in release builds. The env-var lookup is removed by the
+optimiser from any binary built without debug assertions (i.e. the
+standard `--release` profile).
+
+| Variable | Purpose |
+|---|---|
+| `RELICARIO_NO_GROUPS_CACHE` | Suppress the plaintext `groups.cache` write. Developer debugging tool for the cache logic. |
+| `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. |

docs/architecture/overview.md

@@ -0,0 +1,213 @@
+# Architecture overview — Relicario
+
+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)
+>
+> If you want historical *why*, see `docs/superpowers/specs/` — those are time-stamped decision artifacts. This overview describes what *is*.
+
+## The four codebases
+
+```
+                          ┌─────────────────────┐
+                          │  relicario-core     │
+                          │  (Rust, no I/O)     │
+                          │  crypto · items     │
+                          │  manifest · stego   │
+                          │  device keys + fp   │
+                          └──┬───────────┬──────┘
+                             │           │
+            ┌────────────────┼───────────┴──────┬────────────────────┐
+            │                │                  │                    │
+            ▼                ▼                  ▼                    ▼
+   ┌────────────────┐ ┌──────────────────┐ ┌────────────────────┐
+   │ relicario-cli  │ │ relicario-server │ │  relicario-wasm    │
+   │ (Rust binary)  │ │ (Rust binary)    │ │  (#[wasm_bindgen]  │
+   │                │ │                  │ │   bindings)        │
+   │ filesystem +   │ │ pre-receive hook │ │                    │
+   │ git +          │ │ verify-commit  + │ │  compiled to WASM  │
+   │ clap UX        │ │ generate-hook    │ │  for the extension │
+   └────────────────┘ └──────────────────┘ └──────────┬─────────┘
+                                                      │
+                                                      ▼
+                                           ┌─────────────────────┐
+                                           │  extension          │
+                                           │  (TypeScript)       │
+                                           │  popup · vault      │
+                                           │  setup · content    │
+                                           │  service worker     │
+                                           └─────────────────────┘
+```
+
+| Codebase | Language | Role | Key boundary |
+|---|---|---|---|
+| `relicario-core` | Rust | Crypto, item types, manifest, attachments, imgsecret, generators, device keys / fingerprints. Pure, no I/O. | Only `bytes-in / bytes-out`. No filesystem, no git, no network. |
+| `relicario-cli` | Rust binary | Wraps core with filesystem ops, git plumbing, clap UX. | Only entry point that runs without a browser; sole working interface during disaster recovery. |
+| `relicario-wasm` | Rust → WASM | Thin `#[wasm_bindgen]` exports from core for the extension. | Compiles `relicario-core` to WASM; no extra logic. |
+| `relicario-server` | Rust binary | Pre-receive Git hook (`verify-commit`) plus hook installer (`generate-hook`) running on the vault remote. Verifies SSH-signed commits against `.relicario/devices.json` and `.relicario/revoked.json`. | Lives on the git server, not on a client device. The only Relicario component the user does not run themselves. Sees only public key material. |
+| `extension` | TypeScript | Browser-resident UI. Five entry-point bundles (popup, vault tab, setup, content script, service worker). | The service worker is the only crypto holder; popup/vault/content/setup never touch the master key. |
+
+The CLI and the extension are **at parity**: every user-facing capability lands in both surfaces together. Diverging is allowed only with a documented reason. See the per-codebase docs for which surface owns which user flow. The server has no user-facing surface — it is a server-side enforcer of the device-auth invariant the clients already agreed to.
+
+## Inter-codebase contracts
+
+There are four boundaries where the codebases agree on a wire format. Each is versioned independently.
+
+### 1. Core → WASM ABI (Rust / JS edge)
+
+The `relicario-wasm` crate is the JS/Rust contract. Every WASM export takes `JsValue` / `&[u8]` / `&str` and returns the same. Strings on the wire are JSON-encoded for any structured data; raw bytes for ciphertext / images / attachments.
+
+Adding a new core capability for the extension requires:
+1. Add the capability to `relicario-core/src/`.
+2. Re-export through `lib.rs`.
+3. Add a thin `#[wasm_bindgen]` wrapper to `relicario-wasm/src/lib.rs`.
+4. Run `wasm-pack build` (via `npm run build:wasm` in `extension/`).
+5. Use it from the extension's service worker (or setup wizard).
+
+The `SessionHandle` is the cross-language opaque token: WASM owns the `Zeroizing<[u8;32]>` master key behind a numeric handle; JS only ever holds the number. JS calling `wasm.lock(handle)` zeroes the WASM-side memory and invalidates the handle.
+
+### 2. Service worker ↔ popup / vault tab / content script (chrome.runtime messages)
+
+All extension bundles other than the SW communicate with the SW exclusively via `chrome.runtime.sendMessage`. The protocol is defined in `extension/src/shared/messages.ts`:
+
+- `PopupMessage` — sent by popup, vault tab, or setup wizard
+- `ContentMessage` — sent by content scripts injected into web pages
+- `Response` — returned by the SW: `{ ok: true, data?: ... } | { ok: false, error: string }`
+
+Two **capability sets** in `messages.ts` gate which sender can issue which message:
+
+- `POPUP_ONLY_TYPES` — accepted only from popup.html, vault.html, or setup.html
+- `CONTENT_CALLABLE_TYPES` — accepted only from content scripts
+
+The router (`service-worker/router/index.ts`) dispatches by sender. Adding a new message type requires adding it to one of the capability sets, **or it is silently rejected**. Vault tab parity (commit `a7dbf35`) is implemented by recognizing `vault.html` as a popup-class sender at the router level.
+
+### 3. Vault on disk (shared by CLI and extension)
+
+Every relicario vault — whether on disk for the CLI or in a git remote read by the extension — has the same layout:
+
+```
+<vault root>/
+├── .relicario/
+│   ├── salt              # 32 bytes, random per vault, stays constant
+│   ├── params.json       # KdfParams: argon2_m, argon2_t, argon2_p
+│   └── devices.json      # [{ name, public_key }, ...]
+├── manifest.enc          # encrypted Manifest (browse-without-decrypt index)
+├── settings.enc          # encrypted VaultSettings
+├── items/
+│   └── <id>.enc          # encrypted Item, one per file
+└── attachments/
+    └── <item-id>/
+        └── <aid>.enc     # encrypted attachment blob; aid is content-addressed SHA-256
+```
+
+The reference image (`reference.jpg`) lives **outside** the vault by convention — it is the second factor and the user's responsibility to safeguard. It is not in `.relicario/`, not in `items/`, and never committed to git.
+
+This layout is not formally versioned — the **content** within each `.enc` file carries its own version byte (see § Versioning below). The directory layout itself is conventional and changes would be breaking.
+
+### 4. Git remote API (extension's `GitHost`)
+
+The extension cannot shell out to `git`; it talks to the remote via the host's REST API. Two implementations live in `extension/src/service-worker/`:
+
+- `gitea.ts` — Gitea / Forgejo API
+- `github.ts` — GitHub API
+
+Both implement the `GitHost` interface in `git-host.ts`. Adding a third host (GitLab, Bitbucket, custom) means implementing that interface — the rest of the extension is host-agnostic.
+
+The CLI does not use `GitHost`; it shells out to `git` directly via the hardened wrapper in `relicario-cli/src/helpers.rs:46`.
+
+## Versioning strategy
+
+There is no single "relicario format version." Each piece of the format is versioned independently so we can evolve without coordinated upgrades.
+
+| Artifact | Where versioned | Current value | Failure mode on read |
+|---|---|---|---|
+| AEAD ciphertext | First byte of every `.enc` blob | `VERSION_BYTE = 0x02` (in `relicario-core/src/crypto.rs`) | `RelicarioError::Format` — refuses to attempt decryption |
+| Manifest schema | `Manifest.schema_version` field | `2` (set in `relicario-core/src/manifest.rs`) | v1 manifests are explicitly rejected with a clear error |
+| KDF parameters | `.relicario/params.json` | Vault-specific (initially m=64MiB, t=3, p=4) | Read at unlock; stored alongside the vault |
+| Backup container | First 5 bytes of `.relbak`: magic `"RBAK"` + version byte | `0x01` (designed; see import/export spec) | Format-version error if newer-version backup is read by older binary |
+| Device entry | `devices.json` array of `{ name, public_key }` | Unversioned (extend by adding optional fields) | — |
+
+The intentional design: **no big-bang upgrades**. A user can run an older CLI against a newer vault as long as the AEAD version, manifest schema, and KDF params are still compatible.
+
+## Where secrets live
+
+The threat model differs by codebase. This is the per-secret per-codebase residence map:
+
+| Secret | relicario-core | relicario-cli | extension SW | extension popup/vault/content/setup |
+|---|---|---|---|---|
+| Passphrase (UTF-8 bytes) | `Zeroizing<String>` only during a single `derive_master_key` call | Same, in `UnlockedVault::unlock_interactive` | Same, used briefly to derive master key inside WASM | Never seen — entered into a `<input type="password">`, sent to SW via `unlock` message, immediately forgotten |
+| Reference image bytes | Held by caller; core only reads | Held by `UnlockedVault::unlock_interactive` long enough to extract the secret | Same | Setup wizard holds the bytes briefly during create/attach modes |
+| Image secret (32 B) | `Zeroizing<[u8;32]>` during KDF | Same | Same | Never sees it |
+| Master key | `Zeroizing<[u8;32]>` returned by `derive_master_key` | `UnlockedVault.master_key` for the lifetime of one CLI invocation | WASM-side memory behind an opaque `SessionHandle`; JS never sees the bytes | Never sees it |
+| Item secret (password, card number, etc.) | `Zeroizing<String>` / `Zeroizing<Vec<u8>>` | Same | Briefly held in WASM during `item_decrypt`; results passed to popup as plaintext for display | Held in DOM (the user is staring at it); cleared when view changes |
+| Device private key | — | Filesystem under `~/.config/relicario/devices/<name>.key` (mode 0600) | `chrome.storage.local.device_private_key` | — |
+
+The popup / vault / content surfaces of the extension cannot decrypt an item independently — they all message the SW. Content scripts in particular get back already-prepared payloads (e.g. `{ username, password }`) from `fill_credentials` after the SW resolved everything.
+
+The CLI keeps its master key in process memory; if the process exits or crashes, the key is gone (Zeroize on drop). There is no CLI session daemon. The `lock` subcommand exists only for UX parity with the extension and is a no-op.
+
+## Build matrix
+
+| Target | Tool | Output | When to run |
+|---|---|---|---|
+| Native CLI | `cargo build` (debug or `--release`) | `target/{debug,release}/relicario` | After CLI changes; for distribution |
+| Server hook | `cargo build -p relicario-server --release` | `target/release/relicario-server` | After server changes; deploy onto the git remote |
+| Native test suites | `cargo test` (workspace) | — | After any Rust change |
+| WASM module | `wasm-pack build --target web` (via `npm run build:wasm`) | `extension/wasm/relicario_wasm{,_bg.wasm,.js}` | After core or wasm crate changes |
+| Chrome extension | `webpack` (`npm run build`) | `extension/dist/` | After TS or WASM changes; for Chrome distribution |
+| Firefox extension | `webpack --config webpack.firefox.config.js` (`npm run build:firefox`) | `extension/dist-firefox/` | After TS or WASM changes; for Firefox distribution |
+| All extension targets | `npm run build:all` | Both `dist/` and `dist-firefox/` plus rebuilt WASM | Pre-release |
+| Extension tests | `npm test` (vitest, happy-dom) | — | After TS changes |
+
+The WASM build sequence matters: `wasm-pack` writes the binary into `extension/wasm/` before `webpack` picks it up. `npm run build:all` runs them in order. Manual builds need the same order.
+
+## Test strategy at the workspace level
+
+| Layer | Tool | Where | What it covers |
+|---|---|---|---|
+| Core unit tests | `cargo test -p relicario-core` | `crates/relicario-core/src/**/#[cfg(test)]` and `tests/*.rs` | Crypto round-trip, item serialization, manifest schema, generators, imgsecret embed/extract, format-v2 parsing |
+| CLI integration tests | `cargo test -p relicario-cli` | `crates/relicario-cli/tests/*.rs` | End-to-end via `TestVault::init()` harness with synthetic JPEGs and `RELICARIO_TEST_*` env-var escape hatches; covers basic flows, edit + history (incl. TOTP), attachments, settings, vault detection |
+| Extension unit tests | `npm test` (vitest) | `extension/src/**/__tests__/*.test.ts` | Component render + click handlers (mocked SW), router sender dispatch, SW handler logic (mocked WASM + chrome.storage) |
+| End-to-end | none | — | No real-browser tests; mocks stand in. Build-vs-test gap is documented in extension/ARCHITECTURE.md |
+
+Core tests use **fast Argon2id params** (m=256, t=1, p=1) so they don't take forever; the production path is the same code with real params. The CLI's `init` command always uses production-grade params even under tests.
+
+## Conventions that span all three codebases
+
+| Rule | Where enforced | Why |
+|---|---|---|
+| Master key only in `Zeroizing<[u8;32]>` | core types; CLI follows; extension WASM follows | Drop-on-scope-exit zeroization; never leaves stack |
+| AEAD ciphertext starts with version byte | `core/crypto.rs` | Format identification; reject v1 blobs cleanly |
+| Item IDs are random 16-char hex (64 bits) | `core/ids.rs` | Stable, short, no information leak |
+| Attachment IDs are content-addressed (first 32 hex chars / 128 bits of SHA-256) | `core/ids.rs` | Dedup; integrity check |
+| KDF input is length-prefixed | `core/crypto.rs` | Prevents `passphrase || image_secret` collisions |
+| Git history is preserved as audit log; never squash | CLI commits; SW commits | Per-action history is a feature |
+| Per-action git commits with structured messages | `cli` (via `commit_paths`); SW (via vault.ts helpers) | Greppable, useful as audit log |
+| Hardened git invocations (`-c core.hooksPath=/dev/null` etc.) | CLI's `helpers::git_command`; SW does not shell out | Prevent hostile hooks; no GPG prompt holding key alive |
+| Atomic writes (write `.tmp` → rename) | CLI's `session::atomic_write`; SW's vault.ts equivalents | Partial-write safety |
+| Tests use synthesized JPEGs (`make_test_jpeg`), not committed binaries | Both Rust and TS test harnesses | Repo stays small; reproducible |
+| Test-only env vars (`RELICARIO_TEST_*`) have no production fall-through | Verified in `relicario-cli` audit | Escape hatches don't leak into builds |
+
+## Where to look next
+
+| 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) |
+| A new GitHost (e.g. GitLab support) | `extension/src/service-worker/git-host.ts` (interface) and existing implementations |
+| The pre-receive hook / device-auth enforcement | `crates/relicario-server/src/main.rs`, then `docs/superpowers/specs/2026-05-02-device-authentication-design.md` for rationale |
+| Adding a new item type | core's `item_types/` mod, then CLI's `build_*_item`/`edit_*` helpers, then extension's `popup/components/types/<type>.ts` |
+| Threat model / why a primitive was chosen | `docs/superpowers/specs/2026-04-11-relicario-design.md` (historical, but authoritative for rationale) |
+| Format of the import/export feature | `docs/superpowers/specs/2026-04-27-relicario-import-export-design.md` (designed but not yet implemented) |
+| Running the full test suite | `cargo test && (cd extension && npm test)` |
+| Bumping the WASM module after a core change | `cd extension && npm run build:wasm` |
+
+## 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).

docs/superpowers/MULTI-AGENT.md

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

docs/superpowers/audits/2026-04-18-initial-security-audit-opus-4-5.md

@@ -0,0 +1,158 @@
+# Verification: 2026-04-18 Initial Security Audit
+
+**Verified by:** Claude Opus 4.5  
+**Date:** 2026-05-01  
+**Methodology:** Code inspection of referenced file paths and line numbers
+
+---
+
+## Summary
+
+| Finding | File Exists | Lines Match Current | Vulnerability Status | Confidence |
+|---------|-------------|---------------------|---------------------|------------|
+| C1 - Setup web-accessible | ✅ | ❌ refactored | **FIXED** | 10/10 |
+| C2 - Message router trusts all | ✅ | ❌ refactored | **FIXED** | 10/10 |
+| C3 - Capture innerHTML XSS | ✅ | ❌ refactored | **FIXED** | 10/10 |
+| C4 - Autofill no origin check | ✅ | ❌ refactored | **FIXED** | 10/10 |
+| H1 - KDF unprefixed concat | ✅ | ❌ refactored | **FIXED** | 10/10 |
+| H2 - Master key not zeroized | ✅ | ❌ refactored | **FIXED** | 9/10 |
+| H3 - Passphrase gate cosmetic | ✅ | ❌ refactored | **FIXED** | 10/10 |
+| H4 - Git shells out unsafely | ✅ | ❌ refactored | **FIXED** | 10/10 |
+| H5 - WASM Math.random() | ✅ | ❌ refactored | **FIXED** | 10/10 |
+| H6 - Modulo bias | ✅ | ❌ refactored | **FIXED** | 10/10 |
+| H7 - rpassword outdated | ✅ | ✅ | **FIXED** | 10/10 |
+| H8 - Storage plaintext | ✅ | ⚠️ partial | **ACKNOWLEDGED** | 8/10 |
+
+**Verdict:** All CRITICAL and HIGH findings except H8 have been remediated. The codebase has been significantly refactored since this audit, making line number references obsolete but confirming fixes were applied.
+
+---
+
+## CRITICAL Findings
+
+### C1: Setup wizard web-accessible
+
+- **Original claim:** `web_accessible_resources` with `matches: ["<all_urls>"]` allows any website to inject vault config.
+- **Current state:** `extension/manifest.json` line 38 shows `"web_accessible_resources": []` (empty array).
+- **Router validation:** `router/index.ts` lines 29-71 verify sender origins (`isPopup`, `isSetup`, `isContent`) and return `unauthorized_sender` for invalid callers.
+- **Status:** ✅ **FIXED**
+
+### C2: Service-worker trusts every message
+
+- **Original claim:** `index.ts:116-441` ignores `_sender` and trusts all messages.
+- **Current state:** `service-worker/index.ts` is now 100 lines; message handling delegated to modular router.
+- **Router checks:**
+  - `sender.frameId === 0` for content scripts (line 42)
+  - `sender.id === chrome.runtime.id` (line 43)
+  - Returns `{ ok: false, error: 'unauthorized_sender' }` for invalid senders
+- **Status:** ✅ **FIXED**
+
+### C3: Capture prompt innerHTML injection
+
+- **Original claim:** `capture.ts:172-191` uses innerHTML with attacker-controlled strings in page DOM.
+- **Current state:** 
+  - Uses `createShadowHost()` (line 128) for closed Shadow DOM
+  - Builds DOM via `document.createElement` + `.textContent =` (lines 143-216)
+  - File header (lines 6-9) documents this pattern
+- **Status:** ✅ **FIXED**
+
+### C4: Autofill has no origin check
+
+- **Original claim:** `get_autofill_candidates` accepts URL from message payload; `get_credentials` returns any entry by ID.
+- **Current state in `content-callable.ts`:**
+  - Line 25: `const senderHost = safeHostname(sender.tab?.url ?? '')` — uses sender tab, not message
+  - Line 44: `if (!itemHost || itemHost !== senderHost) return { ok: false, error: 'origin_mismatch' }`
+  - Lines 46-51: TOFU origin-ack check before returning credentials
+- **Status:** ✅ **FIXED**
+
+---
+
+## HIGH Findings
+
+### H1: Argon2id unprefixed concatenation
+
+- **Original claim:** `crypto.rs:225-227` has `password = passphrase || image_secret` without length prefix.
+- **Current state at `crypto.rs:229-236`:**
+  ```rust
+  let mut password = Zeroizing::new(Vec::with_capacity(8 + nfc_passphrase.len() + 8 + 32));
+  password.extend_from_slice(&(nfc_passphrase.len() as u64).to_be_bytes());
+  password.extend_from_slice(&nfc_passphrase);
+  password.extend_from_slice(&32u64.to_be_bytes());
+  password.extend_from_slice(image_secret);
+  ```
+  Also includes NFC normalization (lines 224-227).
+- **Status:** ✅ **FIXED**
+
+### H2: Master key never zeroized
+
+- **Original claim:** `Vec<u8>` from `derive_master_key` and intermediates leak into heap.
+- **Current state:**
+  - `crypto.rs:212`: returns `Zeroizing<[u8; 32]>`
+  - `crypto.rs:232`: password wrapped in `Zeroizing::new()`
+  - `session.rs` (WASM/CLI): stores keys as `Zeroizing<[u8; 32]>`
+  - CLI rpassword calls wrapped in `Zeroizing::new()`
+- **Note:** JS string zeroization remains a limitation (acknowledged).
+- **Status:** ✅ **FIXED**
+
+### H3: Passphrase strength gate cosmetic
+
+- **Original claim:** Extension accepts any non-empty passphrase; CLI only requires 8 chars.
+- **Current state:**
+  - `setup.ts:152,640`: `score < 3` disables button
+  - `setup.ts:784-789`: server-side re-validation before create
+  - `generators.rs:124-130`: `validate_passphrase_strength()` requires score >= 3
+- **Status:** ✅ **FIXED**
+
+### H4: Git shells out without guards
+
+- **Original claim:** No hooks/gpgsign/editor isolation.
+- **Current state in `helpers.rs:41-55`:**
+  ```rust
+  cmd.args([
+      "-c", "core.hooksPath=/dev/null",
+      "-c", "commit.gpgsign=false", 
+      "-c", "core.editor=true",
+  ]);
+  ```
+  Comment explicitly references "Audit H4".
+- **Status:** ✅ **FIXED**
+
+### H5: WASM Math.random()
+
+- **Original claim:** `lib.rs:240-256` uses `Math.random()` for password generation.
+- **Current state:** `generate_password` calls `core_generate_password` from relicario-core.
+- **generators.rs:**
+  - Line 6: `use rand::rngs::OsRng;`
+  - Lines 61-64: Uses `Uniform::from()` with `OsRng`
+  - No `Math.random()` anywhere in codebase
+- **Status:** ✅ **FIXED**
+
+### H6: Modulo bias
+
+- **Original claim:** `main.rs:308-317` uses `% CHARSET.len()`.
+- **Current state in `generators.rs`:**
+  - Line 61: `let dist = Uniform::from(0..charset.len());`
+  - Line 63: `charset[dist.sample(&mut rng)]` — rejection sampling, no modulo
+- **Status:** ✅ **FIXED**
+
+### H7: rpassword 5.0.1 outdated
+
+- **Original claim:** Uses deprecated `prompt_password_stderr`.
+- **Current state:** `Cargo.toml` shows `rpassword = "7"`, uses `prompt_password`.
+- **Status:** ✅ **FIXED**
+
+### H8: Storage keeps apiToken/imageBase64 plaintext
+
+- **Original claim:** `chrome.storage.local` stores PAT and reference image unencrypted.
+- **Current state:** Still true — `popup-only.ts:139-141` stores `vaultConfig` and `imageBase64`.
+- **Mitigation:** Acknowledged as design constraint; spec documents that filesystem access to browser profile compromises both factors.
+- **Status:** ⚠️ **ACKNOWLEDGED** (not fixed, documented as acceptable tradeoff)
+
+---
+
+## Conclusion
+
+The 2026-04-18 audit identified real vulnerabilities that existed at that time. **All CRITICAL and HIGH findings (C1-C4, H1-H7) have since been remediated** with the exact fixes recommended in the audit. The codebase underwent significant refactoring, making the original line number references obsolete.
+
+H8 remains as an acknowledged design constraint inherent to Chrome extension architecture.
+
+**The audit was accurate and the remediation was thorough.**

docs/superpowers/audits/2026-04-18-initial-security-audit.md

@@ -1,4 +1,4 @@
-# relicario Security Audit Report
+# Relicario Security Audit Report
 
 **Date:** 2026-04-18
 **Scope:** Full static review of `crates/relicario-core/`, `crates/relicario-cli/`, `crates/relicario-wasm/`, `extension/src/`, both manifests, both webpack configs, and the design spec at `docs/superpowers/specs/2026-04-11-relicario-design.md`.

docs/superpowers/audits/2026-05-01-security-audit-opus-4-5.md

@@ -0,0 +1,113 @@
+# Verification: 2026-05-01 Security Audit
+
+**Verified by:** Claude Opus 4.5  
+**Date:** 2026-05-01  
+**Methodology:** Code inspection of referenced file paths and line numbers
+
+---
+
+## Summary
+
+| Finding | File Exists | Lines Accurate | Vulnerability Real | Confidence |
+|---------|-------------|----------------|-------------------|------------|
+| 1 - Backup KDF NFC | ✅ | ✅ | ✅ | 10/10 |
+| 2 - Commit injection | ✅ | ✅ | ✅ | 10/10 |
+| 3 - WASM private key exposure | ✅ | ✅ | ✅ | 10/10 |
+| 4 - Test env vars in prod | ✅ | ✅ | ✅ | 10/10 |
+| 5 - AttachmentId 64-bit | ✅ | ⚠️ off-by-1 | ✅ | 9/10 |
+| 6 - Field history plaintext | ✅ | ✅ | ✅ | 10/10 |
+| 7 - Device keys non-functional | ✅ | ✅ | ✅ | 10/10 |
+| 8 - Path traversal restore | ✅ | ✅ | ✅ | 10/10 |
+
+**Verdict:** All 8 findings are verified as real vulnerabilities in the current codebase.
+
+---
+
+## Finding-by-Finding Verification
+
+### Finding 1 — Backup KDF missing NFC normalization
+
+- **File:** `crates/relicario-core/src/backup.rs`
+- **Claimed lines:** 303-312
+- **Verified:** ✅ `derive_backup_key` at lines 303-312 passes `passphrase` directly to `argon.hash_password_into()` without NFC normalization. Compare to `derive_master_key` in `crypto.rs:224-227` which explicitly normalizes.
+- **Impact confirmed:** Cross-platform restore failure for non-ASCII passphrases.
+
+### Finding 2 — Commit message injection via item titles
+
+- **File:** `crates/relicario-cli/src/main.rs`
+- **Claimed lines:** 565, 899-901, 1110, 1327
+- **Verified:** ✅
+  - Line 565: `format!("add: {} ({})", item.title, item.id.as_str())`
+  - Line 1110: `format!("edit: {} ({})", item.title, item.id.as_str())`
+  - Line 1327: `format!("trash: {} ({})", item.title, item.id.as_str())`
+- **Impact confirmed:** Newlines/control chars in titles corrupt git log output.
+
+### Finding 3 — WASM `generate_device_keypair` crosses private key to JS
+
+- **File:** `crates/relicario-wasm/src/lib.rs`
+- **Claimed lines:** 215-227
+- **Verified:** ✅ Function returns `{ "private_key_base64": "..." }` as `JsValue`, exposing ed25519 private key to JavaScript heap.
+- **Impact confirmed:** Key material accessible to any JS in service worker context.
+
+### Finding 4 — Test env vars ship in production binary
+
+- **File:** `crates/relicario-cli/src/main.rs`
+- **Claimed lines:** 445-446, 421-423, 1425-1426
+- **Verified:** ✅
+  - Lines 421-423: `RELICARIO_TEST_ITEM_SECRET`
+  - Lines 445-446: `RELICARIO_TEST_PASSPHRASE`
+  - Lines 1425-1426: `RELICARIO_TEST_BACKUP_PASSPHRASE`
+- **Impact confirmed:** All checked in production code without `#[cfg(test)]`. Passphrase visible in `/proc/<pid>/environ`.
+
+### Finding 5 — `AttachmentId` truncated to 64 bits
+
+- **File:** `crates/relicario-core/src/ids.rs`
+- **Claimed lines:** 52-57
+- **Actual lines:** 51-56 (off by 1)
+- **Verified:** ✅ `&digest[..8]` = 8 bytes = 64 bits. Birthday collision at ~2³² work.
+- **Impact confirmed:** Attacker with attachment upload can cause silent overwrites.
+
+### Finding 6 — `get_field_history` returns plaintext to JS
+
+- **File:** `crates/relicario-wasm/src/lib.rs`
+- **Claimed lines:** 232-265
+- **Verified:** ✅ Returns historical `Password`/`Concealed` values as plaintext JSON via `v.as_str().to_owned()`.
+- **Impact confirmed:** Password history exposed to JS heap without Zeroizing.
+
+### Finding 7 — Device key system is security theater
+
+- **File:** `crates/relicario-cli/src/main.rs`
+- **Claimed lines:** 2151-2221
+- **Verified:** ✅ `cmd_device()` handles Add/List/Revoke but:
+  - No `sign_commit` or `verify_signature` functions exist anywhere
+  - `devices.json` is plaintext and unauthenticated
+  - Revocation has no enforcement mechanism
+- **Impact confirmed:** Users falsely believe device revocation provides security.
+
+### Finding 8 — Path traversal on backup restore
+
+- **File:** `crates/relicario-cli/src/main.rs`
+- **Claimed lines:** 1619-1626
+- **Verified:** ✅
+  ```rust
+  for item in &unpacked.items {
+      fs::write(target.join("items").join(format!("{}.enc", item.id)), ...)?;
+  }
+  ```
+  `item.id` and `attachment_id` used directly in path construction with no validation.
+- **Impact confirmed:** Crafted `.relbak` with `id = "../../.bashrc"` escapes target directory.
+
+---
+
+## Blockers Assessment
+
+The audit's "Path to Certifiable Safety" section is accurate:
+
+| Blocker | Verified | Severity |
+|---------|----------|----------|
+| B1 - Device key theater | ✅ Real | High |
+| B2 - Backup KDF NFC | ✅ Real | Medium |
+| B3 - Test env vars | ✅ Real | Medium |
+| B4 - Path traversal | ✅ Real | Medium |
+
+All four blockers are confirmed. B1 is the most dangerous as it misleads users about their security posture.

docs/superpowers/audits/2026-05-01-security-audit.md

@@ -0,0 +1,199 @@
+# Relicario Security Audit — 2026-05-01
+
+Scope: full project audit (not a PR diff). Covers crypto correctness, protocol gaps,
+implementation reality vs. plans, and a roadmap toward third-party auditability.
+
+---
+
+## Section 1 — Security Findings
+
+### Finding 1 — Backup KDF missing NFC normalization
+
+**`crates/relicario-core/src/backup.rs:303-312`** · Severity: **Medium**
+
+`derive_backup_key` passes raw passphrase bytes to Argon2id. The main vault KDF in
+`crypto.rs` uses `u64_be(len) || nfc_passphrase || u64_be(32) || image_secret`. The
+backup KDF has neither NFC normalization nor the length-prefix construction.
+
+**Exploit:** User creates a backup on macOS (NFD normalization) and restores on Linux
+(NFC). The Argon2id input differs → wrong key → unrestorable backup. Affects any
+non-ASCII passphrase (`"Crêpe-7"`, `"café"`, accented chars).
+
+**Fix:** Factor out `normalize_passphrase()` and use it in both `derive_master_key` and
+`derive_backup_key`.
+
+---
+
+### Finding 2 — Commit message injection via item titles
+
+**`crates/relicario-cli/src/main.rs:565, 899-901, 1110, 1327`** · Severity: **Medium**
+
+Item titles (arbitrary user UTF-8) are embedded directly into `-m` commit message strings
+via `format!("add: {} ({})", item.title, ...)`. `git_command` uses `Command::args()` (no
+shell), so shell injection into `git add` is blocked — but newlines in titles produce
+malformed multi-line commit messages that corrupt git log parsers.
+
+**Fix:** Strip control characters from titles before embedding in commit messages, or omit
+the title from the `-m` format entirely and use only the item ID.
+
+---
+
+### Finding 3 — WASM `generate_device_keypair` crosses private key bytes to JS
+
+**`crates/relicario-wasm/src/lib.rs:215-227`** · Severity: **Medium**
+
+Returns `{ "private_key_base64": "..." }` as a `JsValue`. The ed25519 private key lives in
+the JS heap with no `Zeroizing` protection. The vault master key is protected behind an
+opaque `SessionHandle` and never crosses to JS — the device key has no such protection.
+
+**Exploit:** Any JS running in the extension service worker context (compromised dependency,
+content script escalation) that can intercept the return value gets the raw device key.
+
+**Fix:** Never return the private key to JS. Expose only a `sign(handle, data) → signature`
+API; perform the signing in Rust.
+
+---
+
+### Finding 4 — Test env vars ship in production binary
+
+**`crates/relicario-cli/src/main.rs:445-446, 421-423, 1425-1426`** · Severity: **Medium**
+
+`RELICARIO_TEST_PASSPHRASE`, `RELICARIO_TEST_ITEM_SECRET`, `RELICARIO_TEST_BACKUP_PASSPHRASE`
+are checked in production code (not `#[cfg(test)]`). When set, they bypass the interactive
+TTY prompt.
+
+**Exploit:** On Linux, `/proc/<pid>/environ` exposes the passphrase in cleartext to
+same-UID processes. Shell history captures `RELICARIO_TEST_PASSPHRASE=mysecret relicario unlock ...`.
+
+**Fix:** Gate behind `#[cfg(test)]` or a `--features testing` build profile.
+
+---
+
+### Finding 5 — `AttachmentId` truncated to 64 bits of SHA-256
+
+**`crates/relicario-core/src/ids.rs:52-57`** · Severity: **Medium**
+
+`AttachmentId::from_plaintext` takes `&digest[..8]` (8 bytes = 64 bits). Standard
+content-addressed stores use ≥128 bits. With 64 bits, an attacker who can supply attachment
+content can find a second-preimage collision with ~2^32 work, causing a crafted attachment
+to silently overwrite an existing one on disk.
+
+**Fix:** Change `&digest[..8]` → `&digest[..16]` (128 bits). No migration needed for
+existing vaults since only new attachments are affected.
+
+---
+
+### Finding 6 — `get_field_history` re-parses item JSON from JS heap
+
+**`crates/relicario-wasm/src/lib.rs:232-265`** · Severity: **Medium**
+
+Returns all historical `Password`/`Concealed` values as plaintext `JsValue`. The values
+are regular `String` allocations with no `Zeroizing` wrapper before serialization into
+`serde_json::Value`.
+
+**Fix:** Architectural — document that the caller must treat the return value as sensitive.
+For strong hygiene: do all history display in Rust, never returning password history bytes
+to JS.
+
+---
+
+### Finding 7 — Device key system is non-functional as a security control
+
+**`crates/relicario-cli/src/main.rs:2151-2221`** · Severity: **High**
+
+`device add/list/revoke` and `generate_device_keypair` exist, but **no code anywhere signs
+git commits with device keys**, and **no code verifies device signatures**. `devices.json`
+is plaintext in the repo and unauthenticated by the vault.
+
+**Exploit:** Users believe "device revocation" prevents unauthorized access after a device
+is stolen/compromised. It does nothing. A stolen device continues to have full vault access
+via its git remote credentials regardless of revocation.
+
+**Fix:** Either (a) implement commit signing + server-side pre-receive hook verification, or
+(b) remove the `device` subcommands and document that access control is SSH-key-level only.
+
+---
+
+### Finding 8 — Path traversal on backup restore
+
+**`crates/relicario-cli/src/main.rs:1619-1626`** · Severity: **Medium**
+
+During restore, item/attachment IDs from the decrypted backup JSON are used directly as
+path components with no format validation. IDs are AEAD-authenticated but a user restoring
+from a crafted `.relbak` with a known passphrase would execute arbitrary path writes.
+
+**Exploit (social engineering):** Attacker provides a `.relbak` with item ID
+`../../.bashrc` → restore overwrites `~/.bashrc`.
+
+**Fix:**
+```rust
+ensure!(id.len() == 16 && id.chars().all(|c| c.is_ascii_hexdigit()),
+    "invalid id in backup");
+```
+
+---
+
+## Section 2 — Implementation Status
+
+| Feature | Status | Notes |
+|---|---|---|
+| Two-factor decrypt (passphrase + image_secret) | ✅ Implemented | Full crypto pipeline, NFC passphrase, Argon2id m=64MiB t=3 p=4 |
+| imgsecret embed | ✅ Implemented | DCT QIM, QUANT_STEP=50, central 70%, 5-50 redundant copies |
+| imgsecret extract + crop recovery | ✅ Implemented | Majority voting ≥60%, 4 crop search strategies |
+| Manifest browse (schema v2) | ✅ Implemented | Encrypted with master key, search(), title/type/tags/icon |
+| Vault CRUD (init/add/edit/rm/trash/restore/purge) | ✅ Implemented | All 7 item types fully handled |
+| CLI `init` | ✅ Implemented | zxcvbn ≥3 gate, image embed, Argon2id params, git init |
+| CLI `add` / `edit` | ✅ Implemented | All 7 types, TOTP QR decode via rqrr, field history capture |
+| CLI `generate` | ✅ Implemented | Random (rejection-sampled) + BIP39, uses vault defaults |
+| CLI `sync` | ✅ Implemented | `git pull --rebase && git push` |
+| CLI `backup export/restore` | ✅ Implemented | Plan 3A: zstd+AEAD container, optional image + git bundle |
+| CLI `import lastpass` | ✅ Implemented | Plan 3B: CSV validation, Login + SecureNote + TOTP mapping |
+| WASM bindings (all item/manifest/settings) | ✅ Implemented | Complete symmetric set |
+| WASM session handle (opaque master key) | ✅ Implemented | Key never crosses WASM boundary |
+| WASM attachment, generator, TOTP, backup, import | ✅ Implemented | All wired |
+| Field history tracking + CLI `history` | ✅ Implemented | Password/Concealed/TOTP history, prune policies |
+| Trash + retention | ✅ Implemented | `trash list/empty`, TrashRetention window |
+| Attachments (CLI + WASM) | ✅ Implemented | File-level AEAD, cap enforcement, Document type |
+| Settings / VaultSettings | ✅ Implemented | All retention + generator + cap fields, CLI subcommands |
+| Device keys (add/list/revoke) | ⚠️ Partial | Key gen + persistence only — **no signing, no verification** (Finding 7) |
+| Per-vault total attachment cap | ⚠️ Partial | Cap defined in settings, per-attachment enforced — per-vault total bytes not checked |
+| Browser extension UI | ⚠️ Partial | WASM surface complete; extension TypeScript/HTML is a separate repo |
+| Recovery QR | ❌ Plan-only | Spec written; no `recovery_qr.rs` module exists |
+| Password coloring | ❌ Plan-only | Spec written; no implementation |
+| Passphrase rotation | ❌ Deferred | Explicitly back-burnered |
+| Pre-v0.3.0 audit walk | ❌ Not started | Listed as pending before v0.3.0 tag |
+| HOTP counter persistence | ❌ Bug | `Hotp { counter }` never incremented/saved — HOTP desynchronizes immediately |
+
+---
+
+## Section 3 — Path to Certifiable Safety
+
+### Blockers — must fix before any real use
+
+| # | Item |
+|---|---|
+| B1 | **Device key system is security theater** — implement signing or remove the commands. This is the most dangerous finding because it misleads users about their security posture. |
+| B2 | **Backup KDF NFC normalization** — one-line fix; data loss risk for non-ASCII passphrases. |
+| B3 | **Test env vars in production binary** — gate with `#[cfg(test)]`. Exposes passphrase via `/proc`. |
+| B4 | **Path traversal on restore** — two-line ID validation before any `fs::write`. |
+
+### Important — fix before third-party audit
+
+| # | Item |
+|---|---|
+| I1 | Sanitize item titles before embedding in commit messages |
+| I2 | `AttachmentId`: `&digest[..8]` → `&digest[..16]` (128-bit collision resistance) |
+| I3 | Enforce per-vault total attachment bytes cap (already defined, never checked) |
+| I4 | Document manifest integrity model: AEAD protects against silent modification, but item deletion is only detectable via git history |
+| I5 | Stop crossing device private key bytes to JS (prerequisite for B1 if signing is implemented) |
+| I6 | Fix HOTP counter: increment + re-save on each `totp get`, or disable HOTP and return an error |
+
+### Nice-to-have — audit-friendliness
+
+| # | Item |
+|---|---|
+| N1 | Wrap `nfc_passphrase: Vec<u8>` in `Zeroizing` in `derive_master_key` |
+| N2 | `cargo audit` in CI |
+| N3 | Validate Argon2id params on vault load — warn if below production minimums |
+| N4 | Broaden steganography recompression tests to use ImageMagick/libjpeg-turbo (not just the `image` crate) |
+| N5 | Consider machine-readable audit log encrypted alongside the vault |

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

@@ -0,0 +1,178 @@
+# Documentation Audit — 2026-05-02
+
+Pre-v0.5.0 audit of Relicario's documentation against the current codebase.
+
+## Summary
+
+- **Total findings:** 14
+- **Fixed inline (initial pass):** 6
+- **Fixed during v0.5.0 PM run (this audit, follow-up commits):** 8
+- **No action needed:** 0
+- **Top 3 recommendations:**
+  1. **Add `relicario-server` to architecture docs.** It exists in `crates/`, is referenced by SECURITY.md, and underpins device-auth, but `docs/architecture/overview.md`'s "three codebases" framing and `CLAUDE.md`'s project-structure tree still pretend it doesn't exist (Findings 1, 2, 9). This is the single biggest gap before tagging v0.5.0.
+  2. **Replace `CLAUDE.md`'s Roadmap.** It still says "Next: WASM build + Chrome MV3 browser extension (Plan 2)" — a milestone that shipped weeks ago. Multiple subsequent train rounds (typed items, attachments, backup, LastPass, device auth, fullscreen UX phases) have shipped, none of which are reflected (Finding 3).
+  3. **Rewrite the `docs/ARCHITECTURE.md` "Crate Architecture" + "Vault Creation Flow" sections** so they describe the v0.5.0 surface (typed items, settings.enc, device auth boundary, server crate, extension WASM) rather than the v0.1.0 freeze (Finding 10).
+
+The codebase itself is well-documented — `crates/{relicario-core,relicario-cli}/ARCHITECTURE.md`, `extension/ARCHITECTURE.md`, and `docs/architecture/overview.md` are detailed and current. The drift is concentrated in **the top-level entry-point docs** (`README.md`, `CLAUDE.md`, `docs/ARCHITECTURE.md`) and in the SECURITY.md / overview.md edges.
+
+---
+
+## Findings
+
+### Finding 1 — `relicario-server` crate is invisible in cross-codebase docs
+
+**File:** `docs/architecture/overview.md` (lines 14–48 — "The three codebases" + table)
+**Issue:** The repo now has **four** Rust crates (`relicario-core`, `relicario-cli`, `relicario-wasm`, `relicario-server`) plus the extension. The framing "The three codebases" + accompanying ASCII diagram + four-row table all predate the May 2026 server crate. `relicario-server` is the pre-receive hook binary that enforces device-signature verification — load-bearing for the device-auth model that SECURITY.md already advertises.
+**Fix:** Re-title the section ("The four codebases" or "The relicario codebases"), add a server box to the diagram, add a row to the table. The role is "Pre-receive Git hook that verifies commit signatures against `.relicario/devices.json` and `.relicario/revoked.json`".
+**Severity:** must-fix-before-v0.5.0
+**Status:** Fixed in `ca059e7` (PM follow-up, 2026-05-02): "four codebases" framing, ASCII diagram fans core out to cli + server + wasm, table row added, build matrix gains `cargo build -p relicario-server`, "Where to look next" points at server src + design spec.
+
+---
+
+### Finding 2 — `CLAUDE.md` project-structure tree omits `relicario-server`
+
+**File:** `CLAUDE.md` (lines 26–54)
+**Issue:** The `crates/` tree only lists `relicario-core/`, `relicario-cli/`, `relicario-wasm/`. `relicario-server/` is missing. Since CLAUDE.md is the project-level summary every Claude session reads, this is the highest-leverage staleness.
+**Fix:** Add a fourth crate entry for `relicario-server/` with `src/main.rs # pre-receive hook: verify_commit + generate_hook`.
+**Severity:** must-fix-before-v0.5.0
+**Status:** Fixed in `8fd9a05` (PM follow-up, 2026-05-02 with user approval): added `relicario-server/` entry to project tree.
+
+---
+
+### Finding 3 — `CLAUDE.md` Roadmap is severely stale
+
+**File:** `CLAUDE.md` (lines 91–93)
+**Issue:** Says `Next: WASM build + Chrome MV3 browser extension (Plan 2). Then mobile (Rust core compiles to ARM).` Plan 2 (extension) shipped, then Plans 1A-1C, 3A (backup), 3B (LastPass), Plan 4 (security fixes + device auth), and Phases 1-2B of the fullscreen UX redesign all shipped. The current "next thing" per project memory is v0.5.0 polish + harden plus Phase 3/4 of fullscreen UX.
+**Fix:** Replace with a current-state Roadmap line (e.g. `Next: v0.5.0 polish + harden, then Phase 3 (vault tab shell). Mobile (ARM) and recovery QR remain on the roadmap.`).
+**Severity:** must-fix-before-v0.5.0
+**Status:** Fixed in `8fd9a05` (PM follow-up, 2026-05-02 with user approval): replaced with the v0.5.0 / Phases 3-4 / 1C-γ / LastPass / mobile / recovery-QR picture.
+
+---
+
+### Finding 4 — `CLAUDE.md` says "Item IDs are random 8-char hex"
+
+**File:** `CLAUDE.md` (line 79)
+**Issue:** Audit M8 bumped `ItemId`/`FieldId` to 16-char hex (64 bits). Verified against `crates/relicario-core/src/ids.rs:3-4, 35-37` and `tests/integration` — they're 16 hex chars. The same line also doesn't mention that `AttachmentId` was bumped to 32 hex chars / 128 bits (audit I2/B4).
+**Fix:** Change to: `Item IDs and Field IDs are random 16-char hex strings (64 bits of OsRng entropy). AttachmentIds are content-addressed: first 32 hex chars of SHA-256(plaintext) (128 bits, audit I2/B4).`
+**Severity:** must-fix-before-v0.5.0
+**Status:** Fixed in `8fd9a05` (PM follow-up, 2026-05-02 with user approval): now reads "Item IDs and Field IDs are random 16-char hex strings (64 bits of OsRng entropy). AttachmentIds are content-addressed: first 32 hex chars of SHA-256 over the plaintext (128 bits)."
+
+---
+
+### Finding 5 — `docs/architecture/overview.md` conventions table also says "8-char hex"
+
+**File:** `docs/architecture/overview.md` (line 180)
+**Issue:** Same M8 bump; the conventions table at line 180 said `Item IDs are random 8-char hex`.
+**Fix:** Update to 16-char hex / 64 bits, and bump the AttachmentId row to mention the 128-bit width.
+**Severity:** must-fix-before-v0.5.0
+**Status:** Fixed inline in `docs/architecture/overview.md`
+
+---
+
+### Finding 6 — `README.md` uses obsolete `entries/` directory layout
+
+**File:** `README.md` (lines 36, 117–118, 147–149)
+**Issue:** References to `entries/*.enc` and the `entry.rs` module are pre-typed-items vocabulary. The on-disk layout is now `items/<id>.enc` + `attachments/<item-id>/<aid>.enc` + `settings.enc`; the core module is `item.rs` + `item_types/`. The README is the security proof and the first thing visitors read — getting the on-disk shape wrong hurts the legibility-as-security pitch.
+**Fix:** Replace `entries/` with `items/`. Add `settings.enc`, `attachments/<item-id>/<aid>.enc`, and (for device-auth) `revoked.json`. Rewrite the `crates/` tree to match the actual seven-module shape and add `relicario-wasm` and `relicario-server`. Update item-ID width to 16-char hex.
+**Severity:** must-fix-before-v0.5.0
+**Status:** Fixed inline in `README.md`
+
+---
+
+### Finding 7 — `README.md` Roadmap lists shipped features as upcoming
+
+**File:** `README.md` (lines 184–192)
+**Issue:** All of these are checked off in real life but unchecked in the doc: WASM/Chrome extension, secure notes, secure document storage, LastPass import, Firefox extension. Only Bitwarden/1Password import, the unlock daemon, mobile, and Safari are still unstarted.
+**Fix:** Mark the shipped items as `[x]`; add Firefox WebExtension, typed items, backup/restore, LastPass CSV import, and device authentication as completed; keep Bitwarden/1Password import, unlock daemon, mobile, Safari as open.
+**Severity:** must-fix-before-v0.5.0
+**Status:** Fixed inline in `README.md`
+
+---
+
+### Finding 8 — `docs/ARCHITECTURE.md` ASCII vault layout uses `entries/` and lacks settings/attachments/revoked
+
+**File:** `docs/ARCHITECTURE.md` (lines 45–53)
+**Issue:** Same staleness as README Finding 6. The "GIT SERVER (untrusted)" box shows only `manifest.enc` + `entries/<id>.enc` + `.relicario/{salt,params.json,devices.json}`. Missing: `settings.enc`, `attachments/<item-id>/<aid>.enc`, `revoked.json`. ID lengths are 8-char hex (`a1b2c3d4`) instead of 16-char hex.
+**Fix:** Update box to current layout including settings.enc, attachments tree, revoked.json, and 16-char IDs.
+**Severity:** must-fix-before-v0.5.0
+**Status:** Fixed inline in `docs/ARCHITECTURE.md`
+
+---
+
+### Finding 9 — `docs/ARCHITECTURE.md` "Crate Architecture" omits wasm + server crates
+
+**File:** `docs/ARCHITECTURE.md` (lines 208–235)
+**Issue:** The bottom box of the "Crate Architecture" diagram says `Future: relicario-wasm wraps this for browser extension` and `Future: JNI/Swift wrappers for Android/iOS`. WASM is no longer future — it shipped. The `relicario-server` crate isn't mentioned at all. The `relicario-core` module list inside the box still says `entry / Manifest / search`, predating the typed-items rewrite (`item`, `item_types/`, `settings`, `attachment`, `backup`, `device`).
+**Fix:** Replace the inner-box module names with the current set; remove the "Future: relicario-wasm" line and add a "Consumed by" line listing all three downstream crates including server.
+**Severity:** must-fix-before-v0.5.0
+**Status:** Fixed inline in `docs/ARCHITECTURE.md`
+
+---
+
+### Finding 10 — `docs/ARCHITECTURE.md` "Vault Creation Flow" doesn't reflect typed-items or settings.enc
+
+**File:** `docs/ARCHITECTURE.md` (lines 60–89)
+**Issue:** The vault-creation pipeline in this doc shows `master_key → XChaCha20-Poly1305 → manifest.enc` only. In reality `cmd_init` also encrypts and writes `settings.enc` (default `VaultSettings`). Field-history-tracked items, attachments, the `Item` envelope shape — none of these are in the flow doc. Without context on typed items, a new contributor reading this doc would have a v0.1-era model of the system.
+**Fix:** Add a settings.enc step to the flow; either expand the items section or note that the full item lifecycle is in `crates/relicario-core/ARCHITECTURE.md`.
+**Severity:** nice-to-have (the per-codebase ARCHITECTURE.md files are the source of truth; this top-level doc could just point at them)
+**Status:** Fixed in `76d092d` (PM follow-up, 2026-05-02): trim path. Added settings.enc as a parallel artifact in the encrypt step, then a short paragraph pointing at `crates/relicario-core/ARCHITECTURE.md` for the per-item lifecycle.
+
+---
+
+### Finding 11 — `docs/SECURITY.md` "Device registration was optional before v0.4.0" is undated/misleading
+
+**File:** `docs/SECURITY.md` (lines 60–62)
+**Issue:** Says `Device registration was optional before v0.4.0. With device auth enabled, all commits must be signed by a registered device.` But (a) v0.4.0 hasn't been tagged yet — the changelog goes v0.1.0 → v0.2.0 → "Unreleased", and the next tag-in-flight per project memory is v0.5.0; (b) per the v0.5.0 polish + harden spec, device-auth enforcement is **currently a no-op** because the pre-receive hook fix (S1) hasn't landed. Saying "all commits MUST be signed" is aspirational, not current.
+**Fix:** Reword to clarify (a) the actual version line (e.g. "Pre-v0.5.0 vaults can opt out by leaving `devices.json` empty"), AND (b) acknowledge that signature *enforcement* depends on the pre-receive hook being deployed and the S1 fix landing. Could just be a one-line caveat.
+**Severity:** must-fix-before-v0.5.0 (security-doc accuracy is part of the legibility pitch)
+**Status:** Fixed in `1342228` (PM follow-up, 2026-05-02 with user approval): dropped the "before v0.4.0" version line entirely (v0.4.0 was never tagged); replaced with a single line saying registration is optional but recommended for shared vaults. Enforcement story now lives in the Device Authentication section (see F12).
+
+---
+
+### Finding 12 — `docs/SECURITY.md` doesn't mention `relicario-server`
+
+**File:** `docs/SECURITY.md` (lines 44–51)
+**Issue:** The "Device Authentication" section refers to a "pre-receive hook" but never says it lives in `crates/relicario-server`, what binary the hook calls (`relicario-server verify-commit <sha>`), or how to install it (`relicario-server generate-hook`). For a self-hosted user reading this to decide whether to enable it, those are the two essential operational facts.
+**Fix:** Add a short paragraph naming the crate and the two subcommands, pointing to the design spec.
+**Severity:** nice-to-have
+**Status:** Fixed in `1342228` (PM follow-up, 2026-05-02): added paragraph naming the `relicario-server` crate, both subcommands (`generate-hook`, `verify-commit`), and the caveat that signed commits without the server hook provide authorship metadata only.
+
+---
+
+### Finding 13 — Foundational design spec's "Post-V1 Ideas" lists shipped features
+
+**File:** `docs/superpowers/specs/2026-04-11-relicario-design.md` (lines 351–361)
+**Issue:** This doc is explicitly historical (per `docs/architecture/overview.md` "Stale spec docs" disclaimer), so editing it as architecture would violate convention. Still worth flagging that "Post-V1 Ideas" lists secure notes, secure documents, mobile, LastPass import, Firefox extension, TOTP — most of which have shipped. Per project policy this is *informational only*; the spec is a time-stamped decision artifact.
+**Fix:** None — leave alone. If desired, prepend a one-line "Status: V1 shipped 2026-04-22; many Post-V1 ideas have since landed — see CHANGELOG.md" at the top of the file.
+**Severity:** informational
+**Status:** Fixed in `9c97f9f` (PM follow-up, 2026-05-02): added the optional one-line status banner at the top of the spec pointing at CHANGELOG.md and overview.md for current state. Body of the spec untouched per the "specs are frozen decision artifacts" convention.
+
+---
+
+### Finding 14 — Lowercase "relicario" in prose contexts
+
+**File:** `README.md` (line 67), `docs/ARCHITECTURE.md` (none found in prose), `docs/architecture/overview.md` (none found in prose), `docs/SECURITY.md` (none found in prose)
+**Issue:** Per CLAUDE.md, "Relicario" should be capitalized in prose. A search across the audit-scope docs finds no uppercase-violations — most prose lowercase usages are in code paths (`.relicario/`, `relicario init`, `relicario-core`) which are correctly lowercase per the rule. The README at line 67 ("Relicario generates unique passwords per site") is correctly capitalized; line 26 ("Relicario embeds a random 256-bit secret") is correct. **No lowercase prose occurrences found.** This finding is "checked, no action needed."
+**Fix:** N/A
+**Severity:** informational
+**Status:** No action needed (recorded for completeness)
+
+---
+
+## Inline-fix verification
+
+### Initial pass (commit `900ccf1`):
+
+- `README.md` — vault layout (`items/`, `settings.enc`, `attachments/`), crate tree (added `relicario-wasm`, `relicario-server`, typed-items modules), ID width, Roadmap.
+- `docs/ARCHITECTURE.md` — git-server box (`items/`, `settings.enc`, `attachments/`, `revoked.json`), crate-architecture inner box (current core modules), removed "Future: relicario-wasm" line.
+- `docs/architecture/overview.md` — conventions table (16-char hex IDs, 128-bit AttachmentIds).
+
+### v0.5.0 PM follow-up pass (commits `ca059e7`, `8fd9a05`, `1342228`, `76d092d`, `9c97f9f`):
+
+- `docs/architecture/overview.md` — F1: four-codebases framing, ASCII diagram fans out to server, table row, build matrix, "Where to look next".
+- `CLAUDE.md` — F2: project tree gains `relicario-server`. F3: Roadmap line replaced. F4: Item/Field/Attachment ID widths and entropy noted.
+- `docs/SECURITY.md` — F11: dropped `before v0.4.0` line. F12: Device Authentication section now names the `relicario-server` crate and its subcommands, with the "without the hook, commits are advisory" caveat.
+- `docs/ARCHITECTURE.md` — F10: settings.enc shown alongside manifest.enc in the Vault Creation Flow; pointer added to per-crate ARCHITECTURE.md for typed-items detail.
+- `docs/superpowers/specs/2026-04-11-relicario-design.md` — F13: optional one-line "historical spec" status banner at top.
+
+No source files, `Cargo.lock`, or extension code were modified at any point.

docs/superpowers/coordination/archive/v0.5.0-dev-a-prompt.md

@@ -0,0 +1,128 @@
+# Dev A Kickoff Prompt — v0.5.0 Plan A (Security + Cleanup)
+
+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 Relicario v0.5.0 "polish + harden" release. Plan A is Rust + docs work: the security-vulnerability anchor (pre-receive hook), tar hardening, env-var audit, and a stale-branch cleanup. A PM in another terminal coordinates you with Dev B (extension UX). The user relays messages between terminals.
+
+## 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/v0.5.0-plan-a-security-cleanup
+cd ../relicario.plan-a
+pwd  # should print /home/alee/Sources/relicario.plan-a
+```
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario.plan-a`**. Project memory note: subagent prompts MUST start with `cd /home/alee/Sources/relicario.plan-a` — otherwise subagents commit to main.
+
+Today: 2026-05-02. Project rules in `CLAUDE.md` apply.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/specs/2026-05-02-v0.5.0-polish-harden-design.md` — spec (your scope is **S1, S2, S3, C1 only**)
+3. `docs/superpowers/plans/2026-05-02-v0.5.0-plan-a-security-cleanup.md` — your plan, execute task by task
+
+## Execution mode
+
+Use **subagent-driven-development** (per project memory's 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.plan-a
+```
+…before any other instruction. This is non-negotiable per project memory.
+
+## Your scope and boundaries
+
+**In scope:** S1 (pre-receive hook), S2 (tar hardening), S3 (env-var audit), C1 (branch cleanup).
+
+**Out of scope:** anything in Plan B (B1, P1-P4). If you trip over a Plan B issue or a new bug while doing your work, file it via a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- S1 is HIGH-severity security. Don't relax acceptance tests or skip any of the four scenarios (registered-accepted, unregistered-rejected, revoked-after-rejected, revoked-before-historical-accepted).
+- C1 is git-destructive (`git branch -D`). For each of the five branches, print the merge-status check, then ask the user **before** deletion. Do not batch the deletes.
+- 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 three terminals. The user relays messages between them.
+
+**Emit at every task boundary** (when you complete a task, get blocked, or want to ask):
+
+```
+## STATUS UPDATE — DEV-A
+Time: <iso8601 like 2026-05-02T14:30:00-07:00>
+Branch: feature/v0.5.0-plan-a-security-cleanup
+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>
+```
+
+**Emit 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  (does work stop without an answer?)
+```
+
+**You'll receive (pasted by user)**: `## DIRECTIVE TO DEV-A` blocks from the PM. Acknowledge and act.
+
+## Authority within the plan
+
+You don't need PM permission to:
+- Execute task-to-task per the plan
+- Make implementation decisions consistent with the plan and 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 (per project rules)
+- Before opening the PR for review
+
+## Final steps before REVIEW-READY
+
+1. Full `cargo test` (workspace) — must be green
+2. `cargo build -p relicario-wasm --target wasm32-unknown-unknown` — must succeed
+3. `cargo clippy --workspace --all-targets -- -D warnings` — must succeed
+4. Push the branch: `git push -u origin feature/v0.5.0-plan-a-security-cleanup`
+5. Open PR: `gh pr create --base main --head feature/v0.5.0-plan-a-security-cleanup --title "v0.5.0 Plan A: security + cleanup" --body "$(cat <<'EOF'
+## Summary
+Implements Plan A for v0.5.0 polish + harden:
+- S1: pre-receive hook fix (HIGH-severity revocation/registered-device bypass)
+- S2: tar archive path-traversal hardening on backup restore
+- S3: RELICARIO_* env-var audit + cfg-gating of dev-only vars
+- C1: stale local branch cleanup
+
+Spec: docs/superpowers/specs/2026-05-02-v0.5.0-polish-harden-design.md
+Plan: docs/superpowers/plans/2026-05-02-v0.5.0-plan-a-security-cleanup.md
+
+## Test plan
+- [x] cargo test (workspace) green
+- [x] cargo build -p relicario-wasm --target wasm32-unknown-unknown
+- [x] cargo clippy --workspace --all-targets -- -D warnings
+- [ ] PM review
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"`
+6. Emit `## 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/v0.5.0-plan-a-security-cleanup`), then start Task 1 of Plan A.

docs/superpowers/coordination/archive/v0.5.0-dev-b-prompt.md

@@ -0,0 +1,138 @@
+# Dev B Kickoff Prompt — v0.5.0 Plan B (Extension UX)
+
+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 Relicario v0.5.0 "polish + harden" release. Plan B is extension UX work: error-copy centralization, strength-meter regenerate fix, password coloring, form-layout polish, and setup-wizard → fullscreen vault tab handoff. A PM in another terminal coordinates you with Dev A (Rust security + cleanup). The user relays messages between terminals.
+
+## 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/v0.5.0-plan-b-extension-ux
+cd ../relicario.plan-b
+pwd  # should print /home/alee/Sources/relicario.plan-b
+```
+
+**ALL subsequent work happens in `/home/alee/Sources/relicario.plan-b`**. Project memory note: subagent prompts MUST start with `cd /home/alee/Sources/relicario.plan-b` — otherwise subagents commit to main.
+
+Today: 2026-05-02. Project rules in `CLAUDE.md` apply.
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/specs/2026-05-02-v0.5.0-polish-harden-design.md` — spec (your scope is **B1, P1, P2, P3, P4 only**; B2 is folded into P4)
+3. `docs/superpowers/plans/2026-05-02-v0.5.0-plan-b-extension-ux.md` — your plan, execute task by task
+4. `docs/superpowers/specs/2026-05-01-password-coloring-design.md` — spec for P1 (already inlined into your plan, this is the reference design)
+
+## Execution mode
+
+Use **subagent-driven-development** (per project memory's 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.plan-b
+```
+…before any other instruction. This is non-negotiable per project memory.
+
+## Your scope and boundaries
+
+**In scope:** B1 (strength meter regenerate desync), P4 (error copy centralization, subsumes B2), P1 (password coloring inlined), P3 (form layout envelope), P2 (setup → fullscreen tab handoff).
+
+**Out of scope:** anything in Plan A (S1, S2, S3, C1). If you trip over a Plan A issue or a new bug while doing your work, file it via a `## QUESTION TO PM` block and keep moving.
+
+**Hard rules:**
+- Don't ship a UI surface that still leaks raw `snake_case` error codes — P4's whole point is centralizing this.
+- For P3, the spec recommends Approach A (envelope constraint). The plan codifies that. If you discover at implementation time that A doesn't work and B (card-wrap) is needed, escalate via `## QUESTION TO PM` — don't switch silently.
+- 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 three terminals. The user relays messages between them.
+
+**Emit at every task boundary** (when you complete a task, get blocked, or want to ask):
+
+```
+## STATUS UPDATE — DEV-B
+Time: <iso8601 like 2026-05-02T14:30:00-07:00>
+Branch: feature/v0.5.0-plan-b-extension-ux
+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>
+```
+
+**Emit 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  (does work stop without an answer?)
+```
+
+**You'll receive (pasted by user)**: `## DIRECTIVE TO DEV-B` blocks from the PM. Acknowledge and act.
+
+## Authority within the plan
+
+You don't need PM permission to:
+- Execute task-to-task per the plan
+- Make implementation decisions consistent with the plan and 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 (per project rules)
+- For P3, if Approach A doesn't work and you need to switch to B
+- Before opening the PR for review
+
+## Final steps before REVIEW-READY
+
+1. Extension test suite green: `cd extension && pnpm test`
+2. Extension build green: `cd extension && pnpm build`
+3. WASM build still green (sanity): `cd .. && cargo build -p relicario-wasm --target wasm32-unknown-unknown`
+4. Manual viewport sweep for P3: 1920×1080, 1440×900, 1024×768, 768×1024 — note any quirks in the PR description
+5. Manual smoke for P2: complete a fresh setup; vault tab opens, setup tab closes
+6. Push the branch: `git push -u origin feature/v0.5.0-plan-b-extension-ux`
+7. Open PR: `gh pr create --base main --head feature/v0.5.0-plan-b-extension-ux --title "v0.5.0 Plan B: extension UX" --body "$(cat <<'EOF'
+## Summary
+Implements Plan B for v0.5.0 polish + harden:
+- P4: centralized ERROR_COPY map (subsumes B2 vault_locked leak)
+- B1: strength-meter regenerate desync fix (input event dispatch)
+- P1: password coloring (per the 2026-05-01 spec)
+- P3: form-layout envelope constraint (Approach A)
+- P2: setup wizard → fullscreen vault tab handoff
+
+Spec: docs/superpowers/specs/2026-05-02-v0.5.0-polish-harden-design.md
+Plan: docs/superpowers/plans/2026-05-02-v0.5.0-plan-b-extension-ux.md
+
+## Test plan
+- [x] pnpm test green
+- [x] pnpm build green
+- [x] cargo build -p relicario-wasm green
+- [x] Manual viewport sweep — see notes below
+- [x] Manual setup-flow smoke — vault tab opens, setup closes
+- [ ] PM review
+
+### Viewport sweep notes
+<fill in any quirks observed at each resolution; "none" is acceptable>
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"`
+8. Emit `## 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/v0.5.0-plan-b-extension-ux`), then start Task 1 of Plan B (P4: error-copy map).

docs/superpowers/coordination/archive/v0.5.0-pm-prompt.md

@@ -0,0 +1,113 @@
+# PM Kickoff Prompt — v0.5.0 Polish + Harden
+
+Paste everything below the `---` line into a fresh Claude Code terminal as the first user message.
+
+---
+
+You are the **project manager** for the Relicario v0.5.0 "polish + harden" release. Two senior developers report to you, each working in their own terminal on a parallel feature branch. The user runs all three 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-02. Project rules in `CLAUDE.md` apply (Spanish flourish, capitalization, autonomy defaults, never run git-destructive commands without asking).
+
+## Required reading (in order)
+
+1. `CLAUDE.md` — project rules
+2. `docs/superpowers/specs/2026-05-02-v0.5.0-polish-harden-design.md` — the bundle spec
+3. `docs/superpowers/plans/2026-05-02-v0.5.0-plan-a-security-cleanup.md` — Dev A's plan (Rust + cleanup)
+4. `docs/superpowers/plans/2026-05-02-v0.5.0-plan-b-extension-ux.md` — Dev B's plan (extension UX)
+5. `docs/superpowers/audits/2026-05-02-doc-audit.md` — your direct work (8 proposed findings still need action; 6 trivial fixes already merged in commit `900ccf1`)
+
+## Your authority
+
+- Approve or deny scope changes from devs
+- Review and merge PRs from `feature/v0.5.0-plan-a-security-cleanup` and `feature/v0.5.0-plan-b-extension-ux`
+- **Drive the doc-audit follow-ups directly** (the 8 proposed findings) — this is your hands-on work
+- Write the `CHANGELOG.md` entry for v0.5.0
+- Tag `v0.5.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 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`).
+
+## Judgment calls in the plans worth flagging
+
+The subagents who drafted the plans flagged these decisions for your awareness:
+
+- **Plan A:** `safe_unpack_git_archive` was moved from `relicario-cli` to `relicario-core` so integration tests can reach it (matches the bytes-in/bytes-out core philosophy). Tar-bomb test sets the *header's* claimed size to 2 GiB rather than allocating 1 TiB. Adds `regex` as a runtime dep of `relicario-server`.
+- **Plan B:** P1 (password coloring) was *inlined* into Plan B rather than referenced. P3 went with Approach A (envelope constraint, not card-wrap). P4 keeps `humanizeError` as a thin shell for non-snake_case translators.
+
+If any of these conflict with your judgment, raise it with the user before kickoff.
+
+## Coordination protocol
+
+You are one of three terminals. The user relays messages between them.
+
+**You receive (pasted by user):** a `## STATUS UPDATE — DEV-A` or `## STATUS UPDATE — DEV-B` block, or a `## QUESTION TO PM — DEV-X` block.
+
+**You emit (for user to paste back):** a `## DIRECTIVE TO DEV-A` (or `DEV-B`) block. Format:
+
+```
+## DIRECTIVE TO DEV-A
+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.5.0
+Dev A: <task X of Y, status>
+Dev B: <task X of Y, status>
+PM: <which doc finding, status>
+Blockers: <list, or "none">
+Next milestone: <e.g., "Dev A REVIEW-READY", "tag v0.5.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
+4. If green: post `Action: MERGE-APPROVED` and run `gh pr merge --merge` (no squash — git history is preserved per project rule)
+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.
+
+## Doc-audit follow-ups (your direct work)
+
+The 8 proposed findings in `docs/superpowers/audits/2026-05-02-doc-audit.md` are yours. Pick up while the devs are working in parallel. Pay particular attention to:
+
+1. `relicario-server` is invisible in cross-codebase docs (`docs/architecture/overview.md`, `CLAUDE.md` project tree)
+2. `CLAUDE.md` Roadmap line is stale ("Next: WASM extension (Plan 2)")
+3. `docs/SECURITY.md` overstates current device-auth enforcement — note that S1 is the fix that makes this true
+
+For findings that touch `CLAUDE.md`, propose the change in a status block to the user — don't edit it without approval.
+
+## Pre-tag checklist
+
+Before tagging v0.5.0:
+
+- [ ] `feature/v0.5.0-plan-a-security-cleanup` merged to main
+- [ ] `feature/v0.5.0-plan-b-extension-ux` merged to main
+- [ ] All 8 doc-audit findings actioned (fixed, deferred, or dropped)
+- [ ] `CHANGELOG.md` entry for v0.5.0 written
+- [ ] `cargo test` green on main
+- [ ] `cargo build -p relicario-wasm --target wasm32-unknown-unknown` green
+- [ ] Extension build green (`cd extension && pnpm build`)
+- [ ] User-driven smoke test of the merged result
+- [ ] Pre-v0.3.0 manual test walk done (`docs/test-checklists/2026-04-27-pre-v0.3.0-audit.md`) — bundles forward since v0.3.0 was never tagged
+- [ ] Explicit user approval to tag
+
+## First action
+
+After reading: emit a `## RELEASE STATUS` block confirming you've absorbed the spec, both plans, and the audit. Note the three judgment calls in the plans for the user's awareness, and propose your starting doc-audit finding. Wait for user input or a status update from a dev.

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

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

docs/superpowers/plans/2026-04-11-relicario-core-cli.md

@@ -1,4 +1,4 @@
-# relicario Core + CLI Implementation Plan
+# Relicario Core + CLI Implementation Plan
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 

docs/superpowers/plans/2026-04-12-relicario-credential-capture.md

@@ -1,4 +1,4 @@
-# relicario Credential Capture Implementation Plan
+# Relicario Credential Capture Implementation Plan
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 

docs/superpowers/plans/2026-04-12-relicario-firefox-extension.md

@@ -1,4 +1,4 @@
-# relicario Firefox Extension Port Implementation Plan
+# Relicario Firefox Extension Port Implementation Plan
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 

docs/superpowers/plans/2026-04-12-relicario-init-wizard.md

@@ -1,8 +1,8 @@
-# relicario Vault Initialization Wizard Implementation Plan
+# Relicario Vault Initialization Wizard Implementation Plan
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 
-**Goal:** Build a browser-based wizard that creates a new relicario vault, pushes it to Gitea/GitHub via API, downloads the reference image, and optionally configures the Chrome extension.
+**Goal:** Build a browser-based wizard that creates a new Relicario vault, pushes it to Gitea/GitHub via API, downloads the reference image, and optionally configures the Chrome extension.
 
 **Architecture:** Single HTML page (`extension/setup.html`) bundled by webpack as a new entry point. Reuses the existing git API layer and WASM module. New `embed_image_secret` function added to the WASM crate. The wizard runs entirely client-side — all crypto happens in the browser via WASM.
 

docs/superpowers/plans/2026-04-12-relicario-wasm-extension.md

@@ -1,4 +1,4 @@
-# relicario WASM + Chrome MV3 Extension Implementation Plan
+# Relicario WASM + Chrome MV3 Extension Implementation Plan
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 

docs/superpowers/plans/2026-04-20-relicario-extension-1c-alpha.md

@@ -1,4 +1,4 @@
-# relicario Extension 1C-α (Foundation) Implementation Plan
+# Relicario Extension 1C-α (Foundation) Implementation Plan
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 

docs/superpowers/plans/2026-04-24-relicario-gen-ux-redesign.md

@@ -0,0 +1,908 @@
+# Generator UX 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 (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the right-anchored popover (which clips off the popup edge) with an inline panel injected into the form below the password row. Trigger becomes ✨; lowercase form labels with a gold required-marker.
+
+**Architecture:** The popover module gets renamed (`generator-popover.ts` → `generator-panel.ts`) and rewritten: same knob → message logic, but DOM mounts inside a passed parent element instead of `document.body`, and the action row varies by context (`fill-field` for the login form's password input, `configure-defaults` for the vault settings screen). Label polish is a single CSS rule update plus an `<span class="req">` wrap around the `*` markers in 6 type forms.
+
+**Tech Stack:** TypeScript, vitest, webpack, plain CSS (no preprocessor).
+
+**Spec:** `docs/superpowers/specs/2026-04-24-relicario-gen-ux-redesign-design.md` (commit `9add305`).
+
+---
+
+## Task 1: Label polish — lowercase + gold required marker
+
+**Files:**
+- Modify: `extension/src/popup/styles.css` (the `.label` rule + add `.req` rule)
+- Modify: `extension/src/popup/components/types/login.ts` (1 markup change at line ~234)
+- Modify: `extension/src/popup/components/types/identity.ts` (1 markup change at line ~129)
+- Modify: `extension/src/popup/components/types/card.ts` (1 markup change at line ~169)
+- Modify: `extension/src/popup/components/types/key.ts` (2 markup changes at lines ~118, ~120)
+- Modify: `extension/src/popup/components/types/totp.ts` (2 markup changes at lines ~208, ~217)
+- Modify: `extension/src/popup/components/types/secure-note.ts` (1 markup change at line ~107)
+
+Working dir: `/home/alee/Sources/relicario`. Branch: main. Do NOT push.
+
+- [ ] **Step 1: Update the `.label` rule**
+
+In `extension/src/popup/styles.css`, find the `.label {` block (around line 36-45) and change `text-transform`, `letter-spacing`, and `font-weight`:
+
+Old:
+```css
+.label {
+  font-size: 11px;
+  font-weight: 600;
+  color: #8b949e;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  margin-bottom: 4px;
+}
+```
+
+New:
+```css
+.label {
+  font-size: 11px;
+  font-weight: 500;
+  color: #8b949e;
+  text-transform: lowercase;
+  letter-spacing: 0.02em;
+  margin-bottom: 4px;
+}
+```
+
+- [ ] **Step 2: Add the `.req` rule for gold required-marker**
+
+Append this rule directly after the `.label` rule (so it's adjacent and easy to find):
+
+```css
+.label .req {
+  color: #aa812a;
+  margin-left: 2px;
+  font-weight: 600;
+}
+```
+
+- [ ] **Step 3: Update markup in all 6 type forms**
+
+For each of the 7 occurrences of `title *</label>`, `key material *</label>`, `secret (base32) *</label>`, etc., replace the literal `*` with `<span class="req">*</span>`.
+
+Run a sed sweep across the 6 type files (preserves all other content, swaps just the trailing `*</label>` pattern):
+
+```bash
+sed -i 's| \*</label>| <span class="req">*</span></label>|g' \
+  extension/src/popup/components/types/login.ts \
+  extension/src/popup/components/types/identity.ts \
+  extension/src/popup/components/types/card.ts \
+  extension/src/popup/components/types/key.ts \
+  extension/src/popup/components/types/totp.ts \
+  extension/src/popup/components/types/secure-note.ts
+```
+
+- [ ] **Step 4: Verify the swap landed in every expected file**
+
+```bash
+grep -rn '<span class="req">\*</span></label>' extension/src/popup/components/types/
+```
+
+Expected: 8 hits across 6 files (login×1, identity×1, card×1, key×2, totp×2, secure-note×1).
+
+```bash
+grep -rn ' \*</label>' extension/src/popup/components/types/
+```
+
+Expected: no output (every literal `*</label>` should now be wrapped).
+
+- [ ] **Step 5: Run vitest**
+
+```bash
+cd extension && bun run test 2>&1 | tail -3
+```
+
+Expected: 124 passed (some test fixtures may render label HTML — verify they don't have hard-coded assertions on the literal `*` text or the `text-transform: uppercase` style. If any test fails on a label assertion, update the test to match the new markup).
+
+- [ ] **Step 6: Type-check**
+
+```bash
+cd extension && bunx tsc --noEmit
+```
+
+Expected: zero errors.
+
+- [ ] **Step 7: Commit**
+
+```bash
+cd /home/alee/Sources/relicario
+git add extension/src/popup/styles.css \
+        extension/src/popup/components/types/login.ts \
+        extension/src/popup/components/types/identity.ts \
+        extension/src/popup/components/types/card.ts \
+        extension/src/popup/components/types/key.ts \
+        extension/src/popup/components/types/totp.ts \
+        extension/src/popup/components/types/secure-note.ts
+git commit -m "$(cat <<'EOF'
+feat(ext/popup): lowercase form labels + gold required marker
+
+.label drops text-transform: uppercase and tightens letter-spacing.
+The `*` required marker gets wrapped in <span class="req"> so it
+picks up the gold accent color (matches palette refresh).
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 2: Rename module — `generator-popover` → `generator-panel`
+
+**Files (rename via git-mv):**
+- Rename: `extension/src/popup/components/generator-popover.ts` → `generator-panel.ts`
+- Rename: `extension/src/popup/components/__tests__/generator-popover.test.ts` → `generator-panel.test.ts`
+
+**Files modified (import path update only — function names stay the same in this task):**
+- `extension/src/popup/components/types/login.ts` (line 17 import)
+- `extension/src/popup/components/settings-vault.ts` (line 9 import)
+
+Working dir: `/home/alee/Sources/relicario`. Branch: main. Do NOT push.
+
+- [ ] **Step 1: git-mv source + test**
+
+```bash
+cd /home/alee/Sources/relicario
+git mv extension/src/popup/components/generator-popover.ts \
+       extension/src/popup/components/generator-panel.ts
+git mv extension/src/popup/components/__tests__/generator-popover.test.ts \
+       extension/src/popup/components/__tests__/generator-panel.test.ts
+```
+
+- [ ] **Step 2: Update the test file's import path**
+
+Edit `extension/src/popup/components/__tests__/generator-panel.test.ts` line 8:
+
+Old:
+```ts
+import { openGeneratorPopover, closeGeneratorPopover } from '../generator-popover';
+```
+
+New:
+```ts
+import { openGeneratorPopover, closeGeneratorPopover } from '../generator-panel';
+```
+
+(Only the path string changes; function names stay untouched in this task.)
+
+- [ ] **Step 3: Update login.ts import path**
+
+Edit `extension/src/popup/components/types/login.ts` line 17:
+
+Old:
+```ts
+import { openGeneratorPopover, closeGeneratorPopover } from '../generator-popover';
+```
+
+New:
+```ts
+import { openGeneratorPopover, closeGeneratorPopover } from '../generator-panel';
+```
+
+- [ ] **Step 4: Update settings-vault.ts import path**
+
+Edit `extension/src/popup/components/settings-vault.ts` line 9:
+
+Old:
+```ts
+import { openGeneratorPopover } from './generator-popover';
+```
+
+New:
+```ts
+import { openGeneratorPopover } from './generator-panel';
+```
+
+- [ ] **Step 5: Verify no stale references to `generator-popover` exist**
+
+```bash
+grep -rn "generator-popover" extension/src/
+```
+
+Expected: no output (all imports updated).
+
+- [ ] **Step 6: Run vitest**
+
+```bash
+cd extension && bun run test 2>&1 | tail -3
+```
+
+Expected: 124 passed (no behavioral change — just file rename).
+
+- [ ] **Step 7: Type-check**
+
+```bash
+cd extension && bunx tsc --noEmit
+```
+
+Expected: zero errors.
+
+- [ ] **Step 8: Commit**
+
+```bash
+cd /home/alee/Sources/relicario
+git add extension/src/popup/components/generator-panel.ts \
+        extension/src/popup/components/generator-popover.ts \
+        extension/src/popup/components/__tests__/generator-panel.test.ts \
+        extension/src/popup/components/__tests__/generator-popover.test.ts \
+        extension/src/popup/components/types/login.ts \
+        extension/src/popup/components/settings-vault.ts
+git commit -m "$(cat <<'EOF'
+refactor(ext/popup): rename generator-popover module to generator-panel
+
+Pure rename via git-mv (preserves history). Function names and behavior
+unchanged. Sets up the API rewrite in the next commit.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 3: Rewrite panel module + new CSS + caller updates + new tests
+
+**Files:**
+- Modify: `extension/src/popup/components/generator-panel.ts` (major rewrite — new API, inline mount, escape handler)
+- Modify: `extension/src/popup/components/__tests__/generator-panel.test.ts` (function rename + parent mount + 3 new tests)
+- Modify: `extension/src/popup/styles.css` (delete `.generator-popover` rules; add `.gen-trigger` + `.gen-panel` rules)
+- Modify: `extension/src/popup/components/types/login.ts` (✨ trigger button + new openGeneratorPanel call with `context: 'fill-field'`)
+- Modify: `extension/src/popup/components/settings-vault.ts` (✨ trigger button + new openGeneratorPanel call with `context: 'configure-defaults'`)
+
+Working dir: `/home/alee/Sources/relicario`. Branch: main. Do NOT push.
+
+This is the largest task. Steps walk through each file.
+
+### Step 1: Rewrite `generator-panel.ts`
+
+Read the current file first (Read tool) to understand the existing helper functions (`knobsFromRequest`, `requestFromKnobs`, `buildInnerHtml`, `wireInner`, `updateValidation`). KEEP those helpers AS-IS — they encode the knob→GeneratorRequest mapping which is correct. The rewrite only changes:
+
+1. Function rename: `openGeneratorPopover` → `openGeneratorPanel`. Same for `closeGeneratorPopover` → `closeGeneratorPanel`.
+2. New options interface (replaces `OpenPopoverOpts`):
+
+```ts
+export type GeneratorPanelContext = 'fill-field' | 'configure-defaults';
+
+export interface OpenPanelOpts {
+  parent: HTMLElement;       // mount target (form root or settings section)
+  trigger: HTMLElement;      // ✨ button (aria-expanded gets toggled here)
+  initial: GeneratorRequest;
+  context: GeneratorPanelContext;
+  onPicked?: (value: string) => void;  // required when context === 'fill-field'
+}
+```
+
+3. The `host` div is appended to `opts.parent` instead of `document.body`. Drop the `position: absolute / top / left` styling — just `parent.appendChild(host)`.
+4. The trigger gets `aria-expanded="true"` on open, `"false"` on close.
+5. Escape key closes the panel. Add a `document.addEventListener('keydown', escHandler)` on open; remove on close. Handler:
+   ```ts
+   const escHandler = (e: KeyboardEvent): void => {
+     if (e.key === 'Escape') closeGeneratorPanel();
+   };
+   ```
+6. Auto-generate on open: call `render()` then immediately `refreshPreview()` (the existing render does this already in the current popover — confirm it still does in the rewrite).
+7. Action row varies by context. Two HTML branches:
+   - `context === 'fill-field'`: `<button class="save-link" id="gen-save-default">↑ save these as default</button> <button class="btn" id="gen-cancel">cancel</button> <button class="btn btn-primary" id="gen-use">use</button>`
+   - `context === 'configure-defaults'`: `<button class="save-link" id="gen-save-default">↑ save these as default</button>` (no cancel/use)
+8. Clicking ✨ while panel open should close it. The trigger's click handler in the caller (login.ts / settings-vault.ts) checks `if (isGeneratorPanelOpen()) closeGeneratorPanel(); else openGeneratorPanel(...)`. Add `export function isGeneratorPanelOpen(): boolean { return activePanel !== null; }`.
+9. The "more ▾" disclosure: render only for `random` mode (BIP39 has no advanced knobs after the redesign). For `random`, advanced contains the `symbolCharset` toggle. Use `<details>` element for natural disclosure semantics:
+   ```html
+   <details class="more">
+     <summary>more ▾</summary>
+     <div class="more__advanced">
+       <!-- knobs go here -->
+     </div>
+   </details>
+   ```
+10. Element IDs that the existing tests assert on MUST be preserved verbatim: `#gen-kind-random`, `#gen-kind-bip39`, `#gen-length`, `#gen-lower`, `#gen-upper`, `#gen-digits`, `#gen-symbols`, `#gen-use`, `#gen-save-default`. The HTML structure can change, but these IDs stay.
+11. The `closeGeneratorPanel` function must clear:
+    - `activePanel = null`
+    - The `host` element from its parent (host.remove())
+    - `aria-expanded="false"` on the trigger
+    - `document.removeEventListener('keydown', escHandler)`
+    - Any pending debounce timer
+
+The full new `openGeneratorPanel` skeleton (use this as the structure; fill in the helper-function calls from the existing module which you keep unchanged):
+
+```ts
+let activePanel: {
+  host: HTMLElement;
+  trigger: HTMLElement;
+  cleanup: () => void;
+} | null = null;
+
+let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+export function openGeneratorPanel(opts: OpenPanelOpts): void {
+  closeGeneratorPanel();
+
+  const knobs = knobsFromRequest(opts.initial);
+  let currentPreview = '';
+
+  const host = document.createElement('div');
+  host.className = 'gen-panel';
+  opts.parent.appendChild(host);
+
+  opts.trigger.setAttribute('aria-expanded', 'true');
+
+  const escHandler = (e: KeyboardEvent): void => {
+    if (e.key === 'Escape') closeGeneratorPanel();
+  };
+  document.addEventListener('keydown', escHandler);
+
+  const cleanup = (): void => {
+    document.removeEventListener('keydown', escHandler);
+    if (debounceTimer !== null) {
+      clearTimeout(debounceTimer);
+      debounceTimer = null;
+    }
+    opts.trigger.setAttribute('aria-expanded', 'false');
+    host.remove();
+  };
+
+  activePanel = { host, trigger: opts.trigger, cleanup };
+
+  const render = (): void => {
+    host.innerHTML = buildInnerHtml(knobs, opts.context);
+    wireInner(opts);
+    refreshPreview();
+  };
+
+  const refreshPreview = (): void => {
+    /* existing debounced refresh logic — copy from current module */
+  };
+
+  /* wireInner needs `opts` for context (action row composition) and onPicked callback */
+
+  render();
+}
+
+export function closeGeneratorPanel(): void {
+  if (activePanel === null) return;
+  activePanel.cleanup();
+  activePanel = null;
+}
+
+export function isGeneratorPanelOpen(): boolean {
+  return activePanel !== null;
+}
+```
+
+Update `buildInnerHtml(knobs, context)` to:
+- Use `<details class="more">` for the disclosure
+- Render the action row based on `context`
+- Use the new `.gen-panel` child class names (no more `.gen-row`, `.gen-row__label`, etc. — see new CSS in Step 2)
+
+Keep `wireInner` as a closure-scoped helper inside `openGeneratorPanel` (NOT a parameter-taking function — it gets direct access to `opts`, `knobs`, `host`, `currentPreview` via the parent scope, just like the current popover does). Update its body to wire:
+- `#gen-use` click → `opts.onPicked?.(currentPreview); closeGeneratorPanel();`
+- `#gen-cancel` click → `closeGeneratorPanel();`
+- `#gen-save-default` click → existing logic (fetch settings, update with new defaults, send `update_vault_settings`); on success append a `<span class="save-link__toast">✓ saved</span>` to the save-link button and remove it after 1500 ms via `setTimeout`. Skeleton:
+
+```ts
+document.getElementById('gen-save-default')?.addEventListener('click', async () => {
+  const link = host.querySelector('#gen-save-default') as HTMLElement;
+  /* fetch settings, write generator_defaults, send update_vault_settings */
+  const settingsResp = await sendMessage({ type: 'get_vault_settings' });
+  if (!settingsResp.ok) return;
+  const settings = (settingsResp.data as { settings: VaultSettings }).settings;
+  settings.generator_defaults = requestFromKnobs(knobs);
+  const updateResp = await sendMessage({ type: 'update_vault_settings', settings });
+  if (!updateResp.ok) return;
+  /* append + auto-remove toast */
+  link.querySelector('.save-link__toast')?.remove();
+  const toast = document.createElement('span');
+  toast.className = 'save-link__toast';
+  toast.textContent = '✓ saved';
+  link.appendChild(toast);
+  setTimeout(() => toast.remove(), 1500);
+});
+```
+
+Apply this rewrite. The full file should still be ~250-350 lines; structure stays similar to the current popover.
+
+### Step 2: Replace popover CSS with panel CSS in `styles.css`
+
+Find the current `/* --- generator popover (β₂ slice 4) --- */` section (around line 592) and the `.gen-preview-line` rule below it. DELETE the entire block of `.generator-popover` rules (~80 lines).
+
+Add this new block in the same location:
+
+```css
+/* --- generator panel (gen-UX redesign) --- */
+
+.gen-trigger {
+  background: #7c5719;
+  color: #fff3cf;
+  border: none;
+  border-radius: 4px;
+  padding: 0 12px;
+  font-size: 16px;
+  cursor: pointer;
+  line-height: 1;
+  min-width: 38px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+.gen-trigger:hover { background: #aa812a; }
+.gen-trigger[aria-expanded="true"] { background: #aa812a; }
+
+.gen-panel {
+  background: #161b22;
+  border: 1px solid #aa812a;
+  border-radius: 6px;
+  padding: 11px;
+  margin: 6px 0;
+  font-size: 11px;
+  color: #c9d1d9;
+}
+.gen-panel .panel-toggle {
+  display: flex;
+  gap: 4px;
+  background: #21262d;
+  border-radius: 4px;
+  padding: 2px;
+  margin-bottom: 8px;
+}
+.gen-panel .panel-toggle button {
+  flex: 1;
+  background: transparent;
+  border: 0;
+  color: #8b949e;
+  padding: 5px;
+  font-size: 11px;
+  cursor: pointer;
+  border-radius: 3px;
+  font-weight: 600;
+}
+.gen-panel .panel-toggle button.active {
+  background: #aa812a;
+  color: #fff3cf;
+}
+.gen-panel .knob {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin: 6px 0;
+}
+.gen-panel .knob__label {
+  color: #8b949e;
+  width: 56px;
+  flex-shrink: 0;
+  font-size: 10px;
+}
+.gen-panel .knob__slider { flex: 1; }
+.gen-panel .knob__value {
+  font-family: ui-monospace, monospace;
+  min-width: 24px;
+  text-align: right;
+  color: #c9d1d9;
+}
+.gen-panel .classes {
+  display: flex;
+  gap: 8px;
+  font-size: 10px;
+  margin: 6px 0;
+  flex-wrap: wrap;
+  color: #8b949e;
+}
+.gen-panel .classes label {
+  display: flex;
+  align-items: center;
+  gap: 3px;
+  user-select: none;
+  cursor: pointer;
+}
+.gen-panel .preview {
+  background: #0d1117;
+  border: 1px solid #30363d;
+  border-radius: 4px;
+  padding: 8px 10px;
+  margin-top: 8px;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.gen-panel .preview__value {
+  flex: 1;
+  color: #f1cf6e;
+  font-family: ui-monospace, monospace;
+  font-size: 12px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.gen-panel .preview__regen {
+  background: transparent;
+  border: 0;
+  color: #8b949e;
+  cursor: pointer;
+  padding: 0 4px;
+  font-size: 14px;
+}
+.gen-panel .more {
+  color: #8b949e;
+  font-size: 10px;
+  margin-top: 6px;
+  cursor: pointer;
+  user-select: none;
+  padding: 2px 0;
+}
+.gen-panel .more summary {
+  list-style: none;
+  outline: none;
+}
+.gen-panel .more summary::-webkit-details-marker { display: none; }
+.gen-panel .more:hover { color: #d2ab43; }
+.gen-panel .more__advanced { margin-top: 6px; }
+.gen-panel .actions {
+  display: flex;
+  gap: 6px;
+  margin-top: 10px;
+  align-items: center;
+}
+.gen-panel .actions .save-link {
+  flex: 1;
+  background: transparent;
+  border: 0;
+  color: #8b949e;
+  cursor: pointer;
+  font-size: 10px;
+  text-align: left;
+  padding: 4px 0;
+  text-decoration: underline;
+  text-decoration-color: #30363d;
+  text-underline-offset: 2px;
+}
+.gen-panel .actions .save-link:hover {
+  color: #d2ab43;
+  text-decoration-color: #d2ab43;
+}
+.gen-panel .actions .save-link__toast {
+  color: #3fb950;
+  margin-left: 6px;
+  font-size: 10px;
+}
+
+/* keep .gen-preview-line — it's the summary-text in vault settings, separate from panel */
+```
+
+The pre-existing `.gen-preview-line` rule (around line 674) must stay — it's used by the vault-settings summary text, not the panel itself.
+
+### Step 3: Update `login.ts`
+
+Find the `gen-btn` markup (around line 243):
+
+Old:
+```ts
+<button class="btn" id="gen-btn" title="generate">gen</button>
+```
+
+New:
+```ts
+<button class="gen-trigger" id="gen-btn" type="button" title="generate password" aria-expanded="false">✨</button>
+```
+
+Find the click handler (around line 268):
+
+Old:
+```ts
+document.getElementById('gen-btn')?.addEventListener('click', (e) => {
+  const anchor = e.currentTarget as HTMLElement;
+  const initial = getState().generatorDefaults ?? DEFAULT_PASSWORD_REQUEST;
+  openGeneratorPopover({
+    anchor,
+    initial,
+    onPicked: (value) => {
+      const pw = document.getElementById('f-password') as HTMLInputElement | null;
+      if (pw) { pw.value = value; pw.type = 'text'; }
+    },
+  });
+});
+```
+
+New:
+```ts
+document.getElementById('gen-btn')?.addEventListener('click', (e) => {
+  const trigger = e.currentTarget as HTMLElement;
+  if (isGeneratorPanelOpen()) {
+    closeGeneratorPanel();
+    return;
+  }
+  const passwordRow = trigger.closest('.form-group') as HTMLElement | null;
+  if (!passwordRow) return;
+  const initial = getState().generatorDefaults ?? DEFAULT_PASSWORD_REQUEST;
+  openGeneratorPanel({
+    parent: passwordRow,  // panel mounts inside the password form-group
+    trigger,
+    initial,
+    context: 'fill-field',
+    onPicked: (value) => {
+      const pw = document.getElementById('f-password') as HTMLInputElement | null;
+      if (pw) { pw.value = value; pw.type = 'text'; }
+    },
+  });
+});
+```
+
+Update the import on line 17:
+
+Old:
+```ts
+import { openGeneratorPopover, closeGeneratorPopover } from '../generator-panel';
+```
+
+New:
+```ts
+import { openGeneratorPanel, closeGeneratorPanel, isGeneratorPanelOpen } from '../generator-panel';
+```
+
+### Step 4: Update `settings-vault.ts`
+
+Find the `configure-gen` button (around line 131):
+
+Old:
+```ts
+<button class="btn" id="configure-gen">configure ▾</button>
+```
+
+New:
+```ts
+<button class="gen-trigger" id="configure-gen" type="button" title="configure generator defaults" aria-expanded="false">✨</button>
+```
+
+Find the click handler (around line 196):
+
+Old:
+```ts
+document.getElementById('configure-gen')?.addEventListener('click', (e) => {
+  /* current popover open with onPicked that writes to vault settings */
+  ...
+  openGeneratorPopover({
+    anchor: e.currentTarget as HTMLElement,
+    initial: pendingSettings.generator_defaults,
+    /* ... onPicked writes to settings ... */
+  });
+});
+```
+
+New:
+```ts
+document.getElementById('configure-gen')?.addEventListener('click', (e) => {
+  const trigger = e.currentTarget as HTMLElement;
+  if (isGeneratorPanelOpen()) {
+    closeGeneratorPanel();
+    return;
+  }
+  const generatorSection = trigger.closest('.settings-section') as HTMLElement | null;
+  if (!generatorSection || pendingSettings === null) return;
+  openGeneratorPanel({
+    parent: generatorSection,
+    trigger,
+    initial: pendingSettings.generator_defaults,
+    context: 'configure-defaults',
+  });
+});
+```
+
+Update the import on line 9:
+
+Old:
+```ts
+import { openGeneratorPopover } from './generator-panel';
+```
+
+New:
+```ts
+import { openGeneratorPanel, closeGeneratorPanel, isGeneratorPanelOpen } from './generator-panel';
+```
+
+### Step 5: Update tests
+
+In `extension/src/popup/components/__tests__/generator-panel.test.ts`, multiple changes:
+
+1. Update import at line 8:
+```ts
+import { openGeneratorPanel, closeGeneratorPanel, isGeneratorPanelOpen } from '../generator-panel';
+```
+
+2. Update `setupAnchor()` to set up a parent + trigger in a way that matches the new API:
+```ts
+function setupMount(): { parent: HTMLElement; trigger: HTMLElement } {
+  document.body.innerHTML = `
+    <div id="parent">
+      <button id="trigger" aria-expanded="false">✨</button>
+    </div>
+  `;
+  return {
+    parent: document.getElementById('parent')!,
+    trigger: document.getElementById('trigger')!,
+  };
+}
+```
+
+3. Update each test's `openGeneratorPopover({ anchor, ... })` to `openGeneratorPanel({ parent, trigger, context: 'fill-field', onPicked, ...})`. For the `save-as-default` test, use `context: 'fill-field'` (the save-link is shown in both contexts). For tests that don't care about onPicked, pass `vi.fn()`.
+
+4. Update the selector `.generator-popover` → `.gen-panel` in tests that query for the panel host element (e.g., the "opens a popover" test asserts `document.querySelector('.generator-popover')` — change to `.gen-panel`).
+
+5. Add 3 new tests at the end of the `describe` block:
+
+```ts
+it('sets aria-expanded on the trigger when opened', async () => {
+  const { parent, trigger } = setupMount();
+  expect(trigger.getAttribute('aria-expanded')).toBe('false');
+  openGeneratorPanel({ parent, trigger, initial: DEFAULT_REQ, context: 'fill-field', onPicked: vi.fn() });
+  expect(trigger.getAttribute('aria-expanded')).toBe('true');
+  closeGeneratorPanel();
+  expect(trigger.getAttribute('aria-expanded')).toBe('false');
+});
+
+it('auto-generates a preview on open', async () => {
+  const { parent, trigger } = setupMount();
+  openGeneratorPanel({ parent, trigger, initial: DEFAULT_REQ, context: 'fill-field', onPicked: vi.fn() });
+  await new Promise((r) => setTimeout(r, 200));
+  const calls = vi.mocked(sendMessage).mock.calls.filter(
+    ([msg]) => (msg as { type: string }).type === 'generate_password',
+  );
+  expect(calls.length).toBeGreaterThan(0);
+});
+
+it('Escape key closes the panel', async () => {
+  const { parent, trigger } = setupMount();
+  openGeneratorPanel({ parent, trigger, initial: DEFAULT_REQ, context: 'fill-field', onPicked: vi.fn() });
+  await new Promise((r) => setTimeout(r, 50));
+  expect(isGeneratorPanelOpen()).toBe(true);
+  document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape' }));
+  expect(isGeneratorPanelOpen()).toBe(false);
+  expect(document.querySelector('.gen-panel')).toBeNull();
+});
+```
+
+### Step 6: Run the tests
+
+```bash
+cd extension && bun run test 2>&1 | tail -10
+```
+
+Expected: 127 passed (was 124, added 3 new tests). If a test fails:
+- Selector mismatch: confirm `.gen-panel` is the new host class and tests query that, not `.generator-popover`.
+- Mount target mismatch: confirm tests pass `parent`+`trigger` not `anchor`.
+- Save-link selector: still `#gen-save-default` (preserved per Step 1, item 10).
+
+### Step 7: Type-check
+
+```bash
+cd extension && bunx tsc --noEmit
+```
+
+Expected: zero errors. If errors:
+- `OpenPopoverOpts` is gone; tests/callers reference must use `OpenPanelOpts`. Should be caught by the import update.
+- `onPicked` is now optional in `OpenPanelOpts` — TS may complain at the call site if not passed. The `fill-field` context needs `onPicked`; configure-defaults doesn't.
+
+### Step 8: Build both bundles
+
+```bash
+cd extension && bun run build:all 2>&1 | tail -10
+```
+
+Expected: "compiled with 2 warnings" (WASM size only) for each of Chrome and Firefox.
+
+### Step 9: Commit
+
+```bash
+cd /home/alee/Sources/relicario
+git add extension/src/popup/components/generator-panel.ts \
+        extension/src/popup/components/__tests__/generator-panel.test.ts \
+        extension/src/popup/styles.css \
+        extension/src/popup/components/types/login.ts \
+        extension/src/popup/components/settings-vault.ts
+git commit -m "$(cat <<'EOF'
+feat(ext/popup): rewrite generator as inline panel with ✨ trigger
+
+The popover (which clipped off the popup edge) becomes an inline panel
+that mounts inside the form (login.ts) or settings section
+(settings-vault.ts). Trigger button is ✨ with aria-expanded toggling.
+Action row varies by context: fill-field has cancel+use; configure-
+defaults has only the save-default link. Escape key closes the panel.
+Tests adapted to new API; 3 new tests for aria-expanded, auto-generate,
+and Escape behavior.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 4: Build, full verification, manual smoke
+
+Working dir: `/home/alee/Sources/relicario`. Branch: main.
+
+- [ ] **Step 1: Run all test suites end to end**
+
+```bash
+cd /home/alee/Sources/relicario && cargo test --workspace 2>&1 | grep -E "test result" | tail -20
+cd /home/alee/Sources/relicario/extension && bun run test 2>&1 | tail -5
+cd /home/alee/Sources/relicario/extension && bunx tsc --noEmit 2>&1 | tail -5
+```
+
+Expected:
+- Cargo: every "test result" line shows `0 failed`. Total ~155.
+- Vitest: `Tests  127 passed (127)` (was 124; added 3 new generator-panel tests).
+- tsc: zero output (no errors).
+
+- [ ] **Step 2: Build both bundles**
+
+```bash
+cd /home/alee/Sources/relicario/extension && bun run build:all 2>&1 | tail -10
+```
+
+Expected: "compiled with 2 warnings" (WASM size only) for both Chrome and Firefox bundles.
+
+- [ ] **Step 3: Final lint sweep — confirm no stale references to popover**
+
+```bash
+cd /home/alee/Sources/relicario && git grep -nE 'generator-popover|generatorPopover|openGeneratorPopover|closeGeneratorPopover|\.generator-popover' -- 'extension/src/' 'extension/setup.html'
+```
+
+Expected: zero output. The only remaining occurrences allowed are inside markdown specs/plans (`docs/`) — these document the historical name and should NOT be modified.
+
+- [ ] **Step 4: Manual smoke test (relay these instructions to the user)**
+
+Have the user reload the extension and walk through:
+
+  - **Login form:** Open popup → New → Login. Click ✨ button next to password input. Verify:
+    - Inline panel appears below the password row (not a clipped popover)
+    - Panel auto-fills with a generated preview immediately
+    - ✨ button shows gold-active state (`aria-expanded="true"`)
+    - Clicking length slider regenerates the preview after a brief debounce
+    - Toggling kind to "passphrase" switches knobs and regenerates
+    - "more ▾" disclosure expands to reveal symbol charset (random mode only)
+    - "use" button fills the password input and closes the panel
+    - "cancel" button closes the panel without committing
+    - Escape key closes the panel
+    - Clicking ✨ again while open closes the panel
+    - "↑ save these as default" link writes to vault settings (verify by reopening)
+  - **Vault settings:** Open ⚙ → vault settings → ✨ button next to generator preview. Verify:
+    - Inline panel appears inside the generator section
+    - No use/cancel buttons (configure-defaults context)
+    - "↑ save these as default" link works
+    - ✨ closes the panel
+  - **Polish:** All form labels are lowercase across all type forms. Required-field `*` markers are gold (`#aa812a`). Run through Login, SecureNote, Identity, Card, Key, TOTP forms briefly.
+
+- [ ] **Step 5: No close-out commit needed if all green**
+
+If steps 1-3 passed, the slice is complete via the prior 3 commits (label polish, rename, panel rewrite). If any fix was needed, commit as `fix(ext/popup): <description>`.
+
+---
+
+## Verification summary
+
+```bash
+cd /home/alee/Sources/relicario/extension && bun run build:all
+cd /home/alee/Sources/relicario && cargo test --workspace
+cd /home/alee/Sources/relicario/extension && bun run test
+cd /home/alee/Sources/relicario/extension && bunx tsc --noEmit
+git grep -nE 'generator-popover|generatorPopover|openGeneratorPopover|closeGeneratorPopover|\.generator-popover' -- 'extension/src/' 'extension/setup.html'
+```
+
+All five must succeed (grep returns nothing) for the slice to be complete.
+
+---
+
+## Notes for the implementer
+
+- **No worktree** — direct commits to main per project's single-maintainer flow.
+- **Order matters:** Task 1 (label polish) is independent and ships first because it's harmless and doesn't depend on the panel rewrite. Task 2 (rename) MUST come before Task 3 because Task 3's commit message references `generator-panel.ts`. Task 3 must come before Task 4.
+- **The `<details>` element** is the cleanest way to implement the "more ▾" disclosure — it's natively accessible and the CSS hides the default disclosure marker. Make sure the disclosure is conditionally rendered (only for random mode).
+- **Test ID preservation:** the existing test asserts on specific element IDs (`#gen-kind-random`, `#gen-length`, `#gen-use`, `#gen-save-default`, `#gen-lower` etc.). The rewrite must keep those IDs intact, even if surrounding markup changes. Check the test file before completing the rewrite.
+- **Don't add animation/transitions** — the spec explicitly defers those. Panel appears/disappears instantly.
+- **Don't add click-outside-to-close** — the spec explicitly excludes it.

docs/superpowers/plans/2026-04-24-relicario-logo-refresh.md

@@ -0,0 +1,578 @@
+# Logo Refresh + Extension Palette Shift Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the current arched-niche-with-blue-gem logo with a round chapel-style theca + fleur-de-lis finial in burnished gold/deep red, and shift the extension's primary accent from GitHub-blue to the matching gold ramp.
+
+**Architecture:** No new code paths or behavior changes — this is asset replacement (2 SVGs + 3 PNGs) and a static color palette swap across CSS + inline TS/HTML colors. The CLI/dark feel is preserved (backgrounds and text colors untouched). One CSS class rename (`sig-block--blue` → `sig-block--gold`) sweeps through the consumers + a test.
+
+**Tech Stack:** SVG (hand-authored), ImageMagick (`magick` — preferred per project memory) for SVG → PNG, CSS, TypeScript, vitest, webpack.
+
+**Spec:** `docs/superpowers/specs/2026-04-24-relicario-logo-refresh-design.md` (commit `4b7f1fd`).
+
+---
+
+## Task 1: Replace master logo SVG
+
+**Files:**
+- Modify: `extension/icons/relicario-logo.svg` (overwrite entirely)
+
+- [ ] **Step 1: Overwrite the master SVG**
+
+Replace the file contents with:
+
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 220 240" fill="none">
+  <defs>
+    <radialGradient id="redTheca" cx="0.4" cy="0.35">
+      <stop offset="0%" stop-color="#9a1a1a"/>
+      <stop offset="100%" stop-color="#3a0a0a"/>
+    </radialGradient>
+    <linearGradient id="goldRing" x1="0" x2="1">
+      <stop offset="0%" stop-color="#d2ab43"/>
+      <stop offset="50%" stop-color="#f5d97a"/>
+      <stop offset="100%" stop-color="#7c5719"/>
+    </linearGradient>
+    <linearGradient id="goldHi" x1="0" x2="1">
+      <stop offset="0%" stop-color="#fde9a8"/>
+      <stop offset="100%" stop-color="#d2ab43"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Pedestal (compact) -->
+  <ellipse cx="110" cy="226" rx="44" ry="5" fill="url(#goldRing)"/>
+  <rect x="78" y="212" width="64" height="14" rx="2" fill="url(#goldRing)"/>
+  <rect x="98" y="202" width="24" height="12" fill="url(#goldRing)"/>
+  <ellipse cx="110" cy="208" rx="14" ry="3" fill="#7c5719"/>
+  <ellipse cx="110" cy="202" rx="18" ry="4" fill="url(#goldRing)"/>
+
+  <!-- Body, bezel, theca -->
+  <circle cx="110" cy="130" r="72" fill="url(#goldRing)"/>
+  <path d="M 110 58 A 72 72 0 0 0 38 130" stroke="#fde9a8" stroke-width="2" fill="none" opacity="0.6"/>
+  <circle cx="110" cy="130" r="60" fill="#7c5719"/>
+  <circle cx="110" cy="130" r="56" fill="url(#redTheca)"/>
+  <ellipse cx="86" cy="108" rx="16" ry="7" fill="#ffffff" opacity="0.14" transform="rotate(-30 86 108)"/>
+
+  <!-- Asterisk gem with pinwheel facets -->
+  <g transform="translate(110, 130)">
+    <g transform="rotate(0)">
+      <path d="M 0 0 L -4.5 -3.5 C -5.5 -16, -3.5 -29, 0 -36 Z" fill="#f5d97a"/>
+      <path d="M 0 0 L  4.5 -3.5 C  5.5 -16,  3.5 -29, 0 -36 Z" fill="#8a5e1c"/>
+    </g>
+    <g transform="rotate(60)">
+      <path d="M 0 0 L -4.5 -3.5 C -5.5 -16, -3.5 -29, 0 -36 Z" fill="#f5d97a"/>
+      <path d="M 0 0 L  4.5 -3.5 C  5.5 -16,  3.5 -29, 0 -36 Z" fill="#8a5e1c"/>
+    </g>
+    <g transform="rotate(120)">
+      <path d="M 0 0 L -4.5 -3.5 C -5.5 -16, -3.5 -29, 0 -36 Z" fill="#f5d97a"/>
+      <path d="M 0 0 L  4.5 -3.5 C  5.5 -16,  3.5 -29, 0 -36 Z" fill="#8a5e1c"/>
+    </g>
+    <g transform="rotate(180)">
+      <path d="M 0 0 L -4.5 -3.5 C -5.5 -16, -3.5 -29, 0 -36 Z" fill="#f5d97a"/>
+      <path d="M 0 0 L  4.5 -3.5 C  5.5 -16,  3.5 -29, 0 -36 Z" fill="#8a5e1c"/>
+    </g>
+    <g transform="rotate(240)">
+      <path d="M 0 0 L -4.5 -3.5 C -5.5 -16, -3.5 -29, 0 -36 Z" fill="#f5d97a"/>
+      <path d="M 0 0 L  4.5 -3.5 C  5.5 -16,  3.5 -29, 0 -36 Z" fill="#8a5e1c"/>
+    </g>
+    <g transform="rotate(300)">
+      <path d="M 0 0 L -4.5 -3.5 C -5.5 -16, -3.5 -29, 0 -36 Z" fill="#f5d97a"/>
+      <path d="M 0 0 L  4.5 -3.5 C  5.5 -16,  3.5 -29, 0 -36 Z" fill="#8a5e1c"/>
+    </g>
+    <polygon points="0,-6 5.2,-3 5.2,3 0,6 -5.2,3 -5.2,-3" fill="#d2ab43" stroke="#7c5719" stroke-width="0.6"/>
+    <circle cx="-1.5" cy="-2" r="1.4" fill="#fff3cf"/>
+  </g>
+
+  <!-- Hinge collar -->
+  <rect x="98" y="50" width="24" height="10" rx="2" fill="url(#goldRing)"/>
+  <line x1="100" y1="55" x2="120" y2="55" stroke="#7c5719" stroke-width="0.8"/>
+
+  <!-- Fleur-de-lis -->
+  <g transform="translate(110, 50)">
+    <rect x="-3.5" y="-12" width="7" height="12" fill="url(#goldRing)"/>
+    <rect x="-16" y="-18" width="32" height="7" rx="1.5" fill="url(#goldRing)"/>
+    <rect x="-3" y="-19" width="6" height="9" rx="0.8" fill="#7c5719"/>
+    <path d="M 0 -18 Q -8 -36, -4 -54 Q -1 -62, 0 -64 Q 1 -62, 4 -54 Q 8 -36, 0 -18 Z" fill="url(#goldRing)"/>
+    <path d="M 0 -22 Q -2.5 -36, 0 -52 Q 2.5 -36, 0 -22 Z" fill="#7c5719" opacity="0.55"/>
+    <circle cx="0" cy="-66" r="2.5" fill="url(#goldHi)"/>
+    <path d="M -4 -18 Q -22 -22, -26 -38 Q -22 -50, -16 -50 Q -16 -38, -10 -32 Q -6 -28, -4 -28 Z" fill="url(#goldRing)"/>
+    <ellipse cx="-25" cy="-44" rx="2" ry="3" fill="#7c5719" opacity="0.4" transform="rotate(-20 -25 -44)"/>
+    <path d="M  4 -18 Q  22 -22,  26 -38 Q  22 -50,  16 -50 Q  16 -38,  10 -32 Q  6 -28,  4 -28 Z" fill="url(#goldRing)"/>
+    <ellipse cx="25" cy="-44" rx="2" ry="3" fill="#7c5719" opacity="0.4" transform="rotate(20 25 -44)"/>
+  </g>
+</svg>
+```
+
+- [ ] **Step 2: Verify it parses**
+
+Run: `xmllint --noout extension/icons/relicario-logo.svg && echo OK`
+Expected: `OK`
+
+If `xmllint` isn't installed, fallback: `python3 -c "import xml.etree.ElementTree as T; T.parse('extension/icons/relicario-logo.svg'); print('OK')"`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add extension/icons/relicario-logo.svg
+git commit -m "feat(icons): replace master logo with reliquary theca + fleur"
+```
+
+---
+
+## Task 2: Replace 16 px logo SVG
+
+**Files:**
+- Modify: `extension/icons/relicario-logo-16.svg` (overwrite entirely)
+
+- [ ] **Step 1: Overwrite the 16 px SVG**
+
+Replace the file contents with:
+
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="none">
+  <defs>
+    <radialGradient id="redThecaSm" cx="0.4" cy="0.35">
+      <stop offset="0%" stop-color="#9a1a1a"/>
+      <stop offset="100%" stop-color="#3a0a0a"/>
+    </radialGradient>
+    <linearGradient id="goldRingSm" x1="0" x2="1">
+      <stop offset="0%" stop-color="#d2ab43"/>
+      <stop offset="50%" stop-color="#f5d97a"/>
+      <stop offset="100%" stop-color="#7c5719"/>
+    </linearGradient>
+  </defs>
+
+  <!-- Body + theca -->
+  <circle cx="8" cy="9" r="6.5" fill="url(#goldRingSm)"/>
+  <circle cx="8" cy="9" r="4.8" fill="url(#redThecaSm)"/>
+
+  <!-- Asterisk-as-3-bars -->
+  <g transform="translate(8, 9)" stroke="#f5d97a" stroke-width="1.2" stroke-linecap="round">
+    <line x1="0" y1="-3" x2="0" y2="3"/>
+    <line x1="-2.6" y1="-1.5" x2="2.6" y2="1.5"/>
+    <line x1="-2.6" y1="1.5" x2="2.6" y2="-1.5"/>
+  </g>
+  <circle cx="8" cy="9" r="0.7" fill="#fff3cf"/>
+
+  <!-- Fleur (3 tips) -->
+  <path d="M 8 0 L 7.2 2.5 L 8.8 2.5 Z" fill="url(#goldRingSm)"/>
+  <path d="M 5.6 2.5 L 6.5 1 L 7.3 2.5 Z" fill="url(#goldRingSm)"/>
+  <path d="M 10.4 2.5 L 9.5 1 L 8.7 2.5 Z" fill="url(#goldRingSm)"/>
+</svg>
+```
+
+- [ ] **Step 2: Verify it parses**
+
+Run: `xmllint --noout extension/icons/relicario-logo-16.svg && echo OK`
+Expected: `OK`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add extension/icons/relicario-logo-16.svg
+git commit -m "feat(icons): replace 16px logo with bare medallion variant"
+```
+
+---
+
+## Task 3: Regenerate icon PNGs
+
+**Files:**
+- Modify: `extension/icons/icon-16.png` (regenerate)
+- Modify: `extension/icons/icon-48.png` (regenerate)
+- Modify: `extension/icons/icon-128.png` (regenerate)
+
+ImageMagick (`magick`, NOT `rsvg-convert`) is the project preference per memory. Density flag controls source-rasterization sharpness; 384 = 4× standard 96dpi.
+
+- [ ] **Step 1: Generate icon-16.png from the 16 px SVG**
+
+Run:
+```bash
+magick -background none extension/icons/relicario-logo-16.svg -resize 16x16 extension/icons/icon-16.png
+```
+
+Verify: `file extension/icons/icon-16.png`
+Expected: `PNG image data, 16 x 16, ...`
+
+- [ ] **Step 2: Generate icon-48.png from the master SVG**
+
+The master SVG has aspect ratio 220:240 (slightly taller than 1:1 because of the pedestal). ImageMagick's `-resize 48x48` preserves aspect ratio by default — output will be 44 × 48 (constrained by height). Use `-extent 48x48 -gravity center` to pad to a 48 × 48 square with transparent margins.
+
+Run:
+```bash
+magick -background none -density 384 extension/icons/relicario-logo.svg \
+  -resize 48x48 -gravity center -extent 48x48 \
+  extension/icons/icon-48.png
+```
+
+Verify: `file extension/icons/icon-48.png`
+Expected: `PNG image data, 48 x 48, ...`
+
+- [ ] **Step 3: Generate icon-128.png from the master SVG**
+
+Run:
+```bash
+magick -background none -density 384 extension/icons/relicario-logo.svg \
+  -resize 128x128 -gravity center -extent 128x128 \
+  extension/icons/icon-128.png
+```
+
+Verify: `file extension/icons/icon-128.png`
+Expected: `PNG image data, 128 x 128, ...`
+
+- [ ] **Step 4: Visual sanity check**
+
+Open each PNG to confirm the gold/red logo is visible at the right size. From the terminal:
+```bash
+ls -la extension/icons/icon-*.png
+```
+Expected file sizes: icon-16 < icon-48 < icon-128. Each non-empty.
+
+If a viewer is available (eog, feh, xdg-open), open `extension/icons/icon-128.png` and verify visually: gold ring, red theca with gold asterisk gem, fleur-de-lis on top, compact pedestal at bottom. Centered with transparent margins.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add extension/icons/icon-16.png extension/icons/icon-48.png extension/icons/icon-128.png
+git commit -m "feat(icons): regenerate PNGs from refreshed SVG masters"
+```
+
+---
+
+## Task 4: Palette swap in styles.css
+
+**Files:**
+- Modify: `extension/src/popup/styles.css`
+
+The complete mapping from old to new hex values:
+
+| Old | New | Note |
+|-----|-----|------|
+| `#58a6ff` | `#d2ab43` | bright gold replaces primary blue |
+| `#1f6feb` | `#7c5719` | deep gold replaces deep blue |
+| `#388bfd` | `#aa812a` | mid gold replaces mid blue (hover state) |
+| `#f85149` | `#ab2b20` | theca-toned red replaces danger fg |
+| `#da3633` | `#791111` | deep theca-red replaces danger emphasis |
+| `rgba(88, 166, 255, 0.3)` | `rgba(170, 129, 42, 0.4)` | focus ring tint (slightly more saturated) |
+
+Note: `#3fb950` (success green) and `#d29922` (warning yellow) are NOT changed.
+
+- [ ] **Step 1: Apply find-and-replace to styles.css**
+
+Use `sed` (in-place) for the bulk swap:
+
+```bash
+sed -i \
+  -e 's/#58a6ff/#d2ab43/g' \
+  -e 's/#1f6feb/#7c5719/g' \
+  -e 's/#388bfd/#aa812a/g' \
+  -e 's/#f85149/#ab2b20/g' \
+  -e 's/#da3633/#791111/g' \
+  -e 's/rgba(88, *166, *255, *\([0-9.]*\))/rgba(170, 129, 42, \1)/g' \
+  -e 's/rgba(31, *111, *235, *\([0-9.]*\))/rgba(124, 87, 25, \1)/g' \
+  -e 's/rgba(248, *81, *73, *\([0-9.]*\))/rgba(171, 43, 32, \1)/g' \
+  -e 's/rgba(218, *54, *51, *\([0-9.]*\))/rgba(121, 17, 17, \1)/g' \
+  extension/src/popup/styles.css
+```
+
+- [ ] **Step 2: Verify no old colors remain**
+
+Run:
+```bash
+grep -nE '#(58a6ff|1f6feb|388bfd|f85149|da3633)' extension/src/popup/styles.css
+```
+Expected: no output (zero hits).
+
+Run:
+```bash
+grep -nE 'rgba\(88|rgba\(31, *111|rgba\(248, *81|rgba\(218, *54' extension/src/popup/styles.css
+```
+Expected: no output.
+
+- [ ] **Step 3: Run vitest (CSS changes shouldn't break behavior tests)**
+
+Run: `cd extension && bun run test`
+Expected: 124 passed (one test inspects HTML for `sig-block--blue` and will still pass at this point — that fix lands in Task 5).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add extension/src/popup/styles.css
+git commit -m "feat(ext/popup): swap blue accent palette for burnished gold"
+```
+
+---
+
+## Task 5: Rename `sig-block--blue` to `sig-block--gold`
+
+The `--blue` variant of the signature block now renders gold. Rename the class for semantic correctness.
+
+**Files:**
+- Modify: `extension/src/popup/styles.css` (the class definition)
+- Modify: `extension/src/popup/components/fields.ts` (the consumer that emits the class string)
+- Modify: `extension/src/popup/components/__tests__/fields.test.ts` (the assertion)
+
+- [ ] **Step 1: Find all consumers of `sig-block--blue` and `accent: 'blue'`**
+
+Run:
+```bash
+grep -rn "sig-block--blue\|accent: 'blue'\|accent=\"blue\"\|accent: \"blue\"" extension/src/
+```
+
+Expected hits:
+- `extension/src/popup/styles.css:507` — `.sig-block--blue { ... }`
+- `extension/src/popup/components/__tests__/fields.test.ts` — string literals `'sig-block--blue'`, `accent: 'blue'`
+
+The `extension/src/popup/components/fields.ts` template uses `sig-block--${accent}` so it accepts whatever string the caller passes. We need to find any caller that passes `'blue'`.
+
+Run:
+```bash
+grep -rn "renderSignatureBlock" extension/src/
+```
+
+Inspect each call site for an `accent: 'blue'` argument; rename to `accent: 'gold'`. Likely zero or one site outside the test, since most signature-block consumers use `'green'` / `'amber'` / `'red'` for status semantics.
+
+- [ ] **Step 2: Rename in styles.css**
+
+Edit `extension/src/popup/styles.css` line 507:
+```css
+.sig-block--gold  { border-left-color: #7c5719; }
+```
+
+(was `.sig-block--blue { border-left-color: #1f6feb; }` — the color was already swapped to `#7c5719` in Task 4; now we rename the class.)
+
+- [ ] **Step 3: Rename `accent` type union in fields.ts**
+
+Open `extension/src/popup/components/fields.ts`. The `renderSignatureBlock` opts type likely has `accent: 'blue' | 'green' | 'amber' | 'red'`. Replace `'blue'` with `'gold'`:
+
+Find:
+```ts
+accent: 'blue' | 'green' | 'amber' | 'red'
+```
+(or however it's typed — also check for `accent?: ...` and `Accent` aliases)
+
+Replace `'blue'` with `'gold'`. Adjust any default value (e.g. `accent = 'blue'` → `accent = 'gold'`).
+
+- [ ] **Step 4: Rename in fields.test.ts**
+
+Edit `extension/src/popup/components/__tests__/fields.test.ts`:
+
+Line 72-area: change `expect(html).toContain('sig-block--blue');` to `expect(html).toContain('sig-block--gold');`
+
+Line 77-area: change `accent: 'blue'` to `accent: 'gold'`. The assertion line 77 likely reads:
+```ts
+expect(renderSignatureBlock({ accent: 'blue', children: '' })).toContain('sig-block--blue');
+```
+Becomes:
+```ts
+expect(renderSignatureBlock({ accent: 'gold', children: '' })).toContain('sig-block--gold');
+```
+
+- [ ] **Step 5: Update any non-test callers found in Step 1**
+
+For each non-test call site that passes `accent: 'blue'`, change to `accent: 'gold'`. If Step 1 found zero such sites, skip this step.
+
+- [ ] **Step 6: Run vitest**
+
+Run: `cd extension && bun run test`
+Expected: 124 passed (the renamed test now asserts on `'gold'` and matches the renamed class).
+
+- [ ] **Step 7: Verify type-check is clean**
+
+Run: `cd extension && bunx tsc --noEmit`
+Expected: zero errors. (If the `accent` type union missed a spot, this is where it'll surface.)
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add extension/src/popup/styles.css \
+        extension/src/popup/components/fields.ts \
+        extension/src/popup/components/__tests__/fields.test.ts
+git commit -m "feat(ext/popup): rename sig-block--blue to --gold for accuracy"
+```
+
+---
+
+## Task 6: Inline color sweep in TS files
+
+Six TS files have inline hex colors in template literals or DOM-style assignments. Each is a 1–2 line touch.
+
+**Files:**
+- Modify: `extension/src/popup/components/types/login.ts`
+- Modify: `extension/src/popup/components/types/totp.ts`
+- Modify: `extension/src/popup/components/generator-popover.ts`
+- Modify: `extension/src/popup/components/settings.ts`
+- Modify: `extension/src/content/capture.ts`
+- Modify: `extension/src/content/icon.ts`
+
+- [ ] **Step 1: Sweep all six files with sed**
+
+Same color mapping as Task 4. Run:
+
+```bash
+sed -i \
+  -e 's/#58a6ff/#d2ab43/g' \
+  -e 's/#1f6feb/#7c5719/g' \
+  -e 's/#388bfd/#aa812a/g' \
+  -e 's/#f85149/#ab2b20/g' \
+  -e 's/#da3633/#791111/g' \
+  extension/src/popup/components/types/login.ts \
+  extension/src/popup/components/types/totp.ts \
+  extension/src/popup/components/generator-popover.ts \
+  extension/src/popup/components/settings.ts \
+  extension/src/content/capture.ts \
+  extension/src/content/icon.ts
+```
+
+- [ ] **Step 2: Verify no old colors remain in `extension/src/`**
+
+Run:
+```bash
+grep -rnE '#(58a6ff|1f6feb|388bfd|f85149|da3633)' extension/src/
+```
+Expected: no output.
+
+- [ ] **Step 3: Run vitest + type-check**
+
+```bash
+cd extension && bun run test && bunx tsc --noEmit
+```
+Expected: 124 passed; zero TS errors.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add extension/src/popup/components/types/login.ts \
+        extension/src/popup/components/types/totp.ts \
+        extension/src/popup/components/generator-popover.ts \
+        extension/src/popup/components/settings.ts \
+        extension/src/content/capture.ts \
+        extension/src/content/icon.ts
+git commit -m "feat(ext): sweep inline blue/red colors to gold/theca-red"
+```
+
+---
+
+## Task 7: Inline color sweep in `setup.html`
+
+Same swap pattern, but in HTML/CSS context.
+
+**Files:**
+- Modify: `extension/setup.html`
+
+- [ ] **Step 1: Apply sed sweep to setup.html**
+
+```bash
+sed -i \
+  -e 's/#58a6ff/#d2ab43/g' \
+  -e 's/#1f6feb/#7c5719/g' \
+  -e 's/#388bfd/#aa812a/g' \
+  -e 's/#f85149/#ab2b20/g' \
+  -e 's/#da3633/#791111/g' \
+  extension/setup.html
+```
+
+- [ ] **Step 2: Verify no old colors remain in setup.html**
+
+```bash
+grep -nE '#(58a6ff|1f6feb|388bfd|f85149|da3633)' extension/setup.html
+```
+Expected: no output.
+
+- [ ] **Step 3: Verify final scope: zero stale colors anywhere in extension/src/ + setup.html**
+
+```bash
+grep -rnE '#(58a6ff|1f6feb|388bfd|f85149|da3633)' extension/src/ extension/setup.html
+```
+Expected: no output. **This is the spec's primary acceptance gate.**
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add extension/setup.html
+git commit -m "feat(ext/setup): sweep inline colors for palette refresh"
+```
+
+---
+
+## Task 8: Build, full verification, and close-out
+
+- [ ] **Step 1: Build both extension bundles**
+
+```bash
+cd extension && bun run build:all
+```
+
+Expected: "compiled with 2 warnings" (WASM size warnings only) for both Chrome and Firefox.
+
+If webpack errors appear, the most likely cause is a TS type mismatch from Task 5's `accent` type union. Re-run `bunx tsc --noEmit` and fix.
+
+- [ ] **Step 2: Run full test sweep**
+
+```bash
+cd /home/alee/Sources/relicario && cargo test --workspace
+cd /home/alee/Sources/relicario/extension && bun run test
+```
+
+Expected: 155 Rust + 124 Vitest, all green.
+
+- [ ] **Step 3: Manual visual smoke check (instructions for the implementer to relay to user)**
+
+Have the user load `extension/dist/` in Chrome (`chrome://extensions` → "Update" if already loaded, or "Load unpacked" otherwise) and verify:
+
+- [ ] Toolbar icon shows the new gold/red reliquary medallion (16 px treatment).
+- [ ] Open popup → unlock — primary buttons (`+ New`, `autofill`, `save`) have gold backgrounds (`#7c5719`).
+- [ ] Selected list row has a gold left-border (`#aa812a`) + gold tint background.
+- [ ] Focus ring on search input + form fields is gold (`#aa812a` @ 40%).
+- [ ] Reveal/copy links in detail view are bright gold (`#d2ab43`).
+- [ ] Trash button (and any danger states) shows theca-red (`#ab2b20`).
+- [ ] TOTP countdown ring is gold (`#d2ab43`).
+- [ ] Signature blocks: `--gold` accent renders gold (was the old blue accent).
+- [ ] Setup tab: strength bar's "very weak" segment is theca-red; advice block left-border is gold.
+- [ ] Capture prompt and origin-ack icon (content script) use gold + theca-red.
+
+Repeat in Firefox via `about:debugging` → "Update" or "Load Temporary Add-on" → `extension/dist-firefox/manifest.json`.
+
+- [ ] **Step 4: Final acceptance grep (paranoia check)**
+
+```bash
+git grep -nE '#(58a6ff|1f6feb|388bfd|f85149|da3633)' -- 'extension/src/**' 'extension/setup.html'
+```
+Expected: no output. Anything in `dist/`, `dist-firefox/`, `node_modules/`, or `.superpowers/` is out of scope.
+
+- [ ] **Step 5: No close-out commit needed**
+
+If steps 1–4 all passed without changes, there's nothing left to commit. The seven prior commits cover all changes.
+
+If a fix was needed in step 1 or step 3 (e.g., a missed `accent: 'blue'` consumer), commit that fix as `fix(ext): <description>` before closing out.
+
+---
+
+## Verification summary (run after Task 8)
+
+```bash
+# Bundles compile clean
+cd extension && bun run build:all
+
+# All tests pass
+cd /home/alee/Sources/relicario && cargo test --workspace
+cd /home/alee/Sources/relicario/extension && bun run test
+
+# Stale palette purged
+git grep -nE '#(58a6ff|1f6feb|388bfd|f85149|da3633)' -- 'extension/src/**' 'extension/setup.html'  # zero hits
+
+# Type-check clean
+cd extension && bunx tsc --noEmit
+```
+
+All four checks must succeed for the plan to be considered complete.
+
+---
+
+## Notes for the implementer
+
+- **No new tests** — palette + logo are visual changes; existing tests cover behavior. The one test touched (`fields.test.ts`) is updated for the renamed `--gold` class.
+- **No worktree required** — this is a small, atomic change set. Commits go directly to main per the project's single-maintainer flow.
+- **Order matters slightly:** Task 4 swaps `#1f6feb` → `#7c5719` everywhere in styles.css, including inside the old `.sig-block--blue` rule. Task 5 then renames the class. Don't reverse the order or the sed sweep in Task 4 will skip the value because the class context changed.
+- **PNG generation order matters:** Task 3 needs the SVGs from Tasks 1–2 to exist first.
+- **Brainstorm artifacts** in `.superpowers/brainstorm/` contain the old hex values in mockup HTML — those are gitignored and out of scope; do NOT sed-sweep them.

docs/superpowers/plans/2026-04-30-fullscreen-ux-phase-1-visual-foundation.md

@@ -0,0 +1,948 @@
+# Fullscreen UX redesign — Phase 1: Visual Foundation
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Establish the shared visual language (glyph constants, color tokens, focus ring, required pill, header subtitle) and clean up vestigial popup-only UI in the fullscreen vault. No structural or behavioral changes; pure visual foundation that the next three phases will build on.
+
+**Architecture:** A new `extension/src/shared/glyphs.ts` module exports unicode glyph constants and a `REQUIRED_PILL_HTML` HTML snippet, consumed by both popup and fullscreen surfaces. CSS custom properties added to `popup/styles.css` and `vault/vault.css` provide the shared color/focus tokens. All eight type forms migrate from `<span class="req">*</span>` to the pill; sidebar nav buttons replace emoji with glyph constants; the popout-to-tab button is gated behind `!isInTab()` so it disappears in fullscreen. Fullscreen forms gain a static "esc to cancel" subtitle (dynamic dirty-state lands in Phase 3).
+
+**Tech stack:** TypeScript, vanilla DOM (no framework), Vitest + happy-dom for unit tests. No new runtime dependencies.
+
+**Spec:** [`docs/superpowers/specs/2026-04-30-relicario-fullscreen-ux-redesign-design.md`](../specs/2026-04-30-relicario-fullscreen-ux-redesign-design.md)
+
+---
+
+## Task 1: shared/glyphs.ts module + snapshot test
+
+**Files:**
+- Create: `extension/src/shared/glyphs.ts`
+- Create: `extension/src/shared/__tests__/glyphs.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+```typescript
+// extension/src/shared/__tests__/glyphs.test.ts
+import { describe, it, expect } from 'vitest';
+import * as glyphs from '../glyphs';
+
+describe('glyphs', () => {
+  it('exports the documented glyph constants', () => {
+    expect(glyphs.GLYPH_REVEAL).toBe('⊙');
+    expect(glyphs.GLYPH_HIDE).toBe('⊘');
+    expect(glyphs.GLYPH_GENERATE).toBe('↻');
+    expect(glyphs.GLYPH_FILL_FROM_TAB).toBe('⤓');
+    expect(glyphs.GLYPH_QR).toBe('◫');
+    expect(glyphs.GLYPH_MONO).toBe('≡');
+    expect(glyphs.GLYPH_TRASH).toBe('▦');
+    expect(glyphs.GLYPH_DEVICES).toBe('⌬');
+    expect(glyphs.GLYPH_SETTINGS).toBe('⚙');
+    expect(glyphs.GLYPH_LOCK).toBe('⏻');
+  });
+
+  it('exports REQUIRED_PILL_HTML as an HTML snippet', () => {
+    expect(glyphs.REQUIRED_PILL_HTML).toBe('<span class="req-pill">required</span>');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd extension && ./node_modules/.bin/vitest run src/shared/__tests__/glyphs.test.ts`
+Expected: FAIL with module-not-found / unresolved-import error.
+
+- [ ] **Step 3: Create the glyphs module**
+
+```typescript
+// extension/src/shared/glyphs.ts
+//
+// Unicode glyph constants used across popup and fullscreen surfaces. All
+// glyphs are monochrome unicode (no emoji) so they render identically in the
+// codebase's monospace font. Pair each button glyph with a `title=` tooltip
+// at the call site for accessibility — the constants here are the visual,
+// not the affordance.
+
+export const GLYPH_REVEAL        = '⊙';   // password reveal toggle (hidden state)
+export const GLYPH_HIDE          = '⊘';   // password reveal toggle (revealed state)
+export const GLYPH_GENERATE      = '↻';   // password / passphrase generate
+export const GLYPH_FILL_FROM_TAB = '⤓';   // pull URL from active browser tab
+export const GLYPH_QR            = '◫';   // paste / upload QR image (TOTP)
+export const GLYPH_MONO          = '≡';   // toggle notes monospace font
+
+export const GLYPH_TRASH         = '▦';   // sidebar trash nav
+export const GLYPH_DEVICES       = '⌬';   // sidebar devices nav
+export const GLYPH_SETTINGS      = '⚙';   // sidebar settings nav
+export const GLYPH_LOCK          = '⏻';   // sidebar lock nav
+
+/// Inline HTML snippet for the required-field pill. Use after a label's text:
+///   `<label class="label" for="f-title">title ${REQUIRED_PILL_HTML}</label>`
+export const REQUIRED_PILL_HTML = '<span class="req-pill">required</span>';
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd extension && ./node_modules/.bin/vitest run src/shared/__tests__/glyphs.test.ts`
+Expected: PASS, 2/2 tests green.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git -C /home/alee/Sources/relicario add extension/src/shared/glyphs.ts extension/src/shared/__tests__/glyphs.test.ts
+git -C /home/alee/Sources/relicario commit -m "feat(ext/shared): glyph constants module for unified icon language
+
+Centralizes the unicode glyphs used by sidebar nav and form action buttons
+so popup and fullscreen surfaces stay in sync. Includes the REQUIRED_PILL_HTML
+snippet used to replace the trailing-asterisk required-field marker.
+
+Plan 2026-04-30 fullscreen UX phase 1 task 1.
+
+Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 2: Color tokens + focus ring (popup styles.css)
+
+**Files:**
+- Modify: `extension/src/popup/styles.css:1-150`
+
+- [ ] **Step 1: Add color tokens at the top of the file**
+
+Open `extension/src/popup/styles.css` and add a `:root` block immediately after the leading comment (before the `*` reset on line 3):
+
+```css
+/* relicario extension — terminal dark theme */
+
+:root {
+  /* Brand */
+  --accent:        #d2ab43;
+  --accent-soft:   rgba(210, 171, 67, 0.18);
+  --accent-strong: #aa812a;
+
+  /* Surfaces */
+  --bg-page:       #0d1117;
+  --bg-pane:       #161b22;
+  --bg-elevated:   #21262d;
+  --border-subtle: #30363d;
+
+  /* Text */
+  --text:          #c9d1d9;
+  --text-muted:    #8b949e;
+  --text-dim:      #484f58;
+
+  /* Status */
+  --danger:        #ab2b20;
+  --danger-bg:     #791111;
+  --success:       #6cb37a;
+
+  /* Focus */
+  --focus-ring:    0 0 0 2px rgba(210, 171, 67, 0.35);
+}
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+```
+
+- [ ] **Step 2: Update input focus to use the ring token**
+
+Find the existing input focus rule (around line 136) and replace it:
+
+Before:
+```css
+input:focus, textarea:focus, select:focus {
+  border-color: #d2ab43;
+}
+```
+
+After:
+```css
+input:focus-visible, textarea:focus-visible, select:focus-visible {
+  border-color: var(--accent);
+  box-shadow: var(--focus-ring);
+  outline: none;
+}
+```
+
+- [ ] **Step 3: Update button focus to match**
+
+Find the `.btn:focus` rule (around line 97) and replace:
+
+Before:
+```css
+.btn:focus {
+  outline: 1px solid #d2ab43;
+  outline-offset: 1px;
+}
+```
+
+After:
+```css
+.btn:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring);
+}
+```
+
+- [ ] **Step 4: Add the required-field pill style**
+
+Find the `.label .req` rule (around line 58) and add the pill rule immediately after it:
+
+```css
+.label .req {
+  color: var(--accent-strong);
+  margin-left: 2px;
+  font-weight: 600;
+}
+
+.req-pill {
+  display: inline-block;
+  font-size: 9px;
+  padding: 1px 5px;
+  background: var(--accent-soft);
+  color: var(--accent);
+  border-radius: 2px;
+  margin-left: 6px;
+  vertical-align: middle;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  font-weight: 500;
+}
+```
+
+- [ ] **Step 5: Build the popup to verify CSS parses**
+
+Run: `cd /home/alee/Sources/relicario/extension && ./node_modules/.bin/webpack --mode production 2>&1 | tail -5`
+Expected: `webpack ... compiled with 2 warnings` (the existing wasm size warnings; no CSS errors).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git -C /home/alee/Sources/relicario add extension/src/popup/styles.css
+git -C /home/alee/Sources/relicario commit -m "style(ext/popup): add color tokens, focus ring, required-pill class
+
+Establishes :root CSS custom properties (accent, surfaces, status, focus
+ring) and applies the focus ring to inputs/buttons via :focus-visible.
+Adds .req-pill class used by Task 4 to replace the bare-asterisk required
+marker. Existing .label .req kept for backward compatibility during the
+migration window.
+
+Plan 2026-04-30 fullscreen UX phase 1 task 2.
+
+Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 3: Color tokens + focus ring (vault.css)
+
+**Files:**
+- Modify: `extension/src/vault/vault.css`
+
+- [ ] **Step 1: Add the same `:root` block to vault.css**
+
+Open `extension/src/vault/vault.css` and add the same `:root` block at the top (above any existing content). Use the **identical** token block from Task 2 Step 1 so the two stylesheets stay in sync:
+
+```css
+:root {
+  /* Brand */
+  --accent:        #d2ab43;
+  --accent-soft:   rgba(210, 171, 67, 0.18);
+  --accent-strong: #aa812a;
+
+  /* Surfaces */
+  --bg-page:       #0d1117;
+  --bg-pane:       #161b22;
+  --bg-elevated:   #21262d;
+  --border-subtle: #30363d;
+
+  /* Text */
+  --text:          #c9d1d9;
+  --text-muted:    #8b949e;
+  --text-dim:      #484f58;
+
+  /* Status */
+  --danger:        #ab2b20;
+  --danger-bg:     #791111;
+  --success:       #6cb37a;
+
+  /* Focus */
+  --focus-ring:    0 0 0 2px rgba(210, 171, 67, 0.35);
+}
+```
+
+- [ ] **Step 2: Find existing input focus rule and migrate it**
+
+Run: `grep -n "input:focus\|textarea:focus\|:focus" extension/src/vault/vault.css | head -10`
+
+For each focus rule that sets `border-color: #d2ab43` (or similar accent-color border), update it to use `:focus-visible` and add the ring:
+
+```css
+input:focus-visible, textarea:focus-visible, select:focus-visible {
+  border-color: var(--accent);
+  box-shadow: var(--focus-ring);
+  outline: none;
+}
+```
+
+(If no equivalent rule exists in vault.css today, add the rule above; vault inputs currently inherit popup styles or have their own — check what `grep` returns.)
+
+- [ ] **Step 3: Add the .req-pill rule**
+
+Append to vault.css (anywhere; group near `.label` if present):
+
+```css
+.req-pill {
+  display: inline-block;
+  font-size: 9px;
+  padding: 1px 5px;
+  background: var(--accent-soft);
+  color: var(--accent);
+  border-radius: 2px;
+  margin-left: 6px;
+  vertical-align: middle;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  font-weight: 500;
+}
+```
+
+- [ ] **Step 4: Build to verify**
+
+Run: `cd /home/alee/Sources/relicario/extension && ./node_modules/.bin/webpack --mode production 2>&1 | tail -5`
+Expected: `webpack ... compiled with 2 warnings`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git -C /home/alee/Sources/relicario add extension/src/vault/vault.css
+git -C /home/alee/Sources/relicario commit -m "style(ext/vault): mirror color tokens, focus ring, required-pill class
+
+Same :root block and .req-pill rule as popup/styles.css so the two
+stylesheets share visual tokens. Vault input focus migrated to
+:focus-visible + box-shadow ring.
+
+Plan 2026-04-30 fullscreen UX phase 1 task 3.
+
+Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 4: Migrate required-marker sites to REQUIRED_PILL_HTML
+
+**Files (10 sites across 7 files):**
+- Modify: `extension/src/popup/components/types/card.ts:182`
+- Modify: `extension/src/popup/components/types/document.ts:94, 98`
+- Modify: `extension/src/popup/components/types/identity.ts:142`
+- Modify: `extension/src/popup/components/types/key.ts:131, 133`
+- Modify: `extension/src/popup/components/types/login.ts:252`
+- Modify: `extension/src/popup/components/types/secure-note.ts:120`
+- Modify: `extension/src/popup/components/types/totp.ts:221, 230`
+
+- [ ] **Step 1: Create a regression test for the login form's title label**
+
+Create `extension/src/popup/components/types/__tests__/required-pill.test.ts`:
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('../../../../shared/state', () => ({
+  sendMessage: vi.fn(),
+  getState: () => ({ newType: 'login', generatorDefaults: null, error: null, loading: false, vaultSettings: null, entries: [] }),
+  setState: vi.fn(),
+  navigate: vi.fn(),
+  escapeHtml: (s: string) => s,
+  popOutToTab: vi.fn(),
+  isInTab: () => false,
+  openVaultTab: vi.fn(),
+  registerHost: vi.fn(),
+}));
+
+vi.mock('../../generator-panel', () => ({
+  openGeneratorPanel: vi.fn(),
+  closeGeneratorPanel: vi.fn(),
+  isGeneratorPanelOpen: () => false,
+}));
+
+import { renderForm } from '../login';
+
+describe('required-pill migration', () => {
+  beforeEach(() => { document.body.innerHTML = '<div id="app"></div>'; });
+
+  it('login form title uses the required pill', () => {
+    renderForm(document.getElementById('app')!, 'add', null);
+    const titleLabel = document.querySelector('label[for="f-title"]');
+    expect(titleLabel?.innerHTML).toContain('required');
+    expect(titleLabel?.innerHTML).not.toContain('<span class="req">*</span>');
+  });
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `cd extension && ./node_modules/.bin/vitest run src/popup/components/types/__tests__/required-pill.test.ts`
+Expected: FAIL — `<span class="req">*</span>` is currently present, `required` text is not.
+
+- [ ] **Step 3: Migrate `login.ts`**
+
+In `extension/src/popup/components/types/login.ts`:
+
+Add an import near the top (after the existing imports):
+
+```typescript
+import { REQUIRED_PILL_HTML } from '../../../shared/glyphs';
+```
+
+Find line 252:
+```typescript
+      <div class="form-group"><label class="label" for="f-title">title <span class="req">*</span></label>
+```
+
+Replace with:
+```typescript
+      <div class="form-group"><label class="label" for="f-title">title ${REQUIRED_PILL_HTML}</label>
+```
+
+- [ ] **Step 4: Run the test to verify it passes for login**
+
+Run: `cd extension && ./node_modules/.bin/vitest run src/popup/components/types/__tests__/required-pill.test.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Migrate the remaining six files**
+
+Apply the same pattern to each of these six files. For each:
+1. Add `import { REQUIRED_PILL_HTML } from '../../../shared/glyphs';`
+2. Replace each `<span class="req">*</span>` with `${REQUIRED_PILL_HTML}`
+
+| File | Line(s) |
+|---|---|
+| `extension/src/popup/components/types/card.ts` | 182 |
+| `extension/src/popup/components/types/document.ts` | 94, 98 |
+| `extension/src/popup/components/types/identity.ts` | 142 |
+| `extension/src/popup/components/types/key.ts` | 131, 133 |
+| `extension/src/popup/components/types/secure-note.ts` | 120 |
+| `extension/src/popup/components/types/totp.ts` | 221, 230 |
+
+After editing each file, verify no remaining `<span class="req">*</span>` strings exist:
+
+Run: `grep -rn 'class="req"' extension/src --include="*.ts" 2>/dev/null`
+Expected: empty output.
+
+- [ ] **Step 6: Run the full extension test suite**
+
+Run: `cd extension && ./node_modules/.bin/vitest run`
+Expected: all 220+ tests pass (the new test brings it to 221+; no regressions).
+
+- [ ] **Step 7: Build to verify TypeScript compiles**
+
+Run: `cd /home/alee/Sources/relicario/extension && ./node_modules/.bin/webpack --mode production 2>&1 | tail -5`
+Expected: `compiled with 2 warnings`.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git -C /home/alee/Sources/relicario add extension/src/popup/components/types/ extension/src/shared/
+git -C /home/alee/Sources/relicario commit -m "refactor(ext/popup): migrate required-field markers to REQUIRED_PILL_HTML
+
+Replaces ten <span class=\"req\">*</span> sites across all seven type
+forms with the shared REQUIRED_PILL_HTML snippet ('required' badge). Adds a
+regression test pinning the new HTML in the login form.
+
+Plan 2026-04-30 fullscreen UX phase 1 task 4.
+
+Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 5: Migrate vault sidebar nav glyphs
+
+**Files:**
+- Modify: `extension/src/vault/vault.ts:251-254`
+
+- [ ] **Step 1: Write a regression test**
+
+Open `extension/src/vault/components/__tests__/import-panel.test.ts` for reference on how vault tests mock state. Create a new test file:
+
+`extension/src/vault/__tests__/sidebar-glyphs.test.ts`:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { GLYPH_TRASH, GLYPH_DEVICES, GLYPH_SETTINGS, GLYPH_LOCK } from '../../shared/glyphs';
+
+// vault.ts injects HTML into document.getElementById('vault-app'); we
+// don't need to invoke render() — we just need to scan the source for the
+// emoji we removed.
+import * as fs from 'fs';
+import * as path from 'path';
+
+describe('vault sidebar glyphs', () => {
+  const vaultSrc = fs.readFileSync(
+    path.resolve(__dirname, '../vault.ts'),
+    'utf-8',
+  );
+
+  it('uses GLYPH_TRASH instead of the trash emoji', () => {
+    expect(vaultSrc).not.toMatch(/\u{1F5D1}/u);
+    expect(vaultSrc).toContain('GLYPH_TRASH');
+  });
+
+  it('uses GLYPH_DEVICES instead of the devices emoji', () => {
+    expect(vaultSrc).not.toMatch(/\u{1F4F1}/u);
+    expect(vaultSrc).toContain('GLYPH_DEVICES');
+  });
+
+  it('uses GLYPH_LOCK instead of the lock emoji', () => {
+    expect(vaultSrc).not.toMatch(/\u{1F512}/u);
+    expect(vaultSrc).toContain('GLYPH_LOCK');
+  });
+
+  it('uses GLYPH_SETTINGS for the settings nav', () => {
+    expect(vaultSrc).toContain('GLYPH_SETTINGS');
+  });
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run: `cd extension && ./node_modules/.bin/vitest run src/vault/__tests__/sidebar-glyphs.test.ts`
+Expected: FAIL — the emojis are still present, the GLYPH constants are not.
+
+- [ ] **Step 3: Add the import to vault.ts**
+
+In `extension/src/vault/vault.ts`, add to the imports section (near the top, after other shared imports):
+
+```typescript
+import { GLYPH_TRASH, GLYPH_DEVICES, GLYPH_SETTINGS, GLYPH_LOCK } from '../shared/glyphs';
+```
+
+- [ ] **Step 4: Replace the sidebar nav buttons**
+
+Find the block at lines 249-255 in `vault.ts`:
+
+```typescript
+        <div class="vault-sidebar__nav">
+          <button class="vault-sidebar__nav-item" data-nav="add">+ new item</button>
+          <button class="vault-sidebar__nav-item" data-nav="trash">\u{1F5D1} trash</button>
+          <button class="vault-sidebar__nav-item" data-nav="devices">\u{1F4F1} devices</button>
+          <button class="vault-sidebar__nav-item" data-nav="settings">⚙ settings</button>
+          <button class="vault-sidebar__nav-item" data-nav="lock">\u{1F512} lock</button>
+        </div>
+```
+
+Replace with:
+
+```typescript
+        <div class="vault-sidebar__nav">
+          <button class="vault-sidebar__nav-item" data-nav="add">+ new item</button>
+          <button class="vault-sidebar__nav-item" data-nav="trash">${GLYPH_TRASH} trash</button>
+          <button class="vault-sidebar__nav-item" data-nav="devices">${GLYPH_DEVICES} devices</button>
+          <button class="vault-sidebar__nav-item" data-nav="settings">${GLYPH_SETTINGS} settings</button>
+          <button class="vault-sidebar__nav-item" data-nav="lock">${GLYPH_LOCK} lock</button>
+        </div>
+```
+
+- [ ] **Step 5: Run the test to verify it passes**
+
+Run: `cd extension && ./node_modules/.bin/vitest run src/vault/__tests__/sidebar-glyphs.test.ts`
+Expected: PASS, 4/4 tests green.
+
+- [ ] **Step 6: Run the full suite + build**
+
+```bash
+cd /home/alee/Sources/relicario/extension
+./node_modules/.bin/vitest run 2>&1 | tail -5
+./node_modules/.bin/webpack --mode production 2>&1 | tail -5
+```
+Expected: all tests pass; webpack compiles with 2 warnings.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git -C /home/alee/Sources/relicario add extension/src/vault/vault.ts extension/src/vault/__tests__/sidebar-glyphs.test.ts
+git -C /home/alee/Sources/relicario commit -m "style(ext/vault): replace sidebar emoji nav with monochrome glyphs
+
+▦ trash · ⌬ devices · ⚙ settings · ⏻ lock — all imported from the new
+shared/glyphs module so popup and fullscreen stay in sync. Regression
+test scans the source for the old escape-coded emoji to prevent
+backsliding.
+
+Plan 2026-04-30 fullscreen UX phase 1 task 5.
+
+Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 6: Migrate popup settings nav glyphs
+
+**Files:**
+- Modify: `extension/src/popup/components/settings.ts:58-59`
+
+- [ ] **Step 1: Verify the existing emojis**
+
+Run: `grep -n "🗑\|🔐" extension/src/popup/components/settings.ts`
+Expected output (line 58 trash, line 59 devices):
+```
+58:        <button class="btn" id="trash-btn" style="width:100%;margin-bottom:8px;">🗑️ Trash</button>
+59:        <button class="btn" id="devices-btn" style="width:100%;margin-bottom:8px;">🔐 Devices</button>
+```
+
+- [ ] **Step 2: Add the import**
+
+In `extension/src/popup/components/settings.ts`, add to the imports near the top:
+
+```typescript
+import { GLYPH_TRASH, GLYPH_DEVICES } from '../../shared/glyphs';
+```
+
+- [ ] **Step 3: Replace the buttons**
+
+Replace lines 58-59:
+
+Before:
+```typescript
+        <button class="btn" id="trash-btn" style="width:100%;margin-bottom:8px;">🗑️ Trash</button>
+        <button class="btn" id="devices-btn" style="width:100%;margin-bottom:8px;">🔐 Devices</button>
+```
+
+After:
+```typescript
+        <button class="btn" id="trash-btn" style="width:100%;margin-bottom:8px;">${GLYPH_TRASH} trash</button>
+        <button class="btn" id="devices-btn" style="width:100%;margin-bottom:8px;">${GLYPH_DEVICES} devices</button>
+```
+
+(Lowercased "trash" / "devices" to match the brand's lowercase aesthetic established in Phase 1.)
+
+- [ ] **Step 4: Verify no emojis remain**
+
+Run: `grep -n "🗑\|🔐\|🔒\|📺" extension/src/popup/components/settings.ts`
+Expected: empty output.
+
+- [ ] **Step 5: Run tests + build**
+
+```bash
+cd /home/alee/Sources/relicario/extension
+./node_modules/.bin/vitest run 2>&1 | tail -5
+./node_modules/.bin/webpack --mode production 2>&1 | tail -5
+```
+Expected: all tests pass; webpack compiles with 2 warnings.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git -C /home/alee/Sources/relicario add extension/src/popup/components/settings.ts
+git -C /home/alee/Sources/relicario commit -m "style(ext/popup): replace settings nav emoji with shared glyphs
+
+▦ trash and ⌬ devices in the popup settings panel now match the
+fullscreen sidebar's glyph language. Lowercased labels match the brand.
+
+Plan 2026-04-30 fullscreen UX phase 1 task 6.
+
+Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 7: Hide popout-to-tab button in fullscreen forms
+
+**Files (8 sites):**
+- Modify: `extension/src/popup/components/item-form.ts:61`
+- Modify: `extension/src/popup/components/types/card.ts:179`
+- Modify: `extension/src/popup/components/types/document.ts:90`
+- Modify: `extension/src/popup/components/types/identity.ts:139`
+- Modify: `extension/src/popup/components/types/key.ts:128`
+- Modify: `extension/src/popup/components/types/login.ts:249`
+- Modify: `extension/src/popup/components/types/secure-note.ts:117`
+- Modify: `extension/src/popup/components/types/totp.ts:218`
+
+- [ ] **Step 1: Confirm `isInTab()` is exported and used**
+
+Run: `grep -n "export.*isInTab\|import.*isInTab" extension/src/shared/state.ts extension/src/popup/components/types/login.ts`
+Expected: `state.ts` exports `isInTab`; `login.ts` already imports it.
+
+- [ ] **Step 2: Write a test for the login form behavior in fullscreen**
+
+Append to `extension/src/popup/components/types/__tests__/required-pill.test.ts` (or create a new file `popout-button.test.ts` next to it):
+
+```typescript
+// Append to required-pill.test.ts
+
+describe('popout-to-tab button visibility', () => {
+  beforeEach(() => { document.body.innerHTML = '<div id="app"></div>'; });
+
+  it('renders the popout button when isInTab() is false (popup context)', async () => {
+    // The default mock at the top of this file sets isInTab: () => false.
+    // Re-render with that.
+    const { renderForm } = await import('../login');
+    renderForm(document.getElementById('app')!, 'add', null);
+    expect(document.getElementById('popout-btn')).not.toBeNull();
+  });
+});
+```
+
+For the fullscreen variant (isInTab → true), add a separate test file because vi.mock is module-level. Create `extension/src/popup/components/types/__tests__/popout-fullscreen.test.ts`:
+
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+vi.mock('../../../../shared/state', () => ({
+  sendMessage: vi.fn(),
+  getState: () => ({ newType: 'login', generatorDefaults: null, error: null, loading: false, vaultSettings: null, entries: [] }),
+  setState: vi.fn(),
+  navigate: vi.fn(),
+  escapeHtml: (s: string) => s,
+  popOutToTab: vi.fn(),
+  isInTab: () => true,        // FULLSCREEN context
+  openVaultTab: vi.fn(),
+  registerHost: vi.fn(),
+}));
+
+vi.mock('../../generator-panel', () => ({
+  openGeneratorPanel: vi.fn(),
+  closeGeneratorPanel: vi.fn(),
+  isGeneratorPanelOpen: () => false,
+}));
+
+import { renderForm } from '../login';
+
+describe('popout-to-tab button (fullscreen context)', () => {
+  beforeEach(() => { document.body.innerHTML = '<div id="app"></div>'; });
+
+  it('does NOT render the popout button when isInTab() is true', () => {
+    renderForm(document.getElementById('app')!, 'add', null);
+    expect(document.getElementById('popout-btn')).toBeNull();
+  });
+});
+```
+
+- [ ] **Step 3: Run tests to verify the fullscreen test fails**
+
+Run: `cd extension && ./node_modules/.bin/vitest run src/popup/components/types/__tests__/popout-fullscreen.test.ts`
+Expected: FAIL — popout button is currently rendered unconditionally.
+
+- [ ] **Step 4: Gate the popout button in `login.ts`**
+
+In `extension/src/popup/components/types/login.ts`, find line 249:
+
+```typescript
+        <button class="btn" id="popout-btn" title="Open in tab">⤴</button>
+```
+
+Replace with:
+
+```typescript
+        ${isInTab() ? '' : '<button class="btn" id="popout-btn" title="Open in tab">⤴</button>'}
+```
+
+- [ ] **Step 5: Repeat for the other seven files**
+
+Apply the same conditional wrap to each remaining popout button site. For each, the surrounding context is `<button class="btn" id="popout-btn" title="Open in tab">⤴</button>` — wrap that single line with the ternary.
+
+For `extension/src/popup/components/item-form.ts:61` (the type-selection screen's popout button), use the same pattern:
+
+```typescript
+        ${isInTab() ? '' : '<button class="btn" id="popout-btn" title="Open in tab">⤴</button>'}
+```
+
+If `isInTab` is not already imported in a given file, add it to the existing import from `../../../shared/state` (or `../../shared/state` for `item-form.ts`).
+
+After editing each file, also remove or guard the corresponding `document.getElementById('popout-btn')?.addEventListener('click', popOutToTab);` line — or leave it as-is since `getElementById` returns `null` and the optional-chain handles it. **Leave the listener wiring untouched** to keep the diff minimal; it's a no-op when the button isn't present.
+
+- [ ] **Step 6: Run all popout tests + full suite**
+
+```bash
+cd /home/alee/Sources/relicario/extension
+./node_modules/.bin/vitest run 2>&1 | tail -8
+```
+Expected: all tests pass, including both `popout-button` and `popout-fullscreen` cases.
+
+- [ ] **Step 7: Build to verify**
+
+Run: `cd /home/alee/Sources/relicario/extension && ./node_modules/.bin/webpack --mode production 2>&1 | tail -5`
+Expected: `compiled with 2 warnings`.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git -C /home/alee/Sources/relicario add extension/src/popup/
+git -C /home/alee/Sources/relicario commit -m "feat(ext/popup): hide popout-to-tab button in fullscreen forms
+
+The ⤴ popout button is meaningless when the form is already in
+vault.html — gate it on !isInTab(). Affects all seven type forms plus
+the type-selection screen. Regression tests cover both popup (button
+present) and fullscreen (button absent) contexts.
+
+Plan 2026-04-30 fullscreen UX phase 1 task 7.
+
+Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 8: Static "esc to cancel" subtitle in fullscreen forms
+
+**Files:**
+- Modify: same eight files as Task 7 (header markup region, ~3-4 lines above the popout button site)
+- Modify: `extension/src/popup/styles.css` (one new CSS class — shared, since the fullscreen inherits popup styles via vault's own stylesheet only loading vault.css)
+- Modify: `extension/src/vault/vault.css` (one new CSS class)
+
+- [ ] **Step 1: Add the `.form-subtitle` CSS class to popup/styles.css**
+
+Append to `extension/src/popup/styles.css` (anywhere — group near `.muted`):
+
+```css
+.form-subtitle {
+  font-size: 11px;
+  color: var(--text-dim);
+  margin-top: 2px;
+  margin-bottom: 14px;
+  letter-spacing: 0.02em;
+}
+```
+
+- [ ] **Step 2: Add the same class to vault.css**
+
+Append the **identical** `.form-subtitle` rule to `extension/src/vault/vault.css`.
+
+- [ ] **Step 3: Write a test for the subtitle in fullscreen context**
+
+Append to `extension/src/popup/components/types/__tests__/popout-fullscreen.test.ts`:
+
+```typescript
+describe('form subtitle (fullscreen context)', () => {
+  beforeEach(() => { document.body.innerHTML = '<div id="app"></div>'; });
+
+  it('renders "esc to cancel" subtitle in the login form header', () => {
+    renderForm(document.getElementById('app')!, 'add', null);
+    const subtitle = document.querySelector('.form-subtitle');
+    expect(subtitle).not.toBeNull();
+    expect(subtitle?.textContent).toContain('esc to cancel');
+  });
+});
+```
+
+And add a *negative* test in `required-pill.test.ts` (popup context):
+
+```typescript
+describe('form subtitle (popup context)', () => {
+  beforeEach(() => { document.body.innerHTML = '<div id="app"></div>'; });
+
+  it('does NOT render the "esc to cancel" subtitle in popup context', async () => {
+    const { renderForm } = await import('../login');
+    renderForm(document.getElementById('app')!, 'add', null);
+    expect(document.querySelector('.form-subtitle')).toBeNull();
+  });
+});
+```
+
+- [ ] **Step 4: Run tests to verify the fullscreen subtitle test fails**
+
+Run: `cd extension && ./node_modules/.bin/vitest run src/popup/components/types/__tests__/popout-fullscreen.test.ts`
+Expected: FAIL — no `.form-subtitle` element rendered today.
+
+- [ ] **Step 5: Update `login.ts` header**
+
+In `extension/src/popup/components/types/login.ts`, find the header markup (lines 246-250):
+
+```typescript
+      <div style="display:flex; align-items:center; margin-bottom:16px;">
+        <div class="detail-title">${mode === 'add' ? 'new login' : 'edit login'}</div>
+        <span style="flex:1;"></span>
+        ${isInTab() ? '' : '<button class="btn" id="popout-btn" title="Open in tab">⤴</button>'}
+      </div>
+```
+
+Replace with:
+
+```typescript
+      <div style="display:flex; align-items:center;">
+        <div class="detail-title">${mode === 'add' ? 'new login' : 'edit login'}</div>
+        <span style="flex:1;"></span>
+        ${isInTab() ? '' : '<button class="btn" id="popout-btn" title="Open in tab">⤴</button>'}
+      </div>
+      ${isInTab() ? '<div class="form-subtitle">esc to cancel</div>' : '<div style="margin-bottom:16px;"></div>'}
+```
+
+(The header's `margin-bottom:16px` moves to the conditional spacer so the subtitle gets to sit right under the title.)
+
+- [ ] **Step 6: Run the test to verify it passes for login**
+
+Run: `cd extension && ./node_modules/.bin/vitest run src/popup/components/types/__tests__/popout-fullscreen.test.ts src/popup/components/types/__tests__/required-pill.test.ts`
+Expected: PASS — both fullscreen and popup variants of the subtitle test.
+
+- [ ] **Step 7: Repeat for the remaining six type forms**
+
+Apply the same header restructuring to each of:
+- `card.ts` (around line 179)
+- `document.ts` (around line 90)
+- `identity.ts` (around line 139)
+- `key.ts` (around line 128)
+- `secure-note.ts` (around line 117)
+- `totp.ts` (around line 218)
+
+For each, find the existing header `<div>` block that contains the title + popout button, and add the subtitle line below it using the same conditional pattern. The title text differs per type ("new identity" / "new card" etc.) — preserve whatever the current expression is.
+
+For `extension/src/popup/components/item-form.ts` (the type-selection screen), apply the same pattern around line 60-63.
+
+- [ ] **Step 8: Run the full suite + build**
+
+```bash
+cd /home/alee/Sources/relicario/extension
+./node_modules/.bin/vitest run 2>&1 | tail -5
+./node_modules/.bin/webpack --mode production 2>&1 | tail -5
+```
+Expected: all tests pass; webpack compiles with 2 warnings.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git -C /home/alee/Sources/relicario add extension/src/popup/ extension/src/vault/
+git -C /home/alee/Sources/relicario commit -m "feat(ext): static 'esc to cancel' subtitle in fullscreen form headers
+
+All seven type forms plus the type-selection screen now show a small
+'esc to cancel' subtitle under the heading when rendered in the
+fullscreen vault tab (isInTab() === true). The subtitle is suppressed
+in the popup, where esc has the more general meaning of closing the
+popup. .form-subtitle class is shared between popup and vault
+stylesheets so future hooks can reuse it.
+
+Dynamic dirty-state ('unsaved · esc to cancel') wiring is deferred to
+Phase 3 (unsaved-changes guard).
+
+Plan 2026-04-30 fullscreen UX phase 1 task 8.
+
+Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>"
+```
+
+---
+
+## Final verification
+
+- [ ] **Run the full extension test suite one more time**
+
+```bash
+cd /home/alee/Sources/relicario/extension
+./node_modules/.bin/vitest run 2>&1 | tail -10
+```
+Expected: all tests pass (count = previous baseline + the new tests added by this plan).
+
+- [ ] **Build all variants**
+
+```bash
+cd /home/alee/Sources/relicario/extension
+./node_modules/.bin/webpack --mode production 2>&1 | tail -5
+./node_modules/.bin/webpack --config webpack.firefox.config.js --mode production 2>&1 | tail -5
+```
+Expected: both compile with 2 warnings.
+
+- [ ] **Manual smoke test**
+
+Load the unpacked extension in Chrome:
+1. Open the popup: confirm sidebar settings panel shows `▦ trash` / `⌬ devices` (no emoji), required pill on title fields, focus ring is amber.
+2. Open vault.html: confirm sidebar shows `▦ trash · ⌬ devices · ⚙ settings · ⏻ lock`, no popout button on the form header, "esc to cancel" subtitle visible under "new login".
+3. Tab through fields with keyboard: confirm focus ring renders consistently.
+
+(If anything looks off, the symptom is almost certainly a CSS specificity issue — vault.css may need an `!important` or scoped selector. Note the issue and fix in a follow-up commit.)

docs/superpowers/plans/2026-05-01-password-coloring.md

@@ -0,0 +1,804 @@
+# Password Display Character-Class Coloring — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Color revealed passwords in the extension UI by character class (digits, symbols, letters), defaulting to digits-blue / symbols-red / letters-inherit, with user-configurable colors persisted in `chrome.storage.sync`.
+
+**Architecture:** A single pure utility `colorizePassword(text)` that returns a `DocumentFragment` of class-named `<span>` runs. CSS rules in the existing extension stylesheet(s) bind those classes to CSS custom properties (`--relicario-pwd-digit-color`, `--relicario-pwd-symbol-color`). User overrides are stored in `chrome.storage.sync` and applied on popup/vault startup by setting the custom properties on `document.documentElement`. All four password-revealing surfaces (popup field-history viewer, popup item detail, fullscreen item detail, generator preview) call the same utility.
+
+**Tech Stack:** TypeScript, Vitest with JSDOM for unit tests, existing `chrome.storage.sync` plumbing in the extension, existing settings UI patterns in `extension/src/popup/components/settings*.ts`.
+
+**Spec:** `docs/superpowers/specs/2026-05-01-password-coloring-design.md`
+
+---
+
+## File Structure
+
+### Created
+
+- `extension/src/shared/password-coloring.ts` — pure `colorizePassword()` utility + class-name constants.
+- `extension/src/shared/__tests__/password-coloring.test.ts` — Vitest unit tests for the utility.
+- `extension/src/shared/color-scheme.ts` — read/write/apply helpers for the user's stored color scheme.
+- `extension/src/shared/__tests__/color-scheme.test.ts` — Vitest unit tests for storage round-trip + apply.
+
+(If `extension/src/shared/` does not exist, create it. Otherwise place under whatever the extension's existing shared/utility directory is — match the established convention.)
+
+### Modified
+
+- The popup stylesheet (`extension/src/popup/styles.css` and any vault stylesheet): add `:root` defaults + `.pwd-digit/.pwd-symbol/.pwd-letter` rules.
+- `extension/src/popup/components/field-history.ts:72` — replace text-content assignment with `colorizePassword()` fragment.
+- The popup's vault item detail component (find via `grep -n "password.*reveal\|passwordCell" extension/src/popup/`).
+- `extension/src/vault/` item-detail component — same change, fullscreen surface.
+- The generator preview component — same change.
+- The popup's bootstrap (`extension/src/popup/popup.ts` or `index.ts`) — call `applyColorScheme()` once at startup.
+- The vault's bootstrap (`extension/src/vault/vault.ts`) — same `applyColorScheme()` call.
+- A settings page component — add the Display section with two color pickers, preview swatch, reset button.
+
+---
+
+## Phase A — Core utility
+
+### Task 1: `colorizePassword()` pure utility
+
+**Files:**
+- Create: `extension/src/shared/password-coloring.ts`
+- Create: `extension/src/shared/__tests__/password-coloring.test.ts`
+
+- [ ] **Step 1: Write the failing tests**
+
+`extension/src/shared/__tests__/password-coloring.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach } from 'vitest';
+import { JSDOM } from 'jsdom';
+import { colorizePassword, PWD_DIGIT, PWD_SYMBOL, PWD_LETTER } from '../password-coloring';
+
+describe('colorizePassword', () => {
+  beforeEach(() => {
+    const dom = new JSDOM('<!DOCTYPE html><body></body>');
+    (global as any).document = dom.window.document;
+  });
+
+  function classes(frag: DocumentFragment): string[] {
+    return Array.from(frag.querySelectorAll('span')).map(s => s.className);
+  }
+  function texts(frag: DocumentFragment): string[] {
+    return Array.from(frag.querySelectorAll('span')).map(s => s.textContent ?? '');
+  }
+
+  it('returns empty fragment for empty input', () => {
+    const frag = colorizePassword('');
+    expect(frag.childNodes.length).toBe(0);
+  });
+
+  it('classifies a mixed-class run', () => {
+    const frag = colorizePassword('aB3$xY');
+    expect(classes(frag)).toEqual([PWD_LETTER, PWD_DIGIT, PWD_SYMBOL, PWD_LETTER]);
+    expect(texts(frag)).toEqual(['aB', '3', '$', 'xY']);
+  });
+
+  it('all-letters produces a single letter span', () => {
+    const frag = colorizePassword('passwd');
+    expect(classes(frag)).toEqual([PWD_LETTER]);
+    expect(texts(frag)).toEqual(['passwd']);
+  });
+
+  it('all-digits produces a single digit span', () => {
+    const frag = colorizePassword('123456');
+    expect(classes(frag)).toEqual([PWD_DIGIT]);
+    expect(texts(frag)).toEqual(['123456']);
+  });
+
+  it('all-symbols produces a single symbol span', () => {
+    const frag = colorizePassword('!@#$%^');
+    expect(classes(frag)).toEqual([PWD_SYMBOL]);
+    expect(texts(frag)).toEqual(['!@#$%^']);
+  });
+
+  it('classifies unicode letters as letters', () => {
+    const frag = colorizePassword('áñü');
+    expect(classes(frag)).toEqual([PWD_LETTER]);
+  });
+
+  it('classifies whitespace as symbol', () => {
+    const frag = colorizePassword('a b');
+    expect(classes(frag)).toEqual([PWD_LETTER, PWD_SYMBOL, PWD_LETTER]);
+    expect(texts(frag)).toEqual(['a', ' ', 'b']);
+  });
+
+  it('representative password snapshot: aB3$xY7&_!', () => {
+    const frag = colorizePassword('aB3$xY7&_!');
+    expect(classes(frag)).toEqual([
+      PWD_LETTER, PWD_DIGIT, PWD_SYMBOL, PWD_LETTER, PWD_DIGIT, PWD_SYMBOL,
+    ]);
+    expect(texts(frag)).toEqual(['aB', '3', '$', 'xY', '7', '&_!']);
+  });
+});
+```
+
+- [ ] **Step 2: Run — expect compile failure (module missing)**
+
+```
+cd extension && npm run test -- password-coloring
+```
+
+Expected: `Cannot find module '../password-coloring'`.
+
+- [ ] **Step 3: Implement the utility**
+
+`extension/src/shared/password-coloring.ts`:
+
+```ts
+export const PWD_DIGIT = 'pwd-digit';
+export const PWD_SYMBOL = 'pwd-symbol';
+export const PWD_LETTER = 'pwd-letter';
+
+type Class = typeof PWD_DIGIT | typeof PWD_SYMBOL | typeof PWD_LETTER;
+
+function classify(ch: string): Class {
+  if (/^\d$/.test(ch)) return PWD_DIGIT;
+  if (/^\p{L}$/u.test(ch)) return PWD_LETTER;
+  return PWD_SYMBOL;
+}
+
+/**
+ * Split `text` into runs of same-class codepoints and return a DocumentFragment
+ * of class-named <span> nodes (one span per run). Returns an empty fragment
+ * for empty input.
+ *
+ * Pure: does not mutate any DOM outside the returned fragment, does not perform
+ * I/O. Safe to call on every render.
+ */
+export function colorizePassword(text: string): DocumentFragment {
+  const frag = document.createDocumentFragment();
+  if (text.length === 0) return frag;
+
+  // Iterate by codepoint so unicode letters classify correctly.
+  const codepoints = Array.from(text);
+  let runStart = 0;
+  let runClass = classify(codepoints[0]);
+
+  for (let i = 1; i <= codepoints.length; i++) {
+    const c = i < codepoints.length ? classify(codepoints[i]) : null;
+    if (c !== runClass) {
+      const span = document.createElement('span');
+      span.className = runClass;
+      span.textContent = codepoints.slice(runStart, i).join('');
+      frag.appendChild(span);
+      if (c !== null) {
+        runStart = i;
+        runClass = c;
+      }
+    }
+  }
+  return frag;
+}
+```
+
+- [ ] **Step 4: Run — expect pass**
+
+```
+cd extension && npm run test -- password-coloring
+```
+
+Expected: all 8 PASS.
+
+- [ ] **Step 5: Commit**
+
+```
+git add extension/src/shared/password-coloring.ts extension/src/shared/__tests__/password-coloring.test.ts
+git commit -m "feat(ext/shared): add colorizePassword utility"
+```
+
+---
+
+## Phase B — Color scheme storage + apply
+
+### Task 2: `applyColorScheme()` + storage round-trip
+
+**Files:**
+- Create: `extension/src/shared/color-scheme.ts`
+- Create: `extension/src/shared/__tests__/color-scheme.test.ts`
+
+- [ ] **Step 1: Write the failing tests**
+
+`extension/src/shared/__tests__/color-scheme.test.ts`:
+
+```ts
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { JSDOM } from 'jsdom';
+import {
+  loadColorScheme, saveColorScheme, resetColorScheme, applyColorScheme,
+  DEFAULT_DIGIT_COLOR, DEFAULT_SYMBOL_COLOR,
+} from '../color-scheme';
+
+function mockChromeStorage(initial: any = {}) {
+  const store = { ...initial };
+  (global as any).chrome = {
+    storage: {
+      sync: {
+        get: vi.fn((key: string) => Promise.resolve(
+          key in store ? { [key]: store[key] } : {})),
+        set: vi.fn((kv: any) => { Object.assign(store, kv); return Promise.resolve(); }),
+        remove: vi.fn((key: string) => { delete store[key]; return Promise.resolve(); }),
+      },
+    },
+  };
+  return store;
+}
+
+describe('color-scheme storage', () => {
+  beforeEach(() => {
+    const dom = new JSDOM('<!DOCTYPE html><body></body>');
+    (global as any).document = dom.window.document;
+  });
+
+  it('load returns defaults when storage is empty', async () => {
+    mockChromeStorage();
+    const scheme = await loadColorScheme();
+    expect(scheme.digit_color).toBe(DEFAULT_DIGIT_COLOR);
+    expect(scheme.symbol_color).toBe(DEFAULT_SYMBOL_COLOR);
+  });
+
+  it('load returns stored values when present', async () => {
+    mockChromeStorage({
+      password_display_scheme: { digit_color: '#123456', symbol_color: '#abcdef' },
+    });
+    const scheme = await loadColorScheme();
+    expect(scheme.digit_color).toBe('#123456');
+    expect(scheme.symbol_color).toBe('#abcdef');
+  });
+
+  it('save round-trips', async () => {
+    mockChromeStorage();
+    await saveColorScheme({ digit_color: '#111111', symbol_color: '#222222' });
+    const scheme = await loadColorScheme();
+    expect(scheme).toEqual({ digit_color: '#111111', symbol_color: '#222222' });
+  });
+
+  it('reset removes the storage key', async () => {
+    const store = mockChromeStorage({
+      password_display_scheme: { digit_color: '#000', symbol_color: '#fff' },
+    });
+    await resetColorScheme();
+    expect(store.password_display_scheme).toBeUndefined();
+    const scheme = await loadColorScheme();
+    expect(scheme.digit_color).toBe(DEFAULT_DIGIT_COLOR);
+  });
+
+  it('apply sets CSS custom properties on document.documentElement', async () => {
+    mockChromeStorage({
+      password_display_scheme: { digit_color: '#deadbe', symbol_color: '#feed00' },
+    });
+    await applyColorScheme();
+    const root = document.documentElement.style;
+    expect(root.getPropertyValue('--relicario-pwd-digit-color').trim()).toBe('#deadbe');
+    expect(root.getPropertyValue('--relicario-pwd-symbol-color').trim()).toBe('#feed00');
+  });
+
+  it('save rejects malformed hex values', async () => {
+    mockChromeStorage();
+    await expect(saveColorScheme({ digit_color: 'not-a-color', symbol_color: '#ffffff' }))
+      .rejects.toThrow();
+  });
+});
+```
+
+- [ ] **Step 2: Run — expect compile failure**
+
+```
+cd extension && npm run test -- color-scheme
+```
+
+Expected: missing module.
+
+- [ ] **Step 3: Implement**
+
+`extension/src/shared/color-scheme.ts`:
+
+```ts
+export const DEFAULT_DIGIT_COLOR = '#2563eb';
+export const DEFAULT_SYMBOL_COLOR = '#dc2626';
+const STORAGE_KEY = 'password_display_scheme';
+const HEX_RE = /^#[0-9a-fA-F]{6}$/;
+
+export interface ColorScheme {
+  digit_color: string;
+  symbol_color: string;
+}
+
+export const DEFAULT_SCHEME: ColorScheme = {
+  digit_color: DEFAULT_DIGIT_COLOR,
+  symbol_color: DEFAULT_SYMBOL_COLOR,
+};
+
+function isValid(s: ColorScheme): boolean {
+  return HEX_RE.test(s.digit_color) && HEX_RE.test(s.symbol_color);
+}
+
+export async function loadColorScheme(): Promise<ColorScheme> {
+  const result = await chrome.storage.sync.get(STORAGE_KEY);
+  const stored = result[STORAGE_KEY] as Partial<ColorScheme> | undefined;
+  if (!stored) return { ...DEFAULT_SCHEME };
+  const merged: ColorScheme = {
+    digit_color: typeof stored.digit_color === 'string' && HEX_RE.test(stored.digit_color)
+      ? stored.digit_color : DEFAULT_DIGIT_COLOR,
+    symbol_color: typeof stored.symbol_color === 'string' && HEX_RE.test(stored.symbol_color)
+      ? stored.symbol_color : DEFAULT_SYMBOL_COLOR,
+  };
+  return merged;
+}
+
+export async function saveColorScheme(scheme: ColorScheme): Promise<void> {
+  if (!isValid(scheme)) {
+    throw new Error('Invalid color values; expected #rrggbb hex strings.');
+  }
+  await chrome.storage.sync.set({ [STORAGE_KEY]: scheme });
+}
+
+export async function resetColorScheme(): Promise<void> {
+  await chrome.storage.sync.remove(STORAGE_KEY);
+}
+
+/**
+ * Read the user's stored scheme (or defaults) and apply the colors as inline
+ * CSS custom properties on `document.documentElement`. Idempotent — safe to
+ * call on every popup/vault boot, and from a chrome.storage.onChanged handler
+ * to react to live edits from another open extension surface.
+ */
+export async function applyColorScheme(): Promise<void> {
+  const scheme = await loadColorScheme();
+  const root = document.documentElement.style;
+  root.setProperty('--relicario-pwd-digit-color', scheme.digit_color);
+  root.setProperty('--relicario-pwd-symbol-color', scheme.symbol_color);
+}
+```
+
+- [ ] **Step 4: Run — expect pass**
+
+```
+cd extension && npm run test -- color-scheme
+```
+
+Expected: 6 PASS.
+
+- [ ] **Step 5: Commit**
+
+```
+git add extension/src/shared/color-scheme.ts extension/src/shared/__tests__/color-scheme.test.ts
+git commit -m "feat(ext/shared): color-scheme storage + applyColorScheme"
+```
+
+---
+
+## Phase C — Stylesheet integration
+
+### Task 3: Add CSS rules + custom-property defaults
+
+**Files:**
+- Modify: `extension/src/popup/styles.css`
+- Modify: `extension/src/vault/vault.css` (and any other extension stylesheet that styles password reveal cells)
+
+- [ ] **Step 1: Add the rules**
+
+Append to each stylesheet (or to a single shared partial if the build supports CSS imports):
+
+```css
+:root {
+  --relicario-pwd-digit-color: #2563eb;
+  --relicario-pwd-symbol-color: #dc2626;
+}
+.pwd-digit  { color: var(--relicario-pwd-digit-color); }
+.pwd-symbol { color: var(--relicario-pwd-symbol-color); }
+.pwd-letter { color: inherit; }
+```
+
+- [ ] **Step 2: Build the extension**
+
+```
+cd extension && npm run build
+```
+
+Expected: clean build, no CSS errors.
+
+- [ ] **Step 3: Commit**
+
+```
+git add extension/src/popup/styles.css extension/src/vault/vault.css
+git commit -m "style(ext): add password-coloring CSS rules + custom property defaults"
+```
+
+---
+
+## Phase D — Wire into reveal surfaces
+
+### Task 4: Field-history viewer
+
+**Files:**
+- Modify: `extension/src/popup/components/field-history.ts`
+
+- [ ] **Step 1: Locate the text-content assignment**
+
+```
+grep -n "history-entry__value\|displayValue" extension/src/popup/components/field-history.ts
+```
+
+The line near 72 reads roughly:
+
+```ts
+<div class="history-entry__value ${isRevealed ? 'revealed' : 'masked'}">${displayValue}</div>
+```
+
+This is template-string interpolation, so `displayValue` is escaped HTML. The change requires switching from a string-template render to an imperative DOM patch (since `colorizePassword()` returns DOM, not HTML strings).
+
+- [ ] **Step 2: Update the render to imperatively set content**
+
+After the template renders the entry's outer markup, query the `.history-entry__value` element for revealed entries and replace its `textContent` with `colorizePassword(value)`:
+
+```ts
+import { colorizePassword } from '../../shared/password-coloring';
+
+// existing render ...
+
+container.querySelectorAll('.history-entry__value.revealed').forEach((el, idx) => {
+  el.textContent = '';
+  el.appendChild(colorizePassword(revealedValues[idx]));
+});
+```
+
+(`revealedValues` here stands in for whatever array of revealed-entry values was already computed; adapt to actual variable names.)
+
+- [ ] **Step 3: Update or add a test for this surface**
+
+If `extension/src/popup/components/__tests__/field-history.test.ts` exists, add a case asserting that a revealed password's DOM contains `.pwd-*` spans. Otherwise just verify by running the existing test suite + a manual check.
+
+```ts
+it('revealed entry colorizes by character class', () => {
+  const dom = render(/* item with password "aB3$" in field history, revealed */);
+  const revealed = dom.querySelector('.history-entry__value.revealed')!;
+  expect(revealed.querySelector('.pwd-digit')?.textContent).toBe('3');
+  expect(revealed.querySelector('.pwd-symbol')?.textContent).toBe('$');
+});
+```
+
+- [ ] **Step 4: Run tests + manual visual check**
+
+```
+cd extension && npm run test
+```
+
+Expected: PASS. Then build and load the extension to verify a revealed password in the field-history viewer is colored.
+
+- [ ] **Step 5: Commit**
+
+```
+git add extension/src/popup/components/field-history.ts \
+        extension/src/popup/components/__tests__/field-history.test.ts
+git commit -m "feat(ext/popup/field-history): colorize revealed password entries"
+```
+
+---
+
+### Task 5: Popup vault item detail (password reveal)
+
+**Files:**
+- Modify: the popup component that renders the password field's revealed value (find via `grep -rn "field.*Password\|FieldKind.Password\|reveal" extension/src/popup/components/`)
+
+- [ ] **Step 1: Find the surface**
+
+Read the matched files and identify the line(s) that set the password text when revealed. The likely shape is a function `renderField(field)` with a branch on `field.kind === FieldKind.Password`.
+
+- [ ] **Step 2: Apply the same imperative pattern**
+
+Replace whatever currently sets the password's text content with:
+
+```ts
+import { colorizePassword } from '../../shared/password-coloring';
+
+passwordValueEl.textContent = '';
+if (revealed) {
+  passwordValueEl.appendChild(colorizePassword(field.value));
+} else {
+  passwordValueEl.textContent = '••••••••';
+}
+```
+
+- [ ] **Step 3: Run tests + manual check**
+
+```
+cd extension && npm run test
+```
+
+Build, load, reveal a password — confirm coloring.
+
+- [ ] **Step 4: Commit**
+
+```
+git add extension/src/popup/components/
+git commit -m "feat(ext/popup/item-detail): colorize revealed password field"
+```
+
+---
+
+### Task 6: Fullscreen vault item detail
+
+**Files:**
+- Modify: the equivalent component under `extension/src/vault/`
+
+The fullscreen vault is currently undergoing a Phase 1 redesign (see `9ed7e7c` and the Phase 1 plan in `docs/superpowers/plans/2026-04-30-fullscreen-ux-phase-1-visual-foundation.md`). Coordinate with that work — if the password-reveal surface is in active flux, land this change after Phase 1 settles, or fold it into Phase 2 if the user is doing that work themselves.
+
+- [ ] **Step 1: Find the fullscreen reveal surface**
+
+```
+grep -rn "FieldKind.Password\|password.*reveal\|reveal.*password" extension/src/vault/
+```
+
+- [ ] **Step 2: Apply the same pattern as Task 5**
+
+Same code shape. Different file.
+
+- [ ] **Step 3: Run tests + manual check**
+
+Open the fullscreen vault, reveal a password, confirm coloring.
+
+- [ ] **Step 4: Commit**
+
+```
+git add extension/src/vault/
+git commit -m "feat(ext/vault): colorize revealed password field in fullscreen view"
+```
+
+---
+
+### Task 7: Generator preview
+
+**Files:**
+- Modify: the generator component (find via `grep -rn "generate_password\|generator.*preview" extension/src/`)
+
+- [ ] **Step 1: Find the surface**
+
+The generator likely has a live preview element that updates as the user adjusts character-class toggles, length, etc.
+
+- [ ] **Step 2: Apply the imperative pattern**
+
+```ts
+import { colorizePassword } from '../../shared/password-coloring';
+
+previewEl.textContent = '';
+previewEl.appendChild(colorizePassword(generatedPassword));
+```
+
+- [ ] **Step 3: Run tests + manual check**
+
+Open the generator, click roll/regenerate a few times — confirm the preview updates with coloring intact.
+
+- [ ] **Step 4: Commit**
+
+```
+git add extension/src/popup/components/  # or wherever the generator lives
+git commit -m "feat(ext/generator): colorize live password preview"
+```
+
+---
+
+## Phase E — Boot wiring
+
+### Task 8: Call `applyColorScheme()` on popup + vault startup
+
+**Files:**
+- Modify: `extension/src/popup/popup.ts` (or `popup/index.ts` — the popup's bootstrap)
+- Modify: `extension/src/vault/vault.ts` — the fullscreen vault's bootstrap
+
+- [ ] **Step 1: Add the call in popup boot**
+
+Near the top of the popup's `init()` / `main()` function:
+
+```ts
+import { applyColorScheme } from '../shared/color-scheme';
+
+await applyColorScheme();
+```
+
+The `await` is fine — it runs once per popup open, the storage round-trip is cheap (sub-millisecond).
+
+Also wire a `chrome.storage.onChanged` listener so live edits from another open extension surface (e.g., the settings page) reflect immediately:
+
+```ts
+chrome.storage.onChanged.addListener((changes, area) => {
+  if (area === 'sync' && 'password_display_scheme' in changes) {
+    void applyColorScheme();
+  }
+});
+```
+
+- [ ] **Step 2: Add the call in vault boot**
+
+Same pattern in the fullscreen vault's bootstrap.
+
+- [ ] **Step 3: Manual verification**
+
+Open both surfaces, edit the colors via the (about-to-exist) settings page, observe the change reflect in real time.
+
+- [ ] **Step 4: Commit**
+
+```
+git add extension/src/popup/popup.ts extension/src/vault/vault.ts
+git commit -m "feat(ext): apply color scheme on popup + vault startup, react to storage changes"
+```
+
+---
+
+## Phase F — Settings UI
+
+### Task 9: Display section in settings with color pickers + preview swatch + reset
+
+**Files:**
+- Modify: an existing settings component — best candidate is `extension/src/popup/components/settings.ts` (general settings) or a new dedicated section if settings are split. Read the existing settings layout before deciding.
+- Test: `extension/src/popup/components/__tests__/settings.test.ts` (extend existing tests)
+
+- [ ] **Step 1: Find the existing settings shape**
+
+```
+grep -n "render\|section\|setting" extension/src/popup/components/settings.ts | head -30
+```
+
+Identify the pattern used to render a settings group (likely a `section` builder + child controls).
+
+- [ ] **Step 2: Add the Display section**
+
+Following the existing pattern:
+
+```ts
+import {
+  loadColorScheme, saveColorScheme, resetColorScheme,
+  DEFAULT_DIGIT_COLOR, DEFAULT_SYMBOL_COLOR,
+} from '../../shared/color-scheme';
+import { colorizePassword } from '../../shared/password-coloring';
+
+async function renderDisplaySection(parent: HTMLElement) {
+  const section = createSection('Display');
+  parent.appendChild(section);
+
+  const scheme = await loadColorScheme();
+
+  const digitInput = createColorInput('Digit color', scheme.digit_color);
+  const symbolInput = createColorInput('Symbol color', scheme.symbol_color);
+  const swatch = document.createElement('div');
+  swatch.className = 'color-preview-swatch';
+
+  const SAMPLE = 'Abc123!@#xyz';
+
+  const updateSwatch = () => {
+    swatch.style.setProperty('--relicario-pwd-digit-color', digitInput.value);
+    swatch.style.setProperty('--relicario-pwd-symbol-color', symbolInput.value);
+    swatch.textContent = '';
+    swatch.appendChild(colorizePassword(SAMPLE));
+  };
+  updateSwatch();
+
+  const onChange = async () => {
+    updateSwatch();
+    try {
+      await saveColorScheme({
+        digit_color: digitInput.value, symbol_color: symbolInput.value,
+      });
+    } catch (e) {
+      // Show inline error; keep current swatch.
+    }
+  };
+  digitInput.addEventListener('change', onChange);
+  symbolInput.addEventListener('change', onChange);
+
+  const resetBtn = document.createElement('button');
+  resetBtn.textContent = 'Reset to defaults';
+  resetBtn.addEventListener('click', async () => {
+    digitInput.value = DEFAULT_DIGIT_COLOR;
+    symbolInput.value = DEFAULT_SYMBOL_COLOR;
+    await resetColorScheme();
+    updateSwatch();
+  });
+
+  section.append(digitInput, symbolInput, swatch, resetBtn);
+}
+
+function createColorInput(label: string, value: string): HTMLInputElement & { label: string } {
+  // simple <label><input type=color>...
+  const input = document.createElement('input') as HTMLInputElement & { label: string };
+  input.type = 'color';
+  input.value = value;
+  input.label = label;
+  return input;
+}
+```
+
+(Adapt to the existing component-creation idioms — the snippet above is illustrative.)
+
+- [ ] **Step 3: Add the swatch styling**
+
+In the popup stylesheet:
+
+```css
+.color-preview-swatch {
+  font-family: ui-monospace, monospace;
+  font-size: 1.1rem;
+  padding: 8px 12px;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  margin-top: 8px;
+  background: #fff;
+}
+.color-preview-swatch .pwd-digit  { color: var(--relicario-pwd-digit-color); }
+.color-preview-swatch .pwd-symbol { color: var(--relicario-pwd-symbol-color); }
+.color-preview-swatch .pwd-letter { color: inherit; }
+```
+
+(The custom properties are scoped to `.color-preview-swatch` itself via `style.setProperty`, so the swatch's preview is independent of the global root scheme — handy for previewing changes without committing them.)
+
+- [ ] **Step 4: Add a settings test**
+
+In `extension/src/popup/components/__tests__/settings.test.ts`, add:
+
+```ts
+it('Display section round-trips color scheme to storage', async () => {
+  // mock chrome.storage.sync, render settings, change the digit color picker,
+  // assert chrome.storage.sync.set was called with the new value.
+  // (Detailed scaffolding follows the existing tests in this file.)
+});
+
+it('Reset button clears storage and restores swatch defaults', async () => {
+  // render, change colors, click reset, assert chrome.storage.sync.remove
+  // was called and swatch reverts.
+});
+```
+
+- [ ] **Step 5: Run all extension tests**
+
+```
+cd extension && npm run test
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```
+git add extension/src/popup/components/settings.ts \
+        extension/src/popup/components/__tests__/settings.test.ts \
+        extension/src/popup/styles.css
+git commit -m "feat(ext/settings): Display section with color pickers + swatch + reset"
+```
+
+---
+
+## Self-Review Notes
+
+Spec coverage check:
+
+- **`colorizePassword` utility, single source of truth:** Task 1.
+- **Three character classes (digit / symbol / letter), Unicode-letter classification:** Task 1.
+- **CSS rules with custom properties + defaults:** Task 3.
+- **Storage shape (`password_display_scheme`), default fallbacks, hex validation:** Task 2.
+- **`applyColorScheme()` boot step on popup + vault:** Task 8.
+- **Live updates via `chrome.storage.onChanged`:** Task 8.
+- **Wire into field-history viewer:** Task 4.
+- **Wire into popup item detail:** Task 5.
+- **Wire into fullscreen item detail:** Task 6.
+- **Wire into generator preview:** Task 7.
+- **Settings UI with pickers + preview swatch + reset:** Task 9.
+- **WCAG AA contrast warning:** spec says non-blocking; this is a small follow-up not gated by anything in this plan, so it is **not** included as a separate task. Either add a tiny inline contrast check in Task 9's `onChange` (left as an exercise — the contrast formula is `(L1 + 0.05) / (L2 + 0.05)`; show a `.contrast-warning` element when below 4.5) or open a follow-up issue.
+
+No placeholders. No type drift (the `ColorScheme` interface and `PWD_*` constants are referenced consistently).
+
+---
+
+## Coordination note
+
+The fullscreen UX redesign (Phase 1, recently merged in `87e63c2`) is in flight. **Task 6** (fullscreen reveal surface) touches code that may also be touched by ongoing UX work — coordinate with the user before landing it. Tasks 1–5, 7–9 are independent of fullscreen work and can land standalone.
+
+---
+
+## Execution Handoff
+
+Plan complete and saved to `docs/superpowers/plans/2026-05-01-password-coloring.md`.
+
+When ready to execute, the user's preference per `feedback_subagent_default` is **subagent-driven**: a fresh subagent per task, with two-stage review between tasks.

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

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

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

@@ -1,10 +1,12 @@
-# relicario — Design Specification
+# Relicario — Design Specification
+
+> **Status:** historical. V1 shipped 2026-04-22; several "Post-V1 Ideas" listed below (typed items, attachments, secure documents, TOTP, Firefox extension, LastPass import, device authentication) have since shipped. See `CHANGELOG.md` and `docs/architecture/overview.md` for current state. Do not edit this spec as if it were architecture documentation — it is a time-stamped decision artifact.
 
 A git-backed, self-hostable password manager with a Rust core, CLI, and Chrome browser extension. The reference image as a DCT-embedded secret carrier is the core differentiator.
 
 ## Overview
 
-relicario is a password manager where vault decryption requires two independent factors: a passphrase the user memorizes and a reference JPEG that carries a 256-bit secret embedded via DCT steganography. The vault lives in a git repository (self-hosted on the user's own Gitea instance), and the server only ever sees opaque ciphertext. Compromise of either factor alone is insufficient to decrypt the vault.
+Relicario is a password manager where vault decryption requires two independent factors: a passphrase the user memorizes and a reference JPEG that carries a 256-bit secret embedded via DCT steganography. The vault lives in a git repository (self-hosted on the user's own Gitea instance), and the server only ever sees opaque ciphertext. Compromise of either factor alone is insufficient to decrypt the vault.
 
 Primary goals: portfolio project for adlee.work, architectural elegance, legibility-as-security (the README should read as the security proof), learning Rust, and fun to tinker with.
 
@@ -23,7 +25,7 @@ A collection of credentials (usernames, passwords, URLs, TOTP seeds, notes) belo
 | Stolen device | Filesystem: reference image, device key, cached vault | Decrypt vault | Attacker has image_secret but not passphrase. Argon2id makes brute-force expensive. |
 | Stolen device + weak passphrase | Same + feasible brute-force | Decrypt vault | Enforce minimum passphrase strength at vault creation. Universal worst case. |
 | Shoulder surfer | Observed passphrase | Decrypt vault (if they also get image) | Passphrase alone insufficient — still need image_secret. |
-| Credential stuffing | Leaked email/password from other breaches | Access user's accounts | relicario generates unique passwords per site. Breach of site A doesn't compromise site B. |
+| Credential stuffing | Leaked email/password from other breaches | Access user's accounts | Relicario generates unique passwords per site. Breach of site A doesn't compromise site B. |
 
 ### Out of scope
 
@@ -79,7 +81,7 @@ With a 4-word diceware passphrase (~51 bits) and Argon2id at 64 MiB, brute-force
 Compared to competitors:
 - LastPass/Bitwarden: server breach exposes ~40-60 bits (master password only)
 - 1Password: server breach exposes password + 128-bit Secret Key
-- relicario: server breach exposes password + 256-bit image_secret
+- Relicario: server breach exposes password + 256-bit image_secret
 
 ### Authenticated encryption
 

docs/superpowers/specs/2026-04-12-relicario-credential-capture-design.md

@@ -1,4 +1,4 @@
-# relicario — Credential Capture Design
+# Relicario — Credential Capture Design
 
 Experimental feature that detects login form submissions and prompts the user to save or update credentials in the vault. Configurable prompt style (notification bar or toast). Off by default.
 
@@ -60,7 +60,7 @@ A fixed-position bar at the top of the page, injected into the DOM:
 
 ```
 ┌──────────────────────────────────────────────────────────────────┐
-│  relicario: Save login for github.com? (alee)   [Save] [Never] [✕] │
+│  Relicario: Save login for github.com? (alee)   [Save] [Never] [✕] │
 └──────────────────────────────────────────────────────────────────┘
 ```
 
@@ -77,7 +77,7 @@ A floating element in the bottom-right corner:
 
 ```
 ┌─────────────────────────────────┐
-│  relicario                         │
+│  Relicario                         │
 │  Save login for github.com?     │
 │  alee                           │
 │  [Save] [Never] [✕]            │

docs/superpowers/specs/2026-04-12-relicario-firefox-extension-design.md

@@ -1,4 +1,4 @@
-# relicario — Firefox Extension Port Design
+# Relicario — Firefox Extension Port Design
 
 Port the existing Chrome MV3 extension to Firefox. Shared TypeScript source, separate manifests, separate build outputs. No code changes to components, popup, or content script.
 

docs/superpowers/specs/2026-04-12-relicario-init-wizard-design.md

@@ -1,6 +1,6 @@
-# relicario — Standalone Vault Initialization Wizard Design
+# Relicario — Standalone Vault Initialization Wizard Design
 
-A browser-based wizard that guides new users through creating an relicario vault from scratch. Lives at `extension/setup.html`, uses the same WASM module as the extension, same terminal dark aesthetic. No server, no Rust toolchain required.
+A browser-based wizard that guides new users through creating a Relicario vault from scratch. Lives at `extension/setup.html`, uses the same WASM module as the extension, same terminal dark aesthetic. No server, no Rust toolchain required.
 
 ## Scope
 
@@ -81,9 +81,9 @@ Two things happen:
 - Show warning: "Keep this image safe. You need it alongside your passphrase to unlock the vault. Store it somewhere you won't lose it."
 
 **Push config to extension (if available):**
-- Try to detect the relicario extension via `chrome.runtime.sendMessage` with a `get_setup_state` message
+- Try to detect the Relicario extension via `chrome.runtime.sendMessage` with a `get_setup_state` message
 - If extension responds: push `save_setup` message with `{ config: { hostType, hostUrl, repoPath, apiToken }, imageBase64 }`. Show "Extension configured! You can now open the extension and unlock your vault."
-- If extension not detected: show the config as a copyable JSON blob with instructions: "Install the relicario extension, then paste this into the setup wizard." (Or just tell them to run through the extension setup manually with the same host/token/repo.)
+- If extension not detected: show the config as a copyable JSON blob with instructions: "Install the Relicario extension, then paste this into the setup wizard." (Or just tell them to run through the extension setup manually with the same host/token/repo.)
 
 ## WASM Crate Change
 

docs/superpowers/specs/2026-04-12-relicario-wasm-extension-design.md

@@ -1,6 +1,6 @@
-# relicario — WASM + Chrome MV3 Extension Design
+# Relicario — WASM + Chrome MV3 Extension Design
 
-The browser extension for relicario. Compiles `relicario-core` to WASM, wraps it in a Chrome MV3 extension with a terminal-aesthetic popup, conservative autofill, and direct Gitea/GitHub API access. No CLI dependency, no native messaging bridge.
+The browser extension for Relicario. Compiles `relicario-core` to WASM, wraps it in a Chrome MV3 extension with a terminal-aesthetic popup, conservative autofill, and direct Gitea/GitHub API access. No CLI dependency, no native messaging bridge.
 
 ## Scope
 
@@ -330,7 +330,7 @@ No shadow DOM traversal. No heuristic scoring. No iframe inspection. If the form
 ### 2. Field Icon Injection
 
 When a password field is detected:
-- Small relicario icon (16x16, inline SVG) appears at the right edge of the password field
+- Small Relicario icon (16x16, inline SVG) appears at the right edge of the password field
 - Click triggers: send page URL to service worker → get matching entries
 - Single match: fill immediately
 - Multiple matches: show inline picker (small dropdown below the icon)

docs/superpowers/specs/2026-04-18-relicario-typed-items-design.md

@@ -1,6 +1,6 @@
-# relicario — Typed Item Data Model Design
+# Relicario — Typed Item Data Model Design
 
-Foundational data-model rewrite for relicario. Replaces the single `Entry` type with a polymorphic typed-item system supporting Login, SecureNote, Identity, Card, Key, Document, and TOTP — with sections, custom fields, attachments, password history, soft-delete, and the security architecture needed to support 1Password-style daily-driver UX.
+Foundational data-model rewrite for Relicario. Replaces the single `Entry` type with a polymorphic typed-item system supporting Login, SecureNote, Identity, Card, Key, Document, and TOTP — with sections, custom fields, attachments, password history, soft-delete, and the security architecture needed to support 1Password-style daily-driver UX.
 
 This is **Phase 1** of the broader 1Password-parity roadmap. Phase 0 (audit remediation) is the precursor implementation pass; Phase 2+ (admin portal, importers, Watchtower checks, etc.) build on top of this model.
 

docs/superpowers/specs/2026-04-20-relicario-extension-1c-alpha-design.md

@@ -1,4 +1,4 @@
-# relicario — Extension Plan 1C-α (Foundation) Design
+# Relicario — Extension Plan 1C-α (Foundation) Design
 
 First of three sub-plans that port the browser extension from the v1 single-`Entry` data model to the typed-item model landed in Plans 1A + 1B. 1C-α is the **foundation slice**: rebuild the WASM artifact, migrate shared types, rewrite the service worker against the opaque `SessionHandle` surface, split the message router with sender checks, wire the full security architecture from the typed-items spec, and achieve Login-parity on the new stack. Other six item types show "Coming in 1C-β" placeholders.
 

docs/superpowers/specs/2026-04-22-relicario-extension-1c-beta1-design.md

@@ -0,0 +1,401 @@
+# Relicario — Extension Plan 1C-β₁ (Typed-Item Forms) Design
+
+Second of three sub-plans porting the extension to the typed-item core. 1C-α (foundation) shipped Login-parity; 1C-β₁ adds the **other 5 typed-item forms** so the extension can daily-drive every typed item the Rust core knows about (except Document, deferred to γ for attachment dependencies). Custom-fields editor, vault-settings view, and advanced generator UI move to **β₂**.
+
+Reference: 1C-α design `docs/superpowers/specs/2026-04-20-relicario-extension-1c-alpha-design.md` (commits `a1d733d`, `ad6d8af`); 1C-α implementation merged 2026-04-22 (`2b83105`, tag `plan-1c-alpha-complete`).
+
+## Plan 1C decomposition (post-α refinement)
+
+| Sub-plan | Status | Scope |
+|---|---|---|
+| 1C-α | shipped 2026-04-22 | WASM rebuild, shared TS types, SessionHandle SW, split router with sender checks, full security architecture, Login-parity popup, zxcvbn setup gate |
+| **1C-β₁ (this spec)** | proposed | 5 typed-item forms (SecureNote / Identity / Card / Key / Totp) + Rust Steam encoding fix |
+| 1C-β₂ | proposed | Custom fields editor, full vault-settings view, advanced generator-request UI |
+| 1C-γ | proposed | Attachments (with `putBlob` Git-Data-API fallback), Document type, trash view, field-history view, device management |
+
+## Design Decisions (from brainstorming)
+
+| Question | Decision | Why |
+|---|---|---|
+| Does β stay one plan or split? | **β₁ + β₂** | Settings view + custom-fields editor are heavy independently; splitting unlocks daily-driver typed items as soon as β₁ ships |
+| Document type in β₁? | **Defer to γ** | `DocumentCore.primary_attachment` is required; without attachment upload there's nothing to attach |
+| Form visual style? | **Type-flavored, muted** | "Signature block + uniform rows" pattern: each type gets one accent panel + plain rows for the rest. Lower contrast than vivid v1 mockup, sits with the dark-terminal aesthetic |
+| Totp variants in β₁? | **TOTP + Steam** (Hotp deferred) | Steam Guard is widely used; Hotp is rare and needs counter-persistence UX |
+| Steam encoding in Rust core? | **Yes — fix as Slice 1** | Existing `compute_totp_code` returns decimal output for `kind: 'steam'`, which doesn't match Steam Guard. ~30 line patch + test vectors |
+| Sequencing? | **5 slices: Rust Steam → shared helpers + Login refactor → SecureNote+Identity → Card+Key → Totp** | Helper extraction pays off across 5 forms; pairing trivial types together; Totp last because it depends on Steam fix |
+| Custom fields in β₁? | **No — β₂** | Custom fields are the single hardest UI in β; deserves its own focused cycle |
+
+## Scope
+
+### In
+- 5 typed-item forms wired end-to-end (view + add + edit + delete): SecureNote, Identity, Card, Key, Totp.
+- Form style: muted "signature block + uniform rows" with thin left-border accent per type.
+- **Steam Guard** support on Totp items: `kind: 'totp'` and `kind: 'steam'` selectable in the form; UI toggle (no dropdown).
+- **Rust core fix**: `compute_totp_code` learns the Steam alphabet (`23456789BCDFGHJKMNPQRTVWXY`, 5-char output).
+- Concealed-with-reveal+copy pattern applied to: `Card.number`, `Card.cvv`, `Card.pin`, `Key.key_material`, `Totp.secret` (rendered as base32). Re-uses Login's existing convention via a new shared helper.
+- Shared helper module `extension/src/popup/components/fields.ts` for row / concealed-row / signature-block primitives. **Login refactored onto it** as the reference implementation (net code reduction even before adding 5 new types).
+- `item-detail.ts` and `item-form.ts` collapse to thin dispatchers calling `types/<x>.renderDetail()` / `renderForm()`.
+- "New…" picker on the toolbar's `+ New` button, listing all 7 types (Document greyed/disabled with "coming in γ" tooltip).
+- Per-type Vitest unit tests for the form→Item transform.
+
+### Out (→ β₂ / γ)
+- Custom fields editor (sections + per-field add/rename/remove/reorder). β₂.
+- Vault-settings view (retention, generator defaults, attachment caps). β₂.
+- Advanced generator-request UI (BIP39 vs Random, charset toggles, length slider). β₂.
+- Hotp counter UI. β₂ or later.
+- Per-type form custom defaults (e.g. exposing `Totp.digits` / `Totp.period_seconds`). β₂ via the custom-fields editor.
+- Document type. γ.
+- Attachment upload, trash view, field-history view, device-management UI. γ.
+
+## File map
+
+### New
+```
+crates/relicario-core/src/item_types/totp.rs          # Steam alphabet output (modified)
+extension/src/popup/components/fields.ts              # row / concealed-row / signature-block helpers
+extension/src/popup/components/types/login.ts         # extracted from existing item-detail/form Login branches
+extension/src/popup/components/types/secure-note.ts
+extension/src/popup/components/types/identity.ts
+extension/src/popup/components/types/card.ts
+extension/src/popup/components/types/key.ts
+extension/src/popup/components/types/totp.ts
+extension/src/popup/components/__tests__/fields.test.ts
+extension/src/popup/components/types/__tests__/save-shape.test.ts
+```
+
+### Modified
+```
+extension/src/popup/components/item-detail.ts         # dispatch on item.type → types/<x>.renderDetail
+extension/src/popup/components/item-form.ts           # dispatch on item.type → types/<x>.renderForm
+extension/src/popup/components/item-list.ts           # "+ New" button opens type picker
+extension/src/popup/styles.css                        # signature-block + field-row classes
+crates/relicario-core/src/item_types/totp.rs          # see above
+```
+
+### Deleted
+None.
+
+## Slice 1 — Rust Steam encoding
+
+**File**: `crates/relicario-core/src/item_types/totp.rs`
+
+Patch shape:
+
+```rust
+const STEAM_ALPHABET: &[u8] = b"23456789BCDFGHJKMNPQRTVWXY";
+
+pub fn compute_totp_code(config: &TotpConfig, now_unix_seconds: u64) -> Result<String> {
+    let counter = match config.kind {
+        TotpKind::Totp        => now_unix_seconds / config.period_seconds as u64,
+        TotpKind::Hotp { counter } => counter,
+        TotpKind::Steam       => now_unix_seconds / config.period_seconds as u64,
+    };
+    // ... existing HMAC + dynamic-truncation logic produces `truncated: u32` ...
+
+    if matches!(config.kind, TotpKind::Steam) {
+        let mut t = truncated;
+        let mut out = String::with_capacity(5);
+        for _ in 0..5 {
+            out.push(STEAM_ALPHABET[(t % 26) as usize] as char);
+            t /= 26;
+        }
+        return Ok(out);
+    }
+
+    let modulus = 10u32.pow(config.digits as u32);
+    Ok(format!("{:0width$}", truncated % modulus, width = config.digits as usize))
+}
+```
+
+`STEAM_ALPHABET` deliberately excludes `0`, `O`, `1`, `I`, `L`, `S`, `5`, `A`, `Z`. Same alphabet used by Steam Mobile Authenticator and WinAuth.
+
+### Tests (in the same file)
+
+- `steam_known_vector`: pin a `(secret, counter)` to its known Steam output. If a citeable third-party vector is available, prefer it; otherwise pin the value our impl computes today (regression test against accidental future change).
+- `steam_alphabet_no_ambiguous_chars`: `assert!(!STEAM_ALPHABET.contains(&b'0' / &b'O' / &b'1' / &b'I' / &b'L' / &b'S' / &b'5' / &b'A' / &b'Z'))`.
+- `steam_output_is_5_chars`: regardless of `config.digits`, Steam output is exactly 5 characters.
+- `totp_kind_decimal_unaffected`: existing RFC 6238 vectors for `kind: 'totp'` still pass byte-for-byte.
+
+### WASM impact
+
+`totp_compute` in `crates/relicario-wasm/src/lib.rs` doesn't change — it forwards `kind` through serde. The TS `TotpKind` shape in `extension/src/shared/types.ts` is already correct. Only the Rust-side compute body changes.
+
+## Slice 2 — Shared field helpers + Login refactor
+
+### `extension/src/popup/components/fields.ts`
+
+Pure functions returning HTML strings + a small mount-time event-binding helper. No DOM ownership, no state.
+
+```ts
+import { escapeHtml } from '../popup';
+
+export interface RowOpts {
+  label: string;
+  value: string;
+  copyable?: boolean;
+  href?: string;          // wraps value in <a target="_blank" rel="noopener">
+  monospace?: boolean;
+  multiline?: boolean;    // renders as <pre> instead of inline
+}
+export function renderRow(opts: RowOpts): string;
+
+export interface ConcealedRowOpts {
+  id: string;             // unique within the rendered detail view
+  label: string;
+  value: string;          // plaintext; rendered hidden until user reveals
+  monospace?: boolean;
+  multiline?: boolean;    // <pre> when revealed; "•••• (N chars)" when hidden
+}
+export function renderConcealedRow(opts: ConcealedRowOpts): string;
+
+export interface SignatureBlockOpts {
+  accent?: 'blue' | 'green' | 'amber' | 'red';   // default 'blue'
+  children: string;        // HTML, caller's responsibility to escape
+}
+export function renderSignatureBlock(opts: SignatureBlockOpts): string;
+
+/// Wire reveal-toggle + copy handlers for all rows rendered above.
+/// Call once after the parent's innerHTML lands.
+export function wireFieldHandlers(scope: HTMLElement): void;
+```
+
+`wireFieldHandlers` looks for `data-field-action="reveal"` and `data-field-action="copy"` attributes inside `scope` and binds click handlers. Reveal toggles a `data-revealed` attribute on the row's value `<span>`/`<pre>`; copy uses `navigator.clipboard.writeText` and flashes a 1.5s "copied" badge.
+
+### CSS additions in `extension/src/popup/styles.css`
+
+```css
+.field-row {
+  display: grid;
+  grid-template-columns: 90px 1fr auto;
+  gap: 8px 10px;
+  align-items: baseline;
+  padding: 4px 0;
+  font-size: 12px;
+}
+.field-row__label   { color: #8b949e; }
+.field-row__value   { color: #c9d1d9; }
+.field-row__value.monospace { font-family: "SF Mono", "JetBrains Mono", monospace; }
+.field-row__value pre { margin: 0; white-space: pre-wrap; word-break: break-word; }
+.field-row__actions { display: flex; gap: 6px; font-size: 11px; color: #8b949e; }
+.field-row__actions button {
+  background: transparent; border: 0; color: inherit;
+  cursor: pointer; padding: 0; font: inherit;
+}
+.field-row__actions button:hover { color: #c9d1d9; }
+
+.sig-block {
+  background: #161b22;
+  border: 1px solid #30363d;
+  border-left: 3px solid #1f6feb;
+  border-radius: 5px;
+  padding: 14px;
+  margin-bottom: 10px;
+}
+.sig-block--blue  { border-left-color: #1f6feb; }
+.sig-block--green { border-left-color: #3fb950; }
+.sig-block--amber { border-left-color: #d29922; }
+.sig-block--red   { border-left-color: #f85149; }
+```
+
+### Login refactor (same slice)
+
+Extract `popup/components/types/login.ts` exporting `renderDetail(app, item)` / `renderForm(app, mode, existing)` / private `saveLogin(...)`. The bodies are the existing Login-branch code from `item-detail.ts` / `item-form.ts`, ported to use `renderRow` / `renderConcealedRow` / `renderSignatureBlock` instead of inline string concatenation.
+
+Net-line check: this slice should reduce total LOC slightly (helper consolidation) before adding any new types.
+
+### Helper unit tests (`fields.test.ts`)
+
+- `renderRow` produces expected HTML for plain / copyable / linked / monospace / multiline cases.
+- `renderConcealedRow` produces the hidden initial state, includes the unique id in `data-field-id`, has show + copy buttons, hides multiline value as `"•••• (N chars)"`.
+- `renderSignatureBlock` wraps children correctly with each accent class.
+- `wireFieldHandlers`: with a happy-dom `<div>` containing rendered rows, clicking the show button toggles `data-revealed`; clicking copy calls `navigator.clipboard.writeText` (mock).
+
+## Slices 3–5 — Per-type designs
+
+### SecureNote (Slice 3a)
+
+**Data**: `SecureNoteCore { body: Zeroizing<String> }`.
+
+**Detail view**: title at top, then a single signature block (accent `green`) containing the body rendered as a concealed `<pre>` block (multiline concealed row). Copy button copies the whole body verbatim. No other rows.
+
+**Form view**: a single `<textarea>` (10-row default) for the body. Title at the top (always required on the Item envelope, not on the body field). No signature-block visual on the form — the textarea is the content.
+
+### Identity (Slice 3b)
+
+**Data**: `IdentityCore { full_name?, address? (multiline), phone?, email?, date_of_birth? }`.
+
+**Detail view**: title at top; signature block (accent `amber`) with a monogram "avatar" (initials extracted from `full_name`, or `?`) + the name in larger type. Below the block, plain rows in this order: phone, email, address (multiline), date_of_birth (formatted as the user's locale via `toLocaleDateString`). Email and phone are copyable.
+
+**Form view**: plain rows:
+- `full_name`: `<input type="text">`
+- `address`: `<textarea>` (3 rows)
+- `phone`: `<input type="tel">`
+- `email`: `<input type="email">` (browser-native validation surfaces on submit)
+- `date_of_birth`: `<input type="date">` — wire format matches Rust `NaiveDate`'s `"YYYY-MM-DD"` serialization
+
+Empty strings → `undefined` per the established convention.
+
+### Card (Slice 4a)
+
+**Data**: `CardCore { number?, holder?, expiry?: MonthYear, cvv?, pin?, kind: CardKind }`. `MonthYear = { month, year }`. `CardKind = 'credit' | 'debit' | 'gift' | 'loyalty' | 'other'`.
+
+**Detail view**: title at top; signature block (accent `blue`) matching the v2 mockup:
+- Top label band: `"<BRAND> · <KIND>"` uppercased (brand derived from card BIN; see below)
+- Masked card number with reveal toggle, monospace, letter-spaced
+- Footer: HOLDER (left) and EXPIRES (right)
+
+Below the signature block: concealed rows for `cvv` and `pin`.
+
+Brand derivation (display-only, not stored):
+```ts
+function brandFromNumber(num: string): string {
+  if (/^3[47]/.test(num))  return 'AMEX';
+  if (/^4/.test(num))      return 'VISA';
+  if (/^5[1-5]/.test(num)) return 'MASTERCARD';
+  if (/^6/.test(num))      return 'DISCOVER';
+  return '';
+}
+```
+
+**Form view**: plain rows:
+- `number`: `<input type="text" inputmode="numeric">`, no formatting on the form (paste-friendly)
+- `holder`: `<input type="text">`
+- `expiry`: two side-by-side `<select>`s — month (`01`–`12`) + year (current ± 25). Saves as `{ month: number, year: number }`. Empty selection → `undefined` for the whole `expiry`.
+- `cvv`: `<input type="password" inputmode="numeric" maxlength="4">`
+- `pin`: `<input type="password" inputmode="numeric" maxlength="8">`
+- `kind`: `<select>` with the 5 enum values, default `credit`
+
+### Key (Slice 4b)
+
+**Data**: `KeyCore { key_material: Zeroizing<String>, label?, public_key?, algorithm? }`. `key_material` is required.
+
+**Detail view**: title at top; signature block (accent `green`) showing the `key_material` as a concealed monospace `<pre>` block. Below: plain rows for `label`, `algorithm` (free-form text), `public_key` (multiline monospace, **not concealed** — public keys are public).
+
+**Form view**: plain rows:
+- `key_material`: `<textarea>` (8 rows, monospace) with a sibling `[show]` toggle button (since `<textarea>` doesn't honor `type="password"`). Default state: a CSS rule sets `-webkit-text-security: disc` to mask characters; clicking the toggle removes the rule.
+- `label`: `<input type="text">`
+- `public_key`: `<textarea>` (4 rows, monospace, no masking)
+- `algorithm`: `<input type="text">` placeholder `"ed25519"`
+
+### Totp (Slice 5)
+
+**Data**: `TotpCore { config: TotpConfig, issuer?, label? }`. `TotpConfig = { secret: number[], algorithm: 'sha1'|'sha256'|'sha512', digits: number, period_seconds: number, kind: TotpKind }`. β₁ supports `kind: 'totp'` and `kind: 'steam'`.
+
+**Detail view**: title at top (uses `issuer / label` to construct a default if title is empty: `"<issuer>: <label>"`). Signature block (accent `blue`) shows:
+- Large monospace rotating code (centered, 28pt)
+- Thin SVG countdown ring at the right side, sized 32×32
+
+Below the block: plain rows for `issuer`, `label`, and a concealed row for `secret` (rendered as base32 via `shared/base32.ts` `base32Encode`).
+
+The ring re-tick interval is 1000ms; on each tick it calls `chrome.runtime.sendMessage({ type: 'get_totp', id })` (the existing α handler in `router/popup-only.ts` — no new message type). The countdown value is `(expires_at - now)` per the existing `TotpResponse`.
+
+**Form view**: a kind toggle at the top, then plain rows:
+
+```
+┌─ kind ──────────────────────────┐
+│  [● TOTP]  [○ Steam Guard]      │
+└─────────────────────────────────┘
+secret (base32):  [_______________]
+issuer:           [_______________]
+label:            [_______________]
+```
+
+Toggle is a two-button group; click switches `state.kind` and re-renders the small subtitle below ("Standard time-based codes" vs "Steam Mobile Authenticator (5-char alphanumeric)"). For both kinds, `digits` / `period_seconds` / `algorithm` are written with their defaults (`6`/`30`/`sha1` for TOTP; `5`/`30`/`sha1` for Steam — Steam's compute uses the alphabet, ignoring the digits field). Power users who need non-default values use the CLI; β₂ may add a `[more options ▾]` disclosure on the Totp form if this turns out to bite real users.
+
+`secret` parsed via `base32Decode` from `shared/base32.ts` (already exists). Empty string is rejected with a friendly error from the popup's `humanizeError` path.
+
+### Dispatcher updates
+
+`item-detail.ts` after β₁:
+
+```ts
+import * as login      from './types/login';
+import * as secureNote from './types/secure-note';
+import * as identity   from './types/identity';
+import * as card       from './types/card';
+import * as key        from './types/key';
+import * as totp       from './types/totp';
+
+export async function renderItemDetail(app: HTMLElement): Promise<void> {
+  const item = getState().selectedItem;
+  if (!item) { navigate('list'); return; }
+  switch (item.type) {
+    case 'login':       return login.renderDetail(app, item);
+    case 'secure_note': return secureNote.renderDetail(app, item);
+    case 'identity':    return identity.renderDetail(app, item);
+    case 'card':        return card.renderDetail(app, item);
+    case 'key':         return key.renderDetail(app, item);
+    case 'totp':        return totp.renderDetail(app, item);
+    case 'document':    return renderComingSoonPlaceholder(app, item.type);
+  }
+}
+```
+
+`item-form.ts` follows the same shape with `renderForm(app, mode, existing)`.
+
+### "New…" picker
+
+`item-list.ts`'s `+ New` button opens a small picker (popover anchored to the button):
+
+```
+new item
+  🔑 login
+  📝 secure note
+  🪪 identity
+  💳 card
+  🗝 key
+  ⏱ totp
+  📄 document    ← greyed; tooltip "coming in γ — needs attachment upload"
+```
+
+Selecting a type stores `state.newType` (transient — added to PopupState with `'login' | 'secure_note' | …`) and navigates to `'add'`. The form dispatcher reads `state.newType` for add-mode and `state.selectedItem.type` for edit-mode.
+
+The popover lives in the popup's own DOM (no closed Shadow DOM needed — the popup is its own origin and not subject to page-injection threats). Standard `<div>` with `position: absolute` anchored to the button.
+
+## Testing
+
+### Rust
+
+`cargo test --workspace` stays green. New tests in `crates/relicario-core/src/item_types/totp.rs` listed in §Slice 1.
+
+### Vitest
+
+Existing 55 tests stay green. New:
+
+- `extension/src/popup/components/__tests__/fields.test.ts` (helper unit tests, ~12 cases).
+- `extension/src/popup/components/types/__tests__/save-shape.test.ts` (per-type form→Item transform, ~5 cases × ~3 sub-assertions = ~15 cases).
+
+The save-shape tests use happy-dom to render each form's HTML, populate inputs, fire the save handler, and intercept the `add_item` message via a `vi.fn()` shim of `chrome.runtime.sendMessage`. Asserts cover:
+
+- SecureNote: `core.body === '<input value>'`, `core.type === 'secure_note'`.
+- Identity: each present field in JS shape matches the wire format; absent fields are `undefined` (not empty string).
+- Card: `expiry === { month: 8, year: 2029 }`; concealed fields (`number`/`cvv`/`pin`) round-trip through the form values; `kind` matches the select.
+- Key: `key_material` always present; `algorithm` free-form.
+- Totp: `config.secret === Array.from(base32Decode('JBSWY3DPEHPK3PXP'))`; `config.kind === 'totp'` or `'steam'` depending on toggle; for Steam, `config.digits === 5`.
+
+### Manual matrix
+
+Re-run the α matrix's 11 steps (§5.4 of α spec) plus, per type:
+
+1. Add a new item of the type → it appears in the list with the right icon.
+2. Open the item → detail view renders correctly (signature block + rows; no console errors).
+3. For types with concealed fields: click reveal → value appears; click copy → clipboard contains the value.
+4. Edit → save → list updates with new modified time; detail reflects changes.
+5. Trash → moves out of the live list; CLI `relicario list --trashed` shows it.
+6. For Totp: code rotates every 30s; Steam Guard kind produces 5-char alphanumeric; TOTP kind produces 6-digit decimal; switching kinds in the edit form re-renders the detail view's compute output correctly after save.
+
+### Acceptance
+
+- `cargo test --workspace` green.
+- `bun run test` green.
+- `bun run build:all` green for both Chrome and Firefox.
+- `git grep -n 'coming-soon\|Coming in' extension/src/popup/components/` returns hits ONLY for `'document'`.
+- All 5 type matrices pass on Chrome and Firefox.
+- No new lint regressions; `git grep -n '@ts-nocheck' extension/src/` returns zero.
+
+## Open questions deferred to the plan
+
+- Exact CSS sizing of the Totp signature block's countdown ring (32px or 40px). Picked at implementation time.
+- Whether the Card brand-from-BIN is comprehensive enough (currently 4 brands). Likely fine for α/β₁ — extending the table is a one-line change.
+- For Steam toggle UX: a two-button group or a dropdown. Brainstorming locked in two-button; implementation may push back if it's awkward at popup width.
+- Whether to expose `Totp.algorithm` / `digits` / `period_seconds` to power users via a `[more options ▾]` disclosure on the form. β₁ defaults them; β₂ revisits if the CLI workaround friction is real.

docs/superpowers/specs/2026-04-22-relicario-extension-1c-beta2-design.md

@@ -0,0 +1,731 @@
+# Relicario — Extension Plan 1C-β₂ (Custom Fields + Settings + Generator UI) Design
+
+Third of three β sub-plans porting the extension to the typed-item core. 1C-α shipped the security architecture + Login parity; 1C-β₁ added the 5 remaining typed-item forms; **1C-β₂** (this spec) adds the cross-cutting UI surfaces: custom fields editor, full vault-settings view, and an inline generator popover.
+
+Reference specs: `docs/superpowers/specs/2026-04-20-relicario-extension-1c-alpha-design.md` (α, commits `a1d733d` + `ad6d8af`), `docs/superpowers/specs/2026-04-22-relicario-extension-1c-beta1-design.md` (β₁, commit `1b51b7d`). Both implementations merged to main: α at `2b83105` (tag `plan-1c-alpha-complete`), β₁ at `81fbe13` (tag `plan-1c-beta1-complete`).
+
+## Plan 1C decomposition (final shape)
+
+| Sub-plan | Status | Scope |
+|---|---|---|
+| 1C-α | shipped 2026-04-22 | WASM rebuild, typed-item shared TS types, SessionHandle SW, split router with sender checks, closed Shadow DOM content scripts, Login-parity popup, zxcvbn setup gate |
+| 1C-β₁ | shipped 2026-04-22 | 5 remaining typed-item forms (SecureNote / Identity / Card / Key / Totp) + Rust Steam-Guard alphabet patch; shared field helpers + Login refactor |
+| **1C-β₂** (this spec) | proposed | Custom-fields editor (Text/Password/Concealed), full VaultSettings view (retention + generator defaults + origin-ack revoke), advanced generator popover |
+| 1C-γ | proposed | Attachments (with `putBlob` Git-Data-API fallback), Document type, trash view, field-history view, device management, attachment caps UI |
+
+## Design Decisions (from brainstorming)
+
+| Question | Decision | Why |
+|---|---|---|
+| Custom-fields scope | **Tier 1 — Text/Password/Concealed only, no reordering** | The other 8 FieldKinds (Url/Email/Phone/Date/MonthYear/Totp/Reference/Multiline) each add real UX work; tier 1 covers the "recovery codes, security questions" 90% case. Reordering and additional kinds live in a later polish pass. |
+| VaultSettings scope | **Retention + generator defaults + origin-ack revoke; skip attachment caps** | Attachment caps govern a feature that doesn't ship until γ. Ship the caps UI alongside the feature. |
+| Generator UI location | **Inline popover + Settings preview** | One underlying `GeneratorRequest` config, two entry points. Matches 1Password/Bitwarden. "save as default" in the popover updates Settings without forcing the user to navigate. |
+| Custom-fields edit-view placement | **Collapsible disclosure ("▸ custom sections & fields (N)")** | Most items never grow custom fields; always-visible editor adds clutter for the 90% case. Count-hint on the disclosure gives discoverability without noise. |
+| Sequencing | **5 slices: detail render → edit render → vault-settings SW (+ generate_passphrase if missing) → generator popover → settings view** | Matches β₁'s cadence. SW plumbing lands before the popover so "save as default" is fully functional the moment the popover ships. |
+
+## Scope
+
+### In
+
+- **Custom-fields rendering** (detail view): `Item.sections` rendered below typed rows via a new `renderSections(item, idPrefix)` helper in `fields.ts`. Sections with ≥1 field render a header (named) or thin separator (anonymous). Fields of kind `text` render via `renderRow`; `password`/`concealed` via `renderConcealedRow` with per-section unique IDs.
+
+- **Custom-fields editor** (edit view): collapsible disclosure ("▸ custom sections & fields (N)") at the bottom of every type's form. Expanded state shows each section's rename/remove buttons, per-field label + value inputs + `×` delete, and per-section `[+ text] [+ password] [+ concealed]` buttons. A `[+ add section]` button at the bottom. Sections have optional names (rename via `prompt()`; clear to make anonymous). Save packs `sectionsDraft` into the outgoing `Item.sections`.
+
+- **FieldKind support**: `text`, `password`, `concealed` only. `Url` / `Email` / `Phone` / `Date` / `MonthYear` / `Totp` / `Reference` / `Multiline` all remain Rust-core-only (the data model supports them; the popup doesn't render editors for them in β₂).
+
+- **No reordering**: new fields append to their section's `fields` array; new sections append to `item.sections`. Rendering preserves array order. A future polish pass can add up/down arrows or drag handles.
+
+- **Full VaultSettings view**: new `popup/components/settings-vault.ts` screen wired to the ⚙ toolbar button (now a tiny picker: device / vault). Covers:
+  - Trash retention (`Days(N)` / `Forever`) via a preset dropdown (Forever / 7 / 30 / 60 / 90 / 180 / 365 / custom days).
+  - Field-history retention (`LastN(N)` / `Days(N)` / `Forever`) via a preset dropdown (Forever / Last 3 / Last 5 / Last 10 / 30 days / 90 days / 365 days / custom).
+  - Generator-default preview with a "configure ▾" button that opens the same generator popover used at form "gen" sites; "save as default" closes the loop.
+  - Origin-ack list (`autofill_origin_acks`) sorted by most-recent first, with per-host revoke buttons.
+  - Save-changes / discard buttons; save disabled until `pendingSettings` differs from `vaultSettings`.
+
+- **Advanced generator popover**: new `popup/components/generator-popover.ts`. Anchored to the "gen" button; positioned absolutely below. Kind toggle (Random / BIP39). Random knobs: length slider (8-64), 4 char-class checkboxes, symbol-charset toggle (safe_only / extended / custom). BIP39 knobs: word count slider (3-12), separator chip picker (space / `-` / `_` / `.` / `:`), capitalization picker (lower / upper / first-of-each / title). Live preview via `generate_password` / `generate_passphrase` message on 150ms debounce. Four action buttons: `reset to defaults`, `save as default`, `cancel`, `use this value`. Validation: "use this value" disabled when no char class selected for Random kind.
+
+- **New popup-only messages**: `get_vault_settings` → returns full `VaultSettings`. `update_vault_settings` → writes full `VaultSettings`. Both added to `POPUP_ONLY_TYPES`; not in `SETUP_ALLOWED`. Router test matrix grows by 4 cases (accept from popup × 2, reject from content × 2).
+
+- **Teardown integration**: every type module's `teardown()` gains `closeGeneratorPopover()`. The collapsible disclosure's expanded-state (`sectionsExpanded: boolean`) is module-scope and reset by `teardown()`.
+
+### Out (→ γ / later)
+
+- Reordering (sections or fields-within-section).
+- Other FieldKind variants (Url/Email/Phone/Date/MonthYear/Totp/Reference/Multiline).
+- Attachment caps UI (γ concern, bundled with attachments).
+- Bulk custom-field operations (delete-many, template, import-from-CSV).
+- Per-type section templates (e.g., Card auto-creates a "billing address" section).
+- Item-to-item `Reference` pointers (requires attachment picker).
+
+## Architecture
+
+### Data flow additions
+
+1. **Custom fields**: already present end-to-end — the Rust core's `Item.sections: Vec<Section>` + `Section.fields: Vec<Field>` + `Field.value: FieldValue` data model is complete. β₁'s save paths already pass `sections: existing?.sections ?? []` through. β₂ just grows the UI to produce and consume that shape. No SW message changes.
+
+2. **Vault settings**: α plumbed `fetchAndDecryptSettings` / `encryptAndWriteSettings` through `service-worker/vault.ts` for the autofill origin-ack writes. β₂ exposes the full `VaultSettings` object via two new popup-only messages. No new Rust or WASM work.
+
+3. **Generator popover**: already has all the plumbing it needs — α's `generate_password` / `generate_passphrase` messages accept an arbitrary `GeneratorRequest` and route to the WASM layer. β₂ just wires a UI.
+
+### Module boundaries
+
+```
+popup/components/
+  fields.ts                     (extended) — + renderSections, renderSectionsEditor,
+                                              wireSectionsEditor, generateFieldId
+  generator-popover.ts          (new)      — openGeneratorPopover, closeGeneratorPopover
+  settings-vault.ts             (new)      — renderVaultSettings
+  item-list.ts                  (edit)     — ⚙ toolbar button → device/vault picker
+  types/login.ts                (edit)     — + sections tail in renderDetail;
+                                              + disclosure in renderForm;
+                                              + generator popover wire on "gen" button;
+                                              + closeGeneratorPopover in teardown
+  types/{secure-note,identity,card,key,totp}.ts  (edit) — same integration pattern
+
+service-worker/
+  router/popup-only.ts          (edit)     — + get_vault_settings, update_vault_settings
+
+shared/
+  messages.ts                   (edit)     — + 2 new PopupMessage variants, added to POPUP_ONLY_TYPES
+  types.ts                      (unchanged)
+
+popup/popup.ts                  (edit)     — + vaultSettings + generatorDefaults in PopupState;
+                                              + fetch after unlock; + settings-vault view route
+```
+
+### PopupState additions
+
+```ts
+vaultSettings: VaultSettings | null;        // cached on unlock; refreshed on save
+generatorDefaults: GeneratorRequest | null; // derived from vaultSettings.generator_defaults
+view: 'locked' | 'list' | 'detail' | 'add' | 'edit' | 'settings' | 'settings-vault';
+```
+
+The `'settings-vault'` view routes to the new `renderVaultSettings`.
+
+## Slice 1 — Custom-fields detail rendering
+
+### `fields.ts#renderSections`
+
+```ts
+export function renderSections(item: Item, idPrefix: string): string;
+```
+
+- Walks `item.sections`. For each section with ≥1 field:
+  - If `section.name` truthy: emit `<div class="section-header">{escaped name}</div>`
+  - Else (anonymous): emit `<hr class="section-separator">`
+  - For each field:
+    - `field.value.kind === 'text'` → `renderRow({ label: field.label, value: field.value.value, copyable: true })`
+    - `field.value.kind === 'password'` / `'concealed'` → `renderConcealedRow({ id: `${idPrefix}-s${sectionIdx}-f${fieldIdx}`, label: field.label, value: field.value.value })`
+    - Other kinds: silently skip in β₂ (the Rust core may carry other-kind fields from the CLI; we render what we support).
+
+### Per-type integration
+
+Every type module's `renderDetail` gets a call to `renderSections` between typed rows and action buttons:
+
+```ts
+app.innerHTML = `
+  <div class="pad">
+    ${/* signature block + typed rows */}
+    ${renderSections(item, '<type>')}   // ← added
+    ${/* form-actions */}
+  </div>
+`;
+```
+
+`wireFieldHandlers(app)` call already at the bottom of each type module picks up the new reveal/copy buttons in custom-field rows.
+
+### Tests
+
+`types/__tests__/sections-render.test.ts`:
+- Empty `item.sections` → `renderSections` returns empty string.
+- One named section with 2 text fields → contains the section name + both field labels + both values as visible text.
+- Mixed text + password fields → password value concealed (not in visible DOM text); has reveal button.
+- Anonymous section → separator HR, no name header.
+- Unsupported kind (e.g., a `date` field from the CLI) → silently skipped, no error.
+
+### CSS
+
+```css
+.section-header {
+  margin-top: 14px;
+  margin-bottom: 4px;
+  padding-top: 10px;
+  border-top: 1px solid #21262d;
+  color: #8b949e;
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+.section-separator { margin: 10px 0 4px; border: 0; border-top: 1px solid #21262d; }
+```
+
+## Slice 2 — Custom-fields edit rendering
+
+### `fields.ts#renderSectionsEditor` + `wireSectionsEditor`
+
+```ts
+export function renderSectionsEditor(sections: Section[], expanded: boolean): string;
+
+/// Wire handlers for the editor's interactive elements. Mutations to
+/// `sectionsDraft` are reflected by `rerender()` — callers implement
+/// rerender by re-running `renderSectionsEditor` + inserting it back
+/// into the disclosure's body element.
+export function wireSectionsEditor(
+  scope: HTMLElement,
+  sectionsDraft: Section[],
+  rerender: () => void,
+): void;
+```
+
+### Layout (expanded state)
+
+```
+▾ custom sections & fields (2 sections, 5 fields)
+
+── recovery codes ──────  [rename] [× remove section]
+ [label_________] [value_________________] [×]
+ [label_________] [value_________________] [×]
+ [+ text]  [+ password]  [+ concealed]
+
+── (anonymous) ─────────  [rename] [× remove section]
+ [label_________] [value_________________] [×]
+ [+ text]  [+ password]  [+ concealed]
+
+[+ add section]
+```
+
+### `generateFieldId`
+
+```ts
+/// Client-side 16-char hex FieldId. Uses crypto.getRandomValues for
+/// 8 random bytes; matches the wire-format requirement. No SW round-trip.
+export function generateFieldId(): string {
+  const bytes = new Uint8Array(8);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes).map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+```
+
+### Mutations
+
+- **Add section**: `sectionsDraft.push({ name: undefined, fields: [] })`; rerender.
+- **Rename section**: `prompt('Section name (empty for none):', section.name ?? '')`; set `sectionsDraft[i].name = result.trim() || undefined`; rerender.
+- **Remove section**: `confirm('Remove section ...?')`; `sectionsDraft.splice(i, 1)`; rerender.
+- **Add field** (kind K): `sectionsDraft[i].fields.push(makeField(K))`; rerender. Helper:
+
+  ```ts
+  function makeField(kind: 'text' | 'password' | 'concealed'): Field {
+    const hidden = kind !== 'text';
+    return {
+      id: generateFieldId(),
+      label: 'new field',
+      kind,
+      value: { kind, value: '' } as FieldValue,
+      hidden_by_default: hidden,
+    };
+  }
+  ```
+
+- **Remove field**: `sectionsDraft[i].fields.splice(j, 1)`; rerender.
+- **Edit field label**: `input` event on label input mutates `sectionsDraft[i].fields[j].label` in place. No rerender (would steal focus).
+- **Edit field value**: `input` event mutates `sectionsDraft[i].fields[j].value.value` in place. No rerender.
+
+### Per-type form integration
+
+Each of the 6 type modules (`types/<x>.ts`):
+
+1. At the top of `renderForm`, initialize a local `sectionsDraft: Section[] = existing?.sections.map(deepClone) ?? []` (deep clone so cancel doesn't mutate the pre-existing item).
+2. Add `let sectionsExpanded = false;` at module scope, reset by `teardown()`.
+3. Insert `${renderSectionsEditor(sectionsDraft, sectionsExpanded)}` in the form HTML, just before `<div class="form-actions">`.
+4. After `app.innerHTML = ...`, call `wireSectionsEditor(app, sectionsDraft, rerender)` where `rerender` replaces the disclosure subtree's innerHTML with a fresh `renderSectionsEditor(sectionsDraft, sectionsExpanded)`.
+5. In save, replace `sections: existing?.sections ?? []` with `sections: sectionsDraft`.
+
+`deepClone` helper: `JSON.parse(JSON.stringify(existing.sections))` is sufficient for the `Section[]` shape (no class instances, no Date objects, no undefined in positions that need to survive).
+
+### Tests
+
+`types/__tests__/sections-edit.test.ts`:
+- Open form (add mode), click disclosure toggle → data-expanded flips true.
+- Click "+ add section" → one section appears; its field list is empty.
+- Rename the section via mocked `window.prompt` → section header updates.
+- Click "+ text" → a text field appears with label "new field" and empty value.
+- Edit the label + value inputs → assertions on the in-memory sectionsDraft.
+- Click save → `add_item` message's `item.sections` matches the draft structure.
+- Round-trip on edit mode: pre-populate `existing` with sections, open form, confirm sections render expanded (since count > 0), add a field, save → outgoing sections has the new field appended.
+
+### CSS additions
+
+```css
+.disclosure {
+  border-top: 1px solid #21262d;
+  margin-top: 14px;
+  padding-top: 10px;
+}
+.disclosure__toggle {
+  background: transparent; border: 0; color: #58a6ff;
+  cursor: pointer; font-size: 12px; padding: 0;
+  font-family: inherit;
+}
+.disclosure[data-expanded="false"] .disclosure__body { display: none; }
+.section-editor__head {
+  display: flex; align-items: baseline; gap: 8px;
+  margin-top: 10px; margin-bottom: 4px;
+  font-size: 11px;
+}
+.section-editor__head .name { color: #c9d1d9; font-weight: 600; }
+.section-editor__head .name.anon { color: #8b949e; font-style: italic; }
+.section-editor__head .actions { color: #8b949e; font-size: 10px; margin-left: auto; }
+.section-editor__head .actions button { background: transparent; border: 0; color: inherit; cursor: pointer; padding: 0; margin-left: 8px; }
+.section-editor__field {
+  display: grid; grid-template-columns: 120px 1fr auto;
+  gap: 4px; margin-bottom: 4px; font-size: 11px;
+}
+.section-editor__field input {
+  background: #0d1117; border: 1px solid #30363d; color: #c9d1d9;
+  padding: 3px 6px; border-radius: 3px; font: inherit; font-size: 11px;
+}
+.section-editor__field .delete-field {
+  background: transparent; border: 0; color: #f85149; cursor: pointer;
+  font-size: 14px; padding: 0 4px;
+}
+.section-editor__add {
+  display: flex; gap: 6px; margin-top: 6px;
+}
+.section-editor__add button {
+  background: transparent; border: 1px solid #30363d; color: #8b949e;
+  padding: 2px 10px; border-radius: 3px; cursor: pointer; font-size: 10px;
+  font-family: inherit;
+}
+.section-editor__add button:hover { color: #c9d1d9; border-color: #484f58; }
+.disclosure__body .add-section {
+  margin-top: 12px; background: transparent;
+  border: 1px dashed #30363d; color: #8b949e;
+  padding: 6px 10px; border-radius: 4px; cursor: pointer;
+  width: 100%; font-size: 11px; font-family: inherit;
+}
+.disclosure__body .add-section:hover { border-color: #484f58; color: #c9d1d9; }
+```
+
+## Slice 3 — Vault-settings SW plumbing
+
+### Messages
+
+`shared/messages.ts` — add to `PopupMessage`:
+```ts
+  | { type: 'get_vault_settings' }
+  | { type: 'update_vault_settings'; settings: VaultSettings }
+```
+
+Add both to `POPUP_ONLY_TYPES`. NOT in `SETUP_ALLOWED`.
+
+Add:
+```ts
+export interface VaultSettingsResponse extends Extract<Response, { ok: true }> {
+  data: { settings: VaultSettings };
+}
+```
+
+### Handlers (`router/popup-only.ts`)
+
+```ts
+case 'get_vault_settings': {
+  const handle = session.getCurrent();
+  if (!handle || !state.gitHost) return { ok: false, error: 'vault_locked' };
+  const settings = await vault.fetchAndDecryptSettings(state.gitHost, handle);
+  return { ok: true, data: { settings } };
+}
+
+case 'update_vault_settings': {
+  const handle = session.getCurrent();
+  if (!handle || !state.gitHost) return { ok: false, error: 'vault_locked' };
+  await vault.encryptAndWriteSettings(
+    state.gitHost, handle, msg.settings,
+    'settings: update vault-level config',
+  );
+  return { ok: true };
+}
+```
+
+### Router tests
+
+`router/__tests__/router.test.ts` (+4 cases):
+- `get_vault_settings` accepted from popup (mock `fetchAndDecryptSettings` → returns a `VaultSettings`); response shape matches `VaultSettingsResponse`.
+- `get_vault_settings` rejected from content → `unauthorized_sender`.
+- `update_vault_settings` accepted from popup; calls `encryptAndWriteSettings`.
+- `update_vault_settings` rejected from setup tab (not in SETUP_ALLOWED).
+
+### Popup init
+
+`popup.ts#init`, after a successful unlock-is-active branch:
+```ts
+const vsResp = await sendMessage({ type: 'get_vault_settings' });
+if (vsResp.ok) {
+  const vs = (vsResp.data as { settings: VaultSettings }).settings;
+  currentState.vaultSettings = vs;
+  currentState.generatorDefaults = vs.generator_defaults as GeneratorRequest;
+}
+```
+
+Fetched once at popup open; refreshed after any `update_vault_settings` success. The "fetch on open" cost is one extra round-trip over α — acceptable given vault-settings drives multiple screens.
+
+### `generate_passphrase` message (add if missing)
+
+The α plan lists `generate_password` as a popup-only message. The generator popover (Slice 4) also needs `generate_passphrase` for BIP39 preview. Check `shared/messages.ts`; if absent, add:
+
+```ts
+  | { type: 'generate_passphrase'; request: GeneratorRequest }
+```
+
+Add to `POPUP_ONLY_TYPES`. The SW handler mirrors `generate_password` but calls the `generate_passphrase` WASM function. One new case in `router/popup-only.ts`.
+
+## Slice 4 — Generator inline popover
+
+### `popup/components/generator-popover.ts`
+
+```ts
+export function openGeneratorPopover(opts: {
+  anchor: HTMLElement;
+  initial: GeneratorRequest;
+  onPicked: (value: string) => void;
+}): void;
+
+export function closeGeneratorPopover(): void;
+```
+
+Module-scope state:
+
+```ts
+let activePopover: {
+  host: HTMLElement;
+  onDismiss: () => void;
+} | null = null;
+let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+```
+
+### Layout (Random kind)
+
+```
+┌─ generate ────────────────── ✕ ┐
+│                                │
+│ kind:  [● Random] [○ BIP39]    │
+│                                │
+│ length: [════●═══════] 20       │
+│                                │
+│ ☑ lowercase   ☑ digits          │
+│ ☑ uppercase   ☑ symbols         │
+│                                │
+│ symbols:  [● safe] [○ extended] │
+│                                │
+│ ─ preview ──────────────────── │
+│  Kj7%pW@2xNq!8rMvT   [↻]        │
+│                                │
+│ [reset to defaults]             │
+│ [save as default]               │
+│ [cancel]      [use this value]  │
+└─────────────────────────────────┘
+```
+
+### Layout (BIP39 kind)
+
+```
+┌─ generate ────────────────── ✕ ┐
+│ kind:  [○ Random] [● BIP39]    │
+│                                │
+│ words:   [═══●════════] 5       │
+│                                │
+│ separator:  [space] [-] [_] [.] [:]
+│                                │
+│ capitalization:                │
+│   [● lower] [upper] [first] [title]
+│                                │
+│ ─ preview ──────────────────── │
+│  correct horse battery staple parapet
+│                                │
+│ [reset to defaults]             │
+│ [save as default]               │
+│ [cancel]      [use this value]  │
+└─────────────────────────────────┘
+```
+
+### Request construction
+
+```ts
+function buildRequest(kind: 'random' | 'bip39', knobs: UiKnobs): GeneratorRequest {
+  if (kind === 'random') {
+    return {
+      kind: 'random',
+      length: knobs.length,
+      classes: {
+        lower: knobs.lower, upper: knobs.upper,
+        digits: knobs.digits, symbols: knobs.symbols,
+      },
+      symbol_charset:
+        knobs.symbolCharset === 'safe_only' ? { kind: 'safe_only' } :
+        knobs.symbolCharset === 'extended' ? { kind: 'extended' } :
+        { kind: 'custom', value: knobs.customSymbols ?? '' },
+    };
+  }
+  return {
+    kind: 'bip39',
+    word_count: knobs.wordCount,
+    separator: knobs.separator,
+    capitalization: knobs.capitalization,
+  };
+}
+```
+
+### Preview refresh
+
+On any knob change, debounced 150ms:
+```ts
+async function refreshPreview(): Promise<void> {
+  const request = buildRequest(uiKind, uiKnobs);
+  const msg = uiKind === 'random'
+    ? { type: 'generate_password' as const, request }
+    : { type: 'generate_passphrase' as const, request };
+  const resp = await sendMessage(msg);
+  if (resp.ok) {
+    const data = resp.data as { password?: string; passphrase?: string };
+    const previewEl = activePopover?.host.querySelector('.gen-preview__value');
+    if (previewEl) previewEl.textContent = data.password ?? data.passphrase ?? '';
+  }
+}
+```
+
+Note: α added `generate_password` but `generate_passphrase` may need to be added (check α's `messages.ts`). If not present, add it alongside generate_password in slice 4's scope (router handler already accepts a `request_json` → WASM `generate_passphrase`).
+
+### Validation
+
+"use this value" button disabled when:
+- Random kind and no char-class checked (`!lower && !upper && !digits && !symbols`).
+- BIP39 kind never disabled (always valid — word count ≥ 3).
+
+Visual cue: when disabled, button is dimmed + a `<p class="gen-validation">pick at least one character class</p>` renders below.
+
+### Actions
+
+- **use this value**: `onPicked(currentPreview); close();`. Host field's setter wraps this (e.g., `pw.value = value; pw.type = 'text';` for the Login form).
+- **save as default**: fetch the full `vaultSettings` via `sendMessage({ type: 'get_vault_settings' })`; write `{ ...vaultSettings, generator_defaults: currentRequest }` via `update_vault_settings`. On success: update `state.vaultSettings` + `state.generatorDefaults`; flash "saved" on the button for 1.5s; do NOT close.
+- **reset to defaults**: reset UI knobs to `state.generatorDefaults ?? DEFAULT_PASSWORD_REQUEST`; refresh preview.
+- **cancel / Escape / outside-click**: close without callback.
+
+### Teardown wiring
+
+Every type module's existing `teardown()` gains:
+```ts
+closeGeneratorPopover();
+```
+So navigation or re-rendering always cleans up the popover.
+
+### Tests
+
+`__tests__/generator-popover.test.ts` (mocks `sendMessage`):
+- Open with default initial → renders Random kind, shows `length=20`, all 4 classes checked, safe_only.
+- BIP39 toggle → switches knobs to word-count / separator / capitalization; `sendMessage` called with `generate_passphrase`.
+- Length slider change → debounced `generate_password` call with updated `length`.
+- "use this value" → `onPicked` called with current preview string; popover closes.
+- "save as default" → `update_vault_settings` called with the current request merged into vaultSettings.
+- Uncheck all 4 classes in Random → "use this value" button disabled.
+- Escape key → popover closes without invoking onPicked.
+
+## Slice 5 — Settings view + revoke + default wiring
+
+### Routing
+
+`popup.ts`:
+- Add `'settings-vault'` to the `View` union.
+- Add the render-switch case pointing at `renderVaultSettings`.
+- Toolbar ⚙ button on `item-list.ts` becomes a tiny picker (render inline, same pattern as the "+ New" picker):
+
+```
+⚙
+├ device settings    → navigate('settings')
+└ vault settings     → navigate('settings-vault')
+```
+
+### `popup/components/settings-vault.ts`
+
+```ts
+export function renderVaultSettings(app: HTMLElement): void;
+```
+
+Module-scope state:
+- `pendingSettings: VaultSettings | null` — draft, initialized from `state.vaultSettings`, mutated by the screen.
+- `teardown()` exported; removes any active key handler.
+
+### Render body
+
+```html
+<div class="pad">
+  <div class="settings-header">
+    <button class="btn" id="back-btn">← back</button>
+    <h3>vault settings</h3>
+  </div>
+
+  <div class="settings-section">
+    <div class="settings-section__title">retention</div>
+    <div class="settings-row">
+      <span class="settings-row__label">trash</span>
+      <select id="trash-retention">...</select>
+    </div>
+    <div class="settings-row">
+      <span class="settings-row__label">field history</span>
+      <select id="history-retention">...</select>
+    </div>
+  </div>
+
+  <div class="settings-section">
+    <div class="settings-section__title">generator</div>
+    <p class="gen-preview-line">{humanSummary(pending.generator_defaults)}</p>
+    <button class="btn" id="configure-gen">configure ▾</button>
+  </div>
+
+  <div class="settings-section">
+    <div class="settings-section__title">autofill origins</div>
+    {if empty: <p class="muted">No origins acknowledged yet.</p>}
+    {else: sorted ack rows with revoke buttons}
+  </div>
+
+  <div class="settings-footer">
+    <button class="btn" id="discard-btn">discard</button>
+    <button class="btn btn-primary" id="save-btn" disabled>save changes</button>
+  </div>
+</div>
+```
+
+### Retention dropdown semantics
+
+`retentionSelectOptions(kind: 'trash' | 'history')`:
+- Trash: `Forever`, `7 days`, `30 days`, `60 days`, `90 days`, `180 days`, `365 days`, `custom…`.
+- History: `Forever`, `Last 3`, `Last 5`, `Last 10`, `30 days`, `90 days`, `365 days`, `custom…`.
+
+`retentionToSelectValue(r)` maps a `TrashRetention` / `HistoryRetention` union to one of those option labels (falling back to `custom…` if it's an N that doesn't match a preset).
+
+`selectValueToRetention(kind, label)` goes the other way. For `custom…`, `prompt()` the user for a number + unit.
+
+### Generator-default preview
+
+`humanSummary(req: GeneratorRequest): string`:
+- Random: `"Random, {length} chars, {classes joined with +}, {symbolCharset label}"`.
+- BIP39: `"BIP39, {word_count} words, {separator label}-separated, {capitalization}"`.
+
+Clicking "configure ▾" opens the generator popover (`openGeneratorPopover`) with `onPicked: () => {}` (no-op — the user's intent here is "save as default", not "insert into a field"). On popover close (after save-as-default or cancel), refresh `state.vaultSettings` via a `get_vault_settings` round-trip and re-render the settings screen. (The popover's "save as default" already calls `update_vault_settings` itself.)
+
+### Origin-ack list
+
+Sorted by `Object.entries(acks).sort(([, a], [, b]) => b - a)` (most recent first).
+
+Each row:
+```html
+<div class="ack-row">
+  <span class="ack-row__host">github.com</span>
+  <span class="ack-row__meta">acked 3d ago</span>
+  <button class="ack-row__revoke" data-host="github.com">revoke</button>
+</div>
+```
+
+Revoke handler: `delete pending.autofill_origin_acks[host]; rerender(); markDirty();`.
+
+### Save / discard
+
+`markDirty()` enables the save button. `save` sends `update_vault_settings` with `pending`; on success, updates `state.vaultSettings` + `state.generatorDefaults` and navigates back to the list. `discard` just navigates back.
+
+### Tests
+
+`__tests__/settings-vault.test.ts`:
+- Render with seeded `state.vaultSettings` — correct retention labels shown.
+- Change trash-retention select → `pending` updated; save button enabled.
+- Click revoke on an ack → `pending.autofill_origin_acks` loses that key; save button enabled.
+- Save → `update_vault_settings` called with `pending`; navigates back.
+- Discard → no message sent; navigates back.
+
+### CSS
+
+Additions in `popup/styles.css`:
+
+```css
+.settings-header { display: flex; align-items: center; gap: 10px; margin-bottom: 14px; }
+.settings-header h3 { margin: 0; font-size: 14px; }
+.settings-section {
+  margin-top: 14px; padding-top: 10px;
+  border-top: 1px solid #21262d;
+}
+.settings-section__title {
+  color: #8b949e; font-size: 10px;
+  text-transform: uppercase; letter-spacing: 0.08em;
+  margin-bottom: 6px;
+}
+.settings-row {
+  display: grid; grid-template-columns: 110px 1fr;
+  gap: 6px 10px; align-items: center;
+  margin: 4px 0; font-size: 12px;
+}
+.settings-row__label { color: #8b949e; }
+.settings-row select {
+  background: #0d1117; border: 1px solid #30363d; color: #c9d1d9;
+  padding: 3px 8px; border-radius: 3px; font: inherit; font-size: 11px;
+}
+.gen-preview-line {
+  margin: 0 0 6px; font-size: 11px; color: #c9d1d9;
+  font-family: "SF Mono", "JetBrains Mono", monospace;
+}
+.ack-row {
+  display: flex; justify-content: space-between; align-items: center;
+  padding: 4px 0; font-size: 11px;
+  border-bottom: 1px solid #161b22;
+}
+.ack-row__host { color: #c9d1d9; font-family: monospace; }
+.ack-row__meta { color: #6e7681; font-size: 10px; }
+.ack-row__revoke {
+  background: transparent; border: 0; color: #f85149;
+  cursor: pointer; font-size: 10px;
+}
+.settings-footer {
+  display: flex; justify-content: flex-end; gap: 6px;
+  margin-top: 20px; padding-top: 12px; border-top: 1px solid #21262d;
+}
+.btn-primary:disabled { opacity: 0.45; cursor: not-allowed; }
+```
+
+## Testing
+
+### Rust
+No Rust changes. `cargo test --workspace` stays green (155 tests from β₁).
+
+### Vitest
+Existing 84 tests stay green. New tests:
+- `types/__tests__/sections-render.test.ts` — ~5 tests.
+- `types/__tests__/sections-edit.test.ts` (or per-type variants as appropriate) — ~5 tests.
+- `__tests__/generator-popover.test.ts` — ~7 tests.
+- `router/__tests__/router.test.ts` (extensions) — ~4 tests.
+- `__tests__/settings-vault.test.ts` — ~5 tests.
+
+Target post-β₂: ~110 tests.
+
+### Manual matrix
+
+1. Add a Login item; in the form's disclosure, add a section named "recovery codes" with two password fields; save; open detail → sections appear below typed rows; reveal works on each concealed row; copy works on text rows.
+2. Edit the same item; remove one field; add a text field; save; detail reflects all three changes.
+3. Click ⚙ → vault settings; change trash retention to `7 days`; save; reload → still `7 days`.
+4. In vault settings, click "configure ▾" on the generator preview; change kind to BIP39; save as default; close popover; preview shows BIP39 summary. Reload → still BIP39.
+5. Back on Login form, click "gen" → popover opens with BIP39 defaults (inherited from settings).
+6. "use this value" on the popover fills the password field with a BIP39 phrase.
+7. Revoke an origin ack; save; attempt autofill on that site → requires-ack flow re-triggers (per α's content-callable handler).
+8. Kind toggle mid-popover switches Random ↔ BIP39; preview refreshes; request shape correct.
+
+### Acceptance
+
+- `cargo test --workspace` green.
+- `bun run test` green (~110 tests).
+- `bun run build:all` green for Chrome + Firefox.
+- `git grep -n '@ts-nocheck' extension/src/` → 0.
+- `git grep -n 'coming-soon\|Coming in' extension/src/popup/components/ | grep -v document` → 0.
+- Manual matrix 8 steps pass on both browsers.
+
+## Open questions deferred to plan
+
+- `generate_passphrase` message type: α shipped `generate_password`; if the message union lacks `generate_passphrase`, add it in Slice 4 alongside the vault-settings messages. The SW router just needs an additional case mirroring `generate_password`.
+- Custom-field label blanks: what happens when a field has an empty `label`? Options: (a) reject at save time; (b) allow and render as "(unnamed)". Plan ships (b) — no UX friction; render the value row with the row's label span empty.
+- Retention `custom…`: is the `prompt()` acceptable UX, or should it be an inline number + unit input? Plan ships `prompt()` (matches existing rename-section UX); can polish in a later pass.
+- Deep-equal check for save-button enable: `JSON.stringify(a) === JSON.stringify(b)` is cheap and sufficient for the `VaultSettings` shape (no Map/Set/Date keys). Avoids a util dependency.

docs/superpowers/specs/2026-04-24-relicario-extension-1c-gamma1-design.md

@@ -0,0 +1,283 @@
+# Plan 1C-γ₁: Attachments + Document type — design
+
+**Date:** 2026-04-24
+**Scope:** Wire the existing Rust attachment-encryption surface into the extension, add the Git host's missing `putBlob` operation (with Git Data API fallback for large blobs), introduce the Document item type that's been a "coming soon" stub since β₁, and surface attachments in both add-flow and view-flow inside the popup.
+
+## Goal
+
+The Rust core has shipped attachment encryption (`attachment_encrypt` / `attachment_decrypt`, exposed in WASM), the manifest already reserves an `attachment_summaries: Vec<AttachmentSummary>` field on each entry, and every typed item form already round-trips an `attachments: Vec<AttachmentRef>` array (currently always empty from the popup's side). What's missing is the extension plumbing: a UI to add/view attachments, a Document item-type form, a way to encrypt+upload the bytes through the service worker, and the missing `GitHost.putBlob` op (with the >900 KB Git Data API fallback that Contents API can't handle because of base64 inflation).
+
+γ₂ (later) will surface the views over already-supported core capabilities: trash, field history, device management, and the attachment-caps UI.
+
+## Non-goals
+
+- Trash view, field history view, device management UI, attachment-caps configuration UI — all γ₂.
+- Drag-drop file affordance — file picker only in v1; drag-drop is polish that can land later if usage warrants.
+- Multi-file upload at once — single file per pick; reduces edge cases (caps overshoot, partial-upload state) for γ₁.
+- Attachment count on item-list rows — γ₁ shows just a `📎` icon when an item has any attachments; the count is deferred (most users won't care about exact count, and it's noise on narrow rows).
+- Inline image preview panels in the disclosure body — γ₁ uses thumb-icons (16×16) in the row; click → browser download. The big inline-preview pane was option C earlier and was rejected as overkill for the popup's vertical budget.
+- Document type's signature-block image preview at large size — the detail view's gold "signature block" shows a 36×60 thumb plus filename/meta. Full-size in-popup viewing is not provided; user downloads to view full-resolution.
+
+## Visual identity
+
+### Attachments — compact disclosure (locked: pattern A)
+
+Every typed-item form (Login, SecureNote, Identity, Card, Key, TOTP, **Document**) gets an `attachments` disclosure rendered AFTER the type-specific fields and AFTER the existing `custom fields` disclosure. The disclosure header reads:
+
+- Empty: `▸ attachments`
+- Populated: `▾ attachments (N)` (with N being the count from `core.attachments.length`)
+
+Disclosure body in **edit mode**:
+
+- One row per existing attachment: `[icon-or-thumb] filename                   12 KB   ×`
+- A "+ attach file" button at the bottom, full-width, dashed border (`#30363d`), color `#8b949e` → `#c9d1d9` on hover. Clicking it triggers a hidden `<input type="file">` with no `multiple` attr.
+- The `×` removes the attachment from the editing item draft (does NOT delete the underlying blob from the git host until the item is saved — see "lifecycle" below).
+
+Disclosure body in **view mode**:
+
+- One row per attachment, same layout as edit mode, but the action column is `↓` (download) instead of `×`.
+- Click the row OR click the `↓` → triggers a browser download of the decrypted attachment via `chrome.downloads.download` (or anchor-tag fallback for Firefox). Browser handles preview for known mime types when the user opens the downloaded file.
+- No "+ attach file" button (only available in edit mode).
+
+### Image attachments — thumb-icon column (locked: pattern B)
+
+For attachment rows where `mime_type` starts with `image/`, the leading icon column renders a 16×16 thumbnail of the image instead of the generic `📄` glyph. The thumbnail is generated lazily:
+
+- On disclosure open, image-mime rows fetch their decrypted blob via SW message, create a `URL.createObjectURL(blob)` object URL, and use it as the `<img>` src in the icon column.
+- On disclosure close (or item navigation away, or popup close), all created object URLs are `URL.revokeObjectURL`'d in a teardown function. This keeps memory bounded.
+- For non-image attachments: render the generic `📄` glyph; no decryption work happens until the user clicks download.
+
+### Document type (locked: pattern C)
+
+The Document type's identifying field is its `primary_attachment` — a single, REQUIRED file. Form composition:
+
+- **title** (required, lowercase label + gold `*` per project polish)
+- **primary attachment** (required, gold `*`) — compact-row picker. Empty state: dashed-border `+ attach primary file` button. Filled state: a single row with `[thumb] filename 240 KB ↑ change`. Clicking `↑ change` re-triggers the file picker.
+- **notes** (optional, textarea)
+- **tags** (optional, comma-separated input — single text input with chip-style display below if implementer wants polish)
+- **expires** (optional, MM/YYYY two-input row using the existing pattern from Card's expiry)
+- **attachments disclosure** (optional supplementary attachments — same compact-disclosure pattern as other types)
+
+Detail view promotes the primary attachment to a **signature block** (gold left-border `border-left: 3px solid #aa812a`, `#161b22` background, padding 10 px). The signature block contains:
+
+- Left: 48×60 thumbnail (`linear-gradient(135deg, #b88a30, #7c5719)` for non-image; actual decrypted thumb for image-mime)
+- Right: filename (font 11 px, `#f1cf6e`, weight 600), meta line below in `#8b949e` showing `size · created` (e.g. `240 KB · 2026-04-12`), and an action line `↓ download · 🔍 preview` where `🔍 preview` only appears for image-mime attachments and triggers an inline expanded preview within the signature block (toggle).
+
+Below the signature block, the standard typed-rows render (notes, tags, expires) and finally the supplementary `attachments` disclosure if any exist.
+
+### Item-list attachment indicator (locked: 2c)
+
+Item-list rows currently render `[type-icon] [title] [favorite-star]`. After γ₁, items with at least one attachment also show a small `📎` glyph just before the favorite-star slot. No count is rendered. The row template change is one optional span; styling reuses the existing muted-text class.
+
+For Document items, the `📎` is implicit (every Document has at least the primary attachment), but we still render it for consistency.
+
+## Architecture
+
+### Upload pipeline
+
+End-to-end flow when the user clicks "+ attach file":
+
+1. Hidden `<input type="file">` opens browser file picker.
+2. On change, popup reads file via `FileReader.readAsArrayBuffer` (or just `file.arrayBuffer()`).
+3. Popup checks the bytes against `VaultSettings.attachment_caps.per_attachment_max_bytes` — if exceeded, show toast `"file too large (X MB / cap is Y MB)"` and abort. (Caps default to undefined / no limit if `attachment_caps` is empty; γ₂ adds the UI to set them.)
+4. Popup sends `{type: 'upload_attachment', itemId: <id>, filename, mimeType, bytes: <ArrayBuffer>}` to SW. The bytes go via `chrome.runtime.sendMessage` structured-clone — Chrome's per-message limit is generously above any reasonable attachment size we're targeting.
+5. SW receives in `popup-only.ts`:
+   - Verifies sender (popup-only, per existing router pattern)
+   - Calls WASM `attachment_encrypt(sessionHandle, bytes)` → returns `{id, bytes: encryptedBytes}` where `id = sha256(plaintext)`
+   - Constructs the storage path: `attachments/<id>.bin` (within the configured vault root path on the git host)
+   - Calls `gitHost.putBlob(path, encryptedBytes, message)` — the new operation on `GitHost` interface
+   - Updates the item's `attachments` array to include the new `AttachmentRef { id, filename, mime_type, size: plaintextLen, created: now() }`
+   - Updates the manifest's per-entry `attachment_summaries` array
+   - Persists both updated item.json and manifest.json via `gitHost.writeFile` (Contents API; small files)
+   - Returns `{ok: true, attachment: AttachmentRef}` to the popup
+6. Popup updates its in-memory item draft (or re-fetches the item from SW), re-renders the attachments disclosure with the new row, hides loading state.
+
+If any step fails, SW returns `{ok: false, error: 'upload_failed', detail: '...'}` and popup shows toast `"upload failed: <reason>"` without modifying the draft.
+
+### `GitHost.putBlob` — interface extension
+
+The `GitHost` interface (`extension/src/service-worker/git-host.ts`) currently has 4 ops: `readFile`, `writeFile`, `deleteFile`, `listDir`. γ₁ adds:
+
+```ts
+/// Write an opaque binary blob to the repo. Unlike writeFile, this is
+/// optimized for large attachments — implementations choose between
+/// Contents API (small) and Git Data API (large) based on byte length.
+/// Returns the path that was written (same as input, for chaining).
+putBlob(path: string, content: Uint8Array, message: string): Promise<string>;
+
+/// Read an opaque binary blob from the repo. Same semantics as readFile
+/// for small files; for large files the implementation may use the
+/// Git Data API to fetch the blob by its sha rather than the contents
+/// endpoint.
+getBlob(path: string): Promise<Uint8Array>;
+
+/// Delete a blob from the repo. For now identical to deleteFile, but
+/// kept distinct so future fallback paths (Git Data API) have a hook.
+deleteBlob(path: string, message: string): Promise<void>;
+```
+
+`getBlob` mirrors `readFile` but is named distinctly so we can later add streaming/chunked reads if needed. For γ₁ it's just a thin wrapper over `readFile` with no fallback (Contents API GET works for files up to 100 MB on GitHub; we read the encrypted bytes back as base64-decoded Uint8Array).
+
+`deleteBlob` is also a thin wrapper for now; kept distinct for symmetry with putBlob.
+
+### `putBlob` fallback strategy
+
+In `GitHubHost.putBlob` and `GiteaHost.putBlob`:
+
+```
+const THRESHOLD_BYTES = 900 * 1024;  // 900 KB pre-base64
+
+if (content.length <= THRESHOLD_BYTES) {
+  // Use existing writeFile path (Contents API PUT with base64-encoded content)
+  await this.writeFile(path, content, message);
+  return path;
+}
+
+// Git Data API fallback for large blobs:
+// 1. POST /repos/{owner}/{repo}/git/blobs  → returns blob SHA
+// 2. GET  /repos/{owner}/{repo}/branches/{branch}  → get current commit SHA + tree SHA
+// 3. POST /repos/{owner}/{repo}/git/trees  → create new tree with blob added at path, base_tree = current tree
+// 4. POST /repos/{owner}/{repo}/git/commits  → create commit with new tree, parent = current commit
+// 5. PATCH /repos/{owner}/{repo}/git/refs/heads/{branch}  → fast-forward branch to new commit
+```
+
+Both GitHub and Gitea expose these endpoints with the same shape (Gitea modeled itself after GitHub). One concrete divergence: the Gitea v1 API uses `/api/v1/repos/...` prefix; GitHub uses `/repos/...`. The existing `gitea.ts` and `github.ts` already encapsulate this divergence in their constructors. The fallback path adds 4 more endpoint calls per impl; we add them as private helper methods (`createGitBlob`, `getRefSha`, `createGitTree`, `createGitCommit`, `updateRef`) and orchestrate them in `putBlob`.
+
+The threshold `900 * 1024` is a constant exported from `git-host.ts` so both implementations agree. 900 KB pre-base64 → ~1.2 MB after base64 → safely under GitHub's 1 MB Contents API soft-limit and well under Gitea's tolerance.
+
+### Manifest update flow
+
+After every attach/detach, both the item file (`items/<id>.json`) and the manifest file (`manifest.json`) need to be updated atomically-as-possible:
+
+- Item file: re-encrypt the entire item with new `attachments` array
+- Manifest: re-encrypt the entire manifest with the entry's `attachment_summaries` field updated
+
+Two separate `writeFile` calls (the manifest is small, item file is small — both well under threshold). We accept the brief window where item is updated but manifest isn't yet: in the worst case, the popup sees the item with the new attachment but the manifest list view doesn't show the `📎` indicator until the next sync. This is acceptable — the user is the only one writing, and the popup will eagerly re-fetch the manifest after the upload completes.
+
+The blob itself (`attachments/<id>.bin`) is written FIRST, so even if the item/manifest writes fail, the blob exists in the repo (and a subsequent retry can reattach it). Orphaned blobs (referenced by no item) are tolerable — γ₂'s attachment-caps UI can include a "purge orphans" action later.
+
+### Attachment lifecycle
+
+**Add (during item edit):**
+1. User clicks "+ attach file" → file picker → chooses file
+2. Popup sends `upload_attachment` to SW with the bytes
+3. SW encrypts + putBlobs the encrypted bytes immediately (synchronous from the user's perspective; toast "uploading..." → "✓ added" or "✕ failed")
+4. SW returns the `AttachmentRef`; popup adds it to its in-memory item draft
+5. The item itself isn't saved until the user clicks "save" on the form. So between step 4 and the user clicking save, the blob exists in the repo but no item references it. If the user clicks "cancel" instead of save, the orphaned blob stays (will be garbage-collected by γ₂'s purge-orphans action).
+
+**Remove (during item edit):**
+1. User clicks `×` on an existing attachment row in the disclosure
+2. Popup removes the row from the in-memory draft (visual immediate)
+3. The blob is NOT deleted yet; on form save, the SW compares the saved item's attachments vs. the original and `deleteBlob`s any that were removed
+4. If user clicks "cancel" instead of save, the original item (and its blobs) are unchanged
+
+**Save with new attachments:**
+1. User clicks "save"
+2. Popup sends the updated item to SW (existing flow); SW writes item.json + manifest.json
+3. Any deferred deletes (from removes during edit) are processed: SW iterates the original-attachments-minus-current-attachments set and `deleteBlob`s each
+4. Failures are best-effort: a failed delete doesn't block the save; orphaned blobs are tolerable
+
+**Download (in detail view):**
+1. User clicks attachment row
+2. Popup sends `{type: 'download_attachment', itemId, attachmentId}` to SW
+3. SW reads the blob via `getBlob`, decrypts via `attachment_decrypt(sessionHandle, encryptedBytes)`
+4. SW returns the decrypted bytes (ArrayBuffer)
+5. Popup creates a Blob with the original `mime_type`, generates an object URL via `URL.createObjectURL`, triggers download via `chrome.downloads.download({url, filename})`, then revokes the URL after a brief delay
+
+**Image thumb rendering (in detail view):**
+- Same as download except step 5 sets the object URL as the `<img>` src instead of triggering a download
+- Object URLs are tracked in a per-disclosure registry and revoked on disclosure close / navigation
+
+### Caps enforcement (γ₁ enforces, γ₂ configures)
+
+Caps live in `VaultSettings.attachment_caps` (β₂ shipped the schema; the UI is γ₂). γ₁ reads the four caps and enforces:
+
+- `per_attachment_max_bytes`: rejected at popup before sending to SW (cheap; fails fast)
+- `per_item_max_count`: count of attachments on the item (not bytes); rejected at popup
+- `per_vault_soft_cap_bytes`: sum of plaintext sizes across all items (computed from manifest summaries); shows warning toast but allows upload
+- `per_vault_hard_cap_bytes`: same sum; hard reject at popup
+
+If any cap is `undefined`, no limit is enforced for that level. γ₂ will surface the configuration UI; in γ₁ users without explicit caps get unlimited attachments (modulo the implementation's practical limits — large blobs work via Git Data API, but uploading a 50 MB file will be slow).
+
+## Files affected
+
+### Rust core (likely no changes)
+
+The Rust core already has everything we need:
+- `attachment.rs`: `AttachmentRef`, `AttachmentSummary`, `EncryptedAttachment`, `encrypt_attachment`, `decrypt_attachment`
+- `item_types/document.rs`: `DocumentCore { filename, mime_type, primary_attachment }`
+- `manifest.rs`: per-entry `attachment_summaries: Vec<AttachmentSummary>`
+- WASM exports: `attachment_encrypt`, `attachment_decrypt`
+
+If a gap surfaces during implementation (e.g. missing helper), the plan will note it and add a small Rust task. But the design assumes the Rust surface is complete.
+
+### Service worker
+
+- `extension/src/service-worker/git-host.ts` — extend `GitHost` interface with `putBlob`, `getBlob`, `deleteBlob`. Export `BLOB_THRESHOLD_BYTES = 900 * 1024`.
+- `extension/src/service-worker/github.ts` — implement `putBlob` (with Git Data API fallback), `getBlob`, `deleteBlob`. Add 5 private helper methods for the Git Data API endpoints.
+- `extension/src/service-worker/gitea.ts` — same as github.ts. Endpoints have `/api/v1/` prefix; payload shapes are identical.
+- `extension/src/service-worker/router/popup-only.ts` — add 2 message handlers: `upload_attachment` and `download_attachment`. Both wired to existing `popup_only` sender check.
+- `extension/src/service-worker/vault.ts` — add helpers: `addAttachmentToItem(itemId, attachmentRef)`, `removeAttachmentsFromItem(itemId, idsToRemove)`. Both update item.json + manifest.json.
+
+### Popup
+
+- `extension/src/popup/components/attachments-disclosure.ts` — NEW. Renders the compact disclosure (header + rows + "+ attach file" button). Accepts the item draft, the form mode (`'add' | 'edit' | 'view'`), and an `onChange(attachments)` callback for edit mode. Manages object-URL lifecycle for image thumbs in view mode.
+- `extension/src/popup/components/types/document.ts` — NEW. Same shape as other type components (renderForm, renderDetail, save handler). Includes the primary-attachment picker and the signature-block detail rendering.
+- `extension/src/popup/components/item-form.ts` — wire up Document case in the dispatcher (currently routes to `renderComingSoon`).
+- `extension/src/popup/components/item-list.ts` — add the `📎` indicator span in the row template when `entry.attachment_summaries.length > 0`.
+- `extension/src/popup/components/types/{login,secure-note,identity,card,key,totp}.ts` — add `attachmentsDisclosure(...)` call after the custom-fields disclosure in each renderForm. ~3 lines per file.
+- `extension/src/popup/styles.css` — add rules for `.attachment-row`, `.attachment-row__thumb`, `.attachment-row__name`, `.attachment-row__meta`, `.attachment-row__action`; `.attachment-add-btn`; `.document-signature-block` (signature-block treatment).
+
+### Tests
+
+- `extension/src/service-worker/__tests__/git-host.test.ts` — NEW. Test putBlob threshold logic (with mocked fetch): small payload uses Contents API; payload >900KB uses Git Data API sequence (5-call mock). Verify failure paths bubble up.
+- `extension/src/popup/components/__tests__/attachments-disclosure.test.ts` — NEW. Test render in each mode, +attach triggers file picker, × removes from draft, ↓ triggers download message, image-mime rows lazy-load thumbs, object URLs revoked on close.
+- `extension/src/popup/components/types/__tests__/document.save.test.ts` — NEW. Test Document form save: missing primary_attachment shows validation error; valid save sends correct wire format.
+- `extension/src/service-worker/router/__tests__/router.test.ts` — extend with 2 cases: `upload_attachment` accepted from popup, rejected from content; same for `download_attachment`.
+
+Estimated test count growth: ~15 new tests (was 128 after gen-UX, target ~143).
+
+## Acceptance
+
+- [ ] Clicking "+ attach file" on any item form opens browser file picker.
+- [ ] Picking a file uploads it (encrypted) to the configured git host within ~1-3 seconds for typical files (<1 MB) or up to ~10s for large files (>5 MB).
+- [ ] The new attachment appears in the disclosure immediately after upload.
+- [ ] Saving the item persists the updated `attachments` array; reopening shows the attachment.
+- [ ] In view mode, clicking ↓ downloads the decrypted file to the user's downloads folder.
+- [ ] Image-mime attachments show a 16×16 thumb in the icon column (lazily decrypted on disclosure open).
+- [ ] Removing an attachment in edit mode + saving deletes the underlying blob from the git host.
+- [ ] Item-list rows show `📎` for items with at least one attachment.
+- [ ] Document item type's "+ New" entry is no longer "coming soon" — opens the Document form.
+- [ ] Document form rejects save when `primary_attachment` is empty (gold required-field treatment).
+- [ ] Document detail view renders the gold signature block with thumb + filename + meta + actions.
+- [ ] Documents with image primary_attachment offer a `🔍 preview` toggle; clicking expands an inline preview pane within the signature block.
+- [ ] putBlob with content >900 KB uses the Git Data API fallback (verified via test with mocked fetch + via manual upload of a >1 MB file to a real test repo).
+- [ ] putBlob with content ≤900 KB uses the existing Contents API path (no Git Data API calls).
+- [ ] `bun run test` passes (existing 128 + ~15 new = ~143 tests).
+- [ ] `bun run build:all` clean for both Chrome and Firefox.
+- [ ] `cargo test --workspace` passes (155).
+- [ ] `bunx tsc --noEmit` clean.
+- [ ] Manual smoke: walk through Login form add+remove attachment, Document form create+view, attachment > 1 MB triggers Git Data API path, item-list shows 📎 indicator.
+
+## Out of scope (deferred to γ₂ or later)
+
+- Trash view + restore/purge actions (γ₂)
+- Field history view per item (γ₂)
+- Device add/list/revoke UI (γ₂)
+- Attachment caps configuration UI (γ₂; γ₁ reads them but doesn't edit them)
+- Drag-drop file affordance
+- Multi-file picker
+- Attachment count badge on item-list rows
+- Inline image preview pane in the standard attachments disclosure (only Document's primary attachment gets the preview-on-toggle)
+- Orphan-blob garbage collection (γ₂'s caps UI may include a "purge orphans" action)
+- Streaming/chunked uploads for very large files (>50 MB) — current design holds full plaintext + ciphertext in memory simultaneously; fine for typical use
+- Resumable uploads after network failure — γ₁ retry is "user clicks again"
+
+## Open questions deferred to plan
+
+- **Document primary_attachment "change" UX:** clicking the `↑ change` button in edit mode replaces the primary. Does it (a) immediately delete the old blob, or (b) defer the delete until form save (matching standard attachment-removal lifecycle)? Plan ships (b) — consistent with the rest, lower risk if user "changes their mind" mid-edit.
+- **Image preview thumbnail size:** 16×16 may render images as illegible blurs for portrait-orientation files. Plan ships 16×16 with `object-fit: cover` (centered crop); if user feedback wants 24×24 we adjust. The signature-block thumbs (48×60) use `object-fit: contain` to show the full image silhouette.
+- **Per-vault size sum computation:** computing `sum(attachment.size)` across all manifest summaries on every upload is O(n_items × n_attachments_per_item). For vaults with >1000 items this could be ~10-100 ms. Plan: compute once at unlock, cache in popup state, increment on add / decrement on remove. Re-compute fresh from manifest on sync.
+- **Filename collisions:** two attachments with the same filename on the same item — render both rows with the same name? Plan: yes; the underlying ID disambiguates them; the user sees two `screenshot.png` rows and can ✕ either one. Future polish: append `(2)` suffix to display name.
+- **Download filename sanitization:** user-supplied filename goes directly to `chrome.downloads.download({filename})`. Chrome strips path separators automatically; Firefox does the same. Plan: trust the browser sanitization; no extra escaping in popup.
+- **Error toast UX:** `humanizeError()` already exists in popup-side error handling per α design (spec referenced this). Plan: reuse `humanizeError(resp.error)` for upload/download failures.