docs: add developer guide and cross-version contract headers - #48
Conversation
…nd doc map
README gains a Developing section (toolchain floors, sidecar fetch, dev
loops, the full gate list vs the pre-commit subset, a house-rules digest,
and doc-map pointers). CLAUDE.md gains the comment-shorthand legend
(V*-P* build phases, I## ledger entries, IMPROVEMENTS item IDs by
section letter, PR-## review findings) and lists IMPROVEMENTS.md in the
doc map. IMPROVEMENTS.md is marked retired: a code-level audit verified
55 of its 56 items shipped (P1 partial), with the judgment calls
recorded so the item text can't be mistaken for open work.
Module docstrings added where the survey found high-risk gaps:
- TS: crypto/identity.ts (derivation contract, noble sha512 side
effect, NaCl box compat), crypto/topics.ts (rendezvous wire
contracts), trystero/index.ts (fan-out wrapper, merged-room scope),
db/{identity,sessions,friends}.ts (camelCase-in/snake_case-out
convention), the five bare stores, Home.tsx mount invariants,
add-friend dialog pair, Tauri-coupled settings categories, system
listeners, onboarding store.
- Rust: //! headers on every module (lib.rs spine ordering/teardown
rules, sidecar lifecycle invariants, forward-only migration rules,
DB corruption policy, keychain custody model, model-download guards)
plus /// on load-bearing items; ai_dialog.rs's banner converted to
rustdoc.
- scripts/check-tokens.ts gets the file header its siblings already had.
No behavior changes; comments and markdown only.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0171qBAM76TzzpJptZuiua1o
|
Warning Review limit reached
Next review available in: 42 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
📝 WalkthroughWalkthroughThe PR expands repository and development documentation, records frontend and Rust runtime contracts in comments, and adds identity settings plus Tauri autostart bridge functionality. It does not alter existing Rust runtime logic. ChangesDocumentation and settings
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
src/lib/db/sessions.ts (1)
1-6: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueClarify the Tauri arg naming note
sessions_insertuses Tauri’s default camelCase JS invoke keys, while the Rust command and returned rows stay snake_case. Reword the comment to say that directly.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/lib/db/sessions.ts` around lines 1 - 6, Update the module comment above the session types to explicitly state that sessions_insert receives default camelCase keys from JS invoke, while the Rust command parameters and returned session rows remain snake_case; preserve the distinction between SessionRow and SessionRecord.Source: MCP tools
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src-tauri/src/commands/ai_dialog.rs`:
- Around line 24-28: Update the documentation for the dialog toggle function to
remove the incorrect claim that lib.rs close-request interception can veto
closing ai-dialog; explain the actual lifecycle reason for using destroy(), or
omit that rationale if none is required. Keep the toggle behavior unchanged.
In `@src-tauri/src/commands/identity.rs`:
- Around line 4-10: The module documentation incorrectly claims keys are handed
to Rust exactly once. Update the documentation near the identity key custody
description to state that keys are submitted during save or recovery, may be
retried or explicitly overwritten, and are then retained in the OS keychain.
In `@src/features/onboarding/store.ts`:
- Around line 1-4: The comment above readOnboardingCompletedAt() incorrectly
states that non-Tauri reads resolve to 'pending'. Clarify that
readOnboardingCompletedAt() resolves to null outside Tauri, while
useOnboardingState() maps that result to the 'pending' status; retain the no-op
write behavior.
In `@src/features/system/useAutostart.ts`:
- Around line 1-5: Update the top-level comment for the autostart hook to remove
the claim that state is re-read from the OS after every write; accurately state
that successful toggle requests update local state from the requested `next`
value, while retaining the descriptions of the OS registry as the source of
truth, request-id guard, and unavailable Tauri behavior.
---
Nitpick comments:
In `@src/lib/db/sessions.ts`:
- Around line 1-6: Update the module comment above the session types to
explicitly state that sessions_insert receives default camelCase keys from JS
invoke, while the Rust command parameters and returned session rows remain
snake_case; preserve the distinction between SessionRow and SessionRecord.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 13c7c457-ebbd-4e73-aeee-011482a34286
📒 Files selected for processing (42)
CLAUDE.mdIMPROVEMENTS.mdREADME.mdscripts/check-tokens.tssrc-tauri/src/commands/ai_dialog.rssrc-tauri/src/commands/friends.rssrc-tauri/src/commands/identity.rssrc-tauri/src/commands/mod.rssrc-tauri/src/commands/models.rssrc-tauri/src/commands/sessions.rssrc-tauri/src/commands/sidecar.rssrc-tauri/src/commands/system.rssrc-tauri/src/crypto.rssrc-tauri/src/db/audit_events.rssrc-tauri/src/db/friends.rssrc-tauri/src/db/migrations.rssrc-tauri/src/db/mod.rssrc-tauri/src/db/sessions.rssrc-tauri/src/lib.rssrc/features/friends/AddFriendDialog.tsxsrc/features/friends/AddFriendDialogView.tsxsrc/features/onboarding/store.tssrc/features/settings/categories/AboutCategory.tsxsrc/features/settings/categories/AdvancedCategory.tsxsrc/features/settings/categories/IdentityCategory.tsxsrc/features/settings/categories/SessionsCategory.tsxsrc/features/system/PttListener.tsxsrc/features/system/autostart.tssrc/features/system/useAutostart.tssrc/lib/crypto/identity.tssrc/lib/crypto/topics.tssrc/lib/db/friends.tssrc/lib/db/identity.tssrc/lib/db/sessions.tssrc/lib/trystero/index.tssrc/lib/utils.tssrc/routes/Home.tsxsrc/stores/auditStore.tssrc/stores/friendsStore.tssrc/stores/identityStore.tssrc/stores/sessionStore.tssrc/stores/settingsStore.ts
📜 Review details
⏰ Context from checks skipped due to timeout. (4)
- GitHub Check: CodeRabbit / Review
- GitHub Check: Rust (macOS)
- GitHub Check: Frontend
- GitHub Check: Rust (Windows)
🧰 Additional context used
📓 Path-based instructions (5)
**/*.{ts,tsx,css}
📄 CodeRabbit inference engine (CLAUDE.md)
Use
src/design/tokens.tsas the single source of truth for all design tokens; do not use raw hex values, arbitrary pixel values, or inlinecubic-beziervalues outside that file.
Files:
src/lib/db/friends.tssrc/lib/db/sessions.tssrc/features/settings/categories/AdvancedCategory.tsxsrc/lib/trystero/index.tssrc/lib/crypto/topics.tssrc/routes/Home.tsxsrc/stores/identityStore.tssrc/stores/sessionStore.tssrc/stores/friendsStore.tssrc/lib/utils.tssrc/features/system/autostart.tssrc/features/settings/categories/SessionsCategory.tsxsrc/features/onboarding/store.tssrc/features/settings/categories/AboutCategory.tsxscripts/check-tokens.tssrc/stores/auditStore.tssrc/features/friends/AddFriendDialogView.tsxsrc/lib/db/identity.tssrc/lib/crypto/identity.tssrc/features/system/PttListener.tsxsrc/features/friends/AddFriendDialog.tsxsrc/features/system/useAutostart.tssrc/stores/settingsStore.tssrc/features/settings/categories/IdentityCategory.tsx
src/**/*.{ts,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
Keep toast and notification copy in
src/strings.ts; prefer centralized strings over inline user-facing text andaria-labelliterals.
Files:
src/lib/db/friends.tssrc/lib/db/sessions.tssrc/features/settings/categories/AdvancedCategory.tsxsrc/lib/trystero/index.tssrc/lib/crypto/topics.tssrc/routes/Home.tsxsrc/stores/identityStore.tssrc/stores/sessionStore.tssrc/stores/friendsStore.tssrc/lib/utils.tssrc/features/system/autostart.tssrc/features/settings/categories/SessionsCategory.tsxsrc/features/onboarding/store.tssrc/features/settings/categories/AboutCategory.tsxsrc/stores/auditStore.tssrc/features/friends/AddFriendDialogView.tsxsrc/lib/db/identity.tssrc/lib/crypto/identity.tssrc/features/system/PttListener.tsxsrc/features/friends/AddFriendDialog.tsxsrc/features/system/useAutostart.tssrc/stores/settingsStore.tssrc/features/settings/categories/IdentityCategory.tsx
src/**/*.{ts,tsx,css}
📄 CodeRabbit inference engine (CLAUDE.md)
Meet WCAG AA for text/background pairings in both themes, never convey information by color alone, and honor the global reduced-motion kill switch; new motion must be gated by default.
Files:
src/lib/db/friends.tssrc/lib/db/sessions.tssrc/features/settings/categories/AdvancedCategory.tsxsrc/lib/trystero/index.tssrc/lib/crypto/topics.tssrc/routes/Home.tsxsrc/stores/identityStore.tssrc/stores/sessionStore.tssrc/stores/friendsStore.tssrc/lib/utils.tssrc/features/system/autostart.tssrc/features/settings/categories/SessionsCategory.tsxsrc/features/onboarding/store.tssrc/features/settings/categories/AboutCategory.tsxsrc/stores/auditStore.tssrc/features/friends/AddFriendDialogView.tsxsrc/lib/db/identity.tssrc/lib/crypto/identity.tssrc/features/system/PttListener.tsxsrc/features/friends/AddFriendDialog.tsxsrc/features/system/useAutostart.tssrc/stores/settingsStore.tssrc/features/settings/categories/IdentityCategory.tsx
**/*.{ts,tsx}
📄 CodeRabbit inference engine (CLAUDE.md)
**/*.{ts,tsx}: Maintain TypeScript strictness and ensure TypeScript builds and checks pass before committing or opening a PR.
Do not add component tests using RTL/jsdom without deliberate, flagged scope expansion; Vitest uses node-env and component behavior is covered by Storybook and axe-core.
Files:
src/lib/db/friends.tssrc/lib/db/sessions.tssrc/features/settings/categories/AdvancedCategory.tsxsrc/lib/trystero/index.tssrc/lib/crypto/topics.tssrc/routes/Home.tsxsrc/stores/identityStore.tssrc/stores/sessionStore.tssrc/stores/friendsStore.tssrc/lib/utils.tssrc/features/system/autostart.tssrc/features/settings/categories/SessionsCategory.tsxsrc/features/onboarding/store.tssrc/features/settings/categories/AboutCategory.tsxscripts/check-tokens.tssrc/stores/auditStore.tssrc/features/friends/AddFriendDialogView.tsxsrc/lib/db/identity.tssrc/lib/crypto/identity.tssrc/features/system/PttListener.tsxsrc/features/friends/AddFriendDialog.tsxsrc/features/system/useAutostart.tssrc/stores/settingsStore.tssrc/features/settings/categories/IdentityCategory.tsx
src-tauri/**/*.rs
📄 CodeRabbit inference engine (CLAUDE.md)
src-tauri/**/*.rs: Treat peer wire formats and identity derivation as cross-version contracts; coordinate changes so older peers and existing stored data remain compatible.
For Rust changes, run and passcargo test,cargo fmt --check, andcargo clippy.
Files:
src-tauri/src/commands/mod.rssrc-tauri/src/commands/friends.rssrc-tauri/src/db/friends.rssrc-tauri/src/db/sessions.rssrc-tauri/src/crypto.rssrc-tauri/src/db/audit_events.rssrc-tauri/src/db/mod.rssrc-tauri/src/commands/models.rssrc-tauri/src/commands/identity.rssrc-tauri/src/commands/ai_dialog.rssrc-tauri/src/lib.rssrc-tauri/src/commands/sidecar.rssrc-tauri/src/commands/system.rssrc-tauri/src/commands/sessions.rssrc-tauri/src/db/migrations.rs
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: scotej/studyvis
Timestamp: 2026-07-10T05:29:58.096Z
Learning: The application must remain local-only: never add telemetry, and never instruct users to share model files or BIP39 mnemonics with an AI service.
Learnt from: CR
Repo: scotej/studyvis
Timestamp: 2026-07-10T05:29:58.096Z
Learning: Do not create new documentation files unless explicitly asked; update canonical documents, `CHANGELOG.md`, or `ISSUES.md` only when justified.
Learnt from: CR
Repo: scotej/studyvis
Timestamp: 2026-07-10T05:29:58.096Z
Learning: Add comments only when the reason is non-obvious; identifiers should carry meaning and code should read top-to-bottom.
Learnt from: CR
Repo: scotej/studyvis
Timestamp: 2026-07-10T05:29:58.096Z
Learning: Maintain scope discipline: do not refactor adjacent code during feature work or add abstractions for hypothetical future needs.
Learnt from: CR
Repo: scotej/studyvis
Timestamp: 2026-07-10T05:29:58.096Z
Learning: Use one focused change per commit, with a Conventional Commit subject such as `feat:`, `fix:`, `chore:`, `docs:`, or `ci:`; PRs should squash-merge.
🔇 Additional comments (38)
src/lib/crypto/identity.ts (1)
1-20: LGTM!Also applies to: 34-36, 116-119, 173-176
src/lib/crypto/topics.ts (1)
1-11: LGTM!src/lib/db/friends.ts (1)
1-6: LGTM!src/lib/db/identity.ts (1)
1-8: LGTM!src/lib/trystero/index.ts (1)
1-10: LGTM!src/lib/utils.ts (1)
4-6: LGTM!src/features/friends/AddFriendDialog.tsx (1)
1-9: LGTM!src/features/friends/AddFriendDialogView.tsx (1)
1-6: LGTM!src/features/settings/categories/AboutCategory.tsx (1)
1-6: LGTM!src/features/settings/categories/AdvancedCategory.tsx (1)
1-6: LGTM!src/stores/identityStore.ts (1)
1-7: LGTM!src/stores/settingsStore.ts (1)
1-20: LGTM!src/features/settings/categories/SessionsCategory.tsx (1)
1-6: LGTM!src/features/system/PttListener.tsx (1)
1-7: LGTM!src/routes/Home.tsx (1)
1-16: LGTM!src/stores/auditStore.ts (1)
1-8: LGTM!src/stores/friendsStore.ts (1)
1-5: LGTM!src/stores/sessionStore.ts (1)
1-8: LGTM!src-tauri/src/commands/friends.rs (1)
1-6: LGTM!src-tauri/src/commands/mod.rs (1)
1-8: 📐 Maintainability & Code QualityRun the Rust quality gates before merging.
For these Rust source changes, verify
cargo test,cargo fmt --check, andcargo clippypass across the workspace.Source: Coding guidelines
src-tauri/src/commands/models.rs (1)
1-14: LGTM!src-tauri/src/commands/sessions.rs (1)
1-6: LGTM!src-tauri/src/commands/sidecar.rs (1)
1-19: LGTM!src-tauri/src/commands/system.rs (1)
1-16: LGTM!Also applies to: 29-30
src-tauri/src/crypto.rs (1)
1-17: LGTM!Also applies to: 32-34
src-tauri/src/db/audit_events.rs (1)
1-5: LGTM!src-tauri/src/db/friends.rs (1)
1-6: LGTM!src-tauri/src/db/migrations.rs (1)
1-10: LGTM!src-tauri/src/db/mod.rs (1)
1-15: LGTM!Also applies to: 29-32
src-tauri/src/db/sessions.rs (1)
1-9: LGTM!src-tauri/src/lib.rs (1)
1-19: LGTM!CLAUDE.md (1)
19-35: LGTM!IMPROVEMENTS.md (1)
3-19: LGTM!README.md (2)
297-301: LGTM!Also applies to: 337-353
302-335: Node version floor is correct — Vite 8’s documented minimum is Node 20.19.0+ or 22.12.0+.scripts/check-tokens.ts (1)
2-10: LGTM!src/features/settings/categories/IdentityCategory.tsx (1)
1-8: LGTM!Also applies to: 28-32, 37-37, 42-42, 44-44, 46-187, 188-279
src/features/system/autostart.ts (1)
1-4: LGTM!Also applies to: 7-9, 11-13
| // Onboarding-completion flag, persisted as `onboarding_completed_at` in the | ||
| // Tauri store file `app-state.json` (separate from settings.json). Outside a | ||
| // Tauri runtime (Storybook / node tests) the read resolves to 'pending' and | ||
| // writes no-op, so onboarding simply renders. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Clarify the non-Tauri read behavior.
readOnboardingCompletedAt() resolves to null outside Tauri; useOnboardingState() exposes the resulting status as 'pending'. Adjust the comment to distinguish the helper return value from the hook state.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@src/features/onboarding/store.ts` around lines 1 - 4, The comment above
readOnboardingCompletedAt() incorrectly states that non-Tauri reads resolve to
'pending'. Clarify that readOnboardingCompletedAt() resolves to null outside
Tauri, while useOnboardingState() maps that result to the 'pending' status;
retain the no-op write behavior.
The ai-dialog destroy() rationale wrongly credited lib.rs interception (its close-requested handler only acts on the main window); the identity module claimed a strictly-once key handoff (save accepts idempotent retries and confirmed overwrites); the onboarding store note conflated the null-returning helper with the hook's 'pending' status; and the autostart hook does not re-read OS state after a write. Also tightens the sessions.ts camelCase/snake_case direction note. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0171qBAM76TzzpJptZuiua1o
Summary
This PR adds comprehensive documentation to the codebase: a new "Developing" section in README.md with setup and testing instructions, detailed module-level headers documenting cross-version contracts and load-bearing invariants, and updates to CLAUDE.md and IMPROVEMENTS.md to reflect the current state of the project.
Key changes
README.md: Added "Developing" section covering the tech stack, setup steps (
npm install,scripts/fetch-llama-server.sh,npm run tauri dev), lighter development loops (Vite-only and Storybook), and the full quality-gate checklist. Updated doc map to reference CLAUDE.md and clarify IMPROVEMENTS.md as retired.CLAUDE.md: Added "Comment shorthand used throughout the code" section documenting the compact tag convention (
F1,A5,D5, etc.) that appears at implementing code sites, cross-referenced to IMPROVEMENTS.md's Status block. Clarified IMPROVEMENTS.md as a retired 2026-06 snapshot with 55 of 56 items shipped.IMPROVEMENTS.md: Added Status block documenting that the backlog is retired, with a 2026-07 code audit finding 55 of 56 items shipped and only P1 (Linux) partially open. Item IDs now live as comment tags at implementing code sites.
Module-level headers (Rust and TypeScript): Added detailed doc comments to 30+ files explaining purpose, invariants, wire-format contracts, and coupling patterns:
src/lib/crypto/identity.ts,src-tauri/src/crypto.rs,src/lib/crypto/topics.ts): Documented BIP39→Ed25519/X25519 derivation as a cross-version contract, NaCl box byte-compatibility with libsodium, and trystero topic derivation as a rendezvous wire contract.src-tauri/src/db/mod.rs,src-tauri/src/db/migrations.rs,src-tauri/src/db/friends.rs,src-tauri/src/db/sessions.rs,src-tauri/src/db/audit_events.rs): Documented forward-only migration policy, schema compatibility, and upsert semantics.src-tauri/src/lib.rs,src-tauri/src/commands/system.rs,src-tauri/src/commands/identity.rs,src-tauri/src/commands/models.rs,src-tauri/src/commands/sidecar.rs,src-tauri/src/commands/friends.rs,src-tauri/src/commands/sessions.rs): Documented teardown ordering, lifecycle invariants, keychain custody, and sidecar crash-restart budgets.src/stores/settingsStore.ts,src/stores/sessionStore.ts,src/stores/auditStore.ts,src/stores/identityStore.ts,src/stores/friendsStore.ts,src/routes/Home.tsx,src/features/friends/AddFriendDialog.tsx,src/features/friends/AddFriendDialogView.tsx,src/features/settings/categories/*.tsx,src/features/system/PttListener.tsx,src/features/onboarding/store.ts,src/features/system/useAutostart.ts,src/features/system/autostart.ts): Documented mount-structure invariants, cleanup subtleties, and coupling patterns.src/lib/db/identity.ts,src/lib/db/friends.ts,src/lib/db/sessions.ts,src/lib/trystero/index.ts,src/lib/utils.ts,scripts/check-tokens.ts): Documented type mirrors, keychain twins, room merging, and guard-script purpose.Rust comment style: Converted
ai_dialog.rsfrom C-style block comments to Rust doc-comment style (`//https://claude.ai/code/session_0171qBAM76TzzpJptZuiua1o
Summary by CodeRabbit
New Features
Documentation