docs: add SCOPE.md for rapid orientation

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

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)