docs: replace placeholder README with full markidocx README

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

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)