# 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
make dashboard-check
```

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. `make test` includes an Observable dashboard
build smoke check so dashboard startup regressions are not missed.

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