Codebase review: polish, distribution, and agent-UX improvements

[Kinfe123]

A full-codebase review (CLI surface, core/storage internals, docs, website, CI/release pipeline) surfaced a set of improvements. The engineering core is in great shape — fail-closed lifecycle, journaled recovery, actively probed backends, real-filesystem CI. The gaps below are mostly polish, distribution, and the agent-facing story, plus a few small documentation correctness bugs.

1. Correctness fixes (small, high trust impact)

• License contradiction (already fixed on main) — README.md ("Licensing" section) says Apache-2.0, but LICENSE, Cargo.toml, and package.json all declare MIT.
• SUPPORT.md is stale (already fixed on main) — still says Linux and Windows mutation backends are not implemented, contradicting the shipped Milestone 5/7 slices and the README compatibility table.
• SECURITY.md is stale (already fixed on main) — still describes macOS/APFS-only mutations and says "until the first tagged release, only main receives security fixes" (v0.1.0–v0.2.1 have shipped).
• Stale hardcoded commit SHA (already fixed on main) in website/src/app/page.tsx — the "Windows & manual install" link pins a pre-merge blob URL.
• website/README.md overclaims content (merged: docs: describe the sections the website actually has #140) — describes sections (transparent Git usage, safety, lifecycle, compatibility) that don't exist on the page.
• Dead riftri recover command (merged: chore: remove redundant recover subcommand #139) — byte-for-byte equivalent to riftri repair --state-dir <PATH>, never referenced by any doc or test; hide or remove.
• Dependabot coverage (already fixed on main) — .github/dependabot.yml watches only cargo and github-actions; the root npm package and website/ (pnpm, Farm.js beta, React 19) are unmonitored.
• Debug formatting leaks into user output (already fixed on main) — backend kind/status printed with {:?} in two places in crates/riftri-cli/src/main.rs instead of display_name().

2. Agent-first UX (the differentiator)

• --json on success paths (merged: feat: emit stable JSON reports from lifecycle commands #141) — only doctor and backends have --json today. status, gc, repair, and all worktree subcommands are human-text only, so harnesses need a JSON parser for failures (--json-errors receipts) but text scraping for success. Blocked only on deriving Serialize for StorageAccountingReport, GarbageCollectionReport, RecoveryReport, and AddWorktreeResult in riftri-core.
• riftri worktree list (already implemented on main, including --json) — there is no inventory command; the closest is reading the storage block of riftri status.
• Agent-integration guide (merged: docs: add agent-harness integration guide #142, index link fix fix: link the agent integration guide from the site overview #143) — coding agents are the stated audience, but guidance is a few scattered sentences. A doc covering per-harness setup (Claude Code, Codex, Cursor, devcontainers), a "ten parallel agents" walkthrough, and the --json-errors receipt contract would close the loop.
• worktree add for an existing branch (already implemented on main) — only -b <new-branch> and --detach are supported; git worktree add <path> <existing-branch> has no optimized equivalent.

3. Distribution

• Homebrew formula/tap — formula done (merged: feat: add a generated Homebrew formula #161 — generated from a release's SHA256SUMS, with a drift guard test; brew install --formula ./Formula/riftri.rb). Still needs a tap repository (conventionally assistant-ui/homebrew-riftri) before brew install riftri works by name, and a token secret if the release workflow should push to it.
• winget and/or Scoop manifests for the Windows builds.
• Nix flake / AUR — musl and glibc builds for both arches already exist.
• Consider crates.io publication (cargo install riftri) — all crates are currently publish = false by design; worth revisiting at least for the CLI.
• Consider a Docker/OCI image given the OverlayFS + agent-sandbox use case.

4. Supply chain & CI

• Sign/attest GitHub release tarballs (merged: ci: attest build provenance for GitHub release assets #149) — npm gets OIDC provenance, but the tarballs the curl | bash installer downloads are unsigned and SHA256SUMS is unsigned (integrity, not authenticity). actions/attest-build-provenance or cosign would close this.
• cargo-audit / cargo-deny in CI (merged: ci: audit dependencies, verify MSRV, and lock CI builds #145) — notable omission for a tool that deletes directories and installs a root-owned mount helper.
• MSRV job (merged: ci: audit dependencies, verify MSRV, and lock CI builds #145) — rust-version = "1.85" is declared but never verified in CI.
• Code coverage (merged: ci: measure code coverage with cargo-llvm-cov #156 — cargo-llvm-cov job, PR summary + lcov artifact; the Codecov upload step is a no-op until a CODECOV_TOKEN secret is added).
• --locked in the main quality job (merged: ci: audit dependencies, verify MSRV, and lock CI builds #145) — lockfile drift currently isn't caught until release.
• Automate website deployment — still manual (vercel deploy; needs Vercel secrets). The verification half is done (merged: ci: verify the deployed installers match the repo #157 — a weekly and on-change workflow diffs the deployed install.sh/install.ps1 against the package/ copies). Note: the canonical host is riftri.dev, not riftri.vercel.app.
• macOS codesigning/notarization and Windows Authenticode (currently punted in docs/install.md).
• Link checker for docs/README cross-links (merged: ci: check Markdown links with lychee #150 — lychee over all Markdown, weekly sweep of main) — would have caught the stale website SHA.

5. CLI polish

• Shell completions (clap_complete) (merged: feat: generate shell completion scripts #144) and man pages (clap_mangen) (merged: feat: generate troff man pages #153, riftri man <dir>) — both generated on demand instead of shipped in archives, preserving the single-executable release-archive invariant the installers verify.
• Progress output — lifecycle phase progress and --no-progress are implemented; machine-readable error receipts suppress progress automatically. Covered by progress_reporting.rs.
• Human-readable byte sizes in status output (merged: feat: render byte counts with binary units and add --branch #146).
• Consistent repository argument — repository-taking commands accept --repository, covered by repository_option.rs. backends intentionally takes a destination path instead.
• Confirmation prompts or --yes for gc --apply and worktree remove --force (merged: feat(cli): add confirmations, distinct exit codes, and help examples #158 — prompts only when stdin and stderr are both terminals, so agents and CI are unaffected).
• --branch long form for -b (merged: feat: render byte counts with binary units and add --branch #146); help-text examples (after_help) and RIFTRI_* env vars in --help (merged: feat(cli): add confirmations, distinct exit codes, and help examples #158 — documents the two variables users actually set; the rest are internal OverlayFS plumbing and test hooks). Still open: a config file.
• Distinct exit codes for policy vs operational failures (merged: feat(cli): add confirmations, distinct exit codes, and help examples #158 — 1 operational, 2 usage, 3 policy, mirroring the receipt category).

6. Docs & website

• Comparison page — vs plain git worktree, git clone --reference, cp --reflink, container-per-agent setups. Nothing like it exists and it's the first question new users ask.
• CLI reference doc (merged: docs: add a CLI reference #151 — docs/cli.md, all 19 subcommands plus the shared --json/--json-errors conventions).
• docs/README.md index (merged: docs: add a comparison page and a documentation index #147; docs: point the AGENTS.md map at the documentation index #155 points the AGENTS.md map at it).
• Website SEO/social metadata (merged: feat(website): add SEO metadata, crawler files, and a 404 page #160 — OG/twitter/canonical metadata, robots.txt, sitemap.xml, and a prerendered 404 page; the finalizer now asserts all three files exist).
• Troubleshooting/FAQ page (merged: docs: add a troubleshooting and FAQ guide #152 — docs/troubleshooting.md, symptom-first).
• A "how riftri stays safe" page (merged: docs: explain how riftri stays safe #159 — docs/safety.md: fail-closed refusals, real-filesystem CI, benchmark honesty, and supply-chain measures, each traceable to code or CI config).

7. Roadmap features with most user impact (already tracked in ROADMAP.md, listed for completeness)

• Sparse-checkout profiles and submodule support (the two blockers most likely to hit real large repos).
• OverlayFS compaction (upper-layer reset) and non-ASCII case folding/normalization.
• Ordinary-NTFS story on Windows (differencing VHDX / ProjFS evaluation).

---

Found via a full review of the CLI (crates/riftri-cli), core/storage/git crates, docs, website, and CI/release workflows at v0.2.1 (39e50e4).

[Kinfe123]

Section 1 status: six of the eight items were independently addressed on main since this issue was filed (README license, SUPPORT.md, SECURITY.md, the stale website commit link, Dependabot npm coverage, and the debug-formatted backend output — which now uses display_name() for both kind and status). The two remaining items have PRs: #139 removes the redundant recover subcommand, and #140 aligns the website README with the page's actual sections. Checkboxes above updated accordingly.

[Kinfe123]

Section 2 status: worktree list (with --json) and existing-branch worktree add were already implemented on main. The remaining two items now have PRs: #141 adds --json success reports to status/repair/gc and all mutating worktree subcommands, and #142 adds the agent-integration guide (merge #141 first — the guide documents its output contract). Checkboxes updated.

[Kinfe123]

Section 4/5 progress: #144 adds riftri completions <shell> (bash/zsh/fish/elvish/powershell), #145 adds the cargo-deny supply-chain job + MSRV job + --locked CI builds, and #146 adds binary-unit byte rendering and the --branch long flag.

Notable: the MSRV job caught a real defect on its very first run — the workspace declares rust-version = "1.85" but uses let-chains (stabilized in Rust 1.88), so it never actually compiled on the declared minimum. #145 now declares and verifies 1.88. Exactly the silent-MSRV-drift failure mode this issue predicted.