@vintasoftware/pr-review-canvas 0.3.0 → 0.4.0

package/README.md

@@ -1,25 +1,42 @@
 # PR Review Canvas
 
-Review a GitHub pull request canvas: layers by topic, with grouped diffs, attention points, comments,
-and an optional AI chat. Everything runs locally at **http://localhost:3010**.
+Review a GitHub pull request or GitLab merge request canvas: layers by topic, with grouped diffs,
+attention points, comments, and an optional AI chat. Everything runs locally at **http://localhost:3010**.
 
 ## Quick start: author generates, reviewers review
 
 ### Author side
 
-Each PR author should generate a canvas and attach its zip to the **PR description** before
-requesting review. After the project setup below, run the installed skill in Claude Code or Codex:
+Each PR author generates a canvas before requesting review. The skill shares it automatically
+in a comment on the GitHub PR or GitLab MR. After the project setup below, run the installed skill in Claude Code or Codex:
 
 ```text
 /pr-review-canvas 123
 ```
 
-Replace **123** with your PR number. The skill reads the PR, generates and validates the canvas,
-then returns a local review URL and the exported zip's path. Open the URL to check the canvas.
+Replace **123** with your PR number. The skill reads the PR, generates and validates the canvas, then publishes a compressed canvas
+comment using your `gh` or `glab` login. It returns a local review URL and the comment link.
 
-The skill ends with upload instructions. If you're happy with the produced canvas, edit the PR
-description in GitHub's UI, drag the zip into the editor, wait for the upload to finish, and save.
-Uploading the zip is a manual browser step due to restrictions of GitHub's API.
+If automatic sharing fails (including a canvas too large for one comment), the skill warns you
+and gives you a ZIP path. Drag that ZIP into the PR or MR description, wait for the upload, and
+save. This manual upload is only a fallback.
+
+### Before you open the pull request
+
+To read your own change the way a reviewer will, generate a canvas for the work in your clone:
+
+```text
+/pr-review-canvas branch          # the current branch against the default branch
+/pr-review-canvas uncommitted     # the same, with your working-tree edits and new files on top
+```
+
+Start `pr-review serve` and open **http://localhost:3010/review/branch** or
+**/review/uncommitted**. The two are separate reviews, so generating one leaves the other alone.
+
+Nothing is posted anywhere: local work has no pull request, so the comment and sign-off commands
+stay off. Add `--base <ref>` to compare against another branch. Committing after `branch`, or
+editing a file after `uncommitted`, moves the head: the next time you open the page or press
+refresh, the canvas is marked outdated and the page offers to generate it again.
 
 ### Review side
 
@@ -29,13 +46,16 @@ Start the canvas server from the project you want to review:
 pr-review serve
 ```
 
-Open **http://localhost:3010**, enter a PR number, and leave the terminal running while you
-review. Stop the server with **Ctrl+C**. To use another port, run `pr-review serve --port 3011`.
+Open **http://localhost:3010**, enter a PR number (or follow a link to a local review), and
+leave the terminal running while you review. Stop the server with **Ctrl+C**. To use another port, run `pr-review serve --port 3011`.
 
 ## Install
 
-You need Node.js 22+, npm, Git, and [GitHub CLI](https://cli.github.com).
-Sign in to GitHub with `gh auth login`.
+You need Node.js 22+, npm, Git, and the CLI for your host:
+
+- GitHub: [GitHub CLI](https://cli.github.com). Sign in with `gh auth login`.
+- GitLab: [GitLab CLI (glab)](https://gitlab.com/gitlab-org/cli). Sign in with `glab auth login`.
+  Self-hosted GitLab whose hostname does not contain `gitlab` needs `PR_REVIEW_HOST=gitlab`.
 
 Install the command globally once, for use in any project:
 
@@ -57,10 +77,11 @@ Re-run `pr-review install-skill` after upgrading the CLI to refresh them. It als
 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 remote, the GitHub CLI and its login, write access to the local
-canvas directory, and whether installed skills match the current package. It prints a JSON report with a result for
-each check and suggested fixes for failures. `doctor --all-checks` also checks that `acpx` runs and
-reports its version. Exit code `0` means all checks passed.
+`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.
+It prints a JSON report with a result for each check and suggested fixes for failures.
+`doctor --all-checks` also checks that `acpx` runs and reports its version. Exit code `0` means all
+checks passed.
 
 `serve` automatically runs the skill check and warns on stderr if a skill is missing, outdated,
 or modified. The warning includes the reinstall command and does not block startup.
@@ -89,22 +110,26 @@ See the [CLI and configuration reference](docs/reference.md) for detailed option
 pr-review export --pr 123
 ```
 
-The command prints the zip's absolute path. Both `export` and `publish` save locally; neither
-uploads an attachment to GitHub.
+The command prints the zip's absolute path. `export` saves locally; `publish` also shares PR/MR
+canvases automatically as compressed comments.
 
 The zip contains `manifest.json` and `review.json`: the PR description, file/hunk metadata,
-and generated review notes. Check these before sharing, since they can contain private
-information. Each reviewer gets source diffs from their own clone; chat history stays local.
+and generated review notes. Publishing shares this information with everyone who can read the PR/MR. Each reviewer gets source diffs from their own clone; chat history stays local.
 
 ### Update an outdated canvas
 
 After pushing new commits, run `/pr-review-canvas 123` again. To rewrite a canvas for the
-same commit, run `/pr-review-canvas 123 --force`. Replace the zip in the PR description.
+same commit, run `/pr-review-canvas 123 --force`. Publishing updates your canvas comment automatically.
 Reviewers click **refresh**.
 
 When the saved canvas describes a different PR head, **Canvas is outdated** appears at
 the top. You can still read the older canvas, with its commit and distance shown; posting
-from that view is disabled. Click **refresh** to check GitHub for changes and a newer zip.
+from that view is disabled. Click **refresh** to check GitHub or GitLab for changes and a newer canvas.
+
+A head whose diff is identical to the canvas's does not outdate it: after **Update branch**
+merged `main` in without touching the changed files, for example, the canvas still applies
+and the page says so. Set `canvas.keepForIdenticalDiff: false` in the project config to treat
+every commit as a new head.
 
 ## Configuration
 
@@ -161,6 +186,10 @@ Restart the server after changing the config; chat template edits apply to new t
 See the [prompt template reference](docs/reference.md#prompt-templates) for supported keys,
 path rules, validation, and upgrades.
 
+## Website
+
+The [project website](https://vintasoftware.github.io/pr-review-canvas/) introduces the review workflow with a real PR walkthrough. See [website development and publishing](docs/website.md) for local preview commands and the GitHub Pages deployment workflow.
+
 ## Contributing
 
 In a clone of this tool, use pnpm for the shared lockfile and development checks:

package/docs/reference.md

@@ -23,9 +23,12 @@ For setup and the basic review workflow, see the [README](../README.md).
 | `--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**. GitHub Enterprise Server
-hosts are not supported. Fetching a PR does not check out its branch.
+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
+hosts are not supported. Fetching a PR or merge request does not check out its branch. Use `--pr`
+for both GitHub pull request numbers and GitLab merge request IIDs.
 
 ### Prepare, validate, and publish
 
@@ -33,7 +36,7 @@ These commands support custom generation workflows. The bundled
 [generation skill](../skills/pr-review-canvas/SKILL.md) describes the complete sequence and model rules.
 
 ```text
-pr-review prepare (--pr <n> | --base <ref> --head <ref>) [--force]
+pr-review prepare (--pr <n> | --branch | --uncommitted | --base <ref> --head <ref>) [--base <ref>] [--force]
 pr-review validate <model.json|review.json> --canvas <dir> [--human] [--fix]
 pr-review publish <canvasDir> --agent <id> [--model <id>] --harness claude-code|codex|other [--allow-stale]
 ```
@@ -43,7 +46,45 @@ A status of `exists` means that head already has a canvas. With `--force`, prepa
 previous generation's working files while keeping the published canvas available until a new
 publish succeeds.
 
-For a comparison before a PR exists, use local refs:
+### Reviewing before the pull request exists
+
+There are two reviews of the work in a clone, and they are separate targets:
+
+```bash
+pr-review prepare --branch        # served at /review/branch
+pr-review prepare --uncommitted   # served at /review/uncommitted
+```
+
+`--branch` describes the tip of the current branch. `--uncommitted` describes the working tree as
+it stands, with the edits and the untracked files on top of that tip; with a clean tree the two
+build the same canvas. Each keeps its own canvas, review progress and chat threads, so preparing
+one never disturbs the other.
+
+- **Base.** Both compare against the repository's default branch, resolved from `origin/HEAD` and
+  falling back to `origin/main`, `origin/master`, `main`, then `master`. `--base <ref>` overrides
+  it. Preparation fails with a hint when none of them resolve.
+- **Uncommitted work.** `--uncommitted` stages the working tree into an index of its own and
+  writes a commit from it, so the diff covers files that are not committed yet. Nothing the user
+  staged is touched, ignored files stay out, and the commit is anchored at
+  `refs/worktree/pr-review-snapshot` so `git gc` cannot collect it before `publish`. Publishing
+  gives that canvas an anchor of its own under `refs/worktree/pr-review-canvas/`, so a later
+  snapshot cannot leave it collectable. The same working tree always hashes to the same commit.
+- **Staleness.** Committing after `--branch`, or editing a file after `--uncommitted`, moves the
+  head, so `publish` answers `CANVAS_STALE`, exactly as a push does for a pull request. The page
+  reads the head again when it is opened and when `refresh` is pressed, and offers to regenerate.
+  Its background polls answer about that same head, so they never contradict what the page shows;
+  they read the work again only once a new canvas has been prepared.
+- **Worktrees.** The snapshot index and its anchor are per worktree, so two worktrees of one clone
+  never overwrite each other's snapshot. The review targets are not: `branch` and `uncommitted`
+  name one review per clone, so worktrees share their canvas, review progress and chat threads.
+  Review local work from one worktree at a time.
+- **No forge side.** A local canvas posts nothing: comments, sign-off, canvas import, and
+  attachment discovery are refused for it. The page draws no import drop zone and no shared-canvas
+  callout, and the comment and sign-off commands stay disabled with the reason. A canvas of a working-tree
+  snapshot is never offered as a pull request's canvas, or as the branch review's, because its
+  commit is on no branch.
+
+For a comparison between two commits that both exist, name them instead:
 
 ```bash
 pr-review prepare --base origin/main --head HEAD
@@ -54,7 +95,8 @@ pr-review prepare --base origin/main --head HEAD
 the explanation after the first `:` or `—` and reports the changes. Titles that still exceed the
 limit and overlong prose require rewriting.
 
-`publish` returns `status`, `headSha`, `reviewJsonPath`, `attempts`, and a `reviewUrl` for PR runs.
+`publish` returns `status`, `headSha`, `reviewJsonPath`, `attempts`, `sharing`, and a `reviewUrl`
+for PR and local runs.
 Its `--agent`, `--model`, and `--harness` describe who generated the canvas; they do not launch or
 select an agent. `--allow-stale` permits publishing for the prepared commit after the PR head has
 moved. Use it only when that older commit is the intended review target.
@@ -63,6 +105,35 @@ For more than 400 changed files or 50,000 added/deleted lines, preparation leave
 prompt and directs the generator to read patch files individually. Smaller diffs are inlined up
 to `generation.inlineDiffMaxLines`.
 
+### Automatic sharing and ZIP fallback
+
+For PR/MR targets, `publish` saves the validated canvas locally, then posts its compressed ZIP
+as base64 inside a hidden HTML comment on GitHub or GitLab. The visible comment identifies the
+commit and explains how to open the canvas. Publishing again updates the existing canvas comment
+owned by the current CLI account; another author's comment is left alone. The payload contains
+the same `manifest.json` and `review.json` as an export, including the PR/MR description and review
+notes. Hidden markup is not private: anyone who can read the comment can retrieve the payload.
+No generated files enter Git history and no storage service or CI workflow is required.
+
+Check the `sharing` result even when the process exits successfully:
+
+- `{ "status": "shared", "url": "..." }`: the host accepted the comment.
+- `{ "status": "failed", "warning": "...", "zipPath": "..." }`: the canvas is saved locally,
+  but automatic sharing failed. The CLI also prints a warning to stderr and exports a fallback ZIP.
+  Upload that ZIP into the PR/MR description in the browser and save; replace an older attachment
+  link if present. A host failure can have an uncertain outcome, so check the comment before retrying.
+- `{ "status": "local" }`: a refs-only target has no PR/MR to publish to.
+
+The entire comment must fit the host limit: 65,536 characters on GitHub and 1,000,000 on GitLab.
+Base64 uses roughly four characters per three compressed bytes, leaving slightly under 48 KiB
+for a GitHub ZIP after the envelope and visible text. Oversize canvases are never split or truncated.
+Permission, login, network, and host-policy errors use the same ZIP fallback. A sharing failure
+keeps exit code 0 because local publication succeeded; validation errors still exit 5.
+The generation skill must report the warning and manual-upload instructions on sharing failure.
+
+`export` remains a local-only command for backups and manual sharing. For refs-only canvases,
+export with `--head <sha> --pr <n>` once the PR exists, or regenerate for the PR to share automatically.
+
 ### Export and import options
 
 ```text
@@ -79,16 +150,21 @@ pr-review import <zip> [--pr <n>] [--force]
   canvas generation time in UTC, to seconds, so exports sort chronologically within each PR.
   Before a PR exists, `ref-` replaces `pr-<number>-`. Re-exporting the same canvas keeps its name.
 - Export returns `status`, `path`, `name`, `headSha`, and `prNumber` when supplied or stored.
-- `import --pr` compares the imported canvas with that PR's current head. Without it, import does
-  not check against a live PR.
+- `import --pr` compares the imported canvas with that PR's current head, and refuses a canvas
+  exported for a different pull request with `CANVAS_PR_MISMATCH`. `--force` does not lift that
+  refusal: a canvas is stored under the pull request it names, so importing the same ZIP without
+  `--pr` stores it under its own PR instead. Without `--pr`, import does not check against a live
+  PR. A canvas generated before the PR existed names none and joins the pull request it is
+  imported for.
 - Import returns `ready`, `stale`, or `exists`, plus commit information and warnings. `exists`
   keeps a stored canvas generated at the same time or later. `derivable: false` means the canvas
   was accepted but its source diffs could not be rebuilt from Git.
 - `import --force` allows a canvas from another repository. It does not force an older canvas to
-  replace a newer one.
+  replace a newer one, and does not allow a canvas of another pull request.
 
 Imports accept archives up to **20 MiB**. The required `manifest.json` and `review.json` entries
-must be at the archive root and pass format validation. If the necessary commits are missing,
+must be at the archive root, pass format validation, and agree on the commit and the pull request
+they describe. If the necessary commits are missing,
 the tool attempts to fetch them; a failed fetch can leave the notes available without diffs.
 
 ### Skill installation options
@@ -134,7 +210,7 @@ Validation failures from `validate` use its report format instead.
 | `0`       | Success                                                                  |
 | `1`       | Error, including a failed `doctor` check                                 |
 | `2`       | Command usage error, such as an unknown command or missing required flag |
-| `4`       | GitHub CLI missing or unauthenticated                                    |
+| `4`       | GitHub CLI (`gh`) or GitLab CLI (`glab`) missing or unauthenticated      |
 | `5`       | Validation failed in `validate` or `publish`                             |
 
 `doctor` reports failed checks with exit `1`, including authentication failures.
@@ -161,6 +237,7 @@ within one path segment.
 | `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                                                                                                                                                  |
 
 Generation's numeric options and text caps must be positive integers. An empty `layers` list
@@ -264,8 +341,8 @@ By default, Git worktrees of the same clone share the main checkout's data direc
 clones have separate data. An explicit data-directory override also relocates `settings.yml`,
 canvases, review progress, and chat history.
 
-The data directory contains exported archives, saved canvases, generation inputs, cached GitHub
-data, source diffs, and personal review progress. Its own `.gitignore` excludes its contents.
+The data directory contains exported archives, saved canvases, generation inputs, cached GitHub or
+GitLab data, source diffs, and personal review progress. Its own `.gitignore` excludes its contents.
 Deleting the directory loses saved preferences, canvases, progress, and chat history.
 
 ## Review controls
@@ -298,32 +375,61 @@ it automatically.
 
 ### Finding shared canvases
 
-Discovery checks the PR description and comments for canvas ZIP links. It prefers a filename
+Discovery reads compressed canvas comments and checks the PR description and comments for legacy
+canvas ZIP links. Both use the same ZIP validation and import path. It prefers a filename
 matching the current head, then the PR number, then the most recently edited source text.
-If a download fails, it tries other matching attachments. Keep the exported filename so the
-canvas can be recognized.
+If a candidate fails, it tries other matching canvases. Keep the exported filename so the
+canvas can be recognized. **Refresh** also checks for regenerated canvases at the same head commit.
+
+An attachment exported for a different pull request is reported rather than imported, and is not
+downloaded at all when its filename already names the other PR. The page says so and offers the
+drop zone, which applies the same check: a ZIP whose name or manifest belongs to another PR is
+refused.
 
-When automatic download fails, download the archive in GitHub's UI and use the page's drop zone
-or `pr-review import <zip> --pr <n>`.
+When automatic download fails, download the archive in GitHub or GitLab and use the page's drop
+zone or `pr-review import <zip> --pr <n>`.
 
 ### Comments and sign-off
 
 You can post inline comments, replies, PR-level comments, and attention points. Inline comments
-must target lines in the diff. Posting uses your GitHub CLI account and remains subject to its
-repository permissions.
+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.
 
+### Outdated canvases
+
+A canvas describes one head commit. When the pull request moves to another commit, the page
+shows **Canvas is outdated**, offers the older canvas read-only, and disables posting from it.
+
+An identical diff is the exception. When the head's diff against its merge base is the same as
+the canvas commit's diff against its own, file by file and byte for byte, the canvas is carried
+over: the page shows it under a **Canvas still applies** note, review progress carries over, and
+sign-off, comments, and AI Chat keep working. The note says how many commits later the head is,
+when the head was built on the canvas's commit. Merging the base branch in (**Update branch**) keeps
+the diff identical as long as the base did not touch the changed files. The rule does not care how
+the head reached that diff, only that it did; a diff that differs anywhere, even a hunk moved down
+by a base change, marks the canvas outdated as before, because the canvas's layers, hunk ids, and
+attention points describe the diff it was generated from. It needs `canvas.keepForIdenticalDiff`
+(the default) and both commits in the local clone: the canvas's own commit has to be there for its
+diff to be rebuilt, and without that diff there is nothing to compare, so the canvas reads outdated.
+Two empty change sets are not compared either. `pr-review publish` and `pr-review import` apply the
+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.
+
 ## AI Chat
 
 **Ask** on a layer, file, attention point, or line selection chooses the context for your message.
 Choosing another target replaces it; **clear** returns to the whole PR. The `a` key asks about
 the focused target, and `/` focuses the message box.
 
-Chat can propose an inline GitHub comment. A valid proposal appears with controls to post, edit,
+Chat can propose an inline comment. A valid proposal appears with controls to post, edit,
 or copy it. A proposal outside the current diff remains text with an explanation.
 
 Use **stop** to interrupt a reply. Only one chat turn can run per PR at a time. A timeout or
@@ -332,9 +438,10 @@ incomplete answer can be retried; increase `chatTimeoutSec` if replies need more
 ## Network access and permissions
 
 The server binds to `127.0.0.1` and rejects browser writes from other origins. It is intended for
-local use with your GitHub login.
+local use with your GitHub or GitLab login.
 
-GitHub requests fetch PR data and attachments and submit the comments or reviews you choose to
+Publishing sends the canvas as a PR/MR comment. Host requests also fetch PR or MR data and
+attachments and submit the comments or reviews you choose to
 post. Rendered Markdown can load images from HTTPS hosts. Generation and chat send review
 context to the selected coding agent and its configured provider.
 
@@ -344,28 +451,31 @@ sandbox for the agent. Its access also depends on the agent's own permissions. D
 
 ## Troubleshooting
 
-| Symptom or code                      | Next step                                                                                                                                |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `NOT_A_REPO`                         | Run inside a Git clone or pass `--repo <dir>`                                                                                            |
-| `NO_ORIGIN`                          | Check that `origin` points to a repository on github.com                                                                                 |
-| `GH_MISSING` / `GH_UNAUTHENTICATED`  | Install [GitHub CLI](https://cli.github.com), run `gh auth login`, and check authentication in the same environment that runs the server |
-| `GITHUB_API_ERROR`                   | Read the underlying error for permissions, rate limits, connectivity, or GitHub service problems                                         |
-| `PR_NOT_FOUND`                       | Check the PR number, repository, and your access                                                                                         |
-| `CANVAS_NOT_FOUND`                   | Generate or import a canvas for the requested commit                                                                                     |
-| `CANVAS_INVALID`                     | Read the format errors; re-export or regenerate the canvas                                                                               |
-| `CANVAS_REPO_MISMATCH`               | Check which clone is open; use `import --force` only when importing from the other repository is intentional                             |
-| `CANVAS_TOO_LARGE`                   | The archive exceeds the 20 MiB import limit                                                                                              |
-| `CANVAS_STALE`                       | The PR head moved; prepare again for the current commit                                                                                  |
-| `MODEL_INVALID`                      | Fix the reported problems in `model.json`, validate, then publish again                                                                  |
-| `SKILL_DIR_EXISTS`                   | The destination contains a customized directory; preserve it elsewhere before replacing it with `--force`                                |
-| `CHAT_BUSY`                          | Wait for the running reply or press **stop**                                                                                             |
-| `AGENT_AUTH_REQUIRED`                | Sign in through the selected agent's CLI, then retry                                                                                     |
-| `AGENT_MISSING` or missing chat pane | Check `chat.enabled` and confirm the server can find `acpx` and the selected agent; run `pr-review doctor --all-checks`                  |
-| `AGENT_INCOMPLETE`                   | Retry the message or increase the chat timeout                                                                                           |
-| `COMMENT_FORBIDDEN`                  | Check the GitHub account's repository access and token permissions                                                                       |
-| `COMMENT_LINE_NOT_IN_DIFF`           | Choose a line shown in the current diff                                                                                                  |
-| `SIGNOFF_INCOMPLETE`                 | Mark every layer except Other reviewed for this head                                                                                     |
-| `FORBIDDEN_HOST` / `CROSS_ORIGIN`    | Open the local server using `localhost` or `127.0.0.1` and submit actions from that page                                                 |
+| Symptom or code                         | Next step                                                                                                                                             |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `NOT_A_REPO`                            | Run inside a Git clone or pass `--repo <dir>`                                                                                                         |
+| `NO_ORIGIN`                             | Check that `origin` points to github.com or GitLab; for self-hosted GitLab set `PR_REVIEW_HOST=gitlab`                                                |
+| `GH_MISSING` / `GH_UNAUTHENTICATED`     | Install [GitHub CLI](https://cli.github.com), run `gh auth login`, and check authentication in the same environment that runs the server              |
+| `GITHUB_API_ERROR`                      | Read the underlying error for permissions, rate limits, connectivity, or GitHub service problems                                                      |
+| `GLAB_MISSING` / `GLAB_UNAUTHENTICATED` | Install [GitLab CLI](https://gitlab.com/gitlab-org/cli), run `glab auth login`, and check authentication in the same environment that runs the server |
+| `GITLAB_API_ERROR`                      | Read the underlying error for permissions, rate limits, connectivity, or GitLab service problems                                                      |
+| `PR_NOT_FOUND`                          | Check the PR number, repository, and your access                                                                                                      |
+| `CANVAS_NOT_FOUND`                      | Generate or import a canvas for the requested commit                                                                                                  |
+| `CANVAS_INVALID`                        | Read the format errors; re-export or regenerate the canvas                                                                                            |
+| `CANVAS_REPO_MISMATCH`                  | Check which clone is open; use `import --force` only when importing from the other repository is intentional                                          |
+| `CANVAS_PR_MISMATCH`                    | The ZIP was exported for another pull request; import the canvas of this PR, or import that ZIP without `--pr` to store it under its own              |
+| `CANVAS_TOO_LARGE`                      | The archive exceeds the 20 MiB import limit                                                                                                           |
+| `CANVAS_STALE`                          | The PR head moved; prepare again for the current commit                                                                                               |
+| `MODEL_INVALID`                         | Fix the reported problems in `model.json`, validate, then publish again                                                                               |
+| `SKILL_DIR_EXISTS`                      | The destination contains a customized directory; preserve it elsewhere before replacing it with `--force`                                             |
+| `CHAT_BUSY`                             | Wait for the running reply or press **stop**                                                                                                          |
+| `AGENT_AUTH_REQUIRED`                   | Sign in through the selected agent's CLI, then retry                                                                                                  |
+| `AGENT_MISSING` or missing chat pane    | Check `chat.enabled` and confirm the server can find `acpx` and the selected agent; run `pr-review doctor --all-checks`                               |
+| `AGENT_INCOMPLETE`                      | Retry the message or increase the chat timeout                                                                                                        |
+| `COMMENT_FORBIDDEN`                     | Check the GitHub or GitLab account's repository access and token permissions                                                                          |
+| `COMMENT_LINE_NOT_IN_DIFF`              | Choose a line shown in the current diff                                                                                                               |
+| `SIGNOFF_INCOMPLETE`                    | Mark every layer except Other reviewed for this head                                                                                                  |
+| `FORBIDDEN_HOST` / `CROSS_ORIGIN`       | Open the local server using `localhost` or `127.0.0.1` and submit actions from that page                                                              |
 
 ### Validation diagnostics
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vintasoftware/pr-review-canvas",
-  "version": "0.3.0",
-  "description": "Localhost PR review canvas: layered diffs, attention points, and GitHub comments for one PR",
+  "version": "0.4.0",
+  "description": "Localhost PR review canvas: layered diffs, attention points, and GitHub or GitLab comments for one PR",
   "type": "module",
   "bin": {
     "pr-review": "./bin/pr-review.mjs"
@@ -10,7 +10,7 @@
     "dev": "tsx watch --clear-screen=false --ignore '**/.pr-review/**' src/cli.ts serve",
     "start": "tsx src/cli.ts serve",
     "test": "vitest run",
-    "hooks:install": "git config core.hooksPath .githooks",
+    "hooks:install": "git config core.hooksPath \"$(git rev-parse --show-toplevel)/.githooks\"",
     "test:watch": "vitest",
     "test:browser": "playwright test",
     "coverage": "vitest run --coverage",
@@ -23,7 +23,12 @@
     "format": "oxfmt --write",
     "format:check": "oxfmt --check",
     "check": "pnpm lint && pnpm format:check && pnpm typecheck",
-    "precommit": "pnpm check && pnpm test"
+    "precommit": "pnpm check && pnpm test",
+    "site:dev": "vite --config site/vite.config.js",
+    "site:image": "node scripts/render-social-preview.mjs",
+    "site:build": "vite build --config site/vite.config.js",
+    "site:preview": "vite preview --config site/vite.config.js",
+    "site:test": "playwright test --config site/playwright.config.js"
   },
   "dependencies": {
     "@highlightjs/cdn-assets": "^11.12.0",

package/pr-review.config.example.yml

@@ -47,3 +47,9 @@ tests:
 
 chat:
   enabled: true # false removes the chat pane and its routes
+
+canvas:
+  # A canvas stays current for a later head whose diff is identical to the one it was generated
+  # from, as after merging the base branch in. Set false to mark the canvas outdated on every new
+  # commit.
+  keepForIdenticalDiff: true

package/prompts/chat-seed.md

@@ -11,6 +11,9 @@ At most six sentences. No headings unless the reader asks for more. Markdown is
 short lists, `path:line` references. Do not restate the question. Do not summarize the whole PR
 when the reader asked about one file.
 
+Call diff sections **chunks** in answers and proposed comments. Keep code identifiers and
+`#hunk:` link targets unchanged.
+
 ## Answer protocol
 
 For any "is this fine / covered / needed / safe?" question, the verdict comes first, in one of

package/prompts/generation-format.md

@@ -39,6 +39,9 @@ hunk in that file's patch.
 
 ## Layering rules
 
+In reader-facing prose, call diff sections **chunks**. Keep the schema field `hunks` and
+`#hunk:` link targets exactly as specified.
+
 Project-configured layers (optional guidance):
 
 {{CONFIGURED_LAYERS}}