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

docs/transform-compose-include.md

@@ -27,6 +27,10 @@ Supported operations:
 
 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:
@@ -79,5 +83,12 @@ Resolution rules:
   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.