diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..9e73eef --- /dev/null +++ b/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)