diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..2bfb0e03
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,34 @@
+# Markitect — Claude Code Instructions
+
+## Custodian State Hub Integration
+
+This project is tracked as the **markitect** domain in the Custodian State Hub.
+Hub topic ID: `5571d954-0d30-4950-980d-7bcaaad8e3e2`
+
+### Session Protocol
+
+**At the start of every session:**
+Call `get_state_summary()` via the `state-hub` MCP tool to orient yourself.
+If the hub is not reachable, start it: `cd ~/the-custodian/state-hub && make api`
+
+**At the end of every session:**
+Call `add_progress_event()` with at minimum:
+- `topic_id`: `5571d954-0d30-4950-980d-7bcaaad8e3e2`
+- `summary`: what was accomplished or left in-flight
+- `event_type`: `note` for routine updates, `milestone` for completions, `blocker` for blockers
+
+### Available State-Hub MCP Tools
+
+- `get_state_summary()` — full cross-domain overview
+- `add_progress_event(summary, topic_id, event_type, detail)` — log progress
+- `create_workstream(topic_id, title, ...)` — create a new workstream
+- `create_task(workstream_id, title, ...)` — create a task under a workstream
+- `update_task_status(task_id, status)` — move task through lifecycle
+- `record_decision(title, decision_type, topic_id, ...)` — log decisions
+- `resolve_decision(decision_id, rationale, decided_by)` — close a decision
+
+### If the MCP Server is Not Available
+
+The state-hub MCP server (`state-hub`) is registered at user scope in `~/.claude.json`.
+It requires the API to be running at `http://127.0.0.1:8000`.
+Fallback: use `curl` directly against the REST API — see `/docs` at the hub URL.