@erclx/canon 5.40.0 → 5.42.0

package/claude/skills/design-taste/references/tells.md

@@ -5,39 +5,38 @@ description: The visual defaults a model reaches for when nothing states a direc
 
 # Machine tells in design
 
-Each item below is a shape rather than a value, which is why no ban list of colors or fonts reaches any of them. Read this before handing over anything a model drafted. Skip it on a small change to a surface that already has a settled direction.
+Each item below is a shape rather than a value, which is why no ban list of colors or fonts reaches any of them. Read this before handing over anything a model drafted, and skip it on a small change to a surface that already has a settled direction.
 
-The skill body carries the ten most common of these. This is the same catalog at full length, so an item appearing in both is one list rather than two.
-
-An item is a default to reach past, not a prohibition. A brief that explicitly asks for one gets it, and the point is that it was chosen rather than defaulted into.
+The skill body carries the ten most common of these, and this is the same catalog at full length. An item is a default to reach past, not a prohibition, so a brief that explicitly asks for one gets it, chosen rather than defaulted into.
 
 ## Composition
 
-- **The three equal cards.** Three identical boxes in a row under a heading is the most-reached-for feature section in existence. Reach for a two-column alternation, an asymmetric grid, a list with one item given weight, or a single worked example.
-- **One section shape repeated down the page.** A page where every section is a centered heading over a centered body reads flat whatever its palette. Vary alignment, container width and the ratio between sections.
+- **The three equal cards.** Three identical boxes in a row under a heading. Reach for a two-column alternation, an asymmetric grid, a list with one item given weight, or a single worked example.
+- **One section shape repeated down the page.** Every section a centered heading over a centered body reads flat whatever its palette. Vary alignment, container width and the ratio between sections.
 - **The centered hero over a dark wash.** Centered headline, centered subhead, two buttons, gradient behind. Reach for an asymmetric split, a full-bleed artifact, or content that starts immediately.
-- **Decoration standing in for structure.** Hairline grids, crosshairs, floating rules and corner marks added so a page feels designed. Use them where they organize real content and remove them where they do not.
-- **The corner floater.** A large left-aligned section heading with a small explanatory paragraph floating in the top right, aligned to nothing. Put the sub-text under the heading or build a real two-column header.
+- **Decoration standing in for structure.** Hairline grids, crosshairs, floating rules and corner marks added so a page feels designed. Keep them only where they organize real content.
+- **The corner floater.** A large left-aligned heading with a small paragraph floating top right, aligned to nothing. Put the sub-text under the heading or build a real two-column header.
 
 ## Content and labels
 
 - **Enumerated eyebrows.** `001 / Capabilities`, `Phase 02`, `Step 1`, `Stage One`. The content is the label. Where progression genuinely matters, use the verb.
 - **Poetic section labels.** "From the field", "On our desks", "Currently on the bench". Use the plain functional label or drop the label.
-- **Atmospheric strips.** City, time zone, temperature, coordinates, build version, last-sync time, placed for texture rather than information. Keep one only where it carries real state a reader acts on.
+- **Atmospheric strips.** City, time zone, temperature, coordinates, build version, last-sync time, placed for texture. Keep one only where it carries real state a reader acts on.
 - **Scroll cues.** "Scroll", an animated wheel, a downward arrow with a label. A reader looking at the top of a page knows what scrolling is.
-- **Decorative status dots.** A coloured dot before every nav item, list row or badge. Keep it only where it reports genuine state, and then sparingly.
-- **Filler verbs.** A verb chosen for its warmth rather than for what it reports, such as `elevate`, `unleash`, `empower` or `next-generation`. Name the thing the surface does.
-- **Placeholder that reads as placeholder.** Generic person names, egg avatars, invented company names of the `Acme` family, one portrait reused for several people, every item dated identically. Real collections are uneven and specific.
-- **Invented precision.** A figure like 4.1x or 48k either came from real data, is marked as sample, or does not appear. There is no fourth case. Inventing a number to look engineered is the version of this that gets shipped, because it reads as confidence.
+- **Decorative status dots.** A colored dot before every nav item, list row or badge. Keep it only where it reports genuine state, and then sparingly.
+- **Filler verbs.** A verb chosen for warmth rather than for what it reports, such as `elevate`, `unleash`, `empower` or `next-generation`. Name the thing the surface does.
+- **Placeholder that reads as placeholder.** Generic names, egg avatars, `Acme`-family companies, one portrait for several people, every item dated alike. Real collections are uneven and specific.
+- **Invented precision.** A figure like 4.1x or 48k came from real data, is marked as sample, or does not appear. An invented number gets shipped, because it reads as confidence.
 - **The fake screenshot built from boxes.** A product UI simulated out of styled rectangles inside a hero. Show the real thing, a real capture, or nothing.
-- **Copy nobody re-read.** Read every visible string once as a reader rather than as its author, before handing anything over. Rewrite what is grammatically broken, what carries a pronoun with no antecedent on the page, and what reaches for charm it has not earned. Plain beats clever and wrong, which is what a model drafting copy produces by default.
+- **Copy nobody re-read.** Read every visible string once as a reader rather than its author before handing over. Plain beats clever and wrong, which is what a model drafting copy produces by default.
+- **What the re-read rewrites.** A string that is grammatically broken, carries a pronoun with no antecedent on the page, or reaches for charm it has not earned.
 
 ## Surface and palette
 
 - **Glow as depth.** Outer glows and neon rims standing in for elevation. Use a border, a tint, or a real shadow with direction.
 - **Pure black and pure white as grounds.** Both are harsher than nearly any surface wants. Move off the extreme.
-- **Saturation everywhere.** An accent at full saturation next to neutrals that are also tinted leaves nothing to anchor on. Desaturate the neutrals and let one accent carry.
-- **The gradient as a substitute for a decision.** A gradient covering a section, a heading, or a button set, applied because the flat version looked plain. Flat is usually the fix for flat composition, not gradient.
+- **Saturation everywhere.** A full-saturation accent beside tinted neutrals leaves nothing to anchor on. Desaturate the neutrals and let one accent carry.
+- **The gradient as a substitute for a decision.** A gradient over a section, a heading, or a button set because flat looked plain. Flat composition is fixed by composition, not gradient.
 - **Uniform radius and uniform elevation.** Every card at the same radius with the same shadow flattens hierarchy. Let the thing that matters differ.
 
 ## Typography
@@ -49,28 +48,28 @@ An item is a default to reach past, not a prohibition. A brief that explicitly a
 
 ## Motion
 
-- **Motion nobody can justify.** Before adding any animation, say in one sentence what it communicates: hierarchy, sequence, feedback, or a state that changed. "It looked good" is not one of those. A sentence that will not come is the answer, and the animation goes.
+- **Motion nobody can justify.** Before adding any animation, name the hierarchy, sequence, feedback, or changed state it communicates. A sentence that will not come means it goes.
 - **The permanent loop.** Anything animating forever with no input. It costs attention on every frame and earns none back.
 - **Motion on arrival for everything.** Every section fading up on scroll. Reserve entrance motion for what genuinely needs the eye.
-- **Motion claimed but not present, or present but not claimed.** A surface described as restrained that animates on every scroll, or one described as fluid that sits still, has decided nothing. Ship the motion or drop the claim.
-- **Motion that ignores a reduced-motion preference.** Not a taste failure at all. It is a correctness failure the `ui` governance rules own, listed here only so a motion pass does not read this catalog as the whole of what motion owes.
+- **Motion claimed but absent, or present but unclaimed.** A "restrained" surface animating on every scroll, or a "fluid" one sitting still, has decided nothing. Ship the motion or drop the claim.
+- **Motion that ignores a reduced-motion preference.** A correctness failure the `ui` governance rules own, not a taste one. It sits here so a motion pass does not read this catalog as all motion owes.
 
 ## The countable limits
 
-These are the rules with numbers, so they are checked by counting rather than by judging. Every one came out of production testing by people shipping model-drafted pages.
+These rules carry numbers, so they are checked by counting rather than by judging. Every one came out of production testing by people shipping model-drafted pages.
 
 - **A layout family appears once.** Once a section uses a shape, no other section on the surface uses it. Eight sections need at least four distinct families.
-- **Two consecutive splits, never three.** Alternating image-left and image-right reads as considered twice and as filler by the third. Break it with a full-width section, a vertical stack, a grid, or anything else.
-- **One small uppercase label per three sections.** The tiny wide-tracked line above a heading is the single most over-reached default in model output. `interface-casing` carries the count. The fix is usually to delete it, since a section's position already says what it is.
+- **Two consecutive splits, never three.** Alternating image sides reads as considered twice and as filler by the third. Break it with a full-width section, a vertical stack, or a grid.
+- **One small uppercase label per three sections.** The most over-reached default in model output, with the count in `interface-casing`. Usually delete it, since position already says what a section is.
 - **One marquee.** Two sliding strips on one surface read as filler rather than as a device.
 - **Cells equal items.** A grid with a hole in it, or a blank tile at the end, means the grid was shaped before the content was counted. Reshape it.
-- **Over five items wants a different component.** A longer list is the lazy answer. Group into clusters, split into columns, give each item a card, make them scrollable, or collapse the tail behind a disclosure.
+- **Over five items wants a different component.** Group into clusters, split into columns, give each item a card, make them scrollable, or collapse the tail behind a disclosure.
 
 ## The first screen
 
-- **It fits.** The point and the primary action are both visible without scrolling. If the copy will not fit, the copy is too long or the type is too large, and the second is the more common cause.
+- **It fits.** The point and the primary action are both visible without scrolling. Copy that will not fit is too long or set too large, and the second is the more common cause.
 - **At most four text elements.** A label or a brand strip, a headline, a short supporting line, and the actions. That is the whole budget.
-- **Everything else moves down.** A small tagline under the actions, a trust strip, a pricing hint, a feature list, a row of faces. Each of those is a section of its own below, not a fifth element above.
+- **Everything else moves down.** A tagline under the actions, a trust strip, a pricing hint, a feature list, a row of faces. Each is a section of its own below, not a fifth element.
 - **Plan the type scale against the asset.** A headline wrapping to four lines is a size error rather than a length error.
 - **Logos go under it, never inside it.** A credibility row shares no space with the point.
 

package/claude/skills/design-taste/references/vocabulary.md

@@ -7,9 +7,11 @@ description: The layer, property, pattern and process terms this skill uses, so
 
 Terms used by `design-taste` and by the skills it is loaded alongside. It changes when a design round needs a name it cannot look up here.
 
-This glossary departs from one rule in `glossary.md`: an entry does not name where the term first appears. The material is five short files a reader can scan, so a location per entry costs more than it returns.
+This glossary departs from one rule in `glossary.md`, since an entry does not name where the term first appears. The material is five short files a reader can scan, so a location per entry costs more than it returns.
 
-Every other rule there holds, and the one deciding membership holds strictly. A term appears here once this skill's own material uses it, never ahead of that, and the section below records what was considered and left out.
+- Every other rule there holds, and the one deciding membership holds strictly
+- A term appears here once this skill's own material uses it, never ahead of that
+- The last section records what was considered and left out
 
 ## Layers
 
@@ -28,7 +30,7 @@ Ordered by when each settles, not alphabetically, since the order is the content
 ## Properties
 
 - **Casing**: whether text is set upper, lower, title or sentence case, treated as a hierarchy decision rather than a typing one.
-- **Density**: how much information a given area carries. High density is correct in an application surface and reads as clutter on a marketing one, which is why it belongs to the kind rather than to taste.
+- **Density**: how much information a given area carries. Correct in an application surface and clutter on a marketing one, so it belongs to the kind rather than to taste.
 - **Hierarchy**: the order a reader takes things in, produced by weight, color, space and position together rather than by size alone.
 - **Ground**: the surface a thing sits on, whether the page behind everything or the fill behind one element. Named apart from "background" because the relationship that matters is what sits against it.
 - **Line height**: the vertical distance from one baseline to the next, set against size rather than fixed across a scale. Avoid "leading", which names the same thing.
@@ -52,9 +54,9 @@ Named compositions, carried so an operator can ask for one by name instead of de
 
 How a draft is staged while unfinished.
 
-- **FPO**: a placeholder held at the true final size and marked as a placeholder, from print production where it abbreviates "for position only". Marking it is the point, since an unmarked stand-in gets read as a decision.
+- **FPO**: a placeholder held at the true final size and marked as one, from the print term "for position only". Marking it is the point, since an unmarked stand-in gets read as a decision.
 - **Greeking**: standing text in for copy that does not exist yet, of which lorem ipsum is the common form. Correct while judging space and wrong once an arm is judged on content.
-- **Grey-box**: drawing every element as a flat neutral block so the layers above the one under judgment are removed from view. Avoid "wireframe", which reads as a deliverable rather than a drafting stage.
+- **Grey-box**: drawing every element as a flat neutral block, removing the layers above the one under judgment from view. Avoid "wireframe", which reads as a deliverable rather than a stage.
 
 ## Terms this vocabulary deliberately does not carry
 

package/claude/skills/document-health/references/axes.md

@@ -11,78 +11,102 @@ The skill body holds the order, the guards, and the report shape. This holds the
 
 ## Length
 
-**Measures:** whether a document, or a passage inside it, has grown past what a reader takes in one pass.
+| Field          | Value                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------ |
+| Measures       | Whether a document, or a passage inside it, has grown past what a reader takes in one pass |
+| Verb           | `canon markdown audit --json`                                                              |
+| Evidence class | `measured`                                                                                 |
 
-**Verb:** `canon markdown audit --json`.
-
-**Evidence class:** `measured`.
-
-The record carries the checkpoints it read against under `checkpoints` and the per-file weights under `entries`. Read both from the record rather than from a number stated here, since the CLI moves a checkpoint on its own cadence and a copy of one goes stale in place.
-
-Four weights answer this axis, each naming a different shape of overgrowth:
+The record carries the checkpoints it read against under `checkpoints` and the per-file weights under `entries`. Read both from the record rather than from a number stated here, since the CLI moves a checkpoint on its own cadence and a copy goes stale in place.
 
 - `heavyBullets`: a top-level bullet past the character checkpoint, which is a paragraph wearing a dash
 - `heavyParagraphs`: a paragraph past the sentence or character checkpoint
 - `longestRun`, against `longestRunLine`: unbroken rendered lines between headings, which is the depth checkpoint
 - `cadence`, carrying `measured`, `flat`, and `repeating`: sentence-length spread and repeated openers
 
-Weight is a judgment a reader settles rather than a defect, which the verb states for itself and which this axis carries forward. A finding here is an argument for a split or a trim rather than a rule broken.
+### Reading a length finding
 
-**Routes to:** a split of the document, or a move of the overgrown passage to the surface that owns it. Where the project states what a given document may hold, that statement decides whether the passage belongs in it at all, and the finding routes there rather than to a trim.
+Weight is a judgment a reader settles rather than a defect, as the verb states for itself. A finding here argues for a split or a trim rather than naming a broken rule.
 
-**Caveat:** the cadence numbers are drawn from prose a person reads straight through. Terse reference prose sits below that range correctly, so a flat paragraph in a table-heavy or bullet-heavy file is not a finding.
+- **Routes to:** a split of the document, or a move of the overgrown passage to the surface that owns it
+- **A project statement of what a document may hold** decides whether the passage belongs, and the finding routes there rather than to a trim
+- **Caveat:** the cadence numbers are drawn from prose read straight through. Terse reference prose sits below that range correctly, so a flat paragraph in a table or bullet-heavy file is no finding.
 
 ## Placement
 
-**Measures:** whether a document's content sits in the file that owns it, and whether the catalogs pointing at it still resolve.
+| Field          | Value                                                                                                                    |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Measures       | Whether a document's content sits in the file that owns it, and whether the catalogs pointing at it resolve              |
+| Verbs          | `canon context audit --json` for the structural half, `canon context classify sweep --json` for the per-section verdicts |
+| Evidence class | `measured` for the audit's findings, `classified` for the sweep's verdicts                                               |
 
-**Verbs:** `canon context audit --json` for the structural half, `canon context classify sweep --json` for the per-section verdicts.
+The audit answers required sections, entry length, citation resolution, reference form, catalog tables, provenance, and index drift. Required sections reach context entries.
 
-**Evidence class:** `measured` for the audit's findings, `classified` for the sweep's verdicts.
+- A citation resolving to nothing is a fact and gates
+- Entry length, reference form, table shape, and provenance are judgments under every flag
 
-The audit answers required sections, entry length, citation resolution, reference form, catalog tables, provenance, and index drift. Required sections reach context entries. A citation resolving to nothing is a fact and gates. Entry length, reference form, table shape, and provenance are judgments under every flag.
+### The sweep's verdicts
 
-The sweep classifies each section as keep, replace or rewrite, history, or move. A `move` verdict is the placement finding proper, naming content sitting in the wrong document. Each verdict carries its own confidence, which is why the class is `classified` rather than `measured`, and a low-confidence `move` is a prompt to look rather than an instruction to cut.
+The sweep classifies each section as keep, replace or rewrite, history, or move. A `move` verdict is the placement finding proper, naming content sitting in the wrong document.
 
-**Routes to:** the document the verdict names as the owner. Where the move crosses a tier rather than a file, the project's own content-ownership rules decide the destination.
+- Each verdict carries its own confidence, which is why the class is `classified` rather than `measured`
+- A low-confidence `move` is a prompt to look rather than an instruction to cut
+- **Routes to:** the document the verdict names as the owner. Where the move crosses a tier rather than a file, the project's own content-ownership rules decide the destination.
 
-**Caveat:** both verbs resolve their folders by surface root rather than by a path written into them, so a project whose layout differs from the one they look for resolves nothing. The audit says so, refusing with `reason: "no-folders"` and naming the folders it looked for. Report that refusal as an unread axis. The sweep degrades differently: with the model layer off it answers from its regex layer alone, which is a narrower read rather than a refusal, so say which layer answered.
+### When a verb resolves nothing
 
-## Staleness
+Both verbs resolve their folders by surface root rather than by a path written into them, so a project laid out differently resolves nothing. The two degrade differently.
 
-**Measures:** whether a document still describes the tree it was written about.
+- The audit refuses with `reason: "no-folders"`, naming the folders it looked for. Report that refusal as an unread axis.
+- The sweep with the model layer off answers from its regex layer alone, a narrower read rather than a refusal, so say which layer answered
 
-**Verb:** none.
+## Staleness
 
-**Evidence class:** `read`.
+| Field          | Value                                                            |
+| -------------- | ---------------------------------------------------------------- |
+| Measures       | Whether a document still describes the tree it was written about |
+| Verb           | None                                                             |
+| Evidence class | `read`                                                           |
 
-This is the axis the operator names first and the one nothing measures. A document goes stale by the tree moving under it rather than by anything changing in the document, so no property of the file answers it and a timestamp answers a different question. A file untouched for a year beside code untouched for a year is current, and one edited yesterday against a refactor from this morning is stale.
+This is the axis the operator names first and the one nothing measures. A document goes stale by the tree moving under it, so no property of the file answers it and a timestamp answers a different question.
 
-Read each document against the surfaces it names. Four claim shapes are testable without leaving the project:
+A file untouched for a year beside code untouched for a year is current, and one edited yesterday against a refactor from this morning is stale. Read each document against the surfaces it names, testing four claim shapes without leaving the project.
 
 - A file or folder path the document states, against whether it resolves
 - A command or verb the document names, against whether it exists and carries the flags shown
 - A count the document states over a tree, against the tree
 - A cross-reference to another document, against what that document now says
 
-A claim resting on none of the four is unverifiable from here. Report it as unread rather than as passing, which is the same rule the measured axes take when a verb refuses.
+A claim resting on none of the four is unverifiable from here. Report it as unread rather than as passing, the same rule the measured axes take when a verb refuses.
 
 ### Identity drift in the requirements record
 
-This record states what the project is and why it is built, so it goes stale by the project changing direction as well as by the tree moving. Test these claim shapes beside the four above:
+This record states what the project is and why, so it goes stale by the project changing direction as well as by the tree moving. Test these claim shapes beside the four above, each a `read`.
 
 - A goal nobody pursues, read against the task board and the recent history
 - A non-goal the project has since shipped
 - A constraint the tree contradicts
 
-Each is a `read`. The review point beside them is `measured`: `canon records stale canonical --json` returns the `reviewed` date from its frontmatter and `releasesSince`, the release tags merged into HEAD after that day. A null `releasesSince` means the doc was never reviewed, and `tagged: false` means no release tag exists to count, so a zero there measured nothing. The count is a reminder of how far the project has moved since someone last read the record whole, never a threshold.
+### The review point
 
-**Routes to:** the skill that rewrites a stale claim against an answer, rather than a direct edit from here. A document health run reports and never repairs.
+The review point beside them is `measured`. `canon records stale canonical --json` returns the `reviewed` date from the record's frontmatter and `releasesSince`, the release tags merged into HEAD after that day.
 
-**Caveat:** a reading is the weakest evidence in the report and the most consequential finding in it, which is the tension this axis ships with. Marking the class is what keeps the two facts together in the reader's hands.
+- A null `releasesSince` means the doc was never reviewed
+- `tagged: false` means no release tag exists to count, so a zero there measured nothing
+- The count is a reminder of how far the project has moved since someone last read the record whole, never a threshold
+
+### Routing a staleness finding
+
+A document health run reports and never repairs, so a stale claim routes to the skill that rewrites it against an answer rather than to a direct edit from here.
+
+A reading is the weakest evidence in the report and the most consequential finding in it, which is the tension this axis ships with. Marking the class keeps the two facts together in the reader's hands.
 
 ## Why the three stay apart
 
-The axes are not equally actionable and a report flattening them implies they are. A length finding is a number against a checkpoint, a placement finding is a verdict carrying a confidence, and a staleness finding is a judgment with nothing behind it. Each is worth reporting and each is worth a different response, so the class travels beside the state on every row rather than being stated once in a preamble a reader skims.
+The axes are not equally actionable, and a report flattening them implies they are. Each is worth reporting and each is worth a different response, so the class travels beside the state on every row rather than once in a preamble a reader skims.
+
+- A length finding is a number against a checkpoint
+- A placement finding is a verdict carrying a confidence
+- A staleness finding is a judgment with nothing behind it
 
 Shipping staleness on weaker evidence than the other two is the trade taken deliberately. Cutting it would leave the report answering the two questions that were never the operator's complaint.

package/claude/skills/draft-and-pick/references/live-arms.md

@@ -5,7 +5,7 @@ Read when the surface under decision is a running app rather than a static mocku
 ## Lift from the app
 
 - Dump the rendered markup of the surface under decision from the built page, after it has loaded, into a scratch file the run reads from. Strip scripts from the dump.
-- Copy the built stylesheet and font files into the canvas page folder, at the path each frame links them from, since a frame resolves only files inside its own page. Every arm then renders with the stylesheet the app ships and differs from the shipped page only by what the arm names.
+- Copy the built stylesheet and fonts to the canvas page folder at the path each frame links, since a frame resolves only its own page. Each arm then differs from the shipped page only in what it names.
 - Trim a large dump to the part the decision needs, and keep the wrapper classes intact so layout rules keyed to them still resolve.
 - Set each frame's `--width` to the content width the decision names rather than the window width, since a container query reads the frame.
 - Write copy an arm introduces with `write-human`, and take every other word from the dump.
@@ -13,7 +13,7 @@ Read when the surface under decision is a running app rather than a static mocku
 ## The frames
 
 - Generate the frames with a short script, one per round, so a shared change is one edit and a rerun.
-- Leave the theme to the canvas toggle, which sets the app's own `data-theme` switch on every frame's root. Name the attribute the app's stylesheet reads where it is not `data-theme`, since the toggle sets that one alone.
+- Leave the theme to the canvas toggle, which sets the app's own `data-theme` switch on every frame's root. Name the attribute the stylesheet reads where it differs, as the toggle sets that one alone.
 - Print each frame's measurement under it from a script in the frame, so the numbers the operator reads are the browser's.
 - Draw an arm that is a whole page or a route as one frame at that page's width, so it still sits beside the other arms on the round's page.
 - Name anything the canvas cannot reproduce, such as an asset whose colors follow the browser rather than the frame's theme, rather than fixing the frame around it.

package/claude/skills/draft-doc/references/context.md

@@ -13,12 +13,13 @@ A project the surface move has not reached keeps its context folder under `.clau
 
 ## Guards
 
-- Derive a kebab-case slug from the domain and check whether `<context-root>/<slug>.md` or `<context-root>/<slug>/index.md` already exists. Either resolving means the domain is already covered under that exact name. Stop: `❌ <slug> already has a context entry. Use context-fold to refresh it instead.`
+Derive a kebab-case slug from the domain and check whether `<context-root>/<slug>.md` or `<context-root>/<slug>/index.md` already exists. Either resolving means the domain is covered under that exact name, so stop: `❌ <slug> already has a context entry. Use context-fold to refresh it instead.`
 
 ## Placement
 
-- Read `<context-root>/index.md` and check every title and description it lists against the domain. Stop on a match: `❌ <path> already covers this domain under a different name. Use context-fold to refresh it instead.`
-- Default a brand-new entry to a flat file, `<context-root>/<slug>.md`. A domain starts as one page's worth of narrative, and the standard splits it into a folder only once the entry passes the 300-line ceiling, which a fresh domain never does on day one.
+- Read `<context-root>/index.md` and check every title and description it lists against the domain
+- Stop on a match: `❌ <path> already covers this domain under a different name. Use context-fold to refresh it instead.`
+- Default a brand-new entry to a flat file, `<context-root>/<slug>.md`, since the standard splits an entry into a folder only past the 300-line ceiling, which a fresh domain never reaches
 
 ## Draft
 

package/claude/skills/draft-doc/references/docs.md

@@ -9,12 +9,15 @@ description: The guard, placement, draft additions, and regen folder for a brand
 
 ## Guards
 
-- Derive a kebab-case slug from the topic and run `canon docs <slug>`. A resolved page means the topic is already covered under that exact name. Stop: `❌ <slug> already resolves to an existing page. Run canon:docs-sync instead.` This is a name match rather than a topic match. Placement checks the wider case.
+Derive a kebab-case slug from the topic and run `canon docs <slug>`. A resolved page means the topic is covered under that exact name, so stop: `❌ <slug> already resolves to an existing page. Run canon:docs-sync instead.`
+
+This is a name match rather than a topic match, and Placement checks the wider case.
 
 ## Placement
 
-- Read `docs/index.md` and its sub-catalogs for the closest existing `category`. <!-- canon-allow-reference: illustrates the target project's own docs/ tree, not a citation of this repository's own corpus -->
-- Check every page title and description that read surfaces against the topic. Stop on a match: `❌ <path> already covers this topic under a different name. Run canon:docs-sync instead.`
+- Read `docs/index.md` and its sub-catalogs for the closest existing `category`. <!-- canon-allow-reference: the target project's own docs/ tree -->
+- Check every page title and description that read surfaces against the topic
+- Stop on a match: `❌ <path> already covers this topic under a different name. Run canon:docs-sync instead.`
 - Reuse a matching `category` value verbatim. A near-miss spelling opens a second shelf holding one page, per the docs standard.
 - Default to the `docs/` root with no `category` when nothing fits. A subfolder earns itself only once a shelf of pages already sits there, per the standard's splitting rule.
 

package/claude/skills/draft-doc/references/readme/agent-facing.md

@@ -13,11 +13,15 @@
 
 ### Requirements
 
+Install <what the machine needs> before setup.
+
 - <Agent tool and minimum version>
 - <Runtime the listing command needs>
 
 ### Set up
 
+Run these from <where to run them>.
+
 ```bash
 <clone command>
 <setup command, when a session needs one>
@@ -31,6 +35,8 @@
 
 ### List what the project exposes
 
+The listing shows <what it shows>.
+
 ```bash
 <command that lists skills, rules, or commands>
 ```

package/claude/skills/draft-doc/references/readme/application.md

@@ -22,11 +22,15 @@
 
 ### Requirements
 
+Install <what the machine needs> before setup.
+
 - <Runtime and version>
 - <Service the app depends on>
 
 ### Set up
 
+Run these from <where to run them>.
+
 ```bash
 <clone command>
 <dependency install command>
@@ -36,11 +40,13 @@
 
 ### Run locally
 
+The dev server runs <what it runs>.
+
 ```bash
 <dev server command>
 ```
 
-<Address the app serves on.>
+It serves on <address>.
 
 ### Configuration
 
@@ -50,7 +56,7 @@
 
 ### Deploy
 
-<Where the app deploys and the command or workflow that does it.>
+The app deploys to <where>, through <the command or workflow>.
 
 ## Support
 

package/claude/skills/draft-doc/references/readme/cli.md

@@ -27,12 +27,16 @@
 
 ### Run a command
 
+The most common invocation is <what it does>.
+
 ```bash
 <command> <argument>
 ```
 
 ### Flags
 
+Most runs need <the flags a reader reaches for first>.
+
 ```bash
 <command> --<flag> <value>
 <command> --<flag>
@@ -44,7 +48,7 @@
 
 ### Exit codes
 
-<What each non-zero exit means, when a script depends on it.>
+A non-zero exit means <what each code means>, when a script depends on it.
 
 ## Documentation
 

package/claude/skills/draft-doc/references/readme/library.md

@@ -29,12 +29,16 @@
 
 ### Quickstart
 
+The snippet shows <the core behavior>.
+
 ```<language>
 <Import and one call that shows the core behavior>
 ```
 
 ### <Second common task>
 
+Reach for this when <the reader's situation>.
+
 ```<language>
 <Snippet for the task>
 ```

package/claude/skills/draft-doc/references/readme/plugin.md

@@ -18,18 +18,24 @@
 
 ### <First channel name>
 
+Install through this channel when <who it suits>.
+
 ```bash
 <install command for this channel>
 ```
 
 ### <Second channel name>
 
+Install through this channel when <who it suits>.
+
 ```bash
 <install command for this channel>
 ```
 
 ### Update
 
+Update when <the trigger>, which replaces <what it replaces>.
+
 ```bash
 <update command>
 ```
@@ -38,6 +44,8 @@
 
 ### Invoke a skill
 
+Type the command in <where the user types it>.
+
 ```text
 /<plugin name>:<skill name> <argument>
 ```
@@ -50,7 +58,7 @@
 
 ### Configuration
 
-<Setting the plugin reads and where the user sets it, when one exists.>
+Set <the setting the plugin reads> in <where the user sets it>, when one exists.
 
 ## Support
 

package/claude/skills/draft-doc/references/readme.md

@@ -11,12 +11,21 @@ The readme standard claims the voice of a repository-root README. `write-human`
 
 ## Guards
 
-- Default the target to `README.md` at the repository root when no path is given. A caller naming a path under a folder, a harness, or an internal tool is drafting a nested README instead, which keeps the reference voice per the standard's `## Voice` section rather than the root voice.
-- Read the target if it exists.
-  - It carries an H1 naming the project: it is authored. Stop: `❌ <path> already exists and covers the project. Run canon:docs-sync instead.` Report rather than offering to overwrite it or to conform it to what this kind would draft, since the project's own citations into its README are invisible from here.
-  - It carries no H1, or its only headings restate the tool that scaffolded it rather than the project: it is unedited generator output. Continue, drafting over it rather than syncing its sections.
-  - It does not exist: continue.
-- A hand-authored README opening with a badge block, or a title in some other form the H1 test misses, falls into the no-H1 branch the same as a scaffold page. The Confirm step is what catches that case before the write happens, so treat it as load-bearing rather than a courtesy: never skip it on the reasoning that the guard already decided.
+Default the target to `README.md` at the repository root when no path is given. A caller naming a path under a folder, a harness, or an internal tool is drafting a nested README, which keeps the reference voice per the standard's `## Voice` section.
+
+### Reading an existing target
+
+Read the target if it exists, and branch on its headings.
+
+| Target                                                         | Reading          | Route                                                                                 |
+| -------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------- |
+| Carries an H1 naming the project                               | Authored         | Stop: `❌ <path> already exists and covers the project. Run canon:docs-sync instead.` |
+| Carries no H1, or only headings restating the scaffolding tool | Generator output | Continue, drafting over it rather than syncing its sections                           |
+| Does not exist                                                 | Nothing to read  | Continue                                                                              |
+
+- On the authored branch, report rather than offering to overwrite it or to conform it, since the project's own citations into its README are invisible from here
+- A hand-authored README opening with a badge block, or a title the H1 test misses, falls into the no-H1 branch the same as a scaffold page
+- The Confirm step catches that case before the write, so it is load-bearing. Never skip it on the reasoning that the guard already decided.
 
 ## Placement
 
@@ -26,15 +35,18 @@ The target path is the placement. A README keeps no catalog, so there is no coll
 
 Read the project's manifest (`package.json`, `pyproject.toml`, `Cargo.toml`, or equivalent) and the tree, then test each type on its own signal. Note every type that matches rather than stopping at the first, since a project is often several at once.
 
-- Library: an installable package name, counted only when no application, CLI, or plugin signal matches, since a named package is also what a site, a CLI, or a plugin carries. An agent-facing match leaves it in place, so a library with a `CLAUDE.md` still gets its quickstart.
+- Library: an installable package name, counted only when no application, CLI, or plugin signal matches, since a site, a CLI, or a plugin also carries a named package
 - CLI: a `bin` field, a `[project.scripts]` table in `pyproject.toml`, a `[[bin]]` table in `Cargo.toml`, or a CLI entry point.
 - Application: a site framework dependency, a site config file, or an app entry point.
 - Agent-facing: a `.claude/skills/` folder, or a file an agent loads such as `CLAUDE.md`.
 - Plugin: a `plugin.json` or a marketplace manifest.
 
-A match on no type falls back to the standard's generic template. Say so in the preview, and never force the nearest type.
+An agent-facing match leaves the library type in place, so a library with a `CLAUDE.md` still gets its quickstart. A match on no type falls back to the standard's generic template. Say so in the preview, and never force the nearest type.
+
+### Page, mark, and screenshot
+
+A site framework dependency or a site config file in the manifest or the tree marks a project as having a page. Read a live URL separately, from a `homepage` field or a deploy config, since a project can have a page and no known URL.
 
-- Check for a page. A dependency on a site framework or a site config file in the manifest or the tree marks a project as having one. Read a live URL separately, from a `homepage` field or a deploy config, since a project can have a page and no known URL.
 - A monorepo can carry a page in one package and a CLI in another, so both signals may fire. Report each rather than picking one.
 - Look for the mark and the screenshot among images the project already commits: scan the existing README for image references, then the asset and public folders.
 
@@ -61,13 +73,18 @@ Between agent-facing and plugin alone, a repository with no plugin manifest take
 
 ## Draft
 
-- Start from the picked or combined template. Draft the H1, a 2-3 sentence description in plain text, then the required sections, then whichever optional sections and per-type content Detect found. A README takes no frontmatter.
-- Open the page with the standard's header block, filling each slot from what Detect found: mark, title, badges, a one-line claim from the manifest description, the live link, then the product screenshot.
-- Fill the screenshot slot only with an image the project already commits, referenced with alt text naming what it depicts. This kind cannot capture one. Omit the slot when no such image exists and say so in the preview. Never write a placeholder path or invent a mark.
-- Omit the link and the screenshot for a project with no page, and the mark for a project with none, without a note in the drafted page. A project with a page and no known URL gets the screenshot slot, and the Confirm step asks for the link.
+Start from the picked or combined template. Draft the H1, a 2-3 sentence description in plain text, the required sections, then whichever optional sections and per-type content Detect found. A README takes no frontmatter.
+
+- Open with the standard's header block, filled from Detect in order: mark, title, badges, a one-line claim from the manifest description, the live link, then the product screenshot
+- Fill the screenshot slot only with an image the project already commits, with alt text naming what it depicts, since this kind cannot capture one
+- With no such image, omit the slot and say so in the preview. Never write a placeholder path or invent a mark.
+- Omit the link and the screenshot for a project with no page, and the mark for a project with none, with no note in the page
+- A project with a page and no known URL gets the screenshot slot, and the Confirm step asks for the link
 
 ### Types and badges
 
+A badge earns its place only once its rendered value is checked.
+
 - Cover every applicable project type from the standard's `## Content` list rather than picking the closest one.
 - Candidate badges: check for a published package (a registry field in the manifest), a CI workflow, and a `LICENSE` file.
 - State each candidate's rendered value in the preview rather than trusting a fetch's status code, since a badge service answers 200 for a query it cannot satisfy.