@erclx/canon 4.0.0

package/standards/context.md

@@ -0,0 +1,151 @@
+---
+title: Context entry reference
+description: Shape and content rules for .claude/context/<domain>.md entries
+---
+
+# Context entry reference
+
+Applies to per-domain narrative entries under `.claude/context/`. Skip for `index.md`, which is regenerated by `canon indexes regen`.
+
+## Scope
+
+Governs per-domain narrative entries under `.claude/context/`: their structure, the decisions and gotchas they carry, and what they leave to the code.
+
+Does not govern:
+
+- Cross-domain decisions and system-wide risks: `architecture.md`
+- Product scope, goals, and non-goals: `requirements.md`
+- Path-scoped coding rules: `rule.md`
+- Diagrams and wireframes, which answer structure and layout questions an entry hands off: `diagrams.md` and `wireframes.md`
+
+## Organizing principle
+
+Weight the entry toward what cannot be re-derived from the repo. That single rule sorts every section below.
+
+- Folder structure is re-derivable with `ls`. Cheap to regenerate, expensive to maintain by hand. Cap it hard.
+- Command surfaces are re-derivable with `--help` and already live in the CLI reference under `docs/`. Duplicating flag lists creates a second source of truth that drifts.
+- Decisions and gotchas cannot be re-derived at any price. They are the reason the folder exists.
+
+## What a working entry looks like
+
+An entry works when a session can read it and answer three questions without opening source:
+
+- Where do things live in this domain?
+- Why are they that way?
+- How do I add one more of what this domain holds?
+
+An entry that fails these is non-conforming regardless of whether it satisfies every section and ordering rule below. Shape is the means. These three questions are the test.
+
+## Frontmatter
+
+- `title` (required): sentence case, names the domain (`Web`, `API`, `Agents`).
+- `description` (required): one line describing what the domain covers.
+
+Both fields feed `.claude/context/index.md` when regenerated.
+
+## Required sections
+
+- `## Overview`: two to four lines. What the domain owns and where its boundary sits.
+- `## Layout`: one line per folder in owns-X form. Folders only, never files.
+  - Form: ``- `scripts/lib/` owns shared bash functions sourced by domain scripts``. Do not list every file under that folder with a description each.
+  - Implementation detail moves to `## Decisions`, `## Hidden contracts`, or `## Gotchas`.
+  - Omit the section when the domain owns no paths in the repo, as with a domain covering external tools. Inventing a line to satisfy the heading is the padding banned below.
+
+## Expected sections
+
+Include whenever the domain has content for them. Never pad an entry with an empty heading.
+
+- `## Decisions`: non-obvious choices and the reasoning behind them. The highest-value section in the folder and the one most often missing.
+- `## Gotchas`: workarounds, things tried and rejected, scar tissue worth preserving.
+
+## Optional sections
+
+Pick by what the domain is. Add domain-specific headings as needed.
+
+- `## CLI`: the command surface, only when the domain has one, and only as a list of what each verb does. Flags and JSON shapes stay in the CLI reference under `docs/`, linked rather than restated.
+- `## Workflow` or `## Adding a <thing>`: the procedure for the domain's most common task. Most sessions arrive asking how to add one more of the thing the domain holds.
+- `## Hidden contracts`: invariants the code does not self-document (shape constraints, skip rules, header semantics). Use `## Decisions` when the reader needs the reasoning rather than the invariant itself.
+
+## Ordering
+
+- Order sections `Overview`, `Layout`, `Decisions`, `Gotchas`, then everything else.
+- Entries get read top-down and often partially, so irreducible content sits above recoverable content.
+
+## The development entry
+
+Only the `development` entry carries this section. It is not a general-purpose heading for other domains.
+
+- `## Scripts`: a table of run commands (command plus purpose). The single discoverable surface for how to run the project. Keep run commands here, not scattered across `CLAUDE.md`.
+
+## What goes in
+
+- Per-domain narrative on how the code is structured and why
+- Decisions specific to the domain. Broader cross-domain decisions belong in `.claude/ARCHITECTURE.md`.
+- Constraints, gotchas, things tried and rejected
+- Domain-specific conventions that do not fit a `paths:`-scoped rule
+- A reference to another entry, spelled as the path that entry sits at rather than as its bare filename. A bare name resolves against whichever folder the reader is already in, so a domain that splits into subfolders strands every inbound reference and the break surfaces nowhere. A reference to a seed, a standard, or a file the project owns elsewhere keeps the form its own surface uses.
+
+## What does not go in
+
+- Exhaustive file trees with a description per file. Name folders and their responsibility under `## Layout` instead.
+- Restated `--help` output, flag tables, or JSON shapes.
+- A catalog a `list` command already returns. Link the command instead, so the entry cannot drift from it.
+- Function-level documentation for implementation modules. Read the code. The exception is the public surface of a shared utility module, where the entry is how a session finds an existing helper instead of duplicating it.
+- Rules. Those go in `.claude/rules/<scope>.md` with a `paths:` glob.
+- Tutorials or human onboarding. Those go in `docs/` if a public audience exists.
+- Generated content (API references). Generate, do not write by hand.
+- Anything already in `.claude/REQUIREMENTS.md` or `.claude/ARCHITECTURE.md`.
+- The history of how the domain reached its current shape. An entry describes the repository as it stands, so a change number, release label, or date attached to a change goes wherever the project tracks work.
+- A rejected alternative's provenance, which is the same rule at the one place the section above admits history. Keep what was tried and why it lost. Cut who tried it and when.
+
+## Length
+
+- Aim for one entry per domain. There is no hard cap. Length is a symptom, not the defect.
+- Past roughly 150 rendered lines, check three things before adding more: whether the entry still covers a single domain, whether it has filled with content `ls` or `--help` reproduces, and whether it has accumulated the history of its own changes. Fix whichever is true rather than trimming to hit a number. Rendered lines count as `markdown.md` defines them.
+- Where a bullet sits past the weight checkpoint `markdown.md` states, the overflow to move is the incident that motivated the decision, which specializes that rule's instruction to send the overflow to prose. Keep the current design and the alternative that lost, and send the incident to the change that introduced it, the issue that tracked it, or the research record behind it.
+- Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
+- Retire a decision or gotcha once its subject is gone, rewriting the bullet to state the current design rather than leaving the narration of what it replaced beside it. A rejected alternative is not a retired one, so what was tried and why it lost stays whatever its age. The rule above protects content whose subject is live, and this one releases content whose subject is not.
+- Rewrite a decision a later one replaced rather than appending the replacement beside it. The subject is still live, so the rule above does not reach it, and two bullets on one subject leave a reader to work out which of them is current. State the design that stands and keep the superseded reasoning only where it is the alternative that lost.
+- Split into a folder (`.claude/context/<domain>/<sub-area>.md`) when a domain has three or more sub-areas that do not fit cleanly in one file. That split is the natural ceiling.
+- Keep a split domain's `index.md` generated. The catalog body is rewritten on every regen, so the domain's own overview and layout belong in a sibling file rather than in it, and the `subtitle` is what names the file to start with.
+- Author a catalog that grows a row per shipped thing as a bullet list, never a markdown table. A table pads its columns to a shared width, so one row outgrowing its column reflows every row and turns a one-line edit into a whole-file rewrite that conflicts with any sibling branch. This is what forced the split above.
+
+## Examples
+
+### Template
+
+```markdown
+---
+title: API
+description: HTTP layer structure, route ownership, and request validation
+---
+
+# API
+
+## Overview
+
+Owns the HTTP surface end to end: routing, request validation, and response
+serialization. Business logic lives in `src/services/` and is called from here,
+never the reverse.
+
+## Layout
+
+- `src/routes/` owns the HTTP layer and request parsing
+- `src/services/` owns business logic with no HTTP concerns
+- `src/db/` owns persistence and schema migrations
+
+## Decisions
+
+- Validation happens at the route boundary using a schema library. Services trust their inputs.
+- Pagination uses opaque cursor tokens, never offset+limit. Cursor format stays opaque to clients.
+
+## Gotchas
+
+- The `/health` endpoint skips auth middleware. Liveness probes from the orchestrator do not carry tokens.
+- Database connection pool caps at 50. Concurrent requests over that block until a connection frees.
+
+## Hidden contracts
+
+- Route handlers return a plain object. The serializer wraps it in `{ data, meta }`. Handlers never wrap manually.
+- Cursor tokens are base64-encoded JSON of `{ id, sort }`. Any handler that issues a cursor must use the shared encoder.
+```

package/standards/design.md

@@ -0,0 +1,93 @@
+---
+title: Design reference
+description: Shape and content rules for .claude/DESIGN.md
+---
+
+# Design reference
+
+Applies to `.claude/DESIGN.md`. Captures visual intent and the decisions behind how things look, not a style guide, component spec, or framework reference. Update when a visual decision is made or a rule changes.
+
+## Scope
+
+Governs the visual-intent document at `.claude/DESIGN.md`: tokens described as intent, layout constraints, and the omissions that keep visual scope closed.
+
+Does not govern:
+
+- Screen layout, on-screen copy, and interaction intent: `wireframes.md`
+- Per-domain implementation narrative: `context.md`
+
+## What goes in
+
+- A token's exact value, anchored to the surface it was read from and tagged per `## The uncertainty tag` when unconfirmed. Fall back to intent language ("mid gray, muted text") only where no source exists yet to anchor from.
+- Layout constraints and sizing rules not obvious from wireframes
+- Visual rules a developer could get wrong without guidance
+- Non-obvious omissions ("no motion", "no custom icons") that prevent scope creep
+
+## What does not go in
+
+- CSS classes and prop names. Those live in code.
+- Anything that needs updating every time the code is refactored
+
+## Format
+
+- Use tables for token systems, one row per token. Use short bullets for component rules, one decision per line.
+- Plain English over technical notation. If a section could be removed and the developer would still build correctly from wireframes and code alone, remove it.
+- Keep table headers and role names intact so the render tooling can parse the token tables.
+
+## The uncertainty tag
+
+A cell no source anchors ends in ` ? verify`, written inside the cell rather than as a trailing column, since a trailing marker breaks the table parse. A cell wrapping itself in a code span carries the tag inside the span, as in `` `#ffffff ? verify` ``. Both spellings parse.
+
+The renderer splits the tag off the value, so a swatch and a font sample are built from the value alone and the marker shows beside it. The preview also reports how many cells are anchored against how many are tagged, which is the reading a reviewer takes the record's overall confidence from.
+
+Which columns that ratio reads is fixed by the table rather than by the record. The first column of each table names its row, and `Multiplier` and `When used` restate what the row already carries, so none of them is something a source could anchor and none is counted. That leaves `Intent` and `Value` in Color, `Family`, `Weight`, `Size`, and `Line height` in Typography, `Value` in Spacing, and `Radius` and `Width` in Borders. A cell tagged outside that set counts anyway, so a marker the preview draws is never missing from the ratio beside it.
+
+A prose section takes its uncertainty inline instead, in a sentence saying what is proposed and what has yet to confirm it. A tag appended to a paragraph renders verbatim.
+
+## Sections
+
+Use `## Personality`, `## Color`, `## Typography`, `## Spacing`, `## Borders`, `## Motion`, and `## Iconography`. The token tables carry fixed headers the renderer reads.
+
+## Template
+
+The column headers are the strings the renderer parses, read by exact key, so they stay verbatim. Row names are not. Each is slugged into the variable name it emits, which leaves a project free to rename a row, add one, or drop one it has no use for.
+
+```markdown
+# Design
+
+## Personality
+
+<one paragraph on voice, tone, and the feeling a user should have>
+
+## Color
+
+| Role   | Intent           | Value   |
+| ------ | ---------------- | ------- |
+| <role> | <what it is for> | <value> |
+
+## Typography
+
+| Role   | Family   | Weight   | Size   | Line height |
+| ------ | -------- | -------- | ------ | ----------- |
+| <role> | <family> | <weight> | <size> | <height>    |
+
+## Spacing
+
+| Step   | Multiplier   | Value   |
+| ------ | ------------ | ------- |
+| <step> | <multiplier> | <value> |
+
+## Borders
+
+| Role   | Radius   | Width   | When used   |
+| ------ | -------- | ------- | ----------- |
+| <role> | <radius> | <width> | <when used> |
+
+## Motion
+
+<whether motion is used at all, and if so the default duration and easing>
+
+## Iconography
+
+<style, source library, and whether custom icons are allowed>
+```

package/standards/diagrams.md

@@ -0,0 +1,152 @@
+---
+title: Diagram reference
+description: Shape and content rules for .claude/diagrams/<kind>.md files
+---
+
+# Diagram reference
+
+Applies to per-kind entries under `.claude/diagrams/`. Skip for `index.md`, which is regenerated by `canon indexes regen`.
+
+A diagram entry answers one question about the system with one or more Mermaid diagrams and the prose that makes them readable. It is not a rendering of the file tree. The check for any single line: does it tell a reader something the code layout would not have told them? If not, it belongs in `.claude/context/`.
+
+## Scope
+
+Governs per-kind diagram entries under `.claude/diagrams/`: which question each answers, the Mermaid source, the accessibility fields, and the explanation prose beneath. It states the voice for that prose, which is the yield the `write-human` skill grants a surface whose own standard sets one.
+
+Does not govern:
+
+- Rhythm and sentence construction in explanation prose: the `write-human` skill, whose rules the yield does not lift beyond voice
+- Language, word choice, punctuation, and formatting in explanation prose and node labels: `markdown.md`, which the yield does not reach
+- The mechanism behind any component a diagram draws: `context.md`
+- UI layout, on-screen copy, and interaction intent: `wireframes.md`
+- The decision record a components diagram is drawn from: `architecture.md`
+
+## What a working entry looks like
+
+An entry works when a reader who has not opened the repository can answer its question:
+
+- What are the parts, and which ones talk to each other?
+- Which direction does the work flow, and where does it start?
+- What would break if one box were removed?
+
+An entry that fails these is non-conforming regardless of whether it satisfies every section rule below. The fences are the means. These three questions are the test.
+
+## Frontmatter
+
+- `title` (required): sentence case, names what the entry answers (`System context`, `Request flow`), not what it draws.
+- `description` (required): one line on which question the entry settles and which source signal drives it.
+- `category` (required): the diagram kind, one of the five in Entry kinds. It is the grouping field `canon indexes regen` renders headings from.
+- `verified` (required): the short commit SHA an entry was last checked against and the ISO date of that check, separated by a space (`73e9a3f8 2026-08-02`). A stub nobody has drawn yet carries the literal `TODO: never verified` instead, which is the one other accepted value.
+- `stale` (optional): one line naming what changed under the entry since that check. Nothing writes it on its own, so it sits on an entry because a reader put it there and is absent everywhere else.
+
+The first three feed `.claude/diagrams/index.md` when regenerated. The catalog sorts categories alphabetically rather than in narrative order, so an entry cannot rely on its position to introduce another. Each entry names its own starting point, and the catalog's subtitle routes a first-time reader to the system context entry.
+
+The marker fields reach the catalog through neither route. `canon indexes regen` reads `title`, `description`, and `category` and ignores every other key, so a marker changes no generated file. A reader picks it up by opening the entry, which is where it sits above the diagram and where anyone deciding whether to trust the picture is already standing.
+
+One writer touches `verified`, which is the pass that renders an entry and reads the picture back, and it clears `stale` at the same time. A reader who notices the picture has drifted writes `stale` by hand. Keeping the two fields apart is what lets a reader tell a diagram nobody has checked since the code moved from one that was checked and found correct.
+
+## Entry kinds
+
+Five kinds, each with a fixed filename and a fixed `category` value. Write a kind only when its source signal exists, and leave the rest absent rather than padding the folder.
+
+- `system-context.md`, category `System context` (`flowchart TB`): who uses the system, what it talks to, and where its boundary sits. Drawn from `.claude/REQUIREMENTS.md`. This is the entry a reader outside the team opens first, and the only kind that draws the world outside the boundary.
+- `components.md`, category `Components` (`flowchart TB` with `subgraph` boundaries): the layered structure inside the boundary. Drawn from `.claude/ARCHITECTURE.md`.
+- `request-flow.md`, category `Request flow` (`sequenceDiagram`): a request lifecycle, an agent loop, or an interaction between actors.
+- `data-pipeline.md`, category `Data pipeline` (`flowchart TB`): retrieval, ranking, queues, or ETL.
+- `deployment.md`, category `Deployment` (`flowchart TB`): hosts, services, and infrastructure config.
+
+The filenames are fixed rather than free, so a session refreshing one kind finds the file it is meant to overwrite instead of writing a second entry beside it under a name of its own.
+
+Stay inside `flowchart` and `sequenceDiagram`. C4, state, ER, and class diagrams render inconsistently across viewers.
+
+The kinds drift at rates spanning roughly an order of magnitude, which is why they are separate files. A deploy change rewrites one entry and leaves the other four untouched.
+
+A second entry for one kind takes a suffixed name (`request-flow-admin.md`) and repeats the kind's `category` verbatim, which is what the grouping field is for. One entry per kind is the ordinary case, so most catalogs show one entry under each heading.
+
+## Layout
+
+- Declare `flowchart TB` by default. Mermaid ignores a subgraph's direction whenever that subgraph links outward, and an architecture diagram links across its subgraphs as the normal case, so top-bottom is a declaration rather than a guarantee.
+- Restructure a diagram that renders diagonal or left-to-right. Repeating the direction keyword does not fix it.
+- Render a context, component, or pipeline diagram taller than wide. A `sequenceDiagram` is wide by construction and is exempt.
+- Do not let independent nodes render in a row. A row of siblings reads as a sequential chain and asserts a pipeline the system does not have.
+- Do not converge many edges on one node from one side. A crossing bundle is unreadable whatever it encodes.
+- Keep node labels short. Three or four words max. Detail goes in the paragraph below the diagram.
+- Use `<br/>` for a second short line on a node when the label is two ideas, never for a sentence.
+- Subgraphs are for grouping unrelated lanes such as offline versus online or browser versus server. Do not subgraph a single linear flow.
+
+## Budgets
+
+- Hold a diagram to roughly 5 to 10 nodes. Split it past 15.
+- Watch edge count harder than node count. It binds first, and a diagram whose edges outnumber its nodes is already too dense to read.
+- Treat a diagram that cannot be described in one sentence as two diagrams.
+- Keep an entry to one diagram by default. A second fence in the same file needs its own H2 naming what it adds, and a third is a sign the entry covers two kinds.
+- Warn rather than refuse on a budget, and name the split that would fix it. These numbers come from published Mermaid practice rather than from a measurement in this repository, so a hard refusal on them will be wrong sometimes and unarguable when it is.
+
+## Accessibility
+
+- Give every diagram `accTitle` and `accDescr`. `accTitle` names what the diagram answers. `accDescr` states the structure in one sentence for a reader who cannot see the render.
+
+## Explanation
+
+- One to three short paragraphs below each diagram. Plain English and pedagogical.
+- Lead with what the diagram shows. Follow with why this shape was chosen and what alternative was rejected, when the choice was non-obvious.
+- Reference one or two specific code paths the reader can open. Do not enumerate every file. Spell each one exactly, since a reader deciding whether the entry still holds starts by opening the paths it names and a path that resolves to nothing costs them that read.
+- Do not duplicate prose across entries. An entry that restates its neighbor has taken the neighbor's job.
+- The audience is mixed, so vocabulary runs as a gradient across the set. `System context` assumes no knowledge of the repository. `Deployment` may assume the reader has read the others.
+
+This section states the voice for the surface, which is what claims the yield the `write-human` skill grants to a surface whose own standard sets it. Explanation prose is pedagogical here and the default developer-facing voice does not apply. The yield covers voice alone. The rhythm and density rules that skill carries stay in force, as do the language bans, punctuation, and formatting in `markdown.md`, which grants no yield at all.
+
+## Verification
+
+- Judge a diagram from its rendered image, not from its source. Direction, sibling rows, and edge bundles are visible only in the output.
+- Render to PNG. An SVG export reads back as markup with no recoverable spatial meaning.
+- Apply four tests as a reviewer, the same ones the author applied: direction held, no sibling row reading as a chain, no crossing edge bundle, taller than wide outside a sequence diagram.
+- State which verification was skipped when no renderer is available. A diagram written without a render is still shippable, and one reported as verified without a render is not.
+
+## What moves to .claude/context/
+
+Implementation detail that answers how a component is built belongs in a `.claude/context/` entry, not a diagram:
+
+- Function names, call signatures, and lifecycle ordering
+- Library versions, config keys, and environment variable names
+- Retry counts, timeouts, and batch sizes
+- Workarounds and rejected approaches that need more than one sentence
+
+Reference the context entry by path when a reader needs the mechanism. The diagram stays answerable on its own for structure and flow.
+
+## Maintenance
+
+- When the system changes, update the entries whose source signal changed and leave the rest alone. Rewriting the folder wholesale reproduces the defect the per-kind split exists to end.
+- A diagram showing a defunct host or library is worse than no diagram. Audit the affected entry in the same PR.
+- `System context` has no named source signal beyond `.claude/REQUIREMENTS.md`, so nothing tells a session it went stale. Re-read it when the boundary or the set of external dependencies moves.
+- Nothing watches the folder for you. The entries are redrawn on demand rather than swept on every ship, so `verified` carries the whole signal: an entry whose date sits far behind the branch is due a read, and no pass is going to name which one.
+- The explanation paragraphs around a Mermaid block are prose and follow `markdown.md` and the `write-human` skill. The fenced block itself is not, which is why a check scoped to prose is the wrong thing to rely on for what sits inside it.
+- The punctuation bans still apply to node and subgraph labels, and nothing checks them there. An em dash in a label passes every gate the repository has, so read the labels before shipping the entry.
+
+## Template
+
+The filename and the `category` value both come from Entry kinds and are fixed per kind. A stub nobody has drawn yet carries `TODO: never verified` in place of the SHA and date. The node names and labels inside the fence are placeholders, written bare because Mermaid reads an angle bracket as markup.
+
+````markdown
+---
+title: <what the entry answers>
+description: <which question it settles and which source signal drives it>
+category: <the kind, verbatim from Entry kinds>
+verified: <short-sha> <YYYY-MM-DD>
+---
+
+# <what the entry answers>
+
+```mermaid
+flowchart TB
+    accTitle: what the diagram answers
+    accDescr: the structure in one sentence for a reader who cannot see the render
+
+    a[first part] --> b[second part]
+    b --> c[third part]
+```
+
+<One paragraph leading with what the diagram shows.>
+
+<One paragraph on why this shape was chosen and what was rejected, where the choice was non-obvious. Name one or two code paths the reader can open.>
+````

package/standards/glossary.md

@@ -0,0 +1,75 @@
+---
+title: Glossary reference
+description: Frontmatter, entry shape, ordering, and the rules deciding which terms a glossary carries
+---
+
+# Glossary reference
+
+Applies to a glossary, the file holding one entry per term a body of material defines. It changes whenever the material names a concept a reader cannot look up yet, and it is revised in place rather than appended to.
+
+## Scope
+
+Governs a glossary at `.claude/teach/<nn>-<topic>/GLOSSARY.md` and at whatever path a surface fixes for one it holds: its frontmatter, entry shape, ordering, grouping, and the rules deciding which terms it carries.
+
+Does not govern:
+
+- The folder a learning workspace lays out around its glossary, and the other files in it: `teach.md`
+- Which surface a glossary moves to once it leaves the material that produced it, which belongs to the surface driving that move
+- Voice, rhythm, and sentence construction: the `write-human` skill
+- Headings, punctuation, word choice, and file references: `markdown.md`
+
+## What a working glossary looks like
+
+A glossary works when a reader who meets a term in the material settles it here without opening the page that introduced it:
+
+- Which word does this material use for the concept, and which words does it deliberately not use?
+- What does the term mean, stated without leaning on the term itself?
+- Where does the term appear, so a reader can see it used rather than only defined?
+- Does every entry carry a term the material actually uses?
+
+A glossary failing these is non-conforming even when it satisfies every shape rule below.
+
+## Frontmatter
+
+- `title` (required): names the material the terms come from, in sentence case
+- `description` (required): one line naming what a reader gets from the entries
+
+## Entries
+
+- Write one entry per term, as a single bullet.
+- Lead the bullet with the term as a bolded span, then the definition in one or two sentences.
+- Define the term without using it. A definition that spends the term explains nothing to the reader who arrived not knowing it.
+- Name where the term first appears, so a reader can reach one use of it in context.
+- Keep an entry to the meaning. Worked detail belongs on the page that teaches the term.
+- Sort entries alphabetically, so a reader who knows only the word finds it without reading the file.
+
+## Which terms it carries
+
+- Add a term once the material has used it, never ahead of that. A glossary front-loaded with terms nothing has introduced is a syllabus rather than a reference.
+- Pick one word per concept and use that word everywhere. A glossary carrying two words for one thing hands the reader a choice it exists to remove.
+- List each rejected synonym as an alias to avoid inside the entry that won, so a reader arriving with the wrong word lands on the right one.
+- Use the glossary's own terms inside other definitions. A definition reaching for a synonym of a term defined two entries down teaches the reader a word the material does not use.
+- Revise an entry the material has moved under rather than adding a second one narrating the change.
+
+## Grouping
+
+- Keep a short glossary as one alphabetical list under the title. Grouping a handful of entries costs a heading per category and saves no lookup.
+- Group a glossary long enough that one list stops helping under `##` headings by category, sorted alphabetically within each. Roughly two screens of entries is the signal.
+- Name each category so a reader picks it from the term alone. A category a reader cannot predict makes the grouping a second thing to search.
+- State a departure from any rule above in the file itself, naming what it departs from and why. A glossary serving no single body of material is the case that produces one, since a term drawn from everywhere has no first appearance to name.
+
+## Template
+
+```markdown
+---
+title: <Material the terms come from>
+description: <one line naming what a reader gets from these entries>
+---
+
+# <Material the terms come from>
+
+<One line on which material these terms come from and when the file changes.>
+
+- **<Term>**: <the meaning in one or two sentences, written without using the term>. Avoid <rejected synonym>. First appears in `<page or lesson>`.
+- **<Term>**: <the meaning in one or two sentences, written without using the term>. First appears in `<page or lesson>`.
+```