---
kind: spec
status: active
---

# 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/<chapter>/`                                           | The docs root                               |
| Installation, deployment, or recovery procedure       | `docs/ADMIN-GUIDE/<chapter>/`                                          | `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/<task-id>-<slug>.md`                                 | The docs root or a canonical guide          |
| Review, QA, audit, security, or deferral evidence     | `docs/reports/<category>/`                                             | 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.
