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

docs/explode-implode.md

@@ -0,0 +1,69 @@
+# Explode and Implode
+
+Date: 2026-05-04
+
+## Purpose
+
+`mkt explode` and `mkt implode` reintroduce the useful old Markitect
+large-document workflow as a slim WP-0010 extension. The design is
+manifest-first: the exploded directory is editable, but the manifest preserves
+ordering, source spans, heading metadata, hashes, frontmatter, and the selected
+layout variant.
+
+This keeps the operation reversible without requiring a database or service.
+
+## Variants
+
+The initial variants are:
+
+- `flat`: writes ordered section files under `sections/`.
+- `hierarchical`: writes child section files below parent heading directories.
+
+Both variants preserve the same manifest model. A later semantic variant can
+reuse the reference and processor framework once those layers are stable.
+
+## CLI
+
+Explode a document:
+
+```bash
+mkt explode docs/source.md --output-dir work/source-exploded
+```
+
+Use a hierarchical directory shape:
+
+```bash
+mkt explode docs/source.md --output-dir work/source-tree --variant hierarchical
+```
+
+Implode the directory back into one Markdown file:
+
+```bash
+mkt implode work/source-exploded --output docs/source-rebuilt.md
+```
+
+By default `mkt explode` refuses to write into a non-empty output directory. Use
+`--force` when an explicit overwrite is intended.
+
+## Manifest
+
+The manifest is written as `markitect-explode.yaml` in the output directory.
+It records:
+
+- manifest version
+- original source path and SHA-256 hash
+- variant
+- raw frontmatter block
+- ordered entries with file path, kind, unit ID, source line span, heading
+  metadata, and content hash
+
+Implode reads the manifest entries in order and concatenates the current entry
+files. If users edit section files, the rebuilt document reflects those edits
+while preserving the original frontmatter and ordering.
+
+## Extension Boundary
+
+This implementation is intentionally not semantic yet. It does not infer
+contracts, classes, named chunks, or processor outputs. Instead it establishes a
+small reversible substrate that later WP-0010 tasks can enrich with regions,
+references, processors, source maps, and weave/tangle behavior.