Deterministic ops layer and cli

docs/transform-compose-include.md

@@ -0,0 +1,83 @@
+# Transform, Compose, and Include Primitives
+
+`markitect-tool` keeps document operations deterministic and Markdown-native.
+The first operation layer covers three practical needs:
+
+- Transform one document with explicit operations.
+- Compose several Markdown files into one output.
+- Resolve Markdown include markers without adding a service or database layer.
+
+These operations are deliberately small. They are meant to be reliable building
+blocks for later templates, generation, cache backends, and agent workflows.
+
+## Transform
+
+Use `mkt transform` for deterministic edits that can be repeated in a pipeline:
+
+```bash
+mkt transform doc.md --set status=draft --heading-delta 1
+```
+
+Supported operations:
+
+- `--set KEY=VALUE`: set frontmatter values. Dot paths create nested mappings.
+- `--strip-frontmatter`: remove frontmatter.
+- `--heading-delta N`: shift ATX headings and clamp levels to `#` through `######`.
+- `--extract SELECTOR`: replace document content with selector output.
+
+The API equivalent is `transform_markdown(...)`.
+
+## Compose
+
+Use `mkt compose` to concatenate Markdown inputs with predictable separators:
+
+```bash
+mkt compose intro.md details.md --title "Combined Document" --output combined.md
+```
+
+By default, each input file's YAML frontmatter is removed before composition.
+Use `--include-frontmatter` when the frontmatter itself should be preserved in
+the composed body.
+
+The API equivalent is `compose_files(...)`.
+
+## Include
+
+Use `mkt include` to resolve transclusion markers:
+
+```markdown
+Before.
+
+<!-- mkt:include path="sections/intro.md" -->
+
+After.
+```
+
+The explicit marker supports attributes:
+
+```markdown
+<!-- mkt:include path="sections/intro.md" selector="sections[heading=Summary]" heading_delta="1" -->
+```
+
+Supported attributes:
+
+- `path`: required relative path to the included Markdown file.
+- `selector`: optional Markitect selector; only matching content is included.
+- `heading_delta`: optional heading-level shift for included content.
+- `include_frontmatter`: `true` keeps the included file's frontmatter.
+
+The compact shorthand is also supported:
+
+```markdown
+{{include:sections/intro.md}}
+```
+
+Resolution rules:
+
+- Relative paths resolve from the including file.
+- All included paths must stay under `--base-dir`, defaulting to the input file
+  directory.
+- Recursive includes are resolved up to `--max-depth`.
+- Cycles and missing files fail with explicit errors.
+
+The API equivalent is `resolve_includes(...)`.