chore: workplan MRKD-WP-0001 + improved CLAUDE.md; document next steps

- workplans/MRKD-WP-0001-foundation-level1.md: 8-task workplan for
  Foundation & LEVEL1 Core (T01 scaffolding through T08 e2e harness)
- CLAUDE.md: added Planned Architecture section (interface table, FR
  domain map, key concepts, round-trip data flow) and Development
  Commands stubs derived from FRS v0.2
- problems/next-steps-2026-03-14.md: implementation guide for next
  session — task order, dep list, state-hub task UUIDs, quality gates

No code implemented yet; workstream registered in State Hub.

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

specs/MarkiDocxFunctionalRequirementsSpecification_v0.1.md

@@ -0,0 +1,737 @@
+# FRS
+
+*Functional Requirements Specification*
+
+# Functional Requirements Specification: markidocx
+
+## 1. Definition
+
+This Functional Requirements Specification defines the externally observable behaviors and required functions of **markidocx**, a system for controlled **Markdown ↔ DOCX round-trip editing**.
+
+The FRS specifies what markidocx must do from the perspective of users, external systems, and exposed interfaces. It defines required functions for:
+
+* document build and export
+* document import and reconstitution
+* multi-file composition
+* template and style management
+* feature-level document processing
+* validation and drift reporting
+* local CLI usage
+* REST-based service interaction
+* MCP-based tool interaction
+* end-to-end regression execution
+
+This FRS is derived from the markidocx PRD and serves as the binding functional contract for implementation and acceptance.
+
+---
+
+## 2. Context
+
+markidocx is intended to support documentation workflows in which:
+
+* structured content is maintained in Markdown
+* editorial review is performed in Microsoft Word
+* document generation must be repeatable and inspectable
+* multiple stakeholders and systems interact with the same documentation assets
+
+The system acts as a functional bridge between:
+
+* canonical Markdown source documents
+* Word-based review artifacts
+* automated documentation pipelines
+* external tools and agents
+
+Functionally, the system must allow content to move between these contexts while preserving supported structure and surfacing any drift or ambiguity introduced during the process.
+
+---
+
+## 3. Core Concepts
+
+### 3.1 System Function
+
+A system function is a user-visible or interface-visible capability the system provides, such as building a DOCX artifact, importing an edited document, or validating a template registration.
+
+### 3.2 Externally Observable Behavior
+
+Externally observable behavior includes all results visible through the CLI, REST interface, MCP interface, output artifacts, reports, and return statuses.
+
+### 3.3 Requirement Statement
+
+Each requirement in this document is written as a declarative, testable statement describing required system behavior.
+
+### 3.4 Input–Output Relationship
+
+markidocx receives manifests, Markdown sources, templates, styles, DOCX files, and configuration inputs and produces artifacts, reports, validation outcomes, and structured metadata.
+
+### 3.5 Traceability
+
+The requirements in this FRS are intended to trace back to the markidocx PRD and forward into implementation, interface contracts, and validation suites.
+
+---
+
+## 4. Scope and Non-Scope
+
+### In Scope
+
+This FRS covers:
+
+* functional system behavior
+* user-facing and interface-facing commands and operations
+* supported document processing behavior
+* interface-level interactions through CLI, REST, and MCP
+* functional handling of templates, styles, manifests, and artifacts
+* conditions under which functions succeed, warn, or fail
+
+### Out of Scope
+
+This FRS does not define:
+
+* internal architecture
+* code organization
+* algorithms or parser strategies
+* storage implementation
+* UI layout
+* deployment topology
+* performance or security design except where behaviorally relevant
+
+---
+
+## 5. System Overview
+
+markidocx shall provide a functional workflow in which a user or external system can:
+
+1. define a document project using Markdown sources and a manifest
+2. compose one or more Markdown files into a document model
+3. export that document into DOCX using a selected template/style family
+4. import an edited DOCX back into Markdown form
+5. validate compatibility and structural integrity
+6. detect and report drift between baseline and re-imported forms
+7. manage template/style families
+8. access the same capabilities locally, via service calls, or through MCP tools
+9. run end-to-end tests using the latest stable markidocx documentation corpus
+
+---
+
+## 6. Functional Requirements Structure
+
+Requirements are grouped into the following domains:
+
+* FR-100 Project and manifest management
+* FR-200 Build and export
+* FR-300 Import and round-trip processing
+* FR-400 Multi-file document handling
+* FR-500 Feature level support
+* FR-600 Template and style management
+* FR-700 Validation and drift analysis
+* FR-800 CLI functions
+* FR-900 REST service functions
+* FR-1000 MCP functions
+* FR-1100 Test and regression functions
+* FR-1200 Error and warning behavior
+
+---
+
+# 7. Functional Requirements
+
+## 7.1 Project and Manifest Management
+
+### FR-101 Project Manifest Recognition
+
+The system shall accept a project definition that identifies the document project, its source files, document type, feature level, and associated template/style selections.
+
+### FR-102 Manifest Validation
+
+The system shall determine whether a provided project manifest is syntactically and functionally valid.
+
+### FR-103 Missing Resource Detection
+
+The system shall report an error when a manifest references a source, asset, bibliography, template, or style that is not available.
+
+### FR-104 Project Inspection
+
+The system shall provide a way to inspect the resolved project configuration, including source ordering, selected feature level, template selection, and derived document metadata.
+
+### FR-105 Project Capability Disclosure
+
+The system shall expose the effective capabilities of a project as derived from the manifest and registered feature support.
+
+### FR-106 Unsupported Manifest Configuration Detection
+
+The system shall reject or warn on manifest settings that are inconsistent with supported system behavior.
+
+---
+
+## 7.2 Build and Export
+
+### FR-201 Build Invocation
+
+The system shall allow a user or external client to request document build/export for a defined project.
+
+### FR-202 Markdown Composition
+
+The system shall compose the project’s declared Markdown sources into a buildable document representation.
+
+### FR-203 DOCX Export
+
+The system shall generate a DOCX artifact from a valid project when DOCX output is requested.
+
+### FR-204 Template Application
+
+The system shall apply the selected DOCX template family during DOCX generation.
+
+### FR-205 Style Selection
+
+The system shall associate the selected style family with the generated output where relevant to the output mode.
+
+### FR-206 Asset Inclusion
+
+The system shall include referenced images and other supported assets in the exported document where the asset is valid and resolvable.
+
+### FR-207 Metadata Propagation
+
+The system shall propagate supported document metadata from project inputs into the generated document.
+
+### FR-208 Build Result Reporting
+
+The system shall return a structured build result indicating success, warnings, or failure and identify generated artifacts.
+
+### FR-209 Deterministic Build Result Disclosure
+
+The system shall provide build output metadata sufficient for later validation and comparison.
+
+---
+
+## 7.3 Import and Round-Trip Processing
+
+### FR-301 DOCX Import Invocation
+
+The system shall allow a user or external client to submit a DOCX document for import into Markdown-compatible project form.
+
+### FR-302 Project-Aware Import
+
+The system shall import DOCX content in the context of a specified project configuration when such context is provided.
+
+### FR-303 Markdown Reconstitution
+
+The system shall produce Markdown output from the imported DOCX for supported constructs.
+
+### FR-304 Structural Preservation
+
+The system shall preserve supported document structure during import within the bounds of the selected feature level.
+
+### FR-305 Source Mapping Use
+
+When project source mapping is available, the system shall use it to associate imported content with original source boundaries.
+
+### FR-306 Import Result Reporting
+
+The system shall report the result of an import operation, including generated outputs, warnings, and identified ambiguities.
+
+### FR-307 Unsupported Construct Reporting
+
+The system shall explicitly report Word constructs that cannot be safely mapped into supported Markdown representation.
+
+### FR-308 Re-import Equivalence Support
+
+The system shall support round-trip workflows in which exported DOCX documents can be re-imported into semantically equivalent Markdown representations, subject to supported feature classes and accepted normalization.
+
+---
+
+## 7.4 Multi-File Document Handling
+
+### FR-401 Multi-File Source Declaration
+
+The system shall support projects consisting of multiple Markdown source files.
+
+### FR-402 Ordered Composition
+
+The system shall preserve declared source ordering when composing a multi-file document.
+
+### FR-403 Whole-Document Export
+
+The system shall support export of a multi-file project into a single reviewable document artifact.
+
+### FR-404 Source-Origin Awareness
+
+The system shall maintain source-origin information sufficient to support round-trip handling of multi-file documents.
+
+### FR-405 Source Redistribution
+
+The system shall support redistribution of imported content back into source-aligned outputs when source mapping information is available.
+
+### FR-406 Fallback Import Form
+
+When source redistribution cannot be completed safely, the system shall provide a valid merged Markdown result and indicate the fallback condition.
+
+### FR-407 Section Boundary Integrity Reporting
+
+The system shall report when imported edits cause ambiguity or breakage at tracked source or section boundaries.
+
+---
+
+## 7.5 Feature Level Support
+
+## 7.5.1 LEVEL1
+
+### FR-501 Heading Support
+
+The system shall export and import heading structures and preserve supported heading hierarchy.
+
+### FR-502 List Support
+
+The system shall export and import ordered and unordered lists and preserve list structure within supported cases.
+
+### FR-503 Table Support
+
+The system shall export and import supported table structures.
+
+### FR-504 Footnote Support
+
+The system shall export and import footnotes and preserve their association with referencing content.
+
+### FR-505 Image Support
+
+The system shall export and import supported images and preserve image references and associated descriptive metadata where available.
+
+### FR-506 Link Support
+
+The system shall export and import links and preserve supported link targets and visible text.
+
+## 7.5.2 LEVEL3
+
+### FR-531 Cross-Reference Support
+
+The system shall support export and import workflows for supported cross references between labeled content elements.
+
+### FR-532 Numbered Figure Support
+
+The system shall support export of figures with captions and numbering and preserve figure identity sufficiently for supported round-trip usage.
+
+### FR-533 Automatic Diagram Support
+
+The system shall support diagrams derived from source declarations as part of document build/export workflows.
+
+### FR-534 Diagram Intent Preservation
+
+The system shall preserve the connection between diagram source intent and rendered output within the managed workflow.
+
+### FR-535 Bibliography Support
+
+The system shall support bibliography-aware document generation from structured citation inputs.
+
+### FR-536 Citation Preservation
+
+The system shall preserve supported citation semantics during round-trip processing or report when ambiguity prevents safe preservation.
+
+### FR-537 Feature-Level Compatibility Disclosure
+
+The system shall disclose whether a project, template family, or processing path supports LEVEL1 only or LEVEL3.
+
+---
+
+## 7.6 Template and Style Management
+
+### FR-601 Built-In Family Availability
+
+The system shall provide three built-in document families named:
+
+* article
+* book
+* website
+
+### FR-602 Family Metadata Disclosure
+
+The system shall provide discoverable metadata for each available template/style family.
+
+### FR-603 Template Listing
+
+The system shall provide a way to list available template families.
+
+### FR-604 Style Listing
+
+The system shall provide a way to list available style families.
+
+### FR-605 Template Registration
+
+The system shall allow registration of an additional document template.
+
+### FR-606 Style Registration
+
+The system shall allow registration of an additional style definition.
+
+### FR-607 Paired Family Registration
+
+The system shall allow registration of an additional template/style family association.
+
+### FR-608 Registration Validation
+
+The system shall validate a proposed registration and report whether it is acceptable.
+
+### FR-609 Compatibility Declaration
+
+The system shall associate each template/style family with declared capability metadata, including applicable document types and feature-level support.
+
+### FR-610 Family Resolution
+
+The system shall resolve a family reference in a project to the corresponding registered template/style resources.
+
+---
+
+## 7.7 Validation and Drift Analysis
+
+### FR-701 Validation Invocation
+
+The system shall allow validation of a project without performing a full build or import.
+
+### FR-702 Validation Scope
+
+The system shall validate manifest integrity, referenced resources, selected feature level, and template/style compatibility.
+
+### FR-703 Build Preconditions Reporting
+
+The system shall report whether a project is functionally ready for build.
+
+### FR-704 Drift Comparison
+
+The system shall allow comparison of baseline and imported Markdown representations.
+
+### FR-705 Drift Classification
+
+The system shall classify detected differences into at least the following functional categories:
+
+* cosmetic
+* normalized
+* structural
+* unsupported or ambiguous
+* fatal
+
+### FR-706 Structural Drift Detection
+
+The system shall identify structural changes affecting supported document semantics.
+
+### FR-707 Cross-Reference Integrity Check
+
+The system shall detect and report broken or unresolved supported cross references.
+
+### FR-708 Figure Integrity Check
+
+The system shall detect and report supported figure numbering or identity inconsistencies.
+
+### FR-709 Bibliography Integrity Check
+
+The system shall detect and report unresolved bibliography or citation issues in supported workflows.
+
+### FR-710 Validation Result Output
+
+The system shall produce validation and drift results in a machine-consumable form and a human-consumable form.
+
+---
+
+## 7.8 CLI Functions
+
+### FR-801 Local CLI Availability
+
+The system shall provide a local command-line interface for core markidocx functions.
+
+### FR-802 CLI Build Command
+
+The CLI shall provide a command to build/export a project.
+
+### FR-803 CLI Import Command
+
+The CLI shall provide a command to import DOCX content into project-compatible Markdown outputs.
+
+### FR-804 CLI Validate Command
+
+The CLI shall provide a command to validate a project.
+
+### FR-805 CLI Diff Command
+
+The CLI shall provide a command to compare round-trip outputs or equivalent document states.
+
+### FR-806 CLI Inspect Command
+
+The CLI shall provide a command to inspect resolved project information.
+
+### FR-807 CLI Template Listing Command
+
+The CLI shall provide a command to list template families.
+
+### FR-808 CLI Style Listing Command
+
+The CLI shall provide a command to list styles or style families.
+
+### FR-809 CLI Registration Commands
+
+The CLI shall provide commands to register templates, styles, or families.
+
+### FR-810 CLI Test Command
+
+The CLI shall provide a command to execute the defined test suite or end-to-end validation workflow.
+
+### FR-811 CLI Exit Status Behavior
+
+The CLI shall return success, warning, or failure outcomes through distinguishable exit behavior and output.
+
+### FR-812 CLI Structured Output
+
+The CLI shall support a structured output mode for machine consumption.
+
+---
+
+## 7.9 REST Service Functions
+
+### FR-901 REST Service Availability
+
+The system shall provide a REST-accessible service exposing core markidocx functions.
+
+### FR-902 REST Project Validation
+
+The service shall allow clients to submit a project for validation and receive a structured result.
+
+### FR-903 REST Build
+
+The service shall allow clients to request document build/export and retrieve resulting artifacts and reports.
+
+### FR-904 REST Import
+
+The service shall allow clients to submit DOCX content for import and receive generated Markdown-compatible outputs and reports.
+
+### FR-905 REST Drift Comparison
+
+The service shall allow clients to request drift analysis between supplied or project-associated document states.
+
+### FR-906 REST Template Listing
+
+The service shall provide an endpoint for listing available template families.
+
+### FR-907 REST Style Listing
+
+The service shall provide an endpoint for listing available styles or style families.
+
+### FR-908 REST Registration
+
+The service shall allow submission of additional template/style registrations and return validation results.
+
+### FR-909 REST Capability Inspection
+
+The service shall provide a way to retrieve supported capability and feature-level information.
+
+### FR-910 REST Health Disclosure
+
+The service shall provide a machine-readable health/status response.
+
+### FR-911 REST Version Disclosure
+
+The service shall provide a machine-readable version response.
+
+### FR-912 REST Structured Responses
+
+The service shall return structured responses that identify status, outputs, warnings, and errors.
+
+---
+
+## 7.10 MCP Functions
+
+### FR-1001 MCP Availability
+
+The system shall provide an MCP-compatible interface exposing markidocx capabilities to agentic clients.
+
+### FR-1002 MCP Template Discovery
+
+The MCP interface shall expose a tool or equivalent operation to list available template families.
+
+### FR-1003 MCP Style Discovery
+
+The MCP interface shall expose a tool or equivalent operation to list available style families.
+
+### FR-1004 MCP Project Validation
+
+The MCP interface shall expose a tool or equivalent operation to validate a project.
+
+### FR-1005 MCP Project Inspection
+
+The MCP interface shall expose a tool or equivalent operation to inspect a project.
+
+### FR-1006 MCP Build
+
+The MCP interface shall expose a tool or equivalent operation to build/export a project.
+
+### FR-1007 MCP Import
+
+The MCP interface shall expose a tool or equivalent operation to import DOCX content.
+
+### FR-1008 MCP Drift Comparison
+
+The MCP interface shall expose a tool or equivalent operation to compare round-trip states.
+
+### FR-1009 MCP Test Execution
+
+The MCP interface shall expose a tool or equivalent operation to run end-to-end tests.
+
+### FR-1010 MCP Version Disclosure
+
+The MCP interface shall expose a tool or equivalent operation to disclose system version information.
+
+### FR-1011 MCP Resource Exposure
+
+The MCP interface shall expose relevant machine-consumable resources for manifests, capabilities, template metadata, style metadata, and current documentation corpus metadata.
+
+---
+
+## 7.11 Test and Regression Functions
+
+### FR-1101 Stable Documentation Corpus
+
+The system shall maintain the latest stable markidocx documentation as a managed documentation project.
+
+### FR-1102 Documentation-Based E2E Testing
+
+The system shall support execution of end-to-end validation using the latest stable markidocx documentation as the test corpus.
+
+### FR-1103 Round-Trip Regression Execution
+
+The system shall support a test flow in which the documentation corpus is built, exported, imported, and compared.
+
+### FR-1104 Template Coverage in E2E Testing
+
+The system shall support end-to-end testing against the built-in article, book, and website families where applicable.
+
+### FR-1105 Feature-Level Coverage in E2E Testing
+
+The system shall support execution of tests covering LEVEL1 and LEVEL3 behavior as represented in the stable documentation corpus.
+
+### FR-1106 Test Result Reporting
+
+The system shall provide a report identifying whether regression and end-to-end validation passed, warned, or failed.
+
+---
+
+## 7.12 Error and Warning Behavior
+
+### FR-1201 Explicit Failure Reporting
+
+The system shall explicitly report functional failures rather than silently omitting failed operations.
+
+### FR-1202 Explicit Warning Reporting
+
+The system shall explicitly report warnings when an operation completes with ambiguity, normalization, unsupported constructs, or partial degradation.
+
+### FR-1203 Unsupported Construct Visibility
+
+The system shall surface unsupported or ambiguous constructs in import, export, validation, or diff results.
+
+### FR-1204 Partial Result Disclosure
+
+When an operation produces partial results, the system shall indicate the partial nature of those results.
+
+### FR-1205 Non-Silent Degradation
+
+The system shall not silently discard known document constructs that fall outside supported round-trip behavior.
+
+---
+
+# 8. Functional Use Cases
+
+## UC-01 Single-File Round-Trip
+
+A user provides a single Markdown project, builds DOCX, edits the DOCX, imports it back, and receives an updated Markdown result plus drift report.
+
+## UC-02 Multi-File Review Workflow
+
+A user provides a multi-file project, exports one DOCX for review, imports the reviewed DOCX, and receives redistributed or merged Markdown outputs with section mapping status.
+
+## UC-03 Template Switching
+
+A user builds the same content using article, book, and website families and receives corresponding output artifacts without changing the source content.
+
+## UC-04 Validation Before Build
+
+A user validates a project and receives confirmation of readiness or a list of blocking issues.
+
+## UC-05 External Automation
+
+An external system submits a project to the REST service for build, import, or comparison and receives structured results.
+
+## UC-06 Agentic Interaction
+
+An MCP client discovers available templates, validates a project, triggers a build, and retrieves validation outcomes.
+
+## UC-07 Product Self-Test
+
+A release process runs end-to-end tests against the latest stable markidocx documentation and records regression status.
+
+---
+
+# 9. Functional Constraints
+
+### FC-01 Supported Semantic Envelope
+
+The system shall only claim preservation for constructs within the declared supported feature levels and managed workflow boundaries.
+
+### FC-02 Project-Scoped Operation
+
+Build, import, validation, and drift functions shall operate in relation to an explicit project context or explicitly supplied artifact set.
+
+### FC-03 Family-Scoped Capability
+
+Template/style application shall be constrained by the declared capabilities of the selected family.
+
+### FC-04 Fallback Disclosure
+
+Whenever the system falls back from source-aligned redistribution to merged or degraded output, it shall disclose that fallback.
+
+---
+
+# 10. Acceptance-Oriented Functional Summary
+
+markidocx shall be considered functionally conformant to this FRS when it can, at minimum:
+
+1. accept and validate a project manifest
+2. compose single-file and multi-file Markdown documents
+3. export DOCX using built-in document families
+4. import edited DOCX back into Markdown-compatible outputs
+5. support all declared LEVEL1 functions
+6. support declared LEVEL3 functions for managed cases
+7. detect and classify round-trip drift
+8. expose core functions through CLI
+9. expose core functions through REST
+10. expose core functions through MCP
+11. register additional templates and styles
+12. run end-to-end tests using the latest stable markidocx documentation corpus
+
+---
+
+# 11. Related Artifacts
+
+This FRS is expected to relate to:
+
+* PRD: markidocx
+* Non-Functional Requirements document
+* API/interface contracts
+* schema definitions for manifests and registrations
+* test specifications
+* acceptance criteria catalog
+* system design specification
+* architecture decision records
+
+---
+
+# 12. Appendix: Suggested Requirement Trace Anchors
+
+A minimal traceability map should connect:
+
+* PRD product goals → FRS requirement groups
+* FRS requirement IDs → interface contracts
+* FRS requirement IDs → acceptance tests
+* FRS requirement IDs → regression scenarios
+
+Example trace anchors:
+
+* PRD Round-Trip Editing → FR-201 to FR-308
+* PRD Multi-File Composition → FR-401 to FR-407
+* PRD Built-In Families → FR-601 to FR-610
+* PRD CLI/REST/MCP accessibility → FR-801 to FR-1011
+* PRD E2E documentation corpus → FR-1101 to FR-1106
+
+xxx

specs/MarkiDocxProductRequirementsDocument_v0.1.md

@@ -0,0 +1,391 @@
+Below is a **PRD for the markidocx product**, structured according to your **InfoTechPrimer PRD model** and respecting the principle of **implementation independence** (no CLI flags, API routes, or architecture details).
+Implementation specifics such as CLI/REST/MCP interfaces belong in the **FRS**, which would normally follow this PRD.
+
+---
+
+# PRD
+
+*Product Requirement Document*
+
+# Product Requirements Document: markidocx
+
+## 1. Definition
+
+**markidocx** is a product that enables **reliable round-trip editing between Markdown and Microsoft Word documents** while preserving document structure and semantic intent.
+
+The product addresses a recurring coordination problem in technical documentation and knowledge workflows:
+Markdown is widely used for structured authoring and version-controlled collaboration, while Word remains the dominant format for editorial review, stakeholder collaboration, and formal document exchange.
+
+markidocx provides a controlled workflow in which:
+
+* Markdown remains the **canonical structured source**
+* Word serves as a **managed editorial interface**
+* repeated conversion cycles preserve semantic structure
+* template-driven styling separates presentation from content
+* large multi-file documents remain manageable across the editing lifecycle
+
+The product is intended for organizations that require **structured documentation workflows with Word-based collaboration**, including engineering teams, documentation teams, standards bodies, and regulated environments.
+
+---
+
+## 2. Context
+
+markidocx operates at the intersection of:
+
+* **technical documentation systems**
+* **collaborative editorial workflows**
+* **requirements and specification authoring**
+* **knowledge management infrastructures**
+
+In many modern documentation environments:
+
+* engineers and technical authors write in **Markdown**
+* documents are stored in **version-controlled repositories**
+* external stakeholders and reviewers operate primarily in **Word**
+
+This mismatch creates friction:
+
+* Word-based edits often break structured content
+* Markdown workflows are inaccessible to non-technical reviewers
+* conversion pipelines introduce structural drift
+
+markidocx exists to bridge these environments by establishing a **controlled round-trip workflow** where:
+
+* Markdown remains structurally authoritative
+* Word editing is supported within a defined semantic envelope
+* conversion processes are deterministic and inspectable
+
+The product acts as a **boundary system between structured authoring and editorial collaboration**.
+
+---
+
+## 3. Core Concepts
+
+### Round-Trip Editing
+
+Round-trip editing is the ability to export a document into another format for editing and later re-import the modified document while preserving structural meaning.
+
+markidocx establishes a disciplined round-trip process between Markdown and Word.
+
+---
+
+### Canonical Source Model
+
+The canonical source of truth is **Markdown structured documents**.
+
+Word documents generated by the system are considered **editorial projections** of the canonical source rather than independent authoritative artifacts.
+
+---
+
+### Semantic Preservation
+
+The product guarantees preservation of document semantics across editing cycles within defined feature levels.
+
+Preserved semantics include structural constructs such as headings, lists, references, and citations.
+
+---
+
+### Template-Driven Presentation
+
+Document presentation is controlled by **document templates and style definitions**.
+
+This allows the same content to be exported in different presentation forms without modifying the source.
+
+Built-in document families include:
+
+* article
+* book
+* website
+
+---
+
+### Multi-File Document Composition
+
+Large documents are often structured across multiple files for maintainability.
+
+markidocx supports multi-file composition and ensures that editing cycles do not collapse this structure unnecessarily.
+
+---
+
+### Feature Levels
+
+markidocx distinguishes between two functional feature tiers:
+
+**LEVEL1 – Core Document Structure**
+
+* headings
+* lists
+* tables
+* footnotes
+* images
+* links
+
+**LEVEL3 – Advanced Scholarly / Technical Features**
+
+* cross references
+* numbered figures
+* automatic diagrams
+* bibliography
+
+Feature levels define the guarantees the system provides during round-trip editing.
+
+---
+
+### Drift Detection
+
+Structural drift may occur when editing documents in Word.
+
+markidocx introduces mechanisms to detect and report semantic differences between:
+
+* original Markdown sources
+* re-imported Markdown versions
+
+This allows users to understand and manage structural changes.
+
+---
+
+## 4. Scope and Non-Scope
+
+### In Scope
+
+The product must support:
+
+* Markdown ↔ Word round-trip editing
+* multi-file document composition
+* template-based document styling
+* two defined feature levels (LEVEL1 and LEVEL3)
+* preservation of document structure across editing cycles
+* detection and reporting of semantic drift
+* support for editorial collaboration workflows
+* extensibility through additional document templates and styles
+* automated testing of round-trip behavior using product documentation
+
+The product must provide interfaces that enable:
+
+* local document workflows
+* automated integration into documentation pipelines
+* programmatic interaction through service interfaces
+
+---
+
+### Out of Scope
+
+The product does not attempt to:
+
+* replace word processors
+* provide a graphical document editor
+* support arbitrary Word document constructs
+* act as a full document layout system
+* enforce a specific documentation methodology
+* replace existing publishing systems
+
+markidocx focuses specifically on **structured round-trip workflows**, not full document production ecosystems.
+
+---
+
+## 5. Practical Implications
+
+Adopting markidocx introduces a structured approach to document collaboration.
+
+Benefits include:
+
+* improved collaboration between technical and non-technical stakeholders
+* preservation of structured documentation in version-controlled environments
+* reduced manual cleanup after Word-based reviews
+* deterministic document generation workflows
+* improved traceability between authored content and reviewed documents
+
+Trade-offs include:
+
+* the need to operate within supported feature boundaries
+* the requirement to use defined templates and styles
+* occasional limitations when importing highly customized Word content
+
+The system is particularly valuable for organizations that:
+
+* maintain long-lived technical documentation
+* operate cross-disciplinary teams
+* require traceable document evolution
+* manage complex specifications or manuals
+
+---
+
+## 6. Product Use Cases
+
+The product must support the following key use cases.
+
+### Technical Review Workflow
+
+A document written in Markdown is exported to Word for review by stakeholders and later re-imported with edits incorporated into the Markdown source.
+
+---
+
+### Multi-Chapter Document Editing
+
+A large multi-file document is exported as a single Word document for external review and later re-imported without collapsing the source structure.
+
+---
+
+### Specification Publishing
+
+A technical specification written in Markdown is exported using a formal template suitable for distribution and archival.
+
+---
+
+### Documentation Collaboration
+
+Technical authors maintain Markdown sources while subject matter experts provide editorial feedback using Word.
+
+---
+
+### Knowledge System Integration
+
+The product integrates with documentation pipelines, knowledge repositories, or automated publication workflows.
+
+---
+
+### Regression Testing of Documentation
+
+The product documentation itself serves as a round-trip editing test corpus, validating product functionality across releases.
+
+---
+
+## 7. Constraints and Assumptions
+
+### Constraints
+
+* Word document editing environments vary widely.
+* Markdown dialects differ across ecosystems.
+* Some Word features cannot be reliably mapped to Markdown.
+* Diagram and bibliography rendering depend on external tools.
+
+The product must therefore operate within defined semantic boundaries.
+
+---
+
+### Assumptions
+
+* Markdown remains the authoritative authoring format.
+* Word is used primarily for editing and review rather than canonical storage.
+* document structure is maintained using supported constructs.
+* editorial users operate within template-defined formatting environments.
+
+---
+
+## 8. Success Criteria
+
+markidocx is considered successful when it achieves the following outcomes.
+
+### Structural Stability
+
+Repeated Markdown → Word → Markdown cycles preserve document structure within supported feature levels.
+
+---
+
+### Editorial Accessibility
+
+Non-technical stakeholders can review and edit documents without interacting directly with Markdown sources.
+
+---
+
+### Template Flexibility
+
+Organizations can apply different document presentation styles without altering content.
+
+---
+
+### Multi-Document Scalability
+
+Large documents composed from multiple files remain manageable across editing cycles.
+
+---
+
+### Detectable Drift
+
+Structural changes introduced during editing are visible and analyzable.
+
+---
+
+### Pipeline Compatibility
+
+The product integrates into automated documentation and publishing pipelines.
+
+---
+
+### Testable Documentation
+
+The product documentation itself can be used as a stable end-to-end validation corpus.
+
+---
+
+## 9. Dependencies
+
+The product depends on:
+
+* document conversion technologies capable of translating between Markdown and Word formats
+* diagram rendering tools for automated diagrams
+* citation and bibliography processing tools
+* structured document templates
+* consistent Markdown dialect support
+
+External dependencies must be manageable without introducing excessive operational complexity.
+
+---
+
+## 10. Risks
+
+### Semantic Drift Risk
+
+Editing in Word may unintentionally alter document structure.
+
+---
+
+### Template Misuse
+
+Users may modify templates in ways that break round-trip guarantees.
+
+---
+
+### Over-complex Feature Expectations
+
+Users may expect support for all Word features, which is not feasible.
+
+---
+
+### Workflow Discipline
+
+Successful operation depends on maintaining structured authoring practices.
+
+---
+
+## 11. Related Concepts
+
+* Markdown Documentation Systems
+* Structured Authoring
+* Technical Writing Pipelines
+* Documentation-as-Code
+* Word Editorial Workflows
+* Publishing Toolchains
+* Knowledge Repositories
+
+Adjacent artifacts include:
+
+* Functional Requirements Specification (FRS)
+* Architecture Documentation
+* Technical Specifications
+* Template and Style Definitions
+* Round-Trip Validation Reports
+
+---
+
+## 12. Appendix: Product Positioning
+
+markidocx belongs to a class of tools that bridge structured authoring and editorial collaboration.
+
+Compared with typical Markdown toolchains, the product focuses specifically on **controlled editorial round-trip workflows** rather than pure publishing.
+
+Compared with office-based authoring systems, the product preserves **version-controlled structured sources**.
+
+Its value lies in enabling **structured documentation ecosystems that remain compatible with Word-centric collaboration environments**.
+
+xxx