@erclx/canon 4.10.0 → 4.12.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.10.0",
+  "version": "4.12.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/canon-feedback-file/SKILL.md

@@ -17,28 +17,49 @@ Format a `## Toolkit feedback` block from the current session, then ship it to t
 
 From the conversation so far, identify:
 
-- Target project name or path
+- Target project name or kind, never its full path. The path names a folder on one machine and says nothing a triage session can route on, where the project's own name does. Name a private project by its kind instead, such as `a Next.js app`, since the report leaves the machine.
 - Toolkit surface and its type (plugin skill, snippet, tooling config, governance rule, seed, or CLI)
 - Specific toolkit file or name when the session cites one
 - Observed behavior
 - Expected behavior, or `unclear`
 - Repro details already in context (commands run, files touched), or `none`
-- Proposed fix when the user stated one, or `open`
+- Proposed fix, or `open` when the session settled on no direction
 
-Format as a single fenced markdown block:
+Format as a single fenced markdown block, one `###` heading per field:
 
 ```markdown
 ## Toolkit feedback
 
-**From project:** <name or path>
-**Surface:** <type>, <file path or name>
-**Observed:** <one or two lines>
-**Expected:** <one or two lines, or "unclear">
-**Repro:** <commands or steps, or "none">
-**Proposed fix:** <one line, or "open">
+### From project
+
+<name or kind>
+
+### Surface
+
+<type>, <file path or name>
+
+### Observed
+
+<one or two lines>
+
+### Expected
+
+<one or two lines, or "unclear">
+
+### Repro
+
+<commands or steps, or "none">
+
+### Proposed fix
+
+<one line, or "open">
 ```
 
-Keep each field to one or two lines. Write the literal fallback shown above when a field has nothing.
+`canon feedback` refuses a report missing `### Surface`, `### Observed`, or `### Proposed fix`, naming the one it did not find. The other three are optional, so write the literal fallback shown above rather than dropping the heading, which is what keeps a field the session cannot fill reading as absent instead of unreported.
+
+Headings rather than bold labels, because a GitHub issue form renders a submitted field as `### <label>`. One shape reaches the toolkit whichever route a report takes, and the CLI parses both with one parser. The retired `**Surface:**` form is refused rather than accepted, so a block carrying it has to be rewritten.
+
+Keep each field to one or two lines.
 
 ## Step 2: ship to the toolkit
 
@@ -60,7 +81,7 @@ EOF
 
 Report the printed path back to the user on its own line, in the form the project's instruction file sets under `## Output`.
 
-For a durable, cross-machine report instead of local scratch, add `--github`. The CLI opens a GitHub issue on the toolkit repo and prints the issue URL. It needs `gh` authenticated, and falls back to local scratch with a warning when `gh` is absent.
+For a durable, cross-machine report instead of local scratch, add `--github`. The CLI opens a GitHub issue on the toolkit repo and prints the issue URL. It needs `gh` authenticated, and falls back to local scratch with the reason on stderr when the call produces no URL.
 
 ```bash
 cat <<'EOF' | canon feedback --github
@@ -74,6 +95,15 @@ Default to local scratch for a quick note. Use `--github` for a report worth tra
 
 If `canon` is not on PATH, fall back: print the block in chat and tell the user `📋 Copy the block above into a toolkit-repo session.`
 
+## Step 3: read what the CLI said back
+
+The command exits 1 and writes nothing on a report it refuses, so a non-zero run is a block to repair rather than a report that shipped. Two refusals reach this step:
+
+- A named missing field. Add that heading with a real value or its stated fallback, then re-run. Do not report the defect as filed.
+- `gh` absent or its call failed, on `--github` from a machine holding no toolkit source. The stderr names which, since installing `gh` and fixing an authenticated call are different repairs. Fall back to printing the block in chat.
+
+A `--github` run from a toolkit checkout warns and writes local scratch instead, which is a report filed on the other route rather than a failure.
+
 ## Notes
 
 - `canon feedback` resolves the toolkit root from the running `canon` binary's source location. If multiple toolkit clones exist on the machine, the first `canon` on PATH wins.

package/docs/agents/capture.md

@@ -15,9 +15,9 @@ canon capture assets --selector .window --out .canon/review/captures
 
 `--selector` is required and every example above passes it. The element a capture crops to belongs to the page, not to the command, so there is no value that could be right for an arbitrary project's markup. `.window` is what this repository's own two sources declare, and a project renders its own pages by naming whatever theirs declare.
 
-`assets/` here holds two sources, so one run over the folder rebuilds both. `install.html` is hand-authored and its text came from a real run. `hero.html` is generated by `scripts/core/regen-hero.sh` from the CLI catalogs and must not be edited by hand, since `bun run check` regenerates it and fails on the difference.
+`assets/` here holds two sources, so one run over the folder rebuilds both. Neither is edited by hand. `scripts/core/regen-hero.sh` writes both from a template beside it, filling `hero.html.tmpl` from the CLI catalogs and both templates from the design source, and `bun run check` regenerates them and fails on the difference. The terminal text on `install.html` still comes from a real run, and it is the template that holds it.
 
-Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `canon capture assets/hero.html --selector .window` when the check reports the HTML changed.
+Only the HTML is asserted for drift. The PNG is a chromium render whose bytes move with the browser version, so rebuild it with `canon capture assets --selector .window` when the check reports the HTML changed.
 
 Every render writes a stamp beside its PNG, `hero.png` next to `hero.stamp`, holding the source filename, a `source-sha256` over the markup bytes it read, and an `image-sha256` over the image bytes it wrote. Both digests are what `bun run check` compares, so a markup edit committed without a capture and a PNG swapped under unchanged markup each fail. The stamp is tracked and commits alongside the pair. Nothing hand-edits it, and a capture that cannot write it reports that source as failed and exits 1, so an image whose stamp never landed is reported rather than passed over.
 

package/docs/agents/commands.md

@@ -28,7 +28,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon design sync`           | Update a base stylesheet already installed under `.claude/design/`                                                                                                    |
 | `canon slides render`         | Render a `.claude/SLIDES.md` source into a PowerPoint deck, reporting any unrecognized layout name on stderr                                                          |
 | `canon slides list`           | List the available slide layouts (`--json` for the catalog)                                                                                                           |
-| `canon feedback`              | Write toolkit feedback from stdin to `.canon/review/feedback/`, or open a GitHub issue with `--github`                                                                |
+| `canon feedback`              | Write toolkit feedback from stdin to `.canon/review/feedback/`, or open a GitHub issue with `--github`, refusing either when a required field is absent               |
 | `canon transcripts <url>`     | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)                                                                                                 |
 | `canon tasks archive`         | Move a shipped task and its plan off the board, clear its ordering row, and regenerate the index                                                                      |
 | `canon tasks pull-request`    | Record a pull request number on the task a branch closes, by stem or `--plan` (`--json`)                                                                              |
@@ -48,6 +48,7 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon records pull`          | Fetch the records remote and write it back, refusing rather than discarding unpushed records (`--json`)                                                               |
 | `canon migrate rename`        | Rewrite every unprotected `aitk` token to `canon` and move the paths that carry the name, reporting the plan without `--write` (`--scope`, `--json`)                  |
 | `canon migrate records`       | Move the gitignored session records to `.canon/` and repoint every tracked citation, reporting the plan without `--write` (`--root`, `--json`)                        |
+| `canon migrate record-tree`   | Repoint the old-root citations inside the records themselves, scoped to the live folders and reporting every line without `--write` (`--root`, `--json`)              |
 | `canon sessions list`         | Resolve live sessions to the worktree and branch each holds, filtered by `--branch` (`--json`)                                                                        |
 | `canon worktrees list`        | Report which worktrees are reclaimable, keyed on the pull request having merged, with every refusal and the removal route named (`--json`)                            |
 | `canon comments scan`         | Measure comment density by language and comment kind, with a trend recomputed from git                                                                                |
@@ -146,6 +147,10 @@ Common patterns:
 
 A record folder already present at the destination is a refusal rather than a merge, and a line carrying `canon-keep-record-root`, or the line below it, keeps the old spelling for prose that dates a decision. The records themselves are never swept: everything under `.canon/` and every `.claude/` record folder is passed over and reported as a count on its own line, which is what keeps the run that follows the ignore collapse touching the same files as one before it. Running it twice rewrites nothing, which is the check that the exclusions, the markers, and that skip all fired.
 
+`migrate record-tree` is what reaches the records the sweep above passes over, and the two share no scope. That one enumerates through git, so it sees every tracked file and none of the records, which are gitignored by construction. This one walks `.canon/` itself and is scoped to the folders a session still follows a path into: `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`, each minus its own `archive/` subtree. A closed groundwork or intake trail, the scratch folder, and the backup history are reported as counts and never rewritten, because a path inside a closed trail sits in a sentence about work that already ended. Run it after the move, since there is no new root to walk before one.
+
+Every citation in scope is reported with its file, its line number, and the line text. The record tree is untracked, so a wrong rewrite has no git undo, and that report is what a reader judges before passing `--write`. Marking a line that has to keep the old spelling uses the same `canon-keep-record-root` comment, and a second run rewriting nothing is the idempotence check.
+
 ## Version skew
 
 `canon sync --check` and `canon claude skills drift` are the two moments a target

package/docs/ai-workflow.md

@@ -31,7 +31,7 @@ Project docs split across two roots at the project root, on one mechanical line:
 └── tmp/             ← deletable scratch, safe to remove without loss
 ```
 
-A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root. `canon migrate records` moves one project across and repoints what cites it.
+A project scaffolded before the move keeps its records under `.claude/`, and every command reads either root. `canon migrate records` moves one project across and repoints what cites it, and `canon migrate record-tree` follows it to reach the citations inside the records themselves, which the first verb passes over because it enumerates through git.
 
 Three tiers of context load with different cost: always-loaded (root `CLAUDE.md`, `.claude/REQUIREMENTS.md`, `.claude/ARCHITECTURE.md`), path-scoped lazy (`.claude/rules/<scope>.md` with `paths:` glob), and on-demand lookup (`.claude/context/<domain>.md`, or `.claude/context/<domain>/` once a domain outgrows one file, discovered via `.claude/context/index.md`). See [the context model](../.claude/context/context-model.md) for the full picture.
 

package/docs/target-projects.md

@@ -146,6 +146,17 @@ A tracked file that names an old record path on purpose, such as prose dating a
 
 Until the move runs, the project is exposed. The shipped ignore set no longer names the old record paths, so a project holding records at `.claude/` stops ignoring them on its next `canon tooling sync`, and the first sign is a memory file or a task board appearing in a commit. Every command reads either root, so nothing else breaks in the meantime, and running the move is what closes it.
 
+Then sweep the records themselves, which the three lines above never reach. They enumerate through git, and the records are gitignored by construction, so a task still naming its plan at the old root resolves nothing once the folders move.
+
+```bash
+canon migrate record-tree --json
+canon migrate record-tree --write --json
+```
+
+This is a separate step rather than a fourth line in the block above because the move has to land before there is a new root to walk. The scope is the folders a session still follows a path into, being `diagrams`, `memory`, `plans`, `proposals`, `review`, `tasks`, and `teach`, each minus its own `archive/` subtree. A closed groundwork or intake trail, the scratch folder, and the backup history are counted and left alone, since a path inside one of those sits in a sentence about work that already ended.
+
+Read the report before `--write` here more carefully than above. The record tree is untracked, so a wrong rewrite has no git undo, and the report names every citation with its line number and the line text for exactly that reason. The same `canon-keep-record-root` marker protects a line that has to keep the old spelling.
+
 ### Check first
 
 `canon sync --check <path>` reports what has drifted without writing anything. It splits each difference by cause, which is the question that decides what to do next.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.10.0",
+  "version": "4.12.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/core/regen-hero.sh

@@ -1,16 +1,30 @@
 #!/usr/bin/env bash
-# Fills assets/hero.html.tmpl from the CLI catalogs and writes assets/hero.html.
+# Fills every assets/*.html.tmpl from the CLI catalogs and the design source,
+# writing the .html beside each one.
+#
+# The name says hero because the hero was the only template when it was written
+# and every citation of it across docs/, .claude/context/, and src/ spells that
+# name. Renaming the file is a sweep across roughly twenty surfaces for a
+# cosmetic gain, so the file keeps its name and the loop below covers whatever
+# templates the folder holds.
+#
+# The palette arrives the same way the counts do. `canon design css
+# --no-components` emits the custom properties from src/design/tokens.ts and
+# they land on the {{TOKENS}} placeholder, so neither frame carries its own copy
+# of a hex value and a token moved at the source moves both captures. The
+# component half is left out on purpose: it is a scrollbar and a status marker,
+# and a static capture frame renders neither.
 #
 # Only the HTML regenerates here. The PNG beside it is a chromium render whose
 # bytes move with the browser version, so asserting it in verify.sh would fail
 # on a machine whose chromium differs rather than on a stale count. Rebuild the
-# image with `canon capture assets/hero.html --selector .window` after this
-# script reports a change. The selector has no default, since the element a
-# capture crops to belongs to the page rather than to the command, and `.window`
-# is the class this repository's own two sources declare.
-# That capture also writes assets/hero.stamp, which records the digest of the
-# markup it rendered and is what the Hero stage compares, so all three files
-# commit together. The frame carries no version. `package.json` is bumped on main by the release
+# images with `canon capture assets --selector .window` after this script
+# reports a change. The selector has no default, since the element a capture
+# crops to belongs to the page rather than to the command, and `.window` is the
+# class this repository's own two sources declare.
+# That capture also writes a .stamp beside each PNG, which records the digest of
+# the markup it rendered and is what the Hero stage compares, so a frame's three
+# files commit together. The frame carries no version. `package.json` is bumped on main by the release
 # tooling, so embedding it drifts every open branch on the next release and the
 # stage then fails for work that touched nothing.
 #
@@ -22,8 +36,7 @@ set -o pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
 
-TEMPLATE="$PROJECT_ROOT/assets/hero.html.tmpl"
-OUTPUT="$PROJECT_ROOT/assets/hero.html"
+ASSET_DIR="$PROJECT_ROOT/assets"
 LISTED=10
 
 # `bun src/cli.ts` rather than `canon`, since a globally linked binary resolves to
@@ -32,8 +45,17 @@ catalog() {
   (cd "$PROJECT_ROOT" && CANON_NON_INTERACTIVE=1 bun src/cli.ts "$@" --json 2>/dev/null)
 }
 
-if [ ! -f "$TEMPLATE" ]; then
-  echo "regen-hero: missing template at $TEMPLATE" >&2
+TEMPLATES=("$ASSET_DIR"/*.html.tmpl)
+if [ ! -f "${TEMPLATES[0]}" ]; then
+  echo "regen-hero: no templates under $ASSET_DIR" >&2
+  exit 1
+fi
+
+# Not routed through `catalog`, since the design emitter writes CSS on stdout
+# rather than a `--json` record.
+TOKEN_CSS="$(cd "$PROJECT_ROOT" && CANON_NON_INTERACTIVE=1 bun src/cli.ts design css --no-components)"
+if [ -z "$TOKEN_CSS" ]; then
+  echo "regen-hero: the design source emitted nothing, refusing to write an unstyled frame" >&2
   exit 1
 fi
 
@@ -73,17 +95,26 @@ printf '%s' "$GOV_JSON" >"$PAYLOAD_DIR/gov.json"
 printf '%s' "$STANDARDS_JSON" >"$PAYLOAD_DIR/standards.json"
 printf '%s' "$SNIPPETS_JSON" >"$PAYLOAD_DIR/snippets.json"
 printf '%s' "$TOOLING_JSON" >"$PAYLOAD_DIR/tooling.json"
+printf '%s' "$TOKEN_CSS" >"$PAYLOAD_DIR/tokens.css"
 
 export PAYLOAD_DIR
-export TEMPLATE OUTPUT LISTED PROJECT_ROOT
+export ASSET_DIR LISTED PROJECT_ROOT
 
 bun --eval '
-const { readFileSync } = require("node:fs")
+const { readFileSync, readdirSync } = require("node:fs")
 
-const { PAYLOAD_DIR, TEMPLATE, OUTPUT, LISTED, PROJECT_ROOT } = process.env
+const { PAYLOAD_DIR, ASSET_DIR, LISTED, PROJECT_ROOT } = process.env
 
 const payload = (name) => readFileSync(PAYLOAD_DIR + "/" + name + ".json", "utf8")
 
+// Indented to the depth a rule inside the `<style>` block sits at, so the
+// emitted file passes the same formatter every other committed asset does.
+const tokenCss = readFileSync(PAYLOAD_DIR + "/tokens.css", "utf8")
+  .trimEnd()
+  .split("\n")
+  .map((line) => (line === "" ? "" : "      " + line))
+  .join("\n")
+
 const COUNTS_JSON = payload("counts")
 const SKILLS_JSON = payload("skills")
 const GOV_JSON = payload("gov")
@@ -114,6 +145,12 @@ if (!commandCount) {
   process.exit(1)
 }
 
+const MARK_SVG = (await Bun.file(`${PROJECT_ROOT}/assets/brand/mark.svg`).text()).trim()
+if (!MARK_SVG) {
+  console.error("regen-hero: assets/brand/mark.svg read empty, refusing to write a hero with no mark")
+  process.exit(1)
+}
+
 const escape = (value) =>
   value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
 
@@ -190,6 +227,7 @@ for (const [label, list] of [
 }
 
 const values = {
+  TOKENS: tokenCss,
   SKILL_COUNT: String(skills.length),
   RULE_COUNT: String(rules.length),
   STANDARD_COUNT: String(standards.length),
@@ -197,6 +235,7 @@ const values = {
   GOV_STACK_COUNT: String(gov.stacks.length),
   TOOLING_STACK_COUNT: String(toolingStacks.length),
   COMMAND_COUNT: String(commandCount),
+  MARK_SVG,
   SKILL_ENTRIES: markup(featured(skills, FEATURED_SKILLS)),
   RULE_ENTRIES: entries(deliveredRules),
   STANDARD_ENTRIES: entries(standards),
@@ -205,16 +244,30 @@ const values = {
   STANDARD_MORE: remaining(standards),
 }
 
-let html = await Bun.file(TEMPLATE).text()
-for (const [key, value] of Object.entries(values)) {
-  html = html.replaceAll(`{{${key}}}`, value)
-}
+// Every template takes the same value map, so one carrying no count placeholder
+// simply resolves none of them. What a template must not do is name a
+// placeholder nobody fills, which the unresolved check below catches per file.
+const templates = readdirSync(ASSET_DIR)
+  .filter((name) => name.endsWith(".html.tmpl"))
+  .sort()
 
-const unresolved = html.match(/{{[A-Z_]+}}/g)
-if (unresolved) {
-  console.error(`regen-hero: unresolved placeholders ${[...new Set(unresolved)].join(", ")}`)
+if (templates.length === 0) {
+  console.error(`regen-hero: no templates under ${ASSET_DIR}`)
   process.exit(1)
 }
 
-await Bun.write(OUTPUT, html)
+for (const template of templates) {
+  let html = await Bun.file(ASSET_DIR + "/" + template).text()
+  for (const [key, value] of Object.entries(values)) {
+    html = html.replaceAll(`{{${key}}}`, value)
+  }
+
+  const unresolved = html.match(/{{[A-Z_]+}}/g)
+  if (unresolved) {
+    console.error(`regen-hero: ${template} carries unresolved placeholders ${[...new Set(unresolved)].join(", ")}`)
+    process.exit(1)
+  }
+
+  await Bun.write(ASSET_DIR + "/" + template.replace(/\.tmpl$/, ""), html)
+}
 '

package/src/commands/feedback-format.ts

@@ -2,8 +2,81 @@ const SLUG_FALLBACK = 'general'
 const SLUG_MAX_LENGTH = 40
 const TITLE_MAX_LENGTH = 72
 
+/**
+ * The one place the report's field list is spelled. The GitHub issue form is
+ * the other writer of this shape and enforces nothing a producer passes
+ * through, so validation sits here, on the path every filed report crosses.
+ */
+export const REQUIRED_FIELDS = ['Surface', 'Observed', 'Proposed fix'] as const
+
+/**
+ * Fields are `###` headings under the report's own `## Toolkit feedback` title,
+ * because that is the level a GitHub issue form emits for a field label. One
+ * parser therefore reads a report the CLI wrote and one a person submitted
+ * through the web form.
+ *
+ * The retired `**Surface:**` bold form is not accepted. Reading both would
+ * leave a producer free to keep emitting the shape this parser exists to
+ * retire, and the validator would then enforce nothing.
+ */
+const FIELD_HEADING = /^###\s+(.+?)\s*$/
+const FENCE = /^\s*(```|~~~)/
+
+export function parseSections(body: string): Map<string, string> {
+  const sections = new Map<string, string>()
+  let heading: string | undefined
+  let lines: string[] = []
+  let fenced = false
+
+  const flush = (): void => {
+    if (heading === undefined) return
+    sections.set(heading.toLowerCase(), lines.join('\n').trim())
+  }
+
+  for (const line of body.split('\n')) {
+    // A Repro field routinely carries a fenced block, and a `###` comment
+    // inside one is shell rather than the next field. Reading it as a heading
+    // splits the section and drops everything under it.
+    if (FENCE.test(line)) fenced = !fenced
+    const match = fenced ? null : line.match(FIELD_HEADING)
+    if (match?.[1] === undefined) {
+      lines.push(line)
+      continue
+    }
+    flush()
+    heading = match[1]
+    lines = []
+  }
+  flush()
+
+  return sections
+}
+
+export function readField(body: string, field: string): string | undefined {
+  const value = parseSections(body).get(field.toLowerCase())
+  return value ? value : undefined
+}
+
+/**
+ * The first required field the report does not carry, or `undefined` when it
+ * carries them all. One name rather than a list, because a reporter repairs one
+ * field at a time and the next run names the next gap.
+ */
+export function missingField(body: string): string | undefined {
+  const sections = parseSections(body)
+  for (const field of REQUIRED_FIELDS) {
+    const value = sections.get(field.toLowerCase())
+    if (!value) return field
+  }
+  return undefined
+}
+
+export function missingFieldMessage(field: string): string {
+  return `Feedback report is missing its "### ${field}" section. Every report needs ${REQUIRED_FIELDS.map((name) => `### ${name}`).join(', ')}.`
+}
+
 function surfaceField(body: string): string | undefined {
-  return body.match(/\*\*Surface:\*\*\s*([^\n]+)/i)?.[1]?.trim()
+  return readField(body, 'Surface')?.split('\n')[0]?.trim()
 }
 
 export function deriveSlug(body: string): string {

package/src/commands/feedback.ts

@@ -1,10 +1,16 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import type { Command } from 'commander'
-import { deriveSlug, deriveTitle } from '@/commands/feedback-format'
+import {
+  deriveSlug,
+  deriveTitle,
+  missingField,
+  missingFieldMessage,
+} from '@/commands/feedback-format'
 import { PROJECT_ROOT } from '@/project-root'
 import { creationRel } from '@/record-root'
 import { createGithubIssue } from '@/github'
+import { issueFailureMessage } from '@/github-format'
 import { frameError, frameSuccess, palette } from '@/ui'
 
 function readStdin(): Promise<string> {
@@ -78,27 +84,35 @@ export function register(program: Command): void {
         return
       }
 
+      // Both write paths, not `--github` alone. A report missing its surface is
+      // no more useful sitting in the triage queue on disk than in the tracker.
+      const absent = missingField(body)
+      if (absent) {
+        frameError(missingFieldMessage(absent))
+        process.exitCode = 1
+        return
+      }
+
       if (opts.github) {
-        const url = await createGithubIssue({
+        const result = await createGithubIssue({
           title: deriveTitle(body),
           body,
           labels: ['feedback'],
         })
-        if (url) {
-          frameSuccess('canon feedback', url)
-          process.stdout.write(`${url}\n`)
+        if (result.ok) {
+          frameSuccess('canon feedback', result.url)
+          process.stdout.write(`${result.url}\n`)
           return
         }
+        const reason = issueFailureMessage(result)
         if (!isToolkitSource()) {
-          frameError(
-            'gh unavailable and no toolkit source to fall back to. Install gh, or file it at https://github.com/erclx/canon/issues/new',
-          )
+          frameError(`${reason} No toolkit source to fall back to.`)
           process.exitCode = 1
           return
         }
         const { NC, YELLOW } = palette(process.stderr)
         process.stderr.write(
-          `${YELLOW}! gh unavailable, wrote local scratch instead${NC}\n`,
+          `${YELLOW}! ${reason} Wrote local scratch instead.${NC}\n`,
         )
       }