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