# 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)