@erclx/canon 5.78.0 → 5.79.0

package/claude/skills/git-ship/references/ci-watch.md

@@ -5,7 +5,7 @@ description: What the git-ship CI watch does when the installed CLI predates the
 
 # CI watch fallback and refusals
 
-Applies to step 9 of `git-ship` once the watch wakes on anything but a `state` of `passing` or `failing` or a `conflicted: true` record, and to a target whose CLI carries no `canon pr checks`.
+Applies to step 9 of `git-ship` once the watch wakes on anything but a `state` of `passing` or `failing` or a `conflicted: true` record, to a `failing` record whose failed runs were all cancelled, and to a target whose CLI carries no `canon pr checks`.
 
 ## The fallback watch
 
@@ -23,9 +23,33 @@ Empty output stops rather than waits, since `no checks reported on the '<branch>
 
 ## Refused and unsettled reads
 
-Neither of these is a pass, and neither emits `✅ Shipped`.
+None of these is a pass, and none emits `✅ Shipped`. A `reason` and no `state` means the read was refused, and the watch sorts refusals into two kinds.
 
-- A `reason` and no `state` means the read was refused, such as `no-remote-branch` for a branch deleted on the remote. Stop and report that `reason`.
-- A watch that hit its timeout and printed no final record is CI unsettled after 60 minutes, so report it that way
+| Kind      | Reasons                                                      | What the watch did                                               |
+| --------- | ------------------------------------------------------------ | ---------------------------------------------------------------- |
+| Permanent | `no-remote-branch`, `ambiguous-pull`, `no-branch`            | Exited on the first one, since no amount of waiting changes them |
+| Transient | Every other reason, such as `gh-failed` or `runs-unreadable` | Kept polling, since the next read can clear                      |
+
+The set lives in the watch command rather than in the verb, so a refusal `canon pr checks` adds later defaults to transient and waits, which is the safe side.
+
+- A permanent refusal ends the sequence. Stop and report that `reason`, such as `no-remote-branch` for a branch deleted on the remote.
+- A transient refusal in the final record came from the read after the loop, since the loop never exits on one. Read `canon pr checks <number> --json` once more and route on that.
+- A second refusal on that read stops the sequence with its `reason`
+- A watch that hit its timeout and printed no final record is CI unsettled after 60 minutes, so report it that way. A transient refusal that never cleared ends here too.
 
 Do not auto-fix any of these. A stop report is one of the two exceptions to the no-text-between-steps rule.
+
+## A failing record with only cancelled runs
+
+A run cancelled by a runner or a superseded workflow reads as `failing`, and a reviewer reads it as a real failure. This section decides whether a `failing` wake reruns or stops, and the rerun is the one exception to the no-auto-fix rule.
+
+List the failed check runs on the record's `tip`, keeping the newest run per check name as `canon pr checks` does, and print each run id when every one of them was cancelled. The read goes through REST, since `gh pr checks` runs on GraphQL and a cloud session's proxy refuses it:
+
+```bash
+gh api "repos/{owner}/{repo}/commits/<tip>/check-runs?per_page=100" --jq '[.check_runs | group_by(.name)[] | max_by(.id) | select(.conclusion | IN("failure", "timed_out", "cancelled", "action_required", "startup_failure"))] | if length > 0 and all(.conclusion == "cancelled") then [.[].details_url | capture("/runs/(?<id>[0-9]+)").id] | unique | .[] else empty end'
+```
+
+- A non-zero exit means the read was refused, so stop and report the refusal rather than reading it as a real failure
+- An empty print on a zero exit means at least one check really failed, so stop and report it with its URL
+- Otherwise run `gh run rerun <id> --failed` once per printed id, then start the watch again from `### Watching CI`
+- Rerun once per ship. A second `failing` wake on the same cancelled runs stops and reports them as cancelled, naming each URL.

package/claude/skills/markdown-craft/references/markdown.md

@@ -41,7 +41,7 @@ Does not govern:
 ## Headings
 
 - H1 for document title, H2 for main sections, H3 for subsections, and no H4
-- Use sentence case for every heading. The audit reports a heading or a frontmatter `title` with a capitalized word after the first.
+- Use sentence case for every heading. The audit reports a heading or `title` with a capital after the first word, past any task phase label.
 - Proper nouns and product names keep their casing, whatever the audit reports
 - Shape a record as H2 per section and H3 per item a reader looks up by name. Use a table only for a fixed-shape set.
 
@@ -133,7 +133,7 @@ A bullet's punctuation follows its sentence count, and a list opens unannounced.
 ## Punctuation
 
 - Do not use em dashes (`—`) or semicolons (`;`). Rewrite or restructure the sentence to avoid them. A colon or a comma standing where the dash was is the same sentence, so split it or rewrite it.
-- Do not use a colon to join two clauses in the middle of a sentence. A colon belongs after a label or at the end of a line introducing a list.
+- Do not use a colon to join two clauses in a sentence. A colon follows a label of three words or fewer, or ends a line introducing a list.
 - The check misses a clause colon in a list of colon items, but it is wrong.
 - Do not use parenthetical asides in prose (`the config (which is optional) controls...`). Split into its own sentence or drop it. Parentheses in rule definitions for grouping examples are fine.
 
@@ -173,8 +173,8 @@ When frontmatter carries a `title` or `description` used for catalog display:
 ## Links and file references
 
 - Use descriptive anchor text for links. Avoid `click here` or `read more`.
-- Wrap file references in backticks by default. Never repeat the path verbatim as a link label.
-- Use a labeled markdown link (`[label](path)`) only on rendered-for-human surfaces (`README.md`, `docs/`) and in an index file, whose rows exist to be followed
+- Wrap file references in backticks by default. Never repeat the path verbatim as a link label, bar a Key changes code span.
+- Use a labeled markdown link (`[label](path)`) only on human-read surfaces (`README.md`, `docs/`), an index file, and a pull request body's Key changes
 - A relative link resolves against the filesystem over the corpus the ban scan reads, and one carrying a placeholder in angle brackets, such as `<slug>`, is an exempt illustration
 
 ## Examples

package/claude/skills/plan-feature/references/plan.md

@@ -218,6 +218,8 @@ Every outcome reaches the review with its proof named.
 
 - Name, for each outcome, the test or the command that proves it, as one bullet leading with the outcome and ending on the command in backticks.
 - Write a command a later session can run as given, from the project root. A description of what would be checked leaves the executing session to invent the check.
+- Write each command as one command, with no pipe, `&&`, `;`, or command substitution.
+- A permission mode can refuse a compound form, and a substituted check no longer matches the plan, so reach a filter through a verb's own argument or flag, or name a test that holds it.
 - Name the visual check where no test reaches, and say it is visual, so a reader can tell a proof from a look.
 
 ### Risks

package/claude/skills/review-address/SKILL.md

@@ -138,7 +138,8 @@ gh api -X POST 'repos/{owner}/{repo}/issues/<number>/comments' -F body=@.canon/t
 
 After the push, read Watching CI in `${CLAUDE_SKILL_DIR}/../git-ship/SKILL.md` without invoking that skill, start its background watch, end the turn on its line, and run the rest of this step and Step 8 on the wake. Reuse a watch already running on this PR, since it reads the new tip.
 
-- On the wake, stop on `conflicted` naming a rebase, on a `reason` naming it, and on a timeout reporting CI unsettled
+- On the wake, stop on `conflicted` naming a rebase, and on a timeout reporting CI unsettled
+- Route a `reason` through the refused reads in `${CLAUDE_SKILL_DIR}/../git-ship/references/ci-watch.md`, which re-read a transient one once and stop on a permanent one naming it
 - If any check fails, skip the edit and report the failing check so it can be fixed first
 
 When every finding is addressed and the state is `passing`, append the closing confirmation to the reply file Step 6 posted, so the thread carries one terminal state rather than a second comment. A rebase-only run appends the line `${CLAUDE_SKILL_DIR}/references/rebase-only.md` gives instead.

package/claude/skills/review-pr/references/key-changes.md

@@ -16,11 +16,12 @@ Branch on the record rather than on the exit code, which a shell function wrappi
 | Field        | Reading                                                                                |
 | ------------ | -------------------------------------------------------------------------------------- |
 | `unmet`      | a `should-fix` finding under the `**PR body**` block the stale box takes, one per path |
+| `mislinked`  | a `should-fix` finding under the same block, one per link, since it opens another file |
 | `unnamed`    | read for yourself and raise nothing off the count                                      |
 | `unresolved` | reported nowhere, since it was judged in neither direction                             |
 | `incidental` | reported nowhere, since it owes no bullet                                              |
 
-Each `unmet` finding quotes the `preview` bullet and the `head`.
+Each `unmet` finding quotes the `preview` bullet and the `head`. The exit is 2 for a `mislinked` entry too, so a body exiting 2 with `unmet` empty is not clean.
 
 ### Before filing an unmet path
 

package/claude/skills/role-orchestrator/REQUIREMENT.md

@@ -9,7 +9,7 @@ description: What the one warm control session owns, why it plans and dispatches
 
 Without this skill, the control session builds or merges, and the cross-feature picture goes with it. Plans go out unread against each other and a moved tree, the queue empties or fills with whatever is oldest, a parked row's blocker is never re-tested, and a second orchestrator writes a board neither can read.
 
-The channel fails at every hand-off. A finding or a reply stays in a thread nobody re-reads, a dispatch launches a branch other than the one the check cleared, a wave's cost grows unweighed, a report buries the human's decision, and a compaction loses the way back in.
+The channel fails at every hand-off. A finding or a reply stays in a thread nobody re-reads, a dispatch launches a branch other than the one the check cleared, a wave's cost grows unweighed, a report buries the human's decision, a compaction loses the way back in, and a wave a usage limit stopped reads as finished.
 
 ## Must
 

package/claude/skills/role-orchestrator/SKILL.md

@@ -42,7 +42,7 @@ The human asks for each side of a compaction, and this skill reads the runbook.
 
 - On a request to write the handoff, follow `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md`. It sends the generic half to `canon:session-map` and adds decisions taken under delegated authority.
 - That map follows `${CLAUDE_SKILL_DIR}/../session-map/references/session.md`. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
-- Hand launch: `${CLAUDE_SKILL_DIR}/references/orchestrator-hand-launch.md`
+- Hand launch: `${CLAUDE_SKILL_DIR}/references/orchestrator-hand-launch.md`. Limit stops, on request or on this session's first turn after: `${CLAUDE_SKILL_DIR}/references/orchestrator-limit-stops.md`.
 - A lesson about how to work goes to the owning task's Findings, as a bold-labeled line per `${CLAUDE_SKILL_DIR}/../task-board/references/tasks.md`
 - On a request to resume after a compaction, read `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md`, which reads that file back with the board and the groundwork behind the live work
 
@@ -56,7 +56,7 @@ A board that is not moving is a third such moment. On a request to re-test the p
 
 That routing lives in this body and this skill is user-invoked, so a session that has dropped the body routes nothing and the request lands as ordinary conversation. Approaching a compaction, when the handoff matters, is when a long session is likeliest to have dropped it.
 
-Re-invoke `/canon:role-orchestrator` first whenever the session has run long or the ask goes unanswered. The three runbooks sit at `references/orchestrator-handoff.md`, `references/orchestrator-resume.md`, and `references/orchestrator-parked.md`, so a person who knows their plugin root can follow one without this skill loaded.
+Re-invoke `/canon:role-orchestrator` first whenever the session has run long or the ask goes unanswered. The runbooks sit under `references/`, so a person who knows their plugin root can follow one without this skill loaded.
 
 ## Output
 

package/claude/skills/role-orchestrator/references/orchestrator-hand-launch.md

@@ -24,6 +24,8 @@ The `Controller:` line replaces the background template's message clauses, which
 
 The first wave carries the worker. The wave after its pull request opens carries the reviewer alone.
 
+Once the operator confirms a worker launched, run `canon tasks promote <stem>`, the same call a background launch makes. Nothing else moves a hand-launched row out of `## Up next`.
+
 ````markdown
 # Dispatch prompts
 

package/claude/skills/role-orchestrator/references/orchestrator-handback.md

@@ -18,7 +18,7 @@ Read the threshold off `review-pr`, which states it once and governs the heading
 
 Read the pull request's own draft flag rather than the state a worker reports, and report what the read returned and when rather than the state alone. `canon pr head --help` states why a reported field can lag and say nothing about it.
 
-The flag settles the question only once the worker's chain has run its undo, and nothing marks that moment. A read taken between the pull request opening and that call sees a ready pull request about to become a draft, and once told an operator the opposite of what the worker had said.
+A chain's create drafts at once, so its pull request reads draft from the first read. Before a lift or a person readies it, a ready read means the create missed and the fallback mark has yet to run or has failed, so report it as that rather than as a settled state.
 
 ## The rebase handback
 

package/claude/skills/role-orchestrator/references/orchestrator-limit-stops.md

@@ -0,0 +1,47 @@
+---
+title: Orchestrator limit stops runbook
+description: Finding the sessions a usage limit stopped through the roster, and resuming each from its own record with one fixed message
+---
+
+A usage limit stops every session on the account at once, and each one then reads `idle`, `shell`, or `waiting` as though it had finished. Run this pass on the operator's ask, or on this session's own first turn after a limit stop, once the limit has lifted.
+
+## Finding the rows
+
+Read the roster and keep what this session can reach.
+
+```bash
+canon sessions list --stopped --json
+```
+
+- Keep this repository's rows and report the rest to the operator, since `session-relay` refuses a send across repositories
+- Report `stopsUnread` when it is above zero, since those rows may be stopped and nothing will message them
+- Report `foreignDead` when it is above zero, since this reader could not check those sessions at all
+- Find each row's task with `grep -l <sessionId> .canon/tasks/*.md` at the main worktree root, since `canon tasks session` writes the id there
+- Report a refusal of the flag as an older CLI behind the plugin, never as an empty list
+
+### What the watch cannot tell you
+
+`orchestrator-watch.md` reads a worker gone idle as finished, so a limit-stopped worker reports that way there. Its `WORKER-STOPPED` line means a long `waiting` row and says nothing about a limit, so read the `stopped` field in full on every row this pass decides.
+
+## Sending
+
+Each row takes the same message with its own record filled in.
+
+```plaintext
+The usage limit lifted. Re-read <record> and continue. Re-run any command whose result you never read.
+```
+
+The last sentence covers a session stopped between starting a command and reading what came back, such as a reviewer stopped mid-lift.
+
+Fill `<record>` by the row's role, read off its name. A row with a task and a feature branch whose name states no role is a hand-launched worker.
+
+| Row      | `<record>`                                                                         |
+| -------- | ---------------------------------------------------------------------------------- |
+| Worker   | The plan its task links                                                            |
+| Reviewer | The pull request its name carries, through `canon pr review-state <number> --json` |
+| Planner  | Its task                                                                           |
+| No task  | Its branch, and list the row to the operator                                       |
+
+Send each row the message once through `canon:session-relay`, then run the roster read again.
+
+Never send a row the message twice in one pass. A row still reading stopped on the second read either has not drained the message or stopped again, and a new stop can carry the same reset text as the one before. Report it with its reset to the operator and hold the rest of the wave.

package/claude/skills/role-orchestrator/references/orchestrator-sweep.md

@@ -18,9 +18,11 @@ Sweep the board as orchestrator after merging. Run this once per batch of merges
 
 Run `canon worktrees list` after the pull, the first point at which the merges this sweep followed are readable. It owns the reclaim rule and removes nothing, so read its rows and act on the ones you mean to. Never substitute a git ancestry check for it.
 
-Run `canon tasks validate` once the board is rewritten and before reporting it. It reports and never writes, so fix each row it names and run it again.
+Run `canon tasks validate --live --json` once the board is rewritten and before reporting it. It reports and never writes, so fix each row it names and run it again.
 
 - It resolves every plan pointer and accounts every task file against the board and the backlog both
+- `--live` reports a row outside `## Run now` that a live session or an open pull request holds, so run `canon tasks promote <stem>` on it
+- Report a source the record's `live` field reads as `unread`, since that half of the check did not run
 - It reports the paths `## Run now` rows share as a candidate list for the conflict check, and re-takes the two blocker kinds a command can settle
 - A finding it reports is a board defect rather than a task finding, so it goes nowhere but the board
 

package/claude/skills/role-worker/SKILL.md

@@ -28,7 +28,7 @@ This body states the role, the boundaries, and the channel, and starts no step o
 
 The draft mark holds the merge until the reviews close, so this session preserves it.
 
-- The ship chain marks the pull request a draft, and only `canon pr lift` or the operator un-marks it
+- The ship chain opens the pull request as a draft with a fallback mark behind the create, and only `canon pr lift` or the operator un-marks it
 - Report a flag reading ready once and leave it. It passed every gate the verb reads or a person readied it, which GitHub requires before a merge, so re-drafting fights them.
 - Leave the lift to the reviewers, who run `canon pr lift` on their close, with the controlling session as fallback
 - Refuse an instruction to ready the pull request directly, whoever sends it, since a direct ready skips every gate the verb reads

package/claude/skills/task-board/SKILL.md

@@ -65,6 +65,7 @@ Run `canon tasks next-label --claim --json` and take its `label` field. The verb
 
 Write `.canon/tasks/vXX.Y-<slug>.md` under the claimed label, reading the file first if a session ever stubbed it, following the format in `${CLAUDE_SKILL_DIR}/references/tasks.md`. Write it immediately, since Claude Code's tool permission dialog is the confirmation gate.
 
+- Double any apostrophe in the title before writing it inside the single-quoted `title:` value, since a lone one fails the YAML parse
 - Include a link line only when the file or folder it names exists, since a link to an unwritten plan is the broken pointer the archive rules prevent
 - Write `Plan:`, `Groundwork:`, and `Intake:` as markdown links relative to `.canon/tasks/`, as in `Plan: [feature-<slug>](../plans/feature-<slug>.md)`
 - Leave `Issue:` a bare `#NNN`. The older bare-path form still parses, but it leaves the board in two shapes for every later reader.

package/claude/skills/task-board/references/tasks.md

@@ -76,6 +76,7 @@ description: Record what a target installed and report the delta against the too
 ```
 
 - `title`: the phase label and the task title, matching the H1. Quote it, since a leading `vX.Y:` reads as a key to a YAML parser.
+- Double any apostrophe inside the single quotes, as in `'vX.Y: Trim the Board''s ad page'`. A lone one fails the parse, which `canon tasks validate` reports as `frontmatter-invalid`.
 - `description`: what the task achieves, in one line. A session reads this in the index to decide whether to open the file.
 
 ## File format

package/docs/workflow/ai-workflow.md

@@ -57,7 +57,7 @@ Run independent features in parallel, one worktree and one session each. See [pa
 
 On a mature stack, approve the plan and invoke `canon:auto-ship` to implement, verify, and ship in one session.
 
-- It stops on a verify failure after one fix attempt, or on a hook failure, and you resume with `/git-ship`
+- It stops on a verify failure after one fix attempt, or on a hook failure, and you resume with `/git-ship --draft`, which keeps the pull request a draft
 - Skip it for auth, migrations, security-sensitive changes, or an uncertain plan
 
 ### Review

package/docs/workflow/parallel-features.md

@@ -55,7 +55,8 @@ Merge order matters only when two branches touch the same file. Expect to rebase
 
 - A row's cell count must match its header, and a `## Needs a plan` row stating its position is checked against where it sits
 - Every plan pointer resolves, every task file is named once, and every ready row names its files
-- A parked row is reported when its cited task reached the trunk, whether the cell links it or names its bare label
+- A task file whose frontmatter block will not parse as YAML is reported with the parser's message, as with a lone apostrophe inside the single-quoted title
+- A parked row is reported when its cited task reached the trunk, whether the cell links it or names its bare label, and with `--live` when a live session or an open pull request holds it
 - A group header must be the columns the group owns, a `Touches` cell must match its plan, and a `Waiting on` cell renders at most 120 characters
 
 `canon:task-board` creates a task file, and `canon:task-complete` marks outcomes. The `post-merge` hook archives the task a merged pull request closed, with its plan, and a `post-rewrite` hook does the same for a rebase pull. Both archive a closed task whose merge carried a PR number, and a slice merged before then moves only its own plan.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.78.0",
+  "version": "5.79.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/commands/pr.ts

@@ -113,6 +113,7 @@ import {
   type LocalRefusal,
   type LocalRunner,
 } from '@/pr/local'
+import { linkKeyChanges } from '@/pr/links'
 import { KEY_CHANGES } from '@/pr/paths'
 import {
   findDeployWorkflow,
@@ -161,6 +162,7 @@ const GH_TIMEOUT_MS = 30_000
 const UNNAMED_PRINT_LIMIT = 10
 
 interface KeyChangesOptions {
+  readonly link?: boolean
   readonly body?: string
   readonly base?: string
   readonly root?: string
@@ -279,7 +281,7 @@ const LOCAL_REFUSALS: Record<
     'Nothing listening inside this worktree served an HTML page. Start the dev server here and re-run to get a link.',
   unhealthy:
     'A page answered inside this worktree, but a health path it declares failed. Start what the page reaches and re-run to get a link.',
-  'invalid-config': `${LOCAL_CONFIG_REL} cannot be read, so no health path was checked and no link is given. Fix or delete it and re-run.`,
+  'invalid-config': `${LOCAL_CONFIG_REL} cannot be read, so no health path was checked and no link is given. Fix or delete it and re-run. health takes paths starting with /, and page-only takes folders relative to the repository.`,
   'no-listener-reader':
     'This machine offers neither lsof nor /proc, so no listening socket could be read. Nothing is posted.',
   'gh-failed':
@@ -503,13 +505,17 @@ export function register(program: Command): void {
     .helpOption('-h, --help', 'Show this help message')
     .option(
       '--body <path>',
-      'Read the body from a file rather than the API, ignoring any number',
+      'Read the body from a file rather than the API, ignoring any number except the one --link needs',
     )
     .option(
       '--base <ref>',
       'Far side of the range when --body supplies the body',
     )
     .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option(
+      '--link',
+      `Print the body with each ## ${KEY_CHANGES} path linked to its diff, needing a number`,
+    )
     .option('--json', 'Add a machine-readable record on stdout')
     .addHelpText(
       'after',
@@ -538,6 +544,13 @@ export function register(program: Command): void {
         'points the change at a locative the path does not name. Read the bullet on',
         "the record's preview before filing an unmet path as a stale claim.",
         '',
+        '--link prints the body and nothing else, with every path the section',
+        'names that the diff changes written as a link to its row in the Files',
+        'tab. The anchor is `diff-` and the SHA-256 of the path. Pass the pull',
+        'request number, since the link needs it. It also rewrites the anchor',
+        'of a link opening another file, and a plain run reports that link as',
+        "mislinked when its label is a changed path and its anchor hashes another's.",
+        '',
         'Refusals, read off `reason`:',
         '  no-section          the body carries no `## Key changes` heading, so it',
         '                      claims nothing',
@@ -555,14 +568,18 @@ export function register(program: Command): void {
         '  gh-missing          `gh` is not on the path, so no pull request could be',
         '                      resolved',
         '  gh-failed           `gh` could not answer for this repository or branch',
+        '  no-number           --link was given with no pull request number',
+        '  no-repo-url         --link could not read the repository address',
+        '  link-json           --link was given with --json, though it prints the body',
         '',
         'Exit codes:',
-        '  0  every claimed path is in the diff',
+        '  0  every claimed path is in the diff, and every link opens its own file',
         '  1  refused, with the reason on stderr or in the JSON record',
-        '  2  at least one claimed path is absent from the diff',
+        '  2  a claimed path is absent from the diff, or a link opens another file',
         '',
         'Examples:',
         '  canon pr key-changes',
+        '  canon pr key-changes 1265 --link --body .canon/tmp/body.md',
         '  canon pr key-changes 1265 --json',
         '  canon pr key-changes --body .canon/tmp/body.md --base origin/main',
         '',
@@ -1301,6 +1318,15 @@ export function register(program: Command): void {
         "refusal names the lowest page port's first failing path. An absent",
         'file or an empty list checks the page alone.',
         '',
+        'A page served by a static server answers none of those paths, so',
+        'page-only = ["web"] lists repository-relative folders whose',
+        'listeners skip them and are found on the page probe alone. The match',
+        "reads the listener's working directory on whole path segments, so web",
+        'does not cover webapp, and a server started from the root with a',
+        'working-directory flag still takes the health check. Keep health',
+        'beside page-only until the binary a project runs carries this key,',
+        'since an older one refuses a file holding page-only alone.',
+        '',
         'A process in a sibling worktree, in the main checkout seen from a',
         'linked worktree, or in a linked worktree seen from the main checkout',
         'is never reported, since its server shows another branch. Sockets are',
@@ -1326,8 +1352,9 @@ export function register(program: Command): void {
         '  unhealthy           a page answered but a declared health path did',
         '                      not, with `port`, `path`, and `status`, which',
         '                      is null on a timeout',
-        '  invalid-config      canon/config/local.toml is not valid TOML, or',
-        '                      health is not a list of paths starting with /',
+        '  invalid-config      canon/config/local.toml is not valid TOML,',
+        '                      health is not a list of paths starting with /,',
+        '                      or page-only is not a list of relative folders',
         '  removed             --remove dropped the line',
         '  no-comment          --remove found no marked comment, a no-op',
         '  no-line             --remove found no address line, a no-op',
@@ -1865,6 +1892,8 @@ async function runKeyChanges(
   const root = resolve(opts.root ?? process.cwd())
   const emitJson = opts.json ?? false
 
+  if (opts.link === true) return runKeyChangesLink(number, opts, root)
+
   intro('canon pr key-changes')
 
   const source =
@@ -1949,6 +1978,14 @@ async function runKeyChanges(
     for (const claim of report.unresolved) logInfo(claim.path)
   }
 
+  if (report.mislinked.length > 0) {
+    logStep('Mislinked')
+    logWarn(
+      `${plural(report.mislinked.length, 'link')} open another file's diff than the path they name. Re-run with --link to print the body with them corrected.`,
+    )
+    for (const link of report.mislinked) logWarn(link.path)
+  }
+
   outro()
 
   if (emitJson) {
@@ -1966,11 +2003,71 @@ async function runKeyChanges(
         incidental: report.incidental,
         unresolved: report.unresolved,
         evidenceUnread: report.evidenceUnread,
+        mislinked: report.mislinked,
       })}\n`,
     )
   }
 
-  return report.unmet.length === 0 ? 0 : 2
+  return report.unmet.length === 0 && report.mislinked.length === 0 ? 0 : 2
+}
+
+/**
+ * Prints the body with each changed path in `## Key changes` linked to its
+ * diff, and nothing else, so stdout pipes straight into a body file.
+ *
+ * Skips the frame `intro` opens, which would land in the piped body. Refusals
+ * keep the framed shape on stdout like every other mode.
+ */
+async function runKeyChangesLink(
+  number: string | undefined,
+  opts: KeyChangesOptions,
+  root: string,
+): Promise<number> {
+  const emitJson = opts.json ?? false
+
+  if (emitJson) {
+    return refuseWith(
+      'link-json',
+      '--link prints the body itself, so it takes no --json record.',
+      emitJson,
+      root,
+    )
+  }
+
+  const source =
+    opts.body === undefined
+      ? await readFromApi(root, number)
+      : await readFromFile(root, process.cwd(), opts.body, opts.base)
+  if (source.kind === 'refused') return refuse(source.reason, emitJson, root)
+
+  const pull = number ?? source.source.number?.toString()
+  if (pull === undefined) {
+    return refuseWith(
+      'no-number',
+      'The link needs the pull request number, so pass it as the argument.',
+      emitJson,
+      root,
+    )
+  }
+
+  const url = await readRepoUrl(root)
+  if (url === undefined) {
+    return refuseWith(
+      'no-repo-url',
+      'gh could not read the repository address, so no link was built.',
+      emitJson,
+      root,
+    )
+  }
+
+  process.stdout.write(
+    linkKeyChanges(
+      source.source.body,
+      source.source.changed,
+      `${url}/pull/${pull}/files`,
+    ),
+  )
+  return 0
 }
 
 type IdentityRead =
@@ -2494,14 +2591,18 @@ interface PullFiles {
   readonly present: ReadonlyMap<string, boolean>
   /** Each path the pull request removed, which a deploy's push filter still counts. */
   readonly removed: readonly string[]
+  /** Each renamed path mapped to the path it sat at before the pull request. */
+  readonly renamedFrom: ReadonlyMap<string, string>
 }
 
 /**
  * The paths a pull request changed, read through the paginated files endpoint
  * so the set is the same from any checkout and never capped at the first
- * view. `renamed` and `copied` count as added, since the new path has no
- * counterpart at the merge base. Returns undefined when the read fails, which
- * refuses rather than rendering a short set.
+ * view. `copied` counts as added, since a copy leaves its source in place and
+ * has no single base. `renamed` counts as added in `present` too, so the
+ * changed set stays the same, and `renamedFrom` carries the old path of each
+ * rename for a reader that compares against the base. Returns undefined when
+ * the read fails, which refuses rather than rendering a short set.
  */
 async function listPullFiles(
   cwd: string,
@@ -2512,18 +2613,22 @@ async function listPullFiles(
     '--paginate',
     `repos/{owner}/{repo}/pulls/${number}/files`,
     '--jq',
-    '.[] | [.status, .filename] | @tsv',
+    '.[] | [.status, .filename, (.previous_filename // "")] | @tsv',
   ])
   if (stdout === null) return undefined
   const present = new Map<string, boolean>()
   const removed: string[] = []
+  const renamedFrom = new Map<string, string>()
   for (const line of stdout.split('\n').filter(Boolean)) {
-    const [status, path] = line.split('\t')
+    const [status, path, previous] = line.split('\t')
     if (status === undefined || path === undefined) continue
     if (status === 'removed') removed.push(path)
     else present.set(path, status !== 'modified' && status !== 'changed')
+    if (status === 'renamed' && previous !== undefined && previous !== '') {
+      renamedFrom.set(path, previous)
+    }
   }
-  return { present, removed }
+  return { present, removed, renamedFrom }
 }
 
 function everyChangedPath(files: PullFiles): string[] {
@@ -2671,13 +2776,14 @@ async function measureItem(
   head: string,
 ): Promise<MeasuredItem> {
   const headRead = await readImage(cwd, item.path, head)
+  const basePath = item.basePath ?? item.path
   const baseRead =
     item.added || base === undefined
       ? undefined
-      : await readImage(cwd, item.path, base)
+      : await readImage(cwd, basePath, base)
   const unread = [
     ...(headRead.kind === 'failed' ? [`head:${item.path}`] : []),
-    ...(baseRead?.kind === 'failed' ? [`base:${item.path}`] : []),
+    ...(baseRead?.kind === 'failed' ? [`base:${basePath}`] : []),
   ]
   const headBytes = headRead.kind === 'read' ? headRead.bytes : undefined
   const baseBytes = baseRead?.kind === 'read' ? baseRead.bytes : undefined
@@ -2691,6 +2797,9 @@ async function measureItem(
       ...(headBytes !== undefined &&
         baseBytes !== undefined && {
           withinTolerance: isWithinTolerance(baseBytes, headBytes),
+          ...(item.basePath !== undefined && {
+            identical: Buffer.from(baseBytes).equals(headBytes),
+          }),
         }),
     },
     unread,
@@ -2811,6 +2920,7 @@ async function runEvidence(
   const grouped = await groupEvidence(
     [...pullFiles.present.keys()],
     async (path) => pullFiles.present.get(path) === false,
+    pullFiles.renamedFrom,
   )
   const uncaptured = readUncaptured(
     everyChangedPath(pullFiles),
@@ -3412,6 +3522,7 @@ async function runLocal(opts: LocalOptions): Promise<number> {
     worktree,
     machineLocalRunner(),
     declaration.kind === 'paths' ? declaration.paths : [],
+    declaration.pageOnly,
   )
   if (result.kind === 'refused' && result.reason === 'unhealthy') {
     const { port, path, status } = result
@@ -4028,6 +4139,18 @@ async function readRepoName(root: string): Promise<string | undefined> {
   }
 }
 
+/** The repository's web address off the REST repository read, for the same reason as `readRepoName`. */
+async function readRepoUrl(root: string): Promise<string | undefined> {
+  const row = await gh(root, ['api', 'repos/{owner}/{repo}'])
+  if (row === null) return undefined
+  try {
+    const url = (JSON.parse(row) as { html_url?: unknown }).html_url
+    return typeof url === 'string' && url !== '' ? url : undefined
+  } catch {
+    return undefined
+  }
+}
+
 async function runFrames(
   number: string | undefined,
   opts: FramesOptions,