# Documentation Audit — 2026-05-02 Pre-v0.5.0 audit of Relicario's documentation against the current codebase. ## Summary - **Total findings:** 14 - **Fixed inline:** 6 - **Need user input (proposed only):** 8 - **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:** Proposed; needs user decision (>50 words of new prose; touches the framing of the whole overview doc) --- ### 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:** Proposed; needs user decision (CLAUDE.md is user-controlled per audit constraints) --- ### 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:** Proposed; needs user decision (CLAUDE.md is user-controlled; phrasing is a judgment call) --- ### 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:** Proposed; needs user decision (CLAUDE.md is user-controlled) --- ### 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/.enc` + `attachments//.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//.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/.enc` + `.relicario/{salt,params.json,devices.json}`. Missing: `settings.enc`, `attachments//.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:** Proposed; needs user decision (>50 words of new prose, design choice between rewriting vs trimming) --- ### 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:** Proposed; needs user decision (security wording — exact phrasing matters) --- ### 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 `), or how to install it (`relicario-server generate-hook`). For a self-hosted user reading this to decide whether to enable it, those are the two essential operational facts. **Fix:** Add a short paragraph naming the crate and the two subcommands, pointing to the design spec. **Severity:** nice-to-have **Status:** Proposed; needs user decision (>50 words of new prose) --- ### 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:** Proposed; needs user decision (touches a historical spec the user may want to leave frozen) --- ### 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 Files modified during this audit: - `README.md` — vault layout (`items/`, `settings.enc`, `attachments/`), crate tree (added `relicario-wasm`, `relicario-server`, typed-items modules), ID width, Roadmap. - `docs/ARCHITECTURE.md` — git-server box (`items/`, `settings.enc`, `attachments/`, `revoked.json`), crate-architecture inner box (current core modules), removed "Future: relicario-wasm" line. - `docs/architecture/overview.md` — conventions table (16-char hex IDs, 128-bit AttachmentIds). No source files, `Cargo.lock`, or extension code were modified. CLAUDE.md, SECURITY.md, and the foundational design spec were not modified — those changes need user review per the audit constraints.