markdown_composer 0.7.0

data/docs/reference/md_composer_take.md

@@ -0,0 +1,221 @@
+---
+title: Markdown Composer Take Modifiers
+type: reference
+status: current
+updated: 2026-06-01
+description: Public reference for Markdown Composer take syntax, operators, ordering, ranges, percentages, random selection, and field-take usage.
+---
+
+# Markdown Composer Take Modifiers
+
+### References
+
+| What | Where |
+|------|-------|
+| Unit tokens | [./md_composer_unit_tokens.md](./md_composer_unit_tokens.md) |
+| Where conditions | [./md_composer_where.md](./md_composer_where.md) |
+| Select syntax | [../compose/md_composer_compose_select.md](../compose/md_composer_compose_select.md) |
+| Include syntax | [../compose/md_composer_compose_include.md](../compose/md_composer_compose_include.md) |
+| Target syntax | [../compose/md_composer_compose_targets.md](../compose/md_composer_compose_targets.md) |
+| Transform scope | [../transform/md_composer_transform_scope.md](../transform/md_composer_transform_scope.md) |
+| Diagnostics | [./md_composer_reference_diagnostics.md](./md_composer_reference_diagnostics.md) |
+
+---
+
+## 1. Purpose
+
+`take` narrows an ordered set of matched units.
+
+```ruby
+{ "select" => "heading_2_section[first:2]" }
+```
+
+Take is shared selector syntax. You can use it anywhere selector-like fields accept a unit token:
+
+| Field | Example |
+|-------|---------|
+| Compose `select` | `heading_2_section[position:2,3]` |
+| Compose `include` | `paragraph[first:1]` |
+| Compose `target` | `heading_2_section[last:1]` |
+| Transform `scope` | `paragraph[odd]` |
+
+## 2. Syntax Anatomy
+
+Take lives inside square brackets immediately after the unit token.
+
+```text
+selector = unit_token [take] [where condition]
+
+take = [operator]
+     | [operator:value]
+     | [operator:value,value]
+     | [operator:range]
+
+range = n..n | n..last
+```
+
+Examples:
+
+```text
+paragraph[first:2]
+heading_2_section[position:2,3]
+heading_2_section[range:2..4]
+list_item[odd]
+table_row[except:1]
+```
+
+Write order and match order:
+
+| Step | Meaning |
+|------|---------|
+| Write order | `unit_token[take] where condition` |
+| Match order | Match unit token, filter with `where`, then apply take to the filtered results. |
+
+Positions are 1-based. Position `0` is invalid. Negative positions count from the end in structured take values.
+
+## 3. Operator Table
+
+This table is generated from the current public capabilities contract.
+
+| Operator | Alias | Value | Support | Meaning |
+|----------|-------|-------|---------|---------|
+| `all` | | none | normal | Keep all matches. |
+| `first` | | positive integer | normal | Keep the first N matches. |
+| `last` | | positive integer | normal | Keep the last N matches. |
+| `position` | | integer list | normal | Keep one or more 1-based positions. |
+| `ranges` | `range` | range list | normal | Keep one or more inclusive ranges. |
+| `skip` | | positive integer | normal | Ignore the first N matches. |
+| `skip_last` | | positive integer | normal | Ignore the last N matches. |
+| `every` | | positive integer | normal | Keep every Nth match. |
+| `odd` | | none | normal | Keep odd 1-based positions. |
+| `even` | | none | normal | Keep even 1-based positions. |
+| `except` | | integer list | normal | Keep all except selected positions. |
+| `top_percent` | | percent | advanced | Keep a percentage from the start. |
+| `bottom_percent` | | percent | advanced | Keep a percentage from the end. |
+| `middle` | | positive integer | advanced | Keep N matches from the middle. |
+| `middle_percent` | | percent | advanced | Keep a percentage from the middle. |
+| `alternate` | | positive integer | advanced | Keep alternating groups of matches. |
+| `random` | | positive integer | advanced | Keep seeded random matches. |
+
+## 4. Common Take Forms
+
+| Need | Syntax |
+|------|--------|
+| First match | `paragraph[first:1]` |
+| First three matches | `paragraph[first:3]` |
+| Last match | `heading_2_section[last:1]` |
+| Positions two and three | `heading_2_section[position:2,3]` |
+| Range two through four | `heading_2_section[range:2..4]` |
+| Every second item | `list_item[every:2]` |
+| Odd items | `list_item[odd]` |
+| Even items | `list_item[even]` |
+| All except first and third | `paragraph[except:1,3]` |
+| Skip the first match | `paragraph[skip:1]` |
+| Skip the last match | `paragraph[skip_last:1]` |
+
+## 5. Ranges And Positions
+
+Use `position` for a list of exact positions:
+
+```ruby
+{ "select" => "heading_2_section[position:1,3]" }
+```
+
+Use `range` or canonical `ranges` for inclusive spans:
+
+```ruby
+{ "select" => "heading_2_section[range:2..4]" }
+```
+
+Use `last` in ranges when the end should be the final match:
+
+```ruby
+{ "select" => "heading_2_section[range:2..last]" }
+```
+
+Multiple selected indexes are de-duplicated and returned in source order.
+
+## 6. Advanced Take Forms
+
+Advanced operators are exposed by capabilities, but they should be presented carefully in public authoring UIs.
+
+| Need | Syntax |
+|------|--------|
+| First quarter of matches | `paragraph[top_percent:25]` |
+| Last quarter of matches | `paragraph[bottom_percent:25]` |
+| Middle three matches | `paragraph[middle:3]` |
+| Middle half of matches | `paragraph[middle_percent:50]` |
+| Alternating groups of two | `list_item[alternate:2]` |
+| Seeded random sample of three | `paragraph[random:3]` |
+
+`random` is deterministic when the selection runner is given a seed. Validate random-selection plans before relying on them in reproducible docs or tests.
+
+## 7. Include Take
+
+In `include`, take runs inside each selected unit.
+
+```ruby
+{
+  "select" => "heading_2_section[position:1,2]",
+  "include" => "paragraph[first:1]"
+}
+```
+
+This keeps the first paragraph from each selected section. It does not keep the first paragraph across the whole source document.
+
+## 8. Target And Scope Take
+
+In `target`, take matches against the current composition buffer:
+
+```ruby
+{
+  "action" => "replace",
+  "target" => "paragraph[first:1] where text:contains(\"TODO\")"
+}
+```
+
+In transform `scope`, take matches against the composed output or row-level fragment:
+
+```ruby
+{
+  "scope" => "heading_2_section[last:1]",
+  "transform" => "replace_text",
+  "mode" => "literal",
+  "options" => "from:Draft; to:Final"
+}
+```
+
+## 9. Field-Take In Where
+
+Where conditions have a separate field-take form for text fields:
+
+```text
+source_text[first:1]:contains("::-")
+text[first:5]:contains("Warning")
+title[first:2]:equals("API")
+```
+
+This is not the same as selector take. Selector take chooses matched units; field-take narrows words inside a field value before comparing.
+
+## 10. Diagnostics
+
+| Situation | Diagnostic family |
+|-----------|-------------------|
+| Unknown take operator | `take.invalid` |
+| Positive count operator is zero or negative | `take.invalid` |
+| `position` or `except` includes zero | `take.invalid` |
+| Range missing `from` or `to` | `take.invalid` |
+| Range includes zero | `take.invalid` |
+| Unsupported field-take in `where` | `where.field_take_unsupported` |
+| Invalid field-take in `where` | `where.field_take_invalid` |
+
+## 11. Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Calling `take` an action. | Put take inside `select`, `include`, `target`, or `scope` selectors. |
+| Assuming include take runs globally. | Include take runs inside each selected unit. |
+| Using position zero. | Use 1-based positions. |
+| Expecting target take to search source documents. | Target take searches the current buffer. |
+| Expecting scope take to search source documents. | Scope take searches composed output or a row-level fragment. |
+| Mixing selector take and field-take. | Use selector take for units; use field-take inside `where` text fields. |

data/docs/reference/md_composer_unit_tokens.md

@@ -0,0 +1,228 @@
+---
+title: Markdown Composer Unit Tokens
+type: reference
+status: current
+updated: 2026-06-01
+description: Public reference for every Markdown Composer unit token, alias, and supported use context.
+---
+
+# Markdown Composer Unit Tokens
+
+### References
+
+| What | Where |
+|------|-------|
+| Select syntax | [../compose/md_composer_compose_select.md](../compose/md_composer_compose_select.md) |
+| Include syntax | [../compose/md_composer_compose_include.md](../compose/md_composer_compose_include.md) |
+| Target syntax | [../compose/md_composer_compose_targets.md](../compose/md_composer_compose_targets.md) |
+| Transform scope | [../transform/md_composer_transform_scope.md](../transform/md_composer_transform_scope.md) |
+| Registries | [./md_composer_reference_registries.md](./md_composer_reference_registries.md) |
+| Capabilities | [./md_composer_reference_capabilities.md](./md_composer_reference_capabilities.md) |
+| Take modifiers | [./md_composer_take.md](./md_composer_take.md) |
+| Where conditions | [./md_composer_where.md](./md_composer_where.md) |
+
+---
+
+## 1. Purpose
+
+Unit tokens name the Markdown Composer units that can be selected, included, targeted, or transformed.
+
+```ruby
+{ "select" => "heading_2_section[first:1]" }
+{ "include" => "heading_title, paragraph[first:1]" }
+{ "target" => "paragraph where text:contains(\"TODO\")" }
+{ "scope" => "heading_2_section where title:equals(\"API\")" }
+```
+
+Use canonical tokens in saved plans. Aliases are accepted for authoring convenience and normalize to canonical tokens.
+
+## 2. Syntax Anatomy
+
+Unit tokens appear inside selector-like fields.
+
+```text
+selector = unit_token [take] [where condition]
+
+include_item = unit_token [take] [where condition]
+
+target_selector = unit_token [take] [where condition]
+
+scope_selector = unit_token [take] [where condition]
+```
+
+For bracketed take syntax, see [Take Modifiers](./md_composer_take.md).
+For `where` field, predicate, and group syntax, see [Where Conditions](./md_composer_where.md).
+
+Context support matters:
+
+| Support value | Meaning |
+|---------------|---------|
+| `normal` | Supported for ordinary use in that context. |
+| `include_only` | Only valid as an include item. |
+| `output_only` | Only meaningful against composed/structured output. |
+| `advanced` | Exposed as an advanced token; validate against the exact plan behavior. |
+| `adapter_policy` | Requires host policy. |
+| `disabled` | Do not use in that context. |
+
+## 3. Full Token List
+
+This table is generated from the current public capabilities contract.
+
+| Token | Alias | Select | Include | Target | Scope | Meaning |
+|-------|-------|--------|---------|--------|-------|---------|
+| `all` | | normal | normal | disabled | disabled | Whole available content. |
+| `output` | | disabled | disabled | normal | output_only | Whole composed output. |
+| `content` | | disabled | include_only | disabled | advanced | Content inside the selected unit. |
+| `heading_title` | `title` | disabled | include_only | advanced | advanced | Section heading title. |
+| `section` | `sections` | normal | normal | normal | normal | Heading-defined section at any level. |
+| `heading` | `headings` | normal | normal | normal | normal | Heading node at any level. |
+| `paragraph` | `p` | normal | normal | normal | normal | Paragraph node. |
+| `link` | `a` | normal | normal | normal | normal | Link node. |
+| `image` | `img` | normal | normal | normal | normal | Image node. |
+| `list` | | normal | normal | normal | normal | Any list node. |
+| `unordered_list` | `ul` | normal | normal | normal | normal | Bullet list. |
+| `ordered_list` | `ol` | normal | normal | normal | normal | Numbered list. |
+| `list_item` | `li` | normal | normal | normal | normal | List item. |
+| `blockquote` | | normal | normal | normal | normal | Blockquote. |
+| `table` | | normal | normal | normal | normal | Whole table. |
+| `table_head` | `thead` | advanced | advanced | advanced | advanced | Table header group. |
+| `table_body` | `tbody` | advanced | advanced | advanced | advanced | Table body group. |
+| `table_row` | `tr` | advanced | advanced | advanced | advanced | Table row. |
+| `table_header` | `th` | advanced | advanced | advanced | advanced | Header cell. |
+| `table_cell` | `td` | advanced | advanced | advanced | advanced | Table cell. |
+| `code_block` | | normal | normal | normal | normal | Fenced or block code. |
+| `inline_code` | | normal | normal | normal | normal | Inline code span. |
+| `data_block` | | normal | normal | advanced | advanced | Structured YAML/JSON block. |
+| `data_path` | | disabled | include_only | disabled | advanced | Structured data path extraction. |
+| `data_record` | | disabled | disabled | advanced | output_only | Derived structured data record. |
+| `data_value` | | disabled | disabled | advanced | output_only | Derived structured data value. |
+| `mermaid` | | normal | normal | normal | normal | Mermaid diagram block. |
+| `math_block` | | normal | normal | normal | normal | Display math block. |
+| `inline_math` | | normal | normal | normal | normal | Inline math span. |
+| `comment` | | normal | normal | normal | normal | Comment node. |
+| `raw_html` | | adapter_policy | adapter_policy | adapter_policy | adapter_policy | Raw HTML node. |
+| `heading_1_section` | `h1_section` | normal | normal | normal | normal | H1 section. |
+| `heading_1` | `h1` | normal | normal | normal | normal | H1 heading node. |
+| `heading_2_section` | `h2_section` | normal | normal | normal | normal | H2 section. |
+| `heading_2` | `h2` | normal | normal | normal | normal | H2 heading node. |
+| `heading_3_section` | `h3_section` | normal | normal | normal | normal | H3 section. |
+| `heading_3` | `h3` | normal | normal | normal | normal | H3 heading node. |
+| `heading_4_section` | `h4_section` | normal | normal | normal | normal | H4 section. |
+| `heading_4` | `h4` | normal | normal | normal | normal | H4 heading node. |
+| `heading_5_section` | `h5_section` | normal | normal | normal | normal | H5 section. |
+| `heading_5` | `h5` | normal | normal | normal | normal | H5 heading node. |
+| `heading_6_section` | `h6_section` | normal | normal | normal | normal | H6 section. |
+| `heading_6` | `h6` | normal | normal | normal | normal | H6 heading node. |
+
+## 4. Section And Heading Tokens
+
+Use section tokens when you want a heading and its body.
+
+```ruby
+{ "select" => "heading_2_section where title:equals(\"Install\")" }
+```
+
+Use heading tokens when you only want the heading node.
+
+```ruby
+{ "select" => "heading_2 where text:contains(\"Install\")" }
+```
+
+Generic section and heading tokens are useful when the exact heading level does not matter:
+
+```ruby
+{ "select" => "section where title:contains(\"API\")" }
+{ "scope" => "heading" }
+```
+
+## 5. Include-Only Tokens
+
+`content`, `heading_title`, and `data_path` are include-oriented tokens.
+
+```ruby
+{
+  "select" => "heading_2_section[first:1]",
+  "include" => "heading_title, paragraph[first:1]"
+}
+```
+
+`content` keeps the body content inside the selected unit:
+
+```ruby
+{
+  "select" => "heading_2_section where title:equals(\"Intro\")",
+  "include" => "content"
+}
+```
+
+`data_path(...)` extracts values from selected structured data blocks:
+
+```ruby
+{
+  "select" => "data_block where format:equals(\"yaml\")",
+  "include" => "data_path(\"metadata.title\")"
+}
+```
+
+## 6. Structured Data Tokens
+
+`data_block` is the normal token for selecting YAML or JSON blocks.
+
+```ruby
+{ "select" => "data_block where format:equals(\"json\")" }
+```
+
+`data_record` and `data_value` are derived node types produced by `data_path(...)`.
+
+In standalone Markdown output, extracted data is serialized back to Markdown text, and later target/scope matching reparses that Markdown. Treat `data_record` and `data_value` as structured-output metadata unless a host adapter preserves them as matchable buffer nodes.
+
+## 7. Table Tokens
+
+`table` is the practical token for most table work.
+
+```ruby
+{ "select" => "table[first:1]" }
+```
+
+Table substructure tokens are available as advanced tokens:
+
+```ruby
+{ "select" => "table_row[position:2]" }
+{ "include" => "table_cell" }
+```
+
+Validate table substructure plans carefully because Markdown table parsing can depend on the source shape.
+
+## 8. Policy-Gated Tokens
+
+`raw_html` requires host policy.
+
+```ruby
+{ "select" => "raw_html" }
+```
+
+Do not expose `raw_html` as an ordinary public control unless the host explicitly enables adapter-policy tokens and accepts the security boundary.
+
+## 9. Common Recipes
+
+| Need | Token syntax |
+|------|--------------|
+| First H2 section | `heading_2_section[first:1]` |
+| H2 section by title | `heading_2_section where title:equals("API")` |
+| Paragraphs containing text | `paragraph where text:contains("warning")` |
+| First Ruby code block | `code_block[first:1] where language:equals("ruby")` |
+| Any image | `image` |
+| List items two and three | `list_item[position:2,3]` |
+| Structured data block | `data_block where format:equals("yaml")` |
+| Whole table | `table` |
+| All headings | `heading` |
+
+## 10. Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Using `heading_2` when you need the section body. | Use `heading_2_section`. |
+| Using `heading_title` as a top-level `select`. | Select a section, then include `heading_title`. |
+| Using `data_path` outside `include`. | Select `data_block`, then use `include: "data_path(...)"`. |
+| Treating `data_value` as a normal post-compose selector. | Target serialized Markdown text or use a host that preserves structured nodes. |
+| Offering `raw_html` in a public UI without policy. | Gate it behind explicit host policy. |

data/docs/reference/md_composer_where.md

@@ -0,0 +1,227 @@
+---
+title: Markdown Composer Where Conditions
+type: reference
+status: current
+updated: 2026-06-01
+description: Public reference for Markdown Composer where syntax, fields, predicates, groups, and shared selector usage.
+---
+
+# Markdown Composer Where Conditions
+
+### References
+
+| What | Where |
+|------|-------|
+| Unit tokens | [./md_composer_unit_tokens.md](./md_composer_unit_tokens.md) |
+| Take modifiers | [./md_composer_take.md](./md_composer_take.md) |
+| Select syntax | [../compose/md_composer_compose_select.md](../compose/md_composer_compose_select.md) |
+| Include syntax | [../compose/md_composer_compose_include.md](../compose/md_composer_compose_include.md) |
+| Target syntax | [../compose/md_composer_compose_targets.md](../compose/md_composer_compose_targets.md) |
+| Transform scope | [../transform/md_composer_transform_scope.md](../transform/md_composer_transform_scope.md) |
+| Diagnostics | [./md_composer_reference_diagnostics.md](./md_composer_reference_diagnostics.md) |
+
+---
+
+## 1. Purpose
+
+`where` filters matched units by field predicates.
+
+```ruby
+{ "select" => "heading_2_section where title:contains(\"API\")" }
+```
+
+`where` is shared selector syntax. You can use it anywhere a selector-like field accepts it:
+
+| Field | Example |
+|-------|---------|
+| Compose `select` | `heading_2_section where title:equals("Install")` |
+| Compose `include` | `paragraph where text:contains("warning")` |
+| Compose `target` | `paragraph where text:contains("TODO")` |
+| Transform `scope` | `code_block where language:equals("ruby")` |
+
+## 2. Syntax Anatomy
+
+Write a `where` condition after the unit token and bracketed take modifier.
+
+```text
+selector = unit_token [take] where condition
+
+condition = field:predicate(value)
+          | field:exists
+          | field:equals(value)
+          | field:value
+          | group(condition; condition; ...)
+
+group = all | any | none | not | xor
+```
+
+For selector-level take syntax, see [Take Modifiers](./md_composer_take.md).
+
+Common compact forms:
+
+```text
+title:contains("API")
+text:equals("Draft")
+links:exists
+empty:false
+position:range(2..4)
+any(title:contains("API"); title:contains("CLI"))
+not(empty:true)
+```
+
+Syntax order and execution order are slightly different:
+
+| Step | Meaning |
+|------|---------|
+| Write order | `unit_token[take] where condition` |
+| Match order | Match unit token, filter with `where`, then apply take to the filtered results. |
+
+## 3. Fields
+
+| Field | Predicates | Use for |
+|-------|------------|---------|
+| `title` | `contains`, `starts_with`, `ends_with`, `equals`, `matches` | Heading or section titles. |
+| `text` | `contains`, `starts_with`, `ends_with`, `equals`, `matches` | Visible text content. |
+| `source_text` | `contains`, `starts_with`, `ends_with`, `equals`, `matches` | Retained source representation. |
+| `position` | `equals`, `range` | 1-based position among matched units. |
+| `language` | `equals` | Fenced code language. |
+| `diagram_type` | `equals` | Normalized Mermaid diagram type. |
+| `format` | `equals` | Structured data format, such as YAML or JSON. |
+| `location` | `equals` | Structured data location metadata. |
+| `links` | `exists` | Units containing links. |
+| `images` | `exists` | Units containing images. |
+| `code` | `exists` | Units containing code. |
+| `numbers` | `exists` | Text containing digits. |
+| `empty` | `equals` | Empty or non-empty units. |
+| `length` | `min`, `max`, `range` | Character length. |
+| `word_count` | `min`, `max`, `range` | Word count. |
+| `child` | `exists` | Sections with nested child sections. |
+
+Capability metadata currently exposes some where fields and groups with `enabled: false` even though the condition map documents usable predicates. GUI builders should consult `capabilities["where"]["condition_map"]` as the practical field-to-predicate map.
+
+## 4. Predicates
+
+| Predicate | Value | Example |
+|-----------|-------|---------|
+| `contains` | text | `text:contains("warning")` |
+| `starts_with` | text | `title:starts_with("API")` |
+| `ends_with` | text | `title:ends_with("Reference")` |
+| `equals` | scalar | `language:equals("ruby")` |
+| `range` | range | `position:range(2..4)` |
+| `exists` | none | `links:exists` |
+| `min` | number | `word_count:min(20)` |
+| `max` | number | `length:max(280)` |
+| `matches` | regex | `text:matches("^TODO")` |
+
+`matches` is advanced regex matching. Validate regex conditions before exposing them in a public authoring UI.
+
+## 5. Groups
+
+Groups combine conditions. Child conditions are separated with top-level semicolons.
+
+Group tokens are `all`, `any`, `none`, `not`, and `xor`.
+
+| Group | Meaning | Example |
+|-------|---------|---------|
+| `all(...)` | Every child condition must match. | `all(title:contains("API"); links:exists)` |
+| `any(...)` | At least one child condition must match. | `any(title:contains("API"); title:contains("CLI"))` |
+| `none(...)` | No child condition may match. | `none(text:contains("Deprecated"); links:exists)` |
+| `not(...)` | Negates one condition or group. | `not(empty:true)` |
+| `xor(...)` | Exactly one child condition must match. | `xor(links:exists; images:exists)` |
+
+Use semicolons inside groups, not commas:
+
+```text
+any(title:contains("API"); title:contains("CLI"))
+```
+
+## 6. Field-Take
+
+Text fields can apply bracketed field-take before the predicate compares values.
+
+```text
+source_text[first:1]:contains("::-")
+title[first:2]:contains("API")
+```
+
+Field-take is supported for:
+
+| Field | Example |
+|-------|---------|
+| `title` | `title[first:1]:equals("Install")` |
+| `text` | `text[first:5]:contains("Warning")` |
+| `source_text` | `source_text[first:1]:contains("::-")` |
+
+Use field-take when you need to test part of a text field rather than the whole field.
+
+## 7. Shared Field Examples
+
+### 7.1. Select
+
+```ruby
+{
+  "select" => "heading_2_section where title:contains(\"API\")",
+  "action" => "set"
+}
+```
+
+### 7.2. Include
+
+```ruby
+{
+  "select" => "heading_2_section",
+  "include" => "paragraph where text:contains(\"warning\")"
+}
+```
+
+The include condition runs inside each selected section.
+
+### 7.3. Target
+
+```ruby
+{
+  "select" => "paragraph where text:contains(\"New note\")",
+  "action" => "replace",
+  "target" => "paragraph where text:contains(\"Old note\")"
+}
+```
+
+The target condition matches the current composition buffer.
+
+### 7.4. Transform Scope
+
+```ruby
+{
+  "scope" => "code_block where language:equals(\"ruby\")",
+  "transform" => "replace_text",
+  "mode" => "literal",
+  "options" => "from:TODO; to:DONE"
+}
+```
+
+The scope condition matches the composed output or row-level fragment, not the original source document.
+
+## 8. Diagnostics
+
+| Situation | Diagnostic family |
+|-----------|-------------------|
+| Unknown field | `where.field_unknown` |
+| Unknown or unsupported predicate | `where.operator_unknown` |
+| Malformed predicate | `where.predicate_malformed` |
+| Invalid regex | `where.regex_invalid` |
+| Unsupported field-take | `where.field_take_unsupported` |
+| Invalid field-take | `where.field_take_invalid` |
+| Position zero | `where.position_zero` |
+
+See [Diagnostics](./md_composer_reference_diagnostics.md) for the broader validation model.
+
+## 9. Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Treating `where` as select-only syntax. | Use it anywhere selector syntax is accepted: select, include, target, and scope. |
+| Writing commas inside groups. | Use semicolons between child conditions. |
+| Putting `where` before the unit token. | Use `unit_token[take] where condition`. |
+| Expecting target `where` to search the original source. | Target conditions search the current composition buffer. |
+| Expecting transform scope `where` to search source documents. | Scope conditions search composed output or a row-level fragment. |
+| Using regex without validation. | Validate `matches(...)` expressions and expose them as advanced controls. |