stack/docs/scratchpads/DOCS-IA-001.md

DOCS-IA-001 — Documentation Information Architecture

• Task: DOCS-IA-001
• Internal reference: TASKS:DOCS-IA-001
• Objective: Codify the canonical docs/ structure and authoring rules in docs/README.md before moving or rewriting existing documentation.
• Scope: README contract only; no document migration in this slice.
• Approved design: docs/plans/2026-08-10-docs-information-architecture-design.md
• Implementation plan: docs/plans/2026-08-10-docs-structure-readme.md

Plan

1. Replace the starter docs/README.md with the approved target tree and placement policy.
2. Document source-of-truth, audience-book, artifact, migration, and Obsidian link rules.
3. Run focused formatting, whitespace, structure, link, and scope checks.
4. Commit only docs/README.md; preserve unrelated staged and untracked changes.

Progress

• Context inventory completed.
• Design approved by user.
• Design committed as 205cc0d.
• Implementation plan written.
• Scratchpad created.
• README updated.
• Focused verification completed.
• Scoped documentation commit created (docs: codify documentation structure).

Tests and verification

Check	Result
Markdown formatting	PASS — pnpm exec prettier --check docs/README.md docs/plans/2026-08-10-docs-structure-readme.md docs/scratchpads/DOCS-IA-001.md
Whitespace validation	PASS — git diff --no-index --check for all new Markdown files
Required structure anchors	PASS — root controls, books, artifact directories, Obsidian, and retired mosaic-stack boundary found
README-only scope check	PASS — the scoped documentation commit contains only this task's README, plan, and scratchpad; unrelated changes remain outside the commit

Risks and blockers

• Existing documentation remains under docs/_old_structure/; this slice does not migrate it.
• Existing source/tests reference legacy paths such as docs/fleet/ and docs/federation/; those references require a later migration slice.
• docs/TASKS.md has a single-writer orchestrator policy and is intentionally not modified here.
• docs/GETTING_STARTED.md is an unrelated pre-staged deletion and must remain outside this task commit.
• docs/.obsidian/ is pre-existing untracked vault metadata and must not be modified or committed here.

Final evidence

• docs/README.md now defines the complete target tree, placement matrix, source-of-truth policy, authoring workflow, migration policy, and Obsidian/Git link conventions.
• pnpm exec prettier --check docs/README.md docs/plans/2026-08-10-docs-structure-readme.md docs/scratchpads/DOCS-IA-001.md passed.
• git diff HEAD^ HEAD --check and the staged-index whitespace check passed.
• Focused structure and retired-boundary checks passed.
• All three relative Markdown links in the README resolve.
• The scoped documentation commit contains only the README, plan, and scratchpad.
• The pre-existing staged deletion of docs/GETTING_STARTED.md, modified .mosaic/orchestrator/* files, and untracked docs/.obsidian/ metadata remain outside the documentation commit.
• Content migration, sitemap refresh, and legacy source/test path updates remain explicitly deferred to later slices.