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

docs: scaffold guide and API indexes

Browse Source
This commit is contained in:
Jason Woltje
2026-08-10 16:06:42 -05:00
parent 48531755eb
commit d210c2d7ea
7 changed files with 220 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ADMIN-GUIDE/README.md
+45
View File
@@ -0,0 +1,45 @@
# Administrator Guide
> **Status:** Scaffold only. No legacy page has been promoted into this book yet.
This book is the canonical home for installation, configuration, deployment, routine operations, security controls, incident response, and recovery. User workflows belong in [`USER-GUIDE/`](../USER-GUIDE/); implementation and contributor material belongs in [`DEVELOPER-GUIDE/`](../DEVELOPER-GUIDE/).
## Start here
- [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
- [Documentation sitemap](../SITEMAP.md) — existing navigation is transitional and still contains legacy paths.
- [Product requirements](../PRD.md) — normative requirements, currently marked draft.
## Chapter map
| Chapter | Scope | Status |
| --------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------- |
| `installation/` | Prerequisites, installation, and first deployment. | Scaffold only. |
| `configuration/` | Environment, provider, tier, and runtime configuration. | Scaffold only. |
| `deployment/` | Topologies, rollout, migration, and upgrade procedures. | Scaffold only. |
| `operations/` | Health, observability, routine operation, and maintenance. | Scaffold only. |
| [`security/`](security/README.md) | Authentication, authorization, SSO, secrets, and security controls. | Scaffold only; `SSO-PROVIDERS.md` is a migration candidate. |
| `recovery/` | Incident response, backup, rollback, and recovery. | Scaffold only. |
Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.
## Migration backlog — not current operator guidance
These are source candidates, not verified runbooks:
- [`SSO-PROVIDERS.md`](../SSO-PROVIDERS.md) — partially verified; its documented web feature flags conflict with current dynamic provider discovery.
- [`PERFORMANCE.md`](../PERFORMANCE.md) — historical performance evidence, not an operational SLO or runbook.
- [`_old_structure/guides/admin-guide.md`](../_old_structure/guides/admin-guide.md) — historical source; verify claims before promotion.
- [`_old_structure/guides/deployment.md`](../_old_structure/guides/deployment.md) — historical source; verify commands and deployment assumptions before promotion.
Do not treat a migration candidate as current until its commands, paths, permissions, and safety status are checked against source and tests.
## Authoring boundary
New administrator documentation belongs under one of the chapter directories above. Operationally sensitive pages must identify prerequisites, ownership, source-of-truth dependencies, and whether any procedure is current, illustrative, held, or non-operative.
## Related
- [[README|Documentation contract]]
- [[PRD|Product requirements]]
- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]
docs/ADMIN-GUIDE/security/README.md
+19
View File
@@ -0,0 +1,19 @@
# Security
> **Status:** Scaffold only. Security pages are not migrated yet.
This chapter will contain authentication, authorization, SSO, secrets, RBAC, and security-control guidance for administrators.
## Planned pages
- `sso-providers.md` — migrate and verify [`docs/SSO-PROVIDERS.md`](../../SSO-PROVIDERS.md).
- `secrets.md` — document secret handling after source/configuration verification.
- `rbac.md` — document roles and permissions from the canonical implementation.
Do not treat the root SSO document as current guidance until the dynamic provider-discovery behavior and all provider claims have been reconciled.
## Related
- [`Administrator guide`](../README.md)
- [`API documentation`](../../API/README.md)
- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]
docs/API/README.md
+31
View File
@@ -0,0 +1,31 @@
# API Documentation
> **Status:** Scaffold only. The canonical gateway contract has not yet been migrated into this directory.
This directory is the single API documentation boundary. `OPENAPI.yaml` will be the machine-readable contract, and `ENDPOINTS.md` will provide the human-readable endpoint, authentication, permission, and error index. Neither file exists here yet; do not describe this scaffold as a complete API reference.
## Start here
- [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
- [Documentation sitemap](../SITEMAP.md) — existing navigation is transitional and still contains legacy paths.
- [Documentation catalog audit](../reports/documentation/2026-08-10-docs-catalog-audit.md) — current API artifact inventory and migration evidence.
## Contract map
| Artifact | Purpose | Status |
| ---------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------- |
| `OPENAPI.yaml` | Canonical machine-readable HTTP/WebSocket API contract. | Planned; not present yet. |
| `ENDPOINTS.md` | Human index for endpoint behavior, auth, permissions, and errors. | Planned; not present yet. |
| [`../openapi-tess.yaml`](../openapi-tess.yaml) | Legacy Tess-scoped OpenAPI artifact with 17 paths. | Migration candidate; not the complete gateway contract. |
A contract migration must verify paths, schemas, authentication, permissions, error behavior, and generated/client references before the legacy artifact is retired. Keep scoped contracts explicitly labeled if they remain alongside the consolidated contract.
## Authoring boundary
New API contracts belong here. Use `OPENAPI.yaml` for machine-readable authority and `ENDPOINTS.md` for human-readable constraints that OpenAPI cannot fully express. Guide books may explain usage workflows, but must link back to this directory rather than copying endpoint definitions.
## Related
- [[README|Documentation contract]]
- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]
- [[ADMIN-GUIDE/security/README|SSO provider chapter]]
docs/DEVELOPER-GUIDE/README.md
+46
View File
@@ -0,0 +1,46 @@
# Developer Guide
> **Status:** Scaffold only. Architecture and contributor pages are not migrated yet.
This book is the canonical home for architecture, package and application guides, local development, testing, contribution workflow, and integration authoring. User-facing procedures belong in [`USER-GUIDE/`](../USER-GUIDE/); operator procedures belong in [`ADMIN-GUIDE/`](../ADMIN-GUIDE/); API contracts belong in [`API/`](../API/).
## Start here
- [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
- [Architecture index](architecture/README.md) — current architecture chapter scaffold.
- [Documentation audit](../reports/documentation/2026-08-10-docs-catalog-audit.md) — evidence-based migration inventory.
- [Product requirements](../PRD.md) — normative requirements, currently marked draft.
## Chapter map
| Chapter | Scope | Status |
| ----------------------------------------- | -------------------------------------------------------------------- | -------------- |
| [`architecture/`](architecture/README.md) | System model, components, data flow, security model, ADRs, and RFCs. | Scaffold only. |
| `packages/` | Package- and application-level contracts and guides. | Scaffold only. |
| `local-development/` | Safe local setup and development routes. | Scaffold only. |
| `testing/` | Test strategy, verification, and quality gates. | Scaffold only. |
| `contributing/` | Contribution, review, and delivery workflow. | Scaffold only. |
| `integrations/` | Plugin, provider, and adapter authoring. | Scaffold only. |
Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.
## Migration backlog — not current developer guidance
These are source candidates or stale records, not verified current instructions:
- [`PRD-TUI_Improvements.md`](../PRD-TUI_Improvements.md) — contradicted/stale; it references a missing `packages/cli`, while current TUI code is under `packages/mosaic`.
- [`TASKS-TUI_Improvements.md`](../TASKS-TUI_Improvements.md) — historical task ledger; its status and worktree claims require revalidation.
- [`_old_structure/guides/dev-guide.md`](../_old_structure/guides/dev-guide.md) — historical source; verify paths and commands before promotion.
- [`_old_structure/architecture/`](../_old_structure/architecture/) — historical architecture sources; classify each page before migration.
Do not make a legacy or archived page current by linking it from a chapter as if it were already promoted.
## Authoring boundary
New developer documentation belongs under one of the chapter directories above. Architecture decisions and RFCs must identify their status and authority; executable behavior must be checked against current code and tests.
## Related
- [[README|Documentation contract]]
- [[DEVELOPER-GUIDE/architecture/README|Architecture index]]
- [[API/README|API index]]
docs/DEVELOPER-GUIDE/architecture/README.md
+36
View File
@@ -0,0 +1,36 @@
# Architecture
> **Status:** Scaffold only. No legacy architecture page has been promoted into this chapter yet.
This chapter is the canonical home for Mosaic Stack's system model, component boundaries, data and control flow, security model, architecture decisions, and RFCs. It explains why the system has its shape; it does not replace [`PRD.md`](../../PRD.md), [`TASKS.md`](../../TASKS.md), or the API contract.
## Planned pages
| Path | Purpose | Status |
| -------------------- | --------------------------------------------------------------------- | -------------- |
| `system-overview.md` | Platform boundary and major request, event, and agent-runtime flows. | Planned. |
| `component-map.md` | Apps, packages, plugins, and dependency ownership. | Planned. |
| `data-flow.md` | Data, event, and control-plane movement. | Planned. |
| `security-model.md` | Trust boundaries, authority, authentication, and authorization model. | Planned. |
| `decisions/` | Approved architecture decision records. | Scaffold only. |
| `rfcs/` | Proposals and protocol RFCs. | Scaffold only. |
Promoted pages must be linked here, from [`DEVELOPER-GUIDE/README.md`](../README.md), and from [`SITEMAP.md`](../../SITEMAP.md). Do not create duplicate architecture pages in `docs/mosaic-stack/` or the docs root.
## Migration backlog — not current architecture
- [`docs/README.md`](../../README.md) — current documentation contract and placement rules.
- [`Documentation information architecture design`](../../plans/2026-08-10-docs-information-architecture-design.md) — approved documentation structure decision, not product architecture.
- [`Documentation catalog audit`](../../reports/documentation/2026-08-10-docs-catalog-audit.md) — evidence and migration recommendations, not normative architecture.
- [`_old_structure/architecture/`](../../_old_structure/architecture/) — historical sources; each page requires classification and claim verification before promotion.
## Source-of-truth boundary
Architecture pages explain approved design and current system boundaries. Requirements remain in [`PRD.md`](../../PRD.md); active work remains in [`TASKS.md`](../../TASKS.md); executable behavior remains authoritative in source and tests. Draft proposals belong in `rfcs/` or [`docs/plans/`](../../plans/), with status clearly labeled.
## Related
- [[README|Documentation contract]]
- [[DEVELOPER-GUIDE/README|Developer guide]]
- [[PRD|Product requirements]]
- [[API/README|API index]]
docs/USER-GUIDE/README.md
+40
View File
@@ -0,0 +1,40 @@
# User Guide
> **Status:** Scaffold only. No legacy page has been promoted into this book yet.
This book is the canonical home for end-user workflows, user-visible behavior, product concepts, and user troubleshooting. Keep installation, deployment, security controls, and recovery procedures in [`ADMIN-GUIDE/`](../ADMIN-GUIDE/); keep implementation detail in [`DEVELOPER-GUIDE/`](../DEVELOPER-GUIDE/).
## Start here
- [Documentation atlas](../README.md) — placement rules and source-of-truth boundaries.
- [Documentation sitemap](../SITEMAP.md) — existing navigation is transitional and still contains legacy paths.
- [Quickstart candidate](../QUICKSTART.md) — currently empty; it is not yet a usable guide.
## Chapter map
| Chapter | Scope | Status |
| ------------------ | ------------------------------------------------------------- | ---------------------------------------------------------- |
| `getting-started/` | First-use setup, orientation, and quickstarts. | Scaffold only; `QUICKSTART.md` is the migration candidate. |
| `concepts/` | User-facing terminology, product concepts, and mental models. | Scaffold only. |
| `workflows/` | Task-oriented procedures for using Mosaic Stack. | Scaffold only. |
| `troubleshooting/` | User-visible failures, diagnostics, and fixes. | Scaffold only. |
Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice.
## Migration backlog — not current navigation
These are source candidates, not current user guidance:
- [`_old_structure/guides/user-guide.md`](../_old_structure/guides/user-guide.md) — historical source; verify every claim before promotion.
- [`QUICKSTART.md`](../QUICKSTART.md) — incomplete zero-byte placeholder.
Do not link to the quarantine as a current user path. Create a new page only after classifying its audience, status, and evidence in the migration report.
## Authoring boundary
New user-facing documentation belongs under one of the chapter directories above. Use a lowercase kebab-case page name, state whether commands are current or held, and link back to this index plus related canonical sources.
## Related
- [[README|Documentation contract]]
- [[PRD|Product requirements]]
docs/scratchpads/DOCS-IA-002-catalog-audit.md
+3
View File
@@ -17,6 +17,7 @@
- [x] Write human-readable catalog/audit report.
- [x] Verify report formatting and scope.
- [x] Commit audit artifacts without unrelated working-tree changes.
- [x] Scaffold audience, architecture, and API indexes without moving legacy content.
## Initial findings
@@ -29,6 +30,7 @@
- TUI documents reference missing `packages/cli` and a missing historical worktree; current TUI code is under `packages/mosaic`.
- `docs/openapi-tess.yaml` parses as OpenAPI 3.1 with 17 paths, but remains a legacy root-level Tess-scoped contract rather than the full API SSOT.
- `.gitignore` ignores `docs/reports/`, conflicting with the new documentation contract; the audit report must be force-added and ignore remediation deferred to a separate change.
- The scaffold slice adds `USER-GUIDE/README.md`, `ADMIN-GUIDE/README.md`, `ADMIN-GUIDE/security/README.md`, `DEVELOPER-GUIDE/README.md`, `DEVELOPER-GUIDE/architecture/README.md`, and `API/README.md`; legacy pages and `SITEMAP.md` remain unchanged.
## Method
@@ -58,3 +60,4 @@
| Scoped commit | PASS — audit plan, report, and scratchpad committed together; `.mosaic/orchestrator/*` remains outside the commit |
| Report formatting and scope | PASS — `pnpm exec prettier --ignore-path /dev/null --check` passed; ignored report path identified and force-add is required |
| Commit hook behavior | FINDING — lint-staged emitted an ignored `docs/reports` path error during commit even though the report was force-staged; remediation remains open |
| Index scaffold | PASS — six indexes formatted, all new Markdown/wikilinks resolve, target directories exist, and legacy pages plus `SITEMAP.md` were not changed |