generated from coulomb/repo-seed
97 lines
4.2 KiB
Markdown
97 lines
4.2 KiB
Markdown
# 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)
|