From 66783790e5076c68c5568066920374cd094674d4 Mon Sep 17 00:00:00 2001
From: Bernd Worsch <bernd.worsch@gmail.com>
Date: Wed, 18 Mar 2026 17:39:58 +0000
Subject: [PATCH] docs: replace placeholder README with full markidocx README

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 183 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 181 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index fcd7b8f..2b31ee0 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,182 @@
-# repo-seed
+# markidocx
 
-A git repository template to bootstrap coulomb projects from.
\ No newline at end of file
+**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).