docs: establish state hub baseline

README.md

@@ -1,3 +1,61 @@
-# repo-seed
+# State Hub
 
-A git repository template to bootstrap coulomb projects from.
+State Hub is the live coordination service for the Custodian ecosystem:
+PostgreSQL persistence, FastAPI API, FastMCP server, Observable dashboard,
+consistency tooling, and repo/workplan synchronization.
+
+This repository is the standalone home for the service. It replaces the former
+embedded implementation at:
+
+```text
+/home/worsch/the-custodian/state-hub
+```
+
+## Current Extraction State
+
+The repo is being prepared by `CUST-WP-0043 - State Hub Repo Extraction`.
+
+During extraction:
+
+- The live implementation still exists in `the-custodian/state-hub/`.
+- This repo owns the standalone baseline and will become authoritative after
+  the implementation move and verification gate.
+- State Hub implementation work should land here once registration and
+  workplan re-homing are complete.
+
+## Stack
+
+| Layer | Technology | Default endpoint |
+|-------|------------|------------------|
+| Database | PostgreSQL | `127.0.0.1:5432` |
+| API | FastAPI + SQLAlchemy async | `127.0.0.1:8000` |
+| MCP | FastMCP SSE | `127.0.0.1:8001/sse` |
+| Dashboard | Observable Framework | `127.0.0.1:3000` |
+| CLI | `custodian` Python entry point | local shell |
+
+## Expected Commands After Implementation Move
+
+```bash
+cp .env.example .env
+make install
+make db
+make migrate
+make seed
+make api
+make mcp-http
+make dashboard
+make test
+```
+
+## Workplans
+
+New State Hub-local workplans should use the prefix:
+
+```text
+SHUB-WP-0001
+```
+
+Legacy Custodian-hosted State Hub plans, such as `CUST-WP-0042`, may be carried
+over with their existing State Hub IDs or bridged by a new `SHUB-WP-*`
+continuation plan. Do not create duplicate workstreams manually; write the
+workplan file first, then run consistency sync after this repo is registered.