yamlover 0.3.55 → 0.3.58

package/dist/agent-docs/AGENTS.yo

@@ -0,0 +1,621 @@
+!!<*yamlover: $defs: chapter>
+Working with this yamlover project - a guide for AI agents
+description: how to read, write, and co-edit the .yo files of this directory without corrupting the data or the human's live view
+- >
+  This project stores structured knowledge as **yamlover** files. You (an AI coding agent) and a
+  human are editing the **same directory** at the same time: the human browses the tree in the
+  yamlover web UI (`npx yamlover .`) while you read and edit the files on disk. This document is
+  itself a yamlover chapter - the format it describes - and tells you how to manipulate these files
+  **correctly**.
+- >
+  It is self-contained, but not the spec. The authoritative reference is the online documentation
+  book at <"yamlover.inthemoon.net/docs"| -: "https://yamlover.inthemoon.net/docs"> - the
+  <"language"| -: "https://yamlover.inthemoon.net/docs/language">, the
+  <"documents"| -: "https://yamlover.inthemoon.net/docs/documents"> (chapters, marklower, tables,
+  lists), the <"annotations"| -: "https://yamlover.inthemoon.net/docs/annotations">, the
+  <"meta language"| -: "https://yamlover.inthemoon.net/docs/meta">, the
+  <"foreign formats"| -: "https://yamlover.inthemoon.net/docs/formats">, and the
+  <"server"| -: "https://yamlover.inthemoon.net/docs/server">. The worked
+  <"examples"| -: "https://yamlover.inthemoon.net/examples/"> are browsable live, and the source is
+  on <"GitHub"| -: "https://github.com/dims12/yamlover">. This file is regenerated by the UI's
+  "Install LLM agent guide" action - keep project-specific rules in `AGENTS.md` (outside its fenced
+  block), not here. The bundled guide was checked against the implementation on 2026-09-07.
+- What yamlover is
+  - >
+    yamlover is a **distinct, YAML-like language** - close to YAML and mostly readable as it, but
+    **not a superset**: `*` and `&` carry different meanings (a `*` is a path pointer, **not** a
+    YAML alias), so a YAML document with aliases does not round-trip, and these files need the
+    yamlover parser. **Never "fix" a `.yo` file with a generic YAML formatter** - it will destroy
+    the pointers, the bookmarks, the inline tags, and the mixed ordering.
+  - >
+    On top of a YAML-style surface it adds a small **pointer layer**, so data forms a graph rather
+    than a tree:
+  - !!<*yamlover: $defs: bullets>
+    - '`*path` - a **reference** (the pull): this value *is* the node over there - a ref edge, never a copy.'
+    - '`&path` - a **bookmark** (the push): this node *also* lives over there - it grafts a real key.'
+    - '`!!<...>` - an inline **schema tag**; `!!yo` marks a data island, `!!set` a by-identity container.'
+  - >
+    File extensions: `.yo` is the yamlover surface (the legacy `.yamlover` reads forever).
+    `.json5p` is its brace twin - the same pointer layer in JSON5 syntax, pointers written as
+    quoted strings (`*": pets: 1"`). Plain `.yaml`/`.json`/`.json5`/`.md`/`.adoc`/images/PDFs
+    in the tree are read as what they are; yamlover overlays them, it does not rewrite them.
+- The one omni node
+  - >
+    YAML forces a node to be a sequence **or** a mapping. yamlover has **one ordered container**:
+    every entry has an integer **position** (0, 1, ...) and **may also** carry a string key.
+    Keyless and keyed entries coexist, in author order - and a node may carry a **scalar
+    self-value and fields at once**:
+  - !!<format: text/x-yamlover> |
+    playlist:
+      - Intro                  # position 0            keyless
+      - Verse                  # position 1            keyless
+      title: Greatest Hits     # position 2, key=title keyed - AND still positioned
+      - Chorus                 # position 3
+      encore: *: pets: 0       # position 4, key=encore a keyed pointer, still in order
+    rating: 5                  # the node's own SELF-VALUE ...
+      - solid                  #   ... plus a positional field
+      scale: 10                #   ... plus a keyed field
+  - >
+    **Order is data**: the position of every entry, keyed ones included, is part of the value. A
+    bare integer key **pins** a position (`10: ten` is a keyless entry at position 10); the numeric
+    *string* key stays quoted (`'10': v`). `!!mix` is a no-op readability marker for these shapes
+    (mixing is the default) - never add or remove it to change meaning. `!!yo` (deprecated
+    aliases `!!var`, `!!omni`) is **semantic**: it marks a **data island**, plain yamlover exempt
+    from the enclosing document's schema (inside a chapter it renders as data, never as prose).
+- Omni flow syntax
+  - >
+    Flow containers may carry a self-value using postfix `value|`, anywhere among their
+    entries: `{a: 12, 12|}` and `[12, 12|]` each have one entry plus scalar self-value 12.
+    `{Earth| diameter: 12742, -: satellite}` mixes a self-value, keyed and keyless entries.
+    The self-value consumes no position; duplicate self-values are errors. Quote literal
+    pipes in flow strings and keys. Use `-: value` with separation for explicit keyless
+    entries. Unquoted `~`, `null`, `Null` and `NULL` in data key position mean the null
+    key; quote them to author string keys. `:value` stays a string, and `{:value}` is an
+    omitted-value string-key entry. These extensions do not change JSON/json5p or YAML.
+- Paths use colons
+  - >
+    A path chains keys with **colons**: `a: b: c` is key `a`, then `b`, then `c`. Canonical style
+    writes `: ` (colon, space) between steps; the compact `a:b:c` also parses and is what you
+    write *inside prose*. `/` is an ordinary character (`text/html`, `01/02/2026` ride bare); the
+    old slash-separated paths are dead - `*/pets` dangles on the literal key "/pets".
+  - >
+    **The scope ladder** - more colons, wider scope. There is no implicit search up the ancestors:
+    a bare name is the current mapping only, reach outward explicitly.
+  - !!<*yamlover: $defs: table>
+    header:
+      - Form
+      - Base
+        width: 2
+      - Example
+    - ['`*name`, `*..: x`', 'the **current mapping** / its parent', '`*cat`, `*..: ..: pets: 1`']
+    - ['`*: path`', 'this **document** root (the nearest `.yo` file or overlay)', '`*: pets: 1`']
+    - ['`*:: path`', 'this **project** root (the directory yamlover was served)', '`*:: ontos: genre`']
+    - ['`*::: authority: path`', 'the **world** - another project by name, never fetched', '`*::: yamlover.inthemoon.net: $defs: onto`']
+  - >
+    **What a segment means** - every portion is typed by its own form:
+  - !!<*yamlover: $defs: table>
+    header:
+      - Segment
+      - Meaning
+        width: 2
+    - ['`abc`, `"two words"`', 'a **string key** (bare, or quoted when the bare form would read as something else)']
+    - ['`0`, `17`', 'a **position** - bare digits; `''17''` quoted is the numeric string key']
+    - ['`~`', 'the **null key** (quote `"null"` in data for that string key)']
+    - ['`..`', 'the **parent**; the literal keys `..` / `...` are escaped `\.\.` / `\.\.\.`']
+    - ['`-`', 'the **keyless segment** - a trailing `-` on a bookmark appends; in a query, any position']
+    - ['`.`, `.len-(1)`, `3+(3)`, `.-(1)`', '**position arithmetic** - my own position, the last entry, position 6, the previous sibling']
+  - >
+    A key that would read as something else **must be quoted**: pure digits, an empty key, `~`,
+    `-`, a position-shaped token (`-1`, `0-3`, `.len`), or a key containing a space. In a document
+    a plain `1:` is a **pin**, `'1':` the string key. The retired bracket index (`*pets[1]`,
+    `[.-1]`) reads forever but is **written never** - author the bare integer or the arithmetic;
+    the old `[]` append and `[?]` brackets were removed, both are the `-` segment now.
+- References and bookmarks
+  - >
+    `*path` **pulls**: the value lives there. Resolution is lazy, cycle-safe, and yields a **ref
+    edge** - editing the target changes everything that points at it. Walking *through* a pointer
+    pulls implicitly: a path never stops halfway at "a pointer".
+  - !!<format: text/x-yamlover> |
+    humans:
+      - name: Alice
+        manager: *: pets: 1      # Alice.manager IS the node at root -> pets -> position 1
+    feline: *pets: 1             # a sibling key, by position
+    topDog: *: pets: 0
+  - >
+    `&path` **pushes**: this node *also* lives there. A bookmark grafts a **real key** - there is
+    no anchor namespace, so any plain pointer reaches it. Bookmarks ride the node's own row
+    ahead of the value, each chain closed by a colon, or stand on their own lines under the key
+    when the value is a container or a block scalar. Bookmarks are **not entries**: a scalar with
+    bookmarks is still a scalar.
+  - !!<format: text/x-yamlover> |
+    boss: &: chief: Rex          # ALSO the document-root key `chief`; the value is Rex
+    team:
+      lead: *: chief             # the same node - a ref edge
+    adam:
+      cain:
+        &: eve: cain             # "eve holds me as cain" - a reverse relation, as a bookmark
+    fan:
+      name: Bob
+      &: favorites: -            # a trailing `-`: Bob APPENDS himself to `favorites`
+  - >
+    A bookmark path must be **unambiguous**: no wildcards, no position claim (`&: list: 3` and
+    `&: list: .len-(1)` are rejected - use the trailing `-`), no null key. A forward `k: *me` and a
+    reverse `&: P: k` are **two authorings of one edge** - both at once is legal, merely
+    redundant; `normalize` folds them. Bookmark-created members project **after** the
+    container's own entries. The legacy `~key: *path` back-edge syntax reads but is deprecated.
+- Partial documents and flat rows
+  - >
+    A partially loaded graph is valid yamlover. **Pins** state which positions are held
+    (`10: ten`, `11: eleven` - positions 0-9 are **gaps**, reported as *not loaded*, never as a
+    typo); pins must strictly increase. A reference to itself **postpones** a branch - the key
+    is known, the value is not loaded: `a: *a`, normalized to the dot `a: *.`; as a keyless
+    entry `- *.` holds one postponed position, and a trailing `- *.` says **more follows** - the
+    node's tail is open and its length unknown. You will meet this spelling in the engine's
+    own answers; author it only when you mean it.
+  - !!<format: text/x-yamlover> |
+    a:
+      10: value10              # positions 0-9 are gaps
+      - value11                # position 11
+      - *.                     # position 12 postponed, the tail open
+  - >
+    A **flat row** folds a chain of single-pair lines onto one line: `key1: key2: key3: value`
+    reads exactly as the nested spelling, and the nested form is the normalized one. A `-`
+    segment at the end of a flat path **appends** (`list: -: 1`), in the middle it addresses the
+    **last** keyless element. Positions never appear in a flat spine. The editor also preserves
+    supported flat-row authoring; use the native editor, not a YAML formatter.
+- Schemas - tags and $defs
+  - >
+    `!!<...>` binds a node to a schema by a pointer path (the leading `*` is implied):
+    `!!<*yamlover: $defs: chapter>`. The project-hosted schemas sit under `$defs` at the project
+    root; the built-in taxonomy ships with yamlover and is grafted into **every** served root
+    under the self-import key `yamlover`, so `*:: yamlover: $defs: chapter` and
+    `*:: yamlover: ontos: colors: yellow` resolve anywhere. Inside a project the self-import is
+    absorbed: `*:: $defs: onto` is the same path. Always the **all-colon** spelling after `::`.
+  - !!<*yamlover: $defs: table>
+    header:
+      - Schema
+      - What it marks
+        width: 3
+    - ['`$defs: chapter`', 'a document page - self-value title, keyed `description`, a positional body of chunks and subchapters']
+    - ['`$defs: chunk`', 'one renderable block (string or binary); default format `text/marklower`']
+    - ['`$defs: table`, `$defs: bullets`, `$defs: numbered`', 'the structures marklower delegates - enter a body only by their explicit tag']
+    - ['`$defs: task`', 'a chapter plus planning fields (`priority`, `due`, `assignee`, `estimate`, optional `workflow`); its keyless task members are SUBTASKS - a task with subtasks is a board']
+    - ['`$defs: workflow`', 'a state machine as a tag whose sub-tags are the states; `initial:` and per-state `next:` are ref edges']
+    - ['`$defs: onto`', 'an entity of an ontology (a tag): optional `color`, sub-ontos to any depth']
+    - ['`$defs: fragment`', 'a selected region of a node, under the node''s `.yo: fragments:`']
+    - ['`$defs: config`', 'the project settings file `.yo/settings.yo`']
+  - >
+    A schema is **metadata** (typing, format, presentation), never data storage, and it
+    **propagates**: a chapter tagged at its root makes every nested container a chapter and every
+    prose leaf marklower - no per-node tags. A per-chunk override is an inline facet tag:
+    `!!<format: text/x-latex>`, `!!<format: text/x-yamlover>`, `!!<format: text/plain>`.
+- Concretes - how a node is stored on disk
+  - !!<*yamlover: $defs: bullets>
+    - '**A single file** - one `.yo` (or `.json5p`) document is one node with everything inside it.'
+    - '**A directory** - the directory *is* the node: its files and subdirectories are its members (keyed by file name - member keys keep their extension, `merge-op.yo`), and an **instance overlay** supplies its self-value, tag, ordering, pointers and extra entries: `index.yo` for `dir/index.yo`, or `.yo/body.yo` for `dir/.yo`. An optional `.yo/meta.yo` supplies the schema overlay. Use the existing flavor; never create both instance overlays.'
+  - >
+    To give "a folder" a title, a tag, a pointer, or an order, edit (or create) its instance overlay
+    (`index.yo` or `.yo/body.yo`). A body that is a pointer array (`- *: intro`, `- *: chapter-two`)
+    is the **order overlay**: it grants positions to the members it names; a member it never names
+    is keyed-only and sorts after the ordered block. The two concretes are **interconvertible**:
+    `child.yo` (collapsed) and `child/` with an instance overlay (expanded) are the same node.
+    File/directory conversion is a structural operation requiring pointer rewrites, not a plain
+    filesystem rename. Ordinary edits do not automatically convert existing file tasks or directory
+    tasks.
+  - >
+    When creating a member, choose its concrete explicitly when storage matters. The edit API
+    supports inline values, files and directory concretes, with `name` for a new file or
+    directory. A materialized body member is referenced from the instance overlay; tables,
+    lists and prose can stay inline. A task born from the board's + is `task-N/index.yo`;
+    agents should supply a descriptive slug. Existing members are never automatically renamed
+    or converted because their content changes. The body order, not the filename, determines
+    the document's order.
+  - >
+    Inside `.yo/` you also meet `settings.yo` (project configuration - where new ontos and fragments
+    are created; edit only when asked), `.trash/` (the archive of removed members - storage-backed
+    removal archives there), and **`index.db`** with its `-wal`/`-shm` companions - the server's
+    generated SQLite index. **Never edit, copy, or delete `index.db`**; it regenerates from the
+    sources. Any key or file whose name starts with `.` is hidden from the TOC but browsable by
+    direct path. Hidden entries still occupy their original absolute indexes; do not compact indexes
+    when hiding them.
+- Marklower - the prose format
+  - >
+    **Marklower** is the format of a chapter's prose chunks: a markup deliberately a notch *below*
+    Markdown. The current renderer is **inline-only**: it styles prose and displays complete
+    yamlover insertions, links and scalar references. It currently has no block syntax: no headings,
+    no `- ` lists, no `|---|` tables, no fenced code, no `> ` quotes, no `![]()` images. Structure
+    is the chapter body's job: a heading is a subchapter, a table is a `$defs: table` node, a figure
+    is a pointer body element. A `##` or a pipe grid typed into a chunk renders as **literal text**.
+  - !!<*yamlover: $defs: table>
+    header:
+      - Syntax
+      - Meaning
+        width: 2
+    - ['`**bold**`, `__bold__`', 'strong']
+    - ['`*italic*`, `_italic_`', 'emphasis (an intra-word `_` is literal - `snake_case` stays plain)']
+    - ['`~~strike~~`', 'struck through']
+    - ['`` `code` ``', 'code span - **atomic**']
+    - ['`$$...$$`', 'math, typeset with KaTeX - **atomic**, may span lines']
+    - ['`<Earth| diameter: 12742>`', 'complete yamlover flow insertion; literal scalar plus retained fields']
+    - ['`<Earth| -: *:: planets: earth>`', 'scalar label and one keyless link target']
+    - ['`<*: earth>`', 'insert only the target scalar, without recursive markup']
+    - ['`[value](fields)`', 'the **fragment token** - a link when the parens hold one pointer or URL']
+  - >
+    **Atomic** means the contents are never re-read as markup: a `*` inside a code span or `$$`
+    is a literal asterisk - which is why every pointer spelling in this guide sits in backticks.
+    A **single newline is a soft break** (hard-wrapped source rejoins into one paragraph); a
+    blank line inside a block scalar stays a paragraph gap. Nothing else is special - any
+    other character passes through verbatim.
+  - >
+    **Links** use complete angle insertions: `<the spec| -: *::language:pointers>` is project-rooted
+    and `<site| -: "https://example.org">` external. Use a block scalar when inserting spaced
+    key/value syntax into prose. `<*: earth>` substitutes only the target scalar. Angle scalars
+    display literally; extra fields survive editor round trips. A scalar explicitly tagged
+    `!!<format: text/marklower>` can style a label. Escape literal angles as `\<` and `\>` and a
+    literal backslash as `\\`; do not escape code/math contents. Missing scalar targets and
+    ambiguous multiple link targets are visibly marked. Existing bracket links remain readable and
+    source preserved. Structural continuations such as `<| -:>` and `<}>` can now be decomposed into
+    chapter nodes through the browser source editor or the shared gather/decompose CLI. Ordinary .yo
+    prose scalars, including tagless | blocks, now project those structures as queryable nodes. No
+    separate extension or format tag is needed. Explicit plain/code formats and !!yo data islands
+    remain literal. The optional .marklower exchange reader also remains supported. Save gathered
+    source with an external editor; the browser keeps them read-only until source write routing is
+    ready. The chapter editor is WYSIWYG and must never execute typed or pasted structural source.
+    Gathering refuses bookmarks/comments, position gaps, binary and separately stored members; use
+    native yamlover for those. Full grammar: docs/documents/marklower/gathered.
+  - >
+    **Fragment tokens** spell a text fragment inline:
+    `<&"::yamlover:ontos:topic:math:-" "LaTeX">` files the words "LaTeX" under an onto - the
+    angle content is a yamlover scalar with membership bookmarks. Explicit fragment members
+    preserve arbitrary fields on existing authored insertions. Bracket tokens are recognized only
+    by the explicit migrate-links command; normal readers treat them as prose.
+  - >
+    **Embedding** is structural: a body element that is a pointer to an image or media member
+    (`- *: diagram.png`, `- *: talk.mp4`), or a chunk whose **entire text is one media URL**
+    (YouTube, Vimeo, a direct `.mp4`/`.mp3`/`.png` - an allowlist; anything else stays prose).
+    A URL inside a sentence is just a link - to embed, give it its own chunk.
+- Chapters - the document model
+  - >
+    A chapter is a **fully omni** node: its scalar **self-value is the title** (there is no
+    `title:` key), `description` is an optional keyed field, and every keyless entry is a body
+    element read top to bottom - a **chunk** (a leaf: prose, a format-tagged block, a file
+    pointer) or a **subchapter** (a container: a titled one is a scalar with body entries; an
+    untitled one a bare container). Tell them apart by **shape**, not tags. A bare string body
+    element is both "a chunk" and "a title-only subchapter" - the same thing, by design.
+  - !!<format: text/x-yamlover> |
+    !!<*yamlover: $defs: chapter>
+    Getting Started                          # the SELF-VALUE - the title
+    description: the shortest tour           # optional, keyed
+    - yamlover is a YAML layer over the filesystem.     # a chunk - marklower by default
+    - >
+      A longer paragraph - with **bold**, `code`, a [link](*:1) to the first chunk - folds
+      its hard-wrapped lines into one run.
+    - !!<format: text/x-latex> |             # a chunk overriding its format
+      e^{i\pi} + 1 = 0
+    - *: diagram.png                         # a pointer chunk - the image inlines
+    - !!<*yamlover: $defs: bullets>          # a typographical list - by explicit tag
+      - first point
+      - - a nested sub-point                 # an untagged container = a sublist of the same kind
+    - A subchapter                           # a TITLED subchapter: self-value + its own body
+      - its first chunk
+      - - an untitled sub-subchapter
+        - with two chunks
+    - *: appendix                            # a subchapter stored as its own directory/file
+    - !!yo                                   # a data island - rendered as data, not prose
+      sensor: 42
+  - >
+    **Writing prose safely.** Author chunks as block scalars (`- >` folded, `- |` literal): a
+    chunk's text then never collides with the parser - a sentence beginning with `*`, `&`, `!`, `[`,
+    `-` or containing `: ` is harmless inside a block. A one-line chunk may ride bare when it starts
+    with a plain word. Apply only marklower literal escapes inside the block; marklower reads the
+    scalar afterwards.
+  - >
+    **Subchapters on disk.** An inline subchapter is a nested container in the same file. A
+    **materialized** one is its own document - `name.yo` beside the parent, or a subdirectory with
+    its own `index.yo` or `.yo/body.yo` - referenced from the parent's body by a pointer element
+    `- *: name` (member keys keep the extension: `- *: name.yo` for a file). The TOC lists
+    subchapters in **body order**; a directory never named by the body sorts after the named ones. A
+    **task** member (`- *: engine`, a `$defs: task` file or directory - a board is a task with
+    subtasks) lays out as one card linking to the task; its own page holds the lanes.
+  - >
+    **Addressing body elements.** A chapter at path `P` addresses its elements by **absolute
+    entry index** on the node: `:P:0` is the first entry. Keyed entries consume indexes too - a
+    chapter with a `description:` has its first body element at `:P:1` - while the **title
+    consumes no index** (it is the self-value). This is the same index `/api/edit` uses.
+  - >
+    **Unlisted files and Other.** With an authored directory body, files not listed in that body
+    appear as thumbnail cards in Other rather than trailing chunks, in both render and edit mode.
+    The parent chapter collects unlisted files from its own nested subchapters in source order into
+    one pane. It does not collect another task's board or unrelated linked chapters. Other is docked
+    outside the document scroll area, collapsible and resizable; cards wrap. Empty chapter trays
+    start collapsed. A collapsed tray leaves only its divider and expand knob. In both chapter and Tag
+    board Other panes, the ± tag menu filters by the conjunction of selected tags. This selection is
+    browser-only, scoped by served base and node and shared between renderers; it never retags the
+    files. Active badges use the same navigation and appearance as other tag bars.
+  - >
+    **Drop destinations.** External files dropped on a TOC section or Other become members of
+    that section: unlisted on disk-backed directories, keyed references for inline containers.
+    A chapter-body drop places a reference chunk at the indicated position. Internal drags
+    reuse existing items rather than uploading copies; returning an item to Other unlists its
+    placement. Missing reference chunks remain visible and atomically deletable in the editor.
+  - >
+    **References after edits.** References retain path semantics, including authored citation
+    bookmarks. Use mediated structural edits to preserve references through moves and rekeys.
+    Positional references follow positions after unmanaged edits, and reusing a deleted path
+    or bookmark key makes old references resolve to its new occupant. Trash redirection,
+    deletion warnings and permanent memory stubs are not yet a general reference guarantee.
+- Tables and lists
+  - >
+    A table is a body element tagged `!!<*yamlover: $defs: table>`: its keyless entries are the
+    **rows** (top to bottom), each an array of **cells** (left to right, marklower); the row
+    keyed `header` is the header row, `title` the caption. The column count comes from the first
+    row. A header cell may be an omni scalar carrying a `width` weight. A **merged** cell is a
+    pointer to its adjacent neighbor using position arithmetic: `*.-(1)` "I am the cell to my
+    left" (colspan), `*..: .-(1): .` "I am the cell above" (rowspan); the merged region must be
+    a filled rectangle, and every row keeps its full cell count.
+  - !!<format: text/x-yamlover> |
+    - !!<*yamlover: $defs: table>
+      title: Who does what
+      header:
+        - Name
+          width: 2                           # a proportional column weight
+        - Class
+        - *.-(1)                             # "Class" spans two columns
+      - [Whiskers, mammal, '**manager**']    # a flow row; a cell starting with * must be quoted
+      - [Rex, *..: .-(1): ., security]       # "mammal" spans down
+      - - Bubbles                            # a block row
+        - fish
+        -                                    # an UNTAGGED container cell is a CHAPTER again
+          - night shift **only**
+  - >
+    The table schema spends exactly **two** nesting levels (rows, cells); an untagged container
+    cell switches back to a chapter, and a nested table or list enters a cell only by its own
+    tag. Lists (`$defs: bullets`, `$defs: numbered`) are plain yamlover lists of marklower items;
+    an untagged nested container inside one is a sublist of the **same kind**, at any depth.
+    Tag a list when the bullets are *content*; a chapter body's own `- ` elements are structure,
+    not typography.
+- Annotations - ontos and fragments
+  - >
+    An **ontology** is an ordinary subtree of things that exist to be pointed at - colors,
+    topics, workflow states - each node an **onto** (`$defs: onto`, optional `color`). The
+    project's own live under `ontos/` at the project root (the `.yo/settings.yo` location);
+    the built-in palette and workflows ship with yamlover: `::yamlover:ontos:colors:yellow`
+    (also green, sky, mauve, pink, peach) and `::yamlover:ontos:workflow:dev`.
+  - >
+    Filing a node under an onto (tagging) is **one bookmark line on the target** - a
+    membership edge, no annotation object:
+  - !!<format: text/x-yamlover> |
+    !!<*yamlover: $defs: chapter>
+    A Pinch of Math
+    &:: ontos: genre: brevity: shortest-paper: -        # a project onto
+    &:: yamlover: ontos: colors: yellow: -              # a built-in color
+  - >
+    Membership is additive (two ontos, two lines); the onto sees its members as keyless entries
+    after its own. To **untag**, delete the line. The applied onto's color drives display. A
+    **fragment** is a selected region of a node - a text span, an image/PDF rectangle, a map
+    box - stored as a member of the node's **`.yo: fragments:`** key (the legacy `yo:` spelling
+    is read forever - reuse it where a file already has it, never add a second overlay key).
+    Each fragment is an omni: its self-value is the principal content (the selected text), the
+    selector fields sit beside it, and its own memberships ride it. In marklower prose the
+    bracket writer can spell plain selections inline; angle selections use explicit fragment
+    members to retain all insertion fields.
+  - !!<format: text/x-yamlover> |
+    - |
+        Mathematics likes to hide, but a standalone LaTeX block gives it away.
+      .yo: fragments:
+        mq1abc-x2:                                     # a slug key (the UI generates them)
+          LaTeX                                        # the fragment's self-value - the text
+          type: text
+          prefix: ', a standalone '
+          suffix: ' block'
+          &:: yamlover: ontos: topic: math: -          # the fragment's membership
+  - >
+    For a binary file (`paper.pdf`) the keys go in the enclosing directory's instance overlay
+    under the `"paper.pdf":` key. Prefer the UI or the API (`POST /api/annotate`,
+    `POST /api/fragment`) over hand-writing selectors; if you must, keep the key names exact and
+    never renumber or reorder fragment slugs.
+- Tasks, workflows, and boards
+  - >
+    A **task** is a chapter plus planning fields - `!!<*yamlover: $defs: task>`, the title as
+    self-value, keyed `description`, `priority` (low/normal/high/urgent, advisory), `due`,
+    `assignee`, `estimate`, an optional `workflow` - and a body of chunks and **subtasks**. It
+    carries **no state field**: its lifecycle position is one membership bookmark into a workflow
+    onto. There is no separate board schema: **a board is a task with subtasks** (the retired
+    `$defs: board` tag still reads as a task).
+  - !!<format: text/x-yamlover> |
+    !!<*yamlover: $defs: task>
+    Fix the leaky tap
+    description: The bathroom tap drips overnight - replace the washer, or the cartridge.
+    priority: high
+    assignee: dims
+    estimate: 2h
+    - *..: buy-washers.yo                # a BLOCKER - a link to a sibling task (up to the board dir): a subtask here
+    - Turn the water off at the valve under the sink FIRST.
+    - A half-inch washer kit is in the garage toolbox.
+    &::yamlover:ontos:workflow:dev:ready:-            # the STATE - one bookmark line
+  - >
+    **Subtasks** are body elements that are tasks BY THEIR OWN TAG: an inline container tagged
+    `!!<*yamlover:$defs:task>` (an untagged container is a plain section of the task, as in a
+    chapter), a pointer to the task's OWN child (`- *: slug.yo`, a file or directory under it
+    whose document carries the tag), or a link to a task **elsewhere**
+    (`- *..: slug.yo`, `- *:: …`) - a BLOCKER is a subtask of the task it blocks; the link is the
+    DAG edge, the linked task keeps its own storage (so one card may sit in several tasks' lanes).
+    Every subtask is a card of the task's lanes, by its state, and a row of its TOC - a keyless
+    pointer is a positional member of its node, the general rule. Keys keep their `.yo`.
+  - >
+    The built-in **`dev` workflow** (`$defs: workflow` - a tag whose sub-tags are the states) has
+    `backlog` -> `ready` -> `in-progress` -> `review` -> `done` | `cancelled`; `initial:` and each
+    state's `next:` are advisory ref edges - the engine permits any transition. A **board** is a
+    task whose subtasks are files (or inline elements) - a directory tagged in its `index.yo` (or a
+    legacy `.yo/body.yo`, read forever):
+  - !!<format: text/x-yamlover> |
+    # engine/index.yo (or engine/.yo/body.yo)
+    !!<*yamlover:$defs:task>
+    Engine                                             # the board's title (self-value)
+    description: the work board
+    workflow: *::yamlover:ontos:workflow:dev           # optional: EMPTY lanes for states no card has yet
+  - >
+    Every task member of the directory is a **card**. Lanes come from the task's own
+    workflow or the nearest ancestor task's workflow, excluding its initial state; they do
+    not come from whichever tags the cards happen to carry. Initial-state and unmatched cards
+    wait in **Other**. Without a workflow or explicit layout there are no lanes.
+    Saved layouts live in `.yo: lanes:`; missing workflow lanes are completed on reconcile,
+    and terminal states may share a column. Reads reconcile the display in memory without
+    writing files; board mutations persist the layout. **Tags are the truth** for membership.
+    On a chapter page a task is one card; on its own page it shows its planning strip,
+    its foldable board, and its prose.
+  - >
+    **Operating a board from the files.** To **create a subtask**: add `slug.yo` with the tag, a
+    title line, optional fields, and a state bookmark - it is a card on the next reindex (name it in
+    the parent's body with `- *: slug.yo` to give it a position; an untagged file is not a task
+    card). To **move a card**: change its state bookmark line (`...:dev:ready:-` to
+    `...:dev:in-progress:-`); the lanes follow. To **reorder or restructure lanes**, or to move a
+    card as the UI does (`POST /api/board` with `op: "move"`), go through the API - it re-tags and
+    rewrites `.yo: lanes:` together. Do not hand-edit `.yo: lanes:` to move a card: the tag on the
+    card wins, and the next reconcile undoes you. A board's LANES are its workflow's states beyond
+    the initial one - its own `workflow:` or the nearest ancestor task's - never derived from the
+    cards' tags; the initial state IS the `other` pane; a card tagged otherwise waits there too; an
+    empty tagless compartment is forgotten on reconcile. An inline subtask drags too - its state
+    bookmark lands on its own line under the element's head. States BUBBLE UP: a task whose subtask
+    (member or linked blocker, transitively) is in a further non-terminal state stands in that lane
+    on its parent's board, its card saying via which subtask; its own terminal state never moves,
+    and the file keeps only the task's own bookmark. And THE PARENT FOLLOWS: when a subtask reaches
+    the workflow's active state (`in-progress`), every host still behind it (no state, backlog,
+    ready) is written to that state, forward only - review and done stay the host's own call. To
+    **declare a blocker**: add `- *..: slug.yo` as a body element of the blocked task - it joins
+    that task's lanes and its TOC. **Storage**: a task born from the board's `+` is a DIRECTORY
+    member of its host, `task-N/index.yo` (the smallest unused N), **named at birth and never
+    renamed by the machine**; rename it yourself with `POST /api/rekey` (`{ path, key }` - it moves
+    the directory and rewrites every pointer). Nothing converts a file task to a directory or back:
+    a legacy `slug.yo` file task keeps working as it is.
+- Working the tickets - the process for an agent
+  - >
+    A yamlover project runs its work as **tickets**: task files under a tickets directory
+    (`docs/server/todo/*.yo`, say), **sessions** (a task per working session - a directory
+    with an `index.yo` - whose body links the tickets it works, `- *:: server: todo: x.yo`,
+    so each is a card on the session's board), and **subtasks** born under a ticket or a
+    session (`task-N/index.yo`). The `dev` workflow's lanes ARE the process; the state of a
+    ticket is the one bookmark line in ITS OWN file, and moving a card means rewriting that
+    line (or `POST /api/board` `op: move`, or `POST /api/annotate`) - never a hand edit of a
+    board's `.yo: lanes:`. Tag the NODE, never a walked slot (`:session:5`): a bookmark written
+    at the slot lands in the session's file, not the card's.
+  - !!<*yamlover: $defs: bullets>
+    - '**The card moves with you - first.** Before the first edit for a ticket, move its card to `in-progress` - THE TAG IS THE MOVE: rewrite the card''s own state line (`&::yamlover:ontos:workflow:dev:in-progress:-`), or `POST /api/board` with `op: "move"` on a live server, and let the lanes follow. Never hand-edit `.yo: lanes:` to move a card (the tag wins and the next reconcile undoes you). The human watches the board to see what you are on: a card still in `backlog` or `ready` while you work on it is a bug in your process.'
+    - '**Titles and slugs.** Every ticket you create has a TITLE - its first line, a sentence a human reads on a card - and a proper SLUG: the file or directory name is the title''s slug (lowercase, hyphenated, the key words: `rename-leaves-the-menu-open.yo`, `the-key-cell/`), never a serial. `task-N` is only what the board''s ＋ births for a human to name; a card you were handed under a serial name gets its slug through `POST /api/rekey` before you work it.'
+    - '**Refine before you build.** Read the card, write what you understood and the law you will implement into its body (a dated `- >` note), and birth subtasks (descriptive slug directories under the card, each with its own tag, title, `assignee: agent`, and `&...:dev:ready:-`) when the work has parts; each subtask moves to `in-progress` as you take it, to `review` as it lands.'
+    - '**Review means green.** When the code and its pins pass, write a dated "In review" note - what changed, where it is pinned, the suite counts - and move the card to `review`. A UI change waits there for the human''s hands-on check.'
+    - '**Done only with the commit.** A card goes to `done` in the same commit that lands its work (the commit message names the cards); never before. A card the human closes by drag is theirs.'
+    - '**`assignee` says whose call it is.** `agent`: yours to take from `ready`. `user`: the human''s - a question, a check, a decision; you do not move it.'
+    - '**A decision record** (`!!<*::yamlover:$defs:decision>` - a task subtype with `question`, `options`, `decision`, `decided`) is how you hand a question to the human without stalling: birth it under the section where the question arose, `assignee: user`, state `ready`; LINK it from the ticket it blocks (`- *:: session: decide`) - a blocker card on that ticket''s board, waiting; then go on with everything that does not depend on the answer and name it in your report. The human writes `decision:` and moves it to done.'
+    - '**Never move a card as a side effect.** No bulk retagging, no "tidying" of lanes, no state written into a file the human did not name. The server logs every state write on its console (`[state] <op> <node> +tag` / `-tag`) - a card that moved has a line there.'
+    - '**A commit closes the loop.** Commit what you did with a message that tells the law, the fix, the pins and the cards; the human decides where it is pushed. Stage only your task changes unless the human asks to commit the whole state; preserve concurrent edits.'
+- Operating the running server
+  - >
+    The server **watches the filesystem**: every save reindexes and pushes the diff to the
+    human's browser over SSE within a moment, and their edits appear to you on disk. Everything
+    a client does goes through the HTTP API; it is yours to use too, and the safest way to do
+    anything structural.
+  - !!<*yamlover: $defs: table>
+    header:
+      - Endpoint
+      - Use
+        width: 3
+    - ['`GET /api/tree?path=:a:b&depth=3`', 'the TOC subtree - labels, types, formats, `hasChildren`']
+    - ['`GET /api/content/a/b`', 'THE WIRE - a node as a yamlover envelope (`source`, `side`, `relations`); the path is slash-spelled here, digits are positions, `~` the null key']
+    - ['`GET /api/source?path=:a:b`', 'the raw yamlover text of a document (or a re-serialized subtree)']
+    - ['`GET /api/query?q=...&path=:`', 'evaluate a colon-grammar query (`humans: ?: name`, `...: !!<format: x-yamlover-onto>`); `shape=paths` / `tree` / `filter`']
+    - ['`GET /api/dangling`, `GET /api/doctor`', 'pointers that did not resolve; the whole-tree layout-rule sweep - **run both after a batch of edits**']
+    - ['`GET /api/board?path=:engine`', 'the reconciled board and card stubs; `seeded: true` means no saved layout exists; `backlog` contains cards no compartment holds (Other)']
+    - ['`POST /api/edit`', 'THE SURGICAL EDITOR: `{ path, op, yamlover }` with `op` = `emplace` (replace only the facets the payload carries), `replace`, `insert` (at the index `path` names), `remove` (storage-backed members are archived), `unlist` (remove a listed reference while retaining its target); `yamlover` is inline source, validated then spliced verbatim - comments elsewhere survive; `{ edits: [...] }` batches']
+    - ['`POST /api/mv` `{ from, to }`', 'move/rename a file or directory **and rewrite every inbound pointer** - prefer it over `mv`']
+    - ['`POST /api/rekey` `{ path, key }`', 'rename a key - storage-routed: on disk for a file or directory member (every pointer rewritten), in place for an inline entry; a positional path takes a key, `key: null` drops one - the entry never moves']
+    - ['`POST /api/paste`', 'file upload with `{ path, filename, contentBase64, placement, at }`: `placement: "member"` adds an unlisted directory member or an inline keyed reference; `"body"` inserts a chunk at absolute index `at`. Duplicate names receive a suffix. Text and rich HTML modes also exist']
+    - ['`POST /api/annotate` `{ target, tag }` / `DELETE`', 'apply / remove a membership bookmark on a node or fragment']
+    - ['`POST /api/fragment` `{ target, selector }`', 'mark a region under the target''s `.yo: fragments:`']
+    - ['`POST /api/board` `{ path, op }`', '`move` (the drag: re-tag + restructure), `structure` (rewrite the lanes), `reconcile`']
+    - ['`POST /api/reindex`', 'force a reconcile when the watcher missed something']
+  - >
+    **Concurrent edits and retries.** Read `/api/content/…?editing=1` and retain its
+    `X-Yamlover-Revision` header. Mutation requests can include
+    `safety: { revision, operationId }`, where the operation identifier is
+    `<milliseconds-since-epoch>:<UUID>`. Retry an uncertain request with its exact original
+    payload and identifier; do not mint a new one and duplicate the action. A conflict needs
+    a fresh read and reconciliation with the unsaved work. Requests without safety remain
+    compatible but lack this concurrency protection.
+  - >
+    **Generated metadata.** Reconcile removes computed thumbnail metadata for missing files
+    and prunes empty metadata containers. Authored fragments and other meaningful metadata
+    must be preserved. Do not erase `.yo:` wholesale to repair a stale thumbnail.
+  - >
+    With `--read-only` every writing route answers 403 - then the files are the only way in, and
+    your saves still show up live.
+  - >
+    **Safety rules for co-editing:**
+  - !!<*yamlover: $defs: bullets>
+    - '**Make small, valid saves.** A half-written file reindexes as broken and shows the human a parse-error banner. Prefer complete edits; check `GET /api/dangling` afterwards.'
+    - '**Never touch `.yo/index.db`** (nor `-wal` / `-shm`). It is the generated index. Instance and schema overlays are source files; logical `.yo:` metadata is engine-managed through annotation, fragment and board APIs, with settings the authoring exception.'
+    - '**Renames and moves break inbound pointers.** A plain `mv` leaves every `*: old: path` dangling. Use `POST /api/mv` (it rewrites them at the source) or search the project for pointers to the old path and fix them yourself.'
+    - '**Distinguish unlisting from deletion.** `/api/edit` with `op: "unlist"` removes a keyless reference placement, keeping its target. Removing storage-backed members archives their files or directories into the parent''s `.yo/.trash/`; removing inline source is a source edit. Filesystem deletion bypasses that archive. Do not promise reference redirection or memory stubs: those remain future work.'
+    - '**Do not reformat with a generic YAML/JSON tool.** It mangles `*`, `&`, `!!<...>`, colon paths, pins, and the mixed keyed/keyless order. Edit the text and preserve the author''s style.'
+    - '**Confirm a path before you point at it** - `GET /api/query` or `/api/tree` - and read a chapter''s absolute indexes off `/api/content` before an `/api/edit`.'
+    - '**Settings** (`.yo/settings.yo`) say where things are *created*, never constrain reading; change them only when asked.'
+- Escaping
+  - >
+    A literal metacharacter inside a key is **backslash-escaped**, per character: `cat\:dog`
+    is the key "cat:dog", `*\.\.` the literal key "..", `\*boss` the key "*boss". The
+    metacharacters are `: [ ] * & ~ # \` and the query characters `? ! ( ) < > = |`. A key
+    whose **whole** bare form reads as something else is **quoted** instead: a space inside
+    (`'дорожный знак'`), pure digits (`'1'`), `'~'`, `'-'`, an empty key, a position-shaped
+    token (`'2024-01'` - the bare form is a range; `2024-01-15` rides bare). In `.json5p` the
+    same pointer is a quoted string: `*'..: ..: pets: 1'`.
+- Quick reference
+  - !!<format: text/x-yamlover> |
+    # references (pull) - colon paths, the scope ladder
+    sibling:   *pets: 1                  # current mapping, position 1
+    rooted:    *: humans: 0: name        # document root -> position 0 -> key name
+    strkey:    *: counts: '1'            # QUOTED digits = the numeric STRING key
+    nullkey:   *: doc: ~                 # the null key
+    project:   *:: ontos: genre          # this project's root
+    world:     *::: yamlover.inthemoon.net: $defs: onto
+    last:      *items: .len-(1)          # position arithmetic
+    previous:  *.-(1)                    # my previous sibling
+    later:     *.                        # postponed - known, not loaded
+
+    # bookmarks (push) - "I also live there"; real keys; unambiguous only
+    here:  &: chief: Rex                 # also the document-root key `chief`, value Rex
+    rev:   &: parent: child              # parent holds me as `child`
+    mem:   &: favorites: -               # appended keyless member of `favorites`
+    &:: yamlover: ontos: colors: yellow: -   # own-line: file THIS node under an onto
+
+    # schema tags
+    !!<*yamlover: $defs: chapter>        # a document; task / table / bullets likewise
+    - !!<format: text/x-latex> |         # a chunk's format override
+      e^{i\pi}+1=0
+    - !!yo                               # a data island inside a document
+      k: v
+
+    # partial
+    10: ten                              # a pin - positions 0-9 are gaps
+    - *.                                 # the tail is open
+
+    # escaping
+    lit:   *weird: cat\:dog              # a literal colon in a key
+    space: *: ontos: 'two words'         # a spacey key is quoted
+- Where to read more
+  - !!<*yamlover: $defs: table>
+    header:
+      - Topic
+      - Online chapter
+        width: 2
+    - ['the language - principles, the logical graph, the concretes, YAML differences', '<"yamlover.inthemoon.net/docs/language"| -: "https://yamlover.inthemoon.net/docs/language">']
+    - ['pointers, paths, scopes, bookmarks, position arithmetic, escaping, queries', '<"docs/language/pointers"| -: "https://yamlover.inthemoon.net/docs/language/pointers">']
+    - ['partial documents - pins, gaps, postponed branches', '<"docs/language/partial"| -: "https://yamlover.inthemoon.net/docs/language/partial">']
+    - ['flat rows', '<"docs/language/flattening"| -: "https://yamlover.inthemoon.net/docs/language/flattening">']
+    - ['storage - files, directories, overlays, member encoding', '<"docs/language/concretes"| -: "https://yamlover.inthemoon.net/docs/language/concretes">']
+    - ['the meta language - `type`, `format`, `members`, `$defs`', '<"docs/meta"| -: "https://yamlover.inthemoon.net/docs/meta">']
+    - ['chapters, tasks, addressing body elements', '<"docs/documents/chapter"| -: "https://yamlover.inthemoon.net/docs/documents/chapter">']
+    - ['marklower - grammar, link targets, embeds, tables, lists', '<"docs/documents/marklower"| -: "https://yamlover.inthemoon.net/docs/documents/marklower">']
+    - ['annotations - fragments, ontos, membership, storage', '<"docs/annotations"| -: "https://yamlover.inthemoon.net/docs/annotations">']
+    - ['foreign formats - Markdown, AsciiDoc, office, images, media, maps', '<"docs/formats"| -: "https://yamlover.inthemoon.net/docs/formats">']
+    - ['the server - UI, editors, endpoints', '<"docs/server"| -: "https://yamlover.inthemoon.net/docs/server">']
+    - ['worked examples (a table, a chapter, a board - a task with subtasks, marklower links, a deep book)', '<"yamlover.inthemoon.net/examples"| -: "https://yamlover.inthemoon.net/examples/">']

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

@@ -17,8 +17,6 @@ members:
         concrete: yamlover/meta
     workflow:
         concrete: yamlover/meta
-    board:
-        concrete: yamlover/meta
     table:
         concrete: yamlover/meta
     bullets: