# Documentation Information Architecture Design **Status:** Approved **Date:** 2026-08-10 **Scope:** Establish the canonical structure and authoring rules for `docs/` before migrating or rewriting existing documentation. ## Goal Create a clean, human-readable, Obsidian-compatible documentation system for Mosaic Stack. The system must make the relationships between requirements, architecture, guides, API contracts, operational procedures, evidence, and work tracking visible without duplicating canonical content. ## Decision Use a single root-level documentation atlas in `docs/README.md`, organized around audience-specific guide books and dedicated artifact directories. Retire `docs/mosaic-stack/` as a content boundary; it adds no useful ownership distinction once the documentation system has explicit root guides and cross-links. The target structure is: ```text docs/ ├── README.md ├── PRD.md ├── TASKS.md ├── SITEMAP.md │ ├── USER-GUIDE/ │ ├── README.md │ ├── getting-started/ │ ├── concepts/ │ ├── workflows/ │ └── troubleshooting/ │ ├── ADMIN-GUIDE/ │ ├── README.md │ ├── installation/ │ ├── configuration/ │ ├── deployment/ │ ├── operations/ │ ├── security/ │ └── recovery/ │ ├── DEVELOPER-GUIDE/ │ ├── README.md │ ├── architecture/ │ │ ├── README.md │ │ ├── system-overview.md │ │ ├── component-map.md │ │ ├── data-flow.md │ │ ├── security-model.md │ │ ├── decisions/ │ │ └── rfcs/ │ ├── packages/ │ ├── local-development/ │ ├── testing/ │ ├── contributing/ │ └── integrations/ │ ├── API/ │ ├── README.md │ ├── OPENAPI.yaml │ └── ENDPOINTS.md │ ├── assets/ ├── reports/ │ ├── code-review/ │ ├── documentation/ │ ├── qa/ │ ├── security/ │ └── deferred/ ├── tasks/ ├── plans/ ├── scratchpads/ ├── releases/ ├── archive/ └── _old_structure/ # temporary migration quarantine; read-only ``` `docs/plans/` is a workflow directory for approved design and implementation plans. It is not a substitute for the canonical requirements document, active task ledger, or guide books. ## Information architecture ### Root control documents - `docs/README.md` is the documentation contract, placement guide, and top-level entry point. - `docs/PRD.md` is the canonical product and requirements source. Requirements must not be silently redefined in guides or reports. - `docs/TASKS.md` is the active orchestrator rollup. Its single-writer policy remains authoritative. - `docs/SITEMAP.md` is the complete human navigation index. It must be updated when canonical pages are added, moved, renamed, or retired. ### Audience books - `USER-GUIDE/` contains end-user workflows, user-visible behavior, concepts needed to operate the product, and user troubleshooting. - `ADMIN-GUIDE/` contains installation, configuration, deployment, operations, security controls, recovery, and incident procedures. - `DEVELOPER-GUIDE/` contains architecture, package/component documentation, local development, testing, contribution rules, and integration authoring. - `API/` contains the machine-readable OpenAPI contract and its human-readable endpoint index. Audience books are task-oriented. They link to canonical architecture, requirements, API, and operational pages rather than copying those pages. ### Artifact directories - `assets/` contains diagrams and documentation media referenced by canonical pages. - `reports/` contains evidence and findings. Reports are informative and do not override the PRD or normative contracts. - `tasks/` contains archived task snapshots and orchestrator learnings. Active orchestration remains in root `TASKS.md`. - `plans/` contains approved design and implementation plans. - `scratchpads/` contains active, task-specific working notes and verification evidence. Scratchpads are not product documentation. - `releases/` contains release notes and release-specific migration or compatibility notes. - `archive/` contains superseded but intentionally retained documentation. Archived pages must state their replacement or reason for retention. - `_old_structure/` is a temporary migration quarantine. It is read-only, is not indexed as current documentation, and is not an authoring destination. ## Placement rules | Content | Required location | Do not place it in | | ----------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------- | | Product requirements and acceptance criteria | `docs/PRD.md` or an explicitly scoped PRD under a guide/workstream | A scratchpad, report, or README-only note | | Active task status | `docs/TASKS.md` | A guide page or personal scratchpad | | User workflow | `docs/USER-GUIDE//` | The docs root | | Installation, deployment, or recovery procedure | `docs/ADMIN-GUIDE//` | `README.md` or a report | | Architecture, component, package, ADR, or RFC content | `docs/DEVELOPER-GUIDE/architecture/` or its relevant developer chapter | `docs/mosaic-stack/` or the docs root | | API contract | `docs/API/OPENAPI.yaml` and `docs/API/ENDPOINTS.md` | A guide-only description | | Documentation navigation | `docs/SITEMAP.md` | A duplicated ad-hoc index | | Design or implementation plan | `docs/plans/` | `docs/scratchpads/` | | Active task working notes | `docs/scratchpads/-.md` | The docs root or a canonical guide | | Review, QA, audit, security, or deferral evidence | `docs/reports//` | A canonical guide page | | Archived task snapshot | `docs/tasks/` | Root `TASKS.md` unless it is active | | Release notes | `docs/releases/` | The docs root | | Diagram or image | `docs/assets/` or an owning chapter asset directory | An external personal path | | Superseded documentation | `docs/archive/` | `_old_structure/` after migration completes | When a page appears to fit multiple locations, classify it by its primary reader and purpose, then link it from the other relevant indexes. Do not create copies to satisfy multiple audiences. ## Page conventions Every canonical Markdown page should: 1. Cover one concern or workflow. 2. Use a descriptive, lowercase kebab-case filename, except for established root control files and required API filenames. 3. Begin with a clear title and a short purpose statement. 4. Declare status and audience when the page is more than a simple index. 5. Identify prerequisites, source-of-truth dependencies, and related pages. 6. State whether examples and commands are current, illustrative, or held/non-operative. 7. Include an owner or maintenance responsibility when the content is operationally sensitive. Recommended front matter for canonical pages: ```yaml --- title: Human-readable page title type: guide audience: developer status: current --- ``` Allowed `type` values include `guide`, `concept`, `reference`, `decision`, `rfc`, and `runbook`. Allowed `audience` values are `user`, `admin`, `developer`, and `all`. Allowed `status` values are `current`, `draft`, `deprecated`, and `historical`. ## Obsidian and link conventions - Use Obsidian wikilinks for relationship-oriented internal references, for example `[[DEVELOPER-GUIDE/architecture/component-map|Component map]]`. - Use normal relative Markdown links in `SITEMAP.md` and book `README.md` indexes so links render on Git hosting platforms. Obsidian can resolve these links too. - Use `Related`, `Depends on`, and `Referenced by` sections when a page participates in a meaningful documentation relationship. - Link to stable page paths, not transient line numbers or branch URLs. - Omit `.md` in wikilinks. Include an alias when the file path is not a readable label. - Use standard Markdown links for external URLs, source files, commands, and API paths. - Do not rely on a link to `_old_structure/` as a current navigation path. Historical references must explain why the archived page is retained and point to its replacement. ## Migration rules This design phase does not move or rewrite content. During later migration: 1. Inventory current pages and classify each by audience, purpose, status, and source-of-truth role. 2. Move canonical content into the target tree without changing meaning unless the migration task explicitly includes a rewrite. 3. Update all repository links, source comments, tests, and `SITEMAP.md` in the same logical change. 4. Preserve historical evidence in `reports/`, `tasks/`, `releases/`, or `archive/` rather than mixing it into current guides. 5. Treat `_old_structure/` as read-only during migration. It may be removed only after all required links and source references are resolved. 6. Do not add new content to `docs/mosaic-stack/`; the empty directory is retired by this design. 7. For documents referenced by executable tests or source code, update those references deliberately and verify them before deleting the old path. ## Acceptance criteria - `docs/README.md` defines the complete target tree and placement rules. - The target tree has no `docs/mosaic-stack/` content boundary. - Agents can determine where to put product docs, plans, task notes, reports, scratchpads, releases, and archives without guessing. - The rules support both Obsidian graph navigation and Git-hosted Markdown navigation. - The design distinguishes normative sources from evidence and working notes. - Migration can proceed incrementally without treating `_old_structure/` as current documentation.