docs: clarify state hub intent

INTENT.md

@@ -0,0 +1,110 @@
+---
+domain: custodian
+repo: state-hub
+updated: "2026-05-17"
+---
+
+# INTENT
+
+> This file explains why State Hub exists, where its authority begins and ends,
+> and why it is now separate from the-custodian.
+
+---
+
+## Why it exists
+
+State Hub exists because the Custodian ecosystem needs a live, queryable,
+auditable memory of work: domains, repositories, workstreams, tasks, decisions,
+progress events, lifecycle state, and operational telemetry.
+
+Files are excellent for canon, workplans, and provenance. They are less
+ergonomic as the live coordination surface for agents, dashboards, API clients,
+and cross-repo automation. State Hub gives those actors a local-first service
+that can answer "what is happening now?" without replacing the governance record
+that lives in the-custodian.
+
+---
+
+## The governing principle
+
+State Hub is the **readable state and coordination service** for the ecosystem.
+
+It should answer:
+
+1. **What exists?** Domains, repos, workstreams, tasks, decisions, and tools.
+2. **What changed?** Progress events, lifecycle events, interface changes, and
+   synchronization results.
+3. **What needs attention?** Blockers, human interventions, repo health, and
+   dashboard-visible drift.
+
+It should not become the canon, the task factory, the identity authority, or a
+general application platform. When State Hub detects facts, it records and
+exposes them; when new work must be spawned from events, that responsibility
+belongs to activity-core or a human-approved workflow.
+
+---
+
+## What it is
+
+State Hub is the **local-first operational state service** for Custodian.
+
+It contains:
+
+- PostgreSQL persistence and Alembic migrations
+- FastAPI endpoints for topics, repos, workstreams, tasks, decisions, progress,
+  capabilities, contributions, SBOM, TPSC, and related coordination records
+- FastMCP tools for agent access
+- Observable dashboard pages for human inspection
+- consistency tooling that syncs repo-backed workplan files into live state
+- task-flow evaluation and policies for lifecycle movement
+- operational docs, tests, local infra, and prompts for running the service
+
+---
+
+## What it is not
+
+| Concern | Owner |
+|---|---|
+| Canon, values, constitution, and domain charters | `the-custodian` |
+| Event-triggered maintenance task creation | `activity-core` |
+| General task lifecycle backend outside Custodian workplans | `issue-core` |
+| Repository capability profiling and SCOPE generation | `repo-scoping` |
+| Network connectivity/tunnel management | `ops-bridge` |
+| External publication, contracts, payments, or legal authority | Human approval only |
+
+State Hub can reference these systems and expose their status, but it should not
+absorb their core responsibilities.
+
+---
+
+## What it enables
+
+When State Hub is doing its job, Bernd and agents can:
+
+- start a session with current cross-domain state instead of stale local memory
+- see active workstreams, tasks, blockers, decisions, and recent progress in one
+  place
+- sync workplan files into database-backed dashboard views without ghost
+  workstreams
+- access the same coordination state through REST, MCP, CLI, and dashboard
+- keep operational state local, inspectable, and recoverable
+
+---
+
+## Design values
+
+**Local-first operations.** The service runs on local infrastructure and binds to
+loopback by default.
+
+**Files remain authoritative where they should.** Repo-backed workplans are
+written as files first, then synchronized into the database.
+
+**Append-only progress.** Progress events record what happened and are not
+silently rewritten.
+
+**Degrade gracefully.** The dashboard and tools should make partial state
+visible rather than fail opaquely when one component is unavailable.
+
+**Narrow authority.** State Hub coordinates and exposes state; it does not make
+irreversible human decisions or become the owner of every adjacent system.
+

README.md

@@ -11,16 +11,17 @@ the former embedded implementation at:
 /home/worsch/the-custodian/state-hub
 ```
 
-## Current Extraction State
+## Extraction State
 
-The repo is being prepared by `CUST-WP-0043 - State Hub Repo Extraction`.
+The extraction workplan `CUST-WP-0043 - State Hub Repo Extraction` is complete.
 
-During the extraction window:
+Current state:
 
 - The implementation has been imported here with subtree history.
 - `CUST-WP-0042` has been re-homed into this repository.
-- The old embedded tree in `the-custodian` should remain only as a pointer once
+- The old embedded tree in `the-custodian` remains only as a pointer.
-  the verification gate passes.
+- This repository is authoritative for State Hub code, docs, tests, dashboard,
+  migrations, scripts, policies, and State Hub-local workplans.
 
 ## Workplans
 
@@ -30,10 +31,10 @@ New State Hub-local workplans should use the prefix:
 SHUB-WP-0001
 ```
 
-Legacy Custodian-hosted State Hub plans, such as `CUST-WP-0042`, may be carried
+Legacy Custodian-hosted State Hub plans, such as `CUST-WP-0042`, may retain
-over with their existing State Hub IDs or bridged by a new `SHUB-WP-*`
+their existing IDs when that preserves State Hub workstream/task continuity.
-continuation plan. Do not create duplicate workstreams manually; write the
+Do not create duplicate workstreams manually; write the workplan file first,
-workplan file first, then run consistency sync after this repo is registered.
+then run consistency sync.
 
 ---
 

SCOPE.md

@@ -26,17 +26,17 @@ telemetry.
 - generic hub-core extraction unless a dedicated workplan owns it
 - renaming State Hub to Dev Hub unless a dedicated workplan owns it
 
-## Current Extraction Note
+## Extraction Note
 
-This repo is being established as the standalone State Hub home under
+This repo is the standalone State Hub home. It was extracted under
-`CUST-WP-0043`. The implementation has been imported here from:
+`CUST-WP-0043` from:
 
 ```text
 /home/worsch/the-custodian/state-hub
 ```
 
-After verification, this repository is authoritative and the embedded copy in
+This repository is authoritative for State Hub implementation work. The
-`the-custodian` should be removed or replaced with a pointer.
+embedded path in `the-custodian` is now a pointer only.
 
 ## Workplan Convention