Regenerate agent instructions: workstream -> workplan terminology

Registration guidance now prescribes file-first + fix-consistency (C-06)
instead of manual create_workplan/create_workstream calls; progress-event
examples use workplan_id; legacy field names annotated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.claude/rules/credential-routing.md

@@ -20,7 +20,7 @@ Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run wa
 | Agent runtime | How to orient |
 | --- | --- |
 | **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=net-kingdom` is for coordination, not secret vending |
-| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
+| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **still** use `warden route` for credential ownership |
 | **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
 
 ### Quick routing table

.claude/rules/first-session.md

@@ -1,6 +1,6 @@
 ## First Session Protocol
 
-Triggered when `get_domain_summary("infotech")` shows **no workstreams**.
+Triggered when `get_domain_summary("infotech")` shows **no workplans**.
 The project is registered but work has not yet been structured.
 
 **Step 1 — Read, don't write**
@@ -11,27 +11,31 @@ The project is registered but work has not yet been structured.
 **Step 2 — Survey in-progress work**
 Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.
 
-**Step 3 — Propose workstreams to Bernd**
+**Step 3 — Propose workplans to Bernd**
-Propose 1–3 workstreams — each a coherent strand, weeks to months, anchored to a
+Propose 1–3 workplans — each a coherent strand, weeks to months, anchored to a
 roadmap phase. **Wait for approval before creating.**
 
-**Step 4 — Create workplan file first, then DB record (ADR-001)**
+**Step 4 — Write the workplan file; fix-consistency registers it (ADR-001)**
 ```
-workplans/NK-WP-NNNN-<slug>.md   ← write this first
+workplans/NK-WP-NNNN-<slug>.md   ← write this, commit it
 ```
-Then register in the hub:
+Then register by running the consistency check — do **not** call
-```
+`create_workplan`/`create_task` (or legacy `create_workstream`) yourself;
-create_workstream(topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", title="...", owner="...", description="...")
+manual registration duplicates what C-06 creates from the file:
-create_task(workstream_id="<id>", title="...", priority="high|medium|low")
+```bash
+statehub fix-consistency --repo net-kingdom
 ```
+C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id` /
+`state_hub_task_id` back into the file (legacy field names, kept for
+compatibility — they hold workplan/task IDs).
 
 **Step 5 — Record the setup**
 ```
 add_progress_event(
-    summary="First session: structured infotech into N workstreams, M tasks",
+    summary="First session: structured infotech into N workplans, M tasks",
     event_type="milestone",
     topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a",
-    detail={"workstreams": [...], "tasks_created": M}
+    detail={"workplans": [...], "tasks_created": M}
 )
 ```
 

.claude/rules/session-protocol.md

@@ -44,7 +44,7 @@ For each file with `status: ready`, `active`, or `blocked`, note pending
 
 **Step 4 — Present brief**
 
-1. **Active workstreams** for `infotech` — title, task counts, blocking decisions
+1. **Active workplans** for `infotech` — title, task counts, blocking decisions
 2. **Pending tasks** from `workplans/` + any `[repo:net-kingdom]` hub tasks
 3. **Goal guidance** — if `goal_guidance` in summary:
    - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
@@ -52,33 +52,42 @@ For each file with `status: ready`, `active`, or `blocked`, note pending
 4. **Suggested next action** — highest-priority open item
 5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
 
-If no workstreams: follow First Session Protocol (`first-session.md`).
+If no workplans: follow First Session Protocol (`first-session.md`).
 
 **During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()`
 
-> State Hub is a *read model*. Bootstrap tools (`create_workstream`, `create_task`)
+> State Hub is a *read model*. **Never register workplans or tasks by hand**
-> are First Session Protocol only. Work structure belongs in repo files (ADR-001).
+> (`create_workplan`, `create_task`, or the legacy `create_workstream`) — write
+> the workplan file in `workplans/` and run `fix-consistency`; its C-06 check
+> registers the workplan and its tasks in the hub and writes the IDs back into
+> the file. Manual registration creates duplicates the moment fix-consistency
+> runs. Work structure belongs in repo files (ADR-001).
+>
+> Terminology: "workstream" is the legacy name for workplan. Some API/frontmatter
+> field names keep it for compatibility (`state_hub_workstream_id`,
+> `workstream_id` params) — treat them as workplan IDs.
 
 **Session close:**
 With MCP tools:
 ```
-add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workstream_id="<uuid>")
+add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workplan_id="<uuid>")
 ```
 Without MCP tools:
 ```bash
 curl -s -X POST http://127.0.0.1:8000/progress/ \
   -H "Content-Type: application/json" \
-  -d '{"topic_id":"cee7bedf-2b48-46ef-8601-006474f2ad7a","workstream_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
+  -d '{"topic_id":"cee7bedf-2b48-46ef-8601-006474f2ad7a","workplan_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
 ```
-If workplan files were modified, ensure the local copy is up to date first:
+If workplan files were modified, ensure the local copy is up to date first,
+then sync from the repo checkout:
 ```bash
-git -C <repo_path> pull --ff-only
+git pull --ff-only
-cd ~/state-hub && make fix-consistency REPO=net-kingdom
+statehub fix-consistency
 ```
 For repos where implementation runs on a remote machine (e.g. CoulombCore),
-use the combined target which pulls before fixing:
+use the pull-before-fix mode from any shell with the State Hub CLI:
 ```bash
-cd ~/state-hub && make fix-consistency-remote REPO=net-kingdom
+statehub fix-consistency --repo net-kingdom --remote
 ```
 **C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
 will sync the file to match DB.  **C-16** (repo behind remote) blocks all writes

.claude/rules/workplan-convention.md

@@ -5,7 +5,7 @@ ID prefix: `NK-WP-`
 
 Work items originate as files in this repo **before** being registered in the hub.
 
-Canonical workplan/workstream frontmatter statuses are:
+Canonical workplan frontmatter statuses are:
 `proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`.
 Use `proposed` for a newly drafted plan, `ready` after review against current
 repo state, and `finished` when implementation is complete. `stalled` and
@@ -16,14 +16,15 @@ prefix: `YYMMDD-NK-WP-NNNN-<slug>.md`. The frontmatter id remains
 unchanged; the prefix is only for quick visual reference.
 
 Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
-`workplans/ADHOC-YYYY-MM-DD.md`, workstream slug `adhoc-YYYY-MM-DD`, and task ids
+`workplans/ADHOC-YYYY-MM-DD.md`, workplan slug `adhoc-YYYY-MM-DD`, and task ids
 `ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed
 directly. Promote anything requiring analysis, design, approval, dependencies, or
 multiple planned phases into a normal workplan.
 
 Ecosystem todos from other agents arrive as `[repo:net-kingdom]` hub tasks —
-visible at session start. Pick one up by creating the workplan file, then registering
+visible at session start. Pick one up by creating the workplan file, committing,
-the workstream.
+and running `statehub fix-consistency` — C-06 registers the workplan in the hub.
+Never register by hand with `create_workplan`/`create_workstream`.
 
 Task blocks use this shape:
 
@@ -37,4 +38,8 @@ state_hub_task_id: "<uuid>"         # written by fix-consistency — do not edit
 Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
 blocked work and `cancel` for stopped work.
 
+Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name
+kept for compatibility ("workstream" is the old term for workplan); it holds
+the hub workplan id and is written by fix-consistency. Do not edit or rename it.
+
 <!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->

AGENTS.md

@@ -20,6 +20,12 @@ there is no MCP server for Codex agents.
 |---------|-----|
 | Local workstation | `http://127.0.0.1:8000` |
 | Remote via tunnel | `http://127.0.0.1:18000` |
+| Optional local edge relay | http://127.0.0.1:18080 |
+
+When an operator has enabled the edge relay, set API_BASE to the relay URL.
+Queueable writes return an explicit queued receipt if the central hub is
+unreachable. Treat that as pending local evidence, then ask the operator to run
+statehub outbox status/replay after connectivity returns.
 
 ### Orient at session start
 
@@ -27,8 +33,8 @@ there is no MCP server for Codex agents.
 # Offline brief — works without hub connection
 cat .custodian-brief.md
 
-# Active workstreams for this domain
+# Active workplans for this domain
-curl -s "http://127.0.0.1:8000/workstreams/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \
+curl -s "http://127.0.0.1:8000/workplans/?topic_id=cee7bedf-2b48-46ef-8601-006474f2ad7a&status=active" \
   | python3 -m json.tool
 
 # Check inbox
@@ -51,12 +57,12 @@ curl -s -X POST http://127.0.0.1:8000/progress/ \
     "summary": "what was done",
     "event_type": "note",
     "author": "codex",
-    "workstream_id": "<uuid>",
+    "workplan_id": "<uuid>",
     "task_id": "<uuid>"
   }'
 ```
 
-Omit `workstream_id` / `task_id` when not applicable.
+Omit `workplan_id` / `task_id` when not applicable.
 
 ### Update task status
 
@@ -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` — domain goal and open workplans (offline-safe)
 2. Check inbox: `GET /messages/?to_agent=net-kingdom&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,12 @@ 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
+3. After workplan file changes, run:
-   `~/state-hub`:
    ```bash
-   make fix-consistency REPO=net-kingdom
+   statehub fix-consistency
    ```
-   This syncs task status from files into the hub DB.
+   Coding agents should run this directly; ask the operator only if the CLI or
+   State Hub API is unavailable. This syncs task status from files into the hub DB.
 
 ---
 
@@ -123,7 +129,7 @@ Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run wa
 | Agent runtime | How to orient |
 | --- | --- |
 | **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=net-kingdom` is for coordination, not secret vending |
-| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **still** use `warden route` for credential ownership |
+| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **still** use `warden route` for credential ownership |
 | **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
 
 ### Quick routing table