chore(consistency): sync task status from DB [auto]

Updated by fix-consistency on 2026-07-03:
  - update .custodian-brief.md for marki-docx

.custodian-brief.md

@@ -0,0 +1,18 @@
+<!-- custodian-brief: generated by fix-consistency — do not edit manually -->
+# Custodian Brief — marki-docx
+
+**Domain:** communication  
+**Last synced:** 2026-07-03 16:48 UTC  
+**State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
+
+## Active Workstreams
+
+*(none — repo may need first-session setup)*
+
+---
+## MCP Orientation (when available)
+
+If the state-hub MCP server is reachable, call:
+`get_domain_summary("communication")`
+This provides richer cross-domain context.
+If the MCP call fails, use this file as your orientation source.

.repo-classification.yaml

@@ -0,0 +1,34 @@
+repo_classification:
+  standard: Repo Classification Standard
+  version: "1.0"
+  classified_at: "2026-06-22"
+  classified_by: human
+
+  category: product
+  domain: communication
+  secondary_domains:
+    - infotech
+
+  capability_tags:
+    - knowledge
+    - documentation
+    - product-development
+    - traceability
+    - automation
+
+  business_stake:
+    - product
+    - technology
+    - execution
+    - intelligence
+
+  business_mechanics:
+    - intention
+    - coordination
+    - operation
+    - adaptation
+
+  notes: >
+    Markdown↔DOCX round-trip authoring for collaborators who edit in Word while
+    Markdown stays canonical. Communication primary (editorial/review audience);
+    infotech secondary (developer tooling surface: CLI, REST, MCP).

AGENTS.md

@@ -0,0 +1,219 @@
+# marki-docx — Agent Instructions
+
+## Repo Identity
+
+**Purpose:** Markdown ↔ DOCX round-trip editing system. CLI + REST + MCP interfaces for controlled editorial workflows where Markdown is canonical and Word is the editorial projection.
+
+**Domain:** communication
+**Repo slug:** marki-docx
+**Topic ID:** `36c7421b-c537-4723-bf75-42a3ebc6a1dc`
+**Workplan prefix:** `MRKD-WP-`
+
+---
+
+## State Hub Integration
+
+The Custodian State Hub tracks work across all domains. Interact via HTTP REST —
+there is no MCP server for Codex agents.
+
+| Context | URL |
+|---------|-----|
+| Local workstation | `http://127.0.0.1:8000` |
+| Remote via tunnel | `http://127.0.0.1:18000` |
+
+### Orient at session start
+
+```bash
+# Offline brief — works without hub connection
+cat .custodian-brief.md
+
+# Active workstreams for this domain
+curl -s "http://127.0.0.1:8000/workstreams/?topic_id=36c7421b-c537-4723-bf75-42a3ebc6a1dc&status=active" \
+  | python3 -m json.tool
+
+# Check inbox
+curl -s "http://127.0.0.1:8000/messages/?to_agent=marki-docx&unread_only=true" \
+  | python3 -m json.tool
+```
+
+Mark a message read:
+```bash
+curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
+  -H "Content-Type: application/json" -d '{}'
+```
+
+### Log progress (required at session close)
+
+```bash
+curl -s -X POST http://127.0.0.1:8000/progress/ \
+  -H "Content-Type: application/json" \
+  -d '{
+    "summary": "what was done",
+    "event_type": "note",
+    "author": "codex",
+    "workstream_id": "<uuid>",
+    "task_id": "<uuid>"
+  }'
+```
+
+Omit `workstream_id` / `task_id` when not applicable.
+
+### Update task status
+
+```bash
+curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
+  -H "Content-Type: application/json" \
+  -d '{"status": "progress"}'
+# values: wait | todo | progress | done | cancel
+```
+
+### Flag a task for human review
+
+```bash
+curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
+  -H "Content-Type: application/json" \
+  -d '{"needs_human": true, "intervention_note": "reason"}'
+```
+
+---
+
+## Session Protocol
+
+**Start:**
+1. `cat .custodian-brief.md` — domain goal and open workstreams (offline-safe)
+2. Check inbox: `GET /messages/?to_agent=marki-docx&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`
+
+**During work:**
+- Update task statuses in workplan files as tasks progress
+- Record significant decisions via `POST /decisions/`
+
+**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`:
+   ```bash
+   make fix-consistency REPO=marki-docx
+   ```
+   This syncs task status from files into the hub DB.
+
+---
+
+## Credential and access routing
+
+**Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
+for inference. Run this check **before** requesting secrets, API keys, SSH access,
+login tokens, or database passwords — in any repo, not only `ops-warden`.
+
+ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
+other credential need belongs to another subsystem. **Do not** message
+`ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
+
+### Lookup (do this first)
+
+```bash
+warden route find "<describe your need>" --json
+warden route show <catalog-id> --json
+```
+
+Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
+
+| Agent runtime | How to orient |
+| --- | --- |
+| **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=marki-docx` is for coordination, not secret vending |
+| **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workstreams; **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
+
+| I need… | Owner | ops-warden executes? |
+| --- | --- | --- |
+| SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
+| API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
+| Login / OIDC / MFA | key-cape / Keycloak | No — route only |
+| Authorization decision | flex-auth | No — route only |
+| activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
+| SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
+
+### Anti-patterns (do not do these)
+
+- `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
+- Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
+- Pasting secrets into Git, State Hub, workplans, logs, or chat
+
+### Other capabilities (reuse-surface)
+
+Non-credential capabilities are usually discovered through **reuse-surface** federation
+(`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
+every repo's agent instructions because it is high-frequency, high-risk, and easy to
+get wrong.
+
+**Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
+
+<!-- REPO-AGENTS-EXTENSIONS -->
+<!-- Append repo-specific agent instructions below this marker.
+     The state-hub template sync preserves content after this line. -->
+
+---
+
+## Workplan Convention (ADR-001)
+
+Work items originate as files in this repo — not in the hub. The hub is a
+read/cache/index layer that rebuilds from files.
+
+**File location:** `workplans/MARKI-WP-NNNN-<slug>.md`
+
+**Archived location:** finished workplans may move to
+`workplans/archived/YYMMDD-MARKI-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
+the completion/archive date; the frontmatter `id` does not change.
+
+**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
+`workplans/ADHOC-YYYY-MM-DD.md` with task ids `ADHOC-YYYY-MM-DD-T01`, etc. Use
+this only for low-risk work completed directly; create a normal workplan for
+anything needing analysis, design, approval, dependencies, or multiple phases.
+
+**Frontmatter:**
+
+```yaml
+---
+id: MARKI-WP-NNNN
+type: workplan
+title: "..."
+domain: communication
+repo: marki-docx
+status: proposed | ready | active | blocked | backlog | finished | archived
+owner: codex
+topic_slug: ...
+created: "YYYY-MM-DD"
+updated: "YYYY-MM-DD"
+state_hub_workstream_id: "<uuid>"   # written by fix-consistency — do not edit
+---
+```
+
+Use `proposed` for a new draft, `ready` after review against current repo
+state, and `finished` after implementation. `stalled` and `needs_review` are
+derived health labels, not frontmatter statuses.
+
+**Task block format** (one per `##` section):
+
+```
+## Task Title
+
+` ` `task
+id: MARKI-WP-NNNN-T01
+status: wait | todo | progress | done | cancel
+priority: high | medium | low
+state_hub_task_id: "<uuid>"         # written by fix-consistency — do not edit
+` ` `
+
+Task description text.
+```
+
+Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
+
+To create a new workplan:
+1. Write the file following the format above
+2. Notify the custodian operator to run `make fix-consistency REPO=marki-docx`
+   (or send a message to the hub agent via `POST /messages/`)

CLAUDE.md

@@ -1,324 +1,12 @@
-# CLAUDE.md
+# marki-docx — Claude Code Instructions
-
+
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+@SCOPE.md
-
+@.claude/rules/repo-identity.md
-## What This Repo Is
+@.claude/rules/session-protocol.md
-
+@.claude/rules/first-session.md
-**marki-docx** (markidocx) is a Markdown ↔ DOCX round-trip editing system.
+@.claude/rules/workplan-convention.md
-
+@.claude/rules/stack-and-commands.md
-- Markdown is the **canonical structured source**
+@.claude/rules/architecture.md
-- Word documents are **editorial projections** — generated for review, not authoritative
+@.claude/rules/repo-boundary.md
-- Conversion must be deterministic, inspectable, and semantically stable across cycles
+@.claude/rules/credential-routing.md
-- Interfaces: CLI, REST service, MCP tools
+@.claude/rules/agents.md
-
-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
-
----
-
-## Planned Architecture
-
-markidocx is a **conversion pipeline** with three delivery interfaces over a shared functional core.
-
-### Interfaces
-| Interface | Purpose |
-|-----------|---------|
-| CLI | Local document workflows (`markidocx build`, `import`, `validate`, `compare`) |
-| REST service | Automation / pipeline integration |
-| MCP tools | Agent-accessible operations (same functional surface as CLI/REST) |
-
-All three interfaces expose the same functional model — no interface-specific logic should live outside its adapter layer.
-
-### Core Functional Domains (from FRS)
-| FR group | Domain |
-|----------|--------|
-| FR-100 | Project & manifest management |
-| FR-200 | Build / export (Markdown → DOCX) |
-| FR-300 | Import / round-trip (DOCX → Markdown) |
-| FR-400 | Multi-file composition & redistribution |
-| FR-500 | Feature-level enforcement (LEVEL1 / LEVEL3) |
-| FR-600 | Template & style family management |
-| FR-700 | Validation & drift analysis |
-| FR-1100 | Test & regression |
-| FR-1300 | Composite workflow orchestration |
-| FR-1400 | Evidence & report assembly |
-
-### Key Concepts
-- **Project manifest** — declares source files, feature level, and template/style family; drives all operations
-- **Feature levels** — LEVEL1 (headings, lists, tables, footnotes, images, links); LEVEL3 adds cross-refs, numbered figures, auto-diagrams, bibliography
-- **Document families** — three built-in: `article`, `book`, `website`; extensible via registration
-- **Source mapping** — multi-file imports must redistribute content back to origin files; fallback produces a merged single file
-- **Drift detection** — structural diff between original Markdown and re-imported result; reported as inspectable evidence
-
-### Round-trip data flow
-```
-manifest + Markdown sources
-    ↓  FR-100 (resolve project)
-    ↓  FR-200 (compose + export → DOCX)
-     [Word editorial review]
-    ↓  FR-300 (import DOCX → Markdown)
-    ↓  FR-400 (redistribute to source files)
-    ↓  FR-700 (validate + drift report)
-evidence artefacts
-```
-
-### Implementation State
-
-| Module | Status | FR coverage |
-|--------|--------|-------------|
-| `cli.py` | implemented — all commands wired (`build`, `import`, `compare`, `validate`, `serve`, `workflow`, `mcp`, `template`) | all |
-| `manifest.py` | implemented | FR-100 |
-| `builder.py` | implemented — LEVEL1 + LEVEL3 (xrefs, figures, diagrams, citations) | FR-200, FR-531–539 |
-| `importer.py` | implemented — LEVEL1 + LEVEL3 round-trip | FR-300/400, FR-531–536 |
-| `differ.py` | implemented — LEVEL1 + LEVEL3 drift detection | FR-700, FR-540–542 |
-| `templates.py` | implemented | FR-600 |
-| `evidence.py` | implemented | FR-1400 |
-| `workflows.py` | implemented (`single-file-roundtrip`, `multi-file-roundtrip`, `release-regression`, `family-switch-build`) | FR-1300 |
-| `rest.py` | implemented — FastAPI app, all endpoints; structured warning records | FR-900, FR-1208 |
-| `mcp_server.py` | implemented — FastMCP server, all tools and resources; structured warnings | FR-1000, FR-1208 |
-| `errors.py` | implemented — `WarningRecord`, `FailureRecord`, `OutputState` | FR-1201–1210 |
-| `level3.py` | implemented — LEVEL3 support detection, capability disclosure | FR-537–539 |
-| `xref.py` | implemented — cross-reference round-trip helpers | FR-531, FR-540 |
-| `figures.py` | implemented — numbered figure round-trip helpers | FR-532, FR-541 |
-| `diagrams.py` | implemented — auto-diagram source-only + renderer path | FR-533, FR-534 |
-| `bibliography.py` | implemented — citation and references section round-trip | FR-535, FR-536, FR-542 |
-
-`tests/conftest.py` provides shared fixtures. WP-0001, WP-0002, and WP-0003 complete — 259 tests passing. Full LEVEL1 + LEVEL3 feature coverage. All interfaces (CLI, REST, MCP) implemented and parity-tested.
-
----
-
-## Development Commands
-
-```bash
-# Install in editable mode
-pip install -e ".[dev]"
-
-# Run tests
-pytest
-
-# Run a single test file
-pytest tests/path/to/test_file.py
-
-# Lint
-ruff check .
-
-# Type-check
-mypy src/
-
-# Start REST service (dev mode)
-markidocx serve --dev
-
-# CLI: build a document project
-markidocx build <manifest.yaml>
-
-# CLI: import an edited DOCX
-markidocx import <manifest.yaml> <edited.docx>
-
-# CLI: compare baseline vs re-import
-markidocx compare <manifest.yaml> <edited.docx>
-
-# CLI: run end-to-end regression
-markidocx test
-```
-
----
-
-## 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:18001` — 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
-
-Re-run the SBOM after any dependency change (new package added/removed/upgraded in `pyproject.toml`).
-
-The ops-bridge `ingest_sbom_tool` requires the lockfile to be accessible from the bridge machine.
-Use a `requirements.txt` generated via:
-```bash
-pip list --format=freeze | grep -E "^(python-docx|PyYAML|typer|rich|mistune|fastapi|uvicorn|mcp|pytest|pytest-cov|ruff|mypy|types-PyYAML|httpx|pydantic|click|starlette|anyio|httpcore|certifi|h11|sniffio|idna)=" | sort > requirements.txt
-```
-
-Then either:
-- Run locally if API is accessible: `cd ~/the-custodian/state-hub && make ingest-sbom REPO=marki-docx SCAN=1 REPO_PATH=/home/tegwick/marki-docx`
-- Or via MCP `ingest_sbom_tool` once `host_paths` mapping is configured for `marki-docx` in the custodian
-
----
-
-## 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`
-- Release process: `docs/release-process.md`
-- Changelog: `CHANGELOG.md`

README.md

@@ -1,3 +1,182 @@
-# repo-seed
+# markidocx
 
-A git repository template to bootstrap coulomb projects from.
+**Markdown ↔ DOCX round-trip editing system.**
+
+Markdown is the canonical structured source. Word documents are editorial projections — generated for review, edited by collaborators, then imported back with changes redistributed to the original Markdown files.
+
+---
+
+## Overview
+
+markidocx solves a common authoring problem: you want to write and version-control content in Markdown, but collaborators review and edit in Word. Rather than treating the DOCX as the source of truth, markidocx keeps Markdown authoritative and makes the round-trip deterministic and inspectable.
+
+```
+manifest + Markdown sources
+    ↓  resolve project (FR-100)
+    ↓  compose + export → DOCX (FR-200)
+     [Word editorial review]
+    ↓  import DOCX → Markdown (FR-300)
+    ↓  redistribute to source files (FR-400)
+    ↓  validate + drift report (FR-700)
+evidence artefacts
+```
+
+---
+
+## Features
+
+- **Build** — compose multi-file Markdown projects into a styled DOCX
+- **Import** — parse an edited DOCX back to Markdown, redistributing changes to source files
+- **Validate** — structural drift detection between original and re-imported content
+- **LEVEL1** — headings, lists, tables, footnotes, images, links
+- **LEVEL3** — cross-references, numbered figures, auto-diagrams (Mermaid / Graphviz / PlantUML), bibliography
+- **Document families** — `article`, `book`, `website`; extensible via template registration
+- **Three interfaces** — CLI, REST service, MCP tools over a shared functional core
+
+---
+
+## Installation
+
+Requires Python 3.11+.
+
+```bash
+pip install markidocx
+```
+
+For development:
+
+```bash
+git clone https://github.com/tegwick/marki-docx
+cd marki-docx
+pip install -e ".[dev]"
+```
+
+Optional diagram renderer extras:
+
+```bash
+pip install "markidocx[diagram-mermaid]"
+pip install "markidocx[diagram-graphviz]"
+```
+
+---
+
+## Quick Start
+
+### 1. Create a manifest
+
+```yaml
+# project.yaml
+project:
+  name: My Document
+  feature_level: LEVEL1
+  family: article
+
+sources:
+  - intro.md
+  - body.md
+  - conclusion.md
+
+output:
+  docx: dist/my-document.docx
+```
+
+### 2. Build a DOCX
+
+```bash
+markidocx build project.yaml
+```
+
+### 3. Import an edited DOCX
+
+```bash
+markidocx import project.yaml dist/my-document-reviewed.docx
+```
+
+### 4. Check for drift
+
+```bash
+markidocx compare project.yaml dist/my-document-reviewed.docx
+```
+
+---
+
+## CLI Reference
+
+```
+markidocx build <manifest>       Build DOCX from Markdown sources
+markidocx import <manifest> <docx>  Import edited DOCX → Markdown
+markidocx compare <manifest> <docx> Drift analysis (baseline vs re-import)
+markidocx validate <manifest>    Validate manifest file
+markidocx workflow <name>        Run a named end-to-end workflow
+markidocx serve                  Start REST service
+markidocx mcp                    Start MCP server
+markidocx template list          List available template families
+```
+
+All commands accept `--json` for machine-readable output.
+
+---
+
+## REST Service
+
+```bash
+markidocx serve --dev
+```
+
+API is available at `http://localhost:8000`. Interactive docs at `/docs`.
+
+---
+
+## MCP Tools
+
+markidocx exposes its full functional surface as MCP tools, making it accessible to AI agents and automation pipelines.
+
+```bash
+markidocx mcp
+```
+
+---
+
+## Development
+
+```bash
+# Run tests
+pytest
+
+# Lint
+ruff check .
+
+# Type-check
+mypy src/
+```
+
+---
+
+## Architecture
+
+All three interfaces (CLI, REST, MCP) are thin adapters over a shared functional core. No interface-specific logic lives outside its adapter layer.
+
+| Module | Responsibility |
+|---|---|
+| `manifest.py` | Project manifest loading and validation |
+| `builder.py` | Markdown → DOCX composition |
+| `importer.py` | DOCX → Markdown round-trip |
+| `differ.py` | Structural drift detection |
+| `templates.py` | Template and style family management |
+| `workflows.py` | Composite end-to-end workflows |
+| `evidence.py` | Evidence and report assembly |
+| `errors.py` | Structured warning and failure records |
+| `level3.py` | LEVEL3 feature detection and disclosure |
+| `xref.py` | Cross-reference helpers |
+| `figures.py` | Numbered figure helpers |
+| `diagrams.py` | Auto-diagram rendering |
+| `bibliography.py` | Citation and references section |
+| `rest.py` | FastAPI REST interface |
+| `mcp_server.py` | FastMCP tool interface |
+| `cli.py` | Typer CLI interface |
+
+---
+
+## License
+
+See [LICENSE](LICENSE).

SCOPE.md

@@ -0,0 +1,96 @@
+# SCOPE
+
+> This file helps you quickly understand what this repository is about,
+> when it is relevant, and when it is not.
+> It is intentionally lightweight and may be incomplete.
+
+---
+
+## One-liner
+
+Markdown ↔ DOCX round-trip editing system — keeps Markdown as the canonical source while generating Word documents for editorial review and re-importing collaborator edits back into the original Markdown files.
+
+---
+
+## Core Idea
+
+Collaborators review and edit in Word; authors version-control in Markdown. markidocx makes this round-trip deterministic and inspectable: compose multi-file Markdown projects into styled DOCX, distribute Word edits back to source files, and detect structural drift. The functional core is identical across three interfaces: CLI, REST service, and MCP tools.
+
+---
+
+## In Scope
+
+- Build (compose Markdown → styled DOCX): multi-file projects via manifest, LEVEL1 + LEVEL3 features
+- Import (DOCX → Markdown): parse edited Word document, redistribute changes to source files
+- Validate / drift analysis: detect structural divergence between original and re-imported content
+- LEVEL1 features: headings, lists, tables, footnotes, images, links
+- LEVEL3 features: cross-references, numbered figures, auto-diagrams (Mermaid/Graphviz/PlantUML), bibliography
+- Document families: `article`, `book`, `website`; extensible via template registration
+- Three delivery interfaces over a shared functional core: CLI, REST service, MCP tools
+
+---
+
+## Out of Scope
+
+- Making Word the source of truth (Markdown is always canonical)
+- General-purpose document editor or word processor
+- Real-time collaborative editing
+- Non-Markdown source formats (PDF, HTML, etc.)
+- Storing or managing secrets/credentials
+
+---
+
+## Relevant When
+
+- Markdown-authored content needs to be reviewed or approved in Word by non-technical collaborators
+- Need deterministic, versionable Markdown ↔ DOCX conversion as part of a publishing workflow
+- Building automation pipelines that consume or produce DOCX from structured Markdown sources
+- Agent-accessible document operations via MCP tools
+
+---
+
+## Not Relevant When
+
+- All collaborators work in Markdown directly (no DOCX round-trip needed)
+- DOCX is the canonical source (markidocx makes Markdown canonical)
+- Simple single-file, no-iteration document production (overkill)
+
+---
+
+## Current State
+
+- Status: active (v0.1.0, actively developed)
+- Implementation: substantial — all 7 workplans in progress; src/ has full module set (builder, importer, manifest, CLI, REST, MCP server, level3, xref, diagrams, evidence, workflows)
+- Stability: evolving — functional core maturing; interface completeness and packaging in progress
+- Usage: personal/internal; on tegwick machine (92.205.130.254)
+
+---
+
+## How It Fits
+
+- Upstream dependencies: python-docx (DOCX manipulation), mistune (Markdown parsing), typer (CLI), FastAPI (REST), mcp (MCP server), optional diagram renderers (Mermaid/Graphviz/PlantUML)
+- Downstream consumers: Custodian ecosystem — markidocx is tracked under the `markitect` domain; supports producing canon-release documents from Markdown artifacts managed by markitect_project
+- Often used with: markitect_project (knowledge artifact management), the-custodian (state tracking)
+
+---
+
+## Terminology
+
+- Preferred terms: manifest, build, import, redistribute, drift, LEVEL1, LEVEL3, document family, round-trip
+- Also known as: markidocx (package name), marki-docx (repo name)
+- Potentially confusing terms: "import" = DOCX → Markdown (not Python import); "build" = Markdown → DOCX (not compilation); "redistribute" = re-apply Word edits to original source files
+
+---
+
+## Related / Overlapping Repositories
+
+- `markitect_project` — manages structured Markdown knowledge artifacts; markidocx handles the DOCX export/import workflow for those artifacts
+- `the-custodian` — tracks marki-docx under the markitect domain in the State Hub
+
+---
+
+## Getting Oriented
+
+- Start with: `README.md` (overview, round-trip diagram), `CLAUDE.md` (architecture, FR groups, key concepts)
+- Key files / directories: `specs/` (PRD + FRS + use case catalogue), `src/markidocx/` (functional core), `workplans/` (7 workplans MRKD-WP-0001 through -0007)
+- Entry points: `markidocx --help` (CLI); `src/markidocx/rest.py` (REST); `src/markidocx/mcp_server.py` (MCP)

workplans/MRKD-WP-0001-foundation-level1.md

@@ -1,7 +1,7 @@
 ---
 id: MRKD-WP-0001
 type: workplan
-domain: markitect
+domain: communication
 repo: marki-docx
 status: done
 state_hub_workstream_id: de855681-7ce0-4ace-b283-ec61f7557066

workplans/MRKD-WP-0002-service-interfaces.md

@@ -1,7 +1,7 @@
 ---
 id: MRKD-WP-0002
 type: workplan
-domain: markitect
+domain: communication
 repo: marki-docx
 status: done
 state_hub_workstream_id: 6a7b5627-7593-4713-8e56-94c4ab3ff838

workplans/MRKD-WP-0003-level3-advanced-features.md

@@ -1,7 +1,7 @@
 ---
 id: MRKD-WP-0003
 type: workplan
-domain: markitect
+domain: communication
 repo: marki-docx
 status: done
 state_hub_workstream_id: b04fe706-6e4e-48a8-b6c1-194d9e308215

workplans/MRKD-WP-0004-stable-corpus-architecture.md

@@ -1,7 +1,7 @@
 ---
 id: MRKD-WP-0004
 type: workplan
-domain: markitect
+domain: communication
 repo: marki-docx
 status: done
 state_hub_workstream_id: 91d06c92-caa8-42fc-b6d4-82340f1bed4f

workplans/MRKD-WP-0005-diagram-renderer-integration.md

@@ -1,7 +1,7 @@
 ---
 id: MRKD-WP-0005
 type: workplan
-domain: markitect
+domain: communication
 repo: marki-docx
 status: done
 state_hub_workstream_id: 2ef47f11-d828-436d-8955-c58e13c50752

workplans/MRKD-WP-0006-packaging-distribution.md

@@ -1,7 +1,7 @@
 ---
 id: MRKD-WP-0006
 type: workplan
-domain: markitect
+domain: communication
 repo: marki-docx
 status: done
 state_hub_workstream_id: 7e255145-8d18-4f22-b1ca-31f02944b890

workplans/MRKD-WP-0007-interface-completeness-evidence.md

@@ -1,7 +1,7 @@
 ---
 id: MRKD-WP-0007
 type: workplan
-domain: markitect
+domain: communication
 repo: marki-docx
 status: done
 state_hub_workstream_id: 61701224-0813-4258-9308-025bcec41780