Move docs/architecture/overview.md to ARCHITECTURE.md at the repo root —
it is the primary cross-codebase architecture doc (four-codebase diagram,
inter-codebase contracts, secrets map, build matrix, test strategy, where-to-look
table) and belongs at the root alongside STATUS.md, ROADMAP.md, etc.
Update relative paths inside the file (../../crates/ → crates/, etc.).
Update CHANGELOG.md's one active reference to the old path.
Add a "Living docs — update discipline" table to CLAUDE.md that maps every
ALLCAPS.md file to the area it covers and the trigger for updating it. This
closes the loop on the ALLCAPS.md documentation system.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Each Dev A/B/C kickoff now declares the project's `.claude/settings.json`
auto-allow surface (write/cargo/npm/bun/python3/commit/push/PR), enumerates
the hard deny-list guardrails (no rm, no force-push, no reset --hard, no
branch -D, no worktree remove, no clean -f*, no checkout -- *, no sudo,
no chmod 777, no DB drops), and bakes in the simplify discipline required
before every REVIEW-READY: invoke superpowers:simplify on changed code,
no parallel implementations of existing helpers, no defensive checks for
impossible scenarios, no comments unless the WHY is non-obvious, no
half-finished implementations.
Why now: cycle-1 Stream B reached final-validation in roughly an hour
and a half. The bottleneck for cycle-2 is review/iteration cadence, not
typing speed — pushing devs to move at full auto-allow speed while
forcing a simplify pass shifts the cost from "PM rework after merge"
to "dev catches duplication before REVIEW-READY".
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Partitions Plan B's remaining phases (3-8) across three cycle-2 streams
once cycle-1 Stream A and Stream B's bundled Phase 1+2 PR have merged.
Stream A picks up Phase 3 (prompt_or_flag + builder compression),
Stream B owns Phases 4/5/6 (after_manifest_change, ParamsFile, batched
purge), Stream C owns Phases 7/8 (parser migration to relicario-core +
WASM exports). Plan C (extension restructure) is not in cycle 2.
Each kickoff bakes in cycle-1 lessons: prefer single-line relay body
content, avoid the f-string footgun in Python inbox-monitor scripts,
narration discipline (IN-PROGRESS updates at meaningful in-flight
moments, not just phase boundaries). The PM prompt also captures
cycle-1 outcomes (commits/PRs landed, the 17 pre-existing extension
test failures pattern, DEV-B's option-(b) git_run choice) so the new
PM picks up cold without relay history.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Generated by /multi-agent-kickoff for the three architecture-review
followup plans. PM coordinates; Dev-A owns Plan A (security & docs polish,
S, ships first); Dev-B owns Plan B (CLI restructure, M-L); Dev-C owns
Plan C (extension restructure, L).
Each dev prompt forces cd into its worktree (per project memory rule),
includes the relay tool calls + Python shim fallback, scopes hard-rules
to the planning subagents' flagged judgment calls, and ships an opinionated
PR title + body template that mirrors the plan's Done criteria.
PM prompt enforces the cross-plan boundaries: A is independent; B Phase 8
WASM exports are a seam C does not consume in this train; A owns the
.free() swallow removal and Drop impl; if both B and C touch wasm.d.ts,
B sequences first.
Launcher discovers these via `ls -t coordination/*-<role>-prompt.md | head -1`
so they take precedence over previous kickoff sets.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
TL;DR-first guide to the PM/Senior-Dev paradigm: how to invoke
/multi-agent-kickoff, how the launcher's three modes (manual/tmux/kitty)
work, the in-memory queue + per-role inbox semantics, the call.py /
call.ts fallback shims, message kinds, conventions, and troubleshooting.
Lives next to the kickoff prompts in docs/superpowers/coordination/ so
the workflow's docs and outputs share one home.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Plan A (security & docs polish, S): SessionHandle impl Drop + JS .free()
audit + recovery_qr.rs documentation + relay launcher dev-c expansion.
Independent of B/C; ships first.
Plan B (CLI restructure, M-L): split cli/main.rs (2641 LOC) into commands/
folder + prompt.rs + parse.rs; helpers::git_run captures stderr; Vault::
after_manifest_change centralizes the groups-cache discipline; canonical
ParamsFile; batched purge; migrate parse_month_year/base32_decode_lenient/
guess_mime to relicario-core with WASM re-exports.
Plan C (extension restructure, L): typed StateHost (precondition); extract
service-worker/storage.ts; setup.ts SW migration via create_vault/
attach_vault messages + step-registry pattern; vault.ts split into
shell/sidebar/list/drawer/form-wrapper with vault_locked channel
unified through shared/state.ts; P2 cluster (timer reset, gitHost clear,
teardown helper, allSettled, MutationObserver debounce); get_vault_status
closes the relicario status parity gap.
Cross-boundary cites verified: Plan B Phase 8 WASM exports are the seam
Plan C consumes (deferred to a future plan); Plan A owns the .free() swallow
removal that Plan C respects without redoing.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Adds the four kickoff prompts that drove the 2026-05-04 whole-codebase
architecture audit (PM + DEV-A/B/C reviewers), the planning prompt
that converts the synthesis into three implementation plans, and the
PM + DEV-A/B/C kickoff prompts for executing those plans in parallel.
Also updates the existing v0.5.1-* prompts with the relay-server
fallback section that references the new tools/relay/call.py shim.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Three-reviewer architecture audit (DEV-A: core, DEV-B: cli/server/wasm,
DEV-C: extension/relay) plus PM synthesis. Lens: make the codebase
readable for a smart developer who doesn't know Rust but wants to learn
by tinkering.
Top synthesis findings (P1):
- SessionHandle has no impl Drop; .free() is a cleanup no-op (cross-cutting Rust+JS)
- cli/main.rs is a 2641-line monolith with no submodule boundaries
- setup.ts (1220 LOC) bypasses the SW and orchestrates WASM directly
- vault.ts (1027 LOC) owns shell + sidebar + list + drawer + routing
- shared/state.ts is fully any-typed
- recovery_qr.rs is undocumented vs. rest of crypto-adjacent core
- duplicated SW router helpers (storage + itemToManifestEntry)
- pure parsers (parse_month_year, base32_decode_lenient) belong in core
- 16x duplicated git invocation boilerplate with one-line errors
CLI/extension parity: 22/23 capabilities ✓; only true gap is `relicario
status` (no get_vault_status); `detach` is partial via update_item.
Also fixes tools/relay/queue.test.ts:54 to match the dev-c role
expansion already in queue.ts (was failing 1/4; now 5/5 pass).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
v0.5.0 Plan A — Security Fixes + Repo Cleanup. 7 commits, ~800 net
insertions across the Rust workspace. Four items delivered:
- S1 (HIGH-severity authentication bypass fix): rewrite verify_commit
in relicario-server. The previous implementation accepted any
GOODSIG/Good signature line on stderr, ignoring whether the signing
key was registered or revoked. The new implementation:
* builds a temp gpg.ssh.allowedSignersFile from devices.json at the
commit (no global git-config mutation)
* parses the SHA-256 fingerprint from `git verify-commit --raw`
stderr via regex
* checks revocation FIRST (revoked entries may have been removed
from devices.json), with the historical-commit case
(committer_ts < revoked_at) explicitly allowed
* uses committer date (GIT_COMMITTER_DATE / `git show -s
--format=%ct`), not author date or wall clock
* tightened the bootstrap guard to require BOTH devices and revoked
to be empty (closes an empty-devices.json privilege-escalation
route present in the original code)
* 4 acceptance integration tests build real on-disk repos with
SSH-signed commits and verify each scenario
- S2 (tar archive path-traversal hardening): replace
tar::Archive::unpack with safe_unpack_git_archive. Located in
relicario-core (per-spec, so integration tests can reach it without
the bytes-in/bytes-out invariant breaking). Validates each entry's
type (rejects symlinks/hardlinks), path components (rejects '..',
RootDir, Windows drive Prefix), and declared size (rejects
individual or cumulative > 100×compressed-or-1-GiB whichever is
lower). The CLI's restore path adds a paranoid OS-level
starts_with(.git/) check on the joined destination as
defense-in-depth even after textual validation. 5 acceptance tests
cover path traversal, symlinks, oversized headers (header claim of
2 GiB tested without allocating disk).
- S3 (RELICARIO_* env-var audit): docs/SECURITY.md gains a
"Configuration env vars" section enumerating each variable, its
purpose, and trust assumption. Active-in-all-builds variables
(RELICARIO_IMAGE, RELICARIO_GITEA_*) are documented; debug-only
variables (RELICARIO_NO_GROUPS_CACHE, RELICARIO_TEST_*) are gated
behind cfg(debug_assertions) so the env-var lookup is removed from
--release binaries.
- C1 (stale feature branch prune): 5 merged feature branches and
3 worktrees pruned interactively per dev report.
- Bonus: 4d02a50 fixes pre-existing clippy warnings across
crates/relicario-{core,cli} (deref operators, Option::is_none_or
vs map_or(true, ...), iter_mut().enumerate() patterns,
div_ceil()) so the workspace builds clean under `-D warnings`.
Merge resolution: docs/SECURITY.md had a conflict where main's F11/F12
(Device Authentication paragraph naming relicario-server + simplified
"Device registration is optional" line) collided with Plan A's S3
section. Resolved by keeping both — F11/F12's wording for the
Device Authentication section, then Plan A's "Configuration env vars"
section appended below.
Cargo.lock regenerated. The previous committed lock was stale since
commit 8855078 (--totp-qr); cargo test on both devs' worktrees
produced identical regenerated locks. Plan A genuinely added regex +
tempfile to relicario-server (both already transitively present from
relicario-cli), so no new top-level deps; the Cargo.lock churn is
catch-up of crate-version bumps that have happened since the last
commit-of-record.
Tests: 248 cargo tests pass; extension tests unchanged (336/8 with 8
pre-existing device-auth scaffolding failures).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Adds a "Configuration env vars" section listing every RELICARIO_*
variable read by production code, with purpose and trust boundary.
Splits user-facing vars from debug-only ones (cfg(debug_assertions))
to make the attack surface explicit for security reviewers.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Updates each Status: line from "Proposed; needs user decision" to
the actual fix-commit SHA. The audit doc now records the full state:
6 trivial findings fixed in the initial 900ccf1 pass; 8 deeper
findings fixed across ca059e7, 8fd9a05, 1342228, 76d092d, 9c97f9f
during v0.5.0 PM kickoff.
Pre-tag checklist: doc-audit follow-ups item is now done.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The 2026-04-11 design spec lists secure notes, secure documents, TOTP,
Firefox extension, LastPass import, and device authentication as
"Post-V1 Ideas" — most of which shipped over the following weeks.
Per the doc/architecture/overview.md convention, specs are frozen
decision artifacts and shouldn't be retro-edited; instead, add a
one-line status banner pointing readers at CHANGELOG.md and the
overview doc for current state.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The Vault Creation Flow ASCII showed only manifest.enc as init's
encrypted artifact; cmd_init has been writing settings.enc in parallel
since the VaultSettings rollout. Update the encrypt step to show both
artifacts side-by-side with independent nonces.
Below the ASCII, add a short pointer noting that the per-item lifecycle
(typed-item envelope, attachment encryption, field-history) lives in
crates/relicario-core/ARCHITECTURE.md and reuses the same master_key +
XChaCha20-Poly1305 primitives. The doc-audit framing is "this top-level
doc could just point at the per-crate docs" — taking that trim path.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- F12: Device Authentication section now names the relicario-server crate
and its two subcommands (generate-hook, verify-commit), and notes that
signed commits without the server-side hook provide authorship only —
any pusher can still land an unsigned commit.
- F11: drop the "optional before v0.4.0" version line (v0.4.0 was never
tagged; v0.5.0 is the first release with the hook) and replace with a
one-liner: registration is optional but recommended for shared vaults.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Doc-audit Finding 1. The repo has had four Rust crates since early May
when the pre-receive hook crate landed, but docs/architecture/overview.md
still framed itself around three. Update:
- "The three codebases" → "The four codebases" (intro + heading)
- ASCII diagram fans core out to cli + server + wasm, with wasm feeding
the extension
- Table gains a relicario-server row noting it lives on the git server
and only sees public key material
- Build matrix adds `cargo build -p relicario-server --release`
- "Where to look next" points at server src + the device-auth design spec
Server has no user-facing surface, so the CLI/extension parity rule is
clarified to exclude it (it is server-side enforcement of an invariant
the clients already agreed to).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Three-terminal coordination paradigm: a PM session reviews and
integrates while two senior-dev sessions work parallel feature
branches in their own worktrees, dispatching subagents per
task. Prompts encode roles, boundaries, status/directive/question
block formats for user-relayed cross-terminal coordination, and
pre-tag checklists.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Anchors on a HIGH-severity auth bypass in the relicario-server
pre-receive hook (revocation + registered-device checks both
unimplemented), bundles two hardening follow-ups, two confirmed
bugs, and four UX improvements. Splits into Plan A (Rust + docs)
and Plan B (extension UX) for independent merge cadence.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
13-task plan to land patina palette, polish vocabulary (.surface-backdrop,
.glass, .btn-primary/secondary, ▸ arrow glyph), restructured login popup,
setup wizard polish, two-column login form, sticky save bar, and dirty-
state header subtitle.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Bundles patina palette shift, logo update (translucent gradient gem),
glass-card vocabulary across login/setup/fullscreen, and the original
two-column form layout. Updates relicario-logo.svg and -16.svg to the
patina palette.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Two-column CSS Grid for login forms, sticky save bar, and dirty-state
header subtitle. Other item types stay single-column with the polish
applied. Stacks to single column at <=720px viewport.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Clarifies what AEAD protects (tampering) vs. what it doesn't (deletion,
rollback). Documents that git history is the audit trail and device
authentication is the mitigation.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Brand name uses capital R in user-facing text — extension UI strings,
CLI clap help / descriptions / error prose, markdown docs. Lowercase
preserved for the binary command, crate names, npm package, file
paths, env vars, and code identifiers.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
18 tasks across 8 phases covering all 8 form-level smart-input
affordances from spec section C (popup + fullscreen share login.ts) plus
CLI parity (rate, --totp-qr, completions + groups.cache). Cross-plan
coordination notes flag overlap with Phases 2B (recovery-QR) and 2C
(password coloring) — no conflicts, only shared APIs (rate_passphrase,
strength widget).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Two implementation plans, one per spec landed in 00da7e7. Each plan
decomposes its spec into bite-sized TDD tasks with exact file paths,
complete code, and per-task commits.
- recovery-qr-and-entropy-floor.md (15 tasks, 6 phases): core crypto
module + wasm bindings + CLI subcommands (imgsecret embed, recovery-qr
generate/unlock, --force-weak-passphrase) + extension popup window
with canvas QR + vault-tab button + unlock-flow recovery link +
zxcvbn>=3 hard gate at init (CLI + setup wizard) + soft warning at
unlock for grandfathered weak vaults.
- password-coloring.md (9 tasks, 6 phases): pure colorizePassword()
utility + chrome.storage.sync round-trip + applyColorScheme() boot
step + four reveal-surface integrations (field history, popup item
detail, fullscreen item detail, generator preview) + settings UI
with color pickers and live-preview swatch. Task 6 (fullscreen)
flagged for coordination with in-flight Phase 1 UX work.
Both plans follow the subagent-driven execution preference per
feedback_subagent_default.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Two design specs landed together because they're driven by the same
brainstorm session and target the same release window:
- 2026-05-01-recovery-qr-design.md: 1-of-2 disaster recovery via a
paper-or-photo QR carrying image_secret encrypted under Argon2id-of-
passphrase. Display-first UX (snap with phone), print as secondary.
Memory-only — architecturally no API path produces a file. Includes
domain-separation tag, type-level KDF params floor, shared NFC
normalization helper, and a passphrase entropy floor (zxcvbn >= 3)
enforced at vault init.
- 2026-05-01-password-coloring-design.md: 1Password-style character-
class coloring on revealed passwords (digits/symbols/letters with
user-customizable colors via chrome.storage.sync). Single shared
colorizePassword() helper, default scheme blue/red/inherit.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Code-review feedback on Task 1: the _HTML suffix makes the 'this is raw
HTML, do not escape' contract obvious at every call site. Cheap to do
now (zero consumers); would be 8 diffs once Tasks 4-6 wire the constant
into the type forms.
Plan updated in lockstep so Task 4 references the new name.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Eight bite-sized tasks for the visual baseline: shared/glyphs.ts module,
color-token & focus-ring CSS in popup and vault, .req-pill class, migration
of all ten required-marker sites and ten emoji glyph sites to the shared
constants, gating of the popout-to-tab button on !isInTab(), and a static
"esc to cancel" subtitle in fullscreen forms.
Each task pairs a failing test with a minimal implementation; ends with a
commit. Sets the visual language that phases 2-4 build on.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Captures the brainstorm output for the fullscreen vault tab: two-column login
form with sticky save bar, monospace-coherent glyph buttons, eight smart-input
affordances (fill-from-tab, hostname chip, group autocomplete, password reveal
& strength, TOTP live preview, TOTP-from-QR, notes monospace), and seven
power-user features (three-pane shell, keyboard nav, ⌘K palette, unsaved guard,
multi-select bulk ops, drag-drop attach, recent items).
Includes a CLI-parity section pairing each extension capability with its CLI
counterpart so the surfaces ship together.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The repo uses bun (bun.lock present, no pnpm/npm available).
Replaces all pnpm references in the plan with bun equivalents.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Plan 3A: backup & restore — drives the feature branch landing in
the next commit (merge of feature/backup-restore).
Pre-v0.3.0 audit checklist: manual smoke-test list for the v0.2.x
audit-pass commits (TOTP edit, history, detach, status, generator
defaults, vault-tab parity, sync button) — to walk through before
the v0.3.0 tag.
Strategic-depth architecture documentation, the kind that's hard to
recover by reading code: invariants, multi-file flows, design rationale,
gotchas. Goal is to cut the token cost for future Claude sessions.
Four new docs (2091 lines total):
- crates/relicario-core/ARCHITECTURE.md (514 lines) — bytes-in/bytes-out
boundary, 24 verified invariants (VERSION_BYTE=0x02, length-prefixed
KDF input, NFC normalization, content-addressed AttachmentId, history-
tracked field kinds, 60% imgsecret confidence floor, MAX_DIMENSION=
10000, etc.), 7 multi-module flows, 16 non-obvious gotchas (QUANT_STEP=
50, central-70%-embed, BIP39-128bit-then-truncate, Steam alphabet
rationale).
- crates/relicario-cli/ARCHITECTURE.md (539 lines) — module map for the
three source files; the cmd_add/cmd_edit per-type helper pattern (post-
2026-04-27 refactor); the hardened-git invariant (Command::new("git")
is gated to helpers.rs:46); the five history synthetic keys; the env-
var escape-hatch policy; cmd_generate's two-mode design (no-unlock
outside vault, unlock-and-read-defaults inside).
- extension/ARCHITECTURE.md (831 lines) — five-bundle structure (popup,
vault, setup, content, service-worker); SW-as-crypto-fortress model;
capability-set-or-silent-rejection contract; vault-tab-as-popup-class
router parity (commit a7dbf35); origin TOFU flow; setup state machine;
test-vs-build gap.
- docs/architecture/overview.md (207 lines) — cross-codebase entry point.
How the three codebases fit together, the four versioned wire formats
between them (core→WASM ABI, SW chrome.runtime protocol, vault on-disk
layout, GitHost API), per-codebase secret residency table, build
matrix, conventions that span all three.
Specs in docs/superpowers/specs/ remain as historical decision artifacts
("why we chose this") — the new arch docs are the source of truth for
"what is" current invariants and flows.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Brainstormed scope: backup/restore round-trippable to relicario, plus a
LastPass CSV importer. Migration out is explicitly out of scope. CLI and
fullscreen vault tab get parity; popup is untouched.
Backup format `.relbak` v1: magic header + version + Argon2id salt +
XChaCha20-Poly1305 nonce + AEAD-encrypted, zstd-compressed JSON envelope
with base64'd binary blobs. KDF params are tied to backup format
version, not the live vault's params.json.
Reference image inclusion is opt-in; .git history is opt-out. Backup
passphrase is independent of the vault passphrase. Restore refuses if
the target dir already has a vault.
Includes architecture, data flow, error handling, testing strategy,
LastPass field-mapping table, risks, and effort estimate (~5.5 dev-days
for full CLI + extension parity).
Implementation plan and code to follow.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Setup wizard currently overwrites existing vaults silently. Adds a
mode picker (create new / attach this device), a vault-presence probe
after the connection test, and a Step 3b that verifies passphrase +
reference image by decrypting the manifest before registering a new
device key. Refuses destructive overwrite from the GUI; users wanting
a clean slate must delete the repo via their host's web UI.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
