stack/docs/README.md

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, 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.
• Understand active delivery state: read 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.

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.

Recommended front matter for canonical pages:

---
title: Human-readable page title
type: guide
audience: developer
status: current
source_of_truth: false
---

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.

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.