okf 2.0.0 → 2.1.1

data/lib/okf/skill/reference/cli/checks.md

@@ -0,0 +1,171 @@
+# Checking a bundle — `validate`, `lint`, `loose`, `references`
+
+Kind: reference. Answers: what makes a bundle non-conformant, what each lint
+check means and the severity it is pinned at, which of the two clocks a flag
+reads, and which dangling pointers each surface can and cannot see.
+
+The shared contract — `@slug` refs, exit codes, `--json`, the filters — is in
+[cli.md](../cli.md) and is not repeated here.
+
+## validate — the hard gate (§11)
+
+Implements the spec's §11 conformance definition exactly (its words are in
+[SPEC.md](../SPEC.md), routed by [spec-map.md](../spec-map.md)):
+
+- **§11 cond. 1** every non-reserved file has a parseable YAML frontmatter block;
+- **§11 cond. 2** every such block has a non-empty `type`;
+- **§11 cond. 3** any `index.md`/`log.md` present follows §8/§9 (a nested
+  `index.md` has no frontmatter, a root `index.md` carries only `okf_version`,
+  `log.md` date headings are ISO `YYYY-MM-DD`).
+
+`ERROR`s are the three conditions above; the bundle is non-conformant until every
+one is fixed. `warn`s are soft — missing recommended fields, non-list tags, an
+unparseable timestamp, **broken cross-links, which §6.1 explicitly tolerates**,
+the shape of every §5/§10 family (`generated` not a mapping, a non-integer
+`usage_count`, a `stale_after` that is not `YYYY-MM-DD`, a missing `runtime` on
+an Attested Computation, …), and an `okf_version` the gem does not know (read
+best-effort under §12; an absent one never warns). Absence of an optional family
+is never a fault — a pure v0.1 bundle validates with zero warnings.
+
+In `--json`, every warning carries `check` (a stable id) and `source` — `spec`
+when the SPEC's own words state the rule, `convention` for a shape this gem asks
+for beyond them (`verified[].by` presence, integer `usage_count`, a per-entry
+`usage_window` mapping, `parameters[].name`, `executor`/`attester` `resource`).
+Gate on `source` when you want only the spec-normative set; errors keep their
+two-key `{ path, message }` shape. Fix warnings when cheap; never block on them.
+Use `--json` in CI.
+
+## lint — curation quality (advisory)
+
+Asks the complementary question to `validate`: not "is this legal OKF?" but "is
+this well-curated, navigable, trustworthy?" — precisely over the things §11
+forbids `validate` from rejecting. It has its own report, never emits
+conformance errors, and **exits `0` even with findings** unless you pass
+`--fail-on warn` (exit 1 on any `warn` finding) or `--fail-on info` (exit 1 on
+any finding at all).
+
+**Severity is API.** Every check has a pinned level — `warn` or `info` — and
+machine consumers gate on it, so the levels below are stable, not advisory. A
+finding you want to gate on that is `info` gets `--fail-on info` (usually with
+`--only`), never a hope that its severity changes. <!-- rule:okf-severity-is-api -->
+
+Eight categories, each backed by individual checks (severity in brackets):
+
+- **Reachability** — `orphan` [warn], `not_in_index` [warn],
+  `disconnected_component` [info], `unlinked` [info]
+- **Backlog** — `missing_concept` [info], `broken_index_entry` [warn]
+- **Completeness** — `stub` [info], `missing_title` [info],
+  `missing_description` [info], `missing_generated` [info] (quiet on either
+  spelling — a legacy `timestamp` still counts as a recorded change)
+- **Freshness** — `expired` [info] (§5.5: past the concept's own declared
+  `stale_after`, on the day itself), `stale` [warn] (older than the
+  reader-supplied `--stale-after` cutoff, keyed on `generated_at`)
+- **Provenance** — `uncited_external` [info] (external body links and no
+  sources, in either spelling), `broken_source` [warn] (an in-bundle `.md`
+  source target that names no concept; URLs and scope descriptors are out of
+  scope, and a non-`.md` asset is out of reach — the reader models concepts,
+  so lint never sees the file; `okf references` is the view that checks those
+  pointers), `unattributed_claim` [warn] (a footnote
+  no `sources[].id` answers — it *misattributes* a claim, which is why it
+  outranks its join-twin), `unused_source` [info] (a keyed source no footnote
+  cites — slack, not a defect), `unprefixed_actor` [info] (a `verified[].by`
+  outside §7's three forms reads as machine-confirmed; a `generated.by`
+  outside them feeds no tier but leaves a reader unable to tell a person
+  from a process; info so it informs, never blocks). A missing `generated.by` is the *validator's* warning —
+  REQUIRED-within is shape, not curation — so lint never double-reports it
+- **Attestation** — `incomplete_computation` [warn] (an Attested Computation
+  providing its computation neither way, or both ways — §10.3 says a
+  `computation:` path is used *instead of* the body fence),
+  `broken_attestation_ref` [warn] (on an `Attested Computation`, a
+  `computation`, `executor.resource` or `attester.resource` naming an
+  in-bundle `.md` that is not there — a contract no consumer can follow; the
+  keys are read only on that type, since §4.1 lets any other concept use them
+  for its own purpose). Its reach is exactly the `.md` files: URLs are out
+  of scope, and a `.sql` or `.py` target is invisible to *every* check here,
+  because the linter reads the concept model and the model carries only
+  markdown — `okf references` is the surface that sees those files and reports
+  a pointer that misses, whatever the extension. Remember §6.2 reads a bare
+  `references/…` as relative to the concept, so from a nested concept it wants
+  the leading `/`
+- **Migration** — `legacy_timestamp` [info], `legacy_citations` [info]: one
+  finding per bundle naming the files still in a retired v0.1 spelling, with
+  the rewrite instructions in the message. Info on purpose — §13 says a v0.1
+  bundle is consumable forever, so `--fail-on warn` must not turn red on one.
+  A migration campaign gates explicitly:
+  `okf lint <dir> --only legacy_timestamp,legacy_citations --fail-on info`,
+  exit 1 until clean.
+- **Hygiene** — `duplicate_title` [info], `unused_reference_def` [info],
+  `undefined_reference` [warn], `self_link` [info], `log_order` [info] (§9
+  reads a log newest-first; disorder is slack, never a §11 error)
+
+`--only` / `--except` filter by the **individual check names above**, not the
+category labels — `okf lint <dir> --only orphan,stub` works; `--only reachability`
+is an error. Two knobs tune specific checks: `--min-body N` sets the `stub` body
+threshold in characters (default 50), and `--stale-after DUR` sets the `stale`
+cutoff — a duration like `90d` or `12w`, or an ISO date like `2026-01-01` (a bare
+number is rejected).
+
+**Two different clocks, one unlucky name.** The `--stale-after` *flag* and the
+`stale_after:` *frontmatter field* are different mechanisms that happen to share
+a spelling. The flag is the **reader's** age cutoff: "flag anything not touched
+since DUR", keyed on `generated_at`, feeding the `stale` check. The field is the
+**author's** declared expiry: "do not trust this past DATE", feeding the
+`expired` check. Never read one as the other, and never show them adjacent
+without the distinction. <!-- rule:okf-two-clocks -->
+
+**The clock is explicit.** `expired` compares against a day the CLI supplies —
+today by default, or `--today YYYY-MM-DD` for a reproducible report (CI wants
+this). The pure library runs no clock check unless handed `today:`, and every
+clock-gated check that was selected but could not run is *named* in
+`stats.skipped_checks` (the human report prints one `skipped:` line) — a gate
+that is sometimes absent and does not confess converts "unchecked" into
+"checked and fine".
+
+The report's stats carry the bundle's posture too: `trust` (the §5.3 tier
+distribution, in the hyphenated wire spelling) and `status` (effective-status
+frequency).
+
+`lint --json` is the structured substrate you consume to reason about the two
+things lint deliberately does **not** compute — contradictions and *semantic*
+staleness — which need understanding of meaning.
+
+## loose — files with no graph connections (by folder)
+
+Lists the **loose** files — concepts with graph **degree 0**: no cross-links in
+*or* out — grouped by folder. It is a focused, folder-organized view over `lint`'s
+`unlinked` check (`okf loose <dir>` ≈ `okf lint <dir> --only unlinked`, regrouped),
+for the "which files float in the graph?" question. Advisory: **exits `0`**; `--json`
+emits `{ bundle, count, loose: [{ id, title, dir }] }`.
+
+**Loose ≠ orphan** — the trap. `lint`'s `orphan` is about *reachability*, and an
+`index.md` listing makes a file reachable, so an indexed file is never an orphan.
+But an index listing is **not a graph edge**: a file can be listed in an index yet
+have no cross-links, so it floats in the graph while `lint` reports it as reachable.
+`loose`/`unlinked` catch exactly that gap. A loose file is not automatically a
+defect — a terminal leaf (a backlog item, a spec reference) can be loose by design;
+`loose` surfaces the set so you can judge intent (see the
+[maintain playbook](../../playbooks/maintain.md)).
+<!-- rule:okf-loose-not-orphan -->
+
+## references — the `references/` inventory (§6.3)
+
+Lists every file under `references/` — including the non-markdown ones no other
+verb can see, since the concept model carries only markdown — with which
+concepts cite each file through the §6.2 path-valued fields (`resource`,
+`sources[].resource`, `computation`, `executor.resource`, `attester.resource`),
+plus every pointer into `references/` that resolves to nothing. Advisory:
+**exits `0`** even with dangling pointers — the findings are the output. JSON:
+`{ bundle, dangling, count, references: [{ path, dir, kind, referenced_by }] }`,
+with `--fields`/`--except` projecting the rows. A file that is itself a concept
+(§6.3 allows both) is marked `kind: "concept"`; body links are the graph's
+business and are not counted here.
+
+**The dangling list is where §6.2's bare-path trap surfaces.** A bare
+`references/attesters/rev.py` written from `metrics/` resolves relative to the
+concept — `metrics/references/attesters/rev.py`, nothing — and when the
+leading-slash spelling would have hit, the entry says so:
+`/references/attesters/rev.py exists — missing leading slash?`. Reach is any
+extension, which is exactly what `broken_source` and `broken_attestation_ref`
+cannot offer (their exemptions above), so run it wherever a bundle carries
+attester code or computation files.
+

data/lib/okf/skill/reference/cli/graph.md

@@ -0,0 +1,49 @@
+# `graph` — the raw structure
+
+Kind: reference. Answers: what a full dump costs and how to plan a traversal
+without paying it, plus the two rankings that give `refine` its evidence —
+`--hubs` by concept, `--traffic` by directory.
+
+The shared contract — `@slug` refs, exit codes, `--json` — is in
+[cli.md](../cli.md) and is not repeated here.
+
+Prints the node/edge graph. `--json` emits a machine-readable dump — the
+`bundle`/`slug` head every view carries, then `nodes` (with
+`id`/`type`/`title`/`description`/`tags` **and, by default, every `body`** — the
+part that dominates the bytes on a real bundle) plus `edges` — you can pipe into
+other analysis. A concept with a missing *or blank* `type` indexes under
+`Untyped`: §11 condition 2 rejects both identically, so both land in one bucket. To *plan* a traversal, structure is all you need: `--no-body`
+drops each node's body, and `--minimal` ships only `id`/`title` plus the type/tag
+indexes — the lean shape the `server` page boots from. Reach for the full dump
+only when the task truly consumes every body; for one question, the
+[search verb](search.md) is orders cheaper.
+
+`--hubs` swaps the dump for the **inbound ranking**: every concept with at
+least one inbound link, ranked by inbound degree, each with its links grouped
+by *source top-level dir* (`core/status  ×3   flows 2, billing 1`) — the evidence for
+[refine](../../playbooks/refine.md)'s hub origin test ("is this hub well-homed?").
+A source at the bundle root counts under `(root)`. JSON: `{ bundle, count,
+hubs: [{ id, top_dir, inbound, by_top_dir: { <top_dir>: n } }] }`. Advisory read, exit 0;
+`--minimal`/`--no-body` shape node payloads and change nothing here.
+
+`--traffic` asks the same question one grain coarser: **directories**, not
+concepts. Every concept collapses into the directory it lives in and every link
+between two directories collapses into one weighted arc, so a bundle's wiring
+becomes a table you can read — measured on one 47-concept bundle, 227 links
+collapsed into 50 arcs, of which the fitted cut draws 22. Each row carries the
+directory's traffic split three ways
+(`internal` / `out` / `in`) plus **cohesion**, its internal share of the total:
+the evidence for [refine](../../playbooks/refine.md)'s container test, where
+`--hubs` only ever answered about concepts. Rows lead with the lowest cohesion,
+so the directories with a case to answer come first, and a directory with no
+traffic at all prints `—` rather than a `0%` it did not earn.
+
+`--cut N` is the least arc weight drawn. It defaults to a value **fitted to the
+bundle** — enough arcs for roughly 1.5 per directory, floored at 8 — because a
+fixed weight cannot serve both ends: measured at weight 3 across ten bundles it
+left 2 arcs on one and 136 on another. The JSON says which you got. Cohesion is
+computed over *every* arc and never the drawn ones, so tightening the cut
+changes the picture and never the evidence. JSON: `{ bundle, cut, fitted, dirs:
+[{ dir, parent, count, subtree, internal, out, in, cohesion }], arcs: [{ source,
+target, weight }], total_arcs }` — a fraction of the full dump (2.6 KB against
+27 KB on that bundle), and the shape rather than the contents. Advisory, exit 0.

data/lib/okf/skill/reference/cli/map.md

@@ -0,0 +1,98 @@
+# Orienting — `index` and `dirs`
+
+Kind: reference. Answers: which view to run first on a bundle you do not know,
+how `--dir`, `--depth` and the ancestor chain compose, what a synthesized
+listing means, and how to keep the map from paging the whole bundle.
+
+The shared contract — `@slug` refs, exit codes, `--json`, the filters — is in
+[cli.md](../cli.md) and is not repeated here.
+
+## index — the progressive-disclosure map (§8)
+
+The "orient before you read" view, and the read verb that sees the layer the
+concept views can't: `index.md` files are reserved/structural, so
+`catalog`/`files`/… never show them (in the browser, the Indexes tab and
+folder clicks render this same map). `okf index <dir>` prints one entry per directory
+that holds concepts or carries an `index.md`, root first — the authored index body
+(frontmatter stripped), a `type`/`tag` rollup over the concepts that live directly
+there, its child directories, and the concept listing. Run it first when picking up
+an existing bundle: it is the cheapest high-signal orientation, and it surfaces
+enumeration drift a grep can't (you can't grep for a listing entry that is *missing*).
+
+`--dir PATH` narrows to a directory **and everything below it**, and is
+**repeatable** — `--dir model --dir format` shows both; `root` (or `.`) names the
+bundle root, unless the bundle really has a `root/` directory, which owns the
+word. A `--dir` also brings the **chain from the root down to it**, so a branch is
+never shown adrift of the authored context that says what it is — the root
+`index.md`'s prose first among it. Those rows print with a leading `↑` and carry
+`ancestor: true`; `--no-ancestors` drops them. Ascent and descent are separate
+axes, so `--depth` never bounds the chain: `--dir X --depth 0` is X alone, plus
+how you get to X. A `--dir` that names nothing gains no chain — a lone root row
+would read as a partial answer to a query that matched nothing.
+
+`--depth N` bounds how far below the starting point the map reaches
+(the `--dir` when one is given, else the bundle root), counted **relatively**:
+`--depth 1` is the top of the tree, `--dir X --depth 1` is one branch of it, and
+the pair walks down a level at a time.
+
+**On a bundle of any size the map is unreadable whole** — every directory is a
+section, and even `--no-body` keeps one listing row per *concept* — so narrow
+rather than paging it: `okf dirs` is the orientation, `--dir <branch> --depth 1`
+is the step down into it,
+and `--except body,listing` on top of either is the lean JSON skeleton. Full
+`index` output on a few hundred concepts runs to hundreds of KB; the same map at
+`--depth 1` is a couple of KB.
+
+`--no-body` drops the prose to a
+skeleton (headers, rollups, child pointers). For a directory that has concepts but
+**no `index.md`**, the listing is **synthesized** from the concepts' descriptions
+and tagged `(no index.md)` — §8 explicitly permits synthesizing a map on the fly.
+
+It is a **read view**: advisory, always exit 0. A synthesized directory is a
+*signal* (a map worth writing), never a defect — `index` emits no lint findings and
+never fails a bundle. JSON: `{ bundle, count, directories: [{ dir, index_path,
+present, synthesized, count, types, tags, subdirs, body, listing: [{ id, title,
+description, type, tags }] }] }` — `ancestor` marks a row that is there to place
+the branch rather than to answer about it.
+
+## dirs — the bundle's clusters and their sizes
+
+`okf dirs <dir>` lists every directory the bundle has — the ones holding
+concepts, the ones carrying an `index.md`, and the empty intermediates that only
+exist to connect the tree — with the number of concepts living **directly** in
+each and the number in its **subtree**. A cluster *is* a directory here, so this
+is the view that tells you what `--dir` can be pointed at and how much sits
+behind each choice.
+
+Two numbers, because one cannot answer the question. `count` is direct, so the
+column sums to the bundle's concept total and a dir holding only sub-directories
+reads `0` rather than a hidden rollup. `subtree` is defined as *exactly what
+`--dir <that row>` returns*, so the row and the flag can never disagree — which
+is also why the root's subtree is its own direct count (`.` is a prefix of
+nothing). Without it a truncated listing is all zeroes at the top of a deep tree,
+which is where you most need to know where the mass is. The human table shows the
+second column only where some dir actually nests.
+
+`--dir PATH` (repeatable) narrows to a directory and its subtree, and brings the
+**chain up to the root** with it so the branch is placed rather than shown
+adrift — those rows are marked `↑`, carry `ancestor: true`, and stay out of
+`total` (`--no-ancestors` drops them). `--depth N` keeps only N levels below the
+starting point — the `--dir` when one is given,
+the bundle root otherwise. Relative, not absolute, so `--dir a/b --depth 1`
+reads "a/b and one level under it" without your first working out how deep `a/b`
+is. `--depth 0` is the starting point alone. A `--depth` that is not a whole
+number is a usage error (exit 2).
+
+**This is the first command to run on a bundle you do not know** — the same first
+move [SKILL.md](../../SKILL.md) prescribes. `okf dirs <dir>` is one row per
+directory, so its size tracks the tree rather than the concept count: it tells
+you the shape and where the weight sits, `--depth 1` trims it further on a deep
+bundle, and you then descend with `okf index --dir`, one level at a time.
+
+The root prints `(root)` and stores `.` — the split every grouped view keeps, so
+a table and its `--json` never disagree about which spelling is the data. JSON:
+`{ bundle, total, count, dirs: [{ dir, ancestor, count, subtree, subdirs }] }`,
+root first. `count` is rows printed, chain included; `total` sums the direct
+counts of the rows you actually asked for, which is what keeps a row's `subtree`
+equal to the `total` that `--dir` on that row returns.
+

data/lib/okf/skill/reference/cli/registry.md

@@ -0,0 +1,70 @@
+# `registry` — naming bundles once
+
+Kind: reference. Answers: which file a registry op writes and how okf finds it,
+which verbs key on a path and which on a slug, what a group is and which two
+verbs consume one, and why the default is a position rather than a stored slug.
+
+The *persistent registry* is a plain JSON file under `$OKF_HOME` (default
+`~/.okf`), managed by the `okf registry` umbrella — like git's `remote` family,
+and split by what each verb keys on. It is what every `@slug` resolves through
+([cli.md](../cli.md)) and what a bundle-less `okf server` hosts
+([serve.md](serve.md)).
+
+**`okf registry init`** creates a *project-local* registry instead: a
+`.okf-registry.json` in the current directory, which okf discovers by walking up
+from the working directory and uses in place of the global one while you are
+inside its tree (the nearest wins, so nested registries resolve nearest-first).
+Every registry op — and every `@slug` — then resolves through it, so a bare
+`okf server` inside a repo serves that repo's bundles with no `$OKF_HOME` setup;
+`okf registry list` names the local file it found. `OKF_NO_DISCOVERY=1` forces
+the global registry — the escape hatch for a fixed-cwd caller (CI, a tool). A
+local registry stores **portable** paths: a bundle inside its tree is written
+relative to the `.okf-registry.json`, so committing the file lets it travel with
+the repo (a checkout elsewhere, a container mounting it) and resolve unchanged;
+a bundle outside the tree stays absolute, since it cannot travel. Paths still read
+back absolute wherever the CLI reports them.
+**Entry verbs** take a path: `okf registry set <dir>` adds it
+(slug from the basename, or `--as`, which errors on a collision; `--default`
+puts it first), and because the entry is keyed by path, `set` on an
+already-registered dir updates it in place — refreshing its title, and renaming
+it when `--as` is given. `okf registry del <dir|@slug>` removes a bundle *or* a group — by name, so an
+entry whose directory is already gone still deletes, and removing a bundle
+**cascade-drops** it from every group that named it (a group emptied that way is
+deleted). Slug *or* dir, never both readings at
+once: an argument with a `/` in it names a location and only a location, so
+`del ./notes` refuses when no entry points there rather than stripping to the
+slug `notes` and deleting a bundle somewhere else entirely.
+<!-- rule:okf-registry-del-path-or-slug -->
+**Slug verbs** take the name — bare, or as an `@slug`: `okf registry default <@slug>`
+chooses which bundle `/` opens **by moving that entry to the front** (a group is
+refused — the default is one bundle), and
+`okf registry rename <@slug> <new>` renames a bundle *or* group slug (mount path
+and switcher name), **cascading** the new name into every group's member list —
+`<new>` is a name being minted, so it is never a ref. The registry is ordered and **the first entry still on disk is the
+default** — that is the whole rule, so the first bundle you register is the
+default until you move another one, a rename keeps its position, and a `del`
+promotes whatever is next. A vanished directory is stepped over (the server
+cannot open one, so starring it would name a bundle `/` never serves), and
+`registry default @slug` refuses one outright — the same refusal `registry set`
+gives a directory that is not there. The file is hand-editable and reorders
+visibly, which is the point: there is no stored slug that can dangle.
+<!-- rule:okf-registry-default-position -->
+**Group verbs** name a *set* of bundles under one slug — a durable subset for the
+two verbs that take several bundles. `okf registry group <slug> <@member…>`
+creates a group, or adds members to one (a union); members are bundle *or* group
+slugs, so groups nest. A group shares the slug namespace with bundles (a slug
+names one *or* the other, never both), `all` stays reserved, and a member set that
+would make the group reach itself is refused. `okf registry ungroup <slug>
+<@member…>` removes members; emptying a group deletes it. A group resolves,
+recursively and path-deduped, to its bundle leaves — which **only `okf search`
+and `okf server` consume**: every single-bundle verb (`lint`, `index`, …) refuses
+a `@group` with exit 2, the same rule that refuses a second bundle. `@all` is
+unchanged — it still names every registered *bundle*, groups being named subsets
+of that.
+`okf registry list` (or a bare
+`okf registry`) stars the default and flags vanished dirs `(missing)` — the
+server skips those with a note — and lists any groups with their members and
+resolved leaf count; `--json` answers
+`{ registry: <file>, count, bundles: [{ slug, title, dir, mount, default,
+missing }], groups: [{ slug, members, resolved }] }`, naming the file it read so a
+`$OKF_HOME` mismatch is visible.

data/lib/okf/skill/reference/cli/search.md

@@ -0,0 +1,130 @@
+# `search` — ranked text retrieval (metadata + body)
+
+Kind: reference. Answers: how terms are matched and by which engine, what the
+index buys and what it silently loses, how one query spans several bundles, and
+which of the two JSON envelopes comes back.
+
+The shared contract — `@slug` refs, exit codes, `--json`, the filters this verb
+also takes — is in [cli.md](../cli.md) and is not repeated here.
+
+The browser page's search brought to the CLI and extended to bodies, so "which
+concept covers X?" costs rows, not body reads. `okf search <dir> <term…>`:
+terms AND together — every term must hit at least one searched field, not
+necessarily the same one — matched **literally against raw text** by default, or
+as Ruby regular expressions with `--regexp`/`-e` (an invalid pattern is a usage
+error, exit 2). `--fuzzy` forgives typos; pairing it with `-e` is a usage error,
+since a pattern is matched literally rather than by edit distance.
+`--in a,b` restricts the searched fields (title, id, tags, type, description,
+sources, body — `sources` is each entry's title and resource joined, so a
+migrated bundle keeps the recall its `# Citations` body text used to give it);
+the shared `--type/--dir/--tag/--status/--trust` filters narrow the candidates
+*first*, so a search scoped by what `index` taught you stays surgical.
+
+**The default is exact, so an exact query means what it looks like.** A phrase in
+one argument (`"dedup key"`), a dotted version (`7.2.0`), an underscored
+identifier (`customer_id`), a mid-word fragment (`ustomer`) and a word written in
+`backticks` all match literally. This is what the scan engine buys, and it is the
+default precisely because those queries are the common ones and the alternative
+loses them silently. <!-- rule:okf-search-exact-identifiers -->
+
+**`--engine index` is the other engine, and the one to reach for when ranking
+matters more than exactness.** The engine is normally chosen by what the query
+needs — `--fuzzy` routes to the index, anything else stays on the default scan —
+and nothing is printed about the choice. `--engine NAME` overrides that for the
+case the flags cannot express: a matching *model* requires no capability, so no
+flag selects one. Under the index, terms match whole tokens and their prefixes
+(`dedup` finds `deduplication`), rows rank by BM25+, and it is the engine the
+browser page runs — so name it when reconciling a CLI answer with the page. The
+cost is real: its tokenizer splits on punctuation, so identifiers shatter
+(`customer_id` → `customer` + `id`), an infix finds nothing, and a backtick is
+never split off at all, so a word inside a code span is unfindable — a large
+silent loss, since technical prose is full of them. **Do not count on ranking to
+rescue it** — BM25 normalizes by field length, so a short concept dense in `7`,
+`2` and `0` can outrank the one that actually says `7.2.0`. Naming an engine that
+cannot do what you also asked (`--engine index -e`) is a usage error naming one
+that can. <!-- rule:okf-search-engine-choice -->
+
+**The capabilities, and which engine has them.** An engine is selected by what
+the query *requires*; only a matching model has to be named, because requiring
+nothing is not something a flag can express:
+
+| Flag | Capability | Engine | What it does |
+|---|---|---|---|
+| *(none)* | — | scan | literal substring over raw text; scores by summed field weight |
+| `-e` / `--regexp` | `regexp` | scan | each term is a Ruby regexp, case-insensitive; invalid → exit 2 |
+| `--fuzzy` | `fuzzy` | **index** | edit distance 0.2 × term length — and switches engine |
+| `--engine index` | — | index | whole-token + prefix matching, BM25+ ranking, browser parity |
+| `--engine scan` | — | scan | the default, spelled out |
+
+Two consequences worth holding. **`--fuzzy` is an engine switch, not a mode**: it
+carries the whole index with it, so a run that wanted one typo forgiven also gets
+shattered identifiers and unfindable code spans — fix the spelling and stay on
+the default when you can. And **`-e` moves nothing** now, because the default
+engine already offers `regexp`; it changes how a term is *read* (pattern rather
+than literal), not where it is matched. <!-- rule:okf-search-fuzzy-is-a-switch -->
+
+`prefix` is a capability the index declares but no flag selects — it is always on
+there. **It is not a reason to reach for the index**: a substring match already
+covers every prefix and then some, so `dedup` finds `deduplication` under both
+engines, while `duplication` and `uplicat` find it under the default only. Prefix
+is what the index needs to catch up to raw text, not a capability it adds on top.
+The index's real advantages over the default are exactly three — relevance
+ranking, typo tolerance, and page parity.
+
+**Search spans bundles.** Leading @refs pick several registered bundles
+(`okf search @handbook @notes auth`); **`@all`** is the ref that means every one.
+Rows from different bundles are ranked together and comparable, and each row
+carries its bundle's slug. Under `--engine index` the bundles go into **one
+corpus** — BM25 prices a term by how rare it is, so separately-ranked lists would
+not compare — which makes a score relative to the whole answer: the same concept
+scores lower searched beside others than searched alone. The default scan needs
+no such trick — its score is absolute, so a row is worth the same either way.
+This is the
+cross-bundle retrieval the in-page search does not have: one question, every
+bundle you keep. <!-- rule:okf-search-all -->
+
+`@all` is a ref, not a flag, which is what keeps the grammar single: slot 1 is
+always a bundle identity, so a directory there is a directory and nothing can
+flip it into a term. Being a ref, it is normalized like one — `@ALL` and `@All`
+name every bundle just as `@One` names the bundle registered from dir `One`. It composes accordingly — `@all @docs` expands and dedupes
+(all ⊇ docs), needing no diagnostic. **Asking for everything tolerates gaps;
+naming one bundle demands it**: `@all` skips a bundle whose directory has
+vanished with a note on stderr, while `@docs` fails hard. `@all` is only
+`search`'s: every other verb answers about one bundle, so it refuses `@all` by
+name rather than letting the answer depend on how many bundles you happen to
+have registered. `all` is reserved as a slug — a directory named `all/` registers
+as `all-2`, `--as all` is refused, and an `all` row already in the registry file
+(hand-typed, or written before the name was reserved) is read as `all-2` rather
+than taken as grounds to reject the file — so `@all` is never ambiguous, and the
+reservation never strands a registry it inherited. **The read normalizes every
+slug** the same way registration would, so a hand-typed `"slug": "My Docs"` lists
+and resolves as `my-docs`; an entry the listing shows is always an entry `@slug`,
+`rename`, and `default` can name.
+
+`--fields` projects the shape the mode actually emits: `slug` is available in
+registry mode, and a usage error naming the real fields on a path-named search,
+which has no slug to give. Two sharp edges: every *leading* @-arg is taken as a ref, so a literal @-term
+(`@babel/core`, a Ruby `@ivar`) needs a non-@ term before it or `-e '\@term'` —
+the CLI notes both traps on stderr — and any ref, even one, switches the JSON
+envelope (next paragraph).
+
+Rows rank by where they hit — title 5, id 4, tags 3, type/description 2, body 1 —
+summed as an absolute score by the default scan, and carried as per-field boost
+into **BM25+** under `--engine index`. Each row carries one bounded context
+snippet from the strongest match that needs context (description or body). Every row still names the fields that hit (`matched`), so a result stays
+citable rather than being a bare relevance number. Exact by default: the
+consuming agent is the fuzzy layer — when terms miss, learn the bundle's
+vocabulary from `tags`/`types` and re-ask in its own words, rather than
+hammering synonyms or reaching for `--fuzzy` before you have looked. Advisory read: **exit 0 even with zero matches**.
+JSON, plain-dir mode: `{ bundle, query, count, matches: [{ id, title, type,
+dir, top_dir, tags, matched, score, snippet }] }`. Registry mode — any leading @ref,
+`@all` or a `@group` among them (a group fans out to its member bundles) — swaps the envelope: `{ bundles: [{ slug, dir }, …],
+query, count, matches: [{ slug, id, … }] }`; a parser must branch on which form
+it called. The head maps each slug to its dir once, so a row resolves to
+`<dir>/<id>.md` without a second lookup and without repeating a path per row.
+Both are projectable with `--fields/--except`, and projection is literal — when
+merging bundles, put `slug` in your `--fields` list or the row label drops and
+same-id concepts from different bundles become indistinguishable. The retrieval procedure that puts this verb in sequence —
+map first, finder second, bodies last — is the
+[search playbook](../../playbooks/search.md).
+

data/lib/okf/skill/reference/cli/serve.md

@@ -0,0 +1,83 @@
+# Serving the graph — `server` and `render`
+
+Kind: reference. Answers: what the interactive page shows and what it fetches
+live, how several bundles mount behind one hub, what the static export trades
+away, and the trust boundary both modes share.
+
+The shared contract — `@slug` refs, exit codes, `--json` — is in
+[cli.md](../cli.md) and is not repeated here.
+
+## server — interactive graph server
+
+Starts a local HTTP server (`okf server <dir>`; `-p`/`--port`, default 8808, and
+`--bind`) and prints its URL — stop it with Ctrl-C. The page boots from a lean
+payload (nodes carry only `id` and `title`, plus compact type/tag indexes) and
+fetches each concept's markdown body **live from disk** as you click it, so the
+initial load stays small and edits show without a restart. Mermaid code blocks
+in a body render as diagrams, and a click (or tap) opens the diagram full
+screen with drag-to-pan and wheel/pinch zoom. Concepts render as nodes
+coloured by `type` and sized by degree, links as edges, with a detail panel
+(rendered markdown, "Links to" / "Linked from" backlinks), layout switching,
+type/dir/tag filters on every view (the dir chips take a directory *and* its
+subtree, the same rule `--dir` uses), and search. Cluster mode groups the
+concepts into one box per directory, nested to a depth picked beside the layout
+select — depth 1 is the flat view, and a flat bundle is offered no control. The authored layer is in the
+UI too: the Files view carries **Files | Indexes** tabs — the Indexes tab
+lists the log first (the chronological index), then every `index.md` — and
+folder nodes in file-tree mode and directory boxes in cluster mode open a
+directory's §8 map in the inspector (authored, or synthesized when none
+exists). Links to an `index.md`, `log.md`, or bare directory navigate instead
+of dead-ending, and the log is fetched fresh on every read, so a
+just-appended entry shows without a restart. `?view=index` jumps straight to
+the Indexes tab. It is a Rack app, so the same server can be mounted in a
+host app (e.g. Rails).
+
+**Hosting many bundles (the hub).** `okf server` takes zero or more dirs.
+One dir is the classic single bundle at `/`. Two or more mounts each under
+`/b/<slug>/` behind a hub, `/` redirects to the default, and `/b/` is a
+self-contained **bundle index** (every hosted bundle, concept counts, default
+marked — the browser counterpart of `okf registry`). An unknown slug 404s as a
+page listing the hosted bundles, so a stale bookmark after a rename gets a way
+home. With **no** dir it serves the *persistent registry*. The hub roster is a
+**boot-time snapshot**: restart `okf server` after registry changes. Behind a
+hub the page gains a **bundle switcher** (⌘/Ctrl-K, or the rail button with its
+bundle-count badge): the current bundle is pinned, the default chipped; ⏎
+opens, ⌘/Ctrl-⏎ opens a new tab, and the current view carries over. Switching
+is a server-only affordance — a static `render` file has no siblings and shows
+none.
+
+**Bundle-less run.** Register bundles once, then `okf server` (no dir) hosts
+them all with the registry's first entry still on disk at `/` — the way to keep
+several bundles a keystroke apart without re-passing paths.
+`okf server @a @b` serves a registry subset, each mounted under its registered
+slug — but as with any dirs-given run, the *first argument* lands at `/`; the
+registry's own order applies only to the bundle-less run. A `@group` argument
+fans out to its member bundles in the same way (`okf server @backend`), its first
+member landing at `/`; `okf search @group <term…>` merges the group's members
+into one ranking, exactly as naming them individually would.
+The registry itself — the file it reads, how okf finds it, and the verbs that
+write it — is in [registry.md](registry.md).
+
+**Trust boundary:** the page renders each fetched markdown body through
+DOMPurify and escapes everything it inlines (every `<` in the graph data is
+escaped, so it cannot break out of its `<script>`), but it still loads its
+viewer libraries (Cytoscape, marked, DOMPurify — plus Mermaid and Panzoom,
+lazy-loaded on first use) from a CDN and renders whatever
+links the bundle carries — so only serve bundles you trust.
+## render — static graph export
+
+Writes the same interactive page as one static, self-contained HTML file
+(`okf render <dir>`), so the graph hosts where there is no server — GitHub Pages,
+an object store, an attachment. Prints to stdout (`okf render <dir> > graph.html`)
+or writes `-o FILE`; `--title`/`--link`/`--layout` mirror `server`. It is the same
+template `server` renders, one switch apart: rather than fetching each body,
+description, catalog, index, and log live, `render` bakes the whole bundle into
+the page and the browser reads from that embedded payload — no server, no build
+step. The trade-off is weight (every body is inlined), so `server` stays the
+choice for a bundle too large to ship whole.
+
+**Trust boundary:** the same two guards as `server` — every inlined body is
+`</script>`-escaped like the graph data and still sanitized by DOMPurify when
+rendered — so a static file is no laxer than the live server. Only render bundles
+you trust.
+