Documentation contract
Stable URLs, source priority, page conventions, and update requirements for humans and automated agents.
Noir documentation is part of the package contract. A code example must type-check against the published version, and a reference page must describe actual exported behavior rather than an intended future API.
Source priority
When sources disagree, use this order:
- installed TypeScript declarations and implementation for the exact package version
- version-matched reference pages
- version-matched guides and examples
- README summaries and third-party articles
Open an issue when a lower-priority source is stale; do not silently invent compatibility code.
Stable machine surfaces
/llms.txt is the discovery index. /llms-full.txt is the full corpus for offline search. Every page has a deterministic Markdown URL under /llms.mdx/docs/.../content.md. HTML canonical routes remain under /docs/....
The Markdown response begins with the page title and canonical HTML URL, followed by processed page content. This makes citations and follow-up navigation possible even when only raw text is available.
Writing conventions
Each page states a single responsibility, starts with the shortest correct path, then explains contracts, ownership, failure modes, and verification. Code blocks use stable public imports. Security requirements are attached to the operation they govern instead of hidden in one general warning page.
Change requirements
When an exported API changes:
- update the exact reference page
- update every affected guide and example
- update environment and migration guidance
- add or adjust structural docs tests
- verify all code blocks against the package build
- regenerate and test the Fumadocs source
- keep old names marked deprecated only when the package still exports them
The docs should help an agent produce less code, not more abstraction. Prefer the provider's native constructor and Noir's smallest composition boundary.