extension for ref resolve, explode, implode, weave, tangle

docs/literate-weave-tangle.md

@@ -0,0 +1,79 @@
+# Literate Weave and Tangle
+
+Date: 2026-05-04
+
+## Purpose
+
+The literate workflow layer brings a small Knuth-style weave/tangle capability
+to Markdown without requiring a separate language. Prose stays in Markdown.
+Named code chunks live in fenced blocks. Tangling emits source files.
+Weaving keeps the document readable and adds a deterministic chunk index.
+
+## Chunk Syntax
+
+Named chunks use fenced block attributes:
+
+````markdown
+```python {#helpers}
+def helper():
+    return "ready"
+```
+````
+
+A chunk becomes an output root when it declares `tangle`:
+
+````markdown
+```python {#main tangle="src/app.py"}
+<<helpers>>
+
+def main():
+    return helper()
+```
+````
+
+Chunk references use noweb-style syntax:
+
+```text
+<<helpers>>
+```
+
+Whole-line chunk references preserve indentation when expanded.
+
+## CLI
+
+Tangle files:
+
+```bash
+mkt tangle examples/literate/app.md --output-dir build/literate
+```
+
+Inspect without writing:
+
+```bash
+mkt tangle examples/literate/app.md --format json
+```
+
+Weave documentation:
+
+```bash
+mkt weave examples/literate/app.md --output build/app-woven.md
+```
+
+## Diagnostics
+
+Tangling reports structured diagnostics for missing chunks and cyclic chunk
+references. Tangled files are only written by the CLI when the result is valid.
+
+## Extension Boundary
+
+The MVP deliberately keeps the model narrow:
+
+- named fenced blocks
+- `tangle="<path>"`
+- deterministic document-order concatenation for repeated targets
+- noweb-style chunk expansion
+- generated chunk index during weave
+
+Future extensions can add richer source maps, processor execution,
+language-specific extraction, and class/namespace-aware chunk selection without
+changing this initial chunk model.