declarative Markdown workflow layer

docs/markdown-workflows.md

@@ -0,0 +1,102 @@
+# Markdown Workflows
+
+Markitect workflows provide declarative orchestration for Markdown-centered
+document pipelines.
+
+Use them when you want to:
+
+- collect Markdown files, globs, or directories
+- extract frontmatter, sections, blocks, metrics, or selector results
+- bind named data products into later steps
+- run deterministic template/compose/transform/include steps
+- define optional assisted-generation boundaries without requiring a provider
+- write one or more Markdown outputs with provenance and diagnostics
+
+The workflow definition standard is documented in
+`docs/workflow-definition-standard.md`.
+
+## Commands
+
+Inspect a workflow definition:
+
+```text
+mkt workflow inspect examples/workflows/adr-release-notes.workflow.md
+```
+
+Plan a run without writing outputs:
+
+```text
+mkt workflow plan examples/workflows/adr-release-notes.workflow.md
+```
+
+Run and write outputs:
+
+```text
+mkt workflow run examples/workflows/adr-release-notes.workflow.md --output-dir build
+```
+
+JSON/YAML output is available for agents:
+
+```text
+mkt workflow run workflow.md --format json
+```
+
+## Execution Model
+
+The first runner is deterministic and local-first:
+
+1. Load a YAML or Markdown-fenced workflow definition.
+2. Validate required ids/kinds and duplicate step ids.
+3. Collect inputs from Markdown files, directories, globs, or literal values.
+4. Resolve `${...}` bindings.
+5. Execute steps in dependency order.
+6. Render outputs and enforce output path safety.
+7. Return diagnostics, provenance, and trace events.
+
+Assisted steps are explicit boundaries. Without an injected generation hook:
+
+- optional assisted steps are skipped with a warning
+- required assisted steps fail
+
+This makes workflows useful without provider dependencies.
+
+## Supported Step Kinds
+
+| Kind | Result |
+| --- | --- |
+| `shape` | Structured data object. |
+| `extract` | `items`, `count`, and joined `text`. |
+| `query` | query `matches` and `count`. |
+| `template` | rendered `markdown`, variables, missing variables, completion flag. |
+| `compose` | composed `markdown` and sources. |
+| `transform` | transformed `markdown`, operations, provenance. |
+| `include` | include-resolved `markdown`, included paths, provenance. |
+| `contract_stub` | generated contract stub Markdown. |
+| `contract_check` | contract diagnostics and metrics. |
+| `assisted` | generated Markdown if a hook is supplied, otherwise skipped/diagnostic. |
+
+## Data Bindings
+
+Bindings use `${...}`:
+
+```yaml
+data:
+  decisions: ${sources.adrs.extracts.decisions}
+  summary: ${steps.render.markdown}
+```
+
+If the full string is one expression, the native type is preserved. If the
+expression appears inside a longer string, it is rendered as text.
+
+List projection is supported:
+
+```yaml
+paths: ${sources.adrs.items.path}
+```
+
+## Relationship To Extensions
+
+The workflow engine is registered as the built-in extension
+`workflow.markdown-dataflow`. It uses the canonical architecture for
+diagnostics, provenance, trace events, capabilities, and CLI affordance
+metadata, but workflow files remain business-facing orchestration artifacts.