sync-docs

docs/reference/mcp-server.md

@@ -5,13 +5,33 @@
 - Transport: MCP protocol over stdio via the official Python SDK; no network listeners; enforced local-only guard.
 - Source: `scripts/mcp-server/`; connect via the `nixos-mcp` wrapper package.
 
+## Sources of Truth
+- Constitution: `docs/constitution.md` is authoritative for AI rules and workflows.
+- Conflict handling: when human docs differ, update both and record the resolution in `specs/001-ai-docs/research.md`.
+- Reference map: `docs/reference/index.md` is the navigation index for paths and responsibilities.
+- Playbooks: `docs/playbooks/*.md` are the repeatable workflow guides; follow the template structure.
+- Planning artifacts: `specs/001-ai-docs/` captures decisions, plans, and change history.
+
 ## Tool Catalog
-- `show-constitution`: Display `docs/constitution.md` to confirm authoritative rules.
-- `list-playbooks`: List available playbooks under `docs/playbooks/` for common tasks.
-- `show-reference`: Show `docs/reference/index.md` to navigate repo guidance.
-- `search-docs`: Search the docs set for a query (param: `query`).
-- `list-mcp-tasks`: Show MCP feature task list from `specs/001-mcp-server/tasks.md`.
-- `sync-docs`: Compare tool catalog against documented anchors for drift reporting.
+### show-constitution
+- Purpose: Display `docs/constitution.md` to confirm authoritative rules.
+- Docs anchor: `docs/constitution.md` → `#ai-constitution-for-the-nixos-repository`.
+### list-playbooks
+- Purpose: List available playbooks under `docs/playbooks/` for common tasks.
+- Docs anchor: `docs/playbooks/template.md` → `#playbook-template`.
+### show-reference
+- Purpose: Show `docs/reference/index.md` to navigate repo guidance.
+- Docs anchor: `docs/reference/index.md` → `#reference-map`.
+### search-docs
+- Purpose: Search the docs set for a query.
+- Inputs: `query` (string).
+- Docs anchor: `docs/reference/mcp-server.md` → `#search-docs`.
+### list-mcp-tasks
+- Purpose: Show MCP feature task list from `specs/001-mcp-server/tasks.md`.
+- Docs anchor: `specs/001-mcp-server/tasks.md` → `#tasks-mcp-server-for-repo-maintenance`.
+### sync-docs
+- Purpose: Compare tool catalog against documented anchors for drift reporting.
+- Docs anchor: `docs/reference/mcp-server.md` → `#sync-docs`.
 
 ## Invocation
 - Start server: `nixos-mcp` (stdio mode).