markdown_composer 0.7.0

data/docs/examples/md_composer_examples_readme.md

@@ -0,0 +1,45 @@
+---
+title: Markdown Composer Examples
+type: examples
+status: current
+updated: 2026-06-07
+description: Public index of Markdown Composer examples by task.
+---
+
+# Markdown Composer Examples
+
+### References
+
+| What | Where |
+|------|-------|
+| Getting started | [../_md_composer_getting_started.md](../_md_composer_getting_started.md) |
+| Compose anatomy | [../compose/md_composer_compose_anatomy.md](../compose/md_composer_compose_anatomy.md) |
+| Transform anatomy | [../transform/md_composer_transform_anatomy.md](../transform/md_composer_transform_anatomy.md) |
+
+---
+
+## 1. How To Use Examples
+
+Use the runnable examples first when you want copy-paste Ruby. They read shared fixtures from `examples/fixtures/` and write output to `examples/output/`.
+
+For task-focused learning, use the individual examples below. Each task page shows the source shape, plan/config shape, expected output, and notes.
+
+| What | Where |
+|------|-------|
+| Runnable Ruby scripts | [Runnable examples](./md_composer_runnable_examples.md) |
+| Shared fixture map | [Example fixtures](./md_composer_example_fixtures.md) |
+
+## 2. Example Index
+
+| Task | Example |
+|------|---------|
+| Select one section | [Basic compose](./md_composer_example_basic_compose.md) |
+| Define sources with Ruby DSL | [Source Ruby DSL](./md_composer_source_ruby_dsl.md) |
+| Build output from several rows | [Multi-row compose](./md_composer_example_multi_row_compose.md) |
+| Transform selected source content | [Modify](./md_composer_example_modify.md) |
+| Remove or transform existing buffer content | [Buffer target actions](./md_composer_example_buffer_target_actions.md) |
+| Run top-level transforms | [Transforms](./md_composer_example_transforms.md) |
+| Extract YAML/JSON values | [Structured data](./md_composer_example_structured_data.md) |
+| Render HTML output | [HTML output](./md_composer_example_html_output.md) |
+| Author Ruby DSL plans | [Ruby plans](./md_composer_example_ruby_plans.md) |
+| Import/export YAML, JSON, and rows | [YAML, JSON, and rows](./md_composer_example_yaml_json_rows.md) |

data/docs/examples/md_composer_runnable_examples.md

@@ -0,0 +1,374 @@
+---
+title: Markdown Composer Runnable Examples
+type: examples
+status: current
+updated: 2026-06-07
+description: Copy-paste guide to the runnable Ruby examples shipped with Markdown Composer.
+---
+
+# Markdown Composer Runnable Examples
+
+### References
+
+| What | Where |
+|------|-------|
+| Fixture map | [./md_composer_example_fixtures.md](./md_composer_example_fixtures.md) |
+| Source Ruby DSL | [./md_composer_source_ruby_dsl.md](./md_composer_source_ruby_dsl.md) |
+| Examples index | [./md_composer_examples_readme.md](./md_composer_examples_readme.md) |
+| API reference | [../reference/md_composer_reference_api.md](../reference/md_composer_reference_api.md) |
+
+---
+
+## 1. How To Run
+
+Run examples from the gem root:
+
+```bash
+ruby -Ilib examples/basic_compose.rb
+ruby -Ilib examples/source_list_dsl.rb
+ruby -Ilib examples/yaml_plan.rb
+ruby -Ilib examples/html_input.rb
+ruby -Ilib examples/standard_composer.rb
+ruby -Ilib examples/standard_sources_buffer.rb
+ruby -Ilib examples/advanced_composer.rb
+ruby -Ilib examples/complex_composer.rb
+```
+
+Each script prints Markdown and writes the same result to `examples/output/*.md`.
+
+## 2. Runnable Example Index
+
+| Script | What it shows | Fixtures | Output |
+|--------|---------------|----------|--------|
+| [basic_compose.rb](../../examples/basic_compose.rb) | Select one H2 section from the current source. | [current.md](../../examples/fixtures/current.md) | [basic_compose.md](../../examples/output/basic_compose.md) |
+| [source_list_dsl.rb](../../examples/source_list_dsl.rb) | Build sources with `MarkdownComposer.source_list` and compose current, explicit, and inherited inputs. | [current.md](../../examples/fixtures/current.md), [guide.md](../../examples/fixtures/guide.md), [faq.md](../../examples/fixtures/faq.md), [site_intro.md](../../examples/fixtures/site_intro.md) | [source_list_dsl.md](../../examples/output/source_list_dsl.md) |
+| [yaml_plan.rb](../../examples/yaml_plan.rb) | Load a YAML plan from `examples/plans/basic.yml`. | [current.md](../../examples/fixtures/current.md), [guide.md](../../examples/fixtures/guide.md) | [yaml_plan.md](../../examples/output/yaml_plan.md) |
+| [html_input.rb](../../examples/html_input.rb) | Compose from HTML input through the best-effort HTML path. | [source.html](../../examples/fixtures/source.html) | [html_input.md](../../examples/output/html_input.md) |
+| [standard_composer.rb](../../examples/standard_composer.rb) | Select one H2 section, promote heading levels, and insert a generated Summary section. | [current.md](../../examples/fixtures/current.md) | [standard_composer.md](../../examples/output/standard_composer.md) |
+| [standard_sources_buffer.rb](../../examples/standard_sources_buffer.rb) | Use current, explicit, previous, and buffer sources with heading rename/number transforms. | [current.md](../../examples/fixtures/current.md), [guide.md](../../examples/fixtures/guide.md) | [standard_sources_buffer.md](../../examples/output/standard_sources_buffer.md) |
+| [advanced_composer.rb](../../examples/advanced_composer.rb) | Demonstrate all source types, all compose actions, nested modify transforms, and final output transforms. | [current.md](../../examples/fixtures/current.md), [guide.md](../../examples/fixtures/guide.md), [site_intro.md](../../examples/fixtures/site_intro.md) | [advanced_composer.md](../../examples/output/advanced_composer.md) |
+| [complex_composer.rb](../../examples/complex_composer.rb) | Broader copy-paste walkthrough with all source types, all actions, multiple explicit sources, and final transforms. | [current.md](../../examples/fixtures/current.md), [guide.md](../../examples/fixtures/guide.md), [faq.md](../../examples/fixtures/faq.md), [site_intro.md](../../examples/fixtures/site_intro.md) | [complex_composer.md](../../examples/output/complex_composer.md) |
+
+### 2.1 Basic Compose
+
+[basic_compose.rb](../../examples/basic_compose.rb) is the smallest runnable compose example. It reads one Markdown fixture, selects the first H2 section from that source, and writes the selected section unchanged to [basic_compose.md](../../examples/output/basic_compose.md).
+
+Run it from the gem root:
+
+```bash
+ruby -Ilib examples/basic_compose.rb
+```
+
+#### Sources
+
+| Key | Type | File | Purpose |
+|-----|------|------|---------|
+| `current` | `current` | [current.md](../../examples/fixtures/current.md) | Main Markdown source. The example selects the first `##` section, which is `Overview`. |
+
+This example intentionally uses the raw source hash shape:
+
+```ruby
+sources: [
+  { key: "current", type: "current", markdown: current_markdown }
+]
+```
+
+That is equivalent in purpose to a single-source `MarkdownComposer.source_list`, but keeps the most basic example close to the underlying `compose` contract.
+
+#### Composer Rows
+
+| Step | [Source](../compose/md_composer_compose_sources.md) | [Select](../compose/md_composer_compose_select.md) | [Include](../compose/md_composer_compose_include.md) | [Action](../compose/md_composer_compose_actions.md) | What it does |
+|------|--------|--------|---------|--------|--------------|
+| 1 | [`current`](../compose/md_composer_compose_sources.md#4-current-source) | [`h2_section`](../compose/md_composer_compose_select.md#3-section-versus-node-tokens)[`[first:1]`](../reference/md_composer_take.md#4-common-take-forms) | `all` | [`set`](../compose/md_composer_compose_actions.md#41-set) | Reads the first H2 section from `current.md`, keeps the heading and full section body, and replaces the output buffer with that selected content. |
+
+#### Output Shape
+
+The output starts with:
+
+```markdown
+## Overview
+
+This overview section is the normal starting point for Markdown Composer examples.
+```
+
+### 2.2 Source List DSL
+
+[source_list_dsl.rb](../../examples/source_list_dsl.rb) demonstrates the Ruby `MarkdownComposer.source_list` helper with current, explicit, and inherited runtime sources. It composes sections from multiple files, then prepends inherited site content.
+
+Run it from the gem root:
+
+```bash
+ruby -Ilib examples/source_list_dsl.rb
+```
+
+#### Sources
+
+| Key | Type | File | Purpose |
+|-----|------|------|---------|
+| `current` | `current` | [current.md](../../examples/fixtures/current.md) | Main source. Supplies the first H2 section, `Overview`. |
+| `guide` | `explicit` | [guide.md](../../examples/fixtures/guide.md) | Explicit source selected by key. Supplies install/configure/validate/publish sections. |
+| `faq` | `explicit` | [faq.md](../../examples/fixtures/faq.md) | Explicit source selected by key. Supplies FAQ headings and first paragraphs. |
+| `site_intro` | `inherited` | [site_intro.md](../../examples/fixtures/site_intro.md) | Inherited source selected by key. Prepended to the composed output. |
+
+#### Composer Rows
+
+| Step | [Source](../compose/md_composer_compose_sources.md) | [Select](../compose/md_composer_compose_select.md) | [Include](../compose/md_composer_compose_include.md) | [Action](../compose/md_composer_compose_actions.md) | What it does |
+|------|--------|--------|---------|--------|--------------|
+| 1 | [`current`](../compose/md_composer_compose_sources.md#4-current-source) | [`h2_section`](../compose/md_composer_compose_select.md#3-section-versus-node-tokens)[`[first:1]`](../reference/md_composer_take.md#4-common-take-forms) | `all` | [`set`](../compose/md_composer_compose_actions.md#41-set) | Starts the buffer with the first current-source H2 section. |
+| 2 | [`explicit`](../compose/md_composer_compose_sources.md#5-explicit-source) `guide` | `h2_section` | `all` | [`append`](../compose/md_composer_compose_actions.md#42-append) | Appends all guide H2 sections. |
+| 3 | [`explicit`](../compose/md_composer_compose_sources.md#5-explicit-source) `faq` | `h2_section` | `heading_title`, `paragraph[first:1]` | [`append`](../compose/md_composer_compose_actions.md#42-append) | Appends each FAQ H2 heading and its first paragraph. |
+| 4 | [`inherited`](../compose/md_composer_compose_sources.md#3-source-tokens) `site_intro` | `h2_section` | `all` | [`prepend`](../compose/md_composer_compose_actions.md#43-prepend) | Prepends inherited site-introduction sections before the current and explicit content. |
+
+#### Output Shape
+
+The output starts with inherited `## Welcome` content, then includes `## Overview`, guide sections, and FAQ heading/paragraph summaries.
+
+### 2.3 YAML Plan
+
+[yaml_plan.rb](../../examples/yaml_plan.rb) shows the same compose model loaded from [basic.yml](../../examples/plans/basic.yml) instead of the Ruby plan DSL. Sources are still provided at runtime through `MarkdownComposer.source_list`.
+
+Run it from the gem root:
+
+```bash
+ruby -Ilib examples/yaml_plan.rb
+```
+
+#### Sources
+
+| Key | Type | File | Purpose |
+|-----|------|------|---------|
+| `current` | `current` | [current.md](../../examples/fixtures/current.md) | Supplies the first H2 section, `Overview`. |
+| `guide` | `explicit` | [guide.md](../../examples/fixtures/guide.md) | Supplies the first guide H2 section, `Install`. |
+
+#### Composer Rows
+
+| Step | [Source](../compose/md_composer_compose_sources.md) | [Select](../compose/md_composer_compose_select.md) | [Include](../compose/md_composer_compose_include.md) | [Action](../compose/md_composer_compose_actions.md) | What it does |
+|------|--------|--------|---------|--------|--------------|
+| 1 | [`current`](../compose/md_composer_compose_sources.md#4-current-source) | `h2_section[first:1]` | `all` | [`set`](../compose/md_composer_compose_actions.md#41-set) | Starts the output with `Overview` from `current.md`. |
+| 2 | [`explicit`](../compose/md_composer_compose_sources.md#5-explicit-source) `guide` | `h2_section[first:1]` | `all` | [`append`](../compose/md_composer_compose_actions.md#42-append) | Appends `Install` from `guide.md`. |
+
+#### Transform Rows
+
+| Step | [Scope](../transform/md_composer_transform_scope.md) | [Transform](../transform/md_composer_transform_transforms.md) | [Mode](../transform/md_composer_transform_modes.md) | Options | What it does |
+|------|--------|-----------|------|---------|--------------|
+| 1 | `output` | `heading_numbers` | `rebuild` | `levels: h2`, `start: 1` | Rebuilds H2 numbering so the selected sections become `## 1. Overview` and `## 2. Install`. |
+
+#### Output Shape
+
+The output contains numbered H2 sections from two sources: `## 1. Overview` followed by `## 2. Install`.
+
+### 2.4 HTML Input
+
+[html_input.rb](../../examples/html_input.rb) reads HTML instead of Markdown and emits Markdown output. It demonstrates the gem's best-effort HTML-to-Markdown input path.
+
+Run it from the gem root:
+
+```bash
+ruby -Ilib examples/html_input.rb
+```
+
+#### Sources
+
+| Key | Type | File | Purpose |
+|-----|------|------|---------|
+| `current` | `current` with `html` | [source.html](../../examples/fixtures/source.html) | HTML source converted through Composer before selection. |
+
+#### Composer Rows
+
+| Step | [Source](../compose/md_composer_compose_sources.md) | [Select](../compose/md_composer_compose_select.md) | [Include](../compose/md_composer_compose_include.md) | [Action](../compose/md_composer_compose_actions.md) | What it does |
+|------|--------|--------|---------|--------|--------------|
+| 1 | [`current`](../compose/md_composer_compose_sources.md#4-current-source) | `h2_section[first:1]` | `all` | [`set`](../compose/md_composer_compose_actions.md#41-set) | Selects the first H2 section from the converted HTML source and makes it the output. |
+
+#### Output Shape
+
+The output is Markdown, starting with `## Overview` and the converted HTML paragraph/link content.
+
+### 2.5 Standard Composer
+
+[standard_composer.rb](../../examples/standard_composer.rb) selects one focused H2 section, keeps selected child content, renames the H2, promotes heading levels, and inserts a generated `## Summary` section with a transform.
+
+Run it from the gem root:
+
+```bash
+ruby -Ilib examples/standard_composer.rb
+```
+
+#### Sources
+
+| Key | Type | File | Purpose |
+|-----|------|------|---------|
+| `current` | `current` | [current.md](../../examples/fixtures/current.md) | Supplies `Feature Matrix` and its first two H3 child sections. |
+
+#### Composer Rows
+
+| Step | [Source](../compose/md_composer_compose_sources.md) | [Select](../compose/md_composer_compose_select.md) | [Include](../compose/md_composer_compose_include.md) | [Action](../compose/md_composer_compose_actions.md) | What it does |
+|------|--------|--------|---------|--------|--------------|
+| 1 | [`current`](../compose/md_composer_compose_sources.md#4-current-source) | `h2_section where title:equals("Feature Matrix")` | `heading_title`, `paragraph[first:1]`, `link[first:1]`, `table[first:1]`, first two H3 sections with paragraph/code/table content | [`append`](../compose/md_composer_compose_actions.md#42-append) | Builds a focused feature-matrix slice from the current source. |
+
+#### Transform Rows
+
+| Step | [Scope](../transform/md_composer_transform_scope.md) | [Transform](../transform/md_composer_transform_transforms.md) | [Mode](../transform/md_composer_transform_modes.md) | Options | What it does |
+|------|--------|-----------|------|---------|--------------|
+| 1 | `heading_2` | `replace_text` | `literal` | `Feature Matrix` to `Feature Matrix Summary` | Renames the selected H2 heading. |
+| 2 | `heading` | `heading_levels` | `promote` | `by: 1` | Promotes `##` to `#` and `###` to `##`. |
+| 3 | `paragraph[first:1]` | `insert_after` | `insert` | raw Markdown `## Summary` plus paragraph | Inserts a generated Summary section after the lead paragraph. |
+
+#### Output Shape
+
+The output starts with `# Feature Matrix Summary`, then a generated `## Summary`, followed by selected table and child-section content.
+
+### 2.6 Standard Sources Buffer
+
+[standard_sources_buffer.rb](../../examples/standard_sources_buffer.rb) demonstrates current, explicit, previous, and buffer sources. It composes a document title and operations section, appends guide content, reuses the previous explicit source, removes a buffer section, then renames and numbers headings.
+
+Run it from the gem root:
+
+```bash
+ruby -Ilib examples/standard_sources_buffer.rb
+```
+
+#### Sources
+
+| Key | Type | File | Purpose |
+|-----|------|------|---------|
+| `current` | `current` | [current.md](../../examples/fixtures/current.md) | Supplies the H1 title/intro and `Operations` content. |
+| `guide` | `explicit` | [guide.md](../../examples/fixtures/guide.md) | Supplies `Install` and `Validate` sections. |
+
+#### Composer Rows
+
+| Step | [Source](../compose/md_composer_compose_sources.md) | [Select](../compose/md_composer_compose_select.md) | [Include](../compose/md_composer_compose_include.md) | [Action](../compose/md_composer_compose_actions.md) | What it does |
+|------|--------|--------|---------|--------|--------------|
+| 1 | [`current`](../compose/md_composer_compose_sources.md#4-current-source) | `heading_1_section[first:1]` | `heading_title`, `paragraph[first:1]` | [`set`](../compose/md_composer_compose_actions.md#41-set) | Starts with the document H1 and its first paragraph. |
+| 2 | [`current`](../compose/md_composer_compose_sources.md#4-current-source) | `h2_section where title:equals("Operations")` | heading, first paragraph, and first H3 subsection with paragraph/code | [`append`](../compose/md_composer_compose_actions.md#42-append) | Appends a focused operations runbook section. |
+| 3 | [`explicit`](../compose/md_composer_compose_sources.md#5-explicit-source) `guide` | `h2_section where title:equals("Install")` | `all` | [`append`](../compose/md_composer_compose_actions.md#42-append) | Appends guide install content. |
+| 4 | [`previous`](../compose/md_composer_compose_sources.md#6-previous-source) | `h2_section where title:equals("Validate")` | `all` | [`append`](../compose/md_composer_compose_actions.md#42-append) | Reuses the previous explicit guide source to append validation content. |
+| 5 | [`buffer`](../compose/md_composer_compose_sources.md#7-buffer-source) | `h2_section where title:equals("Install")` | `all` | [`remove_buffer_target`](../compose/md_composer_compose_actions.md#412-remove-buffer-target) | Removes the already-composed Install section from the buffer. |
+
+#### Transform Rows
+
+| Step | [Scope](../transform/md_composer_transform_scope.md) | [Transform](../transform/md_composer_transform_transforms.md) | [Mode](../transform/md_composer_transform_modes.md) | Options | What it does |
+|------|--------|-----------|------|---------|--------------|
+| 1 | `heading_2` | `replace_text` | `literal` | `Operations` to `Standard Operations` | Renames the operations H2. |
+| 2 | `heading_3` | `replace_text` | `literal` | `Deployment` to `Release Steps` | Renames the selected H3. |
+| 3 | `output` | `heading_numbers` | `rebuild` | `levels: h2,h3`, `start: 1` | Rebuilds H2/H3 numbering after composition. |
+
+#### Output Shape
+
+The output starts with `# Product Knowledge Base`, then numbered `Standard Operations` and `Validate` sections.
+
+### 2.7 Advanced Composer
+
+[advanced_composer.rb](../../examples/advanced_composer.rb) is a broad but readable DSL example. It uses runtime `current`, `explicit`, and `inherited` sources plus row-level `inline`, `previous`, and `buffer` sources. It demonstrates every compose action and several transform families.
+
+Run it from the gem root:
+
+```bash
+ruby -Ilib examples/advanced_composer.rb
+```
+
+#### Sources
+
+| Key | Type | File | Purpose |
+|-----|------|------|---------|
+| `current` | `current` | [current.md](../../examples/fixtures/current.md) | Supplies feature, reporting, monitoring, and dashboard content. |
+| `guide` | `explicit` | [guide.md](../../examples/fixtures/guide.md) | Supplies validation and publishing sections. |
+| `site_intro` | `inherited` | [site_intro.md](../../examples/fixtures/site_intro.md) | Supplies inherited Welcome content. |
+
+#### Composer Rows
+
+| Step | [Source](../compose/md_composer_compose_sources.md) | [Action](../compose/md_composer_compose_actions.md) | What it does |
+|------|--------|--------|--------------|
+| 1 | `current` | [`set`](../compose/md_composer_compose_actions.md#41-set) | Starts with a focused `Feature Matrix` slice. |
+| 2 | `inline` | [`prepend`](../compose/md_composer_compose_actions.md#43-prepend) | Adds an Advanced Preface at the start. |
+| 3 | `inherited site_intro` | [`append`](../compose/md_composer_compose_actions.md#42-append) | Appends inherited Welcome content. |
+| 4 | `buffer target` | [`transform_buffer_target`](../compose/md_composer_compose_actions.md#413-transform-buffer-target) | Demotes Welcome while it is already in the buffer. |
+| 5 | `explicit guide` | [`append`](../compose/md_composer_compose_actions.md#42-append) | Appends Validate content. |
+| 6 | `previous` | [`append`](../compose/md_composer_compose_actions.md#42-append) | Reuses the guide source to append Publish content. |
+| 7-8 | `buffer target` | [`transform_buffer_target`](../compose/md_composer_compose_actions.md#413-transform-buffer-target) | Demotes and renames Validate and Publish headings. |
+| 9 | `inline` | [`insert_before`](../compose/md_composer_compose_actions.md#44-insert-before) | Inserts Release Note before Automation. |
+| 10 | `current` | [`replace`](../compose/md_composer_compose_actions.md#47-replace) | Replaces Automation with Reporting. |
+| 11 | `inline` | [`insert_between`](../compose/md_composer_compose_actions.md#46-insert-between) | Inserts Support Note between Release Note and Reporting. |
+| 12 | `current` | [`insert_after`](../compose/md_composer_compose_actions.md#45-insert-after) | Inserts Monitoring after Reporting. |
+| 13 | `buffer` | [`copy`](../compose/md_composer_compose_actions.md#48-copy) | Copies Release Note to the end; final dedupe removes the duplicate. |
+| 14 | `buffer` | [`modify`](../compose/md_composer_compose_actions.md#410-modify) | Modifies Dashboard in place, renaming it and inserting a paragraph. |
+| 15 | `buffer` | [`move`](../compose/md_composer_compose_actions.md#49-move) | Moves Advanced Preface into the body. |
+| 16-17 | `inline`, then `buffer` | [`remove_buffer_target`](../compose/md_composer_compose_actions.md#412-remove-buffer-target) | Adds and removes a temporary cleanup marker. |
+
+#### Transform Rows
+
+| Step | [Transform](../transform/md_composer_transform_transforms.md) | What it does |
+|------|-----------|--------------|
+| 1 | `dedupe` | Removes duplicate composed content by normalized text. |
+| 2 | `replace_text` | Renames `Feature Matrix` to `Advanced Composer Walkthrough`. |
+| 3 | `links` | Rewrites the first dashboard link to an absolute example URL. |
+| 4 | `heading_levels` | Promotes headings for the final output shape. |
+
+#### Output Shape
+
+The output starts with `# Advanced Composer Walkthrough`, then contains Dashboard Snapshot, Release Note, Support Note, Reporting, Monitoring, Welcome, Validation Snapshot, Release Checklist, and Advanced Preface sections.
+
+### 2.8 Complex Composer
+
+[complex_composer.rb](../../examples/complex_composer.rb) is the most comprehensive copy-paste walkthrough. It keeps sources inside `result = MarkdownComposer.compose(...)`, uses multiple explicit sources, demonstrates every source type and action, and adds a final generated Summary section.
+
+Run it from the gem root:
+
+```bash
+ruby -Ilib examples/complex_composer.rb
+```
+
+#### Sources
+
+| Key | Type | File | Purpose |
+|-----|------|------|---------|
+| `current` | `current` | [current.md](../../examples/fixtures/current.md) | Supplies feature, reporting, monitoring, and dashboard content. |
+| `guide` | `explicit` | [guide.md](../../examples/fixtures/guide.md) | Supplies validation and publishing sections. |
+| `faq` | `explicit` | [faq.md](../../examples/fixtures/faq.md) | Supplies Source Type Notes. |
+| `site_intro` | `inherited` | [site_intro.md](../../examples/fixtures/site_intro.md) | Supplies inherited Welcome content. |
+
+#### Composer Rows
+
+| Step | [Source](../compose/md_composer_compose_sources.md) | [Action](../compose/md_composer_compose_actions.md) | What it does |
+|------|--------|--------|--------------|
+| 1 | `current` | [`set`](../compose/md_composer_compose_actions.md#41-set) | Starts with a focused `Feature Matrix` slice. |
+| 2 | `inline` | [`prepend`](../compose/md_composer_compose_actions.md#43-prepend) | Adds Complex Preface before other content. |
+| 3-4 | `inherited`, then `buffer target` | [`append`](../compose/md_composer_compose_actions.md#42-append), [`transform_buffer_target`](../compose/md_composer_compose_actions.md#413-transform-buffer-target) | Appends and demotes Welcome. |
+| 5-8 | `explicit guide`, `previous`, then buffer targets | [`append`](../compose/md_composer_compose_actions.md#42-append), [`transform_buffer_target`](../compose/md_composer_compose_actions.md#413-transform-buffer-target) | Appends Validate and Publish, then demotes/renames them. |
+| 9-10 | `explicit faq`, then buffer target | [`append`](../compose/md_composer_compose_actions.md#42-append), [`transform_buffer_target`](../compose/md_composer_compose_actions.md#413-transform-buffer-target) | Adds Source Type Notes from FAQ content. |
+| 11-12 | `inline` | [`insert_before`](../compose/md_composer_compose_actions.md#44-insert-before), [`insert_between`](../compose/md_composer_compose_actions.md#46-insert-between) | Adds Release Note and Support Note around existing child sections. |
+| 13-14 | `current` | [`replace`](../compose/md_composer_compose_actions.md#47-replace), [`insert_after`](../compose/md_composer_compose_actions.md#45-insert-after) | Replaces Automation with Reporting and inserts Monitoring after it. |
+| 15 | `buffer` | [`copy`](../compose/md_composer_compose_actions.md#48-copy) | Copies Release Note; final dedupe removes the duplicate. |
+| 16 | `buffer` | [`modify`](../compose/md_composer_compose_actions.md#410-modify) | Renames Dashboard to Dashboard Snapshot and inserts an explanatory paragraph. |
+| 17 | `buffer` | [`move`](../compose/md_composer_compose_actions.md#49-move) | Moves Complex Preface into final reading order. |
+| 18-19 | `inline`, then `buffer` | [`append`](../compose/md_composer_compose_actions.md#42-append), [`remove_buffer_target`](../compose/md_composer_compose_actions.md#412-remove-buffer-target) | Adds and removes a Cleanup Marker. |
+
+#### Transform Rows
+
+| Step | [Transform](../transform/md_composer_transform_transforms.md) | What it does |
+|------|-----------|--------------|
+| 1 | `dedupe` | Removes copied duplicate content by normalized text. |
+| 2 | `replace_text` | Renames `Feature Matrix` to `Complex Composer Walkthrough`. |
+| 3 | `links` | Rewrites the first dashboard link to an absolute example URL. |
+| 4 | `heading_levels` | Promotes headings for final output. |
+| 5 | `insert_after` | Inserts a generated `## Summary` section after the lead paragraph. |
+
+#### Output Shape
+
+The output starts with `# Complex Composer Walkthrough`, includes a generated `## Summary`, then shows composed current, inherited, guide, FAQ, inline, and buffer-modified content.
+
+## 3. Copy-Paste Pattern
+
+Use `File.read` to load fixture Markdown, then pass sources into `MarkdownComposer.compose`:
+
+```ruby
+root = File.expand_path("../../examples", __dir__)
+
+sources = MarkdownComposer.source_list do
+  current File.read(File.join(root, "fixtures/current.md"))
+  explicit :guide, File.read(File.join(root, "fixtures/guide.md"))
+end
+
+result = MarkdownComposer.compose(sources: sources, plan: plan)
+```
+
+Runtime sources belong in `sources:`. Plan-only sources such as `inline`, `previous`, and `buffer` stay in compose rows.

data/docs/examples/md_composer_source_ruby_dsl.md

@@ -0,0 +1,88 @@
+---
+title: Markdown Composer Source Ruby DSL Example
+type: examples
+status: current
+updated: 2026-06-07
+description: Example for defining Markdown Composer runtime sources with the Ruby source_list DSL.
+---
+
+# Markdown Composer Source Ruby DSL Example
+
+### References
+
+| What | Where |
+|------|-------|
+| Source guide | [../compose/md_composer_compose_sources.md](../compose/md_composer_compose_sources.md) |
+| Fixture map | [./md_composer_example_fixtures.md](./md_composer_example_fixtures.md) |
+| Runnable examples | [./md_composer_runnable_examples.md](./md_composer_runnable_examples.md) |
+
+---
+
+## 1. Goal
+
+Define readable runtime sources in Ruby without hand-writing array-of-hash source records.
+
+## 2. Source List DSL
+
+```ruby
+sources = MarkdownComposer.source_list do
+  current File.read("examples/fixtures/current.md")
+  explicit :guide, File.read("examples/fixtures/guide.md")
+  explicit :faq, File.read("examples/fixtures/faq.md")
+  inherited :site_intro, File.read("examples/fixtures/site_intro.md")
+end
+```
+
+This returns the same source shape accepted by `MarkdownComposer.compose`.
+
+## 3. Use The Sources In A Plan
+
+```ruby
+plan = MarkdownComposer.plan do
+  from :current
+  select 'h2_section where title:equals("Overview")'
+  include "all"
+  set
+
+  from({ type: "explicit", key: "guide" })
+  select 'h2_section where title:equals("Validate")'
+  include "all"
+  append
+
+  from({ type: "inherited", key: "site_intro" })
+  select 'h2_section where title:equals("Welcome")'
+  include "heading_title"
+  include "paragraph[first:1]"
+  prepend
+end
+
+result = MarkdownComposer.compose(sources: sources, plan: plan)
+```
+
+## 4. Key Matching
+
+The key in a source definition is the key used by the plan:
+
+| Source definition | Plan reference |
+|-------------------|----------------|
+| `explicit :guide, ...` | `from({ type: "explicit", key: "guide" })` |
+| `explicit :faq, ...` | `from({ type: "explicit", key: "faq" })` |
+| `inherited :site_intro, ...` | `from({ type: "inherited", key: "site_intro" })` |
+
+`current` defaults to key `"current"`. If a plan has more than one current source, use keyed source references instead of ambiguous `from :current`.
+
+## 5. What Does Not Go In `source_list`
+
+`previous`, `buffer`, and `inline` are plan-row source references, not runtime source records:
+
+```ruby
+from :previous
+from :buffer
+from({ type: "inline", markdown: "## Note\n\nInline body." })
+```
+
+Runnable examples using this pattern:
+
+- [../../examples/source_list_dsl.rb](../../examples/source_list_dsl.rb)
+- [../../examples/advanced_composer.rb](../../examples/advanced_composer.rb)
+- [../../examples/complex_composer.rb](../../examples/complex_composer.rb)