Documentation Rules
Markdown files in this repository are architectural source material, not optional notes.
For the full source document, see docs/DOCUMENTATION_RULES.md. This page exposes the rules in the public documentation route so contributors can find them from the sidebar.
Core rule
Documentation must be preserved and synchronized with implementation.
If code and Markdown disagree, treat it as architecture drift. Do not silently choose code just because it currently compiles, and do not silently choose stale documentation just because it sounds like the intended design.
Required behavior
Before non-trivial changes, identify the Markdown files that govern the task and the constraints they impose.
This matters for changes touching:
- parser behavior;
- runtime composition;
- modules;
- capabilities;
- function calls;
- CLI behavior;
- CI behavior;
- public API;
- documentation smoke checks.
Forbidden fixes
Do not fix CI or tests by:
- deleting architectural documentation;
- replacing substantial documents with placeholders;
- adding path-based Markdown exclusions to smoke checks;
- weakening documentation checks instead of fixing stale examples;
- restoring removed runtime functionality only because old documentation references it;
- implementing behavior that contradicts current architecture docs without explicitly resolving the conflict.
Executable examples
When a Markdown bash block is stale, choose the narrowest honest fix:
- If the command describes supported behavior, update the command.
- If the command is future or historical, convert the fence to
textand say it is not executable in the current state. - If the surrounding document is obsolete, rewrite only the obsolete section.
The Markdown bash smoke runner executes tracked Markdown bash fences unless the block is explicitly marked with supported CI attributes.
Current versus future docs
Current-state documents describe what the repository supports now.
Future or historical documents may describe planned or removed behavior, but they must not contain executable bash blocks for commands that do not exist in the current branch.
Use docs/proposals/ for future designs and docs/archive/ for historical context. Do not treat either location as current runtime truth unless a current-state document and tests explicitly promote the behavior.
Documentation authority and fitness
Substantial architecture, rules, proposal, release, review, or archive documents must state whether they are current truth, a proposal, archive context, a dated review, or a public guide.
Architecture rules should be paired with a practical fitness check before they are treated as enforced release gates.
Practical validation
For documentation changes that affect public examples, run:
npm run docs:status
python3 .github/scripts/run-markdown-bash-blocks.py
npm run docs:buildFor code or behavior changes, also run the relevant .NET build and test commands from Installation.