Start with the repository README for components and installation, and AGENTS.md for authoritative contributor instructions.
| Guide | Use it for |
|---|---|
| DEVELOPMENT.md | Toolchains, build roots, offline checks, and safe verification |
| AGENT_INSTRUCTIONS.md | Shared instruction symlinks, private overrides, precedence, and migration |
| ARCHITECTURE.md | Component boundaries, execution paths, configuration, and trust |
| RELEASING.md | Release ownership, tags, packaging gates, and rollback evidence |
| API_LIMITATIONS.md | Upstream disk I/O counter limitations and affected client outputs |
| MCP_REGISTRY.md | Registry identities, publication order, and missing-entry recovery |
| Python docs | Python installation, auth, configuration, tools, and subscriptions |
| Rust README | Rust CLI/MCP usage, projection modes, and configuration |
| Incus guide | Classic packaging, API backend, Vue UI, and isolation gates |
| Native MCP plugin | Installing and operating the native Rust server on Unraid |
| Codex plugin | Chathead packaging and runtime integration |
The checker validates a regular AGENTS.md with relative CLAUDE.md and
GEMINI.md aliases at every repository instruction scope. The root guide owns
only repository-specific maps, commands, and contracts; nested guides add
component details. Cross-project workflow and instruction conventions belong
in the developer's global guide. Workstation facts belong in a global override,
and checkout facts in the ignored local pair described in
AGENT_INSTRUCTIONS.md. Neither private source belongs
on the repository's main branch or in a shared artifact.
Code, manifests, lockfiles, and executable tests establish current behavior. Avoid copying action counts or dependency versions into multiple pages; link to their source whenever possible. When changing a public interface, update the corresponding user guide and contract tests in the same change.
The Rust npm README is generated from unraid-rs/README.md; synchronize it with
node unraid-rs/packages/unraid-rmcp/scripts/sync-readme.js.
docs/sessions/ and component docs/sessions/ directories record what happened
in a particular session. Changelogs, unraid-py/docs/review/, and issue plans
are historical evidence, not promises about the current tree.
plugins/incus/docs/unraid/ is an imported upstream documentation snapshot,
not a live mirror. unraid-py/docs/unraid/ contains captured/generated schema
references; Rust's schema/ similarly contains a vendored contract and live
capture evidence. Regenerate only from an explicitly selected source or target;
do not rewrite old evidence during a general documentation cleanup.
The offline documentation checker excludes historical session/review records, changelogs, and imported/generated upstream documentation from link validation. It validates instruction triplets everywhere and local links in maintained Markdown. It does not verify external URLs, anchor text, or live API behavior.
To repair missing or incorrect aliases, run
python3 .github/scripts/check_documentation.py --repair-links (also available
as cargo xtask symlink-docs from unraid-rs/). The helper validates all scopes
first and refuses to overwrite any regular alias file or reverse an unreviewed
legacy layout. Preserve and reconcile independent content before repairing.
Python 3.10+ is required; the repository development toolchain provides 3.12.
python3 .github/scripts/check_documentation.py
python3 -m unittest discover -s .github/scripts/tests -p 'test_*.py'