@erclx/canon 5.17.0 → 5.19.0

package/README.md

@@ -68,7 +68,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 | Standards      | Authoring conventions for commits, branches, plans, tasks, and markdown                                                  | Opened by name, read by name with `canon standards <name>`      |
 | Tooling stacks | Golden configs, seeds, and a reference per framework                                                                     | Laid down by `canon init`, reconciled by `canon tooling sync`   |
 | Design system  | Ships a `DESIGN.md` token format, a skill that drafts one from an existing project or from scratch, and a render command | `canon design render`                                           |
-| Slides         | A `SLIDES.md` source format with a layout catalog                                                                        | `canon slides render` writes PowerPoint                         |
+| Slides         | A `SLIDES.md` source format with a layout catalog, or a folder of HTML slides rebuilt as editable shapes                 | `canon slides render` writes PowerPoint                         |
 | Teach          | Lessons, sources, and a glossary in one workspace, rendered to a small site                                              | `canon teach`                                                   |
 | Canvas         | Pages of HTML frames on a local pan and zoom surface, each frame drawn with the project's tokens                         | `canon canvas serve`                                            |
 | Transcripts    | A YouTube transcript with metadata frontmatter                                                                           | `canon transcripts <url>` writes it into any repo               |

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

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.17.0",
+  "version": "5.19.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/deploy-app/REQUIREMENT.md

@@ -0,0 +1,44 @@
+---
+name: deploy-app
+description: What the deploy setup gap is on each host, which of the manual steps this skill closes, and why the credential and the custom domain stay the operator's
+---
+
+# Deploy app requirement
+
+## Gap
+
+Without this skill, a deploy setup is a sequence performed from memory. Most of its repeated acts touch a service rather than the tree, so no workflow file can absorb them. One of those acts has already cost a broken deploy: the account ID displayed in the Cloudflare dashboard is truncated, and a value copied from there is wrong in a way that only shows up at deploy time. That is the Cloudflare instance of the general rule, that an ID comes from the host CLI's own session or files and never from a page a person copies out of.
+
+The same sequence repeats on Vercel with different calls, so a skill per host would duplicate every guard and stop. Picking the wrong host is its own failure: a project mid-migration carries both hosts' files, and a silent pick creates a project on the account the operator was leaving.
+
+## Must
+
+- Pick the host from the signals the project already carries, and ask the operator when it carries none or both
+- Create the host's project through its own CLI: `wrangler pages project create` or `vercel project add` and `vercel link`
+- Fetch every account, org, or project ID from the host CLI's own session or files rather than have it typed or pasted
+- Stop for the operator to issue the API token and run `gh secret set` for it themselves
+- Verify every secret the host needs is present with `gh secret list` before continuing
+- Stop for the operator at the custom domain step, since DNS sits outside the tree
+- Call `wrangler`, `vercel`, and `gh` directly for every step those tools already cover
+
+## Must not
+
+- Accept an API token as input in any form. The toolkit verifies a secret exists, never what it contains.
+- Take an ID from the operator rather than from the host CLI's own session or files
+- Default to a host when the signals are absent or disagree
+- Reimplement a host CLI call or `gh secret set` as a hand-built API call
+- Seed a deploy workflow for Vercel, whose git integration already deploys on push
+- Open a pull request or merge
+
+## Guards
+
+- `wrangler` or `vercel` not authenticated: stop and name the login command
+- `gh` not authenticated: stop and name the login command
+- A secret missing after the token stop: stop and name which one
+
+## Out of scope
+
+- Attaching a custom domain through the Cloudflare REST API instead of the dashboard. Measured absent from `wrangler pages` at plan time and the REST API was not read, so the dashboard stop stays for this pass.
+- Running the deploy itself once secrets and the domain are set. On Cloudflare that is the seeded `deploy.yml` workflow, triggered by a push to main. On Vercel it is the git integration.
+- A Vercel `tooling/` stack or a CI-gated Vercel deploy workflow.
+- Reconfiguring an existing project's build settings on either host.

package/claude/skills/deploy-app/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: deploy-app
+description: Sets up a deploy for the current project on Cloudflare Pages or Vercel by picking the host the project already carries, creating the host's project, setting the IDs it needs as repository secrets, and stopping for the operator to issue the API token and attach the custom domain. Calls `wrangler`, `vercel`, and `gh` rather than reimplementing them. Use when asked to "set up the deploy", "deploy this to Cloudflare Pages", "deploy this to Vercel", "set up the Pages project", "set up a Vercel project", or "connect this repo to Cloudflare". Do NOT use to run an already-configured deploy, which the host's own push trigger does, or to reconfigure an existing project's build settings.
+---
+
+# Deploy app
+
+Runs the one-time setup a deploy needs before the host can publish on push, stopping for the acts only the operator can take. The procedure is the same on every host, and each host's CLI calls and stop points live in its own reference.
+
+## Guards
+
+- Never accept an API token as input, in a prompt, an argument, or a file. Verify a secret's presence with `gh secret list` rather than asking for or reading its content.
+- Read every account, org, or project ID from the host CLI's own session or files, never from the operator, and pipe it into `gh secret set` rather than reporting it first.
+- Never reimplement a host CLI call or `gh secret set` as a hand-built HTTP call. Call the tools directly.
+- If the project name is not supplied, derive it from the repository's own name (`basename` of `git remote get-url origin`, stripped of a trailing `.git`) and confirm it in the preview rather than asking first.
+
+## Step 1: pick the host
+
+Read the tree for these signals before running any command. A file that exists counts as a signal even when it is empty or stale, since the host reference's own guard is what judges whether it still works.
+
+| Signal                                                                   | Host              |
+| ------------------------------------------------------------------------ | ----------------- |
+| `wrangler.toml` or `wrangler.jsonc` at the root                          | cloudflare        |
+| a `pages deploy` line in any `.github/workflows/` file                   | cloudflare        |
+| `.vercel/project.json`                                                   | vercel            |
+| `vercel.json` at the root                                                | vercel            |
+| a `wrangler` or `vercel` entry in `package.json` scripts or dependencies | the host it names |
+
+- Signals for one host only: take that host.
+- Signals for both, or for neither: ask the operator through the structured question surface, naming each signal found. Never default to a host, since a silent pick deploys to the wrong account.
+- A host the operator named in the request wins over the signals. Say which signals disagreed with it, if any.
+
+Report the pick on one line before the next step: `Host: <host>, from <signal>`.
+
+## Step 2: check gh
+
+If `gh auth status` fails, stop: `❌ gh is not authenticated. Run gh auth login, then re-invoke.`
+
+## Step 3: run the host's steps
+
+Read `${CLAUDE_SKILL_DIR}/references/<host>.md` for the host Step 1 picked, `cloudflare.md` or `vercel.md`, and run its steps in order, stopping wherever it stops. Each reference opens with its own CLI guard, creates the project, sets the IDs as secrets, stops for the token, verifies the secrets, stops for the custom domain, and hands off.
+
+## Step 4: hand off
+
+Report that setup is complete and name what deploys on the next push, in the words the host reference's handoff gives. Do not invoke `git-pr` or `git-ship` from here. The operator or the controlling session decides when to open that pull request.

package/claude/skills/{deploy-cloudflare/SKILL.md → deploy-app/references/cloudflare.md}

@@ -1,19 +1,15 @@
 ---
-name: deploy-cloudflare
-description: Sets up a Cloudflare Pages deploy for the current project by creating the Pages project, fetching the account ID, and stopping twice for the operator to issue the API token and attach the custom domain. Calls `wrangler` and `gh` rather than reimplementing them. Use when asked to "set up Cloudflare deploy", "deploy this to Cloudflare Pages", "set up the Pages project", or "connect this repo to Cloudflare". Do NOT use to run an already-configured deploy, which the seeded workflow does on push, or to reconfigure an existing Pages project's build settings.
+title: Cloudflare Pages
+description: The wrangler and gh calls a Cloudflare Pages deploy needs, the two stops for the API token and the custom domain, and the handoff to the seeded deploy workflow
 ---
 
-# Deploy Cloudflare
+# Cloudflare Pages
 
-Runs the one-time setup a Cloudflare Pages deploy needs before the seeded `deploy.yml` workflow can run, stopping twice for the two acts only the operator can take.
+Run these steps once the body's Pick step resolves to Cloudflare.
 
-## Guards
+## Guard
 
 - If `wrangler whoami` fails, stop: `❌ wrangler is not authenticated. Run wrangler login, then re-invoke.`
-- If `gh auth status` fails, stop: `❌ gh is not authenticated. Run gh auth login, then re-invoke.`
-- Never accept a Cloudflare API token as input, in a prompt, an argument, or a file. Verify a secret's presence with `gh secret list` rather than asking for or reading its content.
-- Never reimplement `wrangler pages project create` or `gh secret set` as a hand-built HTTP call. Call the tools directly.
-- If the project name is not supplied, derive it from the repository's own name (`basename` of `git remote get-url origin`, stripped of a trailing `.git`) and confirm it in the preview rather than asking first.
 
 ## Step 1: create the Pages project
 

package/claude/skills/deploy-app/references/vercel.md

@@ -0,0 +1,72 @@
+---
+title: Vercel
+description: The vercel and gh calls a Vercel deploy needs, the two stops for the token and the custom domain, and the handoff to the git integration that deploys on push
+---
+
+# Vercel
+
+Run these steps once the body's Pick step resolves to Vercel. Read `vercel <command> --help` before each call, since flags move between CLI releases and the installed one is the authority.
+
+## Guard
+
+- If `vercel whoami` fails, stop: `❌ vercel is not authenticated. Run vercel login, then re-invoke.`
+- If `command -v jq` fails, stop: `❌ jq is not installed. Install it, then re-invoke.` Step 3 pipes its output into a secret, and a missing reader would set that secret empty while `gh secret list` still lists its name.
+
+## Step 1: create and link the project
+
+Skip the `project add` when `.vercel/project.json` already exists, and run the link anyway. A file left from a deleted or renamed project still counts as a signal, so the link is what judges it, failing on a project that is gone and rewriting the file against the one that answers.
+
+```bash
+vercel project add <project-name>
+vercel link --yes --project <project-name>
+```
+
+The link writes `.vercel/project.json` and adds `.vercel` to `.gitignore`. Report the command's own failure output and stop rather than retrying on a name collision. A project already existing under that name is the operator's to resolve.
+
+## Step 2: connect the repository
+
+```bash
+vercel git connect
+```
+
+Vercel deploys on push only once the project is connected to the repository, so this call is what makes the handoff true. Report its failure output and stop, since a project with no connection publishes nothing on push.
+
+## Step 3: set the org and project IDs
+
+Read both IDs from `.vercel/project.json`, which the link just wrote, rather than asking the operator to copy them from the dashboard. Confirm the file carries both before setting anything, since `jq -r` prints `null` for a missing key and exits zero, and `gh secret list` in Step 5 reads names rather than values:
+
+```bash
+jq -e '(.orgId | type == "string" and length > 0) and (.projectId | type == "string" and length > 0)' .vercel/project.json >/dev/null
+```
+
+On a non-zero exit, stop: `❌ .vercel/project.json carries no orgId or projectId. Delete it and re-invoke so the link writes it again.` Otherwise pipe each ID straight into its secret rather than printing it first:
+
+```bash
+jq -r .orgId .vercel/project.json | gh secret set VERCEL_ORG_ID
+jq -r .projectId .vercel/project.json | gh secret set VERCEL_PROJECT_ID
+```
+
+No workflow reads these today. They are what a GitHub Actions job calling `vercel` reads, so a project that later moves to CI-gated deploys finds them set.
+
+## Step 4: stop for the token
+
+Stop: `⏸ Create a Vercel token at the Vercel account settings, then run: gh secret set VERCEL_TOKEN. Confirm here once that's done.`
+
+This is the one credential the skill never touches. Resume only once the operator confirms the token is set.
+
+## Step 5: verify the secrets
+
+```bash
+gh secret list
+```
+
+- `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`, and `VERCEL_TOKEN` present: continue.
+- Any missing: stop and name which one, with the command that sets it.
+
+## Step 6: stop for the custom domain
+
+`vercel domains add <domain> <project-name>` attaches the domain to the project, and the DNS record that points the domain at Vercel is the operator's. Run the add only when the operator names the domain, then stop: `⏸ Point <domain>'s DNS at Vercel as vercel domains inspect <domain> describes, then confirm here.`
+
+## Step 7: hand off
+
+Report that setup is complete and that Vercel's git integration deploys every push, with production on the default branch and a preview on every other. No workflow is seeded for Vercel, since one would deploy each push a second time.

package/docs/agents/architecture-record.md

@@ -1,11 +1,11 @@
 ---
 title: Architecture record
-description: The five findings canon context audit reads off the architecture record, being the entry cap, revisit sentence, and length gates the record states for itself, the claim coverage report, and the word counts
+description: The findings canon context audit reads off the architecture record, being the entry cap, revisit sentence, length, decision word, and risk bullet gates the record states for itself, the claim coverage report, and the word counts, plus the requirements record's word cap
 ---
 
 # Architecture record
 
-Five findings from `canon context audit` read `canon/ARCHITECTURE.md` rather than a folder, and only the first three are facts. The other checks the audit runs are in `context-audit-checks.md`.
+Seven findings from `canon context audit` read `canon/ARCHITECTURE.md` rather than a folder, and only the first five are facts. One more reads `canon/REQUIREMENTS.md`. The other checks the audit runs are in `context-audit-checks.md`.
 
 The entry cap check counts the record's decisions against the cap it states for itself, in a clause of the form `This record holds at most 12 decisions.` Like the length check, the cap belongs to the record rather than to the toolkit, so a record stating none is measured and never gated. A decision is a `###` heading outside a fenced block, so the template a standard shows does not count, and a heading carrying two decisions counts once. The JSON record carries what it read as `architecture.entryCap`, absent where the record states no cap, and the audit catalog counts a record past it as `recordOverCount`.
 
@@ -17,12 +17,20 @@ A record stating no such rule is measured and reported and never gated, which is
 
 What the derivation costs where it does apply is that the ceiling rises when a decision is added and falls for nothing, so the check passes exactly when the file grew. It gates anyway, because a record that states a limit for itself and makes it computable from a count has turned it into a fact, which is what separates it from every judgment the audit reports. A rewrite of the declaring sentence past the clauses the check reads falls back to reporting rather than to a stale ceiling, so the failure shows up in the run's own output.
 
+The decision word check counts each decision's prose against the cap the record states in a clause of the form `at most 150 words a decision`. The count runs below the `###` heading with fenced lines dropped, so neither the heading nor a template block inside a decision counts, and the report and the gate read the same number. The JSON record carries the clause as `architecture.wordCap`, and the audit catalog counts the decisions past it as `recordOverWords`, absent where the record states no clause.
+
+The risk bullet check counts every list item under `## Risks / open questions`, nested ones included, against a clause of the form `at most 6 risk bullets`, since a nested bullet is weight the reader pays for like any other. Both clauses can share the entry cap's sentence, and each gates only a record stating it, for the reason the cap does. A record stating a risk cap and carrying no Risks section is reported as absent rather than passed as zero bullets. The JSON record carries the clause as `architecture.riskCap` and the count as `architecture.risksBullets`, and the audit catalog counts a section past its cap as `recordOverRisks`, absent where the record states no clause.
+
 The coverage report classifies each decision as carrying a countable claim, a structural invariant, or neither, then reports each testable entry against whether it names a check that exists. A countable claim carries a figure a run could recompute, and an invariant quantifies over a named tree closely enough that a walk could falsify it. A check is a `scripts/**.sh` path the entry spells that is on disk, or a `canon` invocation matching a registered audit, so coverage reads the entry rather than the tree and a claim some check happens to cover without the entry saying so reads as unchecked.
 
 Three limits are stated on every run rather than hidden. The countable signal reads digits alone, so a measured claim written in words reads as uncounted. Entries are counted by heading, and one heading holding several decisions counts once. Nothing is stored, so an entry rewritten tomorrow is classified afresh the next time the verb runs and no verdict goes stale.
 
 The report gates nothing. Deciding whether a sentence states a claim is a judgment no parser settles, so the output names candidates for a reader. This answers a different question from the verification anchors `standards/architecture.md` describes, which record that one cited number was re-read. That mechanism says whether a marked figure held, and this one says how much of the record could be checked at all.
 
-The fifth finding is a word count, measured in words rather than lines: one figure for the whole record and one per decision. `standards/architecture.md` asks a session to judge the file's weight by reading it rather than by counting it, and reads the word figure alongside that judgment when one is available. A paragraph written one source line to a paragraph passes the rendered-line measure other checks use while still reading heavy, which is the gap a word count closes without turning into a second cap.
+The seventh finding is a word count for the whole record, measured in words rather than lines. A paragraph written one source line to a paragraph passes the rendered-line measure other checks use while still reading heavy, which is the gap a word count closes. The whole-record figure gates nothing under any mode, since the per-decision cap above already bounds what a decision adds.
+
+The `## Risks / open questions` section is weighed the same way, reported apart from the whole-record figure. The JSON record carries the whole-record figure as `architecture.words`, the section figure as `architecture.risksWords` where the record carries the heading, and the per-decision figure as `architecture.decisions[].words`.
+
+## The requirements record
 
-The `## Risks / open questions` section is weighed the same way, reported apart from the whole-record figure since the standard singles it out for holding only what is still open. This finding gates nothing under any mode. The JSON record carries the whole-record figure as `architecture.words`, the section figure as `architecture.risksWords` where the record carries the heading, and the per-decision figure as `architecture.decisions[].words`.
+The audit reads `canon/REQUIREMENTS.md` under its own step and counts every word below the frontmatter against the cap the record states in a clause of the form `This record holds at most 600 words.` The cap is the record's own, so a record stating none is measured and never gated, and a project with no record is reported as out of scope. The JSON record carries the reading as `requirements`, null where the project carries no record and absent under `--citations-only`, and the audit catalog counts a record past its cap as `requirementsOverWords`.

package/docs/agents/canvas.md

@@ -1,6 +1,6 @@
 ---
 title: Canvas
-description: The canvas server, its content format, and the verbs that list, arrange, select, and capture frames
+description: The canvas server, its content format, and the verbs that list, arrange, select, edit, and capture frames
 ---
 
 # Canvas
@@ -29,6 +29,18 @@ The operator can also pick one element inside a frame, by clicking it on the sur
 
 A pick is refused as `address-mismatch` when the browser builds elements the file never states, such as a `tbody` a table leaves out or the document wrapper around a fragment. The shell sends its own element count beside the index, so a frame the two sides count differently is reported rather than recorded against the wrong element. A pick is refused as `stale-address` when the frame file changed between the frame being served and the pick arriving, since every served frame carries the hash of its file and the shell sends that hash back.
 
+## Edit
+
+`canvas edit <page>/<frame> --element <index> --set <property>=<value>` sets one property of the element at that index, the same index `canvas selection` reports. The properties are `text`, `color`, `background-color`, `font-size`, `font-weight`, `width`, `height`, `padding`, `gap`, and `flex-direction`. A style property is written into the element's inline `style`, replacing that property and leaving the others as they were, and an empty value drops it.
+
+`text` replaces the text of an element holding text alone and refuses one holding other elements as `not-text-only`. Every byte outside the element stays as it was. `--json` emits the page, frame, file, path, and the file's new `hash`.
+
+The operator edits the same set from the inspector, which posts to the same writer with the hash the frame was served with. An edit made against a version of the file Claude has since rewritten is refused as `stale-address` and the shell reloads the frame, so nothing lands on a shifted element. A color picked from the project's tokens is written as `var(--<name>)`. Both writers take the frame file's lock, and an edit that keeps the selected element where it was keeps the selection fresh.
+
+Inline style beats a class, so an operator's edit masks a class change Claude makes later. Read a frame's inline styles before restyling it, and remove one the change should replace. A property outside the set, or a value carrying `;`, `{`, `}`, `<`, `>`, or a line break, is refused as `invalid-edit`.
+
+The Theme tab in the shell lists what the token stylesheet defines, grouped as color, spacing, radius, font family, font size, and other. The page record at `/api/pages` carries the same list as `tokens.groups`.
+
 ## Capture
 
 `canvas capture <page>/<frame>` renders one frame as a PNG, and `canvas capture <page>` renders every frame on the page. Each goes through a server started for the call, so the injected tokens are in the image, and renders at the frame's own width from the layout, so a media query resolves there. It never captures the file on disk.

package/docs/agents/commands.md

@@ -34,7 +34,7 @@ One row per top-level command, in the order `canon --help` prints them. A domain
 | `canon drive <url> <run>`   | Walk a page through named interactions and measure each state                   |
 | `canon transcripts <url>`   | Fetch a YouTube transcript with metadata frontmatter (needs `yt-dlp`)           |
 | `canon teach <verb>`        | Open and author learning workspaces                                             |
-| `canon canvas <verb>`       | Serve a local canvas of pages and HTML frames, arrange them, and capture them   |
+| `canon canvas <verb>`       | Serve a local canvas of pages and HTML frames, arrange, edit, and capture them  |
 | `canon sandbox [cat:cmd]`   | Run sandbox scenarios, toolkit-only like the tree it reads                      |
 | `canon tasks <verb>`        | Read and write the task board, the plans it cites, and its archive              |
 | `canon intake <verb>`       | Report intake folders and write answers into them                               |
@@ -96,7 +96,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 - `demo`, in `demo.md`: `compile`, `run`, `frames`
 - `inventory`, described above: `run`
 - `teach`, in `teach.md`: `list`, `open`, `resource`, `glossary`, `lesson`, `stylesheet`, `nav`, `render`
-- `canvas`, described below: `serve`, `list`, `page add`, `page rename`, `frame add`, `frame move`, `selection`, `capture`
+- `canvas`, described below: `serve`, `list`, `page add`, `page rename`, `frame add`, `frame move`, `selection`, `edit`, `capture`
 - `sandbox`, in `sandbox.md`: `reset`, `clean`, `check`, `coverage`
 - `tasks`, in `tasks.md`: `next-label`, `archive`, `decline`, `plan-citations`, `plan-answers`, `plan-branch`, `plan-reach`, `plan-link`, `pull-request`, `outcome`, `list`, `validate`
 - `intake`, in `intake.md`: `list`, `answer`
@@ -129,6 +129,7 @@ Subcommands no other page describes:
 - `claude skills rank` scores either skill corpus's descriptions against a case corpus by TF-IDF cosine similarity, reporting rank-one and top-three (`--cases <path>`).
 - `design regen` rewrites this repository's `canon/DESIGN.md` from `src/design/tokens.ts` and `src/design/base.css` from `src/design/neutral.ts`. `design css` emits the tokens and components as CSS on stdout, with `--no-components` for properties alone, and `design render` declares each vendored face the typography table names under `--embed-fonts`.
 - `slides render` renders a `.claude/SLIDES.md` source into a PowerPoint deck and reports any unrecognized layout name on stderr, and `slides list --json` emits the layout catalog.
+- `slides render --source <folder>` lays out each `.html` file in filename order in Chromium at 1280 by 720 and rebuilds it as editable shapes. Each element drawn as a picture prints one `✗` line on stderr naming the slide, the selector, and the properties that forced it. A link left out, being a `#slide-N` past the deck's end or any target that is neither that nor an absolute URL, prints one too, and the exit stays 0.
 - `canvas`, with its verbs, content format, and write routes, is described in `canvas.md`.
 - `labels scan` fails a pull request or a posted review whose title, body, or review comment carries a phase label, a label a code span quotes, a gitignored record path, a session link, a title word no dictionary holds, or a title breaking `standards/pr.md`'s format, casing, or length rule (`--event`, `--body-file`, `--json`).
 - `repo metadata propose` compares a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing, and `repo metadata apply` writes an explicitly supplied set through `gh repo edit` (`--description`, `--homepage`, `--topics`).

package/docs/agents/context-audit-checks.md

@@ -65,7 +65,7 @@ Fenced blocks are excluded, which keeps a pinned version in an install command f
 
 ## The architecture record
 
-Five findings read `canon/ARCHITECTURE.md` rather than a folder: an entry cap, a revisit sentence closing each decision, and a length ceiling, each gating only where the record states it for itself, a claim coverage report, and a word count. What each reads and why the last two gate nothing are in `architecture-record.md`.
+Seven findings read `canon/ARCHITECTURE.md` rather than a folder: an entry cap, a revisit sentence closing each decision, a length ceiling, a word cap a decision, and a risk bullet cap, each gating only where the record states it for itself, a claim coverage report, and a word count. One more reads `canon/REQUIREMENTS.md` against the word cap it states. What each reads and why the last two architecture findings gate nothing are in `architecture-record.md`.
 
 ## Wireframe states
 

package/docs/agents/context-audit.md

@@ -5,7 +5,7 @@ description: Running the audit, its flags and folder scope, the exit codes, the
 
 # Context audit
 
-`canon context audit [path]` reports the structural state of the folders following the index-plus-entry contract, meaning a generated `index.md` beside entries carrying frontmatter, and it measures `canon/ARCHITECTURE.md` beside them. It reads and reports. Fixing what it finds is separate work. What each finding means is in `context-audit-checks.md`, and what the architecture record's five findings mean is in `architecture-record.md`.
+`canon context audit [path]` reports the structural state of the folders following the index-plus-entry contract, meaning a generated `index.md` beside entries carrying frontmatter, and it measures `canon/ARCHITECTURE.md` beside them. It reads and reports. Fixing what it finds is separate work. What each finding means is in `context-audit-checks.md`, and what the architecture and requirements records' findings mean is in `architecture-record.md`.
 
 Findings stated over every markdown file rather than over a context entry are measured by `canon markdown audit`, described in `markdown-audit.md`. That command resolves no folder, so it reaches trees this one refuses.
 
@@ -37,11 +37,11 @@ A run where no requested name resolves refuses, whichever list it read. Naming t
 
 ## Exit codes
 
-Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a gating finding. An unresolved citation gates under every mode. An architecture record that states its own line allowances gates when it is past the ceiling those derive, on any run that measures it, which is every mode except `--citations-only`. A record that states an entry cap gates the same way when it holds more decisions than the cap, and one stating that every decision closes with a revisit sentence gates when a decision lacks it. A record stating none of the three is reported and never gated.
+Exit codes are `0` for a clean run, `1` for a refusal, and `2` for a gating finding. An unresolved citation gates under every mode. An architecture record that states its own line allowances gates when it is past the ceiling those derive, on any run that measures it, which is every mode except `--citations-only`. A record that states an entry cap gates the same way when it holds more decisions than the cap, one stating that every decision closes with a revisit sentence gates when a decision lacks it, and one stating a word cap a decision or a risk bullet cap gates past either. A requirements record stating a word cap gates past it. A record stating none of these is reported and never gated.
 
-`bun run check` in the toolkit repository reads all three of the record's rules through its own Architecture record stage rather than through this verb, since the verb's only gating stage there runs `--citations-only` and never opens the record.
+`bun run check` in the toolkit repository reads every one of these rules through its own Canonical records stage rather than through this verb, since the verb's only gating stage there runs `--citations-only` and never opens either record.
 
-Entry length, reference form, table, provenance, the record's claim classification, and every word figure print and return `0` under every mode, because each is a judgment or a weight read alongside one, and failing a push on either would make the check something to route around.
+Entry length, reference form, table, provenance, the record's claim classification, and every word figure no record caps print and return `0` under every mode, because each is a judgment or a weight read alongside one, and failing a push on either would make the check something to route around.
 
 Required-section, index, and wireframe-states findings sit between the two. All three are answerable from the file rather than weighed, so `--gate` promotes them to failing codes while a bare run leaves them advisory. Sketch-with-evidence sits with the printed measures instead, for the reason `context-audit-checks.md` states: it reads a whole entry against whether any of its states has evidence, not one layout against its own evidence, so a conforming file can still trip it. The toolkit runs the bare form against itself and the widened form against the seed tree, described below.
 

package/docs/agents/index.md

@@ -8,9 +8,9 @@ category: Agent surface
 
 CLI catalog and invocation rules for agents, split by command domain. Start with overview.
 
-- [Architecture record](architecture-record.md): The five findings canon context audit reads off the architecture record, being the entry cap, revisit sentence, and length gates the record states for itself, the claim coverage report, and the word counts
+- [Architecture record](architecture-record.md): The findings canon context audit reads off the architecture record, being the entry cap, revisit sentence, length, decision word, and risk bullet gates the record states for itself, the claim coverage report, and the word counts, plus the requirements record's word cap
 - [Audits](audits.md): Running every health check as one set, what the single verdict means, the exit code each outcome takes, the retained baseline and the delta it reports, and which corpora are kept out of the record
-- [Canvas](canvas.md): The canvas server, its content format, and the verbs that list, arrange, select, and capture frames
+- [Canvas](canvas.md): The canvas server, its content format, and the verbs that list, arrange, select, edit, and capture frames
 - [Capture](capture.md): Rendering HTML sources to PNG, what the command asserts about fonts, and why the selector has no default
 - [Census](census.md): Tracked-plus-untracked file count, a breakdown by extension, and a line total that skips whatever reads as binary
 - [Command catalog](commands.md): Every top-level command with its purpose, each domain's subcommands and the page describing them, the browser commands, and the version skew report

package/docs/agents/teach.md

@@ -126,9 +126,15 @@ The link opens the named workspace's contents page, or the root listing when no
 
 The JSON record is one line carrying the `nav` fields, then `served`, the absolute folder, and the server's `host`, `port`, `entry`, `url`, and `entryExists`. A lesson `nav` skips lands in `skipped` and the server still starts, since a partial refresh is still worth viewing. A `nav` refusal starts no server.
 
+While it runs, `up` watches the teach root. A change there, such as a lesson, a workspace, a glossary term, or a reference page added by hand or by another `teach` verb, runs the `nav` pass again, and every open page reloads once that pass changes what is served. Passes run one at a time, so a burst of saves costs one more pass rather than several at once. A pass `nav` refuses, such as one over a workspace deleted while it was served, is reported on stderr, the server keeps running, and no page reloads.
+
+Each refresh is logged to stderr, so stdout stays the one record line. Dotfiles and editor backups ending in `~` start no pass.
+
+The reload script is added to each page as the server sends it and never written to disk, so a page saved from the browser, a promoted lesson, and a committed fixture carry no trace of it. The script listens on `/__live`, which answers only a request naming the server by its loopback address or `localhost`.
+
 Viewing writes. Every page and generated stylesheet `nav` owns is rewritten first, which on a committed fixture shows as a diff. To serve without rewriting anything, `canon teach list <topic>` ends its human output with a `canon serve` line for that workspace, with the teach folder written relative to the cwd, or absolute when it sits outside it. The JSON record of `list` carries no such field.
 
-`canon serve` itself stays general, since nothing about serving a directory is specific to a learning workspace and the same verb carries a slide render and a design preview. What `up` adds in front of it is the refresh, which is teach-specific, and it serves through the same server rather than a second one.
+`canon serve` itself stays general, since nothing about serving a directory is specific to a learning workspace and the same verb carries a slide render and a design preview. What `up` adds in front of it is the refresh and the watch that repeats it, both teach-specific, and it serves through the same server rather than a second one.
 
 Read `url` off the record rather than building one from the port that was asked for. The verb walks forward past a port already in use, which is routine when a second workspace is already open, and the port it took is the one thing a composed URL gets wrong.
 

package/docs/workflow/skill-map.md

@@ -12,15 +12,15 @@ This page is the corpus the coverage claim is measured against: every name `cano
 
 ## Set up a project
 
-| Skill                     | When to use                                                                                                 |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `canon:target-setup`      | On a fresh scaffold, to detect the stack and run the install chain, or to reach one phase of it alone       |
-| `canon:canon-operator`    | On a project that already exists, to read what it carries before an install is picked                       |
-| `canon:sketch-design`     | Before `design-extract`'s greenfield path, to trace a design direction from reference images or URLs        |
-| `canon:design-extract`    | Before the first UI feature, to draft `canon/DESIGN.md`                                                     |
-| `canon:draft-diagram`     | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                        |
-| `canon:deploy-cloudflare` | Once a project is ready to publish, to set up its Cloudflare Pages deploy and stop for the token and domain |
-| `canon:repo-metadata`     | When the GitHub About text, homepage, or topics may have drifted, to reconcile them against the README      |
+| Skill                  | When to use                                                                                                 |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `canon:target-setup`   | On a fresh scaffold, to detect the stack and run the install chain, or to reach one phase of it alone       |
+| `canon:canon-operator` | On a project that already exists, to read what it carries before an install is picked                       |
+| `canon:sketch-design`  | Before `design-extract`'s greenfield path, to trace a design direction from reference images or URLs        |
+| `canon:design-extract` | Before the first UI feature, to draft `canon/DESIGN.md`                                                     |
+| `canon:draft-diagram`  | Once the architecture is written, to draft per-kind entries under `.canon/diagrams/`                        |
+| `canon:deploy-app`     | Once a project is ready to publish, to set up its Cloudflare or Vercel deploy and stop for token and domain |
+| `canon:repo-metadata`  | When the GitHub About text, homepage, or topics may have drifted, to reconcile them against the README      |
 
 ## Decide what to build
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.17.0",
+  "version": "5.19.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {
@@ -56,6 +56,7 @@
     "commander": "^13.1.0",
     "execa": "^9.5.2",
     "highlight.js": "^11.12.0",
+    "jszip": "^3.10.1",
     "playwright-core": "1.59.1",
     "pptxgenjs": "^4.0.1",
     "preact": "^11.0.0"

package/src/audits/catalog.ts

@@ -173,10 +173,17 @@ function architectureCounts(
     typeof record.entryCap === 'number' ? record.entryCap : undefined
 
   const revisitRequired = record.revisitRequired === true
+  const wordCap =
+    typeof record.wordCap === 'number' ? record.wordCap : undefined
+  const riskCap =
+    typeof record.riskCap === 'number' ? record.riskCap : undefined
+  const risksBullets =
+    typeof record.risksBullets === 'number' ? record.risksBullets : undefined
 
   let unverifiable = 0
   let unchecked = 0
   let lackingRevisit = 0
+  let overWords = 0
   for (const raw of decisions) {
     const entry = asObject(raw)
     const claim = entry?.claim
@@ -186,6 +193,13 @@ function architectureCounts(
     if (claim === 'neither') unverifiable += 1
     else if (checks === 0) unchecked += 1
     if (revisitRequired && entry?.revisit !== true) lackingRevisit += 1
+    if (
+      wordCap !== undefined &&
+      typeof entry?.words === 'number' &&
+      entry.words > wordCap
+    ) {
+      overWords += 1
+    }
   }
 
   return {
@@ -201,11 +215,39 @@ function architectureCounts(
     }),
     // Absent on a record stating no revisit clause, for the same reason.
     ...(revisitRequired && { recordMissingRevisit: lackingRevisit }),
+    // Absent on a record stating no word cap or no bullet cap, for the same
+    // reason, and the bullet key absent too on a record with no Risks section.
+    ...(wordCap !== undefined && { recordOverWords: overWords }),
+    ...(riskCap !== undefined &&
+      risksBullets !== undefined && {
+        recordOverRisks: risksBullets > riskCap ? 1 : 0,
+      }),
     recordUnverifiable: unverifiable,
     recordUnchecked: unchecked,
   }
 }
 
+/**
+ * Reads the requirements record's one cap, or nothing when the record is
+ * absent, states no cap, or the run never opened it.
+ *
+ * The key is optional rather than required the way `architecture` is, so a
+ * record from a binary predating it still counts its other findings.
+ */
+function requirementsCounts(
+  root: Record<string, unknown>,
+): Record<string, number> {
+  const record = asObject(root.requirements)
+  if (
+    record === undefined ||
+    typeof record.words !== 'number' ||
+    typeof record.wordCap !== 'number'
+  ) {
+    return {}
+  }
+  return { requirementsOverWords: record.words > record.wordCap ? 1 : 0 }
+}
+
 /**
  * The retained key for each verdict the sweep can return. A record rather than
  * a list, so the compiler fails here when the classifier gains a verdict,
@@ -261,6 +303,7 @@ function contextCounts(record: unknown): Record<string, number> | undefined {
 
   const architecture = architectureCounts(root)
   if (architecture === undefined) return undefined
+  const requirements = requirementsCounts(root)
 
   const counts = allOf({
     unresolvedCitations: lengthOf(asObject(root.citations)?.unresolved),
@@ -271,7 +314,9 @@ function contextCounts(record: unknown): Record<string, number> | undefined {
   })
 
   if (counts === undefined) return undefined
-  return architecture === 'absent' ? counts : { ...counts, ...architecture }
+  return architecture === 'absent'
+    ? { ...counts, ...requirements }
+    : { ...counts, ...architecture, ...requirements }
 }
 
 function markdownCounts(record: unknown): Record<string, number> | undefined {