# State Hub MCP — Tool Reference Card

Quick reference for all 12 tools and 5 resources. Read this instead of `server.py`.

## Query Tools (read-only)

| Tool | Key Args | When to use |
|------|----------|-------------|
| `get_state_summary()` | — | **Session start.** Full snapshot: totals, blocking decisions, blocked tasks, open workstreams, last 20 events. |
| `get_topic(slug)` | `slug`: e.g. `"markitect"` | Deep-dive on one topic + its workstreams + recent events. |
| `list_blocked_tasks(workstream_id?)` | optional filter | Surface all impediments, optionally scoped to one workstream. |
| `list_pending_decisions(topic_id?)` | optional filter | Decisions holding up work, sorted by deadline. |
| `get_recent_progress(limit, since?)` | `limit` default 20; `since` ISO datetime | Reconstruct recent session history. |

## Mutate Tools (each auto-emits a progress_event)

| Tool | Key Args | Notes |
|------|----------|-------|
| `create_workstream(topic_id, title, ...)` | `slug?` (auto-generated); `owner?`; `description?`; `due_date?` | Creates workstream under a topic. Use `get_state_summary()` to find topic IDs. |
| `create_task(workstream_id, title, ...)` | `priority`: low/medium/high/critical; `assignee?`; `due_date?` | Creates task under a workstream. |
| `update_task_status(task_id, status, ...)` | `status`: todo/in_progress/blocked/done/cancelled; `blocking_reason` required when blocked | |
| `record_decision(title, ...)` | `decision_type`: made/pending; `topic_id?`; `workstream_id?`; `deadline?` | Financial/legal + pending → auto-escalated per constitution §4. At least one of topic_id/workstream_id required. |
| `resolve_decision(decision_id, rationale, decided_by)` | all required | Marks decision resolved and records who decided. |
| `add_progress_event(summary, ...)` | `event_type`: note/milestone/blocker/insight; `topic_id?`; `workstream_id?`; `task_id?`; `detail?` | Append-only log entry. **Use at session end.** |
| `update_workstream_status(workstream_id, status)` | `status`: active/blocked/completed/archived | |

## Resources (URI-addressable, read-only)

| URI | Returns |
|-----|---------|
| `state://summary` | Full StateSummary JSON |
| `state://topics` | Active topics list |
| `state://workstreams/{topic_slug}` | Workstreams for a topic (by slug) |
| `state://decisions/blocking` | All pending decisions |
| `state://tasks/blocked` | All blocked tasks |

## Domain Slugs

`custodian` · `railiance` · `markitect` · `coulomb-social` · `personhood` · `foerster-capabilities`

## Common Patterns

```python
# New workstream:
create_workstream(topic_id="<uuid>", title="My Workstream", owner="me")

# New task:
create_task(workstream_id="<uuid>", title="Do the thing", priority="high")

# Session start ritual:
get_state_summary()

# Session end ritual:
add_progress_event(
    summary="...",
    event_type="note",          # or milestone / insight / blocker
    topic_id="<uuid>",
    workstream_id="<uuid>",     # optional
    detail={"key": "value"},    # optional structured data
)
```