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.
+