yamlover 0.3.55 → 0.3.58

package/README.md

@@ -168,7 +168,7 @@ take an optional `depth` (container-nesting limit).
 | `POST / DELETE /api/annotate` | add / remove an annotation on a target |
 | `POST /api/fragment` | upsert a fragment (region of a target) |
 | `POST /api/board` | board mutations |
-| `POST /api/agent-docs` | install the LLM-agent guide (`AGENTS.md` + `CLAUDE.md`) into the root — a marker-fenced block appended to (or updated in place within) an existing file, never clobbering the human's own rules; idempotent |
+| `POST /api/agent-docs` | install the LLM-agent guide (`AGENTS.yo` — a yamlover chapter covering the language, marklower, chapters, tables, annotations, tasks and boards, the API, with links to the online docs — plus a `AGENTS.md` — the stub every agent reads, pointing at it; an existing `CLAUDE.md` is kept in step) into the root — a marker-fenced block, updated in place on reinstall, appended after the human's own rules in a Markdown file, a human's own unfenced `AGENTS.yo` kept untouched; idempotent |
 
 #### `POST /api/edit` — the editor
 
@@ -239,8 +239,8 @@ Registered today (a representative slice — the registry is the source of truth
 | renderer | matches (format) | draws with |
 |----------|------------------|------------|
 | `chapter` | `x-yamlover-chapter` | a positional body: numbered chunks + subchapter links |
-| `tag` / `board` | `x-yamlover-onto` / `x-yamlover-board` | tag-hierarchy diagram / board (handled outside the specificity loop) |
-| `task` | `x-yamlover-task` | task view |
+| `tag` | `x-yamlover-onto` | tag-hierarchy diagram (handled outside the specificity loop; `tag-board` is a fixed tab on every container) |
+| `task` | `x-yamlover-task` | the planning strip, then the body: prose as a chapter's, the SUBTASKS — own members and linked blockers — as lanes (a board is a task with subtasks) |
 | `table` | `x-yamlover-table` | a grid (`docs/documents/marklower`): rows/header/caption from the omni entries, merged cells (`colSpan`/`rowSpan`) from resolved relative-index `*` pointers, nested tables inline, marklower cells; prose cells edit in place under the lock |
 | `marklower` | `text/marklower` (a chapter's prose chunks, by schema propagation) | its own inline grammar (`docs/documents/marklower`): emphasis, `` `code` ``, `$$math$$` via KaTeX, links, and `*[…](…)` media embeds |
 | `markdown` | `text/markdown` | [marked](https://marked.js.org) |
@@ -293,7 +293,13 @@ Inference splits two ways by how the renderer consumes the file:
 
 - Node.js **22.13+** (the engine's store uses the built-in `node:sqlite`, unflagged only from 22.13).
 
-There are **no runtime dependencies**: the client deps are bundled into
+MP4 frame playback and thumbnails require **FFmpeg** (`ffmpeg` and `ffprobe`) on
+the server PATH. HEVC and other non-H.264 MP4 files cache H.264 previews and frame metadata
+under `.yo/videos` for reuse across server restarts; originals stay unchanged. Select the video tab, drag to pan, use modifier-wheel to
+zoom, and use the collapsible time ruler for live scrubbing. Frame steps, five-second
+jumps and playback controls stay in the toolbar; the speaker icon toggles mute.
+
+There are **no npm runtime dependencies**: the client deps are bundled into
 `dist/client` by `vite build` and the server deps into `dist/server.js` by
 esbuild at `prepack`. The `devDependencies` (React, Vite, the engine/parser, and
 the renderer libraries) are build- and test-time only. DjVu.js is **vendored**
@@ -315,6 +321,16 @@ runs only the parser and engine suites) and from the editor package's own suite
 `docs/server/editor/yed`). CI gates on all of them, so run them before pushing. (Run
 everything from the project root — see the root `package.json`.)
 
+**Node versions — two numbers for two reasons.** Running the server needs Node
+**≥ 22.13**: the engine's store is `node:sqlite`, and `bin/yamlover.js` checks that
+floor at startup. Running the source-level suites (`node --test …*.test.ts` at the
+root and in the parser, engine and docs2yamlover packages) needs TypeScript
+stripping, which Node does natively only from **22.18** on — every such script passes
+`--experimental-strip-types` (available since 22.6, a no-op once stripping is the
+default), so the declared 22.13 floor runs the tests too. Without the flag, a
+conforming machine below 22.18 fails every file with `ERR_UNKNOWN_FILE_EXTENSION
+".ts"` before an assertion runs.
+
 ## Layout
 
 ```
@@ -328,7 +344,7 @@ src/server/            the engine-backed JSON API
   tasks.ts               background task registry + SSE task frames
   gitignore.ts           .gitignore predicate for surfaced stray files
   extract/               the thumbnail pipeline: decoder registry (raster/psd/webp/avif) + scaling
-  agent-docs/            the AGENTS.md / CLAUDE.md guide installed by POST /api/agent-docs
+  agent-docs/            the AGENTS.yo guide (+ AGENTS.md stub) installed by POST /api/agent-docs
 src/client/            the React SPA (tree, node view, render, icons, paths, live SSE)
   renderers/             facet-predicate renderer registry + per-format renderers; the
                          unlocked editors are yed mounts over ../yed (@yamlover/yed) — docs/server/editor
@@ -336,3 +352,30 @@ src/client/            the React SPA (tree, node view, render, icons, paths, liv
 test/                  Vitest suite (server logic + client components)
 index.html             SPA shell
 ```
+
+### Gather/decompose in the source editor
+
+In the yamlover data view, unlock **Edit**, then choose **Gathered marklower**.
+The panel holds a local text draft and a yamlover preview. **Apply as yamlover**
+decomposes it into the existing tree, using the normal revision-protected save and
+Undo/Redo path. Invalid or cancelled drafts never write. Ctrl+Z inside the textarea
+uses native text undo. An external editor-history change invalidates the draft's base.
+
+Gathering refuses bookmarks/comments, gaps, blobs and separately stored members;
+open an inline subtree when a directory is too broad.
+
+Gathered marklower can be authored in an ordinary `.yo` scalar, usually a `|` block,
+without a format tag. The engine projects structural continuations into queryable
+chapter nodes while respecting explicit plain/code formats and data islands. Save
+`examples/79-gathered-marklower.yo` using an external editor; normal reconciliation
+picks up the change. Invalid structure displays its source and recovers when repaired.
+The optional `.marklower` exchange concrete remains supported.
+
+Projected documents and their interior nodes are browser-read-only until gathered
+source writing is ready. `GET /api/source` returns exact file text at the root or
+decomposed yamlover for an interior node. File renames maintain references inside
+quoted and block scalar carriers. Moves that would remove gathered ordering refuse
+before changing files. Ordinary chapter editing stays WYSIWYG: typed structural
+markers are escaped when saved, including text containing only markers.
+The syntax, migration filter and current limits are documented in
+`docs/documents/marklower/gathered/index.yo`.

package/bin/yamlover.js

@@ -72,6 +72,7 @@ let basePath = process.env.BASE_PATH ?? "";
 // CONTENT READ-ONLY: every user-data-mutating API route answers 403 and the UI hides its edit
 // affordances; the server still maintains its own index (.yo/index.db). Seeded from
 // $YAMLOVER_READ_ONLY (same shell-less-image rationale as $BASE_PATH); `--read-only` below too.
+let printOpenApi = false;
 let readOnly = ["1", "true", "yes"].includes(String(process.env.YAMLOVER_READ_ONLY ?? "").toLowerCase());
 // Normalize a base path: leading `/`, no trailing `/`; `""`/`"/"` → disabled.
 function normBase(s) {
@@ -95,11 +96,13 @@ for (let i = 0; i < argv.length; i++) {
   else if (a === "--no-gitignore") gitignore = false;
   else if (a === "--prod") prodFlag = true;
   else if (a === "--read-only") readOnly = true;
+  else if (a === "--print-openapi") printOpenApi = true; // print the wire's OpenAPI document (JSON) and exit
   else if (a === "--help" || a === "-h") {
-    console.log("usage: npx yamlover [ROOT] [--port N] [--headless] [--host ADDR] [--base-path PREFIX] [--no-gitignore] [--prod] [--read-only]");
+    console.log("usage: npx yamlover [ROOT] [--port N] [--headless] [--host ADDR] [--base-path PREFIX] [--no-gitignore] [--prod] [--read-only] [--print-openapi]");
     console.log("  default: serve on 127.0.0.1 (local only); --headless serves on all interfaces");
     console.log("  --base-path PREFIX: serve the whole app under PREFIX (e.g. /demo/abc) instead of /");
     console.log("  --read-only: serve content read-only — every modifying request is refused (403)");
+    console.log("  --print-openapi: print the wire's OpenAPI document (JSON, docs/server/wire) and exit");
     process.exit(0);
   } else if (!a.startsWith("-")) rootArg = a;
 }
@@ -187,6 +190,7 @@ function serveCrawlerFile(req, res, pathname) {
 }
 
 let createHandlers;
+let serverModule; // the handler module — also exports openApiDocument (--print-openapi)
 if (prod) {
   // -- production: prebuilt static client + bundled server, no Vite ---------- //
   const distClient = join(pkgRoot, "dist/client");
@@ -196,7 +200,8 @@ if (prod) {
     console.error("          run `npm run build` in tools/server first.");
     process.exit(1);
   }
-  ({ createHandlers } = await import(pathToFileURL(join(pkgRoot, "dist/server.js")).href));
+  serverModule = await import(pathToFileURL(join(pkgRoot, "dist/server.js")).href);
+  ({ createHandlers } = serverModule);
   serveClient = (req, res, url) => serveStatic(req, res, url, distClient, distIndex);
 } else {
   // -- live: Vite middleware + ssrLoadModule (repo checkout) ----------------- //
@@ -279,7 +284,8 @@ if (prod) {
   // The engine-backed handler (engine-api.ts) is loaded via `ssrLoadModule` so its
   // TS — and the engine/parser source it reaches into (`../../../engine`,
   // `../../../parser`) — is transpiled live, with no build step.
-  ({ createHandlers } = await vite.ssrLoadModule("/src/server/engine-api.ts"));
+  serverModule = await vite.ssrLoadModule("/src/server/engine-api.ts");
+  ({ createHandlers } = serverModule);
 
   const indexHtmlPath = join(pkgRoot, "index.html");
   const spaShell = async (req, res, url) => {
@@ -334,6 +340,12 @@ const ts = () => {
 // The initial index runs as a BACKGROUND task — the server listens immediately
 // (serving the previous on-disk index, or an empty tree on a cold start) while
 // progress lands here and in the web UI (SSE task frames + GET /api/tasks).
+if (printOpenApi) {
+  // the document needs no tree: the schemas come from the bundled taxonomy, the routes from the
+  // authored openapi.yo — print and leave before any index is touched
+  process.stdout.write(JSON.stringify(serverModule.openApiDocument(), null, 2) + "\n");
+  process.exit(0);
+}
 handle = createHandlers(dataRoot, {
   gitignore,
   watch: true, // re-index + push on external edits
@@ -466,7 +478,15 @@ function listenWithFallback(p, triesLeft) {
   const onListening = () => {
     server.off("error", onError); // bound OK — stop intercepting listen errors
     console.log(`yamlover ${ts()}  serving ${dataRoot}${prod ? "" : "  (live/Vite)"}`);
-    console.log(`                        http://${shown}:${p}/  (bound to ${host})`);
+    const boundPort = server.address().port; // --port 0 asks the OS for a free port.
+    const url = `http://${shown}:${boundPort}${basePath}/`;
+    console.log(`                        ${url}  (bound to ${host})`);
+    // The desktop utility process uses a structured handshake, never log scraping.
+    // Wait for indexing too: a listening socket alone does not mean the tree is usable.
+    if (process.parentPort) {
+      handle.ready.then(() => process.parentPort.postMessage({ type: "yamlover-ready", url }))
+        .catch(() => process.exit(1));
+    }
     // Say it out loud: analytics is off in every normal run, so when it IS on the operator
     // should see which stream is being fed and exactly what paths reach it.
     if (ga4) {
@@ -479,3 +499,20 @@ function listenWithFallback(p, triesLeft) {
 }
 
 listenWithFallback(port, MAX_PORT_TRIES);
+
+// Normal CLI/desktop termination must reap decoder workers and disposable video previews.
+let stopping = false;
+async function shutdown() {
+  if (stopping) return;
+  stopping = true;
+  const deadline = setTimeout(() => process.exit(1), 10000);
+  deadline.unref();
+  server.close();
+  server.closeAllConnections();
+  try { await handle.close(); }
+  catch (error) { console.error("yamlover shutdown:", error); }
+  clearTimeout(deadline);
+  process.exit(0);
+}
+process.once("SIGINT", shutdown);
+process.once("SIGTERM", shutdown);

package/dist/agent-docs/AGENTS.md

@@ -1,330 +1,20 @@
-# Working with this yamlover project (guide for AI agents)
-
-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
-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. 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.
-
----
-
-## 1. What yamlover is
-
-yamlover is a **distinct, YAML-like language** — close to YAML and mostly readable as it, but
-**not a strict superset**: `*` and `&` carry different meaning (see below), so a stock YAML
-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 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 `.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
-a generic YAML formatter — you will destroy the pointers and anchors.
-
----
-
-## 2. The one-ordered-container model
-
-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)
-and keyed entries coexist in one node — this is the default ("omni"):
-
-```yamlover
-playlist:
-  - 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                  # position 0  positional field
-  scale: 10                # position 2  keyed field
-```
-
-(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.)
-
----
-
-## 3. Paths use COLONS, not slashes
-
-A path is `key: value` chained. The separator is the **colon**: `a: b: c` means "key a → key b →
-key c". Canonical style writes `: ` (colon + space) after each step; a colon without the space
-also parses.
-
-`/` is an **ordinary character** now — MIME-type keys (`text/html`), date keys (`01/02/2026`)
-and URL-ish keys ride bare in a path. (The old `/`-separator form is DEAD — it no longer
-parses as a path: `*/pets` is a dangling reference to the literal key "/pets". Author `:` only.)
-
-### The scope ladder — more colons, wider scope
-
-```
-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: onto        # :::        — the world (an external project)
-```
-
-- `*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.
-
-### 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 **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
-```
-
-Pointers are **lazy** and **cycle-safe** — pointing two nodes at each other is fine. Editing the
-target changes everything that points at it.
-
----
-
-## 5. Path anchors `&` (the push side)
-
-`&: path` on a node declares "this node **also lives** at that path" — it grafts a **real key**
-(there is no separate anchor namespace), so any plain pointer can then reach it:
-
-```yamlover
-boss: &: chief             # this node is ALSO reachable as the document-root key `chief`
-  name: Rex
-team:
-  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":
-
-```yamlover
-adam:
-  cain:
-    &: eve: cain           # "eve holds me as cain" — the reverse of eve's cain-edge
-```
-
-`&: 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`
-```
-
-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.
-
----
-
-## 6. Tags `!!` and `$defs` schemas
-
-- `!!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: 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.
-
----
-
-## 7. Concretes: how a node is stored on disk
-
-A node can be materialized two ways:
-
-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 `.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.
-   - `.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
-`.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
-members it names (the projection shows each consumed key as a dimmed derived `&` anchor,
-`- &file1 value`); a member the body never names stays keyed-only, after the ordered block.
-Editing derives storage for NEW children by the INHERITANCE RULES (`concrete-rules.ts` — one
-pure module, an explicit `concrete:` always wins): a directory-concrete parent keeps children
-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.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
-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.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/.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).
-
----
-
-## 8. Annotations & fragments (tags applied to content)
-
-The human marks up documents in the UI. These live **on the target node**, not in side files:
-
-- **`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:
-    - *:: 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 (`yo: fragments:`, `yamlover-annotations`) and the tag-pointer form, and do
-not renumber or reorder fragment slugs.
-
----
-
-## 9. Escaping (critical when editing keys)
-
-A literal metacharacter inside a key is **backslash-escaped** (this is per-character, not
-quote-based):
-
-```yamlover
-weird:
-  cat\:dog: 1              # the literal key "cat:dog" (\: suppresses the separator)
-  cat/dog: 2              # `/` is ordinary now — no escape needed
-ref:  *weird: cat\:dog    # the second portion is the literal key "cat:dog"
-dots: *\.\.               # the literal key ".." (NOT the parent scope)
-```
-
-- Metachars that need escaping in a key include: `:` `[` `]` `*` `&` `~` `#` `\` `?` `!`
-  `(` `)` `<` `>` `=` `|`.
-- The literal keys `..` and `...` are written `\.\.` and `\.\.\.` (bare `..` means "parent").
-- **A key containing a space MUST be quoted**: `: tags: 'дорожный знак'`. Use the host surface's
-  string quoting (`'…'` / `"…"`).
-
----
-
-## 10. Co-editing workflow & safety rules
-
-The yamlover server **watches the filesystem**. Every time you save a file, it reindexes and
-pushes the change to the human's browser over a live event stream — so your edits appear in their
-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 `.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 `.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
-  references at their source. Prefer it for moves/renames; if you must move by hand, search the
-  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 `.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'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.
-
----
-
-## 11. Quick reference
-
-```yamlover
-# pointers (pull) — colon paths, the scope ladder
-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`
-
-# tags / schema
-node:  !!<*:: $defs: chapter>       # bind a reusable schema
-
-# escaping
-lit:   *weird: cat\:dog             # literal colon in a key
-space: : tags: 'two words'          # spacey key must be quoted
-```
+## yamlover — read `AGENTS.yo` first
+
+This directory is a **yamlover** project: its structured knowledge lives in `.yo` files, a
+YAML-like language that is **not** YAML (`*` is a path pointer, `&` a bookmark). The authoring
+rules — pointers and bookmarks, marklower prose, chapters, tables, annotations, tasks and boards,
+and the ticket process for an agent — and the rules for safely co-editing the tree while the
+yamlover web UI is running are in **`AGENTS.yo`** beside this file (itself a yamlover chapter —
+read it as text; every code span is a literal spelling). Read it before editing any `.yo` /
+`.json5p` file. The full reference is online at https://yamlover.inthemoon.net/docs.
+
+The three rules that matter most:
+
+- **Never reformat a `.yo` file with a generic YAML tool** — it destroys pointers, bookmarks and
+  tags. Edit the text and keep the author's style.
+- **While the server runs, go through its API** — `POST /api/edit`, `/api/mv`, `/api/rekey`,
+  `/api/annotate` — rather than raw writes for anything structural, and check
+  `GET /api/dangling` after a batch of edits.
+- **A ticket's state is one bookmark line in its own file**
+  (`&::yamlover:ontos:workflow:dev:in-progress:-`). Move a card by rewriting that line — never by
+  editing a board's `.yo: lanes:`, which the tags overrule on the next reconcile.