Watch mode, agent skill, and review-first positioning docs

CHANGELOG.md

@@ -7,8 +7,32 @@ pre-1.0).
 
 ## [Unreleased]
 
+### Added
+
 ### Fixed
 
+- `rift diff --watch` live-reloads the browser as the working tree changes —
+  built for reviewing while an agent edits in another pane. The file list,
+  stats, and diffs refresh in place (the selection survives), the tests lens
+  re-collects, and content-keyed reviewed marks reset as files change, so the
+  unreviewed filter always shows what still needs eyes. A `watching` tag in
+  the header shows it's live, and `w` toggles it without restarting —
+  enabling catches up on anything that changed while it was off.
+- `rift skill` prints a built-in agent skill that teaches an AI agent rift's
+  composable review workflow (`--json` changeset inspection, structural
+  `--print` diffs, the `--tests` lens, review state). `rift skill path` writes
+  it to `~/.local/share/rift/skills/rift-review/SKILL.md` and prints the path,
+  so you can tell an agent "run `rift skill path` and follow that skill".
+- Committed-range and base-ref diffs now detect renames: a moved file lists as
+  one `R` record showing only its real content delta (with an `old → new`
+  preview title and `old_path` in `--json`) instead of a full delete plus add.
+  The tests lens reads a renamed file's old side from its old path, so its
+  specs no longer all report as newly added. Working-tree and staged listings
+  keep git-status semantics (the stage screen operates on real index paths).
+
+- In a base-ref diff (`rift diff main`), returning from the editor (`o`) no
+  longer replaces the file list with the plain worktree-vs-index set — the
+  reload now honors the base ref.
 - `install.sh` no longer fails checksum verification on macOS with a matching
   hash: it now compares hash strings directly instead of relying on `-c` check
   mode, whose behavior differs between GNU `sha256sum` and macOS's `shasum`.
@@ -184,7 +208,7 @@ pre-1.0).
   - `rift diff` shows the file list and toggles to the tests view live with `t`
     (the header reads `rift ❯ diff ❯ tests` to show it's a lens); `--tests` just
     opens straight into it. Works on the working tree, `--staged`, or a `<commit>
-    <commit>` range, with `--print`/`--json` for scripting. The diff preview
+<commit>` range, with `--print`/`--json` for scripting. The diff preview
     scrolls to the selected test and labels it in the panel's border, so a
     body-only change stays named even when its declaration isn't in the diff;
     `o` opens it in `$EDITOR` at its line.
@@ -247,7 +271,7 @@ pre-1.0).
 
 ## [0.2.0] - 2026-05-31
 
-A big step toward being a daily driver for *reading* git state: the diff and log
+A big step toward being a daily driver for _reading_ git state: the diff and log
 browsers got a top-to-bottom presentation overhaul, and the tool's scope
 tightened around what it does best.
 
@@ -275,7 +299,7 @@ tightened around what it does best.
   quitting; quit stays on `q` / `ctrl+c`.
 - Upgraded to the Charm v2 ecosystem (bubbletea / lipgloss / bubbles) and
   extracted a reusable split-list component shared across screens.
-- Repositioned as *worktree-aware* — every command reads correctly inside
+- Repositioned as _worktree-aware_ — every command reads correctly inside
   bare-repo and linked-worktree layouts — rather than worktree-managing. Pair
   with [worktrunk](https://github.com/max-sixty/worktrunk) for managing
   worktrees and branches.

CLAUDE.md

@@ -38,6 +38,7 @@ internal/      # private packages
   review/      # review state (reviewed marks) + test-case extraction
   tooling/     # external tool management (difftastic download/detect)
   output/      # --print / --json composable output
+  skill/       # embedded agent skill (SKILL.md) + materialization
 main.go        # entrypoint
 ```
 
@@ -50,6 +51,9 @@ design intent only — do not assume the packages or tools exist:
 - **Syntax-aware merge / conflict resolution:** mergiraf (`internal/merge`)
 - **Checkpoints:** shadow-commit snapshots on hidden refs (`internal/checkpoint`)
 - **Risk classification** in review — today `internal/review` only tracks reviewed marks and extracts test cases
+- **Inline agent annotations:** `rift annotate` writing to a JSON store next to the reviewed marks (`.git/rift/annotations.json`), rendered in the diff preview and picked up by `--watch`. File-based on purpose — no daemon/socket (see the design doc's Future Considerations)
+- **Mouse support:** wheel scroll + click-to-select via bubbletea mouse events; must keep terminal text selection workable (see design doc)
+- **Moved-line diff view:** a config option swapping the git engine's flags to `--color-moved=zebra --color-moved-ws=allow-indentation-change` (mutually exclusive with the default `--word-diff=color` — git silently ignores `--color-moved` under word-diff, so it can't be a combined default; see `displayFlags` in `internal/diff`)
 
 ## Workflow