Symbolic README References

HTML comments in markdown files act as declarative queries over the codebase — they describe what the surrounding content should reflect. Example:

## API

<!-- exported functions and their signatures from src/index.ts -->

| Function | Description |
| --- | --- |
| `createMachine(config)` | Creates a state machine |

## Installation

<!-- install command matching package.json#name -->

`npm install xstate`

A comment is a symbolic reference if it describes content derivable from source — references to files/modules, package metadata, code constructs, or consistency constraints (consistent with, matching, derived from). Purely editorial comments (<!-- TODO: rewrite -->) are not symbolic references.

References can be path-qualified (exported functions from src/index.ts) or logical (all exported creator functions, public API of the state module, supported config options). Resolve logical references by searching the codebase for constructs that match the description — don't require a filename.

When you change the repo

1. Scan all non-gitignored markdown files for symbolic comments: rg -l '<!--' --glob '*.md' .
2. Check relevance — does your change affect the content each comment describes? For logical references, resolve them against the codebase first, then check if the changed file/symbol falls in that set.
3. Regenerate affected sections: read the referenced source, extract the described construct, format to match existing style, replace only the content below the comment. Preserve the comment itself.
4. Preserve surrounding prose and sections without comments.
5. Backfill comments on unannotated READMEs — if a README has no symbolic comments but contains sections that clearly describe the code you just changed (API tables, install commands, config lists, CLI usage), infer the symbolic reference and insert a comment above that section before regenerating. Only backfill sections actually affected by the current change; don't rewrite the whole README. If the inferred reference is ambiguous, flag it instead of guessing.

If a comment references something that no longer exists, flag it to the user rather than silently removing the section.

When you author a README

Add a symbolic comment above any section that reflects the repo (code, structure, or metadata). Good comments are specific (<!-- exported functions from src/index.ts --> or <!-- all exported creator functions --> — not <!-- API docs -->), scoped to one concept, and reference logical constructs rather than line numbers. Prefer logical descriptions when the set spans multiple files or may move.

Scope

Apply to all non-gitignored markdown files in the project tree — README.md, packages/*/README.md, src/**/README.md, docs/**/*.md, CONTRIBUTING.md, etc.