feat(review): local review notes across app, CLI, and agents

Author: hewigovens

AGENTS.md

@@ -8,9 +8,12 @@ Keep this file as always-loaded guidance. Load focused docs only when the task t
 
 - [Release Workflow](agents/release.md) - version bumps, notarization, appcast, GitHub release, Homebrew tap.
 - [Testing Guide](agents/testing.md) - Rust/Swift/GPUI test placement, fixtures, UI test rules.
-- [Architecture Guide](agents/architecture.md) - MVVM boundaries, file layout, review state, presentation surfaces.
+- [Architecture Guide](agents/architecture.md) - workspace crates, dependency rules, MVVM boundaries, core module layout.
+- [SwiftUI Shell Guide](agents/swiftui.md) - shell/mac file layout, view-model and caching conventions, presentation surfaces.
+- [GPUI Shell Guide](agents/gpui.md) - shell/gpui file layout, state ownership, globals, caches, rendering tips.
+- [Review State Guide](agents/review-state.md) - review store, marks, notes, and the reconciliation contract.
 - [Design Guide](agents/design.md) - JayJay product context, visual direction, interaction principles.
-- [Help Book Guide](agents/help-book.md) - bundled macOS Help Book, web guide reuse, Help Viewer cache, and Apple Help pitfalls.
+- [Help Book Guide](agents/help-book.md) - public website (`docs/`), bundled macOS Help Book, web guide reuse, Help Viewer cache, and Apple Help pitfalls.
 - [Pull Request Workflow](agents/pull-requests.md) - bookmark-based GitHub and Codeberg PRs, review updates, landing.
 - [Code Review Guide](agents/code-review.md) - repo-specific review setup, adversarial checks, severity, and reporting.
 
@@ -50,7 +53,7 @@ just release    # Sign, notarize, package; read agents/release.md first
 
 Business logic lives in Rust core. UniFFI bridges types. SwiftUI and GPUI shells render state and dispatch actions.
 
-Load [Architecture Guide](agents/architecture.md) before changing ownership boundaries, review state, presentation surfaces, or large file layout.
+Load [Architecture Guide](agents/architecture.md) before changing crate or ownership boundaries; load the [SwiftUI](agents/swiftui.md) or [GPUI](agents/gpui.md) shell guide before large file-layout or convention changes in that shell; load [Review State Guide](agents/review-state.md) before touching review marks or notes.
 
 ## Testing
 
@@ -105,6 +108,17 @@ Do not use `git commit`, `git add`, `git push`, `git stash`, `git branch`, or `g
 
 Do not add AI attribution to commits or PRs — no `Generated with`, `Co-Authored-By`, or assistant/session trailers — unless the user explicitly asks.
 
+## Local Review Notes
+
+JayJay can store local review notes on the current working-copy change. Agents should read them before finalizing issue work:
+
+```bash
+jayjay review notes --repo . --format json
+jayjay review resolve-note <id> --repo .
+```
+
+Treat `current` notes as actionable, `stale` notes as needing re-check against the changed diff, and `orphaned` notes as comments whose original file/anchor disappeared. Resolve notes only after the underlying feedback is addressed.
+
 ## UI And Design
 
 JayJay is a macOS-native developer tool for jj users. Keep UI changes:

Cargo.lock

@@ -1,5 +1,5 @@
 [workspace]
-members = ["crates/jj-diff", "crates/jj-test", "crates/jayjay-network", "crates/jayjay-core", "crates/jayjay-uniffi", "crates/jayjay-cli", "shell/gpui"]
+members = ["crates/jj-diff", "crates/jj-test", "crates/jayjay-network", "crates/jayjay-primitives", "crates/jayjay-review", "crates/jayjay-core", "crates/jayjay-uniffi", "crates/jayjay-cli", "shell/gpui"]
 resolver = "2"
 
 [workspace.package]
@@ -26,6 +26,7 @@ serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 sha2 = "0.11.0"
 hex = "0.4"
+uuid = { version = "1", features = ["v4"] }
 similar = "3.1.1"
 unicode-width = "0.2"
 unicode-segmentation = "1"

Cargo.toml

@@ -1,82 +1,42 @@
 # Architecture Guide
 
-Load this file before changing module ownership, repo state, review state, presentation surfaces, or large file layout.
+Load this file before changing crate ownership, module boundaries, or cross-shell contracts. For shell file layouts and conventions load [SwiftUI Shell Guide](swiftui.md) or [GPUI Shell Guide](gpui.md); for review marks and notes load [Review State Guide](review-state.md).
 
-## MVVM
-
-```text
-Rust Core -> UniFFI -> ViewModel -> SwiftUI/GPUI Views
-    ^             |          |              |
-    |             v          v              v
- business     type bridge  actions       rendering
-```
+## Workspace Crates
 
-- **Model** (`crates/jayjay-core/`): jj-lib wrapper, diff engine, tree-sitter syntax, review state, repo operations. Pure Rust, no platform code.
-- **Bindings** (`crates/jayjay-uniffi/`): thin UniFFI layer. Convert types and expose core APIs; do not add business logic.
-- **SwiftUI ViewModel** (`Repo/RepoViewModel.swift` and `RepoViewModel+Actions.swift`): owns `JayJayRepo`. jj operations go through here. Async work uses `Task.detached` then `MainActor.run`.
-- **Views**: feature folders in SwiftUI and GPUI. Views render state and call callbacks; they should not know jj internals.
-
-## Core Modules
+| Crate / target | Responsibility |
+| --- | --- |
+| `jayjay-primitives` | jj-lib-free domain types: `Change`, `Bookmark`, `DiffHunk`, review types, hashing |
+| `jj-diff` | Diff engine: Histogram line diff, word diff, tree-sitter syntax, context collapse, wrapping, conflict display, canonical change groups |
+| `jayjay-review` | Local review store: marks, notes, reconciliation (uses `jj-diff`) |
+| `jayjay-network` | Shared blocking HTTP client helpers |
+| `jayjay-core` | jj-lib wrapper and repo operations; re-exports `jj-diff` as `jayjay_core::diff` |
+| `jayjay-uniffi` | UniFFI bindings for the SwiftUI shell only; no business logic |
+| `jayjay-cli` | `jayjay` binary: app launcher plus agent-facing `review` subcommands |
+| `jj-test` | Shared jj repo fixtures for integration and component tests |
+| `shell/gpui` | Cross-platform GPUI shell; links the Rust crates directly (no UniFFI) |
+| `shell/mac` | SwiftUI shell + the `JayJayDiffUI` Swift package (AppKit diff renderer) |
 
-Keep core logic split by responsibility:
+Dependency direction (never invert): `primitives` and `jj-diff` are leaves → `jayjay-review` → `jayjay-core` → `jayjay-uniffi` / `jayjay-cli` / `shell/gpui`.
 
-- `repo/mod.rs`
-- `repo/log.rs`
-- `repo/diff.rs`
-- `repo/mutations.rs`
-- `repo/bookmarks.rs`
-- `repo/git.rs`
-- `repo/working_copy.rs`
-- `repo/config.rs`
-- `repo/environment.rs`
-- `repo/resolve.rs`
-- `repo/conflicts.rs`
-- `repo/annotate.rs`
-- `diff/compute.rs`
-- `review.rs`
-- `hash.rs`
+- New shared types go in `jayjay-primitives`, not `jayjay-core`, so review/CLI code stays jj-lib-light.
+- Anything two surfaces must agree on (change groups, review identity, note reconciliation) lives at or below `jayjay-review`/`jj-diff` and is consumed by all surfaces. Do not re-implement a diff or identity computation per surface; the GUI and `jayjay review notes` must reconcile through the same provider or notes silently report stale.
 
-## SwiftUI File Layout
+## MVVM
 
 ```text
-shell/mac/Sources/JayJay/
-  App/
-    Config/       AppSettings, AppearanceTypes, EditorTypes, TerminalTypes, AppSettingsTools, FontEnvironment, AppMetadata, JJEnvironment
-    Window/       RepoWindowManager, RepositoryCommands, RepositoryFocus, RepositoryActions
-    Watcher/      RepoFSWatcher
-    JayJayApp.swift, CLIInstaller.swift, DebugBadge.swift, LaunchArguments.swift, SparkleUpdater.swift
-  Repo/           RepoWindow, RepoSidebar, RepoViewModel, RepoViewModel+Actions, DAGView, DAGLayout, DAGRow, DAGRowViewModel, RepoPresentation, RepoToast, CommitBox, BookmarkPicker, UndoView
-  Detail/         DetailView, DetailHeader, FileColumn, FileListView, AnnotateView, FileHistoryView
-  Diff/           DiffSection, DiffColors, NativeDiffView, SideBySideDiffView
-  Onboarding/     OnboardingView, WelcomeView
-  Settings/       SettingsView, JJConfigView, AboutView, SettingsComponents
-  Shared/         ChangeActions, ErrorMessages, ReviewStore, SheetViews, CommandPalette
+Rust Core -> UniFFI -> ViewModel -> SwiftUI Views
+    |                                      
+    +------------- direct link ---------> GPUI shell (view_model + window)
 ```
 
-## Review State
-
-Review state is persistent across app restarts and local to the user.
-
-- Canonical implementation: `jayjay_core::review::ReviewStore`.
-- SwiftUI still has `Shared/ReviewStore.swift` with the same shape; GPUI uses the Rust store.
-- Identity is caller-supplied. The store is a pure keyed store with no disk access and no hashing.
-- Review identity is computed in `jayjay_core::repo::diff::entry::compute_review_identity` from `MergedTreeValue` blob IDs.
-- Keying: `(changeId, path) -> { identity, file_marked, hunks }`.
-- Valid marks require the stored identity to match the current `hunk.review_identity`.
-- Same blob IDs preserve review across rebases or amends that do not change file bytes.
-- Any byte change in the old or new side invalidates only that file's review.
-- `is_hunk_reviewed(idx)` is true when the file is marked or the hunk set contains `idx`.
-- Marking every hunk promotes to file-level review. Unmarking a hunk drops the file flag.
-- Persistence path: `~/Library/Application Support/dev.hewig.jayjay/review_store.json` for Rust and `UserDefaults` for Swift.
-
-## Presentation Surfaces
+- **Model** (`crates/`): all business logic. Pure Rust, no platform code.
+- **Bindings** (`crates/jayjay-uniffi/`): convert types and expose core APIs; do not add business logic. Bindings regenerate during `just build`.
+- **ViewModels** own the repo handle and all jj operations: `Repo/ViewModel/` in SwiftUI, `repo/view_model/` in GPUI.
+- **Views**: feature folders in SwiftUI and GPUI. Views render state and call callbacks; they should not know jj internals.
 
-Use repo-level presentation types from `RepoPresentation.swift` instead of ad hoc booleans.
+Async conventions (both shells): heavy jj work runs off the UI thread (`Task.detached` → `MainActor.run` in Swift; `cx.background_spawn` → `this.update` in GPUI) and every in-flight result is guarded by a supersession check — a token, generation counter, or commit-id compare against current `@State`/VM state — so a slow stale result can never overwrite a newer one. Both shells also suppress the FS-watcher echo of their own writes (`lastInternalMutationAt` / `last_internal_mutation_at`).
 
-- **Inline state**: pane-scoped no-data, first-run guidance, and recoverable section errors.
-- **Toast** (`RepoOverlayState.toast` / `RepoToast`): non-blocking action feedback, success messages, conflict follow-up, and lightweight warnings. Keep it short and allow at most one direct action.
-- **HUD** (`RepoOverlayState.loading`): temporary blocking busy states where further interaction would be misleading or unsafe. Prefer quiet refreshes.
-- **Alert** (`RepoAlertState`): short blocking interruptions that need acknowledgement or a simple binary choice. No forms, long copy, or more than two meaningful actions.
-- **Sheet** (`RepoModalState` + `SheetContainer`): forms, previews, richer explanations, multi-step flows, or confirmations needing more context than an alert.
+## Core Modules
 
-Do not escalate inline states into alerts or sheets just because they are errors. Scope the surface to the problem.
+Keep `jayjay-core` logic split by responsibility under `repo/` (one file or folder per operation family: `log`, `diff/`, `mutations`, `bookmarks`, `git/`, `working_copy`, `resolve/`, `conflicts`, `annotate`, `evolog`, `diffedit/`, `stacked_pr/`, `pull_requests/`, `review_notes`, `undo`, `workspace`). Top-level modules (`dag`, `file_tree`, `fuzzy`, `palette`, `theme`, `commit_message`) are repo-free helpers.

agents/architecture.md

@@ -9,7 +9,7 @@ The focused docs remain the source of truth. This guide points review attention
 ## Review Setup
 
 1. Read `AGENTS.md`.
-2. Load the focused guide for the changed area: `agents/architecture.md`, `agents/testing.md`, `agents/design.md`, `agents/pull-requests.md`, or `agents/release.md`.
+2. Load the focused guide for the changed area: `agents/architecture.md`, `agents/swiftui.md`, `agents/gpui.md`, `agents/review-state.md`, `agents/testing.md`, `agents/design.md`, `agents/pull-requests.md`, or `agents/release.md`.
 3. Inspect `jj st` and the diff, then read the full changed files and nearby patterns before judging the patch.
 4. Flag direct edits to generated files, bindings, fixtures, release outputs, or documentation assets unless they trace back to source inputs.
 5. Identify the changed behavior, affected user path, verification that would catch a regression, and whether the change is non-trivial enough to need adversarial review.

agents/code-review.md

@@ -18,14 +18,14 @@ Clean, modern, approachable. The blue jaybird mascot adds personality without ma
 - Support light and dark modes through system preference.
 - Prefer macOS-native feel: SF Symbols, system fonts, native controls.
 
+## Website
+
+The public site at [jayjay.hewig.dev](https://jayjay.hewig.dev) (sources in `docs/`) is a brand surface: the landing page, FAQ, and user guide follow the same jaybird palette, voice, and screenshot style as the app. Load [Help Book Guide](help-book.md) for the `docs/` file layout and what to update together when user-facing features change.
+
 ## Interaction Principles
 
 1. **Native first** - Use SwiftUI forms, system fonts, SF Symbols, and platform conventions.
 2. **Keyboard-driven** - Every action should be reachable through command palette or shortcut.
 3. **Dense, not cluttered** - Optimize for scanning, comparison, and repeated developer workflows.
 4. **Performance is UX** - Prefer quiet refreshes over loading spinners where possible.
 5. **Jujutsu-native** - Embrace changes, bookmarks, revsets, and working-copy semantics rather than forcing git branch/commit mental models.
-
-## GPUI Layout
-
-- Row-like controls should usually set `.w_full()` before centering content; `justify_center()` only centers within the element's own width.

agents/design.md

@@ -0,0 +1,37 @@
+# GPUI Shell Guide
+
+Load this file before changing the GPUI shell's layout, state ownership, globals, caches, or rendering conventions. Crate boundaries live in [Architecture Guide](architecture.md); review marks and notes in [Review State Guide](review-state.md).
+
+`shell/gpui` is the cross-platform shell (macOS + Linux; packaged as an AppImage via `just gpui-appimage`). It links the Rust crates directly — no UniFFI, no Swift.
+
+## File Layout
+
+```text
+shell/gpui/src/
+├── app/           process-level: actions, TOML AppConfig store, Theme, native menus,
+│                  fs_watcher/ (notify-based repo watcher), telemetry, editor/terminal launchers
+├── diff/          pure view components: diff_view/ (unified + side-by-side, find bar, wrap_cache),
+│                  file_column/ (flat + tree list, tree_cache), selection, annotate, image diff
+├── platform/      cfg-gated macos.rs vs linux.rs seam: MOD_KEY, toolbar insets, menu-bar
+│                  strategy (native vs in-window), reveal-in-file-manager
+├── repo/          the main repo window feature
+│   ├── revset/        change/compare/endpoint helpers over jj revsets
+│   ├── toolbar/       top toolbar and buttons
+│   ├── view_model/    RepoViewModel: domain state, loaders, mutations, tasks
+│   └── window/        RepoWindow view: render, actions, sidebar, DAG, detail, review, status bar
+├── ui/            reusable widgets: text_area/, input/, avatar/ (+cache), context_menu, scrollbar
+└── windows/       secondary GPUI windows: settings/, bookmark_manager, operation_log/,
+                   command_palette/, evolog, file_history — each opened via a static `open(...)`
+```
+
+## Conventions
+
+- **State ownership** mirrors the SwiftUI split: `RepoWindow` (`repo/window/view.rs`) owns UI state — focus, pane/layout, find, diff selection, scroll handles, toasts, commit-box `TextArea`s, cache slots, the fs watcher, and the shared review-store handle. `RepoViewModel` (`repo/view_model/`) owns domain state — `Arc<Repo>`, graph data, selection, loaded diffs, compare state, loading flags. Input flows window → `vm.update(cx, …)` → `jayjay_core::Repo`.
+- **Async** is centralized in `view_model/tasks.rs` (`background_update`, `repo_write_task`, `core_result_task`): heavy jj work on `cx.background_spawn`, re-entry via `this.update`, with per-section generation counters (`change_gen`, `diff_gen`, `pr_gen`, `refresh_gen`) dropping stale results.
+- **Globals** (the only ones): `Theme`, `AppConfigStore` (TOML config), `ReviewStoreHandle` (process-wide review store — mutate only through `window/review.rs::mutate`), and the test-only `WatcherSuppressed`. Tests replace all of them via `tests/support::install_test_globals` (ephemeral config, light theme, in-memory review store, suppressed watcher).
+- **Render caches** live in `Rc<RefCell<…>>` slots so re-renders reuse work: `DiffWrapCache` (wrapped lines keyed on `Arc<FileDiff>` identity + columns), `FileTreeCache` (flattened tree keyed on hunks identity + visibility + collapsed dirs), and the VM's `diff_cache`. Canvas prepaint writes panel bounds into `Rc<Cell<…>>` slots that mouse handlers read.
+- **FS watcher** (`app/fs_watcher/`): notify events are classified into op-heads vs working-copy changes, debounced (1s/2s), relevance-filtered through `has_unignored_working_copy_paths`, and delivered over a flume channel into `vm.handle_working_copy_change`.
+
+## Rendering Tips
+
+- Row-like controls should usually set `.w_full()` before centering content; `justify_center()` only centers within the element's own width.

agents/gpui.md

@@ -1,6 +1,17 @@
 # Help Book Guide
 
-Load this file before changing the bundled macOS Help Book, the public user guide, help screenshots, command-palette help entries, or Help menu behavior.
+Load this file before changing the bundled macOS Help Book, the public website or user guide, help screenshots, command-palette help entries, or Help menu behavior.
+
+## Website
+
+`docs/` is the GitHub Pages root, served at `jayjay.hewig.dev` (see `docs/CNAME`):
+
+- `docs/index.html` is the landing page with the FAQ (`/#faq`), linked from `README.md`.
+- `docs/guide.html` + `docs/guide.css` are the user guide; screenshots live in `docs/imgs` and double as Help Book sources.
+- `docs/llms.txt` is the machine-readable project summary; `docs/sitemap.xml` and `docs/robots.txt` cover indexing.
+- `docs/appcast.xml` is the Sparkle update feed — owned by the release flow; load [Release Workflow](release.md) before touching it.
+
+When a user-facing feature ships, update together: the guide page, the llms.txt summary if the feature list changed, the FAQ if it answers a common question, and the Help Book (below) which reuses the same content and screenshots.
 
 ## Source Layout