docs: sync from source repos — charter, edgestack, ecosystem

Kurt Overmier · claude · Kurt Overmier · commit f0713547aa93 · 2026-03-14T07:11:31.000-05:00
Synced 3 pages via docs-sync pipeline:
- getting-started.md: streamlined from charter repo
- compass-governance-api.md: expanded route taxonomy from edgestack_v2
- ecosystem.md: updated to 3-piece architecture (engine merged into Stackbilder)

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/src/content/docs/compass-governance-api.md b/src/content/docs/compass-governance-api.md
@@ -7,102 +7,175 @@ color: "#22d3ee"
 tag: "08"
 ---
 
-# Compass Governance
+# Compass Governance API
 
-Compass is an internal governance service accessed via Cloudflare Service Binding from the Stackbilder flow pipeline. It is **not a public API** — there are no HTTP endpoints, no MCP server, and no admin surface.
+Compass is the governance system behind StackBilt. This page documents the current Compass API surface and route taxonomy implemented in the `DigitalCSA` worker.
 
-## Architecture
+Base URL (production): accessed via Stackbilder service binding (not a public subdomain)
 
-Compass is a lightweight RPC service (`compass` worker) bound to EdgeStack via `CSA_SERVICE` service binding. It provides governance guidance, quality assessment, and decision persistence for the 6-mode flow pipeline.
+## What This Covers
 
-```
-EdgeStack (FlowDO)
-  │
-  ├── fetchGuidance(mode, tier) → constraints + quality thresholds
-  │
-  ├── mode execution (LLM)
-  │
-  ├── assessQuality(artifact) → score + pass/fail
-  │
-  └── persistDecisions(decisions) → ledger write (SPRINT mode only)
-```
+- Compass MCP endpoints (`/mcp`, `/mcp/info`, legacy compatibility paths)
+- Canonical admin/domain route taxonomy
+- JWT + JWKS auth routes
+- Core governance APIs (ledger, patterns, requests, triage, validation, exhibits, agent ops)
 
-## RPC Methods
+This page is a route map and integration reference, not a full schema-level endpoint spec.
 
-All calls go through `POST /rpc` with JSON-RPC payload. Requires `scope` object with `projectId`, `flowId`, `mode`, `tier`, `effectiveGovernanceMode`.
+## Authentication Model
 
-### compass.fetchGuidance
+Compass uses scoped API auth for most `/api/*` routes and enforces tenant/domain boundaries in the worker:
 
-Returns governance context and quality thresholds for a flow mode. Called before each mode execution.
+- ecosystem scope (`ecosystem_id`)
+- optional domain/project scope (`domain_id` / `project_id`)
+- payload scope enforcement on write requests (`POST` / `PATCH` / `PUT`)
 
-```json
-{
-  "method": "compass.fetchGuidance",
-  "params": {
-    "scope": {
-      "projectId": "...",
-      "flowId": "...",
-      "mode": "ARCHITECT",
-      "tier": "pro",
-      "effectiveGovernanceMode": "ADVISORY"
-    }
-  }
-}
-```
+### MCP Authentication (`/mcp`)
 
-### compass.assessQuality
+Compass MCP supports:
 
-Scores a generated artifact against quality thresholds. Called after artifact generation.
+- JWT Bearer token (primary)
+- session-based follow-up requests via `mcp-session-id`
+- query-token compatibility mode (deprecated; can be warn/block mode)
 
-```json
-{
-  "method": "compass.assessQuality",
-  "params": {
-    "scope": { "..." },
-    "artifact": "...",
-    "mode": "ARCHITECT"
-  }
-}
-```
+If no valid JWT and no session is present, Compass rejects the request.
 
-### compass.persistDecisions
+### JWT / JWKS Routes
 
-Stores ADRs and architectural decisions in the governance ledger. Called at end of SPRINT mode only.
+| Endpoint | Method | Notes |
+|---|---|---|
+| `/api/.well-known/jwks.json` | `GET` | Public JWKS for JWT verification |
+| `/api/auth/token` | `POST` | Issue Compass JWT (requires valid API key) |
+| `/api/auth/revoke` | `POST` | Revoke JWTs (admin only) |
 
-```json
-{
-  "method": "compass.persistDecisions",
-  "params": {
-    "scope": { "..." },
-    "decisions": [{ "..." }]
-  }
-}
-```
+## MCP Endpoints
 
-## Governance Modes by Plan
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/mcp/info` | `GET` | Public server info / capabilities summary |
+| `/mcp` | `GET` | SSE stream (session-capable) |
+| `/mcp` | `POST` | MCP JSON-RPC requests |
+| `/mcp` | `DELETE` | End MCP session |
+| `/mcp/*` | `GET/POST` | MCP path variants routed through the same handler |
+| `/mcp-client/*` | varies | Admin-only MCP client routes (feature flagged) |
 
-| Plan | Max Mode | Behavior |
-|------|----------|----------|
-| Free | `PASSIVE` | Log only — never blocks |
-| Pro | `ADVISORY` | Warn on issues, flow continues |
-| Enterprise | `ENFORCED` | Block on FAIL, require remediation |
+## Canonical Route Taxonomy
 
-## Integration
+Compass uses a canonical route structure for admin, domain registry, and domain-scoped governance operations.
 
-EdgeStack creates a `CompassExchangeClient` per flow (cached, 5-min TTL). The client calls Compass via service binding with a 10-second timeout.
+### Admin Routes (`/api/admin/*`)
 
-```toml
-# edgestack-v2/wrangler.toml
-[[services]]
-binding = "CSA_SERVICE"
-service = "compass"
-```
+Primary admin surfaces include:
 
-## Future Direction
+- `/api/admin/keys`
+- `/api/admin/domains`
+- `/api/admin/repo-keys`
+- `/api/admin/repo-keys/:keyId/rotate`
+- `/api/admin/repo-keys/:keyId/revoke`
+- `/api/admin/repo-keys/:keyId/events`
+- `/api/admin/repos/:repoId/revoke-all-keys`
 
-Compass governance logic is being consolidated into the Stackbilder Engine (`stackbilt-engine`), which already handles blessed pattern enforcement, compatibility scoring, and tier gating deterministically. See [edgestack#32](https://github.com/Stackbilt-dev/edgestack_v2/issues/32) for the migration plan.
+These routes require admin auth and apply scope checks before writes.
+
+### Domain Registry Routes (`/api/domains`)
+
+Admin-manageable domain registry endpoints:
+
+- `GET/POST /api/domains`
+- `GET/PATCH /api/domains/:domainId`
+
+### Domain-Scoped Governance Routes (`/api/domains/:domainId/*`)
+
+These routes enforce domain ownership and payload scoping.
+
+| Endpoint Pattern | Methods | Purpose |
+|---|---|---|
+| `/api/domains/:domainId/ledger` | `GET`, `POST` | Ledger entries |
+| `/api/domains/:domainId/tickets` | `GET`, `POST` | Governance requests/tickets |
+| `/api/domains/:domainId/chat/threads` | `GET`, `POST` | Domain chat threads |
+| `/api/domains/:domainId/chat/threads/:id` | `GET`, `PATCH`, `DELETE` | Thread lifecycle |
+| `/api/domains/:domainId/chat/threads/:id/messages` | `POST` | Send message |
+| `/api/domains/:domainId/patterns` | `GET`, `POST` | Pattern catalog |
+| `/api/domains/:domainId/patterns/:id` | `GET`, `PATCH`, `DELETE` | Pattern management |
+| `/api/domains/:domainId/protocols` | `GET`, `POST` | Protocols |
+| `/api/domains/:domainId/protocols/:id` | `DELETE` | Protocol delete |
+
+## Core Governance APIs (Top-Level)
+
+Compass also exposes top-level scoped APIs (with `ecosystem_id` / `project_id` query support in many cases) for compatibility and operational workflows.
+
+### Ledger, Patterns, Requests
+
+- `/api/ledger`
+- `/api/ledger/:id`
+- `/api/ledger/temporal/valid-at`
+- `/api/ledger/temporal/approaching-review`
+- `/api/ledger/:id/temporal`
+- `/api/patterns`
+- `/api/patterns/:id`
+- `/api/requests`
+- `/api/requests/:id`
+- `/api/requests/:id/resolve`
+- `/api/requests/:id/notes`
+
+### Triage, Audit, Validation
+
+- `/api/triage/run`
+- `/api/triage/commit` (admin)
+- `/api/triage/history`
+- `/api/triage/entropy`
+- `/api/triage/detect`
+- `/api/triage/scope`
+- `/api/audit/report`
+- `/api/validate`
+- `/api/validate/history` (admin)
+- `/api/git/validate`
+- `/api/git/validations` (admin)
+
+### Submission + Chat
+
+- `/api/submit`
+- `/api/submit/my`
+- `/api/submit/status/:id`
+- `/api/chat/threads`
+- `/api/chat/threads/:id`
+- `/api/chat/threads/:id/messages`
+
+### Exhibits (Constitution / Policy Content)
+
+- `/api/exhibits`
+- `/api/exhibits/active/:projectId`
+- `/api/exhibits/:id`
+- `/api/exhibits/:id/sections`
+- `/api/exhibits/:exhibitId/sections/:sectionId`
+
+### Agent Operations (Admin)
+
+- `/api/agent/request-action`
+- `/api/agent/status/:actionId`
+- `/api/agent/approve/:actionId`
+- `/api/agent/audit/:actionId`
+- `/api/agent/kill-switch`
+- `/api/agent/actions`
+- `/api/agent/operations`
+- `/api/agent/cancel/:actionId`
+- `/api/agent/execute/:actionId`
+
+### Miscellaneous Operational Endpoints
+
+- `/api/heartbeat` (proactive governance health checks)
+- `/api/llm` (primary LLM route)
+- `/api/gemini` (deprecated compatibility route)
+
+## Integration Notes
+
+- Prefer the canonical domain-scoped routes (`/api/domains/:domainId/*`) for new integrations.
+- Use JWT auth for MCP clients and reuse the session header for follow-up requests.
+- Treat query-token MCP auth as deprecated and migrate to header-based auth.
+- For public key verification across services, use Compass JWKS (`/api/.well-known/jwks.json`).
 
 ## Related Docs
 
 - [Ecosystem](/ecosystem)
-- [Platform](/platform) (Stackbilder flow pipeline)
+- [MCP Integration](/mcp) (StackBilt MCP server)
+- [API Reference](/api-reference) (StackBilt platform API)
diff --git a/src/content/docs/ecosystem.md b/src/content/docs/ecosystem.md
@@ -9,53 +9,46 @@ tag: "01"
 
 # Ecosystem
 
-Stackbilt is a unified developer platform with four complementary systems spanning the full development lifecycle — from stack selection to governed deployment.
+StackBilt is three complementary tools that enforce governance across the full development lifecycle.
 
-## The Four Pieces
+## The Three Pieces
 
 | Tool | License | Role |
 |------|---------|------|
-| **Charter** (`@stackbilt/cli`) | Apache-2.0 (open source) | Local + CI governance runtime, ADF context compiler, CLI gateway to the engine |
-| **Stackbilder Engine** | Commercial | Deterministic tech stack builder — 52-primitive catalog, compatibility scoring, scaffold generation. Zero LLM. |
-| **Stackbilder Platform** | Commercial | AI-powered architecture generation, 6-mode flow pipeline, structured artifacts |
+| **Charter** (`@stackbilt/cli`) | Apache-2.0 (open source) | Local + CI governance runtime with ADF context compiler |
+| **Stackbilder** | Commercial | Architecture generation, scaffold engine, structured artifacts |
 | **Compass** | Commercial | Governance policy brain, institutional memory, ADR ledger |
 
-Charter is the open-source CLI. The engine, platform, and Compass are commercial services.
+Charter is the open-source foundation. Stackbilder and Compass are commercial services.
 
 ## Service Map
 
-| Service | URL / Worker | Purpose |
+| Service | URL | Purpose |
 |---------|-----|---------|
-| **Stackbilt Platform** | `stackbilt.dev` | Architecture generation, MCP server, flow pipeline |
-| **Stackbilt Engine** | `stackbilt-engine` | Deterministic stack builder (52-card tech deck, compatibility matrix, scaffold templates) |
-| **Compass** | via service binding | Governance enforcement, blessed patterns, ADR ledger |
-| **Auth** | `auth.stackbilt.dev` | Centralized auth — API keys, JWT, SSO, Stripe billing, PAYG credit packs |
-| **img-forge** | `imgforge.stackbilt.dev` | AI image generation API (multi-model, MCP + OAuth 2.1) |
-| **AEGIS** | `aegis.stackbilt.dev` | Persistent cognitive agent — memory, goals, task pipeline, dreaming cycle |
+| **StackBilt** | `stackbilt.dev` | Architecture generation, MCP server, scaffold engine |
+| **Compass** | via Stackbilder service binding | Governance enforcement, blessed patterns, ADR ledger |
+| **Auth Worker** | `auth-tenant-v2` | Authentication service (Better Auth + D1, OAuth, SSO) |
+| **img-forge** | `imgforge.stackbilt.dev` | AI image generation for documentation |
 
 ## How They Fit Together
 
 ```
 IDEA
   │
   ▼
-Engine: build(description) → deterministic stack selection (zero LLM)
-  │  52-primitive catalog, compatibility scoring, scaffold template
-  │
-  ▼
 Compass: governance("Can we build X?")
   │
   ├── REJECTED ──► Stop
   │
   ▼ APPROVED
-Platform: runFullFlowAsync(idea + engine stack)
+Stackbilder: runFullFlowAsync(idea)
   → PRODUCT → UX → RISK → ARCHITECT → TDD → SPRINT
   │
   ▼
 Compass: red_team(architecture) → security review
   │
   ▼
-Platform: getFlowScaffold(flowId) → deployable project
+Stackbilder: getFlowScaffold(flowId) → deployable project
   │
   ▼
 Charter: validate + drift → commit and stack compliance
@@ -79,7 +72,6 @@ npx charter adf init    # scaffold .ai/ context directory
 
 **Governance commands:** `validate`, `drift`, `audit`, `classify`, `hook install`.
 **ADF commands:** `adf init`, `adf fmt`, `adf patch`, `adf bundle`, `adf sync`, `adf evidence`.
-**Engine commands:** `login`, `architect`, `scaffold` — generate and write tech stacks via the Stackbilder Engine.
 
 For quantitative analysis of ADF's impact on autonomous system architecture, see the [Context-as-Code white paper](https://github.com/stackbilt-dev/charter-kit/blob/main/papers/context-as-code-v1.1.md).
 <!-- DOCSYNC:END:charter-oss-ecosystem -->
@@ -171,7 +163,7 @@ For automated pipelines, each service has its own token:
 
 ```json
 {
-  "stackbilder": { "url": "https://stackbilt.dev/mcp", "token": "STACKBILDER_MCP_TOKEN" },
+  "edgestack": { "url": "https://stackbilt.dev/mcp", "token": "EDGESTACK_MCP_TOKEN" },
   "compass": { "url": "https://stackbilt.dev/mcp", "transport": "service_binding", "token": "CSA_MCP_TOKEN" },
   "imgforge": { "url": "https://imgforge.stackbilt.dev/mcp", "token": "IMGFORGE_MCP_TOKEN" }
 }
diff --git a/src/content/docs/getting-started.md b/src/content/docs/getting-started.md
