docs(ai): define documentation truth hierarchy

docs/README.md

@@ -0,0 +1,67 @@
+# CCS Maintainer Documentation
+
+This directory explains how the CLI repository is organized and maintained.
+User-facing guides and command reference live at
+[docs.ccs.kaitran.ca](https://docs.ccs.kaitran.ca).
+
+## Truth Hierarchy
+
+Use the narrowest authoritative source:
+
+1. Source, tests, package scripts, and workflows define implemented behavior.
+2. [`CLAUDE.md`](../CLAUDE.md) and
+   [`CONTRIBUTING.md`](../CONTRIBUTING.md) define repository workflow.
+3. The documents below explain architecture, rationale, and maintainer
+   decisions.
+4. Build artifacts, releases, and runtime checks define shipped or observed
+   state.
+
+When sources disagree, verify the implementation first and update or remove the
+stale prose. Avoid copying volatile counts, recursive trees, and exhaustive
+option lists when a source link can remain accurate.
+
+## Start Here
+
+| Need | Owner |
+| --- | --- |
+| Repository domains and source entry points | [Codebase summary](./codebase-summary.md) |
+| Coding, testing, error, and size conventions | [Code standards](./code-standards.md) |
+| System boundaries and data flow | [System architecture](./system-architecture/index.md) |
+| Current maintenance direction | [Project roadmap](./project-roadmap.md) |
+| Release mechanics | [Release process](./release-process.md) |
+| Dashboard localization | [Dashboard i18n](./i18n-dashboard.md) |
+| Test layout and commands | [Test suite](../tests/README.md) |
+| Dashboard development | [UI guide](../ui/README.md) |
+
+Feature-specific maintainer notes remain in this directory. Discover them by
+filename, then verify referenced behavior against the linked source.
+
+## Update Triggers
+
+Update the owning documentation in the same change when any of these move:
+
+- CLI or dashboard behavior, commands, flags, or configuration
+- installation, deployment, release, or contributor workflow
+- architecture, data flow, persistence, security, or public contracts
+- source ownership or the stable entry point named by a guide
+
+Pure refactors need documentation changes only when they invalidate a
+maintainer decision or navigation link. Public behavior changes also require a
+matching update in the separate `kaitranntt/ccs-docs` repository on the same
+target branch. Maintainers using the standard CloudPersonal checkout may have
+that repository at `/Users/kaitran/CloudPersonal/ccs/docs`; fork contributors
+can use their own checkout and coordinate the matching docs change in the PR.
+
+## Validation
+
+Before review:
+
+```bash
+bash tests/docs/quickstart-parity.sh
+git diff --check
+```
+
+The repository-owned docs test currently checks the canonical quickstart
+snippet only. For other changed Markdown, verify each relative link and
+referenced path directly, then run the focused validation command for any code
+or workflow the document describes.