---
kind: spec
source_of_truth: true
status: active
---

# Mosaic Stack Documentation

This directory is the canonical home for Mosaic Stack product, architecture, API, operations, and delivery documentation.

This file is the **documentation contract**. It defines where information belongs, which files are authoritative, how pages connect, and how agents must maintain the documentation set. The structure below is the target structure for the documentation migration; existing content is not considered migrated until it has been classified and moved deliberately.

## Start here

Choose the path that matches your purpose:

- **Understand the product:** start with [`PRD.md`](PRD.md), then use the user guide and the architecture overview.
- **Use Mosaic Stack:** use `USER-GUIDE/`.
- **Install, configure, deploy, or recover Mosaic Stack:** use `ADMIN-GUIDE/`.
- **Change or extend the codebase:** use `DEVELOPER-GUIDE/`.
- **Integrate with the gateway:** use `API/`.
- **Find a page or follow the documentation graph:** use [`SITEMAP.md`](SITEMAP.md).
- **Understand active delivery state:** read [`TASKS.md`](TASKS.md), subject to its single-writer policy.

The root README is an atlas and authoring guide, not a replacement for the user, administrator, developer, or API books.

## Canonical directory structure

The following is the complete target structure. Directories and pages may be created incrementally, but new documentation must use these locations.

```text
docs/
├── README.md                         # this documentation contract and atlas
├── PRD.md                            # canonical requirements source
├── TASKS.md                          # active orchestrator task rollup
├── SITEMAP.md                        # complete navigation index
├── .obsidian/                        # optional Obsidian vault metadata only
│
├── USER-GUIDE/                       # end-user documentation
│   ├── README.md                     # user-book index
│   ├── getting-started/              # first install/use and quickstarts
│   ├── concepts/                     # user-facing concepts and terminology
│   ├── workflows/                    # task-oriented user procedures
│   └── troubleshooting/              # user-visible failures and fixes
│
├── ADMIN-GUIDE/                      # operator and administrator documentation
│   ├── README.md                     # admin-book index
│   ├── installation/                 # installation and prerequisites
│   ├── configuration/                # configuration and environment
│   ├── deployment/                   # deployment topologies and rollout
│   ├── operations/                   # routine operation and observability
│   ├── security/                     # auth, RBAC, secrets, and security controls
│   └── recovery/                     # incident response, backup, and recovery
│
├── DEVELOPER-GUIDE/                  # contributor and maintainer documentation
│   ├── README.md                     # developer-book index
│   ├── architecture/                # system model and technical design
│   │   ├── README.md                 # architecture index
│   │   ├── system-overview.md        # platform boundary and major flows
│   │   ├── component-map.md          # apps, packages, plugins, and dependencies
│   │   ├── data-flow.md              # data, event, and control-plane movement
│   │   ├── security-model.md         # trust boundaries and authority model
│   │   ├── decisions/                # ADRs and approved design decisions
│   │   └── rfcs/                     # proposals and protocol RFCs
│   ├── packages/                     # package- and application-level guides
│   ├── local-development/            # local setup and safe development routes
│   ├── testing/                      # test strategy and verification workflow
│   ├── contributing/                 # contribution and review workflow
│   └── integrations/                 # plugin, provider, and adapter authoring
│
├── API/                              # machine- and human-readable API contract
│   ├── README.md                     # API documentation index
│   ├── OPENAPI.yaml                  # canonical OpenAPI contract
│   └── ENDPOINTS.md                  # endpoint, auth, permission, and error index
│
├── assets/                           # diagrams and documentation media
├── reports/                          # evidence and findings; never normative by itself
│   ├── code-review/                  # review reports
│   ├── documentation/                # documentation audits and checklists
│   ├── qa/                           # QA and verification reports
│   ├── security/                     # security reviews and threat evidence
│   └── deferred/                     # unresolved or explicitly deferred findings
├── tasks/                            # archived task snapshots and learnings
├── plans/                            # approved design and implementation plans
├── scratchpads/                      # active task-specific working notes
├── releases/                         # release notes and compatibility notes
├── archive/                          # superseded but intentionally retained docs
└── _old_structure/                   # temporary read-only migration quarantine
```

### Directory rules

- `.obsidian/` is optional tool metadata. It is not a content directory. Do not put Markdown pages, reports, plans, task notes, or source-of-truth files there.
- `USER-GUIDE/`, `ADMIN-GUIDE/`, and `DEVELOPER-GUIDE/` are books. Each book must have a `README.md` that links to every chapter and page in that book.
- Each chapter is a directory for one topic area. Each page should cover one concern or workflow.
- `API/OPENAPI.yaml` is the API contract. `API/ENDPOINTS.md` explains details that OpenAPI cannot fully express.
- `reports/`, `tasks/`, `plans/`, `scratchpads/`, `releases/`, and `archive/` are artifact boundaries, not alternative guide books.
- `_old_structure/` is temporary migration quarantine. It is read-only, is not current documentation, and is never a destination for new work.
- `docs/mosaic-stack/` is retired as a content boundary. Do not create new files there. Cross-cutting architecture belongs in `DEVELOPER-GUIDE/architecture/` and navigation belongs here and in `SITEMAP.md`.
- Do not add miscellaneous Markdown files directly under `docs/`. The permitted root files are `README.md`, `PRD.md`, `TASKS.md`, and `SITEMAP.md`; all other content belongs in a scoped directory.

## Where agents must place documents

Classify a document by its primary reader and purpose before creating it. Use this matrix instead of guessing from an existing filename.

| Content                                                                    | Required location                                                      | Examples                                                  |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------- |
| Documentation contract and top-level map                                   | `docs/README.md`                                                       | Folder rules, source-of-truth policy, authoring workflow  |
| Product requirements and acceptance criteria                               | `docs/PRD.md` or an explicitly scoped workstream PRD                   | Objectives, scope, requirements, acceptance criteria      |
| Active orchestrator task state                                             | `docs/TASKS.md`                                                        | Milestone/task rollup; single writer is the orchestrator  |
| Documentation navigation                                                   | `docs/SITEMAP.md` and the relevant book `README.md`                    | Page indexes and reader paths                             |
| User-visible workflow or troubleshooting                                   | `docs/USER-GUIDE/<chapter>/`                                           | Chat, projects, task workflows, user setup                |
| Installation, configuration, deployment, operations, security, or recovery | `docs/ADMIN-GUIDE/<chapter>/`                                          | SSO, tiers, secrets, health checks, incident runbooks     |
| Architecture, component map, data flow, package design, ADR, or RFC        | `docs/DEVELOPER-GUIDE/architecture/` or its relevant developer chapter | System design, protocol decisions, package contracts      |
| Local development, testing, contribution, or integration authoring         | `docs/DEVELOPER-GUIDE/<chapter>/`                                      | Setup, test commands, plugin development                  |
| HTTP/WebSocket API contract                                                | `docs/API/OPENAPI.yaml` and `docs/API/ENDPOINTS.md`                    | Paths, schemas, auth, permissions, errors                 |
| Diagram, screenshot, or other documentation media                          | `docs/assets/` or an owning chapter's asset directory                  | Architecture diagrams, workflow images                    |
| Approved design or implementation plan                                     | `docs/plans/`                                                          | Design docs and task-by-task execution plans              |
| Active task working notes and verification log                             | `docs/scratchpads/<task-id>-<slug>.md`                                 | Assumptions, progress, commands, evidence, blockers       |
| Code review, QA, audit, security, or deferral evidence                     | `docs/reports/<category>/`                                             | Review findings, test reports, security evidence          |
| Archived task snapshot or orchestrator learning                            | `docs/tasks/`                                                          | Closed task breakdowns and retained learnings             |
| Release notes or version-specific compatibility information                | `docs/releases/`                                                       | Release summaries, upgrade notes, deprecations            |
| Superseded documentation that must remain discoverable                     | `docs/archive/`                                                        | Historical guides, retired proposals, old mission records |

If content seems to fit multiple locations, choose one canonical home and link to it from the other relevant indexes. Do not create copies merely to satisfy multiple audiences.

## Source-of-truth and precedence

Use these rules when documents disagree:

1. **Requirements:** `PRD.md` is the project requirements source. A scoped PRD may add detail, but must link to and remain consistent with the root PRD.
2. **Active work state:** `TASKS.md` is the active orchestrator rollup. Workers read it; they do not rewrite its status or schema unless the orchestrator authorizes that change.
3. **API:** `API/OPENAPI.yaml` is the machine-readable API contract. `ENDPOINTS.md` is the human index and may explain constraints not represented by OpenAPI.
4. **Current behavior:** guide pages describe verified current behavior. If implementation changes, update the affected guide in the same logical change set.
5. **Architecture and decisions:** approved decisions under `DEVELOPER-GUIDE/architecture/decisions/` and RFCs explain why the system has its current shape. They do not silently override the PRD or API contract.
6. **Evidence:** reports record what was reviewed, tested, or deferred. They are evidence, not a substitute for current requirements or operational instructions.
7. **Plans:** plans describe intended work. After delivery, update the canonical guide, contract, or decision page rather than treating the plan as the current behavior.
8. **Scratchpads:** scratchpads are working memory and verification records. They are not product documentation and must not become hidden requirements.
9. **Archive:** archived pages are historical. Every retained page should identify its status and replacement, if one exists.
10. **Code is authoritative for executable behavior:** documentation must not claim commands, paths, APIs, or safety properties that the current code and tests do not support. When the desired behavior differs from current behavior, record the desired behavior in the PRD or an approved design and label operational procedures as held/non-operative when necessary.

## Page conventions

Every canonical page should:

1. Use a descriptive lowercase kebab-case filename, except for established root control files and required API filenames.
2. Cover one concern, concept, decision, or workflow.
3. Start with a clear title and a short purpose statement.
4. Identify its audience and lifecycle status when it is more than a simple index.
5. State prerequisites, dependencies, and source-of-truth references.
6. Mark examples and commands as current, illustrative, held, or non-operative when that distinction matters.
7. Include an owner or maintenance responsibility for operationally sensitive content.
8. Link to the relevant book index and related canonical pages.

Required front matter for every canonical page:

```yaml
---
kind: tracking | projection | spec | guide | record | superseded
status: active # or: completed | superseded-by: <path>
source_of_truth: false # optional, defaults false
audience: developer # optional: user | admin | developer | all
title: Human-readable page title # optional
---
```

`kind` says what the document **is**. One value, required, and it follows the document's content,
never its filename: a file named `TASKS.md` whose body says "this is a build plan, not a task
tracker" is a `spec`.

| kind       | rule                                                             |
| ---------- | ---------------------------------------------------------------- |
| tracking   | Live state, single-writer. Never a spec                          |
| projection | Generated. Never hand-edited. MUST have a drift test             |
| spec       | How to build one goal or workstream                              |
| guide      | Explains use. Decides nothing                                    |
| record     | What happened. Never authoritative, never updated after the fact |
| superseded | Kept for history, and NAMES its replacement                      |

`source_of_truth` is a separate boolean because authority is **orthogonal to kind**. A document can
be a `spec` and still be the thing everything else answers to;
`docs/requirements/native-kanban-sot.md` is exactly that. Folding authority into `kind` forced one
field to carry two independent facts, which is why an earlier draft of this contract could not
classify that file at all.

`status` has three values. `active` means in force. `completed` means the work the document
describes landed and the document is now finished rather than stale; executed implementation plans
take this. `superseded-by: <path>` replaces `status` entirely and names the replacement.

**This contract covers `.md` files only.** It is not an omission: a YAML document cannot carry YAML
front matter. The repository's own `yaml@2.8.3` throws `Source contains multiple documents` on a
front-mattered `.yaml`, and `parseNorthStar` (`packages/mosaic/src/commands/fleet.ts:242`) is a live
consumer that would break. `.yaml` sources declare their own kind inside the document or not at all.

A `parent` field is planned and is deliberately not yet required; it lands once the docs flatten
settles the paths it would point at.

Indexes may omit front matter when their purpose is self-evident. A page with normative authority
must explicitly identify the authority it owns and the boundaries of that authority.

## Obsidian and link conventions

Mosaic Stack documentation is compatible with Obsidian without making Git-hosted navigation unusable.

- Use Obsidian wikilinks for graph-oriented internal relationships, 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 Gitea/GitHub and other Markdown hosts. Obsidian resolves these links too.
- Use `Related`, `Depends on`, and `Referenced by` sections when a page has meaningful relationships to other pages.
- Use wikilink heading targets when a specific section matters, for example `[[DEVELOPER-GUIDE/architecture/system-overview#Gateway boundary|Gateway boundary]]`.
- Omit `.md` in wikilinks. Use an alias when the path is not a readable label.
- Use standard Markdown links for external URLs, source files, commands, and API paths.
- Link to stable repository-relative paths, not temporary branches, line numbers, or machine-local paths.
- Every current canonical page must be reachable from a book index or `SITEMAP.md`; do not create orphan pages.
- Do not use `_old_structure/` links as current navigation. Historical references must explain why the page is retained and point to its replacement.

## Authoring workflow for agents

For every documentation change:

1. **Search first.** Look for an existing page, requirement, report, task, or scratchpad before creating a new file.
2. **Classify.** Choose the primary audience, content type, lifecycle status, and source-of-truth role.
3. **Choose the canonical home.** Apply the placement matrix; do not place content in the docs root or `docs/mosaic-stack/`.
4. **Write one concern.** Keep the page focused and link to existing pages instead of copying them.
5. **Connect the page.** Add it to the owning book index and `SITEMAP.md`; add `Related`, `Depends on`, or `Referenced by` links where useful.
6. **Record non-trivial work.** Create or update `docs/scratchpads/<task-id>-<slug>.md` with objective, assumptions, progress, commands, risks, and evidence. Active `docs/TASKS.md` changes remain under its single-writer policy.
7. **Verify claims.** Check commands, paths, API schemas, permissions, and status against source and tests. Label held or non-operative procedures explicitly.
8. **Format and review.** Run the repository's Markdown formatting check, inspect links and headings, and review the diff for stale paths or duplicated authority.
9. **Commit a coherent change.** Keep documentation changes with the related code/API/operation change when applicable, and do not include unrelated staged files.

## Migration policy

The initial structure pass defined the target structure without moving or rewriting the existing documentation set. Subsequent migration slices may move or rewrite classified pages deliberately, with repository references and indexes updated together.

- Treat `_old_structure/` as read-only migration quarantine. Do not add new content there.
- Treat the current root-level legacy pages (`openapi-tess.yaml` and the task/mission documents) as migration backlog, not permission to create more root files. The former empty `QUICKSTART.md` placeholder now lives as `USER-GUIDE/getting-started/quickstart.md`; the verified SSO runbook lives under `ADMIN-GUIDE/security/`; historical evidence such as the P8-003 performance report belongs under `reports/qa/`.
- Candidate destinations include `USER-GUIDE/getting-started/`, `ADMIN-GUIDE/security/`, `DEVELOPER-GUIDE/architecture/`, `API/`, `tasks/`, `plans/`, and `archive/`; classify each page before moving it.
- `docs/fleet/` is an executable documentation contract consumed by current source and tests; keep that complete book at its canonical path. Federation and other authority surfaces may also have live consumers. Update any such path only through an explicitly coordinated source/test and authority migration.
- When a page is moved, update all repository links, source comments, tests, book indexes, and `SITEMAP.md` in the same logical change.
- Preserve historical evidence in `reports/`, `tasks/`, `releases/`, or `archive/` instead of mixing it into current guides.
- Remove the empty `docs/mosaic-stack/` boundary only after confirming no source, test, or documentation reference requires it.
- Remove `_old_structure/` only after migration verification proves that current navigation and required historical retention are intact.

## Current transition state

Classified migration is active and the audience books now contain verified current pages. During this transition:

- The target directories listed above remain the placement contract; some planned chapters are not populated yet.
- `docs/_old_structure/` remains available for migration evidence but is not current documentation or command authority.
- `docs/fleet/`, `docs/native-kanban-sot/`, `docs/requirements/native-kanban-sot.md`, and the KBN-101 hold-site documents remain at their canonical paths because they are active executable or authority surfaces. Their placement cannot change through documentation-only cleanup.
- Root control and API artifacts remain until their authority and destination decisions are approved.
- `docs/SITEMAP.md` contains only resolvable current navigation plus a non-linked summary of authority-gated migration groups.
- No external publishing platform is assumed. The canonical source remains this repository under `docs/`.

## Current migration boundaries

- Do not bulk-promote or bulk-rewrite quarantined documentation; classify and verify each coherent slice.
- Do not rewrite product requirements, orchestrator-owned task state, mission status, or the API contract without the required authority decision.
- Do not create a documentation website or publishing pipeline as part of content migration.
- Do not treat Obsidian metadata as product or project source of truth.
