@omgbase/core 0.8.0 → 0.10.0

package/dist/src/mcp/reference.d.ts

@@ -1 +1 @@
-export declare const QUERY_SYNTAX = "# query \u2014 OQX syntax reference\n\nThe `query` tool takes ONE plain OQX string (+ optional `limit`/`cursor`). There\nis no {from, filter, order} envelope: every concern is a clause of the string.\n\n  [select <items>] from <target> [where <pred>] [follow <dest>, \u2026 [{ \u2026 }]]\n                   [order by <expr> [asc|desc], \u2026] [limit N] [offset N]\n  $repo.<target> count|exists|none|first|single { <block> }     (scalar/one-row form)\n\nCLAUSE ORDER IS FIXED: select, from, where, follow, order by, limit, offset \u2014\neach at most once; an out-of-order clause is a parse error naming the order.\nOnly `select` may drop its keyword, and only as the first clause\n(`$path, era from docs where \u2026`). Every other clause always carries its keyword:\na predicate is NEVER implicit (`nodes exists { where kind == \"md:task\" }`, not\n`{ kind == \"md:task\" }`), and `from docs count` is an error (write\n`$repo.docs count { \u2026 }`). `where` may use the same body's `select` aliases\n(`select $path, old: era < 1000 from docs where old`; an alias shadows a\nsame-named field there).\n\nResults are LEAN hits \u2014 {id, path} + whatever `select` projects (or `values`,\n`count`, `exists`, `none`). Hydrate full content by id via nodes_get/docs_read.\n\n## Targets & field namespaces\n\nThe sigil rule: `$`-prefixed names are engine intrinsics; BARE identifiers are\nyour content. On docs a bare first segment that collides with an intrinsic base\nname (id/path/repo/updated_at/content_hash/body) is REJECTED with a \"did you mean\n$X?\" hint (bare `path` would silently read an absent frontmatter key). Force the\nproperty with `frontmatter.<k>`. `title`/`tags` are NOT reserved: `$title`/`$tags`\nare computed and never shadow an authored `title:`/`tags:` key.\n\ndocs:\n  - bare identifier  = a document PROPERTY (frontmatter + inline `key:: value`,\n                       unioned; nested via dots: meta.owner). YAML/JSON docs\n                       expose the parsed object's keys the same way.\n  - source-scoped    = frontmatter.<k> / inline.<k>; the whole bag as a collection\n                       via entries(frontmatter) / entries(inline) (see entries()).\n  - computed         = $title (first H1), $tags (body #hashtags), format\n                       (the doc's format \u2014 \"markdown\"/\"yaml\"/\"json\"; a bare\n                       computed field, present on EVERY doc, so has(format) is\n                       always true and `format == \"yaml\"` is the filter).\n  - intrinsics       = $id, $path, $updated_at (ISO-8601, sorts chronologically),\n                       $body (whole file), $content_hash.\n  - relations        = nodes, blocks, doc.out / doc.in (citation graph),\n                       doc.out_edges / doc.in_edges (a doc's edges as rows).\n\nblocks:\n  - bare fields      = type, text, and every attrs key FLATTENED onto the row\n                       (bare `checked` reads attrs.checked; `attrs.<k>` still\n                       works; type/text win on collision; absent \u21D2 false).\n  - intrinsics       = $id, $doc, $path, $ordinal, $depth, $updated_at, $body\n                       (the block text), $content_hash (the block's OWN raw hash \u2014\n                       the value update/split expect).\n  - reach-through    = doc.<key> / doc.$path / doc.format = the CONTAINING doc.\n  - relations        = block.children, block.nodes, block.out_edges, section.\n\nnodes:\n  - bare fields      = kind (md:task / md:link / md:section / yaml:\u2026), name,\n                       value, + attrs keys flattened (checked, level).\n  - intrinsics       = $id (=$node_id), $doc_id, $block_id, $path.\n  - reach-through    = doc.<key>, block.type / block.text.\n  - relations        = section.blocks, section.children, section.subsections.\n\nedges:  (the authored link graph as rows \u2014 one per open edge)\n  - bare fields      = predicate (\"references\"/\"embeds\"/freeform), provenance\n                       (\"link\"/\"frontmatter\"/\"inline_field\"/\u2026), dst_kind\n                       (\"document\"/\"external\"/\"collection\"), anchor, src_field\n  - intrinsics       = $id, $src, $dst, $dst_path (target doc path; NULL when\n                       dangling/external), $dst_uri (external URL; NULL\n                       otherwise), $src_block, $via, $from_commit; $path and\n                       doc.<key> reach the SOURCE document.\n  - text()/semantic() are N/A on edges.\n\n## Scoping (ADR-015): bare names are LOCAL\n\n  name          the CURRENT row only \u2014 never falls through to an enclosing row\n                or the repository; an absent field is simply absent.\n  ^name         one scope OUT (the enclosing row's fields/intrinsics/lifts);\n                ^^name two scopes out. `^$path` = the enclosing row's path.\n  $repo.<t>     the root scan \u2014 $repo.docs / $repo.nodes / $repo.blocks /\n                $repo.edges \u2014 available from ANY depth (uncorrelated until you\n                add a ^ predicate). $repo.$id = the repository id.\n  $it           the current item itself (a row, or each ELEMENT when the\n                receiver is a list property); ^$it = the enclosing row.\n                $value is NOT an intrinsic (since oqx 0.15): it reads a\n                property literally named $value, absent when there is none.\n  $key          inside an entries(x) block: the entry's key.\n\n## Scalar semantics (@omgbase/oqx)\n\n  comparisons  ==  !=  <  <=  >  >=    strict & typed (5 == \"5\" is false); either\n                                       side may be a field (field-vs-field OK).\n  absence      null and a missing field are the same \"absent\" value; two absents\n               are EQUAL, so `absent != \"x\"` is TRUE and `absent == null` is TRUE.\n               Relational (< <= > >=) on an absent operand \u2192 FALSE. Bare `f` in\n               boolean position uses JS truthiness (absent/false/0/\"\" \u21D2 false;\n               NOTE: \"false\", [] and {} are truthy). has(f) = explicit presence.\n  boolean      &&  ||  !    grouping ( \u2026 )\n  arithmetic   + - * / %    (+ concatenates if either side is a string)\n  membership   x in y       array \u2192 typed membership; string \u2192 substring;\n                            object \u2192 key exists; range \u2192 coverage. Any list\n                            property works directly: \"pricing\" in tags. list(f)\n                            coerces scalar-or-list (absent \u2192 []) \u2014 use it when a\n                            key is sometimes scalar, sometimes a list.\n  ranges       lo..hi (inclusive)  lo...hi (exclusive hi)  ..hi  lo..\n               era in 800..1680; works over ISO dates. range(prop) reads a\n               range-shaped STRING property as an interval: \"2026-01-15\" in range(window).\n  strings      x.contains(\"s\") x.startsWith(\"p\") x.endsWith(\"s\") x.matches(\"^re$\")\n               (real regex) x.lower() x.upper() size(x). ALL CASE-SENSITIVE \u2014\n               fold with .lower(): $title.lower().contains(\"aurora\").\n  functions    has(f)  size(x)  list(x)  entries(x)  range(s)\n  literals     \"str\" 'str' 123 1.5 true false null\n  determinism  no now()/clock/random. Lists/structs are not literals; ternary is\n               not supported. Errors surface as filter_invalid.\n  scalars vs lists  a list-authored key never == a scalar (tags == \"x\" is false\n               when tags is a list) \u2014 use `\"x\" in tags` / `in list(tags)`.\n\n## Domain predicates (omgbase)\n\n  text(\"terms\")        FTS5 PRUNING predicate (docs match via their blocks, nodes\n                       via the node index); composes anywhere, incl. nested scopes.\n  semantic(\"phrase\")   embedding cosine SCORE (docs/blocks): threshold it\n                       (semantic(\"x\") > 0.6), project it, or `order by semantic(\"x\")\n                       desc` for top-K. Needs a provider; else semantic_unavailable.\n  blocks target only:\n    under(id_or_heading)      block in the containment subtree / section range\n    under_heading(\"Launch\")   an ancestor section heading contains the text (ci)\n    under_kind(type[, name])  an ancestor block has that type (name: its text\n                              contains / its key equals name)\n    within(\"path\" | \"d_..\")   containing doc = id, exact path, or path glob (*)\n    yaml_path(\"a.b\")          YAML docs: the block at that key path\n    json_pointer(\"#/a/b\")     JSON docs: the block at that pointer\n    has_edge(\"pred\"[, target])  an open authored edge with that predicate leaves here\n    has_anchor()              block carries an authored ^ref\n    parent_type() == \"x\"      parent block's type (must be compared)\n    child_count() > 0         number of direct children (must be compared)\n\n## Nested queries & consumers\n\n  <receiver> collect|exists|none|count|first|single { <block> }\n    receiver = a relation (nodes, blocks, doc.out_edges, section.blocks, \u2026), a\n    list property (tags), entries(x), or a root ($repo.docs).\n    block    = [select \u2026] [where \u2026] [follow \u2026] [order by \u2026] [limit N] [offset N]\n               \u2014 the same fixed order as the top level (`from` optional; the\n               receiver supplies the rows). A leading name/alias list is the\n               projection (`select` dropped); a predicate always needs `where`.\n  exists    \u22651 row      nodes exists { where kind == \"md:task\" && !checked }\n  none      0 rows      nodes none { where kind == \"md:task\" && !checked }  (\"every task done\")\n  count     a number    nodes count { where kind == \"md:task\" } >= 2\n  collect   rows (default) \u2014 in select for nested results; in where with a lift\n  first / single   zero-or-one (single errors on >1) \u2014 lookups in select\n  distinct  on any consumer: dedup by projected value \u2014 nodes count distinct { select kind }\n  limit/offset  bound the block's rows AFTER where/order/distinct, BEFORE the\n            consumer reduces: nodes exists { offset 1 } = at least two;\n            first { \u2026 offset 1 } = the second.\n  lift      `^name:` in a where-collect binds values outward:\n            select $path, open from docs where nodes collect { ^open: value where kind == \"md:task\" && !checked }\n  joins     $repo.<t> exists { where slug == ^ref }  semi-join; !\u2026 exists  anti-join;\n            $repo.nodes single { where kind == \"person\" && attrs.id == ^owner_id }  lookup;\n            x in ^keys  membership over a lifted set.\n\n## select \u2014 projection\n\n  select a, alias: expr, nested: nodes collect { \u2026 }\n  bare key \u2192 the property (scalar-authored \u2192 scalar; list \u2192 array); $-intrinsics;\n  a call/arithmetic needs an alias (n: size(tags)) unless in values mode.\n  \"$body\"     whole file bytes (docs) \u2014 docs_read is cheaper for one doc.\n  distinct    select distinct type   (dedup hits by projected value)\n  values      select <ONE item> values \u2192 bare values instead of records:\n                from docs select distinct type values          \u2192 values: [\"hub\",\"lab-note\",\u2026]\n                tags: tags collect { $it values }             \u2192 a plain array\n                h: nodes first { name values where kind == \"md:section\" order by first_ordinal }\n  entries(x)  a record as a collection ($key / $it per entry), key order:\n                select fm: entries(frontmatter) collect { k: $key, v: $it }\n                where entries(frontmatter) exists { where $key == \"era\" && $it > 1600 }\n                entries(inline), entries(attrs), a nested map, or a list (index keys)\n  $semantic_score is not a field \u2014 project semantic(\"\u2026\") under an alias instead.\n\n## order by, limit/offset, pagination\n\n  order by era desc, $path asc     absent values sort LAST (asc); ties \u2192 (path, id)\n  limit N / offset N               define the result SET (integer literals);\n                                   the tool's limit/cursor then page WITHIN it\n  cursor                           opaque keyset on (path,id); a custom order by\n                                   disables it (you get the top page + truncated)\n\n## Graph traversal (follow) and edges\n\n  from docs where <seed> follow doc.out            docs the seed links TO\n  from docs where <seed> follow doc.in             backlinks\n    follow doc.out { depth 3 }                     bound (1..8, default 8)\n    follow doc.out { where layer == \"canon\" }      keep only matching successors\n    follow doc.in { where before.contains(^$path) }   ^ = the row being expanded\n                                                   (^^ = the walk's enclosing scope)\n    follow doc.out, doc.in                         several destinations: their union\n                                                   (one step dedups by identity)\n    follow $repo.docs collect { where doc.out exists { where $path == ^^$path } }\n                                                   a destination block, re-read per\n                                                   frontier row (^ = that row) = doc.in\n    follow doc.out { frontier type == \"practitioner\" }   cut, keeping the frontier row\n    follow distinct doc.out / follow doc.out { by group } identity control\n  Per-occurrence metadata: $depth (seed = 1), $stop (interior|leaf|frontier|\n  depth|cycle), $leaf/$frontier, $ordinal \u2014 usable in select/order by and the\n  top-level post-walk where, NOT metadata of the candidates the follow-local\n  where/frontier read.\n  Type-preserving relations: doc.out/doc.in, block.children, section.children,\n  section.subsections.\n  from edges where $dst_path == \"notes/x.md\"       inbound edges to a doc, as rows\n  from edges where predicate == \"depends_on\" select $src, $dst_path\n  from docs where !doc.in_edges exists { }         orphans (nothing links in)\n  (The `graph` tool is a convenience wrapper that compiles to a follow query.)\n\n## semantic grain\n\nfrom docs ranks whole DOCUMENTS (one hit per file); from blocks ranks PASSAGES.\ntext()/where prune the candidate set; only order by reweights.\n\n## Examples\n\n  from docs where layer == \"working\"\n  from docs where $path.startsWith(\"guides/\") && $updated_at >= \"2026-08-01\"\n  from docs where \"pricing\" in list(tags) select layer, tags\n  from docs where inline.owner == \"alice\"\n  from docs where $title.lower().contains(\"q3 plan\")\n  from docs where format == \"yaml\"\n  from docs where type == \"practitioner\" order by era desc limit 2\n  from docs where nodes none { where kind == \"md:task\" && !checked }\n  from docs where tags exists { where $it == \"tria-prima\" }\n  from docs where $path == \"x.md\" select fm: entries(frontmatter) collect { k: $key, v: $it }\n  from docs select owner_id, owner: $repo.nodes single { where kind == \"person\" && attrs.id == ^owner_id }\n  from blocks where type == \"task\" && !checked && under_heading(\"Launch\") && doc.layer == \"working\"\n  from blocks where type == \"paragraph\" && has_edge(\"references\", \"d_92aaaaa\")\n  from blocks order by semantic(\"identity preservation across edits\") desc limit 10\n  from edges where dst_kind == \"external\" select $dst_uri\n  $repo.docs count { where layer == \"canon\" }\n\nCommon mistake: bare `path.startsWith(...)` meant the intrinsic \u2014 it fails loud\nwith a hint; write `$path.startsWith(...)`. Another: `where tags == \"x\"` on a\nlist-valued key is false \u2014 write `\"x\" in tags`.\n";
+export declare const QUERY_SYNTAX = "# query \u2014 OQX syntax reference\n\nThe `query` tool takes ONE plain OQX string (+ optional `limit`/`cursor`). There\nis no {from, filter, order} envelope: every concern is a clause of the string.\n\n  [select <items>] from <target> [where <pred>] [follow <dest>, \u2026 [{ \u2026 }]]\n                   [order by <expr> [asc|desc], \u2026] [limit N] [offset N]\n  <target> count|exists|none|first|single { <block> }     (scalar/one-row form: a bare target at the root scope)\n\nCLAUSE ORDER IS FIXED: select, from, where, follow, order by, limit, offset \u2014\neach at most once; an out-of-order clause is a parse error naming the order.\nOnly `select` may drop its keyword, and only as the first clause\n(`$path, era from docs where \u2026`). Every other clause always carries its keyword:\na predicate is NEVER implicit (`nodes exists { where kind == \"md:task\" }`, not\n`{ name, kind == \"md:task\" }` \u2014 but a block may LEAD with a predicate, see Sugar),\nand `from docs count` is an error (write `docs count { \u2026 }`). `where` and\nlater `select` items may use the same body's `select` aliases\n(`select $path, old: era < 1000 from docs where old`; an alias shadows a\nsame-named field there).\n\n## Sugar (OQX 0.17)\n\nEvery form here is shorthand for an explicit directive (the AST is the explicit form):\n  nodes { kind == \"md:task\" }        \u2261 nodes collect { where kind == \"md:task\" } \u2014 a receiver block with\n                                       no consumer is collect; a block whose LEADING expression is a predicate\n                                       (comparison, call, !/is/not, in, literal, (\u2026), a consumer test \u2014 anything\n                                       but a bare name, a dotted path or a ^lift) is where-first. Bare names still\n                                       project: nodes { name } \u2261 nodes collect { name }; filter a bare field with\n                                       nodes { is checked }. Not after follow: follow children { depth 2 } is options.\n  refs(x)[0]                          \u2261 refs(x) first { offset 0 }   positional (integer literal or ${binding});\n                                       out of range \u21D2 absent; refs(x)[0].$path navigates the row\n  ^docs[$path == ^company]            \u2261 ^docs first { where $path == ^company }   first match or absent\n  ^docs[$path == ^company]!           \u2261 \u2026 single { \u2026 } required: exactly one, else filter_invalid\n  title!                              required: title, or an error naming the expression (and the row's $id)\n                                       \u2014 never a filter, never a coercion (0!, \"\"! are values); tightest: a!.b vs a.b!\n  is x / not x                        \u2261 !!x / !x (truthiness)\n  x is y / x is not y                 identity (a row's id, else structural) \u2014 compares rows, which == does not;\n                                       x is null = absent; for scalars is \u2261 ==; comparison precedence, no chaining\n  a and b / a or b                    \u2261 a && b / a || b (same precedence, short-circuit, value: title or $path coalesces)\n  boss: ^docs[$path == ^manager], bossName: boss.$title   a select item may use the items to its LEFT\n  Reserved words (never a bare field name): from where select is not and or, true false null.\n\nResults are LEAN hits \u2014 {id, path} + whatever `select` projects (or `values`,\n`count`, `exists`, `none`). Hydrate full content by id via nodes_get/docs_read.\n\n## Paths\n\nEvery path the surface returns is `/`-rooted \u2014 the form a reference is\nwritten in (`[x](/projects/oqx.md)`, `before: [/timeline/kickoff.md]`): a\nhit's `path`, `$path`, `$dst_path`, every tool's paths. Every path it\naccepts tolerates both forms (`/a.md` or `a.md`): tool arguments, `refs(x)`,\n`within(...)`, and a string LITERAL compared with `$path`/`$dst_path` by\n`==`/`!=` or passed to their `.startsWith(...)` (it is rooted first, so\n`$path == \"a.md\"` and `$path == \"/a.md\"` both match). A property holding a\nreference compares directly: `where ^$path in list(after)`,\n`where customer == ^$path` \u2014 no `\"/\" + ...` glue.\n\n## Targets & field namespaces\n\nThe sigil rule: `$`-prefixed names are engine intrinsics; BARE identifiers are\nyour content. On docs a bare first segment that collides with an intrinsic base\nname (id/path/updated_at/content_hash/body) is REJECTED with a \"did you mean\n$X?\" hint (bare `path` would silently read an absent frontmatter key). Force the\nproperty with `frontmatter.<k>`. `title`/`tags` are NOT reserved: `$title`/`$tags`\nare computed and never shadow an authored `title:`/`tags:` key.\n\ndocs:\n  - bare identifier  = a document PROPERTY (frontmatter + inline `key:: value`,\n                       unioned; nested via dots: meta.owner). YAML/JSON docs\n                       expose the parsed object's keys the same way.\n  - source-scoped    = frontmatter.<k> / inline.<k>; the whole bag as a collection\n                       via entries(frontmatter) / entries(inline) (see entries()).\n  - computed         = $title (first H1), $tags (body #hashtags), format\n                       (the doc's format \u2014 \"markdown\"/\"yaml\"/\"json\"; a bare\n                       computed field, present on EVERY doc, so has(format) is\n                       always true and `format == \"yaml\"` is the filter).\n  - intrinsics       = $id, $path (/-rooted, see Paths), $updated_at (ISO-8601,\n                       sorts chronologically), $body (whole file), $content_hash.\n  - relations        = nodes, blocks, doc.out / doc.in (citation graph),\n                       doc.out_edges / doc.in_edges (a doc's edges as rows).\n\nblocks:\n  - bare fields      = type, text, and every attrs key FLATTENED onto the row\n                       (bare `checked` reads attrs.checked; `attrs.<k>` still\n                       works; type/text win on collision; absent \u21D2 false).\n  - intrinsics       = $id, $doc, $path, $ordinal, $depth, $updated_at, $body\n                       (the block text), $content_hash (the block's OWN raw hash \u2014\n                       the value update/split expect).\n  - reach-through    = doc.<key> / doc.$path / doc.format = the CONTAINING doc.\n  - relations        = block.children, block.nodes, block.out_edges, section.\n\nnodes:\n  - bare fields      = kind (md:task / md:link / md:section / yaml:\u2026), name,\n                       value, + attrs keys flattened (checked, level).\n  - intrinsics       = $id (=$node_id), $doc_id, $block_id, $path.\n  - reach-through    = doc.<key>, block.type / block.text.\n  - relations        = section.blocks, section.children, section.subsections.\n\nedges:  (the authored link graph as rows \u2014 one per open edge)\n  - bare fields      = predicate (\"references\"/\"embeds\"/freeform), provenance\n                       (\"link\"/\"frontmatter\"/\"inline_field\"/\u2026), dst_kind\n                       (\"document\"/\"external\"/\"collection\"), anchor, src_field\n  - intrinsics       = $id, $src, $dst, $dst_path (target doc path, /-rooted;\n                       NULL when dangling/external), $dst_uri (external URL;\n                       NULL otherwise), $src_block, $via, $from_commit; $path\n                       and doc.<key> reach the SOURCE document.\n  - text()/semantic() are N/A on edges.\n\n## Scoping (ADR-015; the root row since surface 2.0): bare names are LOCAL\n\n  name          the CURRENT row only \u2014 never falls through to an enclosing row\n                or the repository; an absent field is simply absent.\n  ^name         one scope OUT (the enclosing row's fields/intrinsics/lifts);\n                ^^name two scopes out. `^$path` = the enclosing row's path.\n  ^docs ^nodes ^blocks ^edges\n                THE ROOT ROW (surface 2.0, oqx 0.18): the repository is the root\n                scope's row, one scope out from a top-level row, so ^docs there is\n                the whole documents scan (uncorrelated until you add a ^ predicate);\n                one caret per enclosing block (^^docs from depth two), or the\n                absolute 0^docs from ANY depth. ^$id / 0^$id = the repository id.\n                ^$it = the root object: ^$it.docs \u2261 ^docs, entries(^$it) names the\n                four collections. At the root scope itself a bare target is the scan\n                (docs count { \u2026 }, from docs, entries(docs)).\n                ERRORS: a bare `docs` INSIDE a block reads a property of the current\n                row, which has none \u2014 refused (\"did you mean ^docs\"); `^docs` AT THE\n                TOP LEVEL reaches past the root \u2014 refused (write the bare `docs`);\n                so is `$repo` (surface < 2.0; the message names the replacement).\n                nodes/blocks on a doc row are that doc's RELATIONS, not the root.\n  $it           the current item itself (a row, or each ELEMENT when the\n                receiver is a list property); ^$it = the enclosing row.\n                $value is NOT an intrinsic (since oqx 0.15): it reads a\n                property literally named $value, absent when there is none.\n  $key          inside an entries(x) block: the entry's key.\n\n## Scalar semantics (@omgbase/oqx)\n\n  comparisons  ==  !=  <  <=  >  >=    strict & typed (5 == \"5\" is false); either\n                                       side may be a field (field-vs-field OK).\n  absence      null and a missing field are the same \"absent\" value; two absents\n               are EQUAL, so `absent != \"x\"` is TRUE and `absent == null` is TRUE.\n               Relational (< <= > >=) on an absent operand \u2192 FALSE. Bare `f` in\n               boolean position uses JS truthiness (absent/false/0/\"\" \u21D2 false;\n               NOTE: \"false\", [] and {} are truthy). has(f) = explicit presence.\n  boolean      &&  ||  !    grouping ( \u2026 )\n  arithmetic   + - * / %    (+ concatenates if either side is a string)\n  membership   x in y       array \u2192 typed membership; string \u2192 substring;\n                            object \u2192 key exists; range \u2192 coverage. Any list\n                            property works directly: \"pricing\" in tags. list(f)\n                            coerces scalar-or-list (absent \u2192 []) \u2014 use it when a\n                            key is sometimes scalar, sometimes a list.\n  ranges       lo..hi (inclusive)  lo...hi (exclusive hi)  ..hi  lo..\n               era in 800..1680; works over ISO dates. range(prop) reads a\n               range-shaped STRING property as an interval: \"2026-01-15\" in range(window).\n  strings      x.contains(\"s\") x.startsWith(\"p\") x.endsWith(\"s\") x.matches(\"^re$\")\n               (real regex) x.lower() x.upper() size(x). ALL CASE-SENSITIVE \u2014\n               fold with .lower(): $title.lower().contains(\"aurora\").\n  functions    has(f)  size(x)  list(x)  entries(x)  range(s)\n  literals     \"str\" 'str' 123 1.5 true false null\n  determinism  no now()/clock/random. Lists/structs are not literals; ternary is\n               not supported. Errors surface as filter_invalid.\n  scalars vs lists  a list-authored key never == a scalar (tags == \"x\" is false\n               when tags is a list) \u2014 use `\"x\" in tags` / `in list(tags)`.\n\n## Domain predicates (omgbase)\n\n  text(\"terms\")        FTS5 PRUNING predicate (docs match via their blocks, nodes\n                       via the node index); composes anywhere, incl. nested scopes.\n  semantic(\"phrase\")   embedding cosine SCORE (docs/blocks): threshold it\n                       (semantic(\"x\") > 0.6), project it, or `order by semantic(\"x\")\n                       desc` for top-K. Needs a provider; else semantic_unavailable.\n  blocks target only:\n    under(id_or_heading)      block in the containment subtree / section range\n    under_heading(\"Launch\")   an ancestor section heading contains the text (ci)\n    under_kind(type[, name])  an ancestor block has that type (name: its text\n                              contains / its key equals name)\n    within(\"path\" | \"d_..\")   containing doc = id, exact path, or path glob (*);\n                              either path form\n    yaml_path(\"a.b\")          YAML docs: the block at that key path\n    json_pointer(\"#/a/b\")     JSON docs: the block at that pointer\n    has_edge(\"pred\"[, target])  an open authored edge with that predicate leaves here\n    has_anchor()              block carries an authored ^ref\n    parent_type() == \"x\"      parent block's type (must be compared)\n    child_count() > 0         number of direct children (must be compared)\n  refs(x)              the live documents a property's document references name:\n                       x is a string, a list or absent; each \"/a/b.md\", \"a/b.md\"\n                       or \"d_\u2026\" element resolves to that doc's row; dangling and\n                       non-string elements are dropped. Yields docs rows, so it is\n                       a source, a receiver or a follow destination:\n                       follow refs(before), refs(after) walks a timeline both ways.\n                       The reverse direction needs no function: a document's\n                       $path is already the reference form, so\n                       ^docs collect { where ^$path in list(after) } is\n                       \"the documents whose `after` names me\".\n  A HIT IS A STORE ROW: a top-level row that is not a doc/block/node/edge fails\n                       (filter_invalid). `follow before` over a list of paths\n                       reaches the STRINGS \u2014 write `follow refs(before)`.\n\n## Nested queries & consumers\n\n  <receiver> collect|exists|none|count|first|single { <block> }\n    receiver = a relation (nodes, blocks, doc.out_edges, section.blocks, \u2026), a\n    list property (tags), entries(x), or a root collection (^docs; 0^docs at depth \u2265 2).\n    block    = [select \u2026] [where \u2026] [follow \u2026] [order by \u2026] [limit N] [offset N]\n               \u2014 the same fixed order as the top level (`from` optional; the\n               receiver supplies the rows). A leading name/alias list is the\n               projection (`select` dropped); a predicate always needs `where`.\n  exists    \u22651 row      nodes exists { where kind == \"md:task\" && !checked }\n  none      0 rows      nodes none { where kind == \"md:task\" && !checked }  (\"every task done\")\n  count     a number    nodes count { where kind == \"md:task\" } >= 2\n  collect   rows (default) \u2014 in select for nested results; in where with a lift\n  first / single   zero-or-one (single errors on >1) \u2014 lookups in select\n  distinct  on any consumer: dedup by projected value \u2014 nodes count distinct { select kind }\n  limit/offset  bound the block's rows AFTER where/order/distinct, BEFORE the\n            consumer reduces: nodes exists { offset 1 } = at least two;\n            first { \u2026 offset 1 } = the second.\n  lift      `^name:` in a where-collect binds values outward:\n            select $path, open from docs where nodes collect { ^open: value where kind == \"md:task\" && !checked }\n  joins     ^<t> exists { where slug == ^ref }  semi-join; !\u2026 exists  anti-join;\n            ^nodes single { where kind == \"person\" && attrs.id == ^owner_id }  lookup;\n            x in ^keys  membership over a lifted set.\n\n## select \u2014 projection\n\n  select a, alias: expr, nested: nodes collect { \u2026 }\n  bare key \u2192 the property (scalar-authored \u2192 scalar; list \u2192 array); $-intrinsics;\n  a call/arithmetic needs an alias (n: size(tags)) unless in values mode.\n  \"$body\"     whole file bytes (docs) \u2014 docs_read is cheaper for one doc.\n  distinct    select distinct type   (dedup hits by projected value)\n  values      select <ONE item> values \u2192 bare values instead of records:\n                from docs select distinct type values          \u2192 values: [\"hub\",\"lab-note\",\u2026]\n                select $path values from docs                  \u2192 values: [\"/index.md\", \u2026]\n                tags: tags collect { $it values }             \u2192 a plain array\n                h: nodes first { name values where kind == \"md:section\" order by first_ordinal }\n  entries(x)  a record as a collection ($key / $it per entry), key order:\n                select fm: entries(frontmatter) collect { k: $key, v: $it }\n                where entries(frontmatter) exists { where $key == \"era\" && $it > 1600 }\n                entries(inline), entries(attrs), a nested map, or a list (index keys)\n  $semantic_score is not a field \u2014 project semantic(\"\u2026\") under an alias instead.\n\n## order by, limit/offset, pagination\n\n  order by era desc, $path asc     absent values sort LAST (asc); ties \u2192 (path, id)\n  limit N / offset N               define the result SET (integer literals);\n                                   the tool's limit/cursor then page WITHIN it\n  cursor                           opaque keyset on (path,id); a custom order by\n                                   disables it (you get the top page + truncated)\n\n## Graph traversal (follow) and edges\n\n  from docs where <seed> follow doc.out            docs the seed links TO\n  from docs where <seed> follow doc.in             backlinks\n    follow doc.out { depth 3 }                     bound (1..8, default 8)\n    follow doc.out { where layer == \"canon\" }      keep only matching successors\n    follow doc.in { where ^$path in list(before) }    ^ = the row being expanded\n                                                   (^^ = the walk's enclosing scope)\n    follow doc.out, doc.in                         several destinations: their union\n                                                   (one step dedups by identity)\n    follow ^docs collect { where doc.out exists { where $path == ^^$path } }\n                                                   a destination block, re-read per\n                                                   frontier row (^ = that row; ^docs\n                                                   is the root's documents) = doc.in\n    follow doc.out { frontier type == \"practitioner\" }   cut, keeping the frontier row\n    follow distinct doc.out / follow doc.out { by group } identity control\n  Per-occurrence metadata: $depth (seed = 1), $stop (interior|leaf|frontier|\n  depth|cycle), $leaf/$frontier, $ordinal \u2014 usable in select/order by and the\n  top-level post-walk where, NOT metadata of the candidates the follow-local\n  where/frontier read.\n  Type-preserving relations: doc.out/doc.in, block.children, section.children,\n  section.subsections.\n  from edges where $dst_path == \"/notes/x.md\"      inbound edges to a doc, as rows\n  from edges where predicate == \"depends_on\" select $src, $dst_path\n  from docs where !doc.in_edges exists { }         orphans (nothing links in)\n  (The `graph` tool is a convenience wrapper that compiles to a follow query.)\n\n## semantic grain\n\nfrom docs ranks whole DOCUMENTS (one hit per file); from blocks ranks PASSAGES.\ntext()/where prune the candidate set; only order by reweights.\n\n## Examples\n\n  from docs where layer == \"working\"\n  from docs where $path.startsWith(\"/guides/\") && $updated_at >= \"2026-08-01\"\n  from docs where \"pricing\" in list(tags) select layer, tags\n  from docs where inline.owner == \"alice\"\n  from docs where $title.lower().contains(\"q3 plan\")\n  from docs where format == \"yaml\"\n  from docs where type == \"practitioner\" order by era desc limit 2\n  from docs where nodes none { where kind == \"md:task\" && !checked }\n  from docs where tags exists { where $it == \"tria-prima\" }\n  from docs where $path == \"/x.md\" select fm: entries(frontmatter) collect { k: $key, v: $it }\n  from docs select owner_id, owner: ^nodes single { where kind == \"person\" && attrs.id == ^owner_id }\n  from blocks where type == \"task\" && !checked && under_heading(\"Launch\") && doc.layer == \"working\"\n  from blocks where type == \"paragraph\" && has_edge(\"references\", \"d_92aaaaa\")\n  select $path, $depth from docs where $path == \"/timeline/review.md\" follow refs(before), refs(after)\n  select $path, next: ^docs collect { $path where ^$path in list(before) } from docs where type == \"milestone\"\n  select $path, n: ^docs count { }, id: ^$id from docs limit 1\n  select $path, back: nodes first { select p: 0^docs collect { $path where ^^$path in list(after) } values } from docs where type == \"milestone\"\n  select $path, prior: refs(before) collect { $path, when } from docs where type == \"milestone\"\n  from blocks order by semantic(\"identity preservation across edits\") desc limit 10\n  from edges where dst_kind == \"external\" select $dst_uri\n  docs count { where layer == \"canon\" }\n\nCommon mistake: bare `path.startsWith(...)` meant the intrinsic \u2014 it fails loud\nwith a hint; write `$path.startsWith(...)`. Another: `where tags == \"x\"` on a\nlist-valued key is false \u2014 write `\"x\" in tags`.\n";

package/dist/src/mcp/reference.js

@@ -12,26 +12,61 @@ is no {from, filter, order} envelope: every concern is a clause of the string.
 
   [select <items>] from <target> [where <pred>] [follow <dest>, … [{ … }]]
                    [order by <expr> [asc|desc], …] [limit N] [offset N]
-  $repo.<target> count|exists|none|first|single { <block> }     (scalar/one-row form)
+  <target> count|exists|none|first|single { <block> }     (scalar/one-row form: a bare target at the root scope)
 
 CLAUSE ORDER IS FIXED: select, from, where, follow, order by, limit, offset —
 each at most once; 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 …\`). Every other clause always carries its keyword:
 a predicate is NEVER implicit (\`nodes exists { where kind == "md:task" }\`, not
-\`{ kind == "md:task" }\`), and \`from docs count\` is an error (write
-\`$repo.docs count { … }\`). \`where\` may use the same body's \`select\` aliases
+\`{ name, kind == "md:task" }\` — but a block may LEAD with a predicate, see Sugar),
+and \`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).
 
+## 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
+                                       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 }. Not after follow: follow children { depth 2 } is options.
+  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 $id)
+                                       — never a filter, never a coercion (0!, ""! are values); tightest: a!.b vs a.b!
+  is x / not x                        ≡ !!x / !x (truthiness)
+  x is y / x is not y                 identity (a 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                    ≡ a && b / a || b (same precedence, short-circuit, value: title or $path 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.
+
 Results are LEAN hits — {id, path} + whatever \`select\` projects (or \`values\`,
 \`count\`, \`exists\`, \`none\`). Hydrate full content by id via nodes_get/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\`, \`$path\`, \`$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\` 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: \`where ^$path in list(after)\`,
+\`where customer == ^$path\` — no \`"/" + ...\` glue.
+
 ## Targets & field namespaces
 
 The sigil rule: \`$\`-prefixed names are engine intrinsics; BARE identifiers are
 your content. On docs a bare first segment that collides with an intrinsic base
-name (id/path/repo/updated_at/content_hash/body) is REJECTED with a "did you mean
+name (id/path/updated_at/content_hash/body) is REJECTED with a "did you mean
 $X?" hint (bare \`path\` would silently read an absent frontmatter key). Force the
 property with \`frontmatter.<k>\`. \`title\`/\`tags\` are NOT reserved: \`$title\`/\`$tags\`
 are computed and never shadow an authored \`title:\`/\`tags:\` key.
@@ -46,8 +81,8 @@ docs:
                        (the doc's format — "markdown"/"yaml"/"json"; a bare
                        computed field, present on EVERY doc, so has(format) is
                        always true and \`format == "yaml"\` is the filter).
-  - intrinsics       = $id, $path, $updated_at (ISO-8601, sorts chronologically),
-                       $body (whole file), $content_hash.
+  - intrinsics       = $id, $path (/-rooted, see Paths), $updated_at (ISO-8601,
+                       sorts chronologically), $body (whole file), $content_hash.
   - relations        = nodes, blocks, doc.out / doc.in (citation graph),
                        doc.out_edges / doc.in_edges (a doc's edges as rows).
 
@@ -72,21 +107,32 @@ edges:  (the authored link graph as rows — one per open edge)
   - bare fields      = predicate ("references"/"embeds"/freeform), provenance
                        ("link"/"frontmatter"/"inline_field"/…), dst_kind
                        ("document"/"external"/"collection"), anchor, src_field
-  - intrinsics       = $id, $src, $dst, $dst_path (target doc path; NULL when
-                       dangling/external), $dst_uri (external URL; NULL
-                       otherwise), $src_block, $via, $from_commit; $path and
-                       doc.<key> reach the SOURCE document.
+  - intrinsics       = $id, $src, $dst, $dst_path (target doc path, /-rooted;
+                       NULL when dangling/external), $dst_uri (external URL;
+                       NULL otherwise), $src_block, $via, $from_commit; $path
+                       and doc.<key> reach the SOURCE document.
   - text()/semantic() are N/A on edges.
 
-## Scoping (ADR-015): bare names are LOCAL
+## 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.
-  $repo.<t>     the root scan — $repo.docs / $repo.nodes / $repo.blocks /
-                $repo.edges — available from ANY depth (uncorrelated until you
-                add a ^ predicate). $repo.$id = the repository id.
+  ^docs ^nodes ^blocks ^edges
+                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.
+                ^$it = the root object: ^$it.docs ≡ ^docs, entries(^$it) names the
+                four collections. At the root scope itself a bare target is the scan
+                (docs count { … }, from docs, 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.
   $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
@@ -134,19 +180,33 @@ edges:  (the authored link graph as rows — one per open edge)
     under_heading("Launch")   an ancestor section heading contains the text (ci)
     under_kind(type[, name])  an ancestor block has that type (name: its text
                               contains / its key equals name)
-    within("path" | "d_..")   containing doc = id, exact path, or path glob (*)
+    within("path" | "d_..")   containing doc = id, exact path, or path glob (*);
+                              either path form
     yaml_path("a.b")          YAML docs: the block at that key path
     json_pointer("#/a/b")     JSON docs: the block at that pointer
     has_edge("pred"[, target])  an open authored edge with that predicate leaves here
     has_anchor()              block carries an authored ^ref
     parent_type() == "x"      parent block's type (must be compared)
     child_count() > 0         number of direct children (must be compared)
+  refs(x)              the live documents a property's document references name:
+                       x is a string, a list or absent; each "/a/b.md", "a/b.md"
+                       or "d_…" element resolves to that doc's row; dangling and
+                       non-string elements are dropped. Yields docs rows, so it is
+                       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 collect { where ^$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
+                       reaches the STRINGS — write \`follow refs(before)\`.
 
 ## Nested queries & consumers
 
   <receiver> collect|exists|none|count|first|single { <block> }
     receiver = a relation (nodes, blocks, doc.out_edges, section.blocks, …), a
-    list property (tags), entries(x), or a root ($repo.docs).
+    list property (tags), entries(x), or a root collection (^docs; 0^docs at depth ≥ 2).
     block    = [select …] [where …] [follow …] [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
@@ -162,8 +222,8 @@ edges:  (the authored link graph as rows — one per open edge)
             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" && !checked }
-  joins     $repo.<t> exists { where slug == ^ref }  semi-join; !… exists  anti-join;
-            $repo.nodes single { where kind == "person" && attrs.id == ^owner_id }  lookup;
+  joins     ^<t> exists { where slug == ^ref }  semi-join; !… exists  anti-join;
+            ^nodes single { where kind == "person" && attrs.id == ^owner_id }  lookup;
             x in ^keys  membership over a lifted set.
 
 ## select — projection
@@ -175,6 +235,7 @@ edges:  (the authored link graph as rows — one per open edge)
   distinct    select distinct type   (dedup hits by projected value)
   values      select <ONE item> values → bare values instead of records:
                 from docs select distinct type values          → 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 }
   entries(x)  a record as a collection ($key / $it per entry), key order:
@@ -197,13 +258,14 @@ edges:  (the authored link graph as rows — one per open edge)
   from docs where <seed> follow doc.in             backlinks
     follow doc.out { depth 3 }                     bound (1..8, default 8)
     follow doc.out { where layer == "canon" }      keep only matching successors
-    follow doc.in { where before.contains(^$path) }   ^ = the row being expanded
+    follow doc.in { where ^$path in list(before) }    ^ = the row being expanded
                                                    (^^ = the walk's enclosing scope)
     follow doc.out, doc.in                         several destinations: their union
                                                    (one step dedups by identity)
-    follow $repo.docs collect { where doc.out exists { where $path == ^^$path } }
+    follow ^docs collect { where doc.out exists { where $path == ^^$path } }
                                                    a destination block, re-read per
-                                                   frontier row (^ = that row) = doc.in
+                                                   frontier row (^ = that row; ^docs
+                                                   is the root's documents) = doc.in
     follow doc.out { frontier type == "practitioner" }   cut, keeping the frontier row
     follow distinct doc.out / follow doc.out { by group } identity control
   Per-occurrence metadata: $depth (seed = 1), $stop (interior|leaf|frontier|
@@ -212,7 +274,7 @@ edges:  (the authored link graph as rows — one per open edge)
   where/frontier read.
   Type-preserving relations: doc.out/doc.in, block.children, section.children,
   section.subsections.
-  from edges where $dst_path == "notes/x.md"       inbound edges to a doc, as rows
+  from edges where $dst_path == "/notes/x.md"      inbound edges to a doc, as rows
   from edges where predicate == "depends_on" select $src, $dst_path
   from docs where !doc.in_edges exists { }         orphans (nothing links in)
   (The \`graph\` tool is a convenience wrapper that compiles to a follow query.)
@@ -225,7 +287,7 @@ text()/where prune the candidate set; only order by reweights.
 ## Examples
 
   from docs where layer == "working"
-  from docs where $path.startsWith("guides/") && $updated_at >= "2026-08-01"
+  from docs where $path.startsWith("/guides/") && $updated_at >= "2026-08-01"
   from docs where "pricing" in list(tags) select layer, tags
   from docs where inline.owner == "alice"
   from docs where $title.lower().contains("q3 plan")
@@ -233,13 +295,18 @@ text()/where prune the candidate set; only order by reweights.
   from docs where type == "practitioner" order by era desc limit 2
   from docs where nodes none { where kind == "md:task" && !checked }
   from docs where tags exists { where $it == "tria-prima" }
-  from docs where $path == "x.md" select fm: entries(frontmatter) collect { k: $key, v: $it }
-  from docs select owner_id, owner: $repo.nodes single { where kind == "person" && attrs.id == ^owner_id }
+  from docs where $path == "/x.md" select fm: entries(frontmatter) collect { k: $key, v: $it }
+  from docs select owner_id, owner: ^nodes single { where kind == "person" && attrs.id == ^owner_id }
   from blocks where type == "task" && !checked && under_heading("Launch") && doc.layer == "working"
   from blocks where type == "paragraph" && 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: ^docs count { }, id: ^$id from docs limit 1
+  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
   from edges where dst_kind == "external" select $dst_uri
-  $repo.docs count { where layer == "canon" }
+  docs count { where layer == "canon" }
 
 Common mistake: bare \`path.startsWith(...)\` meant the intrinsic — it fails loud
 with a hint; write \`$path.startsWith(...)\`. Another: \`where tags == "x"\` on a