Normalize repo metadata and sync docs

AGENTS.md

@@ -4,11 +4,17 @@
 
 **Purpose:** Auto-regulating market value exploring price engine.
 
-**Domain:** financials
+**Primary repo domain:** financials
 **Repo slug:** adaptive-pricing
+**State Hub topic:** `helix-forge`
 **Topic ID:** `f39fa2a3-c491-414c-a91b-b4c5fcc6139c`
 **Workplan prefix:** `ADAPTIVE-WP-`
 
+`adaptive-pricing` is classified as a `financials` repo in
+`.repo-classification.yaml`, but State Hub coordination currently runs through
+the shared `helix-forge` topic in the hub's `infotech` domain. Keep repo-domain
+fields (`domain`) and hub-topic fields (`topic_slug`, `topic_id`) distinct.
+
 ---
 
 ## State Hub Integration
@@ -27,7 +33,7 @@ there is no MCP server for Codex agents.
 # Offline brief — works without hub connection
 cat .custodian-brief.md
 
-# Active workstreams for this domain
+# Active workstreams for this repo's hub topic
 curl -s "http://127.0.0.1:8000/workstreams/?topic_id=f39fa2a3-c491-414c-a91b-b4c5fcc6139c&status=active" \
   | python3 -m json.tool
 
@@ -80,7 +86,7 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
 ## Session Protocol
 
 **Start:**
-1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
+1. `cat .custodian-brief.md` — hub-topic goal and open workstreams (offline-safe)
 2. Check inbox: `GET /messages/?to_agent=adaptive-pricing&unread_only=true`; mark read
 3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
 4. Check human-needed tasks: `GET /tasks/?needs_human=true`
@@ -92,12 +98,22 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
 **Close:**
 1. Update workplan file task statuses to reflect progress
 2. Log: `POST /progress/` with a summary of what changed
-3. Note for the custodian operator: after workplan file changes, run from
-   `~/state-hub`:
+3. After workplan file changes, run:
    ```bash
+   statehub fix-consistency
+   ```
+   Fallback when the CLI is unavailable:
+   ```bash
+   /home/worsch/state-hub/.venv/bin/python /home/worsch/state-hub/custodian_cli.py \
+     fix-consistency --repo adaptive-pricing --repo-path /home/worsch/adaptive-pricing
+   ```
+   Legacy wrapper:
+   ```bash
+   cd ~/state-hub
    make fix-consistency REPO=adaptive-pricing
    ```
-   This syncs task status from files into the hub DB.
+   Coding agents should run the direct CLI when available. This syncs task
+   status from files into the hub DB.
 
 ---
 
@@ -161,7 +177,7 @@ get wrong.
 | Path | Purpose |
 |------|---------|
 | `INTENT.md`, `docs/`, `research/`, `registry/` | Generic adaptive-pricing framework |
-| `projects/<slug>/` | Deployment-specific MVP material (integrations, configs, project docs) |
+| `projects/<slug>/` | Deployment-specific implementations, integrations, data, and project docs |
 | `workplans/` | ADR-001 workplans and task tracking (including MVP execution plans) |
 
 Do not place project-specific MVP documentation in `specs/` or other generic
@@ -169,6 +185,35 @@ paths. The Coulomb Social MVP lives under `projects/coulomb-pricing/`; its
 Coulomb MVP workplan is archived at
 `workplans/archived/260622-ADAPTIVE-WP-0002-economic-observatory-mvp.md`.
 
+## Developer Workflow
+
+The root repo is documentation- and workplan-heavy. The current executable
+runtime lives under `projects/coulomb-pricing/`.
+
+```bash
+# Generate the Coulomb observatory Markdown report
+cd projects/coulomb-pricing
+python3 -m observatory --period 2026-06
+
+# Start the local observatory UI
+python3 -m observatory.server
+
+# Run tests when pytest is available
+python3 -m pytest -q
+
+# Makefile wrappers when make is available
+make test
+make serve
+make design
+
+# Sync workplan metadata back into the hub after workplan edits
+statehub fix-consistency
+
+# Fallback when the CLI is not installed
+/home/worsch/state-hub/.venv/bin/python /home/worsch/state-hub/custodian_cli.py \
+  fix-consistency --repo adaptive-pricing --repo-path /home/worsch/adaptive-pricing
+```
+
 ---
 
 ## Workplan Convention (ADR-001)
@@ -194,11 +239,11 @@ anything needing analysis, design, approval, dependencies, or multiple phases.
 id: ADAPTIVE-WP-NNNN
 type: workplan
 title: "..."
-domain: helix_forge
+domain: financials
 repo: adaptive-pricing
 status: proposed | ready | active | blocked | backlog | finished | archived
 owner: codex
-topic_slug: ...
+topic_slug: helix-forge
 created: "YYYY-MM-DD"
 updated: "YYYY-MM-DD"
 state_hub_workstream_id: "<uuid>"   # written by fix-consistency — do not edit
@@ -228,5 +273,6 @@ Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blo
 
 To create a new workplan:
 1. Write the file following the format above
-2. Notify the custodian operator to run `make fix-consistency REPO=adaptive-pricing`
-   (or send a message to the hub agent via `POST /messages/`)
+2. Run `statehub fix-consistency` locally; use the direct CLI fallback above if
+   `statehub` is not installed. Ask the operator only if the CLI or State Hub
+   API is unavailable.