@erclx/aitk 0.8.0

package/standards/bundled/pr.md

@@ -0,0 +1,124 @@
+---
+title: Pull request reference
+description: Pull request title and body conventions
+consumers: git-split, git-pr, claude-standards-audit
+---
+
+# Pull request reference
+
+## Title
+
+- Format: `<type>(<scope>): <subject>`
+- Casing: lowercase for `<type>`, `<scope>`, and first word of `<subject>`
+- Length: 72 characters maximum
+
+## Content
+
+- Use imperative mood for all content (`add`, `fix`, `refactor`)
+- Do not start with "This PR," "This commit," "Included are," or "I have"
+- Do not use buzzwords (`seamless`, `robust`, `game-changer`, `enhanced`)
+- Do not describe historical behavior or unchanged code. Describe new behavior only.
+- Do not include future promises or speculative documentation
+- Do not explain obvious changes (formatting, renaming variables)
+- Do not duplicate commit messages verbatim
+
+## Sections
+
+- `## Summary`: 1-2 sentences following `<Action Verb> <Direct Object> to <Result>`, expand for clarity if needed
+- `## Key Changes`: name actual files, functions, or modules (e.g., `AuthService.verify()` not "auth handler"). Always use bullet points, never prose.
+- `## Technical Context` (optional): 1-2 lines of architectural reasoning explaining why, not what
+- Omit Technical Context for docs, config, or trivial changes
+- Use bullet points for multiple reasons, one sentence for a single reason
+- `## Testing` (optional): specify exact commands or test cases run
+- Omit Testing for docs, config, or trivial sync changes
+- Use checkboxes, never prose. See Testing discipline for which box gets ticked.
+- `## For the reviewer` (optional): what the reviewer should confirm, one bullet per request
+- Visuals: include only when they clarify architecture, UI, or complex logic flows
+
+## Testing discipline
+
+- Run the check before writing its line. A `- [ ]` reports a check that has not run rather than one that is planned.
+- Tick the box and state the observed result. `- [x] npm test passes, 42 tests` beats `- [ ] run npm test`.
+- Quote the count or output the run reported, never a figure carried from elsewhere.
+- Leave a box unchecked only when a human is required, and name which human and why on the same line.
+- Human-only covers visual or aesthetic judgment, anything needing credentials or a live third-party service, anything needing a second machine or a fresh OS, and judgment about whether a boundary or an abstraction reads correctly. The agent runs everything else.
+- Put a request for the reviewer under `## For the reviewer`. It is a request rather than unfinished testing, so it never appears as an unchecked Testing box.
+
+## Formatting
+
+- End every bullet point with a period
+
+## Examples
+
+### Template
+
+```markdown
+## Summary
+
+<Action Verb> <Direct Object> to <Result>.
+
+## Key Changes
+
+- <Verb> <specific component/file/function> (<reason if non-obvious>)
+- <Verb> <specific component/file/function>
+
+## Technical Context
+
+- <Architectural reasoning explaining why, not what>
+
+## Testing
+
+- [x] <Command run> <observed result>
+- [x] <Edge case verified> <what was observed>
+- [ ] <Human-only check> (<which human, why>)
+
+## For the reviewer
+
+- <What the reviewer should confirm>
+```
+
+### Correct
+
+```markdown
+## Summary
+
+Update auth middleware to enforce jwt expiration checks. # imperative + direct object + result
+
+## Key Changes
+
+- Add `verifyExpiration()` to `src/auth/validators.ts`. # specific function + file path
+- Refactor `AuthService.authenticate()` to handle 401 codes. # named component + clear change
+
+## Technical Context
+
+- Migration to stateless session management for horizontal scalability. # why, not what
+
+## Testing
+
+- [x] `npm run test:auth` passes, 42 tests. # command run + observed result
+- [x] Expired token rejected with a 401 against a local server. # edge case + what happened
+- [ ] Staging smoke test (release owner, needs staging credentials). # unchecked + which human + why
+
+## For the reviewer
+
+- Confirm the 401 and 403 split reads correctly for the public API. # a request, not a test result
+```
+
+### Incorrect
+
+```markdown
+## Summary
+
+This PR updates the authentication system to be more robust. # "This PR" opener + buzzword
+
+## Key Changes
+
+- Updated auth middleware files # vague, no specific component, no period
+- The old system used to check tokens differently # describes historical behavior
+
+## Testing
+
+- Tested manually # no specific command or case
+- [ ] `npm run test:auth` # unchecked box for a check the agent can run
+- [ ] Reviewer confirms the error split reads correctly # a reviewer request, belongs under `## For the reviewer`
+```

package/standards/bundled/roadmap.md

@@ -0,0 +1,52 @@
+---
+title: Roadmap reference
+description: Shape and content rules for .claude/ROADMAP.md
+consumers: claude-roadmap
+---
+
+# Roadmap reference
+
+Applies to `.claude/ROADMAP.md`. Sequences the scope from `.claude/REQUIREMENTS.md` into ordered versions, each a usable increment. Update when the sequence changes or a version ships. The roadmap is committed because the sequence and its rationale are shared strategic truth a fresh session needs, unlike `.claude/tasks/`, which is ephemeral scratch.
+
+The roadmap is one scannable table. That is what keeps it distinct from `.claude/tasks/`: the roadmap is an overview read at a glance, while tasks are worked one file at a time.
+
+## What goes in
+
+- One row per version, ordered top to bottom by sequence
+- A status per version: active, next in line, or deferred
+- The observable outcome each version delivers, as a short phrase
+- The features a version groups, by name, drawn from the MVP list in `.claude/REQUIREMENTS.md`
+- The version each row depends on, and a short why
+
+## What does not go in
+
+- Task breakdown, checkboxes, or per-feature file lists. Those live in `.claude/tasks/` and `.claude/plans/`.
+- Implementation detail, API names, or component references
+- Rationale for tech choices. That belongs in `.claude/ARCHITECTURE.md`.
+- Sentence-long cells. Keep each cell terse so the table stays scannable.
+
+## Format
+
+One table. Columns, in order:
+
+- `Version`: the `vX.Y` phase label. Phase-label format is governed by `standards/versioning.md`.
+- `Status`: `Now` for the active version, `Next` for sequenced upcoming versions, `Later` for deferred themes.
+- `Outcome`: what the user can do once this version ships, as a phrase.
+- `Features`: the feature names this version groups, comma-separated.
+- `Depends on`: the version this one needs and a short why, or `none` when independent.
+
+## Template
+
+```markdown
+# Roadmap
+
+| Version | Status | Outcome  | Features             | Depends on         |
+| ------- | ------ | -------- | -------------------- | ------------------ |
+| v0.1    | Now    | <phrase> | <feature>, <feature> | none               |
+| v0.2    | Next   | <phrase> | <feature>            | v0.1, for <reason> |
+| v0.3    | Later  | <phrase> | <feature>            | none               |
+```
+
+## Lifecycle
+
+The roadmap sequences a finite, known scope. When the last version ships, the scope is exhausted and the project cuts a semver release per `standards/versioning.md`. Later work arrives as discrete items, a fresh requirements pass or tracked issues, rather than extending the original roadmap without end.

package/standards/bundled/snippets.md

@@ -0,0 +1,57 @@
+---
+title: Snippet reference
+description: Snippet reference and authoring conventions
+consumers: create-snippet
+---
+
+# Snippet reference
+
+## What a snippet is
+
+A snippet is a short, focused prompt stored as a plain markdown file. Invoke one to insert a prepared instruction into any AI chat without retyping it. Each snippet covers one purpose. If a prompt needs headers or multiple goals, use a system prompt instead.
+
+## Invocation channels
+
+- Chrome extension: type `>slug` in a supported chat UI (claude.ai, gemini.google.com) to insert the snippet text inline
+- Claude Code terminal: prefix the install path with `@` (e.g. `@.claude/snippets/claude/feature`)
+- Snippets install preserving the source folder structure. A snippet at `claude/edit.md` installs as `.claude/snippets/claude/edit.md` and is invoked as `@.claude/snippets/claude/edit`
+
+## Use patterns
+
+- Run-as-is: invoke and send immediately. The snippet is self-contained and needs no extra context.
+- Invoke-then-add-context: invoke the snippet, then append specifics in the same message (e.g. invoke `claude-feature`, then add the feature name or extra constraints)
+- Invoke-on-history: invoke after a discussion. The snippet uses prior conversation as implicit context with no additional input needed (e.g. invoke `claude-figma` after discussing a design).
+
+## Authoring
+
+- One focused purpose per snippet. If it needs headers or multiple goals, use a system prompt instead.
+- Self-contained. No references to external files or assumed prior context.
+- No user fill-in placeholders. If a value depends on context, the user adds it after invocation.
+- Plain markdown only. No YAML frontmatter, no headers, no nested structure.
+- Filename is the slug: kebab-case, no capitals, no underscores
+
+## Structure
+
+- Lead with a verb. Open with an imperative that states the job immediately.
+- One instruction per sentence. Do not stack multiple actions into one sentence.
+- For sequential steps, use a numbered list with one action per item.
+- When the output has a fixed shape, show it in a fenced code block with a language identifier.
+- Put constraints and exclusions last, not inline with the main instructions.
+
+## Examples
+
+### Correct
+
+```markdown
+I want to implement the following. Scan relevant files and list conflicts. Do not implement. # user adds feature after invocation
+Scan relevant files and list conflicts. Do not implement. # run-as-is, no context needed
+```
+
+### Incorrect
+
+```markdown
+I want to implement: <feature or task name> # redundant fill-in, add context after invocation instead
+See ARCHITECTURE.md before starting. # external dependency, not self-contained
+
+## Overview\n## Steps # headers belong in a system prompt, not a snippet
+```

package/standards/bundled/standard.md

@@ -0,0 +1,52 @@
+---
+title: Standard reference
+description: Shape and content rules for authoring a standard
+consumers: create-standard
+---
+
+# Standard reference
+
+## Overview
+
+A standard is a target-facing authoring convention for one document type. It installs into a project under `.claude/standards/` and is consumed by skills and developers alike. One standard governs one doc type. Split unrelated conventions into separate files.
+
+## Frontmatter
+
+- Start the file with a frontmatter block carrying `title` and `description`.
+- `title`: names the doc type in sentence case, suffixed `reference` (`Commit reference`, `Branch reference`).
+- `description`: one line naming what the standard covers. It becomes the index link label on install.
+
+## Structure
+
+- Use sentence case for every heading.
+- Flat `##` rule groups for a single-topic standard. Group `##` headers by concern for a multi-topic one.
+- When one `##` section covers more than one sub-concern, split its bullets into `###` subgroups, one subgroup per sub-concern. A flat bullet list under an `##` covers a single sub-concern. Roughly seven bullets is a signal to split, not a hard cap.
+- Order groups from the most-used rule down to the edge case.
+
+## Rules
+
+- Write rules as imperative bullets: one rule per bullet, one concern per group.
+- State the forbidden shape rather than enumerating allowed options, so a rule survives new categories.
+- Cut any rule that resists a crisp one-line phrasing.
+- Do not pad with filler prose. Every line earns its place as a usable reference entry.
+
+## Success criterion
+
+- State what a conforming artifact achieves, not only what shape it takes. A standard that specifies structure exhaustively and success nowhere cannot be argued against, only edited on taste.
+- Write the criterion as a small set of questions the artifact must answer, or a task a reader must be able to complete from it. Keep it checkable by a person in one sitting.
+- Place it near the top, above the shape rules it governs. The shape rules are the means and the criterion is the test.
+- Say that an artifact failing the criterion is non-conforming even when it satisfies every shape rule. Without that line the criterion reads as advice.
+- Add a criterion to an existing standard when that standard is next exercised, not in a sweep. A criterion written without a failure to point at is the taste-based edit this section exists to prevent, so a standard with no criterion yet is a known gap rather than a violation.
+
+## Changing a standard
+
+- Change a standard on a failure, not on a finding. A finding is that the docs say X or a paper suggests Y. A failure is a conforming artifact that satisfied every shape rule and still missed the success criterion.
+- Park findings wherever the project tracks pending work, or in the standard's own backlog section when it tracks none. They are hypotheses to test, not instructions to apply.
+- Cite the failing artifact in the change that fixes it, so the next reader can tell which rules were paid for by evidence.
+
+## Examples
+
+- Include examples only where a rule is non-obvious. A self-evident rule needs none.
+- When shown, label them `### Correct` and `### Incorrect` with an inline `# reason` on each entry.
+- Keep to two or three entries. Show the pattern, not a catalog.
+- Keep each entry a short one-liner or command. Do not write multi-line correct and incorrect function blocks.

package/standards/context.md

@@ -0,0 +1,132 @@
+---
+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 `aitk indexes regen`.
+
+## 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
+
+## 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`.
+
+## Length
+
+- Aim for one entry per domain. There is no hard cap. Length is a symptom, not the defect.
+- Past roughly 150 lines, check two things before adding more: whether the entry still covers a single domain, and whether it has filled with content `ls` or `--help` reproduces. Fix whichever is true rather than trimming to hit a number.
+- Never cut a `## Decisions` or `## Gotchas` entry to shorten a file. Cut a `## Layout` or `## CLI` section instead.
+- 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.
+
+## 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,31 @@
+---
+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.
+
+## What goes in
+
+- Tokens described as intent ("mid gray, muted text"), not computed values. Exact values live in code.
+- 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, computed values, component filenames, and prop names. Those live in code.
+- UX copy and interaction flows. Those live in the wireframes.
+- 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.
+
+## Sections
+
+Use `## Personality`, `## Color`, `## Typography`, `## Spacing`, `## Borders`, `## Motion`, and `## Iconography`. The token tables carry fixed headers the renderer reads.

package/standards/diagrams.md

@@ -0,0 +1,55 @@
+---
+title: Diagram reference
+description: Conventions for Mermaid diagrams in .claude/DIAGRAMS.md
+---
+
+# Diagram reference
+
+Applies to Mermaid diagrams in `.claude/DIAGRAMS.md`. Goal: diagrams that render cleanly in narrow-column renderers (VS Code preview, GitHub PR view, Cursor) and read pedagogically without surrounding prose.
+
+## 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 component, context, 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 (offline versus online, 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.
+- 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.
+
+## 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.
+
+## Narrative
+
+- Build a narrative arc across the file, not a parallel list of unrelated views. Start with the whole system in five or six boxes. Drill into one phase per section.
+- Order sections chronologically when possible: framing, then setup, then a query travels through, then measurement.
+- One H2 per diagram. The H2 names what the diagram answers, not what it shows ("How the corpus gets populated", not "Corpus ingestion").
+
+## Explanation
+
+- One to three short paragraphs below each diagram. Plain English, pedagogical, no marketing copy.
+- 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.
+- Do not duplicate prose between sections. Each paragraph earns its line.
+
+## Maintenance
+
+- When the system changes (new layer, new provider, new deploy posture), audit `.claude/DIAGRAMS.md` in the same PR. A diagram showing a defunct host or library is worse than no diagram.
+- Mermaid blocks are inside fenced code, so the prose-standards hook ignores them. The explanation paragraph below is still prose. Follow `standards/prose.md`.

package/standards/index.md

@@ -0,0 +1,21 @@
+---
+title: Standards
+subtitle: Reference docs for consistent authoring across the toolkit and target projects.
+---
+
+# Standards
+
+Reference docs for consistent authoring across the toolkit and target projects.
+
+- [Architecture reference](architecture.md): Shape and content rules for .claude/ARCHITECTURE.md
+- [Context entry reference](context.md): Shape and content rules for .claude/context/<domain>.md entries
+- [Design reference](design.md): Shape and content rules for .claude/DESIGN.md
+- [Diagram reference](diagrams.md): Conventions for Mermaid diagrams in .claude/DIAGRAMS.md
+- [Prose reference](prose.md): Voice, structure, formatting, and language rules for reference markdown
+- [Readme reference](readme.md): Readme structure and content conventions
+- [Requirements reference](requirements.md): Shape and content rules for .claude/REQUIREMENTS.md
+- [Governance rule reference](rule.md): Rule frontmatter, body shape, and voice for .claude/rules files
+- [Claude skill reference](skill.md): Claude skill structure and authoring rules
+- [Tasks reference](tasks.md): Folder layout, filename convention, and content rules for .claude/tasks/
+- [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, commits, and tags
+- [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/prose.md

@@ -0,0 +1,122 @@
+---
+title: Prose reference
+description: Voice, structure, formatting, and language rules for reference markdown
+---
+
+# Prose reference
+
+Applies to markdown reference docs, READMEs, and inline documentation in repos. It is the default voice for `.md` files and yields to any surface with its own voice, such as blogs, emails, changelogs, or commit messages.
+
+## Voice
+
+- Write for a developer who is scanning, not studying. Every sentence should be understandable on first read.
+- Use active voice. Default to present tense unless past or future tense is factually correct.
+- Prioritize direct verbs and plain words, using the minimum necessary. Write `use` not `utilize`, `help` not `facilitate`, `is` not `serves as`.
+- Vary sentence length and opening structure to break uniform cadence. Do not start consecutive sentences the same way.
+- Use substantive connectives where flow matters, but never add words solely for rhythm. Terse reference prose needs no padding.
+- Be direct on established facts. Hedge on genuinely uncertain claims.
+- Assume developer-level technical knowledge. Skip hand-holding explanations.
+- Keep paragraphs to four sentences or fewer. Split longer blocks at the next logical boundary.
+
+## Structure
+
+### Headings
+
+- H1 for document title, H2 for main sections, H3 for subsections
+- Use sentence case for all headings (H1, H2, H3)
+- Proper nouns and product names retain their casing in headings
+
+### Paragraphs and lists
+
+- Front-load key information in each paragraph. Keep paragraphs concise and scannable.
+- Every sentence must provide new information. Cut redundant context.
+- Use prose by default. Reserve bullets for discrete, unrelated items.
+- Keep bullets tight. If a bullet needs more than a couple of sentences, it belongs in prose.
+
+## Formatting
+
+### Lists
+
+- Use dashes (`-`) not asterisks (`*`) for bulleted lists
+- Do not end single-sentence or fragment bullets with a period. Use periods when a bullet has two or more sentences.
+- For key path lists, use colon format: `- \`src/\`: description`. Never use an em dash.
+- Do not introduce a list with a "Here are the X:" or "The following X:" lead-in
+
+### Code and identifiers
+
+- Wrap commands, API names, file paths, and code identifiers in backticks
+- Use a language identifier on all fenced code blocks (`markdown`, `typescript`, `plaintext`). Never use a bare ` ``` `
+- In ASCII tree diagrams, use `←` for inline annotations. Never use `#`.
+
+### Punctuation
+
+- Do not use em dashes (`—`) or semicolons (`;`). Rewrite or restructure the sentence to avoid them.
+- Do not use parenthetical asides in prose (`the config (which is optional) controls...`). Split into its own sentence or drop it. Parentheses in rule definitions for grouping examples are fine.
+
+### Emphasis and dividers
+
+- Do not over-format with excessive bold, italic, or header usage
+- Do not use horizontal rules or dividers (`---`) in body content. The `---` delimiters of a YAML frontmatter block at the top of the file are allowed.
+
+### Links and file references
+
+- Use descriptive anchor text for links. Avoid `click here` or `read more`.
+- Wrap file references in backticks by default. Use a labeled markdown link (`[label](path)`) only on rendered-for-human surfaces (`README.md`, `docs/`) for cross-folder navigation. Never repeat the path verbatim as the label.
+
+## Language
+
+- Use American English spelling. Prefer `-ize` over `-ise`, `-or` over `-our`, `-er` over `-re` (`organize`, `analyze`, `summarize`, `recognize`, `behavior`, `color`, `center`)
+- Do not use marketing buzzwords (`seamless`, `robust`, `powerful`, `revolutionary`, `enhanced`, `allows`, `leverage`)
+- Do not use vague qualifiers (`simply`, `just`, `easily`, `quickly`, `very`, `really`)
+- Open a sentence with its subject and action, not filler (`Note that`, `Basically`), a hollow connective (`That being said`, `It's worth noting`), or a gerund windup (`Leveraging the API...`). Substantive transitions that carry a real relationship are fine.
+- Do not use the negative parallelism pattern (`It's not X, it's Y`, `not because X, but because Y`)
+- Do not pad verb phrases or delay the action. Write the shortest form (`in order to` → `to`, `ensure that X is set` → `set X`, `By doing X, you can Y` → state Y directly).
+- Do not address the reader as a participant (`Let's`, `Here's`, `Here are`). State the content directly.
+- Commit to a position. Do not hedge in clusters (`It might be worth considering`) or use false balance (`While X is true, Y is also important`). Recommend, or state the tradeoff.
+
+## Frontmatter descriptions
+
+When frontmatter carries a short `title` or `description` used for catalog display:
+
+- `title`: sentence case, identifies the file uniquely against its siblings in the same catalog. Proper nouns retain their casing. No trailing period.
+- `description`: sentence case, names the specific topics covered so a reader can decide whether to open the file. Lead with concrete subjects, strip filler like "guide to", "overview of", or "documentation about". No trailing period, no leading article (`the`, `a`).
+- Do not mechanically reuse the H1 as the description.
+
+## Examples
+
+Each pair shows a banned pattern and its fix.
+
+```markdown
+Bad: The configuration file serves as the central hub for all build settings.
+Good: Configuration lives in `vite.config.ts`.
+```
+
+```markdown
+Bad: In order to configure the server, you'll need to ensure that the port is set.
+Good: Set `port` in the server config.
+```
+
+```markdown
+Bad: It's not just a cache. It's a system for intelligent memory management.
+Good: The cache is an LRU store. It evicts the least-recently-used entry when full.
+```
+
+```markdown
+Bad: Leveraging the retry mechanism, developers can build more resilient integrations.
+Good: Use the `retry` option for failed webhooks. Set `maxRetries` to 3.
+```
+
+```markdown
+Bad: It might be worth considering whether to enable caching.
+Good: Enable caching for read-heavy endpoints. Skip it for writes.
+```
+
+```markdown
+Bad: See [.claude/context/retrieval.md](.claude/context/retrieval.md) for the retrieval flow.
+Good: See `.claude/context/retrieval.md` for the retrieval flow.
+```
+
+```markdown
+Bad: Read [docs/development.md](docs/development.md) before contributing.
+Good: Read the [development guide](docs/development.md) before contributing.
+```