From 16920c4a6f4c1489b95d36edc5f2224362c51595 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Mon, 10 Aug 2026 18:33:02 -0500 Subject: [PATCH] docs: integrate second autonomous migration wave --- docs/ADMIN-GUIDE/security/README.md | 7 +++--- docs/DEVELOPER-GUIDE/README.md | 24 +++++++++++-------- docs/DEVELOPER-GUIDE/architecture/README.md | 21 +++++++++------- .../architecture/rfcs/README.md | 15 ++++++++++++ .../lease-broker-operations.md | 0 docs/SITEMAP.md | 16 +++++++++---- docs/USER-GUIDE/README.md | 9 +++++-- docs/scratchpads/DOCS-IA-002-catalog-audit.md | 18 +++++++++----- 8 files changed, 75 insertions(+), 35 deletions(-) create mode 100644 docs/DEVELOPER-GUIDE/architecture/rfcs/README.md rename docs/DEVELOPER-GUIDE/{operations => testing}/lease-broker-operations.md (100%) diff --git a/docs/ADMIN-GUIDE/security/README.md b/docs/ADMIN-GUIDE/security/README.md index 554fdc30..aff6909a 100644 --- a/docs/ADMIN-GUIDE/security/README.md +++ b/docs/ADMIN-GUIDE/security/README.md @@ -1,16 +1,17 @@ # Security -> **Status:** Initial migration active. The SSO provider runbook is current; other security pages remain planned. +> **Status:** Partially migrated. The SSO provider and Discord ingress security pages are current. This chapter will contain authentication, authorization, SSO, secrets, RBAC, and security-control guidance for administrators. ## Planned pages - [`sso-providers.md`](sso-providers.md) — current provider configuration, discovery, callbacks, and failure modes. -- `secrets.md` — document secret handling after source/configuration verification. +- [`discord-ingress.md`](discord-ingress.md) — current Discord service authentication, allowlists, bindings, roles, replay, and failure controls. +- `secrets.md` — document general secret handling after source/configuration verification. - `rbac.md` — document roles and permissions from the canonical implementation. -The current SSO page reflects the dynamic provider-discovery behavior. Do not revive the retired root document or add frontend feature flags that the web flow does not consume. +The current SSO page reflects dynamic provider discovery. The Discord page documents only the verified Discord compatibility boundary; it does not claim Telegram or Matrix parity. Do not revive retired root documents or add frontend feature flags that the web flow does not consume. ## Related diff --git a/docs/DEVELOPER-GUIDE/README.md b/docs/DEVELOPER-GUIDE/README.md index 8d81cb82..e9a4922a 100644 --- a/docs/DEVELOPER-GUIDE/README.md +++ b/docs/DEVELOPER-GUIDE/README.md @@ -1,6 +1,6 @@ # Developer Guide -> **Status:** Partially migrated. The architecture chapter contains the promoted lease-broker security-contract pages; contributor chapters remain unmigrated. +> **Status:** Partially migrated. Architecture, lease-broker verification, and channel-adapter authoring pages are current; other contributor chapters remain unmigrated. 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/). @@ -13,14 +13,19 @@ This book is the canonical home for architecture, package and application guides ## Chapter map -| Chapter | Scope | Status | -| ----------------------------------------- | -------------------------------------------------------------------- | ------------------- | -| [`architecture/`](architecture/README.md) | System model, components, data flow, security model, ADRs, and RFCs. | Partially migrated. | -| `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. | +| Chapter | Scope | Status | +| ----------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------- | +| [`architecture/`](architecture/README.md) | System model, components, data flow, security model, ADRs, and RFCs. | Partially migrated. | +| `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. | Lease-broker verification boundary is current. | +| `contributing/` | Contribution, review, and delivery workflow. | Scaffold only. | +| `integrations/` | Plugin, provider, and adapter authoring. | Channel-adapter authoring boundary is current. | + +### Current contributor pages + +- [Lease-broker operations and verification](testing/lease-broker-operations.md) — safe static/test commands plus explicitly held live operations. +- [Channel adapters](integrations/channel-adapters.md) — current shared contracts and Discord reference boundary; future adapter parity is draft. Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice. @@ -31,7 +36,6 @@ These are source candidates or stale records, not verified current instructions: - [`archived TUI PRD`](../archive/tui/PRD-TUI_Improvements.md) — contradicted/stale; it references a missing `packages/cli`, while current TUI code is under `packages/mosaic`. - [`archived TUI task ledger`](../archive/tui/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. diff --git a/docs/DEVELOPER-GUIDE/architecture/README.md b/docs/DEVELOPER-GUIDE/architecture/README.md index 153c4324..a7d4ac9f 100644 --- a/docs/DEVELOPER-GUIDE/architecture/README.md +++ b/docs/DEVELOPER-GUIDE/architecture/README.md @@ -17,14 +17,18 @@ These pages are current security-contract references and are consumed by the lea ## 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/`](decisions/README.md) | Approved architecture decision records. | Partially migrated. | -| `rfcs/` | Proposals and protocol RFCs. | Scaffold only. | +| 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/`](decisions/README.md) | Approved architecture decision records. | Partially migrated. | +| [`rfcs/`](rfcs/README.md) | Proposals and protocol RFCs. | Draft egress RFC indexed. | + +### Draft RFCs + +- [`rfcs/optional-ai-egress-gateways.md`](rfcs/optional-ai-egress-gateways.md) — proposed model-egress boundary; not approved or integrated. 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. @@ -33,7 +37,6 @@ Promoted pages must be linked here, from [`DEVELOPER-GUIDE/README.md`](../README - [`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/) — remaining historical sources; each page requires classification and claim verification before promotion. ## Source-of-truth boundary diff --git a/docs/DEVELOPER-GUIDE/architecture/rfcs/README.md b/docs/DEVELOPER-GUIDE/architecture/rfcs/README.md new file mode 100644 index 00000000..7c5b3085 --- /dev/null +++ b/docs/DEVELOPER-GUIDE/architecture/rfcs/README.md @@ -0,0 +1,15 @@ +# Architecture RFCs + +> **Status:** Current proposal index. RFCs are draft design material and have no operational or implementation authority until an approved decision and implementation evidence supersede them. + +## Draft proposals + +- [Optional AI egress gateways](optional-ai-egress-gateways.md) — proposed model-egress boundary; LiteLLM and Bifrost are not integrated, and Claudex remains experimental harness tooling. + +A draft RFC must not be cited as a supported feature, deployment path, or approved architecture decision. Approved implemented boundaries belong under [`../decisions/`](../decisions/README.md). + +## Related + +- [[DEVELOPER-GUIDE/architecture/README|Architecture index]] +- [[DEVELOPER-GUIDE/architecture/decisions/README|Architecture decisions]] +- [[PRD|Product requirements]] diff --git a/docs/DEVELOPER-GUIDE/operations/lease-broker-operations.md b/docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md similarity index 100% rename from docs/DEVELOPER-GUIDE/operations/lease-broker-operations.md rename to docs/DEVELOPER-GUIDE/testing/lease-broker-operations.md diff --git a/docs/SITEMAP.md b/docs/SITEMAP.md index 479e009a..172a7ba5 100644 --- a/docs/SITEMAP.md +++ b/docs/SITEMAP.md @@ -19,6 +19,12 @@ - [Administrator operations index](ADMIN-GUIDE/operations/README.md) — current local procedures and held operational outlines. - [Upgrade safety and recovery](ADMIN-GUIDE/operations/upgrade-safety-and-recovery.md) — installed-CLI/local-PGlite upgrade and framework recovery runbook. - [Mos connector lease operations](ADMIN-GUIDE/operations/mos-connector-lease-operations.md) — held/non-operative M1 operations outline. +- [Lease-broker operations and verification](DEVELOPER-GUIDE/testing/lease-broker-operations.md) — safe static/test workflow with live procedures held. +- [Optional AI egress gateways RFC](DEVELOPER-GUIDE/architecture/rfcs/optional-ai-egress-gateways.md) — draft proposal; no candidate is integrated. +- [Web dashboard](USER-GUIDE/product/web-dashboard.md) — current routes, views, chat persistence, settings, and admin behavior. +- [Discord conversations](USER-GUIDE/workflows/discord-conversations.md) — current authorized Discord workflow. +- [Discord ingress security](ADMIN-GUIDE/security/discord-ingress.md) — current service authentication, allowlist, binding, role, and replay controls. +- [Channel adapter authoring](DEVELOPER-GUIDE/integrations/channel-adapters.md) — current shared contract and Discord reference boundary. - [API documentation index](API/README.md) — scaffold for the consolidated gateway contract. - [Reports index](reports/README.md) — review, audit, QA, security, and retained evidence. - [Documentation catalog and truth audit](reports/documentation/2026-08-10-docs-catalog-audit.md) — evidence and migration recommendations. @@ -32,7 +38,7 @@ Canonical pages added to a book must be linked from that book's README and this ## Compaction refresh lease broker - [Internal broker protocol](DEVELOPER-GUIDE/architecture/lease-broker-protocol.md) — kernel identity, ancestry and generation invariants, framed requests, responses, and persisted cycle bindings. -- [Broker operations](guides/lease-broker-operations.md) — protected paths, startup, constrained recovery, fail-closed posture, distinct-principal deployment, and residual risk. +- [Broker operations](DEVELOPER-GUIDE/testing/lease-broker-operations.md) — safe static/test workflow; live startup, recovery, mutation, and cleanup remain held. - [Constrained recovery skill](../packages/mosaic/framework/skills/mosaic-context-refresh/SKILL.md) — source-resident thin wrapper, receipt scope, C4 replay boundary, and T-C middle-drop disclosure. - [Lease-broker security notes](DEVELOPER-GUIDE/architecture/lease-broker-security.md) — identity, whole-class authorization, threat boundaries, and coordinator review requirements. - [Whole mutator-class gate](DEVELOPER-GUIDE/architecture/mutator-class-gate.md) — default-deny policy, revoke-first/promote-last state machine, TTL, runtime adapters, and T-B/T-C assurance boundary. @@ -67,9 +73,9 @@ Canonical pages added to a book must be linked from that book's README and this ## Official channel plugins - [Channel protocol architecture](DEVELOPER-GUIDE/architecture/channel-protocol.md) — shared lifecycle, message, stable-route, authorization, and response-target contracts; future adapters are explicitly draft. -- [Discord administrator configuration](guides/admin-guide.md#discord-ingress-security) — secrets, allowlists, bindings, role policy, and thread permissions. -- [Discord user workflow](tess/USER-GUIDE.md#discord-conversations) — in-channel messages, mention-created threads, and runtime-transparent continuity. -- [Channel plugin authoring](tess/PLUGIN-GUIDE.md#official-channel-adapter-contract) — requirements for future Matrix, Slack, and other official adapters. +- [Discord administrator configuration](ADMIN-GUIDE/security/discord-ingress.md) — secrets, allowlists, bindings, role policy, and thread permissions. +- [Discord user workflow](USER-GUIDE/workflows/discord-conversations.md) — in-channel messages, mention-created threads, and runtime-transparent continuity. +- [Channel plugin authoring](DEVELOPER-GUIDE/integrations/channel-adapters.md) — current shared contract and requirements for future adapters. - [Discord package guide](../plugins/discord/README.md) — package behavior, configuration shape, and development commands. ## Native Kanban and canonical task SOT @@ -120,7 +126,7 @@ Canonical pages added to a book must be linked from that book's README and this ## Runtime-neutral Mos portability -- [Optional AI egress gateway ADR](architecture/ADR-MOS-EGRESS-GATEWAYS.md) — placement and gates for LiteLLM, Bifrost, and purpose-built translation proxies. +- [Optional AI egress gateway RFC](DEVELOPER-GUIDE/architecture/rfcs/optional-ai-egress-gateways.md) — draft placement and gates for LiteLLM, Bifrost, and translation proxies; no candidate is integrated. - [Runtime-neutral Mos identity and failover mission](https://git.mosaicstack.dev/mosaicstack/stack/issues/754) - [Logical identity and connector lease/fencing implementation](https://git.mosaicstack.dev/mosaicstack/stack/issues/755) - [M1 logical identity and fencing architecture](DEVELOPER-GUIDE/architecture/decisions/mos-runtime-portability-m1.md) diff --git a/docs/USER-GUIDE/README.md b/docs/USER-GUIDE/README.md index 98ea8f60..94e959d2 100644 --- a/docs/USER-GUIDE/README.md +++ b/docs/USER-GUIDE/README.md @@ -1,6 +1,6 @@ # User Guide -> **Status:** Initial migration active. The quickstart is current; additional user pages remain to be migrated. +> **Status:** Partially migrated. The quickstart, web-dashboard reference, and Discord conversation workflow are current. 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/). @@ -9,6 +9,8 @@ This book is the canonical home for end-user workflows, user-visible behavior, p - [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](getting-started/quickstart.md) — install Mosaic, complete setup, and launch a session. +- [Web dashboard](product/web-dashboard.md) — current routes, navigation, chat persistence, projects/tasks views, settings, and admin behavior. +- [Discord conversations](workflows/discord-conversations.md) — current authorized parent-channel, thread, attachment, and control workflow. ## Chapter map @@ -16,12 +18,15 @@ This book is the canonical home for end-user workflows, user-visible behavior, p | ------------------ | ------------------------------------------------------------- | ---------------------------------------------------- | | `getting-started/` | First-use setup, orientation, and quickstarts. | Quickstart is current; additional pages are planned. | | `concepts/` | User-facing terminology, product concepts, and mental models. | Scaffold only. | -| `workflows/` | Task-oriented procedures for using Mosaic Stack. | Scaffold only. | +| `workflows/` | Task-oriented procedures for using Mosaic Stack. | Discord conversation workflow is current. | +| `product/` | Current product surfaces and visible behavior. | Web dashboard reference is current. | | `troubleshooting/` | User-visible failures, diagnostics, and fixes. | Scaffold only. | ### Current pages - [Quickstart](getting-started/quickstart.md) — the verified installed-CLI first-use path. +- [Web dashboard](product/web-dashboard.md) — verified current Next.js dashboard behavior and limitations. +- [Discord conversations](workflows/discord-conversations.md) — verified current Discord user workflow. Every promoted page must be added to this index and to [`SITEMAP.md`](../SITEMAP.md) in the same migration slice. diff --git a/docs/scratchpads/DOCS-IA-002-catalog-audit.md b/docs/scratchpads/DOCS-IA-002-catalog-audit.md index 33c0173a..8c3fbd55 100644 --- a/docs/scratchpads/DOCS-IA-002-catalog-audit.md +++ b/docs/scratchpads/DOCS-IA-002-catalog-audit.md @@ -46,12 +46,12 @@ Shared indexes, navigation, audit records, integration review, and final commits ### Implementation wave 2 -| Lane | Branch | Owned slice | State | -| ---------------------- | --------------------------------- | ---------------------------------------------------------- | -------- | -| `docs-channel-guides` | `docs/channel-audience-guides` | Discord admin, user workflow, and adapter-authoring pages. | Running. | -| `docs-lease-ops` | `docs/lease-operations-migration` | Current/held lease-broker operational boundary. | Running. | -| `docs-egress-rfc` | `docs/egress-rfc-migration` | Explicitly draft optional egress gateway RFC. | Running. | -| `docs-dashboard-guide` | `docs/dashboard-guide-migration` | Verified current web-dashboard user page. | Running. | +| Lane | Branch | Owned slice | State | +| ---------------------- | --------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `docs-channel-guides` | `docs/channel-audience-guides` | Discord admin, user workflow, and adapter-authoring pages. | Complete; cherry-picked as `f4faa3f`. | +| `docs-lease-ops` | `docs/lease-operations-migration` | Current/held lease-broker operational boundary. | Complete; cherry-picked as `6b3ebce`, then placed under the canonical testing chapter. | +| `docs-egress-rfc` | `docs/egress-rfc-migration` | Explicitly draft optional egress gateway RFC. | Complete; cherry-picked as `0692d99`. | +| `docs-dashboard-guide` | `docs/dashboard-guide-migration` | Verified current web-dashboard user page. | Complete; cherry-picked as `7fa0f65`. | ## Progress @@ -74,6 +74,7 @@ Shared indexes, navigation, audit records, integration review, and final commits - [x] Remove the blanket `docs/reports/` ignore rule so canonical evidence can be staged and linted normally. - [x] Migrate the three-file #756 Discord evidence batch byte-identically and add a reports index. - [x] Complete and integrate the four implementation-agent slices after independent scope and evidence review. +- [x] Complete wave 2 audience, testing, RFC, and dashboard migrations and connect every page to its owning index and sitemap. ## Initial findings @@ -138,3 +139,8 @@ Shared indexes, navigation, audit records, integration review, and final commits | Channel architecture | PASS — verified DTO/Discord behavior is separated from draft Telegram, Matrix, registry, identity, and multiplexing work | | Runtime portability M1 | PASS — current decision precision corrected; companion operations page is explicitly held/non-operative | | Upgrade/recovery guide | PASS — installed-CLI/local-PGlite route only; PostgreSQL, Compose, migration, and Gateway/Web activation remain held | +| Implementation wave 2 | PASS — four isolated Luna lanes produced scoped commits; coordinator reviewed, cherry-picked, and integrated each page | +| Channel audience guides | PASS — Discord admin/user/developer pages align to shared source/tests and explicitly deny Telegram/Matrix parity claims | +| Lease-broker verification | PASS — safe static/test workflow is current; startup, recovery, mutation, service management, and cleanup remain held | +| Optional egress RFC | PASS — proposal remains draft/non-operative; model and runtime-provider boundaries are separated and candidates are not integrated | +| Web dashboard guide | PASS — current routes, views, chat persistence, and absent project/task creation controls are documented from source/tests |