mosaicstack/stack
1
0
Fork 1
Code Issues 246 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/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]]