@vintasoftware/pr-review-canvas 0.4.0 → 0.5.0

package/README.md

@@ -63,6 +63,18 @@ Install the command globally once, for use in any project:
 npm install -g @vintasoftware/pr-review-canvas
 ```
 
+### Upgrade
+
+Run this from a project that has the skill installed:
+
+```bash
+pr-review upgrade
+```
+
+It updates pr-review, acpx, and the project's skill copies, after showing the plan and asking.
+Commit and push any refreshed skill copies so your team uses the same skill. `--yes` skips the
+question.
+
 ## Set up a project
 
 ```bash
@@ -73,9 +85,8 @@ pr-review doctor --all-checks
 
 `install-skill` sets up **both Claude Code and Codex** in one command: `.claude/skills/pr-review-canvas`
 and `.agents/skills/pr-review-canvas`, respectively. These are portable copies you can commit to Git.
-Re-run `pr-review install-skill` after upgrading the CLI to refresh them. It also adds `.pr-review/settings.yml` to the
-project's `.gitignore`. Restart your coding agent if the skill
-does not appear. Repeat this setup for each project you want to review.
+`pr-review upgrade` refreshes them after the CLI changes. It also adds `.pr-review/settings.yml` to the
+project's `.gitignore`. Restart your coding agent if the skill does not appear. Repeat this setup for each project you want to review.
 
 `doctor` checks Git, your GitHub or GitLab remote, the matching CLI (`gh` or `glab`) and its login,
 write access to the local canvas directory, and whether installed skills match the current package.
@@ -91,7 +102,7 @@ or modified. The warning includes the reinstall command and does not block start
 To ask questions about a PR inside the canvas, install `acpx` globally:
 
 ```bash
-npm install -g acpx
+npm install -g acpx@latest
 acpx --version
 pr-review doctor --all-checks
 ```
@@ -131,17 +142,25 @@ merged `main` in without touching the changed files, for example, the canvas sti
 and the page says so. Set `canvas.keepForIdenticalDiff: false` in the project config to treat
 every commit as a new head.
 
+Regenerating for a new head updates the previous canvas. Content for untouched files is kept,
+and your review progress on them follows. `--force` starts from a blank page, and
+`canvas.incremental: false` turns this off. See [Incremental canvases](docs/reference.md#incremental-canvases).
+
 ## Configuration
 
 ### User-local preferences
 
-Your appearance and AI Chat preferences are saved in `.pr-review/settings.yml` in your local
-project directory. This file is ignored by Git, so each teammate can use their own settings.
+Your appearance, reading level, and AI Chat preferences are saved in `.pr-review/settings.yml`
+in your local project directory. This file is ignored by Git, so each teammate can use their own
+settings.
 
-Use **skin** and **theme** in the header to change the appearance.
+Use **skin** and **theme** in the header to change the appearance, and **Hide code by default**
+in the settings dialog to choose how much code a review hides when it opens.
 
 For AI Chat, open **settings**, choose Claude Code or Codex, and optionally enter a model ID.
-Leave the model blank to use the agent's default. You can also adjust the reply timeout and
+Leave the model blank to use the agent's default. A model ID runs as the newest model of its family
+(`claude-opus-4-8` runs as `opus`); write `pin:claude-opus-4-8` to use that exact model. See
+[Model families](docs/reference.md#model-families). You can also adjust the reply timeout and
 maximum turns. Click **Test agent** to check the connection, then **save**.
 
 Switching agents starts a new thread and keeps earlier threads. Server flags `--agent` and

package/docs/reference.md

@@ -15,15 +15,15 @@ For setup and the basic review workflow, see the [README](../README.md).
 
 ### Repository and runtime options
 
-| Option                           | Applies to                 | Default and behavior                                                                                             |
-| -------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `--repo <dir>`                   | All commands               | Uses the current directory when omitted; resolves the repository root from there                                 |
-| `--data-dir <dir>`               | All except `install-skill` | Overrides `PR_REVIEW_DATA_DIR`, then the default `<main checkout>/.pr-review`                                    |
-| `--port <n>`                     | `serve`                    | Overrides `PR_REVIEW_PORT`, then `3010`; accepts 1–65535                                                         |
-| `--agent claude\|codex`          | `serve`                    | Overrides the saved chat agent for this run                                                                      |
-| `--model <id>`                   | `serve`                    | Overrides the saved chat model for this run                                                                      |
-| `--fixture-canvas <review.json>` | `serve`                    | Development preview: uses the supplied canvas for every requested PR, with its head replaced by the live PR head |
-| `PR_REVIEW_HOST=gitlab`          | Environment                | Treats a non-github.com origin as GitLab (self-hosted hosts whose name does not contain `gitlab`)                |
+| Option                           | Applies to                               | Default and behavior                                                                                             |
+| -------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `--repo <dir>`                   | All commands                             | Uses the current directory when omitted; resolves the repository root from there                                 |
+| `--data-dir <dir>`               | All except `install-skill` and `upgrade` | Overrides `PR_REVIEW_DATA_DIR`, then the default `<main checkout>/.pr-review`                                    |
+| `--port <n>`                     | `serve`                                  | Overrides `PR_REVIEW_PORT`, then `3010`; accepts 1–65535                                                         |
+| `--agent claude\|codex`          | `serve`                                  | Overrides the saved chat agent for this run                                                                      |
+| `--model <id>`                   | `serve`                                  | Overrides the saved chat model for this run                                                                      |
+| `--fixture-canvas <review.json>` | `serve`                                  | Development preview: uses the supplied canvas for every requested PR, with its head replaced by the live PR head |
+| `PR_REVIEW_HOST=gitlab`          | Environment                              | Treats a non-github.com origin as GitLab (self-hosted hosts whose name does not contain `gitlab`)                |
 
 Repository operations require an `origin` remote on **github.com** or **GitLab** (gitlab.com, a
 hostname that contains `gitlab`, or any host with `PR_REVIEW_HOST=gitlab`). GitHub Enterprise Server
@@ -91,7 +91,9 @@ pr-review prepare --base origin/main --head HEAD
 ```
 
 `validate` checks the supplied file against the context in `--canvas`. By default it returns
-`{ ok, errors }`; `--human` prints readable diagnostics. `--fix` edits overlong titles by removing
+`{ ok, errors }`; `--human` prints readable diagnostics. A `review.json` is checked for
+correctness only. The folding rules (`FOLD_MISSING`, a test file collapsed at `light`) apply only
+to a `model.json`, because older canvases predate them. `--fix` edits overlong titles by removing
 the explanation after the first `:` or `—` and reports the changes. Titles that still exceed the
 limit and overlong prose require rewriting.
 
@@ -188,14 +190,45 @@ Each installed `SKILL.md` records `metadata.body-sha256` in its YAML frontmatter
 covers the body after the closing frontmatter delimiter, with CRLF normalized to LF. `doctor`
 compares the recorded hash and actual body against the skill bundled with the running CLI. Any
 outdated or modified copy in `.claude/skills` or `.agents/skills` fails the skill check, even if the
-other copy is current. Refresh copies with `pr-review install-skill` (repeat any custom directory
-flags used during installation). Automatic discovery checks the two default directories.
+other copy is current. Refresh copies with `pr-review upgrade` or `pr-review install-skill` (repeat
+any custom directory flags used during installation). Automatic discovery checks the two default directories.
 
 `serve` runs this skill check automatically and prints failures with a repair hint to stderr.
 Warnings do not prevent the server from starting. Use `doctor --all-checks` for full diagnostics.
 The `.gitignore` update always applies to the selected repository root, even with custom skill
 directories.
 
+### Upgrade options
+
+```text
+pr-review upgrade [--yes] [--only package,acpx,skill] [--repo <dir>]
+```
+
+`upgrade` checks three things, prints a plan to stderr, and asks `Proceed? [y/N]`:
+
+| What              | When it changes                                                             | How                                                        |
+| ----------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| pr-review         | npm has a newer version, and this copy is the global npm install            | `npm install -g @vintasoftware/pr-review-canvas@<version>` |
+| acpx              | npm has a newer version, and the acpx on PATH is the global npm install     | `npm install -g acpx@<version>`                            |
+| The project skill | A copy in `.claude/skills` or `.agents/skills` differs from the bundled one | The same copy `install-skill` makes                        |
+
+When pr-review itself upgrades, the skill step covers every copy, since the new version may ship
+a new skill. After installing, it runs the new version as `pr-review upgrade --yes --only <kinds>`
+with the confirmed steps, so the new version copies its own skill and takes only the steps the plan
+showed. If the install fails, the current version runs the remaining steps itself.
+
+- `--only` limits the run to the named kinds. Skipped kinds are listed in `notes`.
+- `upgrade` does not install a missing acpx or add a missing skill copy. It prints the command
+  that does.
+- An unmanaged skill directory is left alone; replace it with `install-skill --force`.
+- A pr-review run from a clone or through `npx` is left alone, with a note to update it the way it
+  was installed.
+
+Without a terminal, `upgrade` prints the plan and changes nothing. `--yes` applies it without
+asking. stdout is one JSON line with `applied` and, after applying, `ok` and each step's `status`
+(`done` or `failed`, with a `detail`). The exit code is `1` when a step fails. When a skill copy
+changes, stderr says to commit and push it.
+
 ### Output and exit codes
 
 One-shot commands normally print a JSON result on stdout. Preparation progress goes to stderr.
@@ -224,21 +257,22 @@ Lists you supply replace their defaults.
 Path patterns match repository-relative paths. `**` crosses directories; `*` and `?` match
 within one path segment.
 
-| Key                             | Default                                             | Details                                                                                                                                                                                                                    |
-| ------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `version`                       | `1`                                                 | The only supported configuration version                                                                                                                                                                                   |
-| `rulebook`                      | Unset                                               | Path to a Markdown file of project code standards, resolved from the repository root; these standards take precedence over bundled standards                                                                               |
-| `layers`                        | `[]`                                                | Optional review guidance; each entry has `id`, `title`, `description`, and optional `paths` patterns. The agent may combine, split, or reorder groups. When omitted or empty, it chooses semantic sections from the change |
-| `highRisk`                      | `[]`                                                | Entries with a `pattern` glob and `label`; matching changes receive risk labels and cannot go in the Other layer                                                                                                           |
-| `generation.mode`               | `strict`                                            | See [generation modes](#generation-modes)                                                                                                                                                                                  |
-| `generation.maxRepairRounds`    | `3`                                                 | Failed validation rounds allowed by the generation skill                                                                                                                                                                   |
-| `generation.inlineDiffMaxLines` | `1500`                                              | Maximum diff length to include directly in the generation prompt                                                                                                                                                           |
-| `generation.smallPrHunks`       | `10`                                                | At or below this hunk count, the prompt asks for one layer unless concerns differ                                                                                                                                          |
-| `generation.caps`               | See below                                           | Overrides individual text limits                                                                                                                                                                                           |
-| `tests.patterns`                | `['**/*.test.*', '**/*.spec.*', '**/__tests__/**']` | Paths treated as tests for review ordering and labels                                                                                                                                                                      |
-| `chat.enabled`                  | `true`                                              | Set to `false` to disable AI Chat                                                                                                                                                                                          |
-| `canvas.keepForIdenticalDiff`   | `true`                                              | Keep the canvas current for a later head whose diff is identical to the canvas's; see [outdated canvases](#outdated-canvases). Set to `false` to mark it outdated on every commit                                          |
-| `prompts`                       | Bundled templates                                   | See [prompt templates](#prompt-templates) for supported keys and behavior                                                                                                                                                  |
+| Key                             | Default                                                                     | Details                                                                                                                                                                                                                    |
+| ------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `version`                       | `1`                                                                         | The only supported configuration version                                                                                                                                                                                   |
+| `rulebook`                      | Unset                                                                       | Path to a Markdown file of project code standards, resolved from the repository root; these standards take precedence over bundled standards                                                                               |
+| `layers`                        | `[]`                                                                        | Optional review guidance; each entry has `id`, `title`, `description`, and optional `paths` patterns. The agent may combine, split, or reorder groups. When omitted or empty, it chooses semantic sections from the change |
+| `highRisk`                      | `[]`                                                                        | Entries with a `pattern` glob and `label`; matching changes receive risk labels and cannot go in the Other layer                                                                                                           |
+| `generation.mode`               | `strict`                                                                    | See [generation modes](#generation-modes)                                                                                                                                                                                  |
+| `generation.maxRepairRounds`    | `3`                                                                         | Failed validation rounds allowed by the generation skill                                                                                                                                                                   |
+| `generation.inlineDiffMaxLines` | `1500`                                                                      | Maximum diff length to include directly in the generation prompt                                                                                                                                                           |
+| `generation.smallPrHunks`       | `10`                                                                        | At or below this hunk count, the prompt asks for one layer unless concerns differ                                                                                                                                          |
+| `generation.caps`               | See below                                                                   | Overrides individual text limits                                                                                                                                                                                           |
+| `tests.patterns`                | Test directories and file-name shapes across stacks; see the example config | Paths treated as tests for review ordering, labels, and the light reading level                                                                                                                                            |
+| `chat.enabled`                  | `true`                                                                      | Set to `false` to disable AI Chat                                                                                                                                                                                          |
+| `canvas.keepForIdenticalDiff`   | `true`                                                                      | Keep the canvas current for a later head whose diff is identical to the canvas's; see [outdated canvases](#outdated-canvases). Set to `false` to mark it outdated on every commit                                          |
+| `canvas.incremental`            | `true`                                                                      | Regenerate a canvas for a new head by updating the newest canvas of a commit the head was built on; see [incremental canvases](#incremental-canvases). Set to `false` to generate every canvas from a blank page           |
+| `prompts`                       | Bundled templates                                                           | See [prompt templates](#prompt-templates) for supported keys and behavior                                                                                                                                                  |
 
 Generation's numeric options and text caps must be positive integers. An empty `layers` list
 provides no suggested groups; an empty `tests.patterns` list recognizes no files as tests.
@@ -259,14 +293,18 @@ affects canvas generation; chat answers the reviewer's selected question.
 
 The `prompts` map in `pr-review.config.yml` accepts these keys:
 
-| Key                       | Purpose                               |
-| ------------------------- | ------------------------------------- |
-| `generation-format.md`    | Schema and output rules               |
-| `generation-strict.md`    | Instructions for strict mode          |
-| `generation-surfacing.md` | Instructions for surfacing mode       |
-| `quality-standards.md`    | Bundled code standards                |
-| `layering-guidance.md`    | Guidance for grouping related changes |
-| `chat-seed.md`            | Opening AI Chat instructions          |
+| Key                                   | Purpose                                                     |
+| ------------------------------------- | ----------------------------------------------------------- |
+| `generation-format.md`                | Schema and output rules                                     |
+| `generation-strict.md`                | Instructions for strict mode                                |
+| `generation-surfacing.md`             | Instructions for surfacing mode                             |
+| `generation-strict-incremental.md`    | Strict mode, updating an existing canvas                    |
+| `generation-surfacing-incremental.md` | Surfacing mode, updating an existing canvas                 |
+| `judging-strict.md`                   | Strict mode's judging rules, shared by both of its tasks    |
+| `judging-surfacing.md`                | Surfacing mode's judging rules, shared by both of its tasks |
+| `quality-standards.md`                | Bundled code standards                                      |
+| `layering-guidance.md`                | Guidance for grouping related changes                       |
+| `chat-seed.md`                        | Opening AI Chat instructions                                |
 
 Each configured file replaces a whole template. Paths resolve from the project root,
 including when running from a subdirectory or using `--repo`. Absolute paths work for
@@ -324,19 +362,54 @@ placed in Other while its source is in a regular layer.
 
 The data directory's `settings.yml` accepts these keys and values:
 
-| Key              | Default    | Accepted values                                  |
-| ---------------- | ---------- | ------------------------------------------------ |
-| `version`        | `1`        | `1`                                              |
-| `skin`           | `terminal` | `terminal`, `github`                             |
-| `theme`          | `auto`     | `auto`, `light`, `dark`                          |
-| `agent`          | `claude`   | `claude`, `codex`                                |
-| `model`          | `null`     | A model ID, or `null` for the agent's default    |
-| `chatTimeoutSec` | `600`      | Integer seconds, 30–3600                         |
-| `maxTurns`       | `null`     | Integer 1–100, or `null` for the agent's default |
+| Key              | Default  | Accepted values                                   |
+| ---------------- | -------- | ------------------------------------------------- |
+| `version`        | `1`      | `1`                                               |
+| `skin`           | `github` | `terminal`, `github`                              |
+| `theme`          | `auto`   | `auto`, `light`, `dark`                           |
+| `foldLevel`      | `light`  | `light`, `moderate`, `aggressive`                 |
+| `agent`          | `claude` | `claude`, `codex`                                 |
+| `model`          | `null`   | A model ID, or `null` for the agent's default (1) |
+| `chatTimeoutSec` | `600`    | Integer seconds, 30–3600                          |
+| `maxTurns`       | `null`   | Integer 1–100, or `null` for the agent's default  |
+
+(1) A model ID names a family; see [Model families](#model-families).
 
 Invalid settings fall back to defaults. URL parameters `?skin=github&theme=light` can override
 appearance for one page load without saving it.
 
+#### Model families
+
+Each chat turn runs the newest model of the saved model's family. A trailing `[...]`, such as
+`[1m]` or `[high]`, is kept.
+
+- **Claude:** an Anthropic model ID becomes its family alias, which the `claude` CLI resolves to
+  its newest model. `claude-opus-4-8[1m]` runs as `opus[1m]`, and `claude-haiku-4-5-20251001` runs
+  as `haiku`.
+- **Codex:** a GPT model follows the `upgrade` links in the Codex model catalog
+  (`codex debug models`) to the model that replaced it, even under a new name: `gpt-5.6-terra` runs
+  as `gpt-6-sol`. A model with no `upgrade` link runs as saved.
+- **Blank model:** the agent's default applies. A thread still on a replaced model moves to its
+  replacement.
+
+To pin an exact version, prefix the ID with `pin:`. The ID is then sent as written, for either
+agent:
+
+| Agent  | Example                   | Runs                       |
+| ------ | ------------------------- | -------------------------- |
+| Claude | `pin:claude-opus-4-8`     | Opus 4.8                   |
+| Codex  | `pin:gpt-5.6-terra[high]` | GPT-5.6 Terra, high effort |
+
+The agent must still offer the model. Claude Code refuses some combinations, for example
+`claude-opus-4-8[1m]`, and the turn fails with the agent's error.
+
+Bedrock and Vertex Claude IDs, such as `us.anthropic.claude-opus-4-8-v1:0` or
+`claude-opus-4-8@20260801`, run as written without `pin:`. They work only when Claude Code is set
+up for that provider, for example with `CLAUDE_CODE_USE_BEDROCK=1` or `CLAUDE_CODE_USE_VERTEX=1`.
+
+Claude chat runs the `claude` CLI on PATH, or the Claude Code bundled with acpx when there is none.
+To use another binary, set `CLAUDE_CODE_EXECUTABLE` before `pr-review serve`.
+
 By default, Git worktrees of the same clone share the main checkout's data directory. Separate
 clones have separate data. An explicit data-directory override also relocates `settings.yml`,
 canvases, review progress, and chat history.
@@ -370,6 +443,47 @@ start collapsed. Click the summary to expand them. Moves are detected within a f
 between files appear as deletions and additions. Edited moves keep their changed text visible.
 Collapsing content does not mark it reviewed.
 
+### Reading levels
+
+The **Hide code** control, beside the review progress, sets how much of the canvas is hidden. The
+levels nest: whatever `light` hides, `moderate` and `aggressive` hide too. The generator gives each
+fold and each collapsed file the lowest level at which it hides.
+
+| Level        | What it hides                                                                            |
+| ------------ | ---------------------------------------------------------------------------------------- |
+| `light`      | Imports, whitespace, moves, and wholly generated files (the default)                     |
+| `moderate`   | Also test bodies under their titles, helpers, adapters, boilerplate, mappings and wiring |
+| `aggressive` | Also any block its title explains, so the change reads as pseudo-code                    |
+
+The control shows what the chosen level hides and how many lines that is. Each layer shows its count
+in its Files heading, and the sign-off dialog records the total.
+
+The page opens at `foldLevel` from `settings.yml` (`light` by default), which the **Hide code by
+default** field in the settings dialog sets. The control and the `f` key change the level for the
+current page only. Changing the level redraws the visible diffs and re-applies file collapse,
+including cards opened by hand.
+
+These always stay visible:
+
+- Attention points, comment threads, and pending review drafts. A file with a thread or a draft
+  folds nothing.
+- Files with an annotation or an attention point. They never collapse whole.
+- Annotations, except under an `aggressive` fold that covers the whole annotation and no other. That
+  fold shows the annotation's text instead of its title.
+- Test files at `light`, except snapshots and fixtures. From `moderate`, each test body folds under
+  its own title, or the file collapses whole.
+
+Validation fails with `FOLD_MISSING` when the generator hides too little:
+
+- A file with more than 20 changed lines outside its annotations and no attention point hides
+  nothing at any level.
+- An open file over 60 lines folds less than half of its lines outside attention points by
+  `aggressive`. Annotated lines count, since an aggressive fold may hide them.
+- A layer over 100 changed lines leaves more than 20 lines open at `moderate` (outside attention
+  points) and hides nothing more at `aggressive`. Smaller layers only need to pass the file rules.
+
+A `light` fold may cover at most 40 lines of generated content.
+
 Files with patches longer than 2,000 lines wait behind **show diff**. A link into the file opens
 it automatically.
 
@@ -393,13 +507,56 @@ zone or `pr-review import <zip> --pr <n>`.
 
 You can post inline comments, replies, PR-level comments, and attention points. Inline comments
 must target lines in the diff. Posting uses your `gh` or `glab` account and remains subject to its
-repository permissions. On GitLab, **request changes** posts the review body as a merge request
-note; **approve** calls GitLab's approve API.
-
-The sign-off dialog previews an editable review body summarizing reviewed layers, dismissed
-attention points, and comments posted from the canvas. Approval requires every layer except
-**Other changes** to be reviewed for the current head. Requesting changes does not require that
-completion. If the head moves before submission, reload and review the current commit.
+repository permissions.
+
+Click a line number to comment on one line. Shift-click a second line number, or drag across a
+range, to select several lines: the comment then covers the whole range, and posts as a multi-line
+comment (`start_line` on GitHub, a `line_range` position on GitLab). A range must stay inside one
+chunk of the diff.
+
+### Pending reviews
+
+A pending review holds comments on your machine until you submit them together.
+
+- **post to github** on a diff-line comment posts it at once. **start a review** adds it to a new
+  pending review instead.
+- While a review is open, a diff-line comment can only **add review comment**, so no comment
+  publishes ahead of the review. Replies and pull-request comments are not part of a forge review,
+  so they still post at once.
+- An attention point keeps both **post to github** and **add to review**, since its text is written
+  in advance. A point in the review shows **in your review**; edit or remove it as the draft on its
+  line. After submission, the point shows the comment it became.
+- A bar under the progress line shows how many drafts are waiting. Each draft appears on its line
+  with a **pending** badge and edit and delete commands. Drafts are saved in the local review state
+  and survive a reload. **discard** drops the whole review; nothing was sent to the forge.
+- Drafts from an earlier commit are listed separately in the bar with their original location and
+  commit. They are submitted only when the stored diff is identical to the current one and
+  `canvas.keepForIdenticalDiff` is on. Otherwise, copy the text, delete the draft, and comment on
+  the current code.
+- A draft added or edited during submission stays pending.
+
+**finish your review** opens the sign-off dialog, which shows how many drafts go out with the
+review:
+
+- **GitHub:** the drafts are the comments of the single call that creates the review.
+- **GitLab:** the inline comments and summary are staged as draft notes and published in one batch.
+  Finish or discard any review already pending in GitLab first. Approval is a separate call; if it
+  fails after publication, the comments stay published and the page asks you to approve in GitLab.
+
+A refused submission keeps the local drafts and removes the remote drafts that attempt staged.
+
+### Sign-off
+
+Sign-off offers three verdicts: **approve**, **request changes**, and **comment**, which posts a
+review with no verdict. Each opens a
+dialog previewing an editable review body summarizing reviewed layers, dismissed attention points,
+and comments posted from the canvas, so an approval or a rejection always carries a comment.
+
+Approval requires every layer except **Other changes** to be reviewed for the current head.
+Requesting changes and a comment-only review do not require that completion. On GitLab,
+**approve** calls GitLab's approve API; **request changes** and **comment** post the review body
+as a merge request note. If the head moves before submission, reload and review the current
+commit.
 
 ### Outdated canvases
 
@@ -423,6 +580,33 @@ same rule, so the CLI never calls a canvas stale that the page shows as current.
 AI Chat also answers on an outdated canvas: it quotes the diff of the canvas's own commit, the
 one on screen.
 
+## Incremental canvases
+
+When a canvas is regenerated for a new head, `pr-review prepare` starts from the **basis canvas**:
+the newest canvas of a commit the head was built on. A canvas of a commit the head no longer
+contains is never a basis. `--force` starts from a blank page, and `canvas.incremental: false`
+turns this off for the project.
+
+`prepare` compares the basis diff with the head diff file by file. A file whose patch is
+byte-identical is untouched. The prompt tells the generator to copy, word for word:
+
+- whole layers whose files are all untouched;
+- in other layers, the notes, folds, annotations, and attention points of untouched files.
+
+Everything else is decided again. The summary and risk tags are always rewritten. A carried
+attention point keeps its kind, path, and title, so it keeps its fingerprint and any dismissal.
+
+The canvas records only which basis it came from. Your server decides which review marks follow,
+using the two canvases and your clone:
+
+- A file's mark follows when the file is in both canvases, under the same layer key, with a
+  byte-identical patch.
+- A layer's mark follows only when the layer has exactly the same files and none changed.
+
+The canvas you marked is compared directly with the one on screen, so marks survive any number of
+regenerations in between. When a mark follows, the page names the canvas you made it on. If your
+machine lacks that canvas or cannot rebuild either diff, no marks follow.
+
 ## AI Chat
 
 **Ask** on a layer, file, attention point, or line selection chooses the context for your message.
@@ -481,14 +665,15 @@ sandbox for the agent. Its access also depends on the agent's own permissions. D
 
 Validation reports name the field, file, hunk, or line to fix. Common groups are:
 
-| Codes                                                           | What to check                                                  |
-| --------------------------------------------------------------- | -------------------------------------------------------------- |
-| `SCHEMA`, `TEXT_TOO_LONG`                                       | Required fields, types, and text limits                        |
-| `HUNK_UNASSIGNED`, `HUNK_DUPLICATE`, `HUNK_UNKNOWN`             | Each known hunk belongs to exactly one layer                   |
-| `PATH_UNKNOWN`, `TEST_PATH_UNKNOWN`                             | Referenced files exist in the relevant diff or PR head         |
-| `LAYER_EMPTY`, `LAYER_KEY_DUPLICATE`                            | Layers contain hunks and have unique keys                      |
-| `OTHER_DUPLICATE`, `OTHER_NOT_LAST`, `RISK_IN_OTHER`            | At most one Other layer, last, without risk-tagged changes     |
-| `TEST_NOT_LAST`, `TEST_IN_OTHER`                                | Tests follow the code they cover and use the appropriate layer |
-| `ANNOTATION_OUTSIDE_HUNK`, `POINT_OUTSIDE_DIFF`, `FOLD_INVALID` | Locations and fold ranges fit the assigned diff                |
-| `TOO_MANY_POINTS`                                               | Count explicit points and missing-test entries together        |
-| `LINK_UNRESOLVED`, `DIAGRAM_NODE_UNKNOWN`, `DIAGRAM_LIMIT`      | Link targets, diagram node IDs, and diagram counts             |
+| Codes                                                           | What to check                                                                                                                |
+| --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `SCHEMA`, `TEXT_TOO_LONG`                                       | Required fields, types, and text limits                                                                                      |
+| `HUNK_UNASSIGNED`, `HUNK_DUPLICATE`, `HUNK_UNKNOWN`             | Each known hunk belongs to exactly one layer                                                                                 |
+| `PATH_UNKNOWN`, `TEST_PATH_UNKNOWN`                             | Referenced files exist in the relevant diff or PR head                                                                       |
+| `LAYER_EMPTY`, `LAYER_KEY_DUPLICATE`                            | Layers contain hunks and have unique keys                                                                                    |
+| `OTHER_DUPLICATE`, `OTHER_NOT_LAST`, `RISK_IN_OTHER`            | At most one Other layer, last, without risk-tagged changes                                                                   |
+| `TEST_NOT_LAST`, `TEST_IN_OTHER`                                | Tests follow the code they cover and use the appropriate layer                                                               |
+| `ANNOTATION_OUTSIDE_HUNK`, `POINT_OUTSIDE_DIFF`, `FOLD_INVALID` | Locations and fold ranges fit the assigned diff                                                                              |
+| `FOLD_MISSING`                                                  | A file over 20 unannotated lines hides something; an open file over 60 folds half; a layer over 100 hides more at aggressive |
+| `TOO_MANY_POINTS`                                               | Count explicit points and missing-test entries together                                                                      |
+| `LINK_UNRESOLVED`, `DIAGRAM_NODE_UNKNOWN`, `DIAGRAM_LIMIT`      | Link targets, diagram node IDs, and diagram counts                                                                           |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vintasoftware/pr-review-canvas",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Localhost PR review canvas: layered diffs, attention points, and GitHub or GitLab comments for one PR",
   "type": "module",
   "bin": {

package/pr-review.config.example.yml

@@ -39,11 +39,41 @@ generation:
   #   rationale: 300
   #   diagram: 1500       # mermaid source, counted raw
 
-# Which paths count as tests, for the layering rules and the `test` pill on a file card.
-# Defaults to the JavaScript and TypeScript conventions below; name your own for other languages
-# (Python: '**/test_*.py', '**/tests/**'; Go: '**/*_test.go').
+# Which paths count as tests, for the layering rules, the `test` pill on a file card, and the
+# light reading level, which keeps test titles on screen. The defaults below match test
+# directories and file-name shapes across stacks (JS/TS, Python, Go, Ruby, Java, Kotlin, PHP,
+# C#, Swift, Elixir, Dart, Rust). A list here replaces them; add `'**/spec/**'` when that
+# directory holds tests in your repository. Snapshots and fixtures inside test paths may still
+# hide at light, since they are generated.
 tests:
-  patterns: ['**/*.test.*', '**/*.spec.*', '**/__tests__/**']
+  patterns:
+    - '**/__tests__/**'
+    - '**/tests/**'
+    - '**/test/**'
+    - '**/*.test.*'
+    - '**/*.spec.*'
+    - '**/*_test.*'
+    - '**/*_spec.*'
+    - '**/test_*.py'
+    - '**/conftest.py'
+    - '**/*Test.java'
+    - '**/*Tests.java'
+    - '**/*Test.kt'
+    - '**/*Tests.kt'
+    - '**/*Test.scala'
+    - '**/*Tests.scala'
+    - '**/*Test.groovy'
+    - '**/*Tests.groovy'
+    - '**/*Test.cs'
+    - '**/*Tests.cs'
+    - '**/*Test.fs'
+    - '**/*Tests.fs'
+    - '**/*Test.vb'
+    - '**/*Tests.vb'
+    - '**/*Test.swift'
+    - '**/*Tests.swift'
+    - '**/*Test.php'
+    - '**/*Tests.php'
 
 chat:
   enabled: true # false removes the chat pane and its routes
@@ -53,3 +83,7 @@ canvas:
   # from, as after merging the base branch in. Set false to mark the canvas outdated on every new
   # commit.
   keepForIdenticalDiff: true
+  # Regenerating a canvas for a new head starts from the newest canvas of a commit the head was
+  # built on, keeping the layers, folds, notes and attention points its diff leaves untouched.
+  # Set false to generate every canvas from a blank page, as `--force` always does.
+  incremental: true