yamlover 0.3.48 → 0.3.50

package/dist/agent-docs/AGENTS.md

@@ -6,9 +6,10 @@ yamlover web UI (`npx yamlover .`) while you read and edit the files on disk. Th
 tells you how to manipulate these files **correctly** so you don't corrupt the data or break the
 human's live view.
 
-> This file is self-contained. You do **not** need any other spec to follow it. If the project
-> also contains files like `YAMLOVER.md`, `SEPARATOR.md`, `QUERY.md`, or `ANNOTATIONS.md`, those
-> are the authoritative, deeper specs — consult them for edge cases.
+> This file is self-contained. You do **not** need any other spec to follow it. The full,
+> authoritative spec is the yamlover documentation book (the `docs/` tree of the yamlover
+> project itself — the language under `docs/language/`, the document model under
+> `docs/documents/`); consult it for edge cases.
 
 ---
 
@@ -19,13 +20,13 @@ yamlover is a **distinct, YAML-like language** — close to YAML and mostly read
 document that uses aliases/anchors does **not** round-trip identically. On top of a YAML-style
 surface it adds a small **pointer layer** so that data forms a graph, not just a tree:
 
-- **`*` pointers** — a value that *refers to* another node (a shared edge, not a copy).
+- **`*` pointers** — a value that *refers to* another node (a ref edge, not a copy).
 - **`&` path anchors** — declare that "this node also lives over there" (the push side of `*`).
 - **`!!` tags** — type/schema markers, including inline schema references `!!<…>`.
 
 There is a sibling brace surface called **json5p** (`.json5p` files) — the same pointer layer
-expressed in JSON5 syntax. Most projects use `.yamlover`; treat `.json5p` as the JSON-flavored
-twin (pointers are written as quoted strings, e.g. `*": pets[1]"`).
+expressed in JSON5 syntax. Most projects use `.yo`; treat `.json5p` as the JSON-flavored
+twin (pointers are written as quoted strings, e.g. `*": pets: 1"`).
 
 **Important:** because `*` and `&` mean something different than in stock YAML (a `*` is a path
 pointer, **not** a YAML alias), these files require the yamlover parser. Do not "fix" them with
@@ -37,29 +38,30 @@ a generic YAML formatter — you will destroy the pointers and anchors.
 
 Plain YAML forces a node to be **either** a sequence (all `- item`) **or** a mapping (all
 `key: value`). yamlover unifies them: there is **one ordered container**. Every entry has an
-integer **position** (`[0]`, `[1]`, …) and **may also** carry a string key. Keyless (positional)
+integer **position** (0, 1, …) and **may also** carry a string key. Keyless (positional)
 and keyed entries coexist in one node — this is the default ("omni"):
 
 ```yamlover
 playlist:
-  - Intro                  # [0]            keyless / positional
-  - Verse                  # [1]            keyless
-  title: Greatest Hits     # [2], key=title keyed — AND still positioned
-  - Chorus                 # [3]            keyless
-  encore: *: pets[0]       # [4], key=encore a keyed pointer, still in order
+  - Intro                  # position 0            keyless / positional
+  - Verse                  # position 1            keyless
+  title: Greatest Hits     # position 2, key=title keyed — AND still positioned
+  - Chorus                 # position 3            keyless
+  encore: *: pets: 0       # position 4, key=encore a keyed pointer, still in order
 ```
 
 A node can even carry a **scalar value AND fields at once**:
 
 ```yamlover
 rating: 5                  # the node's own scalar value …
-  - solid                  # [0]  positional field
-  scale: 10                # [2]  keyed field
+  - solid                  # position 0  positional field
+  scale: 10                # position 2  keyed field
 ```
 
-(You may see optional `!!mix` / `!!var` tags marking these shapes. They are **no-op readability
-markers** — mixing and scalar-plus-fields are the default. Don't add or remove them to change
-meaning; they don't carry any.)
+(You may see an optional `!!mix` tag marking these shapes. It is a **no-op readability marker**
+— mixing and scalar-plus-fields are the default. Don't add or remove it to change meaning; it
+doesn't carry any. `!!yo` — whose deprecated aliases `!!var` / `!!omni` still parse — is a
+DIFFERENT thing and is **semantic**: see §6.)
 
 ---
 
@@ -79,29 +81,48 @@ parses as a path: `*/pets` is a dangling reference to the literal key "/pets". A
 current: object: path                         # bare       — current scope (siblings)
 : document: rooted: path                      # :          — this document's root
 :: project: rooted: path                      # ::         — this project's root
-::: yamlover.inthemoon.net: $defs: tag        # :::        — the world (an external project)
+::: yamlover.inthemoon.net: $defs: onto        # :::        — the world (an external project)
 ```
 
-- `*pets[1]` — bare: a **sibling** named `pets`, position 1.
-- `*: pets[0]` — `:` document root.
-- `*:: tags: genre` — `::` this project's root.
-- `*::: host.example: $defs: tag` — `:::` a world/external reference.
+- `*pets: 1` — bare: a **sibling** named `pets`, position 1.
+- `*: pets: 0` — `:` document root.
+- `*:: ontos: genre` — `::` this project's root.
+- `*::: host.example: $defs: onto` — `:::` a world/external reference.
 
-`[n]` addresses by **position** (integer key); a bare word addresses by **string key**. They
-chain: `*: pets[1]: name` = root → position 1 → key `name`.
+### The bare-token rule — what a portion means
+
+Every portion is typed **by its own form**:
+
+- **pure digits** = the integer key, i.e. a **position**: `*: pets: 1: name` = root → position 1
+  → key `name`.
+- **a bare `~`** = the **null key** (`~: value`; `: v` is the same entry). The *string* key
+  `"null"` is written `null:`.
+- **anything else bare, and any quoted portion** = a **string key**: `: '1'` is the numeric
+  string key, `: '~'` the literal tilde.
+
+A key whose bare form would read as something else MUST be quoted: empty, pure digits, `~`,
+`-`+digits, or a key containing a space. In a document, a plain `1:` is a **parse error** —
+author `'1':` for the numeric string key.
+
+> **The retired bracket index.** The old `[n]` position form (`*pets[1]`) still *reads* — it is
+> a permanent alias — but it is **written never**. Author the bare-integer segment. The one
+> surviving bracket operator is `[.±k]` (a position relative to the pointer's own host). The
+> former `[]` (append) and `[?]` (any position) brackets were REMOVED — both are now the `-`
+> segment: a trailing `: -` on a bookmark appends (§5), and `-` in a query matches any
+> position. A literal `-` key must be quoted (`'-'`).
 
 ---
 
 ## 4. Pointers `*` (the pull side)
 
-A `*` value dereferences a path to another node and creates a **shared edge** (not a copy):
+A `*` value dereferences a path to another node and creates a **ref edge** (not a copy):
 
 ```yamlover
 humans:
   - name: Alice
-    manager: *: pets[1]      # Alice.manager IS the node at root → pets → position 1
-feline: *pets[1]             # bare → a sibling
-topDog: *: pets[0]           # : → document root
+    manager: *: pets: 1      # Alice.manager IS the node at root → pets → position 1
+feline: *pets: 1             # bare → a sibling
+topDog: *: pets: 0           # : → document root
 ```
 
 Pointers are **lazy** and **cycle-safe** — pointing two nodes at each other is fine. Editing the
@@ -118,7 +139,7 @@ target changes everything that points at it.
 boss: &: chief             # this node is ALSO reachable as the document-root key `chief`
   name: Rex
 team:
-  lead: *: chief           # same node as `boss` — a shared edge, not a copy
+  lead: *: chief           # same node as `boss` — a ref edge, not a copy
 ```
 
 Reverse relations are spelled as anchors. `&: parent: child` means "parent holds me as child":
@@ -129,17 +150,20 @@ adam:
     &: eve: cain           # "eve holds me as cain" — the reverse of eve's cain-edge
 ```
 
-`&: container[]` (trailing `[]`, no index) means **positional membership**: "that container also
+`&: container: -` (a trailing `-` segment) means **positional membership**: "that container also
 holds me", appended after the container's own entries:
 
 ```yamlover
 fan:
   name: Bob
-  &: favorites[]           # Bob appends himself to `favorites`
+  &: favorites: -          # Bob appends himself to `favorites`
 ```
 
-Anchor paths must be **unambiguous** (no wildcards, no trailing `[n]` position claim) — they
-create real keys, so they must resolve to exactly one place.
+Anchor paths must be **unambiguous** (no wildcards, no trailing position claim — neither a bare
+integer nor a relative `[.±k]`) — they create real keys, so they must resolve to exactly one
+place. The trailing `-` is an append, not a claim; a `-` anywhere else in an anchor path is
+reserved (a parse error today). The old `&: container[]` bracket spelling was removed and no
+longer parses.
 
 > You may encounter the older `~key: *path` back-edge syntax in legacy files. It still parses but
 > is deprecated; author new reverse edges as `&` anchors.
@@ -148,14 +172,19 @@ create real keys, so they must resolve to exactly one place.
 
 ## 6. Tags `!!` and `$defs` schemas
 
-- `!!type` — a YAML-style tag. Common no-op markers: `!!mix`, `!!var` (see §2). `!!set` marks a
-  container whose membership is by identity (duplicates collapse).
+- `!!type` — a YAML-style tag. `!!mix` is the one no-op marker (see §2). The rest are
+  **semantic** and must not be added or dropped casually:
+  - `!!set` marks a container whose membership is by identity (duplicates collapse);
+  - `!!yo` (deprecated aliases `!!var` / `!!omni`) marks a node as **plain yamlover, exempt
+    from the enclosing document's schema** — a *data island*. Inside a structured document (a
+    chapter, say) a `!!yo` node is never interpreted by that schema: it is data, drawn by the
+    generic renderer.
 - **Inline schema reference** `!!<…>` binds a node to a reusable schema definition:
   ```yamlover
   mychapter: !!<*:: yamlover: $defs: chapter>
   ```
   Reusable schemas live at the project root under **`$defs`** (e.g. `$defs: chapter`,
-  `$defs: tag`, `$defs: annotation`, `$defs: fragment`). They are referenced project-scoped
+  `$defs: onto`, `$defs: annotation`, `$defs: fragment`). They are referenced project-scoped
   (`*:: $defs: name`) or via the self-import (`*:: yamlover: $defs: name` — synonyms inside this
   project). Schemas are **metadata** (typing/format/presentation), not data storage.
 
@@ -165,15 +194,15 @@ create real keys, so they must resolve to exactly one place.
 
 A node can be materialized two ways:
 
-1. **Single-file concrete** — a whole document in one `.yamlover` (or `.json5p`) file.
+1. **Single-file concrete** — a whole document in one `.yo` (or `.json5p`) file.
 2. **Directory concrete** — a directory **is** the node; its files/subdirs are its entries, and
-   two optional overlay files inside a hidden `.yamlover/` subdir add data and schema:
-   - `.yamlover/body.yamlover` — **instance** overlay: scalar values, ordering, pointers,
+   two optional overlay files inside a hidden `.yo/` subdir add data and schema:
+   - `.yo/body.yo` — **instance** overlay: scalar values, ordering, pointers,
      extra keyed/keyless entries layered onto the directory's contents.
-   - `.yamlover/meta.yamlover` — **schema** overlay: typing, format, validation.
+   - `.yo/meta.yo` — **schema** overlay: typing, format, validation.
 
 So to add a pointer or a value "to a folder", you edit (or create) that folder's
-`.yamlover/body.yamlover`. Plain files inside the directory are its members; a `.yamlover/`
+`.yo/body.yo`. Plain files inside the directory are its members; a `.yo/`
 subdir does not appear as a member — it's the overlay.
 
 A pure pointer-array body (`- *file1` …) is the ORDER overlay: it grants positions to the
@@ -184,7 +213,7 @@ pure module, an explicit `concrete:` always wins): a directory-concrete parent k
 directory-concrete; a keyed container child becomes a nested real directory; an untagged
 keyless (ordinal) container child becomes an order-numbered subdirectory (`item01`,
 `item02`, …) referenced by a `- *: itemNN` pointer-array element; scalars and tagged containers
-(tables, typographical lists) go inline into `body.yamlover`. Title-born subchapter members are
+(tables, typographical lists) go inline into `body.yo`. Title-born subchapter members are
 numbered too (`01-Введение`). The numbers are COSMETIC listing order — the body pointer-array is
 the order's data, and an existing member is NEVER renamed: an insert between neighbors slots a
 sub-number (`item01-1`, `01-1-Новая`). Content inside a file document speaks that file's
@@ -192,12 +221,12 @@ language (a `.json5p` interior never switches to yaml).
 
 **Collapse / expand / promotion — the same node, two shapes.** The two concretes are
 freely interconvertible without changing what the data means: a child stored as
-`child.yamlover` (collapsed) and the same child stored as `child/` with a
-`.yamlover/body.yamlover` (expanded) are equivalent. Converting a single-file node **into**
+`child.yo` (collapsed) and the same child stored as `child/` with a
+`.yo/body.yo` (expanded) are equivalent. Converting a single-file node **into**
 a directory is called **directory promotion** (the UI's action; the engine keeps inbound
 pointers valid across it, like `mv`). If you do it by hand, it is a two-step move: create the
-`child/` directory, move the file's contents into `child/.yamlover/body.yamlover` (plus any
-members as files), and delete the old `child.yamlover` — then let the engine reindex. Because
+`child/` directory, move the file's contents into `child/.yo/body.yo` (plus any
+members as files), and delete the old `child.yo` — then let the engine reindex. Because
 it is a move, treat it with the same care as any rename: pointers that addressed the old file
 path must still resolve (prefer the mediated `mv`/promotion in the UI, which rewrites them —
 see §10).
@@ -208,19 +237,22 @@ see §10).
 
 The human marks up documents in the UI. These live **on the target node**, not in side files:
 
-- **`yamlover-fragments`** — a mapping of slug → selector (a text span, image/PDF rectangle, or
+- **`yo: fragments:`** — a mapping of slug → selector (a text span, image/PDF rectangle, or
   map box) identifying a region within the node.
 - **`yamlover-annotations`** — a sequence; each element applies a tag to the node (or a
   fragment). An element is either a bare **tag pointer** or an object with a `tag:` field plus
   parameters:
   ```yamlover
   yamlover-annotations:
-    - *:: tags: genre: brevity            # parameterless
-    - {description: A math block, tag: *:: tags: topic: math}   # parametrized
+    - *:: ontos: genre: brevity            # parameterless
+    - {description: 'A math block', tag: *:: ontos: topic: math}   # parametrized
   ```
 
+  (A flow scalar carrying a SPACE must be quoted — an unquoted `A math block` inside `{…}` is a
+  parse error.)
+
 Prefer letting the human create these through the UI. If you must touch them by hand, keep the
-exact key names (`yamlover-fragments`, `yamlover-annotations`) and the tag-pointer form, and do
+exact key names (`yo: fragments:`, `yamlover-annotations`) and the tag-pointer form, and do
 not renumber or reorder fragment slugs.
 
 ---
@@ -253,10 +285,10 @@ pushes the change to the human's browser over a live event stream — so your ed
 UI within a moment, and theirs appear to you on disk. Work with that, not against it:
 
 - **Make small, valid saves.** A half-written file will reindex as broken. Prefer complete edits.
-- **NEVER touch `.yamlover/index.db`** (nor its `-wal` / `-shm` companions). It is the server's
+- **NEVER touch `.yo/index.db`** (nor its `-wal` / `-shm` companions). It is the server's
   generated SQLite index — it regenerates itself from the source files. Editing or deleting it
-  does nothing useful and can confuse a running server. It is the *only* thing in `.yamlover/`
-  you must not edit; `body.yamlover` / `meta.yamlover` overlays (§7) are normal editable data.
+  does nothing useful and can confuse a running server. It is the *only* thing in `.yo/`
+  you must not edit; `body.yo` / `meta.yo` overlays (§7) are normal editable data.
 - **Renames and moves break inbound pointers.** Other files may point at a node by its path
   (`*: some: node`). If you move or rename it with a plain `mv`, those pointers dangle. The
   running server exposes a **mediated move** (`POST /api/mv`) that surgically rewrites inbound
@@ -264,10 +296,11 @@ UI within a moment, and theirs appear to you on disk. Work with that, not agains
   project for pointers to the old path (`*` followed by the path) and update them too.
 - **Don't reformat with a generic YAML/JSON tool.** It will mangle `*`, `&`, `!!<…>`, the
   colon paths, and the mixed keyed/keyless ordering. Edit the text directly and preserve style.
-- **Settings live in `.yamlover/settings.yamlover`** at the project root (e.g. where new tags and
+- **Settings live in `.yo/settings.yo`** at the project root (e.g. where new tags and
   annotations are written). Treat it as configuration; change it only when asked.
 - **When unsure of a path, query it.** The server answers `GET /api/query?...` using the path
-  grammar above, and serves the tree at `GET /api/tree` / a node at `GET /api/json?path=:a:b`.
+  grammar above, and serves the tree at `GET /api/tree` / a node's yamlover at
+  `GET /api/content/a/b` (slash-spelled path; digits are positions, `~` the null key).
   Use these to confirm a path resolves before you author a pointer to it.
 
 ---
@@ -276,15 +309,17 @@ UI within a moment, and theirs appear to you on disk. Work with that, not agains
 
 ```yamlover
 # pointers (pull) — colon paths, the scope ladder
-sibling:   *pets[1]                 # current scope, by position
-rooted:    *: humans[0]: name       # document root → position 0 → key name
-projscope: *:: tags: genre          # this project's root
-world:     *::: host.example: $defs: tag
+sibling:   *pets: 1                 # current scope, by position (bare digits = the position)
+rooted:    *: humans: 0: name       # document root → position 0 → key name
+strkey:    *: counts: '1'           # QUOTED digits = the numeric STRING key
+nullkey:   *: doc: ~                # the null key
+projscope: *:: ontos: genre          # this project's root
+world:     *::: host.example: $defs: onto
 
 # anchors (push) — "I also live there"; real keys; unambiguous only
 here:  &: chief                     # also at document-root key `chief`
 rev:   &: parent: child             # parent holds me as `child`
-mem:   &: favorites[]               # appended member of `favorites`
+mem:   &: favorites: -             # appended member of `favorites`
 
 # tags / schema
 node:  !!<*:: $defs: chapter>       # bind a reusable schema

package/dist/agent-docs/CLAUDE.md

@@ -2,6 +2,6 @@
 
 This is a **yamlover** project. The authoring rules, the pointer/anchor syntax, and the rules for
 safely co-editing the tree while the yamlover web UI is running are in **`AGENTS.md`** — read it
-before editing any `.yamlover` / `.json5p` file.
+before editing any `.yo` / `.json5p` file.
 
 @AGENTS.md

package/dist/builtin-taxonomy/$defs/.yo/meta.yo

@@ -0,0 +1,29 @@
+# $defs/.yo/meta.yo — every definition file is a yamlover/meta document: the CONCRETE names
+# the decoding (parse the text as a schema doc); the parsed type follows from it (docs/meta —
+# the concrete/type/format split; the old spelling `type: string` + `format: yamlover/meta`
+# stays readable but is not authored anymore).
+members:
+    chapter:
+        concrete: yamlover/meta
+    chunk:
+        concrete: yamlover/meta
+    tag:
+        concrete: yamlover/meta
+    annotation:
+        concrete: yamlover/meta
+    fragment:
+        concrete: yamlover/meta
+    task:
+        concrete: yamlover/meta
+    workflow:
+        concrete: yamlover/meta
+    board:
+        concrete: yamlover/meta
+    table:
+        concrete: yamlover/meta
+    bullets:
+        concrete: yamlover/meta
+    numbered:
+        concrete: yamlover/meta
+    config:
+        concrete: yamlover/meta

package/dist/builtin-taxonomy/$defs/annotation

@@ -1,7 +1,7 @@
 # $defs/annotation — ONE TAG APPLICATION on the host node (a whole document, or a fragment within
 # it). It lives as an element of the host's `yamlover-annotations` array. Two forms:
-#   • parameterless — a bare tag pointer (`- *::tags:…`): the host simply HAS this tag.
-#   • parametrized  — an object carrying `tag: *::tags:…` plus parameters (e.g. `description`).
+#   • parameterless — a bare tag pointer (`- *::ontos:…`): the host simply HAS this tag.
+#   • parametrized  — an object carrying `tag: *::ontos:…` plus parameters (e.g. `description`).
 # The applied tag drives the display color (its `color`, else a name-derived hue). The region, if
 # any, is the host fragment's selector — an annotation carries no selector of its own. This
 # replaces the old separate-file annotation (a `target` pointer + `selector` + reverse tag
@@ -9,10 +9,10 @@
 # !!<*::yamlover/$defs/annotation> is optional, for the parametrized object form.
 type: variant
 format: x-yamlover-annotation
-value: *:: yamlover: $defs: tag          # the parameterless case: the self-value IS a tag (by ref)
-properties:
-  tag: *:: yamlover: $defs: tag          # the parametrized case: the applied tag, by pointer
+value: *:: yamlover: $defs: onto          # the parameterless case: the self-value IS a tag (by ref)
+members:
+  tag: *:: yamlover: $defs: onto          # the parametrized case: the applied tag, by pointer
   description:
     type: string
     format: text/marklower
-additionalProperties: true               # any other field is a free-form parameter
+others: true                             # any other field is a free-form parameter

package/dist/builtin-taxonomy/$defs/board

@@ -1,15 +1,15 @@
 # $defs/board — marks a DIRECTORY of tasks as an agile/kanban board. Attach it to the directory's
-# `.yamlover/body.yamlover` overlay; the `workflow:` ref names which $defs/workflow supplies the
+# `.yo/body.yo` overlay; the `workflow:` ref names which $defs/workflow supplies the
 # lanes (its states, in order). The board renderer then groups the directory's task members into
 # those lanes by each task's current state annotation, and a drag between lanes rewrites that
 # annotation (re-tags the state). format `x-yamlover-board`. Attach with  !!<*yamlover:$defs:board>.
 # Spec: ../TICKETS.md §3.
 type: object
 format: x-yamlover-board
-properties:
-  workflow: *:: yamlover: $defs: tag    # ref → the workflow that SEEDS the default lanes
+members:
+  workflow: *:: yamlover: $defs: onto    # ref → the workflow that SEEDS the default lanes
   lanes:                                # optional saved lanes (the explorer board view's config):
     type: array                         #   a sequence of lanes, each a list of tag refs — one tag
-    items:                              #   = a plain lane, several = per-tag SUBLANES stacked
+    others:                             #   = a plain lane, several = per-tag SUBLANES stacked
       type: array                       #   vertically. Edited via the lane headers, persisted by
-      items: *:: yamlover: $defs: tag   #   POST /api/board.
+      others: *:: yamlover: $defs: onto  #   POST /api/board.

package/dist/builtin-taxonomy/$defs/bullets

@@ -2,11 +2,11 @@
 # keyless entries are the items. An item is marklower prose (a chunk) or — when it is an
 # UNTAGGED container — a nested bullets list: unlike table's two-level budget, the list
 # schema applies at ANY depth, until an explicit !!<…> tag switches to something else.
-# A titled list is a chapter holding a list — no keyed properties here on purpose.
+# A titled list is a chapter holding a list — no keyed member clauses here on purpose.
 # Attach with !!<*yamlover: $defs: bullets>.
-# No explicit `format:` — `type: variant` derives x-yamlover-bullets. Spec: ../MARKLOWER.md.
+# No explicit `format:` — `type: variant` derives x-yamlover-bullets. Spec: docs/documents/marklower.
 type: variant
-items:
+others:
   anyOf:
     - *:: yamlover: $defs: bullets   # an untagged container item = a nested sublist, SAME kind
     - *:: yamlover: $defs: chunk     # a list item — marklower prose

package/dist/builtin-taxonomy/$defs/chapter

@@ -5,27 +5,26 @@
 #
 # There is no `chunks` array and no `children` array — prose, media, diagrams, and
 # subchapters are siblings in ONE ordered stream. Attach it to a yamlover node with the
-# tag  !!<*yamlover/$defs/chapter>.  Spec: ../CHAPTER.md, ../META.md.
+# tag  !!<*yamlover/$defs/chapter>.  Spec: docs/documents/chapter, docs/meta.
 #
 # `type: variant` is the omni node: a scalar self-value (the title, given as `value:`) AND
-# keyed fields (description) AND positional elements (the body) at once. The body element type
-# is a union — a chapter OR a chunk; the two are told apart structurally (a chapter is a
-# container, a chunk is a leaf). A BARE SCALAR body element is therefore both "a chunk" and
-# "a title-only subchapter" — the same thing, by design (CHAPTER.md).
-# NOTE: `value` (scalar) + `properties` (keyed) + `items` (ordinal) is the JSON-Schema encoding
-# of an omni node's facets; META.md §Vocabulary proposes a native `elements`/`additionalElements`.
+# keyed fields (description) AND positional elements (the body) at once. ONE omni `members:`
+# clause describes the members (here: the keyed `description`); the sibling `others:` covers
+# every member no clause matched — the BODY, a union routed structurally (a container element
+# is a chapter, a leaf is a chunk). A BARE SCALAR body element is therefore both "a chunk" and
+# "a title-only subchapter" — the same thing, by design (docs/documents/chapter).
 type: variant
 value:                             # the self-value — the chapter's TITLE
   type: string
   format: text/marklower
-properties:
+members:
   description:                     # optional subtitle / heading annotation — stays keyed
     type: string
     format: text/marklower
-items:                             # the body — a positional sequence, read top to bottom
+others:                            # the body — every unmatched member, read top to bottom
   anyOf:
     - *:: yamlover: $defs: chapter   # a nested subchapter (a container) — the recursion
-    - *:: yamlover: $defs: table     # a table — enters only by its EXPLICIT tag (MARKLOWER.md)
+    - *:: yamlover: $defs: table     # a table — enters only by its EXPLICIT tag (docs/documents/marklower)
     - *:: yamlover: $defs: bullets   # a bullet list — enters only by its explicit tag
     - *:: yamlover: $defs: numbered  # a numbered list — enters only by its explicit tag
     - *:: yamlover: $defs: chunk     # a content block — a leaf

package/dist/builtin-taxonomy/$defs/chunk

@@ -1,8 +1,9 @@
 # $defs/chunk — one renderable content block, a leaf of a chapter's positional body.
 #
-# A chunk is a typed value; its (type, format) selects the renderer. The default is
-# markdown prose; a chunk overrides type/format/concrete to be a diagram, image, LaTeX,
-# CSV, a file pointer, etc. `binary` covers image/pdf/… chunks (a `*` pointer to a file).
-# Spec: ../CHAPTER.md.
+# A chunk is a typed value; its (type, format) selects the renderer — the format CONSTRAINS
+# the value, and the concrete (declared in meta, docs/meta) says how its bytes decode. The
+# default is markdown prose; a chunk overrides them to be a diagram, image, LaTeX, CSV, a
+# file pointer, etc. `binary` covers image/pdf/… chunks (a `*` pointer to a file).
+# Spec: docs/documents/chapter.
 type: [string, binary]
 format: text/marklower

package/dist/builtin-taxonomy/$defs/config

@@ -1,4 +1,4 @@
-# $defs/config — the project configuration schema for `<root>/.yamlover/settings.yamlover`
+# $defs/config — the project configuration schema for `<root>/.yo/settings.yo`
 # (settings.ts, IMPORTS.md). Settings are DEFAULTS, never constraints; reading is location-
 # independent. The format `x-yamlover-config` lets the server render the (hidden but accessible)
 # config file with the SETTINGS EDITOR — opened by the gear button, in the main pane. Locations are
@@ -6,19 +6,19 @@
 #  !!<*yamlover:$defs:config>.
 type: object
 format: x-yamlover-config
-properties:
+members:
   uri:                                  # this project's identity (IMPORTS.md §1) — an authority,
     type: string                        #   authored as `::: host`; identity, not transport
   exports:                              # the paths exported to importers (IMPORTS.md §2):
     type: array                         #   a list of pointer/query texts
-    items:
+    others:
       type: string
-  annotations: *:: yamlover: $defs: tag   # where new annotations are created (`*:: annotations`)
-  tags: *:: yamlover: $defs: tag          # where new tags are created (`*:: tags`)
+  annotations: *:: yamlover: $defs: onto   # where new annotations are created (`*:: annotations`)
+  ontos: *:: yamlover: $defs: onto          # where new tags are created (`*:: tags`)
   sidecars:                             # where derived sidecar blobs go: per-directory | project
     type: string
   width:                                # reading width (ch) for rendered prose (markdown/asciidoc/
     type: integer                       #   chapter); the browser settings layer overrides it per device
   theme:                                # ui palette: dark | light; the browser settings layer
     type: string                        #   overrides it per device
-  annotation-tag: *:: yamlover: $defs: tag  # the last-used annotation tag (the picker default)
+  annotation-tag: *:: yamlover: $defs: onto  # the last-used annotation tag (the picker default)

package/dist/builtin-taxonomy/$defs/fragment

@@ -7,7 +7,7 @@
 # its own `yamlover-annotations`. Attach with the tag  !!<*::yamlover/$defs/fragment>.
 type: object
 format: x-yamlover-fragment
-properties:
+members:
   type:
     type: string
     description: The locator kind — text | rect | pdf | djvu | map
@@ -41,4 +41,4 @@ properties:
     type: string
   yamlover-annotations:
     type: array
-    items: *:: yamlover: $defs: annotation
+    others: *:: yamlover: $defs: annotation

package/dist/builtin-taxonomy/$defs/numbered

@@ -2,11 +2,11 @@
 # keyless entries are the items. An item is marklower prose (a chunk) or — when it is an
 # UNTAGGED container — a nested numbered list: unlike table's two-level budget, the list
 # schema applies at ANY depth, until an explicit !!<…> tag switches to something else.
-# A titled list is a chapter holding a list — no keyed properties here on purpose.
+# A titled list is a chapter holding a list — no keyed member clauses here on purpose.
 # Attach with !!<*yamlover: $defs: numbered>.
-# No explicit `format:` — `type: variant` derives x-yamlover-numbered. Spec: ../MARKLOWER.md.
+# No explicit `format:` — `type: variant` derives x-yamlover-numbered. Spec: docs/documents/marklower.
 type: variant
-items:
+others:
   anyOf:
     - *:: yamlover: $defs: numbered  # an untagged container item = a nested sublist, SAME kind
     - *:: yamlover: $defs: chunk     # a list item — marklower prose

package/dist/builtin-taxonomy/$defs/{tag → onto}

@@ -1,17 +1,17 @@
-# $defs/tag — a node in a tag taxonomy. A tag's description is its BODY (the node's own scalar
+# $defs/onto — a node in an ontology. A tag's description is its BODY (the node's own scalar
 # value — author `name: !!omni The description` when the tag also has fields, or a plain
 # `name: The description` for a leaf); an optional explicit `color` ("#rrggbb" — a "pure color
 # tag"; absent ⇒ the UI derives a stable hue from the name); every OTHER key is a sub-tag, so
-# the taxonomy recurses to any depth (`additionalProperties` → tag). The format `x-yamlover-tag`
+# the taxonomy recurses to any depth (`others:` → onto). The format `x-yamlover-onto`
 # makes the server render each one as a tag (a badge wired to its super/sub-tags). Attach to the
-# taxonomy root with the tag  !!<*yamlover/$defs/tag>  — it propagates down.
+# taxonomy root with the tag  !!<*yamlover/$defs/onto>  — it propagates down.
 type: variant
-format: x-yamlover-tag
+format: x-yamlover-onto
 value:
   type: string
   format: text/marklower
-properties:
+members:
   color:
     type: string
     description: An explicit display color ("#rrggbb"); absent ⇒ derived from the tag's name
-additionalProperties: *:: yamlover: $defs: tag
+others: *:: yamlover: $defs: onto

package/dist/builtin-taxonomy/$defs/table

@@ -1,33 +1,34 @@
 # $defs/table — a grid node: an OMNI node whose keyless entries are the ROWS (top to
 # bottom), each row an array of CELLS (left to right). A row keyed `header` is the header
 # row; optional keyed `title` is the caption. The column count is inferred from the first
-# row. The table schema consumes exactly TWO nesting levels — rows, then cells; a cell
-# that is an untagged container switches BACK to a CHAPTER (prose, subchapters, tables —
-# the same rules as a top chapter). A NESTED table — like a list — enters a cell only by
-# its explicit !!<…> tag. A header cell may be an omni scalar carrying a keyed `width`
-# sidecar — a proportional column weight (AsciiDoc `cols` style), rendered weight/sum %;
-# `width` is deliberately schema-untyped (an omni cell must stay a LEAF for shape routing).
-# A cell that is a `*` pointer to its adjacent previous cell (`*[.-1]` left, `*..[.-1][.]`
-# up — relative indexes, URIs.md) declares a MERGED cell: colspan/rowspan. Attach with
+# row. The table schema consumes exactly TWO nesting levels — rows, then cells (the outer
+# `others:` sweep is a row, ITS `others:` a cell); a cell that is an untagged container
+# switches BACK to a CHAPTER (prose, subchapters, tables — the same rules as a top chapter).
+# A NESTED table — like a list — enters a cell only by its explicit !!<…> tag. A header cell
+# may be an omni scalar carrying a keyed `width` sidecar — a proportional column weight
+# (AsciiDoc `cols` style), rendered weight/sum %; `width` is deliberately schema-untyped (an
+# omni cell must stay a LEAF for shape routing). A cell that is a `*` pointer to its adjacent
+# previous cell (`*[.-1]` left, `*..[.-1][.]` up — relative indexes,
+# docs/language/pointers/relative-indexes) declares a MERGED cell: colspan/rowspan. Attach with
 # !!<*yamlover: $defs: table>.
-# No explicit `format:` — `type: variant` derives x-yamlover-table. Spec: ../MARKLOWER.md.
+# No explicit `format:` — `type: variant` derives x-yamlover-table. Spec: docs/documents/marklower.
 type: variant
-properties:
+members:
   title:                           # optional caption
     type: string
     format: text/marklower
   header:                          # the header row — same shape as a body row (the schema
     type: array                    #   loader follows only $defs pointers, so the row
-    items:                         #   schema is repeated literally rather than *: items)
+    others:                        #   schema is repeated literally rather than *: others)
       anyOf:
         - *:: yamlover: $defs: chunk
         - *:: yamlover: $defs: chapter
         - *:: yamlover: $defs: table
         - *:: yamlover: $defs: bullets
         - *:: yamlover: $defs: numbered
-items:                             # a row
+others:                            # a row
   type: array
-  items:                           # a cell
+  others:                          # a cell
     anyOf:
       - *:: yamlover: $defs: chunk    # marklower prose (the default leaf)
       - *:: yamlover: $defs: chapter  # an UNTAGGED container cell IS a chapter (the first