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

docs/processors.md

@@ -0,0 +1,81 @@
+# Fenced-Block Processors
+
+Date: 2026-05-04
+
+## Purpose
+
+The processor registry is the deterministic execution boundary for WP-0010.
+It lets Markdown fenced blocks opt into named processors while keeping
+execution explicit, inspectable, and non-magical.
+
+Processors receive:
+
+- the fenced content unit
+- resolver-capable context
+- variables and policy maps
+
+Processors return:
+
+- generated content
+- optional generated files
+- diagnostics
+- dependencies
+- operation provenance
+
+No built-in processor runs arbitrary code.
+
+## Syntax
+
+A fenced block opts into processing by using an `mkt-<processor>` language:
+
+````markdown
+```mkt-uppercase {#shout}
+hello
+```
+````
+
+The processor can also be named with attributes:
+
+````markdown
+```markdown {#example processor="identity"}
+Rendered as-is by the identity processor.
+```
+````
+
+## Built-In Processors
+
+Initial deterministic processors:
+
+- `identity`: returns the fenced block content unchanged.
+- `uppercase`: returns uppercased content; mainly a registry smoke-test.
+- `include`: resolves a `ref` attribute through the content reference resolver.
+
+Reference-backed include:
+
+````markdown
+```mkt-include {#payment ref="std:clauses.md#payment-terms"}
+```
+````
+
+The include processor returns the resolved content, records the target file as
+a dependency, and emits operation provenance.
+
+## CLI
+
+Run processors in a document:
+
+```bash
+mkt process examples/references/context.md --format json
+```
+
+Text output reports processor validity, block IDs, and the first generated
+content line. JSON/YAML output includes diagnostics, dependencies, and
+provenance.
+
+## Extension Boundary
+
+The registry is deliberately small. It does not render a final document yet and
+does not execute shell, Python, SQL, or LLM calls. Those can become opt-in
+processors later, but they should use the same result envelope so diagnostics,
+dependencies, provenance, cache invalidation, and access-control hooks stay
+consistent.