chore: register repo with Custodian State Hub + add CLAUDE.md

- Register marki-docx under markitect domain (repo ID 75d31180)
- Add CLAUDE.md with full session protocol, workplan convention (ADR-001),
  First Session Protocol, and contribution/SBOM tracking instructions
- Ignore .claude/ local state directory

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -1,3 +1,6 @@
+# Claude Code local state
+.claude/
+
 # ---> Python
 # Byte-compiled / optimized / DLL files
 __pycache__/

CLAUDE.md

@@ -0,0 +1,209 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working in this repository.
+
+## What This Repo Is
+
+**marki-docx** (markidocx) is a Markdown ↔ DOCX round-trip editing system.
+
+- Markdown is the **canonical structured source**
+- Word documents are **editorial projections** — generated for review, not authoritative
+- Conversion must be deterministic, inspectable, and semantically stable across cycles
+- Interfaces: CLI, REST service, MCP tools
+
+Key artefacts already in this repo:
+- `specs/MarkiDocxProductRequirementsDocument_v0.1.md` — PRD (implementation-independent)
+- `specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md` — FRS (binding functional contract)
+- `specs/MarkiDocxUseCaseCatalog_v0.1.md` — use case catalogue
+
+---
+
+## Custodian State Hub Integration
+
+This project is tracked as the **markitect** domain in the Custodian State Hub.
+
+| Key | Value |
+|-----|-------|
+| Domain | `markitect` |
+| Topic ID | `5571d954-0d30-4950-980d-7bcaaad8e3e2` |
+| Repo ID | `75d31180-acf5-4d47-aea8-2a5b1e71e6a9` |
+| Repo slug | `marki-docx` |
+
+Hub API: `http://127.0.0.1:8000` — if offline: `cd ~/the-custodian/state-hub && make api`
+
+---
+
+## Session Protocol (MANDATORY)
+
+### On session start — before writing any response text:
+
+**Step 1 — Orient via State Hub**
+```
+get_domain_summary("markitect")
+```
+Note: active workstreams, blocking decisions, recent progress, SBOM status.
+
+**Step 2 — Scan local workplans**
+
+```bash
+ls workplans/   # or Glob(pattern="workplans/**/*.md")
+```
+For each file with `status: active`, extract pending `todo` / `in_progress` tasks.
+
+**Step 3 — Present orientation**
+
+Output a concise brief:
+1. **Active workstreams** for `markitect` domain — title, task counts, blocking decisions
+2. **Pending tasks** — from local `workplans/` + state hub tasks with `[repo:marki-docx]`
+3. **Goal guidance** — if `goal_guidance` is present in the summary:
+   - `needs_workplan`: surface as top suggested action — create workplan file + workstream
+   - `alignment_warnings`: name the misaligned workstream and flag it
+4. **Suggested next action** — highest-priority open item
+5. **SBOM status** — `last_sbom_at` set? If not, note it as a gap
+
+If no workstreams exist → follow **First Session Protocol** below.
+
+### During work:
+- `record_decision()` — any decision affecting direction or dependencies
+- `add_progress_event()` — milestones, blockers, insights
+- `resolve_decision()` — once a decision is made
+
+### On session end:
+```python
+add_progress_event(
+    summary="<what was accomplished or decided>",
+    event_type="note|milestone|blocker",
+    topic_id="5571d954-0d30-4950-980d-7bcaaad8e3e2",
+    workstream_id="<id if applicable>"
+)
+```
+
+> **Design boundary:** The State Hub is a *read model*. Two write operations are
+> permanently sanctioned: **Resolving Decisions** and **Suggesting Next Steps**.
+> Bootstrap tools (`create_workstream`, `create_task`) are First Session Protocol only.
+> Work items originate as files in this repo (ADR-001), not in the hub alone.
+
+---
+
+## Repo Boundary Rule
+
+This agent is responsible for files **in this repo only**.
+
+- Do **not** write files or commit in any other repository
+- Work identified for another repo → create a state hub task with `[repo:<slug>]` in the title
+- Work identified for an upstream package → create a contribution artefact in `contrib/`
+
+---
+
+## First Session Protocol
+
+Triggered when `get_domain_summary("markitect")` shows **no workstreams** linked to `marki-docx`.
+
+**Step 1 — Read the specs**
+- `specs/MarkiDocxProductRequirementsDocument_v0.1.md`
+- `specs/MarkiDocxFunctionalRequirementsSpecification_v0.2.md`
+- `specs/MarkiDocxUseCaseCatalog_v0.1.md`
+- Scan the repo root for any existing code or further docs
+
+**Step 2 — Survey the canon**
+- `~/the-custodian/canon/projects/markitect/project_charter_v0.1.md`
+- `~/the-custodian/canon/projects/markitect/roadmap_v0.1.md`
+
+**Step 3 — Propose workstreams to Bernd**
+Propose 1–3 workstreams — coherent strands of work lasting weeks to months, anchored
+to a roadmap phase. **Wait for approval before creating anything.**
+
+**Step 4 — Create workplan file first, then DB record (ADR-001)**
+```
+workplans/MRKD-WP-0001-<slug>.md   ← write this first
+```
+Then register:
+```python
+create_workstream(
+    topic_id="5571d954-0d30-4950-980d-7bcaaad8e3e2",
+    title="...", owner="marki-docx", description="..."
+)
+create_task(workstream_id="<id>", title="...", priority="high|medium|low")
+```
+
+**Step 5 — Record the setup**
+```python
+add_progress_event(
+    summary="First session: structured marki-docx work into N workstreams, M tasks",
+    event_type="milestone",
+    topic_id="5571d954-0d30-4950-980d-7bcaaad8e3e2",
+    detail={"workstreams": [...], "tasks_created": M}
+)
+```
+
+---
+
+## Workplan Convention (ADR-001)
+
+Work items MUST originate as files in this repo before being registered in the hub.
+
+**File location:** `workplans/MRKD-WP-NNNN-<slug>.md`
+
+**Required frontmatter:**
+```yaml
+---
+id: MRKD-WP-NNNN
+type: workplan
+domain: markitect
+repo: marki-docx
+status: active|done|paused
+state_hub_workstream_id: <uuid>
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+**Task blocks (embedded in the workplan file):**
+```markdown
+## Task Title
+​```task
+id: MRKD-WP-NNNN-T01
+status: todo
+priority: high
+state_hub_task_id: <uuid>
+​```
+```
+
+After writing or modifying workplan files, run:
+```bash
+cd ~/the-custodian/state-hub && make fix-consistency REPO=marki-docx
+```
+This syncs task blocks → DB. Without it, the dashboard shows 0 progress.
+
+---
+
+## Contribution Tracking
+
+Track upstream contributions in `contrib/`:
+```
+contrib/
+  bug-reports/       # br-YYYY-MM-DD--org--repo--slug.md
+  feature-requests/  # fr-YYYY-MM-DD--org--repo--slug.md
+  extension-points/  # EP-MRKD-NNN--org--repo--slug.md
+  upstream-prs/      # upr-YYYY-MM-DD--org--repo--slug.md
+```
+
+Templates: `~/the-custodian/canon/standards/contrib-templates/`
+
+---
+
+## SBOM
+
+After updating dependencies:
+```bash
+cd ~/the-custodian/state-hub
+make ingest-sbom REPO=marki-docx SCAN=1 REPO_PATH=/home/worsch/marki-docx
+```
+
+---
+
+## Quick Reference
+
+- MCP tool reference: `~/the-custodian/state-hub/mcp_server/TOOLS.md`
+- ADR-001 (workplan convention): `~/the-custodian/canon/architecture/adr-001-workplans-as-repo-artefacts.md`
+- Contribution convention: `~/the-custodian/canon/standards/contribution-convention_v0.1.md`