marki-docx/SCOPE.md

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)