Maintain the documentation

The documentation repository is the canonical user guide for one explicit stable source state.

Source synchronization

For every stable release:

1. identify the qualifying release and exact commit;
2. compare public code, tests, examples, and source docs;
3. update behavioral pages in the same pull request;
4. update docs-source.json;
5. set the real synchronization timestamp;
6. run the full documentation validation suite;
7. review the preview before merge.

Do not point docs-source.json at mutable main.

Verify the highest-risk pages

Always recheck:

• CLI reference against Typer registrations and help;
• MCP tools against schemas, registration, and dispatch;
• Python resolver API against public function signatures;
• Configuration against validation and actual call sites;
• Response envelope against Pydantic models;
• Parser and query coverage against parsers, importers, repositories, resolvers, and tests;
• Errors and current limitations against implemented and explicitly deferred surfaces;
• Project legal and redistribution against LICENSE, NOTICE, and distribution tests.

A README summary alone is not sufficient for exact reference updates.

Preserve the reader architecture

Keep the top-level hierarchy:

1. Getting started
2. Guides
3. Concepts
4. Reference
5. Contributing

Add a page only when it has a distinct user need. Do not mirror internal source directories into navigation.

Example rules

• Use commands that work from the documented installation context.
• Keep a network-free fixture path.
• Use <concrete-edition> for mutable official-release examples.
• Reserve 2026b for the synthetic fixture unless an official example is explicitly verified.
• Keep Bash blocks prompt-free.
• Include expected checkpoints and likely failure modes.
• Never include a full official standard excerpt or generated bulk data.

Reference-generation discipline

Generated reference can reduce drift only when the generation source and review process are explicit.

Until the source project publishes a stable generator:

• maintain reference tables manually from typed source contracts;
• review diffs for removed as well as added behavior;
• do not import runtime source code during the static site build;
• do not make the site depend on a local generated knowledge base.

Legal and authority language

Keep the project legal page and documentation licensing page separate.

Do not remove:

• non-affiliation language;
• DICOM trademark and copyright notice;
• code-license scope;
• generated-content restrictions;
• no-certification boundary.

Validation

From the documentation repository:

npm run format
npm run validate

Also check:

• internal links;
• frontmatter;
• code-fence languages;
• no shell prompts;
• no placeholders;
• no unexpected committed artifacts;
• static build output;
• Linux CI;
• Cloudflare preview.

A documentation-only change follows the same focused commit policy as source changes.