stack/docs/SITEMAP.md

Documentation Sitemap

Transition status: The current structure is listed first. The legacy sections below are retained migration inventory and may contain stale or unresolved paths; they are not a claim that those pages are current.

Current documentation structure

• Documentation atlas — placement, source-of-truth, linking, and migration rules.
• User guide index — end-user documentation and current quickstart.
• Administrator guide index — operator documentation and current security runbooks.
• Developer guide index — partially migrated contributor and architecture documentation.
• Architecture index — system design, security contracts, decisions, and RFCs.
• Lease-broker protocol — authenticated runtime lease-broker protocol and persistence boundary.
• Lease-broker security notes — identity, ancestry, filesystem, and residual security boundaries.
• Whole mutator-class gate — default-deny tool authorization and launch choke point.
• Compaction revocation lifecycle — Claude/Pi lifecycle observers, generation fencing, and residual boundary.
• API documentation index — scaffold for the consolidated gateway contract.
• Documentation catalog and truth audit — evidence and migration recommendations.
• User quickstart — installed-CLI first-use path.
• SSO provider runbook — current Authentik, WorkOS, and Keycloak configuration.
• P8-003 performance report — historical performance evidence; not a current SLO or runbook.
• Archive index — retained historical pages; not current guidance.

Canonical pages added to a book must be linked from that book's README and this section. Replace or retire legacy entries only after the associated migration slice verifies repository references and claim status.

Compaction refresh lease broker

• Internal broker protocol — kernel identity, ancestry and generation invariants, framed requests, responses, and persisted cycle bindings.
• Broker operations — protected paths, startup, constrained recovery, fail-closed posture, distinct-principal deployment, and residual risk.
• Constrained recovery skill — source-resident thin wrapper, receipt scope, C4 replay boundary, and T-C middle-drop disclosure.
• Lease-broker security notes — identity, whole-class authorization, threat boundaries, and coordinator review requirements.
• Whole mutator-class gate — default-deny policy, revoke-first/promote-last state machine, TTL, runtime adapters, and T-B/T-C assurance boundary.
• Compaction revocation lifecycle — Claude/Pi observer matrix, same-PID generation rollover, failure fencing, and the named bounded residual stale window.

CLI and skill management

• Skill registration user guide — register, unregister, list statuses, automatic install/update reconciliation, and Claude reload behavior.
• Skill bridge developer guide — path-validation, ownership, clobber-protection, install/update wiring, tests, and Pi/Codex scope notes.

Fleet configuration management

• Fleet configuration entry point — desired-versus-observed decision tree and complete operator link map.
• Desired, derived, and observed state — roster authority, generation, ownership, and drift.
• Identity, class, and runtime — stable name, display alias, class, runtime, provider, and model separation.
• Role authority and leases — validator/merge-gate separation and bounded lease authority.
• Generated launch chain — strict data parsing, precedence, and quarantine.
• Roster v2 structural contract — schema, supported values, required fields, defaults, and constraints.
• Fleet CLI reference — local desired-state commands, JSON/exit behavior, and gateway-catalog separation.
• Lifecycle transitions — create/apply/reboot/migration/rollback boundaries.
• Status and drift — desired/managed/observed state and current/future classifications.
• Safe agent CRUD — expected generation, dry-run, and partial-failure recovery.
• Local lifecycle operations — persisted versus one-shot actions.
• Configurable interaction instance and validator instance — generic identities and protected limits.
• Reconcile and recover — plan/apply lock and recovery behavior.
• Environment quarantine — private evidence and value-free diagnostics.
• Systemd/tmux troubleshooting — socket, holder, unmanaged-session, and lock decisions.
• Backup/restore boundary and upgrade-assets hold.
• v1-to-v2 migration preview and executable artifact dispositions.
• FCM M5 closure evidence and approved deferrals.

Official channel plugins

• Channel protocol architecture — shared lifecycle, message, stable-route, authorization, and response-target contracts.
• Discord administrator configuration — secrets, allowlists, bindings, role policy, and thread permissions.
• Discord user workflow — in-channel messages, mention-created threads, and runtime-transparent continuity.
• Channel plugin authoring — requirements for future Matrix, Slack, and other official adapters.
• Discord package guide — package behavior, configuration shape, and development commands.

Native Kanban and canonical task SOT

• Canonical requirements — ratified P0–P3 requirements and acceptance criteria.
• Workstream index — artifact map, lane partition, and delivery order.
• Mission manifest — scope, authority, invariants, and gate model.
• Task decomposition — dependency-ordered implementation slices and ownership boundaries.
• KBN-101 database role split — rc.16 direct-Drizzle storage-wrapper hold: legacy N-1/uncertified/non-operative pending -02/-03/-06/-08; exact README/user-guide wrapper forms fail before masking and source-consistency rejects runner-delegation copy; held bootstrap → TLS/roles → run → verify → readiness; plus prior attestation, pgvector owner, classifier, TLS, activation, and certification prerequisite.
• Federated tier data migration — active KBN-101-07 operator route: runner-produced target attestation, dedicated non-DDL importer, and paired credential-/attestation-file references only.
• Frozen shared contract — schema, API, Coordinator, health, recovery, and migration contracts.
• KBN-101 exact-head security review — retained prior REQUEST CHANGES evidence for da742ca; rc.16 awaits independent exact-head re-review after closing the current generic storage-wrapper authority HIGH finding.
• Initial independent review — KCR-001–016 findings that blocked the first draft.
• Final independent re-review — closure evidence and GO verdict.
• Ultron final gate — final requirements, authority, schema, migration, recovery, and evidence review.

Tess interaction agent

Operator guides

• User guide — authorized session, attach, send, stop, and handoff workflows.
• Admin guide — deployment configuration, policy, and approval controls.
• Developer guide — provider contracts, scope boundaries, and test workflow.
• Plugin guide — adapter, redaction, and identity-as-data requirements.
• Operations guide — readiness, recovery, and incident-safe procedures.

Architecture and security

• Architecture
• Threat model
• Mos coordination boundary
• Hermes runtime adapter design
• Operator plugin sketch

API contract

• Tess OpenAPI contract

Migration and qualification

• Migration inventory
• Cutover procedure
• Rollback procedure
• Retention and deprecation evidence
• Verification matrix
• Documentation checklist
• Independent Option 2 runtime-portability qualification (2026-07-14)

Runtime-neutral Mos portability

• Optional AI egress gateway ADR — placement and gates for LiteLLM, Bifrost, and purpose-built translation proxies.
• Runtime-neutral Mos identity and failover mission
• Logical identity and connector lease/fencing implementation
• M1 logical identity and fencing architecture
• M1 connector lease operations

Comms evolution — Matrix-native MACP (design, draft)

• RFC-001 — MACP: a Mosaic-native, Matrix-native comms layer — Synapse + Mosaic appservice backbone, MACP v1 protocol, presence/escalation, federation, strangler migration off the Hermes MCP bridge.
• RFC-002 — Install, configuration & topology for the Matrix/MACP comms system — open-source install topology modes, ACME cert provisioning, pluggable secret backend, and config precedence.