@vintasoftware/pr-review-canvas 0.3.0 → 0.5.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:
 
@@ -43,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
@@ -53,14 +85,14 @@ 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 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.
@@ -70,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
 ```
@@ -89,34 +121,46 @@ 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.
+
+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
@@ -161,6 +205,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: