@erclx/canon 5.38.0 → 5.39.0

package/claude/skills/design-taste/SKILL.md

@@ -7,11 +7,9 @@ metadata:
 
 # Design taste
 
-A model with no stated direction draws the population average of what it has seen. That is why unguided design output reads as templated while satisfying every rule of craft it was given, and it is why adding more craft rules does not fix it. This skill carries the direction: where a decision sits, what settles before it, and which defaults to reach past.
+A model with no stated direction draws the population average of what it has seen, so unguided output reads as templated while satisfying every craft rule, and more craft rules do not fix it. This skill carries the direction: where a decision sits, what settles before it, and which defaults to reach past.
 
-Load this before drafting rather than after. A revision pass recovers a color and never recovers the composition the draft already settled.
-
-Skip it for work that does not change how something looks, feels, moves, or is interacted with.
+Load this before drafting rather than after, since a revision pass recovers a color and never the composition the draft already settled. Skip it for work that does not change how something looks, feels, moves, or is interacted with.
 
 ## The defaults you are reaching past
 
@@ -25,6 +23,8 @@ This is what the population average looks like. Each one is what gets drawn when
 
 ### Details and copy
 
+The rest of the ten sit in the details and the copy.
+
 - A colored dot before every navigation item, row or badge.
 - A glow standing in for elevation, on a pure black or pure white ground.
 - A product screenshot built out of styled rectangles.
@@ -53,9 +53,10 @@ Put the read to the operator through the structured question surface where it ge
 
 ## The layers, and the order they settle
 
-A lower layer constrains every layer above it. Two consequences follow, they run in opposite directions, and collapsing them is the mistake worth avoiding.
+A lower layer constrains every layer above it. Two consequences follow in opposite directions, and collapsing them is the mistake worth avoiding.
 
-Settling a higher layer over a broken lower one changes nothing, which is why a palette round against a broken composition is wasted. Judging a lower layer through a finished higher one is nearly impossible, which is why grey-boxing works.
+- Settling a higher layer over a broken lower one changes nothing, which is why a palette round against a broken composition is wasted
+- Judging a lower layer through a finished higher one is nearly impossible, which is why grey-boxing works
 
 The model is Jesse James Garrett's five planes from _The Elements of User Experience_ (2000), subdivided to the granularity a drafting round works at.
 
@@ -73,10 +74,11 @@ The model is Jesse James Garrett's five planes from _The Elements of User Experi
 
 ### What follows from the order
 
-- Work at the lowest layer the complaint reaches. A complaint is voiced at the layer a person can name and usually lives lower. "It feels gloomy" reads as palette and is frequently composition, since a page with one section shape reads flat whatever color it is.
+Work at the lowest layer the complaint reaches. A complaint is voiced at the layer a person can name and usually lives lower, so "it feels gloomy" reads as palette and is frequently composition, since a page with one section shape reads flat whatever its color.
+
 - A round varies one layer and says which. Varying three answers nothing, because the pick cannot say which difference decided it.
-- Never settle a higher layer before the one below it. Imagery and palette are the one pair that settle together, since a real photograph sets a ground rather than accepting one.
-- Content leads the order and is frequently absent when drafting starts. Draft against real copy where it exists, stand in for it where it does not, and treat the composition as unsettled until real copy has run through it.
+- Never settle a higher layer before the one below it. Imagery and palette settle together, since a real photograph sets a ground rather than accepting one.
+- Content leads the order and is often absent at the start. Draft against real copy where it exists, stand in where it does not, and treat the composition as unsettled until real copy runs through it.
 - Name the layer the complaint sits at, then check the layers below are settled. Where one is not, that is the round, and say so rather than drafting the requested one.
 
 ## Grey-box when judging layers 1 to 4
@@ -114,7 +116,7 @@ Never change these without saying so and getting agreement, because each one bre
 
 ## Setting up the scales
 
-Read `${CLAUDE_SKILL_DIR}/references/systems.md` when establishing or revising what a surface draws from, being the space scale, the type scale, and the relationships a palette holds. Every other reference here is read against a draft. That one is read before there is one, so a project reaches for it at the start and on a system revision rather than on an ordinary round.
+Read `${CLAUDE_SKILL_DIR}/references/systems.md` when establishing or revising what a surface draws from, being the space scale, the type scale, and the relationships a palette holds. Every other reference is read against a draft, and this one before there is one, at the start and on a system revision.
 
 It states no values. A value belongs to the project's own stylesheet, and its intent to the design document.
 
@@ -122,7 +124,9 @@ It states no values. A value belongs to the project's own stylesheet, and its in
 
 Read `${CLAUDE_SKILL_DIR}/references/tells.md` before handing over anything a model drafted, and whenever output satisfies every rule here and still reads generic. The ten above are the common cases. It holds the rest, plus the countable composition limits and the first-screen budget.
 
-Skip `tells.md` on a small change to a surface with a settled direction. The catalog is a diagnostic and costs a read on every invocation that does not need one.
+Skip `tells.md` on a small change to a surface with a settled direction, since the catalog is a diagnostic and costs a read wherever it is not needed.
+
+### Source record
 
 Read `${CLAUDE_SKILL_DIR}/references/adopted.md` only when extending this guidance or arguing against a rule in it. It records which external catalog items were adopted, which declined, and why.
 
@@ -150,6 +154,8 @@ Run `${CLAUDE_SKILL_DIR}/references/preflight.md` against the output. It is the
 
 ### Other skills
 
+Four neighbors own the rest.
+
 - The candidate loop, the arm set, the render, and the pick: `draft-and-pick`
 - The shape of the project's design document and where its values live: `${CLAUDE_SKILL_DIR}/../canvas-board/references/design.md`
 - Reading source for roughness: `ux-audit`. Measuring what a running interface costs to paint: `ux-measure`

package/claude/skills/docs-sync/REQUIREMENT.md

@@ -22,6 +22,7 @@ The quiet one is the baseline. A diff resolved against a bare local ref equals H
 - Say so in the output when the baseline degrades, rather than reporting a clean pass off a set it could not build
 - Discover the doc set by glob at run time
 - Classify and rewrite at section level, so a partly stale file is partly rewritten
+- Mark a section stale only when the diff changes what a caller sees, since a page rewritten on every internal change starts carrying the reasons behind it
 - Write immediately after the preview, since the tool permission dialog is the confirmation gate
 
 ## Must not

package/claude/skills/docs-sync/SKILL.md

@@ -29,7 +29,9 @@ The baseline is unusable in two cases:
 - No merge base resolves against either ref.
 - The base equals HEAD, whichever ref resolved it. Nothing is committed ahead of the base to compare against. This is the ordinary shape on `main`, and on a feature branch before its first commit.
 
-An unusable baseline costs only the committed half. `git diff --cached <base>` degrades to the staged set and `git status --short` still reports the working tree, so both reads stay at this skill's own scope. Say so in the preview with `⚠ Baseline unusable. Synced against the uncommitted set only.` The base ref is the only thing this change touches, and the `--cached` scope stays.
+An unusable baseline costs only the committed half. `git diff --cached <base>` degrades to the staged set and `git status --short` still reports the working tree, so both reads stay at this skill's own scope.
+
+Say so in the preview with `⚠ Baseline unusable. Synced against the uncommitted set only.` The base ref is the only thing this change touches, and the `--cached` scope stays.
 
 ## Context
 
@@ -41,7 +43,8 @@ Run these commands in parallel:
 
 ## Guards
 
-- If `git diff --cached <base>` output is empty and `git status --short` output is empty, stop: `❌ No changes since main. Nothing to sync.` Resolve the base ref first. A guard reading bare local `main` stops the skill on `main` before it reaches the corrected read.
+- If `git diff --cached <base>` output is empty and `git status --short` output is empty, stop: `❌ No changes since main. Nothing to sync.`
+- Resolve the base ref first, since a guard reading bare local `main` stops the skill on `main` before it reaches the corrected read
 
 ## Discovery
 
@@ -56,9 +59,9 @@ Read each discovered file in parallel.
 
 For each discovered doc, classify as one of:
 
-- `stale`: the diff touches something the doc describes
+- `stale`: the diff changes something a caller sees in what the doc describes, being a flag, the output, a refusal, or how commands chain
 - `departed`: the doc records a deliberate contract and the diff broke it
-- `unrelated`: no overlap between diff and doc content
+- `unrelated`: no overlap between diff and doc content, or the diff changes only internals a caller never sees
 
 The split between `stale` and `departed` is whether the doc was describing or promising. A doc that trailed the code is `stale`. A doc stating a contract the code was meant to keep is `departed`, and rewriting it to match the diff would record the regression as the contract.
 
@@ -68,9 +71,16 @@ Classify at the section level, not the file level. A doc edited earlier in the s
 
 Rewrite only the stale sections. Do not touch sections unrelated to the diff.
 
-Write the updated file immediately after the preview. Claude Code's tool permission dialog is the confirmation gate. Do not wait for user input.
+- Write the updated file immediately after the preview. Claude Code's tool permission dialog is the confirmation gate, so do not wait for user input.
+- Never rewrite a `departed` section. Leave it as written and report it as a finding, since the repair belongs in the code rather than in the prose.
+
+## Audit
+
+Run `canon markdown audit <path>` over every page this run rewrote, and fix each ban, density, and reference shape finding it reports per the markdown standard and the docs reference read above.
 
-Never rewrite a `departed` section. Leave it as written and report it as a finding, since the repair belongs in the code rather than in the prose.
+- Fix a finding inside a section this run rewrote, then re-run the audit on that page until it reports none there
+- Report a finding in a section the diff does not reach as an audit line in the summary, since the rule above leaves that section as it is
+- Report a refusal or a missing subcommand as an audit line and continue
 
 ## Response format
 
@@ -95,4 +105,5 @@ One line per file, using the same relative path format as the preview table (e.g
 ✅ Updated: <relative-path>
 ⏭️  Skipped: <relative-path>
 ⚠️ Departed: <relative-path> records <the contract>, and the diff <what it did>. Left unwritten.
+⚠️ Audit: <relative-path>, <finding>
 ```

package/claude/skills/docs-sync/references/docs.md

@@ -1,18 +1,21 @@
 ---
 title: Docs reference
-description: Reader and jurisdiction, frontmatter, page structure, what a page links out to, the diagram permission, and when a category earns a subfolder
+description: Reader and jurisdiction, frontmatter, page structure, the command reference shape, what a page links out to, the diagram permission, and when a category earns a subfolder
 ---
 
 # Docs reference
 
 Applies to each authored reference page under `docs/`. Skip for `index.md` at any depth, which is generated rather than authored.
 
+Its reader is an operator running what the project ships rather than developing it, or an agent reading the page cold from a project that consumes it. Neither has the source open, which separates a page from internal narrative, whose reader does, and from the front-door page, whose reader has not installed anything yet.
+
 ## Contents
 
 - [Scope](#scope)
 - [What a working docs page looks like](#what-a-working-docs-page-looks-like)
 - [Frontmatter](#frontmatter)
 - [Structure](#structure)
+- [Reference pages](#reference-pages)
 - [Content](#content)
 - [Diagrams](#diagrams)
 - [Splitting the folder](#splitting-the-folder)
@@ -20,13 +23,11 @@ Applies to each authored reference page under `docs/`. Skip for `index.md` at an
 
 ## Scope
 
-Governs each authored reference page under `docs/`, whose reader is an operator running what the project ships rather than developing it, and an agent reading the page cold from a project that consumes it: the frontmatter a page carries, its structure, what it links out to rather than restating, whether it holds a diagram, and when a category earns a subfolder of its own.
-
-Neither reader has the source open. That is the whole of the distinction from internal narrative, whose reader does, and from the page a project puts at its front door, whose reader has not decided to install anything yet.
+Governs each authored reference page under `docs/`, being the frontmatter a page carries, its structure, what it links out to rather than restating, whether it holds a diagram, and when a category earns a subfolder of its own.
 
 Does not govern:
 
-- The page a project puts at its front door, whose reader is deciding whether to commit at all: `readme.md`
+- `README.md`, the page a project puts at its front door, whose reader is deciding whether to commit at all. It keeps its own voice and takes the density limits but not the no-why rule: `readme.md`
 - Per-domain internal narrative written for a reader with the source open: `context.md`
 - The drawing inside a Mermaid fence: `mermaid.md`
 - Voice, rhythm, and sentence construction: the `write-human` skill
@@ -48,10 +49,13 @@ A page failing these is non-conforming even when it satisfies every shape rule b
 - `title` (required): sentence case, naming the surface the page covers rather than the action a reader takes on it
 - `description` (required): one line naming what the page covers, which is what the folder's catalog shows beside the link
 - `category` (conditional): the shelf the page sits on in that catalog
+- `kind` (optional): `reference` on a page documenting one command, which opts it into the shape under [Reference pages](#reference-pages)
 
 ### Declaring category
 
-- Declare `category` on every page in a folder where any page declares one. A grouped catalog writes the declared shelves and nothing else, so a page omitting the field beside a sibling that carries one is absent from the catalog with nothing reporting it.
+A grouped catalog writes the declared shelves and nothing else, so `category` is all or nothing within a folder.
+
+- Declare `category` on every page in a folder where any page declares one, since a page omitting it beside a sibling that carries one is absent from the catalog with nothing reporting it
 - Omit it on every page or on none. A folder where no page declares one lists flat, which is the right shape for a folder whose pages need no shelves.
 - Spell one shelf's value identically on every page sitting there. The grouping reads the literal string, so a second spelling opens a second shelf holding one page.
 
@@ -60,18 +64,35 @@ A page failing these is non-conforming even when it satisfies every shape rule b
 - Open with an H1 matching `title`, then one or two lines saying what the surface is, before any heading
 - Use `##` for major sections and `###` for subsections. Do not nest deeper.
 - Use sentence case for every heading, proper nouns aside
-- Lead with the invocation a reader came for. Background, rationale, and edge cases sit below it.
+- Lead with the invocation a reader came for, with the edge cases below it
 - Write a command, a flag, or a field as something copyable, in a code span or a fence, never paraphrased into prose
 
+## Reference pages
+
+A page marked `kind: reference` documents one command and holds a fixed set of parts. `canon markdown audit` checks the headings and tables on every marked page, and an unmarked page is never measured.
+
+Write a reference page only for a command a person or a target project runs by hand. A command only a skill calls gets no page, since the calling skill and `<command> --help` cover it.
+
+- Open with the H1, one or two lines on what the command does, and the command in a fence
+- Follow with `## Output`, `## Refusals`, and `## See also`, each at most once and in that order, and no other H2. A page may leave one out.
+- Use no H3. A part long enough to need one belongs on a page of its own.
+- Point at `<command> --help` for flags rather than tabling them. A table whose first header cell is `Flag` or `Option` is a finding.
+- Table the refusals by their `reason` where the command emits one
+
+A guide walking a reader through several commands carries no marker and keeps free sections, held by the density limits and the no-why rule under [Content](#content).
+
 ## Content
 
+- State how to use the surface and never why it was built that way. The why lives in the code and the pull request that changed it.
 - Write for a reader with no access to the source. A sentence that resolves only by opening a file belongs in internal narrative instead.
 - Name the failures a surface produces alongside the path that works. A page documenting success alone sends its reader to the source at the first refusal.
 - Link to the adjacent page rather than restating it. One page owns each surface, and a second copy drifts with nothing comparing the two.
 
 ### What to leave out
 
-- Do not restate output a command already prints, such as a full flag table. Name the command that prints it.
+A page leaves out what its reader can get elsewhere or does not need yet.
+
+- Do not restate what `<command> --help` prints, such as a flag table. Name the command and point at its help.
 - Do not carry the history of how a surface reached its shape. A page describes the surface as it stands, and the change that moved it is recorded wherever the project tracks work.
 - Do not carry contributor setup or the argument for adopting the project. Both are addressed to a reader who has not installed anything yet.
 
@@ -80,41 +101,53 @@ A page failing these is non-conforming even when it satisfies every shape rule b
 - Carry a diagram where the page describes a structure or a path the reader has to hold in their head at once. One per page at most, and none is a correct answer for most pages.
 - Draw it as a Mermaid fence or as a committed image the page references. Neither form is preferred, and the pick belongs to whoever knows which one the page's reader reads it in.
 - Follow `mermaid.md` for the drawing inside a fence. It reaches the drawing and stops at the fence markers, so everything around it stays this file's subject.
-- Do not write the drawing as raw inline markup. A rendering host strips markup outside its own allowlist, so an inline drawing survives a local preview and vanishes on the surface the page is read from.
+- Do not write the drawing as raw inline markup. A rendering host strips markup outside its allowlist, so an inline drawing survives a local preview and vanishes where the page is read.
 - Say beneath the diagram, in prose, what it shows. A reader who cannot see the image gets the same answer from the sentence.
 
 ## Splitting the folder
 
-- Move a `category` into a subfolder once its pages stop reading as a list in the catalog and start reading as a section of one. The shelf is the signal, not a file count, and a count invites an argument about the count instead.
+Move a `category` into a subfolder once its pages stop reading as a list in the catalog and start reading as a section of one. The shelf is the signal, not a file count, since a count invites an argument about the count instead.
+
 - Move every page carrying that value. A shelf split across two depths is harder to scan than either arrangement taken whole.
-- Give the subfolder a catalog page of its own, so the parent lists one entry where it listed several. The parent lists a subfolder as a folder rather than as a member of the shelf it replaced, so nothing on that page restores the grouping.
+- Give the subfolder a catalog page of its own, so the parent lists one entry where it listed several, as a folder rather than as a member of the shelf it replaced
 - Retarget every link into a moved page in the same change. A link resolving nowhere is what the move costs, and nothing else reports it.
 - Name a moved page per the `codebase-layout` skill, which drops the prefix the subfolder now states.
 
 ## Template
 
-```markdown
+A command reference page, in the four-part shape:
+
+````markdown
 ---
 title: <Surface>
 description: <one line naming what this page covers>
 category: <the shelf this page sits on, carried by every sibling or by none>
+kind: reference
 ---
 
 # <Surface>
 
-<One or two lines on what the surface is and when a reader reaches for it.>
+<One or two lines on what the command does and who calls it.>
 
-## <The invocation>
+```bash
+<the command, spelled to copy>
+```
 
-`<the command or field, spelled to copy>`
+Run `<command> --help` for every flag.
 
-<What it does and what it produces.>
+## Output
 
-## <Refusals>
+<What the command prints or writes, with one example where the shape is not obvious.>
 
-- `<the condition>`: <what the reader sees, and what to do about it>
+## Refusals
 
-## <Adjacent surface>
+Branch on `reason` in the record, not the exit code.
 
-<Where the reader goes for the thing this page stops at.>
-```
+| Reason     | Meaning                                |
+| ---------- | -------------------------------------- |
+| `<reason>` | <what the reader sees, and what to do> |
+
+## See also
+
+- `<adjacent command or page>`: <what it covers that this page stops at>
+````

package/claude/skills/docs-sync/references/readme.md

@@ -5,7 +5,10 @@ description: Readme voice, structure, and content conventions
 
 # Readme reference
 
-Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so the `write-human` skill yields to it there. The yield covers voice alone. The rhythm and density rules that skill carries stay in force, as does the word-choice guidance that travels with them, and so do the punctuation and formatting in `markdown.md`, so the warmer register ships with the same hygiene: no em dashes, no semicolons, no marketing words.
+Applies to every `README.md`. The `## Voice` section states the voice for a repository's root README, so the `write-human` skill yields to it there, for voice alone.
+
+- The rhythm, density, and word-choice rules that skill carries stay in force
+- The punctuation, formatting, and density limits in `markdown.md` stay in force too, so the warmer register ships with no em dashes, no semicolons, and no marketing words
 
 The reader is what changes. Reference prose serves someone who already committed to the project and is scanning for a fact. A root README meets someone deciding whether to commit at all, and it is often the only file they read.
 
@@ -54,6 +57,8 @@ Scoped to the README at a repository root. A nested README documenting a folder,
 
 ### Leave out
 
+A README links to the surface that owns long-form material rather than carrying it.
+
 - Do not include full API documentation. Link to separate docs instead.
 - Do not include license text. Reference the `LICENSE` file.
 - Do not include detailed contribution guidelines. Reference `CONTRIBUTING.md`.
@@ -61,8 +66,12 @@ Scoped to the README at a repository root. A nested README documenting a folder,
 
 ### Routing and generator output
 
-- A README that points to the project's own context entries instead of restating them satisfies the required list by routing rather than carrying. A repository documented in `docs/` or `canon/context/` names the entry point and the listing command, then stops. The reader is one hop away, the same way `## Badges` treats zero as complete.
-- A README missing an H1, or whose headings restate the tool that scaffolded it rather than the project, is unedited generator output rather than a page anyone wrote. Draft over it. Nothing here asks a session to preserve a section a scaffold wrote and nobody replaced.
+A README can satisfy the required list by routing to the project's own context entries rather than restating them.
+
+- A repository documented in `docs/` or `canon/context/` names the entry point and the listing command, then stops, since the reader is one hop away
+- That counts as complete the same way `## Badges` treats zero as complete
+- A README missing an H1, or whose headings restate the tool that scaffolded it rather than the project, is unedited generator output. Draft over it.
+- Nothing here asks a session to preserve a section a scaffold wrote and nobody replaced
 
 ### Header block
 
@@ -73,7 +82,7 @@ The opening of a root README is a block of up to six elements in a fixed order.
 3. Badges: the block `### Badges` below governs, placed directly under the title.
 4. Claim: one line saying what the project does, taken from the manifest description or the repository description.
 5. Live link: the URL of the running surface, from a `homepage` field or a deploy config. Omit it when the project has no page or no known URL.
-6. Product screenshot: an image the project already commits and references, shown with alt text naming what it depicts. Present only when the project has a page. Omit it when no such image exists rather than writing a placeholder path.
+6. Product screenshot: an image the project already commits, with alt text naming what it depicts. Present only when the project has a page, and omitted rather than given a placeholder path.
 
 The description of 2-3 sentences follows the block and expands the claim rather than repeating it.
 
@@ -81,7 +90,9 @@ The description of 2-3 sentences follows the block and expands the claim rather
 - A project whose own page carries the screenshot omits it here and keeps the live link, which answers the slot rather than skipping it. Say so in the pull request that drops it.
 - The order is the block's rather than the page's. The screenshot sits last inside the block, which puts it in the first row of content a reader meets below the title, badges, and claim.
 
-#### Themes and wrappers
+### Themes and wrappers
+
+The block takes a project's styling as it is and adds nothing of its own.
 
 - A themed light and dark pair counts as one element in the slot rather than two. The block does not require a pair and leaves the handling of themes to the project.
 - Centering the block in an HTML wrapper is optional. Plain markdown reaches every host a README renders on, and a wrapper is styling a project can add.
@@ -99,11 +110,16 @@ Stars, forks, download counts, language chips, and "made with" badges fail. The
 
 - Cap the block at four. A fifth costs more scanning than any badge repays.
 - Give each badge alt text naming what it reports rather than the service that renders it. Write `npm version`, not `shields.io`.
-- Link each badge to the page a doubting reader would check next, which is the registry listing for a version badge and the run history for a status badge. A red badge with no route to the failing run reports a problem and withholds the only thing the reader wants.
+- Link each badge to the page a doubting reader would check next, which is the registry listing for a version badge and the run history for a status badge
+- A red badge with no route to the failing run reports a problem and withholds the only thing the reader wants
+
+### Pinning and verifying
 
-#### Pinning and verifying
+A badge reports a fact only when its source runs where the badge says and the value it renders is checked.
 
-- Pin a status badge to the branch whose health it claims to report, and confirm the workflow actually runs on that branch. A workflow triggered by pull requests alone never runs on the default branch, so an unpinned badge reports whichever branch ran last and a pinned one reports nothing at all. Fix the trigger, or drop the badge under the rule below.
+- Pin a status badge to the branch whose health it claims to report, and confirm the workflow actually runs on that branch
+- A workflow triggered by pull requests alone never runs on the default branch, so an unpinned badge reports whichever branch ran last and a pinned one reports nothing at all
+- Fix the trigger, or drop the badge under the zero-badge rule below
 - Verify a badge by the value it renders, not by its status code. A badge service answers 200 for a query it cannot satisfy, so a blank badge and a working one look identical to a status check.
 - Zero badges is a correct answer. A private project with no registry presence and no CI has nothing that passes the test, and an empty block beats a padded one.
 
@@ -115,6 +131,8 @@ Stars, forks, download counts, language chips, and "made with" badges fail. The
 
 ### Per project kind
 
+Each kind of project owes its reader a different first snippet.
+
 - For libraries/tools: include API quickstart
 - For applications/products: include usage instructions and configuration options
 - For CLI tools: include command examples with flags
@@ -127,6 +145,8 @@ A project is often several of these at once. Cover every type that applies rathe
 
 ### Template
 
+A README a scaffold would start from, with the required sections and the optional ones most projects carry.
+
 ````markdown
 # Project Name
 
@@ -171,6 +191,8 @@ See the [contributing guidelines](CONTRIBUTING.md).
 
 ### Correct
 
+Each line names what it is and links what it cites.
+
 ```plaintext
 Lightweight authentication library for Node.js with OAuth2 and JWT support.  # one line naming what it is
 ## Quick start                                                               # sentence case, a runnable snippet follows
@@ -179,6 +201,8 @@ Lightweight authentication library for Node.js with OAuth2 and JWT support.  # o
 
 ### Incorrect
 
+Each line pitches, pads, or inlines what belongs elsewhere.
+
 ```plaintext
 ## Why Use This?                                 # title case, and a pitch rather than a feature list
 Simply run the following command to install:     # filler qualifier before the command

package/claude/skills/document-health/SKILL.md

@@ -16,7 +16,7 @@ Three axes carry the report. Two answer from a verb and the third answers from a
 - `canon` absent from the path: stop. `❌ canon is not on PATH, so neither measured axis can be read.`
 - `git ls-files '*.md'` listing nothing: stop. `❌ No tracked markdown here, so there is no corpus to read.`
 - Run every command under `CANON_NON_INTERACTIVE=1` and prompt at no point. A caller reaching this from a rollout wave has nobody present to answer.
-- Branch on each record's own fields rather than on an exit status. An operator's shell profile may wrap `canon` in a function whose status comes from a trailing command, which reports every refusal as success.
+- Branch on each record's own fields rather than on an exit status, since a shell profile may wrap `canon` in a function whose trailing command reports every refusal as success
 - Repair nothing, write no file in the project, and open no pull request. Whoever read the report decides what to fix.
 
 ## Step 1: scope the corpus
@@ -51,9 +51,8 @@ Take the checkpoints from the record each verb returns rather than from a number
 
 A refusal, an absent key, and a subcommand the project's binary does not carry each leave an axis unread. Report it as unread against the documents it would have covered, name the read that could not be taken, and name the cause.
 
-`canon context audit` refuses with `reason: "no-folders"` in a project whose folders resolve to nothing, which is the ordinary shape where the layout differs from the one the verb looks for. That refusal is the honest answer rather than a failure, and reading it as an empty finding set reports a healthy corpus for documents nothing looked at.
-
-A narrower read is not an unread one. The sweep running on its regex layer alone still answered, so it is reported with the layer named rather than as an axis nothing reached.
+- `canon context audit` refuses with `reason: "no-folders"` where the layout is not the expected one. Reading that honest refusal as an empty finding set reports a healthy corpus nothing looked at.
+- A narrower read is not an unread one. The sweep running on its regex layer alone still answered, so report it with the layer named.
 
 ## Step 3: read the staleness axis