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

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.