# 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(...)`.

Heading shifts are token-safe: Markdown fenced and indented code blocks are
left untouched even if their lines look like headings. `TransformResult`
includes structured provenance events alongside the older operation-name list.

## 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.
- Include markers inside fenced or indented code blocks are left literal.

The API equivalent is `resolve_includes(...)`.

`IncludeResult` includes structured provenance events. Each include event
records the source marker line when available, the resolved target path,
dependency edge, selector, heading shift, and frontmatter policy. This is the
first provenance envelope used by later WP-0010 processor, source-map, and
explode/implode work.