mosaicstack/stack
1
0
Fork 1
Code Issues 246 Pull Requests 7 Actions Packages Projects Releases 15 Wiki Activity

docs: establish canonical documentation architecture #1210

Merged
mos-dt-0 merged 47 commits from docs/ia-merge-current into next 2026-08-13 17:56:15 +00:00
Conversation 0 Commits 47 Files Changed 241
+410
3 changed files with 410 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 0830e2e3ae - Show all commits
docs/README.md
+221
View File
@@ -0,0 +1,221 @@
# 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.
Recommended front matter for canonical pages:
```yaml
---
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
This initial pass defines the target structure only. It does not move or rewrite the existing documentation set.
- Treat `_old_structure/` as read-only migration quarantine. Do not add new content there.
- Treat the current root-level legacy pages (`QUICKSTART.md`, `PERFORMANCE.md`, `SSO-PROVIDERS.md`, `openapi-tess.yaml`, and the task/mission documents) as migration backlog, not permission to create more root files.
- Candidate destinations include `USER-GUIDE/getting-started/`, `ADMIN-GUIDE/security/`, `DEVELOPER-GUIDE/architecture/`, `API/`, `tasks/`, `plans/`, and `archive/`; classify each page before moving it.
- Existing source code and tests still reference legacy paths such as `docs/fleet/` and `docs/federation/`. Update those references deliberately as part of the relevant migration slice; do not delete a referenced path blindly.
- 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
The structure is being established before content migration. During this transition:
- The target directories listed above are a blueprint; not all indexes or chapters exist yet.
- `docs/_old_structure/` remains available for reference but is not current documentation.
- Existing root documentation files remain until their migration destinations are reviewed.
- `docs/SITEMAP.md` still contains legacy paths and will be refreshed as pages are migrated.
- No external publishing platform is assumed. The canonical source remains this repository under `docs/`.
## Non-goals for this pass
- Do not move, delete, or rewrite the archived documentation.
- Do not rewrite the product PRD, active task rollup, API contract, or sitemap yet.
- Do not create a documentation website or publishing pipeline.
- Do not treat Obsidian metadata as product or project source of truth.
docs/plans/2026-08-10-docs-structure-readme.md
+135
View File
@@ -0,0 +1,135 @@
# Documentation Structure README Implementation Plan
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Replace the starter `docs/README.md` with the normative documentation structure, placement rules, source-of-truth policy, and Obsidian-compatible navigation conventions approved for Mosaic Stack.
**Architecture:** Keep `docs/README.md` as the root documentation atlas and authoring contract. Use audience books for current user, administrator, and developer content; keep API contracts and operational artifacts in dedicated directories; retain `_old_structure/` as a read-only migration quarantine. Do not move or rewrite existing documentation in this slice.
**Tech Stack:** Markdown, YAML front matter examples, Obsidian wikilinks, relative Markdown links, Prettier.
---
### Task 1: Write the documentation structure contract
**Files:**
- Modify: `docs/README.md`
- Reference: `docs/plans/2026-08-10-docs-information-architecture-design.md`
**Step 1: Confirm the approved design and current transition constraints**
Verify that the README preserves these decisions:
- `docs/mosaic-stack/` is not a target content directory.
- `docs/README.md` is the documentation atlas and placement contract.
- Existing files are not moved or rewritten yet.
- `_old_structure/` is read-only migration quarantine.
- Root control files, audience books, API, reports, tasks, plans, scratchpads, releases, archive, and assets have distinct responsibilities.
**Step 2: Replace the starter README**
Write `docs/README.md` with these sections:
1. Purpose and scope.
2. Reader entry points.
3. Complete target directory tree, including the optional `.obsidian/` vault configuration boundary and the workflow-only `plans/` directory.
4. Root control document responsibilities.
5. Guide book responsibilities and chapter rules.
6. Artifact directory responsibilities.
7. Placement matrix for agents.
8. Source-of-truth and precedence rules.
9. Page naming and front matter conventions.
10. Obsidian wikilink and Git-hosted Markdown link conventions.
11. Authoring workflow for new or changed documentation.
12. Migration rules for `_old_structure/`, legacy root files, and repository references.
13. Current transitional exceptions and explicit non-goals.
Use future target paths as a blueprint, but clearly label directories that are not populated yet so readers do not mistake the blueprint for completed migration.
**Step 3: Preserve the existing Obsidian configuration boundary**
Document `.obsidian/` as optional vault metadata only. Do not place Markdown content, scratchpads, reports, or source-of-truth files under it, and do not modify its existing files in this task.
**Step 4: Keep the README portable**
Use ordinary relative Markdown links for indexes and Git-hosted navigation. Use Obsidian wikilinks for graph-oriented relationships such as `Related`, `Depends on`, and `Referenced by`. Do not make a current navigation path depend solely on a Git-host-incompatible wikilink.
**Step 5: Review the resulting document**
Check that an agent can answer all of these without inspecting another file:
- Where does a user guide go?
- Where does an admin runbook go?
- Where does architecture or an RFC go?
- Where does an API contract go?
- Where does an active scratchpad go?
- Where does a review or QA report go?
- Where does an approved design or implementation plan go?
- Which files are normative, working notes, evidence, or historical?
- What may be added directly under `docs/`?
**Step 6: Commit only the README**
Because `docs/GETTING_STARTED.md` is an unrelated pre-staged deletion, stage and commit only `docs/README.md`:
```bash
git add docs/README.md
git commit --only docs/README.md -m "docs: codify documentation structure"
```
Expected: the commit contains only the README change; the existing staged deletion and orchestrator state remain outside the commit.
### Task 2: Verify the README-only change
**Files:**
- Verify: `docs/README.md`
**Step 1: Run Markdown formatting validation**
Run:
```bash
pnpm exec prettier --check docs/README.md
```
Expected: Prettier reports the file is formatted.
**Step 2: Run whitespace validation**
Run:
```bash
git diff --check HEAD^ -- docs/README.md
```
Expected: no whitespace errors.
**Step 3: Validate required structural anchors**
Run a focused search or script confirming the README names:
- `PRD.md`, `TASKS.md`, and `SITEMAP.md`;
- `USER-GUIDE/`, `ADMIN-GUIDE/`, `DEVELOPER-GUIDE/`, and `API/`;
- `reports/`, `tasks/`, `plans/`, `scratchpads/`, `releases/`, `archive/`, and `assets/`;
- `_old_structure/` as read-only quarantine;
- `docs/mosaic-stack/` as retired/non-authoring;
- Obsidian wikilinks and Git-compatible Markdown links.
Expected: all anchors are present and no section instructs agents to create content under `docs/mosaic-stack/`.
**Step 4: Confirm scope isolation**
Run:
```bash
git status --short
git show --stat --oneline HEAD
```
Expected: the new commit contains only `docs/README.md`; pre-existing `.mosaic/orchestrator/*`, `docs/GETTING_STARTED.md`, and `docs/.obsidian/` states remain untouched.
**Step 5: Record verification evidence**
Update the task scratchpad at `docs/scratchpads/DOCS-IA-001.md` with commands, results, known transitional gaps, and the next migration slice. Do not modify active `docs/TASKS.md`; its single-writer policy belongs to the orchestrator.
docs/scratchpads/DOCS-IA-001.md
+54
View File
@@ -0,0 +1,54 @@
# 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
- [x] Context inventory completed.
- [x] Design approved by user.
- [x] Design committed as `205cc0d`.
- [x] Implementation plan written.
- [x] Scratchpad created.
- [x] README updated.
- [x] Focused verification completed.
- [x] 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.