# 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.