markdown_composer 0.7.0

data/docs/_md_composer_getting_started.md

@@ -0,0 +1,114 @@
+---
+title: Markdown Composer Getting Started
+type: guide
+status: current
+updated: 2026-06-01
+description: First practical steps for composing Markdown with Markdown Composer.
+---
+
+# Markdown Composer Getting Started
+
+### References
+
+| What | Where |
+|------|-------|
+| Readme | [./_md_composer_readme.md](./_md_composer_readme.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) |
+| Basic compose example | [./examples/md_composer_example_basic_compose.md](./examples/md_composer_example_basic_compose.md) |
+
+---
+
+## 1. Install And Require
+
+```ruby
+require "markdown_composer"
+```
+
+The gem is headless. You provide sources and a plan; it returns Markdown, optional HTML, diagnostics, and errors.
+
+## 2. Create A Source
+
+A source is a hash with content and a source identity.
+
+```ruby
+sources = [
+  {
+    "key" => "guide",
+    "type" => "current",
+    "markdown" => "# Guide\n\n## Intro\n\nWelcome.\n\n## API\n\nUse it.\n"
+  }
+]
+```
+
+Use `current` for the main source. Use explicit keys when a plan needs more than one source.
+
+## 3. Write A Compose Row
+
+A compose row reads like this:
+
+```text
+From this Source, Select these units, Include these parts, then perform this Action at this Target.
+```
+
+Minimal config:
+
+```ruby
+config = {
+  "compose" => [
+    {
+      "source" => "current",
+      "select" => "heading_2_section[first:1]",
+      "include" => "all",
+      "action" => "set"
+    }
+  ]
+}
+```
+
+Expected output:
+
+```markdown
+## Intro
+
+Welcome.
+```
+
+## 4. Validate Before Saving
+
+```ruby
+validation = MarkdownComposer.validate(config: config, sources: sources)
+abort validation[:errors].inspect unless validation[:valid]
+```
+
+Validation catches unknown tokens, bad targets, missing transform options, YAML/JSON errors, and policy-gated features.
+
+## 5. Add A Transform
+
+Top-level transforms run after all compose rows have built the buffer.
+
+```ruby
+config = {
+  "compose" => [
+    { "select" => "heading_2_section", "action" => "set" }
+  ],
+  "transform" => [
+    {
+      "scope" => "output",
+      "transform" => "replace_text",
+      "mode" => "literal",
+      "options" => { "from" => "Welcome", "to" => "Hello" }
+    }
+  ]
+}
+```
+
+## 6. Next Steps
+
+| Need | Read |
+|------|------|
+| Learn row anatomy | [Compose anatomy](./compose/md_composer_compose_anatomy.md) |
+| Learn transforms | [Transform anatomy](./transform/md_composer_transform_anatomy.md) |
+| See complete examples | [Examples](./examples/md_composer_examples_readme.md) |
+| Use Ruby DSL plans | [Ruby plans example](./examples/md_composer_example_ruby_plans.md) |
+

data/docs/_md_composer_readme.md

@@ -0,0 +1,93 @@
+---
+title: Markdown Composer Readme
+type: readme
+status: current
+updated: 2026-06-01
+description: Public overview for the Markdown Composer gem documentation.
+---
+
+# Markdown Composer Readme
+
+### 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) |
+| Examples | [./examples/md_composer_examples_readme.md](./examples/md_composer_examples_readme.md) |
+| API reference | [./reference/md_composer_reference_api.md](./reference/md_composer_reference_api.md) |
+| Unit tokens | [./reference/md_composer_unit_tokens.md](./reference/md_composer_unit_tokens.md) |
+| Take modifiers | [./reference/md_composer_take.md](./reference/md_composer_take.md) |
+| Where conditions | [./reference/md_composer_where.md](./reference/md_composer_where.md) |
+
+---
+
+## 1. What Markdown Composer Does
+
+Markdown Composer is a headless Ruby gem for selecting, composing, modifying, and transforming Markdown or best-effort HTML content. It is useful when an application needs to build a new Markdown document from one or more sources without hand-writing string slicing logic.
+
+The core model has two row types:
+
+```text
+Compose:   Source -> Select -> Include -> Action -> Target
+Transform: Scope  -> Transform -> Mode    -> Options
+```
+
+Compose rows build a temporary output buffer. Transform rows reshape that buffer after composition.
+
+## 2. Sixty-Second Example
+
+```ruby
+require "markdown_composer"
+
+sources = [
+  {
+    "key" => "current",
+    "type" => "current",
+    "markdown" => "# Guide\n\n## Intro\n\nKeep this.\n\n## Draft\n\nSkip this.\n"
+  }
+]
+
+config = {
+  "compose" => [
+    {
+      "source" => "current",
+      "select" => "heading_2_section where title:equals(\"Intro\")",
+      "include" => "all",
+      "action" => "set"
+    }
+  ],
+  "output" => "markdown"
+}
+
+result = MarkdownComposer.compose(sources: sources, config: config)
+puts result.markdown
+```
+
+Expected output:
+
+```markdown
+## Intro
+
+Keep this.
+```
+
+## 3. Where To Start
+
+| If you want to... | Read |
+|-------------------|------|
+| Compose your first document | [Getting started](./_md_composer_getting_started.md) |
+| Understand compose rows | [Compose anatomy](./compose/md_composer_compose_anatomy.md) |
+| Learn each compose field | [Sources](./compose/md_composer_compose_sources.md), [Select](./compose/md_composer_compose_select.md), [Include](./compose/md_composer_compose_include.md), [Actions](./compose/md_composer_compose_actions.md), [Targets](./compose/md_composer_compose_targets.md) |
+| Find every unit token | [Unit tokens](./reference/md_composer_unit_tokens.md) |
+| Choose first, last, ranges, or positions | [Take modifiers](./reference/md_composer_take.md) |
+| Filter selections, includes, targets, or scopes | [Where conditions](./reference/md_composer_where.md) |
+| Transform composed output | [Transform anatomy](./transform/md_composer_transform_anatomy.md) |
+| Use `modify` | [Modify examples](./examples/md_composer_example_modify.md) |
+| Build a GUI | [Capabilities reference](./reference/md_composer_reference_capabilities.md) |
+| Validate or debug configs | [Diagnostics reference](./reference/md_composer_reference_diagnostics.md) |
+
+## 4. Public Documentation Shape
+
+This `docs/` tree is the human-facing documentation set for GitHub and RubyGems readers. The `docs/ai/` directory is not the main reader path; it maps these public docs back to canonical audited source material.

data/docs/_md_composer_user_guide.md

@@ -0,0 +1,65 @@
+---
+title: Markdown Composer User Guide
+type: user_guide
+status: current
+updated: 2026-06-01
+description: Public user guide for learning Markdown Composer by task.
+---
+
+# Markdown Composer User Guide
+
+### References
+
+| What | Where |
+|------|-------|
+| Getting started | [./_md_composer_getting_started.md](./_md_composer_getting_started.md) |
+| Compose docs | [./compose/md_composer_compose_anatomy.md](./compose/md_composer_compose_anatomy.md) |
+| Transform docs | [./transform/md_composer_transform_anatomy.md](./transform/md_composer_transform_anatomy.md) |
+| Unit tokens | [./reference/md_composer_unit_tokens.md](./reference/md_composer_unit_tokens.md) |
+| Take modifiers | [./reference/md_composer_take.md](./reference/md_composer_take.md) |
+| Where conditions | [./reference/md_composer_where.md](./reference/md_composer_where.md) |
+| Examples | [./examples/md_composer_examples_readme.md](./examples/md_composer_examples_readme.md) |
+
+---
+
+## 1. Learning Path
+
+1. Start with [Getting started](./_md_composer_getting_started.md).
+2. Learn [compose anatomy](./compose/md_composer_compose_anatomy.md).
+3. Learn [selection](./compose/md_composer_compose_select.md), then the shared [unit tokens](./reference/md_composer_unit_tokens.md), [take modifiers](./reference/md_composer_take.md), and [where conditions](./reference/md_composer_where.md).
+4. Learn [actions](./compose/md_composer_compose_actions.md) and [targets](./compose/md_composer_compose_targets.md).
+5. Learn [transform anatomy](./transform/md_composer_transform_anatomy.md) and [options](./transform/md_composer_transform_options.md).
+6. Copy a task from [examples](./examples/md_composer_examples_readme.md).
+
+## 2. Common Tasks
+
+| Task | Read |
+|------|------|
+| Pull one section from a document | [Basic compose](./examples/md_composer_example_basic_compose.md) |
+| Build output from several rows | [Multi-row compose](./examples/md_composer_example_multi_row_compose.md) |
+| Rewrite selected content while composing | [Modify](./examples/md_composer_example_modify.md) |
+| Remove or transform content already in the buffer | [Buffer target actions](./examples/md_composer_example_buffer_target_actions.md) |
+| Extract YAML/JSON values | [Structured data](./examples/md_composer_example_structured_data.md) |
+| Use Ruby plans | [Ruby plans](./examples/md_composer_example_ruby_plans.md) |
+
+## 3. Rules Of Thumb
+
+| Rule | Why it helps |
+|------|--------------|
+| Build the buffer first, then transform it. | This keeps compose and transform concerns separate. |
+| Prefer `heading_2_section` over `heading_2` when you want a heading and its body. | Heading tokens select only the heading node. Section tokens select the heading and content until the next same-or-higher heading. |
+| Use `include` to narrow selected content. | `select` chooses units; `include` chooses what to keep from those units. |
+| Use `modify` for selected-source transformations. | It is a compose action that transforms a temporary fragment before placing it. |
+| Use `transform_buffer_target` for existing buffer content. | It transforms content already in the buffer by target. |
+
+## 4. When You Get Stuck
+
+Run validation and inspect diagnostics before guessing:
+
+```ruby
+validation = MarkdownComposer.validate(config: config, sources: sources)
+pp validation[:errors]
+pp validation[:diagnostics]
+```
+
+Most authoring mistakes are field-specific: unknown selector, invalid target, missing transform option, or policy-gated feature.

data/docs/ai/md_composer_ai_audit.md

@@ -0,0 +1,35 @@
+---
+title: Markdown Composer AI Audit Notes
+type: reference
+status: current
+updated: 2026-06-01
+description: Maintainer and AI audit notes for caveats in public Markdown Composer docs.
+---
+
+# Markdown Composer AI Audit Notes
+
+### References
+
+| What | Where |
+|------|-------|
+| Source map | [./md_composer_ai_source_map.md](./md_composer_ai_source_map.md) |
+| Capabilities reference | [../reference/md_composer_reference_capabilities.md](../reference/md_composer_reference_capabilities.md) |
+
+---
+
+## 1. Required Public Caveats
+
+| Caveat | Public docs that must mention it |
+|--------|----------------------------------|
+| `data_record` and `data_value` are transient `data_path(...)` result node types in standalone Markdown output. | Targets, include, structured data, registries, architecture |
+| `set`, `append`, and `prepend` ignore supplied custom targets. | Actions |
+| `remove_buffer_target` and `transform_buffer_target` use target as the meaningful address. | Actions, buffer, buffer examples |
+| `modify target: in_place` requires original `source: "buffer"`. | Actions, targets, modify example |
+| Semicolon option strings are first-class, not fallback-only. | Transform options |
+| HTML link attribute modes are top-level HTML-output post-processing. | Transform modes, HTML output example |
+| Some optional transform metadata is ahead of standalone runner behavior. | Transform anatomy, options, capabilities |
+
+## 2. Code Accuracy Rule
+
+Before publishing changed examples, run focused Ruby probes and the full gem test suite.
+

data/docs/ai/md_composer_ai_canonical_docs.md

@@ -0,0 +1,44 @@
+---
+title: Markdown Composer AI Canonical Docs
+type: reference
+status: current
+updated: 2026-06-01
+description: Maintainer and AI map of canonical Markdown Composer docs used as source material.
+---
+
+# Markdown Composer AI Canonical Docs
+
+### References
+
+| What | Where |
+|------|-------|
+| Source map | [./md_composer_ai_source_map.md](./md_composer_ai_source_map.md) |
+| Public readme | [../_md_composer_readme.md](../_md_composer_readme.md) |
+
+---
+
+## 1. Canonical Source Location
+
+The canonical project docs live outside this gem directory:
+
+```text
+_docs/gems/markdown_composer/
+```
+
+This public `docs/` tree is the gem distribution docs set. It should be clear, task-based, and human-facing.
+
+## 2. Canonical Files Used
+
+| Topic | Canonical files |
+|-------|-----------------|
+| Overview | `_markdown_composer_readme.md`, `_markdown_composer_user_guide.md`, `_markdown_composer_cheatsheet.md` |
+| Architecture | `_markdown_composer_architecture.md`, `reference/markdown_composer_capabilities.md`, `reference/markdown_composer_registries.md` |
+| Compose | `reference/markdown_composer_compose.md`, sources, selection, include, actions, targets, take, where |
+| Transform | `reference/markdown_composer_transforms.md`, capabilities, actions |
+| Examples | `markdown_composer_examples.md` |
+| Release | `release/markdown_composer_release_checklist.md` |
+
+## 3. Do Not Publish This As The Main Entry
+
+Link readers to [../_md_composer_readme.md](../_md_composer_readme.md), not to this file.
+

data/docs/ai/md_composer_ai_source_map.md

@@ -0,0 +1,39 @@
+---
+title: Markdown Composer AI Source Map
+type: reference
+status: current
+updated: 2026-06-01
+description: Maintainer and AI source map for public Markdown Composer docs.
+---
+
+# Markdown Composer AI Source Map
+
+### References
+
+| What | Where |
+|------|-------|
+| AI audit | [./md_composer_ai_audit.md](./md_composer_ai_audit.md) |
+| Canonical docs map | [./md_composer_ai_canonical_docs.md](./md_composer_ai_canonical_docs.md) |
+| Public readme | [../_md_composer_readme.md](../_md_composer_readme.md) |
+
+---
+
+## 1. Purpose
+
+This directory is for maintainers and AI agents. It is not the main public reader path.
+
+Use it to trace public docs back to canonical audited source material under `_docs/gems/markdown_composer/` and gem code/tests.
+
+## 2. Public-To-Canonical Map
+
+| Public doc area | Canonical source material |
+|-----------------|---------------------------|
+| Root overview docs | `_docs/gems/markdown_composer/_markdown_composer_readme.md`, user guide, cheatsheet, architecture, dev guide |
+| `compose/` | canonical compose, sources, selection, include, actions, targets, take, where docs |
+| `transform/` | canonical transforms, capabilities, actions, targets docs |
+| `examples/` | canonical examples plus focused tests |
+| `reference/` | canonical API, plan schema, diagnostics, capabilities, registries, unit-token, take, and where-condition docs |
+
+## 3. Update Rule
+
+When code changes, update canonical source material and these public docs together. Do not let `docs/ai/` become a second public docs set.