docs: establish state hub baseline

AGENTS.md

@@ -0,0 +1,72 @@
+# AGENTS.md
+
+This repository is the standalone home for the Custodian State Hub service.
+
+## Session Start
+
+1. Read this file and `SCOPE.md`.
+2. Read `.custodian-brief.md` if present.
+3. If the State Hub API is reachable, query the local hub for orientation:
+   - `GET http://127.0.0.1:8000/state/summary`
+   - `GET http://127.0.0.1:8000/messages/?to_agent=hub&unread_only=true`
+4. Mark relevant inbox messages read after acting on them.
+5. Check `git status --short` before editing.
+
+If the API is not reachable, continue from local files. The repo must remain
+usable offline.
+
+## Repository Boundary
+
+State Hub owns:
+
+- FastAPI app, models, schemas, routers, migrations
+- MCP server and tool reference
+- Observable dashboard
+- consistency, registration, SBOM, token, image, and repo-sync scripts
+- task-flow engine and flow definitions
+- State Hub operational docs, tests, policies, prompts, and infra
+
+The Custodian governance repo owns:
+
+- canon, constitution, values, memory, and broad cross-domain governance
+- bridge workplans that coordinate extraction from the old embedded layout
+
+Do not write governance canon directly from this repo.
+
+## Build And Test
+
+After the implementation move, the expected command surface is:
+
+```bash
+make install
+make db
+make migrate
+make test
+make api
+make mcp-http
+make dashboard
+```
+
+When API routers, models, migrations, or consistency logic change, run the
+relevant tests before closing the session. Prefer `make test` when the database
+test prerequisites are available.
+
+## Workplans
+
+Use `workplans/` for State Hub-local workplans. New workplans should use:
+
+```text
+SHUB-WP-0001
+```
+
+For migrated Custodian-hosted plans, preserve existing `state_hub_workstream_id`
+and task IDs when safe. Never call `create_workstream()` or `create_task()`
+manually for a file-backed workplan before the file exists in this repo.
+
+## Session Close
+
+1. Add a progress event through State Hub if the API is reachable.
+2. Run consistency sync for this repo once it is registered.
+3. Record any decisions that change repo ownership, state model, API contracts,
+   or deployment topology.
+4. Leave the worktree clear or explicitly report remaining uncommitted changes.