@omgbase/core 0.28.0 → 0.29.2

package/dist/src/mcp/reference.js

@@ -5,233 +5,269 @@
 // tool handler stays thin. Semantics are the @omgbase/oqx contract (ADR-013);
 // when this text and the corpus (corpus/oqx/alchemy.test.ts) disagree, the
 // corpus wins.
+//
+// Three texts (spec/surface §4 `query_syntax`, 5.1): `QUERY_SYNTAX_CARD` is
+// what `query_syntax {}` returns — a ~3 kB card an agent can hold in context
+// (the 2026-10-21 agent-bench fetched the 38 kB manual twelve times and
+// replayed it as cached prefix on every later turn); `QUERY_SYNTAX` is the
+// whole manual (`section: "all"`); `querySyntaxSection(slug)` is one chapter of
+// it, by the slugs of `QUERY_SYNTAX_SECTIONS` (the manual's `##` headings). The
+// Rust twin (`crates/omgbase-surface/src/reference.rs`) mirrors all three byte
+// for byte; its tests compare against this file.
 export const QUERY_SYNTAX = `# query — OQX syntax reference
 
 The \`query\` tool takes ONE plain OQX string (+ optional \`limit\`/\`cursor\`, and
-\`bare: true\` to drop the automatic \`id\`/\`path\` envelope — needs a \`select\`).
+\`bare: true\` to drop the automatic \`_id\`/\`_path\` envelope — needs a \`select\`).
 There is no {from, filter, order} envelope: every concern is a clause of the
 string. Two rules tell the two syntaxes apart: DOT navigation belongs to the
-host object model (\`doc.layer\`, \`section.blocks\`, \`dst.title\`); WHITESPACE
+host object model (\`_doc.layer\`, \`_section._blocks\`, \`_dst._title\`); WHITESPACE
 query directives belong to OQX — a nested query is \`<receiver> collect|exists|
 count|first|single { <block> }\` (a postfix directive + a \`{ … }\` block), never a
 method. Its distinctive power is the receiver-constrained nested query that
-correlates to the current row: \`from docs where nodes exists { where kind ==
-"md:task" }\` returns only the docs that themselves contain a matching node.
-
-  [select <items>] from <target> [where <pred>] [frontier <pred>] [follow <dest> [{ … }], …]
-                   [flatten <expr> [{ … }] [as <name>]]… [group by <key>, …] [having <pred>]
-                   [order by <expr> [asc|desc], …] [limit N] [offset N]
-  <target> count|exists|none|first|single { <block> }     (scalar/one-row form: a bare target at the root scope)
-
+correlates to the current row: \`docs { _nodes exists { _kind == "md:task" } }\`
+returns only the docs that themselves contain a matching node.
+
+  <target> { [select <items>] [where <pred>] [frontier <pred>] [follow <dest> [{ … }], …]
+             [flatten <expr> [{ … }] [as <name>]]… [group by <key>, …] [having <pred>]
+             [order by <expr> [asc|desc], …] [limit N] [offset N] }
+  <target> count|exists|none|first|single { <block> }     (a scalar or one row; <target> is docs, blocks, nodes, links or revisions)
+
+THE COLLECTION HEADS THE BODY (OQX 0.26): \`docs { … }\` reads the documents and
+shapes them with the clauses inside the braces; a consumer word between the
+target and the brace (\`docs count { … }\`) shapes the whole result; nothing may
+follow the closing brace. The pre-0.26 clause form \`select … from docs where …\`
+is still read as the same query — write the braces.
 CLAUSE ORDER IS FIXED: select, from, where, frontier, follow, flatten, group by, having, order by, limit, offset —
-each at most once (\`flatten\` may repeat); an out-of-order clause is a parse error naming the order.
+each at most once (\`flatten\` may repeat; \`from\` inside a body RE-PROJECTS the
+rows through a relation, see Nested — it never names the source); an
+out-of-order clause is a parse error naming the order.
 Only \`select\` may drop its keyword, and only as the first clause
-(\`path, era from docs where …\`). A top-level predicate needs \`where\`, because
-\`where\` follows \`from\` (\`era > 1600 from docs\` is the clause-order error); a
-block may LEAD with a predicate (see Sugar), but a predicate after a projection
-still needs the keyword (\`{ name where kind == "md:task" }\`, not
-\`{ name, kind == "md:task" }\`); \`from docs count\` is an error (write
-\`docs count { … }\`). \`where\` and later \`select\` items may use the same body's
-\`select\` aliases (\`select path, old: era < 1000 from docs where old\`; an alias
-shadows a same-named field there). \`and\` / \`or\` / \`not\` are the connectives;
+(\`docs { _path, era where … }\`). A body may LEAD with a predicate — \`docs { era
+> 1600 }\` filters (see Sugar) — but a predicate after a projection still needs
+the keyword (\`{ _name where _kind == "md:task" }\`, not \`{ _name, _kind ==
+"md:task" }\`); in the clause form a top-level predicate needs \`where\` (\`era >
+1600 from docs\` is the clause-order error), and \`from docs count\` is an error
+(write \`docs count { … }\`). \`where\` and later \`select\` items may use the same
+body's \`select\` aliases (\`docs { select _path, old: era < 1000 where old }\`; an
+alias shadows a same-named field there). \`and\` / \`or\` / \`not\` are the connectives;
 the symbols \`&&\` / \`||\` / \`!\` are accepted synonyms (the words are canonical and
 what \`print\` writes).
 
 ## Sugar (OQX 0.17)
 
 Every form here is shorthand for an explicit directive (the AST is the explicit form):
-  nodes { kind == "md:task" }        ≡ nodes collect { where kind == "md:task" } — a receiver block with
+  nodes { _kind == "md:task" }       ≡ nodes collect { where _kind == "md:task" } — a receiver block with
                                        no consumer is collect; a block whose LEADING expression is a predicate
                                        (comparison, call, !/is/not, in, literal, (…), a consumer test — anything
-                                       but a bare name, a dotted path or a ^lift) is where-first. Bare names still
-                                       project: nodes { name } ≡ nodes collect { name }; filter a bare field with
-                                       nodes { is checked }. Wherever a value stands (0.20), call arguments included:
-                                       size(children { is checked }); x distinct { … } ≡ x collect distinct { … }. After a
-                                       follow destination too: follow children { depth 2 } is that destination's block.
+                                       but a bare name, a dotted path or a ^lift) is where-first. Names still
+                                       project: _nodes { _name } ≡ _nodes collect { _name }; filter a bare field with
+                                       _nodes { is checked }. Wherever a value stands (0.20), call arguments included:
+                                       size(_children { is checked }); x distinct { … } ≡ x collect distinct { … }. After a
+                                       follow destination too: follow _children { depth 2 } is that destination's block.
   (a, b)                              a tuple (0.20): two or more expressions, concatenated one level flat — a value
                                        (size((tags, aliases)), "x" in (tags, aliases)) and a receiver ((a, b) { … },
                                        follow (before, after) { depth 2 }); (a) alone is grouping
   refs(x)[0]                          ≡ refs(x) first { offset 0 }   positional (integer literal or \${binding});
-                                       out of range ⇒ absent; refs(x)[0].path navigates the row
-  ^docs[path == ^company]             ≡ ^docs first { where path == ^company }   first match or absent
-  ^docs[path == ^company]!            ≡ … single { … } required: exactly one, else filter_invalid
-  title!                              required: title, or an error naming the expression (and the row's $key — its id)
+                                       out of range ⇒ absent; refs(x)[0]._path navigates the row
+  ^docs[_path == ^company]            ≡ ^docs first { where _path == ^company }   first match or absent
+  ^docs[_path == ^company]!           ≡ … single { … } required: exactly one, else filter_invalid
+  _title!                             required: _title, or an error naming the expression (and the row's $key — its _id)
                                        — never a filter, never a coercion (0!, ""! are values); tightest: a!.b vs a.b!
   is x / not x                        truthiness of x, and its negation (prefix; \`not\` ≡ \`!\`)
   x is y / x is not y                 identity ($key: a store row's id, else structural) — compares rows, which == does not;
                                        x is null = absent; for scalars is ≡ ==; comparison precedence, no chaining
-  a and b / a or b                    the connectives (≡ && / ||: same precedence, short-circuit, value: data.title or path coalesces)
-  boss: ^docs[path == ^manager], bossName: boss.title   a select item may use the items to its LEFT
+  a and b / a or b                    the connectives (≡ && / ||: same precedence, short-circuit, value: title or _title coalesces)
+  boss: ^docs[_path == ^manager], bossName: boss._title   a select item may use the items to its LEFT
   Reserved words (never a bare field name): from where select is not and or, true false null.
   Contextual words (limit order offset follow collect count first distinct desc by in frontier depth group having
-  flatten as) parse as fields in expression position (select o: order from docs).
+  flatten as) parse as fields in expression position (docs { select o: order }).
 
-Results are LEAN hits — { id, path } + whatever \`select\` projects (or \`values\`,
+Results are LEAN hits — { _id, _path } + whatever \`select\` projects (or \`values\`,
 \`count\`, \`exists\`, \`none\`). The envelope keys ARE the attributes: copy a hit's
-\`id\` straight into \`where id == "…"\` (no translation); \`select id, path\` is simply
-the envelope (no duplicate columns); any OTHER projection whose output key would
-be \`id\` or \`path\` must be aliased — \`select data.path\` is refused ("projection
-\`path\` collides with the hit envelope — alias it (\`p: data.path\`)"); a row
-surfacing as a value (an empty \`collect { }\`) is the same \`{ id, path }\`. Every
-other tool spells a row the same way (\`docs_read\` → \`{ id, path, rev, properties,
-raw }\`, \`blocks_read\` → \`{ id, type, text, raw, hash, … }\`, \`docs_list\` → \`{ id,
-path, updated_at, blocks }\`, a revision → \`{ id, path, hash }\`): hydrate by id via
-blocks_read/docs_read.
+\`_id\` straight into \`where _id == "…"\` (no translation); \`select _id, _path\` is
+simply the envelope (no duplicate columns); an alias \`_id:\`/\`_path:\` on any OTHER
+expression is refused — \`blocks { select _path: _doc._path }\` fails ("projection
+\`_path\` collides with the hit envelope — alias it (\`p: _doc._path\`)"); a row
+surfacing as a value (an empty \`collect { }\`) is the same \`{ _id, _path }\`. Every
+other tool spells a row the same way (\`docs_read\` → \`{ _id, _path, rev, properties,
+_raw }\`, \`blocks_read\` → \`{ _id, _type, _text, _raw, _hash, … }\`, \`docs_list\` → \`{ _id,
+_path, _updated_at, blocks }\`, a revision → \`{ _id, _path, _hash }\`): hydrate by \`_id\`
+via blocks_read/docs_read.
 
 ## Paths
 
 Every path the surface returns is \`/\`-rooted — the form a reference is
 written in (\`[x](/projects/oqx.md)\`, \`before: [/timeline/kickoff.md]\`): a
-hit's \`path\`, an edge's \`dst_path\`, every tool's paths. Every path it
+hit's \`_path\`, an edge's \`_dst_path\`, every tool's paths. Every path it
 accepts tolerates both forms (\`/a.md\` or \`a.md\`): tool arguments, \`refs(x)\`,
-\`within(...)\`, and a string LITERAL compared with \`path\`/\`dst_path\` (bare, or
-through a row handle: \`doc.path\`) by \`==\`/\`!=\` or passed to their
-\`.startsWith(...)\` (it is rooted first, so \`path == "a.md"\` and \`path == "/a.md"\`
-both match). A property holding a reference compares directly — and is never
-rooted: \`where ^path in list(after)\`, \`where customer == ^path\`,
-\`where data.path == "/x.md"\` (the author's \`path:\` key, as written) — no
-\`"/" + ...\` glue.
+\`within(...)\`, and a string LITERAL compared with \`_path\`/\`_dst_path\` (on the row,
+or through a row handle: \`_doc._path\`, \`_dst._path\`, \`$it._path\`) by \`==\`/\`!=\` or
+passed to their \`.startsWith(...)\` (it is rooted first, so \`_path == "a.md"\` and
+\`_path == "/a.md"\` both match). A property holding a reference compares directly —
+and is never rooted: \`where ^_path in list(after)\`, \`where customer == ^_path\`,
+\`where path == "/x.md"\` (YOUR authored \`path:\` key — the bare name — compared as
+written) — no \`"/" + ...\` glue.
 
 ## Targets & field namespaces
 
-THE NAME RULE: \`$\` belongs to OQX — $it, $key, $depth, $stop, $leaf, $frontier,
-$ordinal are values the LANGUAGE injects into a scope; omgbase adds NO $ names
-(a \`$id\` in a query is an unknown name, absent). Every engine attribute is a BARE
-snake_case name that WINS on collision — the convention the relations (children,
-blocks, out, in, doc, frontmatter, …) always followed: a bare name that is an
-engine attribute reads the engine's value, never yours. Your data is bare too;
-where a key of yours collides with an engine name, reach it through a source
-handle: \`data.<k>\` (the merged authored view — frontmatter + inline, exactly the
-read a bare non-colliding key performs), \`frontmatter.<k>\`, \`inline.<k>\`. So
-\`path\` is the engine's /-rooted location and \`data.path\` your \`path:\` key;
-\`tags\` is your tags ∪ the body #hashtags and \`data.tags\` the authored list alone;
-\`title\` the computed title (the first H1) and \`data.title\` your \`title:\`;
-\`entries(data)\` lists every authored top-level key. Same value, same name
-everywhere: a hit's \`id\` is docs_read's \`id\` and the \`id\` argument of blocks_read.
-
-  Reserved bare names per kind (engine attributes; handles; self; relations):
-    docs    id path raw hash updated_at created_at title tags format | data frontmatter inline | doc | blocks nodes out_links in_links revisions
-    blocks  id path doc_id raw hash updated_at created_at type text attrs depth ordinal | block doc | children nodes out_links section
-    nodes   id path doc_id block_id kind name value attrs | section doc block | blocks subsections children
-    links   id path doc_id block_id via_id dst_id dst_path uri field dst_kind predicate provenance anchor | doc dst block
-    revisions  id path rev seq doc_id commit ts origin actor reason hash is_current archived | doc
-  A key of yours with any of these names is \`data.<k>\` (or frontmatter.<k> /
-  inline.<k> by source; attrs.<k> on a block or node).
-  UNKNOWN NAMES: a name that is none of the above AND that no object of the
-  kind in this repository carries is reported before any row is read — on
-  links as a filter_invalid error naming the fields; on docs/blocks/nodes the
-  result gains \`hints\` (one line per name, nearest match when there is one)
-  and the rows still come back; in a plan/apply/execute selector it is refused.
-  A property some objects carry is known (partial presence is normal).
+THE NAME RULE — one rule on every record kind: a BARE name is YOURS (an authored
+property: frontmatter + inline on a doc, an attrs key on a block or node), an
+UNDERSCORE-prefixed name is the ENGINE's (however derived: \`_id\`, \`_path\`,
+\`_title\`, \`_updated_at\`, \`_doc\`), and \`$\` belongs to OQX — $it, $key, $depth,
+$stop, $leaf, $frontier, $ordinal are values the LANGUAGE injects into a scope;
+omgbase adds NO $ names (a \`$id\` in a query is an unknown name, absent). Nothing
+bare is reserved: \`title\`, \`tags\`, \`path\`, \`id\`, \`format\`, \`doc\` are your keys
+when you wrote them. Collections stay bare (\`docs { … }\`, \`^docs\`, \`docs count { … }\`,
+\`entries(^$it)\`) — the collection before a body is a root, not a row property — and so do the
+row functions in call position (\`text("x")\`, \`under(…)\`, \`refs(x)\`): a call is
+never an entry read. There is NO self alias (the 4.x \`doc\`/\`block\`/\`section\`):
+\`$it\` is the self, and \`_doc\`/\`_block\`/\`_dst\` reach ANOTHER row. So \`_path\` is the
+engine's /-rooted location and \`path\` your \`path:\` key; \`_tags\` is your tags ∪ the
+body #hashtags and \`tags\` the authored list alone; \`_title\` the computed title (the
+first H1) and \`title\` your \`title:\`; \`_data.<k>\` ≡ \`<k>\` (the merged authored view —
+kept for \`entries(_data)\` and to reach an authored key that itself starts with
+\`_\`), \`_frontmatter.<k>\` / \`_inline.<k>\` one source each. Same value, same name
+everywhere: a hit's \`_id\` is docs_read's \`_id\` and the \`_id\` argument of blocks_read.
+
+  Engine names per kind (attributes | handles | relations):
+    docs    _id _path _raw _hash _updated_at _created_at _title _tags _format | _data _frontmatter _inline | _blocks _nodes _out_links _in_links _revisions
+    blocks  _id _path _doc_id _raw _hash _updated_at _created_at _type _text _attrs _depth _ordinal | _doc | _children _nodes _out_links _section
+    nodes   _id _path _doc_id _block_id _kind _name _value _attrs | _doc _block | _blocks _subsections _children
+    links   _id _path _doc_id _block_id _via_id _dst_id _dst_path _uri _field _dst_kind _predicate _provenance _anchor | _doc _dst _block | —
+    revisions  _id _path _rev _seq _doc_id _commit _ts _origin _actor _reason _hash _is_current _archived | _doc | —
+    root    _id (^_id, 0^_id) | — | docs blocks nodes links revisions
+  Every bare name is yours; \`_attrs.<k>\` on a block or node is the same read as
+  the bare attrs key \`<k>\`.
+  UNKNOWN NAMES: a bare name that no object of the kind in this repository
+  carries is a property read that yields absent — on docs/blocks/nodes the result
+  gains \`hints\` (one line per name, the nearest match drawn from your keys and the
+  engine names: "no document in this repository carries a property \`title\`; did
+  you mean \`_title\`?") and the rows still come back; in a plan/apply/execute
+  selector it is refused. On links and revisions (closed: no authored data reaches
+  them) a bare name is a filter_invalid error. A \`_x\` that is no engine name of
+  the kind is filter_invalid naming the kind's engine names. A property some
+  objects carry is known (partial presence is normal).
 
 docs:
   - bare identifier  = a document PROPERTY (frontmatter + inline \`key:: value\`,
                        unioned; nested via dots: meta.owner). YAML/JSON docs
-                       expose the parsed object's keys the same way.
-  - source handles   = data.<k> (merged authored view) / frontmatter.<k> /
-                       inline.<k>; the whole bag as a collection via entries(data)
-                       / entries(frontmatter) / entries(inline) (see entries()).
-  - attributes       = id, path (/-rooted, see Paths), updated_at (ISO-8601,
-                       sorts chronologically), raw (the whole file, frontmatter
-                       included), hash (its sha256, 64 hex), title (the computed
-                       title: the first H1; data.title is the authored key), tags
-                       (authored tags ∪ body #hashtags, deduped, authored first;
-                       data.tags is the authored list), format (the doc's format —
-                       "markdown"/"yaml"/"json"; present on EVERY doc, so
-                       has(format) is always true and \`format == "yaml"\` is the
-                       filter).
-  - relations        = nodes, blocks, doc.out_links / doc.in_links (a doc's
-                       links as rows; the documents at their other end are
-                       out_links collect distinct { from dst } and
-                       in_links collect distinct { from doc } — there is no
-                       out / in relation), revisions (the document's stored
+                       expose the parsed object's keys the same way. Nothing is
+                       reserved: \`title\`, \`tags\`, \`path\`, \`id\` are your keys.
+  - source handles   = _data.<k> (the merged authored view — the same read as the
+                       bare key) / _frontmatter.<k> / _inline.<k>; the whole bag
+                       as a collection via entries(_data) / entries(_frontmatter)
+                       / entries(_inline) (see entries()).
+  - attributes       = _id, _path (/-rooted, see Paths), _updated_at (ISO-8601,
+                       sorts chronologically), _created_at, _raw (the whole file,
+                       frontmatter included), _hash (its sha256, 64 hex), _title
+                       (the computed title: the first H1; \`title\` is the authored
+                       key), _tags (authored tags ∪ body #hashtags, deduped,
+                       authored first; \`tags\` is the authored list), _format (the
+                       doc's format — "markdown"/"yaml"/"json"; present on EVERY
+                       doc, so has(_format) is always true and \`_format == "yaml"\`
+                       is the filter).
+  - relations        = _nodes, _blocks, _out_links / _in_links (a doc's links as
+                       rows; the documents at their other end are
+                       _out_links distinct { from _dst } and
+                       _in_links distinct { from _doc } — there is no
+                       out / in relation), _revisions (the document's stored
                        revisions, oldest first — see revisions below).
 
 blocks:
-  - bare fields      = doc_id (the owning doc), type, text (normalized), ordinal
-                       (0-based among siblings), depth (0 at the top level), and
-                       every attrs key FLATTENED onto the row (bare \`checked\`
-                       reads attrs.checked; \`attrs.<k>\` still works; the
-                       structural fields win on collision; absent ⇒ false).
-  - attributes       = id, path (the owning doc's path), raw (the block's raw
-                       source — a container's raw holds its children), hash
+  - bare fields      = every attrs key FLATTENED onto the row (bare \`checked\`;
+                       \`_attrs.<k>\` is the same read; absent ⇒ false) — a block's
+                       authored side.
+  - attributes       = _id, _path (the owning doc's path), _doc_id (the owning
+                       doc), _type, _text (normalized), _ordinal (0-based among
+                       siblings), _depth (0 at the top level), _raw (the block's
+                       raw source — a container's raw holds its children), _hash
                        (its sha256 — the value update/split expect as
-                       expect.content_hash), updated_at.
-  - reach-through    = doc.<key> / doc.path / doc.id / doc.format = the
-                       CONTAINING doc (doc.id and doc.path cost nothing — they
-                       read the row's own doc_id / joined path, no lookup).
-  - relations        = block.children, block.nodes, block.out_links, section.
+                       expect.content_hash), _updated_at, _created_at, _attrs.
+  - reach-through    = _doc.<key> / _doc._path / _doc._id / _doc._format = the
+                       CONTAINING doc (_doc._id and _doc._path cost nothing — they
+                       read the row's own _doc_id / joined path, no lookup).
+  - relations        = _children, _nodes, _out_links, _section (no self alias:
+                       the 4.x \`block.children\` is \`_children\`).
   NOTE: inside a \`follow\`, $depth/$ordinal are ALWAYS the walk's metadata; a
-  block's own nesting is \`depth\` / \`ordinal\` (no $) everywhere.
+  block's own nesting is \`_depth\` / \`_ordinal\` everywhere.
 
 nodes:
-  - bare fields      = doc_id, block_id (null for a block-less node), kind
-                       (md:task / md:link / md:section / yaml:…), name, value,
-                       + attrs keys flattened (checked, level).
-  - attributes       = id, path.
-  - reach-through    = doc.<key> / doc.id / doc.path, block.type / block.text
-                       / block.id / block.path.
-  - relations        = section.blocks, section.children, section.subsections.
+  - bare fields      = the attrs keys flattened onto the row (checked, level,
+                       first_ordinal; \`_attrs.<k>\` is the same read).
+  - attributes       = _id, _path, _doc_id, _block_id (null for a block-less
+                       node), _kind (md:task / md:link / md:section / yaml:…),
+                       _name, _value, _attrs.
+  - reach-through    = _doc.<key> / _doc._id / _doc._path, _block._type /
+                       _block._text / _block._id / _block._path.
+  - relations        = _blocks, _children, _subsections (a section node's; the
+                       4.x \`section.blocks\` is \`_blocks\`).
 
 links:  (the authored link graph as rows — one per open link: the relation a link
-        establishes; the md:link NODE is its occurrence in the text and via_id
+        establishes; the md:link NODE is its occurrence in the text and _via_id
         points at it — a frontmatter link has a row and no node)
-  - bare fields      = doc_id (the SOURCE doc), block_id (the source block; null
-                       for a frontmatter edge), via_id, dst_id (the destination
-                       node id: a doc id, an external node id or phantom:<path>),
-                       dst_path (target doc path, /-rooted; NULL when
-                       dangling/external), uri (external URL; NULL otherwise),
-                       predicate ("references"/"embeds"/freeform), provenance
-                       ("link"/"frontmatter"/"inline_field"/…), dst_kind
-                       ("document"/"external"/"collection"), anchor, field (the
+  - attributes       = _id, _path (the SOURCE doc's path), _doc_id (the SOURCE
+                       doc), _block_id (the source block; null for a frontmatter
+                       edge), _via_id, _dst_id (the destination node id: a doc id,
+                       an external node id or phantom:<path>), _dst_path (target
+                       doc path, /-rooted; NULL when dangling/external), _uri
+                       (external URL; NULL otherwise), _predicate
+                       ("references"/"embeds"/freeform), _provenance
+                       ("link"/"frontmatter"/"inline_field"/…), _dst_kind
+                       ("document"/"external"/"collection"), _anchor, _field (the
                        frontmatter key / inline field it was authored in).
-  - attributes       = id, path (the SOURCE doc's path); doc.<key> reaches the
-                       source document. There is no from_commit: a query sees
-                       open edges only (history is blocks_history/changes_since).
+  - reach-through    = _doc.<key> (the source document), _dst.<key> (the
+                       destination document; absent when dangling/external),
+                       _block.<key> (the source block). Closed: links carry no
+                       authored data, so a bare name is filter_invalid. There is
+                       no from_commit: a query sees open edges only (history is
+                       blocks_history/changes_since).
   - text()/semantic() are N/A on links.
 
 revisions:  (history as rows — one per stored revision of every document of the
         repository, deleted documents included: what docs_history lists, queryable)
-  - bare fields      = rev (= id), seq (1, 2, … per document), doc_id, commit,
-                       ts (the commit's time, sorts chronologically), origin
-                       ("observed"/"api"/"import"/"projection"), actor, reason,
-                       hash (the rendered file's sha256 — docs_history's hash),
-                       is_current (true for the document's current revision),
-                       archived (true when the bodies moved to an archive segment:
-                       the row stays, docs_read { at } reads through the segment).
-  - attributes       = id (the revision id, r_…), path (the path the revision
-                       was committed under — a move re-paths only the current
-                       revision, so earlier ones keep the old path). doc.<key>
-                       reaches the document's CURRENT row; absent for a deleted
-                       document, so where doc == null is the revisions of deleted documents.
-  - on docs          = revisions is a relation (oldest first): a document with
-                       more than one version is docs { revisions count { } > 1 }.
+  - attributes       = _id (the revision id, r_…), _rev (= _id), _seq (1, 2, … per
+                       document), _doc_id, _commit, _ts (the commit's time, sorts
+                       chronologically), _origin ("observed"/"api"/"import"/
+                       "projection"), _actor, _reason, _hash (the rendered file's
+                       sha256 — docs_history's _hash), _is_current (true for the
+                       document's current revision), _archived (true when the
+                       bodies moved to an archive segment: the row stays,
+                       docs_read { at } reads through the segment), _path (the
+                       path the revision was committed under — a move re-paths
+                       only the current revision, so earlier ones keep the old
+                       path).
+  - reach-through    = _doc.<key> reaches the document's CURRENT row; absent for
+                       a deleted document, so where _doc == null is the revisions
+                       of deleted documents. Closed: a bare name is filter_invalid.
+  - on docs          = _revisions is a relation (oldest first): a document with
+                       more than one version is docs { _revisions count > 1 }.
   - text()/semantic() are N/A on revisions. The body as of a revision is
-    docs_read { path, at: "<rev>" } (docs_read_at is the same call).
+    docs_read { _path, at: "<rev>" } (docs_read_at is the same call).
 
 ## Scoping (ADR-015; the root row since surface 2.0): bare names are LOCAL
 
   name          the CURRENT row only — never falls through to an enclosing row
                 or the repository; an absent field is simply absent.
   ^name         one scope OUT (the enclosing row's fields/intrinsics/lifts);
-                ^^name two scopes out. \`^path\` = the enclosing row's path.
+                ^^name two scopes out. \`^_path\` = the enclosing row's path.
   ^docs ^nodes ^blocks ^links ^revisions
                 THE ROOT ROW (surface 2.0, oqx 0.18): the repository is the root
                 scope's row, one scope out from a top-level row, so ^docs there is
                 the whole documents scan (uncorrelated until you add a ^ predicate);
                 one caret per enclosing block (^^docs from depth two), or the
-                absolute 0^docs from ANY depth. ^id / 0^id = the repository id.
+                absolute 0^docs from ANY depth. ^_id / 0^_id = the repository id.
                 ^$it = the root object: ^$it.docs ≡ ^docs, entries(^$it) names the
                 five collections. At the root scope itself a bare target is the scan
-                (docs count { … }, from docs, entries(docs)).
+                (docs { … }, docs count { … }, entries(docs)).
                 ERRORS: a bare \`docs\` INSIDE a block reads a property of the current
-                row, which has none — refused ("did you mean ^docs"); \`^docs\` AT THE
-                TOP LEVEL reaches past the root — refused (write the bare \`docs\`);
-                so is \`$repo\` (surface < 2.0; the message names the replacement).
-                nodes/blocks on a doc row are that doc's RELATIONS, not the root.
+                row, which has none — refused ("did you mean ^docs"); so is a bare
+                \`blocks\`/\`nodes\`/\`revisions\` there (a doc's own relations are
+                \`_blocks\`/\`_nodes\`/\`_revisions\`); \`^docs\` AT THE TOP LEVEL reaches
+                past the root — refused (write the bare \`docs\`); so is \`$repo\`
+                (surface < 2.0; the message names the replacement).
   $it           the current item itself (a row, or each ELEMENT when the
-                receiver is a list property); ^$it = the enclosing row.
-                $value is NOT an intrinsic (since oqx 0.15): it reads a
+                receiver is a list property); ^$it = the enclosing row, ^$it._id
+                its id. $value is NOT an intrinsic (since oqx 0.15): it reads a
                 property literally named $value, absent when there is none.
   $key          the row's identity (0.20): a store row's id (doc/block/node/edge), an entries(x)
                 entry's key, a follow occurrence's walk identity; project $key: <expr> to rekey the
@@ -258,7 +294,7 @@ revisions:  (history as rows — one per stored revision of every document of th
                range-shaped STRING property as an interval: "2026-01-15" in range(window).
   strings      x.contains("s") x.startsWith("p") x.endsWith("s") x.matches("^re$")
                (real regex) x.lower() x.upper() size(x). ALL CASE-SENSITIVE —
-               fold with .lower(): title.lower().contains("aurora").
+               fold with .lower(): _title.lower().contains("aurora").
                Infix regex: x ~ "re" is x.matches("re"); x ~* "re" is the
                case-insensitive match; x !~ "re" and x !~* "re" negate them.
                Unanchored unless the pattern anchors; an absent x is false
@@ -277,7 +313,7 @@ revisions:  (history as rows — one per stored revision of every document of th
                n.dur_iso() → "PT1H30M". Total: a non-date is absent, so
                \`where date(due) < date("today").minus(dur("30 days"))\` just
                filters. A datetime is never < its own date: compare
-               updated_at.date() == date("today"), or < date("tomorrow").
+               _updated_at.date() == date("today"), or < date("tomorrow").
   literals     "str" 'str' 123 1.5 true false null
   determinism  no random; the only clock is date("today"/"now"/…), read once per
                query. Lists/structs are not literals; ternary is not supported.
@@ -312,8 +348,8 @@ revisions:  (history as rows — one per stored revision of every document of th
                        a source, a receiver or a follow destination:
                        follow refs(before), refs(after) walks a timeline both ways.
                        The reverse direction needs no function: a document's
-                       path is already the reference form, so
-                       ^docs { where ^path in list(after) } is
+                       _path is already the reference form, so
+                       ^docs { ^_path in list(after) } is
                        "the documents whose \`after\` names me".
   A HIT IS A STORE ROW: a top-level row that is not a doc/block/node/edge fails
                        (filter_invalid). \`follow before\` over a list of paths
@@ -322,58 +358,64 @@ revisions:  (history as rows — one per stored revision of every document of th
 ## Nested queries & consumers
 
   <receiver> collect|exists|none|count|first|single { <block> }
-    receiver = a relation (nodes, blocks, doc.out_links, section.blocks, …), a
-               reach-through row (dst, doc: one row — dst { title }), a
+    The block may be omitted after a consumer word (OQX 0.26): the omitted block is
+    the empty block — \`_nodes exists\`, \`_revisions count > 1\`, \`_blocks first\`,
+    \`docs count\` as a whole query; \`x { }\` keeps its braces (the brace is what
+    makes a collect). A projection block over a lookup is the lookup's projection:
+    \`_blocks[0] { _text }\` ≡ \`_blocks first { _text offset 0 }\`.
+    receiver = a relation (_nodes, _blocks, _doc._out_links, _section._blocks, …), a
+               reach-through row (_dst, _doc: one row — _dst { _title }), a
     list property (tags), entries(x), or a root collection (^docs; 0^docs at depth ≥ 2).
     block    = [select …] [from E] [where …] [frontier …] [follow …] [flatten …] [group by …] [having …] [order by …] [limit N] [offset N]
-               — the same fixed order as the top level (\`from\` optional; the
-               receiver supplies the rows). A leading name/alias list is the
-               projection (\`select\` dropped); a predicate always needs \`where\`.
-               A \`from E\` inside a block RE-PROJECTS the rows through a relation
-               (a typed flatMap): \`docs collect { from nodes where kind == "md:task" }\`
-               starts at docs, projects each through \`nodes\`, and queries the
-               resulting nodes; a scalar relation (\`from doc\`) contributes one
-               row; a missing or non-navigable relation is a loud error, never a
-               global scan.
-  exists    ≥1 row      nodes exists { where kind == "md:task" and not checked }
-  none      0 rows      nodes none { where kind == "md:task" and not checked }  ("every task done")
-  count     a number    nodes count { where kind == "md:task" } >= 2
+               — the same fixed order as the whole query, whose body is a block
+               too (the target is its receiver). A leading name/alias list is the
+               projection (\`select\` dropped); a predicate needs \`where\` unless
+               it LEADS the block (Sugar). A \`from E\` inside a block RE-PROJECTS
+               the rows through a relation (a typed flatMap):
+               \`docs { from _nodes where _kind == "md:task" }\` starts at docs,
+               projects each through \`_nodes\`, and queries the resulting nodes;
+               a scalar relation (\`from _doc\`) contributes one row; a missing or
+               non-navigable relation is a loud error, never a global scan. \`from\`
+               never names the source — the collection before the body does.
+  exists    ≥1 row      _nodes exists { _kind == "md:task" and not checked }
+  none      0 rows      _nodes none { _kind == "md:task" and not checked }  ("every task done")
+  count     a number    _nodes count { _kind == "md:task" } >= 2
   collect   rows (default) — in select for nested results; in where with a lift
   first / single   zero-or-one (single errors on >1) — lookups in select
-  distinct  on any consumer: dedup by projected value — nodes count distinct { select kind }
+  distinct  on any consumer: dedup by projected value — _nodes count distinct { select _kind }
   limit/offset  bound the block's rows AFTER where/order/distinct, BEFORE the
-            consumer reduces: nodes exists { offset 1 } = at least two;
+            consumer reduces: _nodes exists { offset 1 } = at least two;
             first { … offset 1 } = the second.
   lift      \`^name:\` in a where-collect binds values outward:
-            select path, open from docs where nodes collect { ^open: value where kind == "md:task" and not checked }
-  joins     ^<t> exists { where slug == ^ref }  semi-join; not … exists  anti-join;
-            ^nodes single { where kind == "person" and attrs.id == ^owner_id }  lookup;
+            docs { select _path, open where _nodes { ^open: _value where _kind == "md:task" and not checked } }
+  joins     ^<t> exists { slug == ^ref }  semi-join; not … exists  anti-join;
+            ^nodes single { _kind == "person" and _attrs.id == ^owner_id }  lookup;
             x in ^keys  membership over a lifted set.
 
 ## select — projection
 
-  select a, alias: expr, nested: nodes collect { … }
-  bare key → the attribute when it is one (id, path, title, …), else the property
-  (scalar-authored → scalar; list → array); data.<k> forces the property;
+  select a, alias: expr, nested: _nodes collect { … }
+  bare key → your property (scalar-authored → scalar; list → array); _name →
+  the engine's field (_id, _path, _title, …); _data.<k> is the bare key's read;
   a call/arithmetic needs an alias (n: size(tags)) unless in values mode;
-  an output key of id/path other than the attribute itself needs an alias.
-  raw         whole file bytes (docs) — docs_read is cheaper for one doc.
-  distinct    select distinct type   (dedup hits by projected value)
+  an output key of _id/_path other than the attribute itself needs an alias.
+  _raw        whole file bytes (docs) — docs_read is cheaper for one doc.
+  distinct    select distinct _type   (dedup hits by projected value)
   values      select <ONE item> values → bare values instead of records:
-                select distinct type values from docs          → values: ["hub","lab-note",…]
-                select path values from docs                   → values: ["/index.md", …]
-                tags: tags collect { $it values }             → a plain array
-                h: nodes first { name values where kind == "md:section" order by first_ordinal }
+                docs { select distinct type values }          → values: ["hub","lab-note",…]
+                docs { select _path values }                   → values: ["/index.md", …]
+                tags: tags { $it values }                     → a plain array
+                h: _nodes first { _name values where _kind == "md:section" order by first_ordinal }
   entries(x)  a record as a collection ($key / $it per entry), key order:
-                select fm: entries(data) collect { k: $key, v: $it }
-                where entries(frontmatter) exists { where $key == "era" and $it > 1600 }
-                entries(inline), entries(attrs), a nested map, or a list (index keys)
+                select fm: entries(_data) { k: $key, v: $it }
+                where entries(_frontmatter) exists { $key == "era" and $it > 1600 }
+                entries(_inline), entries(_attrs), a nested map, or a list (index keys)
   $semantic_score is not a field — project semantic("…") under an alias instead.
 
 ## flatten (OQX 0.25)
 
   flatten <expr> [{ … }] [as <name>]      after follow, before group by; may repeat
-  Splits one value into rows. Every hit is still the PARENT row — its id/path
+  Splits one value into rows. Every hit is still the PARENT row — its _id/_path
   repeat per element, as Dataview's TABLE … FLATTEN — with <name> bound beside
   its fields at the same depth: an array → one row per element (an empty list
   yields none), a missing field → one row with the name absent (never dropped),
@@ -383,44 +425,44 @@ revisions:  (history as rows — one per stored revision of every document of th
   projection, order by, limit, distinct), applied first. Later clauses read the
   name — a later flatten (flatten jobs as j flatten j.tags as t), group by,
   having, select, order by; where runs before it. A flattened query pages by
-  position (cursor null); as id / as path is refused (the envelope reads them).
-    select path, tags from docs where type == "process" flatten tags order by path, tags
-    select path, t: b.text from docs flatten blocks { where type == "task" and not checked } as b
-    select tags, n: count() from docs flatten tags group by tags order by count() desc
+  position (cursor null); as _id / as _path is refused (the envelope reads them).
+    docs { select _path, tags where type == "process" flatten tags order by _path, tags }
+    docs { select _path, t: b._text flatten _blocks { _type == "task" and not checked } as b }
+    docs { select tags, n: count() flatten tags group by tags order by count() desc }
 
 ## order by, limit/offset, pagination
 
-  order by era desc, path asc      absent values sort LAST (asc); ties → (path, id)
+  order by era desc, _path asc     absent values sort LAST (asc); ties → (_path, _id)
   limit N / offset N               define the result SET (integer literals);
                                    the tool's limit/cursor then page WITHIN it
-  cursor                           opaque keyset on (path,id); a custom order by
+  cursor                           opaque keyset on (_path, _id); a custom order by
                                    disables it (you get the top page + truncated)
 
 ## Graph traversal (follow) and links
 
   The citation graph is the LINK ROWS walked through a destination block:
-  dst is a link's destination document (absent for an external or dangling
-  link — it then contributes no successor), doc its source.
-  from docs where <seed> follow out_links collect { from dst }     docs the seed links TO
-  from docs where <seed> follow in_links collect { from doc }      backlinks
-    follow out_links collect { from dst depth 3 }                  bound (1..8, default 8) — a clause of the block
-    follow out_links collect { from dst where layer == "canon" }   keep only matching successors
-    follow in_links collect { from doc where ^path in list(before) }   ^ = the row being expanded
+  _dst is a link's destination document (absent for an external or dangling
+  link — it then contributes no successor), _doc its source.
+  docs { where <seed> follow _out_links { from _dst } }     docs the seed links TO
+  docs { where <seed> follow _in_links { from _doc } }      backlinks
+    follow _out_links { from _dst depth 3 }                  bound (1..8, default 8) — a clause of the block
+    follow _out_links { from _dst where layer == "canon" }   keep only matching successors
+    follow _in_links { from _doc where ^_path in list(before) }   ^ = the row being expanded
                                                    (^^ = the walk's enclosing scope)
-    follow out_links collect { from dst where predicate == "depends_on" }   one predicate only
-    follow out_links collect { from dst }, in_links collect { from doc }
+    follow _out_links { from _dst where _predicate == "depends_on" }   one predicate only
+    follow _out_links { from _dst }, _in_links { from _doc }
                                                    several destinations: their union
                                                    (one step dedups by identity)
-    follow ^docs { where out_links exists { where dst_path == ^^path } }
+    follow ^docs { _out_links exists { _dst_path == ^^_path } }
                                                    a destination block over the root's
                                                    documents, re-read per frontier row
                                                    (^ = that row) = the backlinks walk
-    follow out_links collect { from dst frontier type == "practitioner" }   cut, keeping the frontier row
-    from docs where type == "process" frontier !verified follow out_links collect { from dst }
+    follow _out_links { from _dst frontier type == "practitioner" }   cut, keeping the frontier row
+    docs { type == "process" frontier !verified follow _out_links { from _dst } }
                                                    the BODY's frontier applies to the seeds:
                                                    an unverified seed is kept, not expanded
-    follow distinct out_links collect { from dst } / … { $key: group from dst }   identity control ($key)
-    follow refs(before), ^docs { where ^path in list(after) }    forward over \`before\`, backward
+    follow distinct _out_links { from _dst } / … { $key: group from _dst }   identity control ($key)
+    follow refs(before), ^docs { ^_path in list(after) }    forward over \`before\`, backward
                                                    over every doc whose \`after\` names me
   Per-occurrence metadata: $depth (seed = 1), $stop (interior|leaf|frontier|
   depth|cycle), $leaf/$frontier, $ordinal (a deterministic 1..N rank over the
@@ -428,14 +470,15 @@ revisions:  (history as rows — one per stored revision of every document of th
   \`where $ordinal <= N\` for a deterministic budget cut), $key — usable in
   select/order by and the top-level post-walk where (a where conjunct that
   reads one filters the walk's RESULT; the other conjuncts remain the seed
-  predicate), NOT metadata of the candidates a destination block's where reads,
-  nor valid inside a consumer directive. Cyclic graphs are safe: a revisited
+  predicate), NOT metadata of the candidates a destination block's where reads;
+  a consumer directive may carry a follow of its own (its block yields the
+  walk: \`_children count { follow _children } > 5\`). Cyclic graphs are safe: a revisited
   node is admitted once as a \`$stop == "cycle"\` occurrence and never
   re-expanded. The default keeps one occurrence per distinct walk path;
   \`follow distinct\` dedups reached rows by identity.
   Destination blocks (OQX 0.20): a brace after ANY destination opens that
-  destination's block — children { depth 2 }, refs(x) { depth 2 }, out_links
-  collect { from dst depth 2 }, ^docs { where ^path in list(after) } — with the
+  destination's block — _children { depth 2 }, refs(x) { depth 2 }, _out_links
+  { from _dst depth 2 }, ^docs { ^_path in list(after) } — with the
   0.17 body rules (where-first, projections) and two clauses of its own after
   \`where\`: frontier <pred> (occurrences reached through this destination that
   match are frontiers; ^ there is the walk's enclosing scope) and depth <n>
@@ -446,55 +489,155 @@ revisions:  (history as rows — one per stored revision of every document of th
   expanded; each destination's frontier is its own. There is no options block;
   the old \`by\` is $key. A bare follow ^docs (no brace, no consumer) is an
   error naming both block spellings.
-  Type-preserving relations: block.children, section.children, section.subsections;
-  the citation graph is out_links collect { from dst } / in_links collect { from doc }.
-  from links where dst_path == "/notes/x.md"       inbound links to a doc, as rows
-  select d: dst.title, k: dst_kind from links       the destination document's title
-  from docs where out_links exists { where dst.layer == "draft" }   links into drafts
-  select b: in_links collect distinct { from doc } from docs     backlinks as { id, path }
-  select doc_id, dst_path from links where predicate == "depends_on"
-  from docs where not doc.in_links exists { }      orphans (nothing links in)
+  Type-preserving relations: a block's _children; a section node's _children and
+  _subsections; the citation graph is _out_links { from _dst } / _in_links { from _doc }.
+  links { _dst_path == "/notes/x.md" }       inbound links to a doc, as rows
+  links { select d: _dst._title, k: _dst_kind }       the destination document's title
+  docs { _out_links exists { _dst.layer == "draft" } }   links into drafts
+  docs { select b: _in_links distinct { from _doc } }     backlinks as { _id, _path }
+  links { select _doc_id, _dst_path where _predicate == "depends_on" }
+  docs { not _in_links exists }      orphans (nothing links in)
   (The \`graph\` tool is a convenience wrapper that compiles to a follow query.)
 
 ## semantic grain
 
-from docs ranks whole DOCUMENTS (one hit per file); from blocks ranks PASSAGES.
+docs { … } ranks whole DOCUMENTS (one hit per file); blocks { … } ranks PASSAGES.
 text()/where prune the candidate set; only order by reweights.
 
 ## Examples
 
-  from docs where layer == "working"
-  from docs where path.startsWith("/guides/") and updated_at >= "2026-08-01"
-  select layer, tags from docs where "pricing" in list(tags)
-  from docs where inline.owner == "alice"
-  from docs where title.lower().contains("q3 plan")
-  from docs where format == "yaml"
-  from docs where type == "practitioner" order by era desc limit 2
-  from docs where nodes none { where kind == "md:task" and not checked }
-  from docs where tags exists { where $it == "tria-prima" }
-  select fm: entries(data) collect { k: $key, v: $it } from docs where path == "/x.md"
-  select owner_id, owner: ^nodes single { where kind == "person" and attrs.id == ^owner_id } from docs
-  from blocks where type == "task" and not checked and under_heading("Launch") and doc.layer == "working"
-  from blocks where type == "paragraph" and has_edge("references", "d_92aaaaa")
-  select path, $depth from docs where path == "/timeline/review.md" follow refs(before), refs(after)
-  select path, next: ^docs collect { path where ^path in list(before) } from docs where type == "milestone"
-  select path, n: size(^docs), repo: ^id from docs limit 1
-  select p: data.path, t: data.title from docs where has(data.path)
+  docs { layer == "working" }
+  docs { _path.startsWith("/guides/") and _updated_at >= "2026-08-01" }
+  docs { select layer, tags where "pricing" in list(tags) }
+  docs { _inline.owner == "alice" }
+  docs { _title.lower().contains("q3 plan") }
+  docs { _format == "yaml" }
+  docs { type == "practitioner" order by era desc limit 2 }
+  docs { _nodes none { _kind == "md:task" and not checked } }
+  docs { tags exists { $it == "tria-prima" } }
+  docs { select fm: entries(_data) { k: $key, v: $it } where _path == "/x.md" }
+  docs { select owner_id, owner: ^nodes single { _kind == "person" and _attrs.id == ^owner_id } }
+  blocks { _type == "task" and not checked and under_heading("Launch") and _doc.layer == "working" }
+  blocks { _type == "paragraph" and has_edge("references", "d_92aaaaa") }
+  docs { select _path, $depth where _path == "/timeline/review.md" follow refs(before), refs(after) }
+  docs { select _path, next: ^docs { _path where ^_path in list(before) } where type == "milestone" }
+  docs { select _path, n: size(^docs), repo: ^_id limit 1 }
+  docs { select path, title where has(path) }
   docs { type == "substance" and not verified }
-  select subject, process: ^docs[slug == ^subject]!.path from docs where type == "lab-note"
-  select path, back: nodes first { select p: 0^docs collect { path where ^^path in list(after) } values } from docs where type == "milestone"
-  select path, prior: refs(before) collect { path, when } from docs where type == "milestone"
-  from blocks order by semantic("identity preservation across edits") desc limit 10
-  select uri from links where dst_kind == "external"
-  docs count { where layer == "canon" }
-  select seq, origin, ts, hash from revisions where path == "/processes/calcination.md" order by seq desc
-  from docs where revisions count { where origin == "api" } > 0
-  select p: path, d: doc.path from revisions where doc == null
-  select layer, n: count(), titles: collect(title), open: rows count { where nodes exists { where kind == "md:task" and not checked } } from docs group by layer having count() > 1 order by count() desc
-  select path, tag: tags from docs where "process" in tags flatten tags order by path, tags
-
-Common mistake: \`$path\`/\`$id\` (the 2.x spelling) — omgbase has no $ names; write
-\`path\`/\`id\`. Another: \`where tags == "x"\` on a list-valued key is false — write
-\`"x" in tags\`. Another: \`select data.path\` — alias it (\`p: data.path\`).
+  docs { select subject, process: ^docs[slug == ^subject]!._path where type == "lab-note" }
+  docs { select _path, back: _nodes first { select p: 0^docs { _path where ^^_path in list(after) } values } where type == "milestone" }
+  docs { select _path, prior: refs(before) { _path, when } where type == "milestone" }
+  blocks { order by semantic("identity preservation across edits") desc limit 10 }
+  links { select _uri where _dst_kind == "external" }
+  docs count { layer == "canon" }
+  revisions { select _seq, _origin, _ts, _hash where _path == "/processes/calcination.md" order by _seq desc }
+  docs { _revisions count { _origin == "api" } > 0 }
+  revisions { select p: _path, d: _doc._path where _doc == null }
+  docs { select layer, n: count(), titles: collect(_title), open: rows count { _nodes exists { _kind == "md:task" and not checked } } group by layer having count() > 1 order by count() desc }
+  docs { select _path, tag: tags where "process" in tags flatten tags order by _path, tags }
+
+Common mistake: \`$path\`/\`$id\` — omgbase has no $ names; the engine's location and
+identity are \`_path\`/\`_id\`. Another: the 4.x bare \`path\`/\`id\`/\`title\`/\`tags\` — a
+bare \`path\` is now YOUR \`path:\` key (absent when you wrote none, with a hint
+pointing at \`_path\`); the engine's are \`_path\`/\`_id\`/\`_title\`/\`_tags\`; \`select
+data.path\` is gone — write \`path\`. Another: \`where tags == "x"\` on a list-valued
+key is false — write \`"x" in tags\`. Another: \`select _path: _doc._path\` — alias it
+(\`p: _doc._path\`).
+`;
+/**
+ * The manual's chapters (spec/surface §4 `query_syntax`, 5.1): one entry per
+ * `## ` heading of `QUERY_SYNTAX`, in order — the `section` argument's names.
+ * `querySyntaxSection(slug)` is the text from that heading up to the next one.
+ * The Rust twin pins the same table (its test checks every pair against this
+ * source).
+ */
+export const QUERY_SYNTAX_SECTIONS = [
+    { slug: "sugar", heading: "Sugar (OQX 0.17)" },
+    { slug: "paths", heading: "Paths" },
+    { slug: "targets", heading: "Targets & field namespaces" },
+    { slug: "scoping", heading: "Scoping (ADR-015; the root row since surface 2.0): bare names are LOCAL" },
+    { slug: "scalars", heading: "Scalar semantics (@omgbase/oqx)" },
+    { slug: "predicates", heading: "Domain predicates (omgbase)" },
+    { slug: "nested", heading: "Nested queries & consumers" },
+    { slug: "select", heading: "select — projection" },
+    { slug: "flatten", heading: "flatten (OQX 0.25)" },
+    { slug: "order", heading: "order by, limit/offset, pagination" },
+    { slug: "follow", heading: "Graph traversal (follow) and links" },
+    { slug: "semantic", heading: "semantic grain" },
+    { slug: "examples", heading: "Examples" },
+];
+/** The `section` names a caller may pass: every slug, then `all` (the whole manual). */
+export const QUERY_SYNTAX_SECTION_NAMES = [...QUERY_SYNTAX_SECTIONS.map((s) => s.slug), "all"];
+/**
+ * One chapter of the manual: the lines from `## <heading>` up to (not
+ * including) the next `## ` heading or the end, trailing blank lines dropped,
+ * one trailing newline. `"all"` is the whole manual; an unknown slug is `null`.
+ */
+export function querySyntaxSection(slug) {
+    if (slug === "all")
+        return QUERY_SYNTAX;
+    const entry = QUERY_SYNTAX_SECTIONS.find((s) => s.slug === slug);
+    if (!entry)
+        return null;
+    const lines = QUERY_SYNTAX.split("\n");
+    const start = lines.indexOf(`## ${entry.heading}`);
+    if (start < 0)
+        return null;
+    let end = start + 1;
+    while (end < lines.length && !lines[end].startsWith("## "))
+        end++;
+    while (end > start + 1 && lines[end - 1].trim() === "")
+        end--;
+    return lines.slice(start, end).join("\n") + "\n";
+}
+/**
+ * The card `query_syntax {}` returns (5.1): the grammar skeleton, the names
+ * rule and the engine names per kind, the handles, the consumers, follow in
+ * one line, the examples agents reach for first, and where the chapters are.
+ * Every indented example parses (reference.test.ts extracts them exactly as it
+ * extracts the manual's). Keep every line earning its place: this is the most
+ * read text on the surface.
+ */
+export const QUERY_SYNTAX_CARD = `# query — OQX card. Chapters: query_syntax { section: "<name>" }; the manual: { section: "all" }
+
+One OQX string; limit/cursor page the hits; bare: true drops the { _id, _path } envelope.
+  <target> { [select <items>] [where <pred>] [follow <dest> { … }] [order by <expr> [desc]] [limit N] [offset N] }
+  <target> count|exists|none|first|single [{ <block> }]   a scalar or one row; no block = the empty block (docs count)
+The collection (docs blocks nodes links revisions) heads the body; nothing follows its closing brace.
+CLAUSE ORDER IS FIXED: select, from, where, frontier, follow, flatten, group by, having, order by, limit, offset.
+and / or / not. Comparisons strict and typed; null == a missing field. A list key: "x" in tags, never tags == "x".
+Strings .contains("s") .startsWith("p") .lower(); x ~* "re" (ci regex), x !~ "re". Dates date("today"),
+date(due) < date("today").minus(dur("30 days")), _updated_at >= "2026-08-01".
+
+NAMES: a BARE name is YOURS (frontmatter, inline key:: value, a block's attrs); an UNDERSCORE name is the ENGINE's;
+$ is OQX's ($it $key $depth $stop $ordinal). title tags path id are your keys; _title _tags _path _id the engine's.
+  docs       _id _path _raw _hash _updated_at _created_at _title _tags _format | _data _frontmatter _inline | _blocks _nodes _out_links _in_links _revisions
+  blocks     _id _path _doc_id _raw _hash _type _text _attrs _depth _ordinal | _doc | _children _nodes _out_links _section
+  nodes      _id _path _doc_id _block_id _kind _name _value _attrs | _doc _block | _blocks _subsections _children
+  links      _id _path _doc_id _block_id _via_id _dst_id _dst_path _uri _dst_kind _predicate _provenance _anchor _field | _doc _dst _block
+  revisions  _id _path _rev _seq _doc_id _commit _ts _origin _actor _reason _hash _is_current _archived | _doc
+Handles _data.<k> ≡ <k>, _frontmatter.<k> / _inline.<k>; entries(_data) the bag as rows ($key, $it). Reach-through
+_doc.<k> the owning document, _dst.<k> a link's target. Scoping: a bare name is the CURRENT row; ^name one scope
+out; ^docs ^blocks ^nodes ^links the repository from a row. An unknown bare name is absent plus a hints line.
+
+NESTED: <receiver> collect|exists|none|count|first|single { [select …] [where …] [order by …] [limit N] } over a
+relation, a list key, entries(x) or ^docs; no consumer = collect, a leading predicate = where: docs { type == "x" }.
+FOLLOW: docs { where <seed> follow _out_links { from _dst depth 3 } }   links out; _in_links { from _doc }
+backlinks; refs(before) a property's documents; $depth per row. SEARCH: text("words") prunes; order by semantic("…") desc.
+
+  docs { layer == "working" }
+  docs { select _title, stage where "process" in tags order by _path limit 5 }
+  blocks { select _type, _text where _path == "/processes/calcination.md" }
+  nodes { select _path, _value where _kind == "md:task" and not checked }
+  links { select _path, _block_id where _dst_path == "/processes/calcination.md" }
+  docs { _title.lower().contains("salt") and _updated_at >= "2026-01-01" }
+  docs { _nodes exists { _kind == "md:task" and not checked } }
+  docs { select _path, $depth where _path == "/timeline/review.md" follow refs(before), refs(after) }
+  docs count { layer == "canon" }
+  revisions { select _seq, _ts, _hash where _path == "/processes/calcination.md" order by _seq desc }
+  docs { select tags, n: count() flatten tags group by tags order by count() desc }
+
+Every error is filter_invalid naming what to change; when the engine can correct the call, data.fix IS the call.
+Chapters: sugar paths targets scoping scalars predicates nested select flatten order follow semantic examples; all.
 `;
 //# sourceMappingURL=reference.js.map