okf 2.1.0 → 2.2.0

data/.okf/capabilities/search.md

@@ -0,0 +1,297 @@
+---
+type: Capability
+title: Ranked text search (search)
+description: Full-text retrieval over concept metadata and bodies — raw-text matching by default, BM25+ token ranking on request, and explainable row by row either way.
+resource: gems/okf/lib/okf/bundle/search.rb
+tags: [read, cli, json, registry, search]
+generated:
+  by: human:maintainer
+  at: 2026-08-13T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/bundle/search.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/bundle/search.rb
+  - title: gems/okf/test/integration/cli/by_dir/cli_search_test.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/test/integration/cli/by_dir/cli_search_test.rb
+  - title: gems/okf/test/unit/bundle/search/recall_test.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/test/unit/bundle/search/recall_test.rb
+---
+
+# Overview
+
+`okf search <dir> <term…>` answers "which concept covers X?" for the price of a
+few rows instead of a body read. The [browser page](graph-server.md) already had
+search; this brings it to the [CLI](../cli.md) — the agent's eyes — and goes
+further by searching bodies too. The core is `OKF::Bundle::Search`, a pure class
+(guarded by the [core/shell boundary](../design/core-shell-split.md)) over the
+in-memory [bundle](../model/bundle.md), so the CLI and any embedding app share
+it: `OKF::Bundle::Search.call(bundle, [ "dedup", "key" ])`.
+
+It is a **facade over two engines**. The default is a linear scan over raw text;
+`--engine index` (and `--fuzzy`, which implies it) reaches a
+[`minifts`](../design/runtime-dependencies.md) full-text index — the pure-Ruby
+port of the MiniSearch build the browser loads, so a Ruby-built index and the
+page's rank identically by construction rather than by two implementations
+agreeing for as long as someone maintains both.
+
+# Why the scan is the default
+
+A CLI process loads the bundle, asks one question, and exits. An index build has
+exactly one query to amortize it over, and it is not close:
+
+| concepts | `--engine index` | default (scan) |
+|---|---|---|
+| 24 | 0.16 s | 0.10 s |
+| 250 | 0.83 s | 0.18 s |
+| 1,000 | 3.00 s | 0.24 s |
+
+End to end through the CLI, 2026-07-18, Ruby 4.0.5. The build is ~95% of the
+index path's cost at every size, and the gap widens with the bundle.
+
+The headline number points the other way — `minifts` sustains
+[~44–56× the query throughput](https://github.com/serradura/minifts) of a scan —
+and that is the right measure for a **long-lived** index (a browser page, a
+server) and the wrong one for a one-shot process. So the arithmetic above governs
+the CLI only, and the server takes the other branch.
+
+# The server holds the index, the CLI cannot
+
+`Search.prepare` builds a **Corpus** — the documents, the key → concept map, and
+the built index — and `Search.with` queries it without rebuilding. That is the
+whole difference between the two callers: `okf server` prepares one at boot
+(`warm_search`), so the build lands in startup where it is attributable, and
+every search after it is a query alone.
+
+| 414 concepts, served | before | after |
+|---|---|---|
+| boot | — | 1.39 s (once) |
+| each search | 1.45 s | 0.016 – 0.052 s |
+
+Measured 2026-07-22 through the Rack app, Ruby 4.0.5. Flat before, because each
+request rebuilt the corpus it had just thrown away.
+
+The cost is staleness: a corpus is a **snapshot**, so a body edited after it was
+built is searchable only once the holder drops it — the hub does exactly that
+when a registry write changes the served set. The graph is memoized on the same
+terms, so this is the boundary the server already had, not a new one.
+
+The CLI still builds per call and still defaults to the scan: a one-shot process
+has nothing to amortize over, which is the asymmetry this whole section is about.
+
+Speed is not the only reason. Raw-text matching has **no tokenizer**, so it has
+no tokenizer-shaped recall holes — see below.
+
+# Matching and ranking
+
+Terms **AND** together: every term must hit at least one searched field, though
+not necessarily the same one. Field weights are shared by both engines:
+
+| Field | Weight |
+|-------|-------|
+| `title` | 5 |
+| `id` | 4 |
+| `tags` | 3 |
+| `type`, `description` | 2 |
+| `sources`, `body` | 1 |
+
+The **scan** matches a term as a literal substring anywhere in a field and scores
+by summing the weights of the fields that matched — an absolute number, small and
+integral. The **index** matches a whole token or a token it prefixes (`dedup`
+reaches `deduplication`), and scores BM25+ with those weights riding as per-field
+boost — a float, relative to the corpus.
+
+Rows order by score descending, then slug, then id. A match in `description`,
+`body` or `sources` carries one bounded context snippet (~44 characters each
+side of the first matched term); the other fields need none because they
+already appear whole on the row. `sources` is each entry's title and resource
+joined, at the weight the `# Citations` body text carried in v0.1, so a
+migrated bundle keeps its recall and a source-only hit keeps a snippet — the
+snippet *moves* from body text to source text rather than vanishing.
+
+The pages share the fields with one pinned asymmetry: the **static** page bakes
+each concept's body and source text and indexes both offline; the **served**
+page indexes metadata only — its catalog row carries a source *count*, and
+spending body-sized bytes on every fetch to serve one view is the trade the
+payload already refuses for `body`. Pre-existing, deliberate, and stated at
+`FT_FIELDS` in the template rather than discovered.
+
+**The row still says which fields hit.** A relevance number alone would be a
+verdict an agent cannot check, so every row carries its `matched` list — read off
+the engine's own per-term field record, not recomputed beside it.
+
+# What the index gives up, and why it is opt-in
+
+Everything a token index cannot represent is something the tokenizer already
+split or normalized away. These are the reasons the scan leads:
+
+| Query | Default (scan) | `--engine index` |
+|---|---|---|
+| `"dedup key"` as one argument | contiguous only | two tokens ANDed — matches words paragraphs apart |
+| `7.2.0` | one string | tokens `7`, `2`, `0` — matches "0 downtime, 7 regions, 2 zones" |
+| `customer_id` | the identifier, whole | `customer` + `id` — matches "the customer table has an id column" |
+| `ustomer` | finds Customers | nothing: an infix is not a token |
+| `minifts` | **5** concepts | 2 — three write it only as `` `minifts` `` |
+| `json_for_script` | **4** | 1 |
+
+Measured on this bundle, 2026-07-18. The tokenizer splits on whitespace **and
+punctuation**, which is why a dot and an underscore both shatter an identifier.
+The last two rows are a different fault: a backtick is Unicode `Sk` and `$` is
+`Sc`, neither of which is `P`, so **neither is ever split off**. A word inside a
+code span is stored as the token `` `minifts` ``, which the query `minifts` does
+not match — 409 such tokens on this bundle, 1,013 occurrences.
+
+That class of loss is invisible: the search succeeds, returns plausible rows, and
+silently omits most of the answer. Making raw text the default is what removed it
+from the path nobody opted into.
+
+**Ranking does not contain the loss.** This capability once claimed the true hit
+still ranks first, so the cost was only extra rows below the answer. That is
+false, and the pinning tests found it: BM25 normalizes by field length, so a short
+body dense in `7`, `2` and `0` outscores the concept that actually says `7.2.0`.
+On this bundle, `okf search .okf 7.2.0 --engine index` ranks
+[the Ruby floor](../design/ruby-floor.md) — a page full of `2.4`, `2.6`, `3.x` —
+**above** [the graph server](graph-server.md), the one concept naming the version.
+
+# What the index buys
+
+Reaching for it is a real choice, not a legacy path:
+
+- **BM25+ ranking.** Corpus-relative relevance, which absolute field weights only
+  approximate. On a large or uneven bundle this is the better ordering.
+- **Fuzzy matching.** `--fuzzy` is only available here — the scan has no notion
+  of edit distance, so asking for it routes automatically.
+- **Parity with the browser page**, which runs the same MiniSearch build. If you
+  are reconciling a CLI answer with what the page shows, name the index.
+
+That is the whole list — three things. The `prefix` capability is conspicuously
+**not** a fourth, though the index declares it: a substring match already reaches
+every prefix, so `dedup` finds `deduplication` under either engine while
+`duplication` and `uplicat` find it under the scan alone. Prefix is what a token
+index needs to catch up to raw text, not something it adds on top. Worth stating
+plainly, because "prefix matching" reads like a feature the default lacks.
+
+# Engines are adapters, chosen by what the query needs
+
+`OKF::Bundle::Search` is a facade over N engines, not one implementation with a
+branch. It owns everything that defines what a *result* is — documents, the row
+and its key order, the snippet window, the final sort — and delegates only "which
+documents match, how well, and where":
+
+| Engine | Capabilities | Scoring |
+|---|---|---|
+| `Search::Scan` (default) | `regexp` | summed field weights, absolute |
+| `Search::Index` | `fuzzy`, `prefix` | BM25+, corpus-relative |
+
+Selection happens two ways, and they answer different questions.
+
+**By capability**, when the query requires something: `--fuzzy` requires `:fuzzy`,
+which only the index offers, so it routes there without naming it. `-e` requires
+`:regexp`, which the default already provides, so it moves nothing. A query
+requiring nothing gets the default. Routing is **silent** — no note on stderr,
+nothing in the header, nothing in the JSON envelope.
+
+**By name**, with `--engine`, when the query requires nothing but the *matching
+model* matters. This is the case capability flags cannot express: BM25 ranking
+requires no capability, so there is nothing to route on. A named engine that
+cannot do what was *also* asked is an error, never a silent fallback:
+
+```
+okf search . --engine index -e 'err_[a-z]+'   # error: --engine index does not
+                                              # support --regexp (try --engine scan)
+okf search . --engine fts5 auth               # error: unknown search engine: fts5
+                                              # (available: index, scan)
+```
+
+The two readings of a term stay separate from the engine that reads them: the
+scan matches **literally** and `-e` opts into the pattern reading, so `7.2.0`
+does not match `7x2y0` and `[draft]` is not a character class unless you said so.
+Note the edge: `-e` is a *pattern* language, so the literal wants `-e '7\.2\.0'`.
+
+`Search.register` is the seam an addon plugs into — the second base-gem extension
+point, deliberately shaped like the linter's — and
+[the engine contract](../design/search-engines.md) is what keeps a registered
+engine from redefining what a match is. `--engine` reads the registry at parse
+time, so an addon appears in `okf search --help` without the CLI knowing it exists.
+
+# It composes with the shared CLI surface
+
+`--in FIELDS` restricts the searched fields; the `--type`/`--dir`/`--tag`
+filters and `--fields`/`--except` projections shared with the
+[read views](read-views.md) apply unchanged. It is an advisory read: exit `0`
+even with zero matches — only an invalid `--regexp` pattern, `-e` paired with
+`--fuzzy`, or an `--engine` that cannot honour a flag, is a usage error (exit `2`).
+
+# One question, every bundle you keep
+
+Knowledge rarely lives in one bundle, so search is the one verb that spans the
+[registry](../registry.md): leading @slugs pick bundles explicitly
+(`okf search @handbook @notes auth`), and `@all` is the ref that means every
+registered one — including the bundles a [link](../registry.md) folds in, since
+those are registered here in every sense that matters to a reader looking for an
+answer. Every row is labeled by its bundle's slug.
+
+**Merged rows are comparable by construction, and each engine earns that
+differently.** The scan's score is absolute — summed field weights, with no
+corpus term to move — so a row is worth exactly the same alone or beside two
+other bundles. The index has no such luxury: BM25 prices a term by how rare it
+is, so the bundles go into **one** index rather than N. A per-bundle index would
+score the same match differently depending on where it came from, and
+interleaving those lists would produce a ranking that looks sorted and compares
+nothing. The visible consequence, under `--engine index` only, is that a score is
+relative to the whole answer: the same concept is worth less searched beside two
+other bundles than alone, because the term got commoner.
+
+The graph stays per-bundle on purpose — cross-links are bundle-relative, so a
+merged graph would be disconnected components — which makes search the one
+cross-bundle question the CLI can answer honestly, and (for now) a capability the
+[hub](graph-server.md) does not mirror.
+
+**Asking for everything tolerates gaps; naming one bundle demands it.** `@all`
+skips a registered bundle whose directory has vanished, with a note — the same
+forgiveness the hub shows a stale entry — while `@handbook` fails hard, because
+an explicit ask that silently answered about less than it named would be a
+confident wrong answer. `@all @handbook` needs no diagnostic at all: all ⊇
+handbook, so it expands, dedupes by resolved path, and answers.
+
+That "every bundle" is a **ref rather than a flag** is what keeps the grammar
+single, and it was not always so. A `--all` flag *reinterpreted the
+positionals* — `okf search .okf home` read `.okf` as the bundle, `okf search
+--all .okf` read it as a term — the same slot meaning opposite things, decided
+by a flag optparse accepts anywhere in argv. Every diagnostic around it existed
+to explain that flip. As a ref, slot 1 is always a bundle identity: a directory
+there is a directory, a term after it is a term, and the explanations have
+nothing left to explain. Being a ref also means being normalized like one:
+`@ALL` reaches `@all` through the same `Registry.normalize` that makes `@One`
+find dir `One`, because a ref exempt from the grammar's one normalization is a
+trapdoor. Only `search` expands `@all`, since it is the only verb
+that merges; see [the CLI](../cli.md) for why the others refuse it by name.
+
+Three edges of the grammar, all deliberate. Any leading @-arg — even one —
+switches the JSON envelope from `{ bundle, slug, … }` to
+`{ bundles: [{ slug, dir }, …], …, matches: [{ slug, id, … }] }`, so a consumer
+branches on the form it called; the head maps each slug to its dir once, which
+is what lets a row resolve to `<dir>/<id>.md` without a second lookup while
+keeping long paths off every row. Projection is literal: when merging, put
+`slug` in `--fields` or the row label drops and same-id concepts from
+different bundles become indistinguishable. And every leading @-arg is taken
+as a ref, so a literal @-term (`@babel/core`) needs a non-@ term before it or
+`-e '\@term'` — the CLI notes each of these traps on stderr when it sees one.
+
+# Exact by default, fuzzy on request
+
+No stemming, no synonyms, and no typo distance **unless asked**: `--fuzzy` turns
+on an edit distance of `0.2 × term length`, the same tolerance the browser page
+passes. The default stays exact because determinism is what keeps a result
+citable — the consuming agent is the fuzzy layer, since synonyms and vocabulary
+drift are judgment over the index map, not string distance.
+
+Worth knowing when you reach for it: `--fuzzy` is not merely a mode, it is an
+**engine switch**. It routes to the index, so everything on this page about token
+matching applies to that run — including the recall holes. A typo forgiven and an
+identifier shattered arrive together.
+
+# The retrieval eval keeps the economics honest
+
+The suite plants a fact in a fixture bundle and asserts that the progressive
+path — index skeleton, one search, one body — answers it in **under 25% of the
+bytes** of the full graph dump. The [companion skill](agent-skill.md)'s search
+playbook rides that path, so its economics stay true by construction.

data/.okf/capabilities/validator.md

@@ -0,0 +1,60 @@
+---
+type: Capability
+title: Conformance validator (validate)
+description: Implements the spec's §11 conformance definition exactly — three hard conditions, everything else a machine-readable warning.
+resource: gems/okf/lib/okf/bundle/validator.rb
+tags: [conformance, cli]
+generated:
+  by: human:maintainer
+  at: 2026-08-13T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/bundle/validator.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/bundle/validator.rb
+---
+
+# Overview
+
+`okf validate` answers one question: *is this a legal OKF (`@okf-eco format/okf-format`)
+bundle?* `OKF::Bundle::Validator` implements §11 exactly and is the **only**
+capability that can fail a bundle — exit `1` on any hard error, `0` otherwise.
+
+# The three hard conditions (errors)
+
+| Rule | Condition |
+|------|-----------|
+| §11 cond. 1 | every non-reserved file can be **read** and has a parseable frontmatter (`@okf-eco format/frontmatter`) block |
+| §11 cond. 2 | every such block has a **non-empty `type`** |
+| §11 cond. 3 | every `index.md` / `log.md` present is well-formed (nested index has no frontmatter, root index carries only `okf_version`, log dates are real ISO calendar days — `2026-02-30` matches the shape and is refused) |
+
+A file that will not **open** fails condition 1 too, not only one whose frontmatter will
+not parse: the reader keeps it in [`bundle.unparseable`](../model/bundle.md) with
+its errno rather than letting one locked file abort the read, and `validate`
+reports it there — one unusable file counted as one, named with why.
+
+# Everything else is a warning
+
+The validator is **forbidden by §11** from rejecting a bundle for soft issues, so
+these are warnings that never change conformance:
+
+- missing recommended fields, non-list `tags`, an unparseable `timestamp`;
+- the shape of every §5/§10 family — `generated` not a mapping or missing `by`,
+  a non-integer `usage_count`, a `stale_after` that is not `YYYY-MM-DD`, a
+  missing `runtime` on an Attested Computation — read off the raw keys, never
+  the fallback-carrying accessors, so a pure v0.1 bundle validates silently;
+- an `okf_version` the gem does not know (read best-effort under §12, compared
+  after `to_s.strip` because an unquoted `0.2` is a Psych Float);
+- **broken cross-links (`@okf-eco format/cross-links`)** (§6.1) — consumers MUST
+  tolerate them.
+
+Judging those is the [linter](linter.md)'s job, and keeping the two apart is a
+[hard design contract](../design/core-shell-split.md). The
+[writer](library-api.md) runs this validator *before* publishing, so a saved
+bundle is never written non-conformant.
+
+# Warnings are machine-readable
+
+Every warning carries `check:` (a stable id) and `source:` — `:spec` when the
+SPEC's own words state the rule, `:convention` for the shapes this gem asks for
+beyond them (a tested constant pins the set). A consumer that wants only the
+spec-normative warnings filters on `source` instead of string-matching
+messages; errors keep their exact two-key `{ path, message }` shape.

data/.okf/cli.md

@@ -0,0 +1,214 @@
+---
+type: Component
+title: The okf command-line front end
+description: The only layer that parses argv, prints, writes files, and decides exit codes.
+resource: gems/okf/lib/okf/cli.rb
+tags: [cli, shell, registry]
+generated:
+  by: human:maintainer
+  at: 2026-08-13T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/cli.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/cli.rb
+  - title: gems/okf/lib/okf/cli/command.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/cli/command.rb
+---
+
+# Overview
+
+`OKF::CLI` is the executable's front end and the single place where the gem
+touches the outside world for a command: it parses `argv`, prints, writes files,
+and chooses the exit code. Every library class beneath it just returns data — the
+CLI is the [shell half](design/core-shell-split.md) of the architecture. Output
+streams are injected (`out:`/`err:`) so the whole surface is driven in tests
+without a real terminal or socket — which is what lets this layer, the product a
+user actually touches, be [proven end to end](design/integration-first.md) rather
+than by proxy. Even `--help` keeps that contract: rather than the `exit`
+OptionParser's own handler would call — printing past those streams to the
+process's stdout — each parser writes its banner to `out:` and throws `:help`
+back to `run`, which returns the caught status, so a command's help is driven
+and asserted like the command itself.
+
+# Subcommands
+
+Dispatch goes through a **registry**. Each verb is a `CLI::Command` subclass in
+its own file under `okf/lib/okf/cli/`, registering itself at load; `cli.rb` looks the
+name up and calls it. The require block at the bottom of `cli.rb` *is* the order
+`okf help` lists them in, and a test pins that so the coupling cannot drift
+unnoticed.
+
+That registry is also the CLI's extension point (`@okf-eco design/extension-points`): a
+gem shipping `okf/plugin.rb` adds a verb with no edit here, and it appears in the
+map under `installed extensions:`. Discovery is lazy — a built-in never scans —
+and a broken addon is reported on stderr rather than being fatal.
+
+A verb's group is now something it *declares* — `.group`, one of the four
+questions a command answers about itself — and `CLI::GROUPS` fixes the order they
+print in. So this is the map `okf help` builds, not an editorial arrangement of
+it; a group here that no command returns is a group nobody sees.
+
+| Group | Verbs | Notes |
+|-------|-------|-------|
+| `:act` | `skill`, `server`, `render` | boot the [graph server](capabilities/graph-server.md) or write it as a [static file](capabilities/render.md); install the [agent skill](capabilities/agent-skill.md). |
+| `:registry` | `registry` | one umbrella verb over its subcommands — curate the [bundle registry](registry.md), global or [project-local](registry.md#global-by-default-project-local-by-discovery). |
+| `:judge` | `lint`, `loose`, `validate` | [validate](capabilities/validator.md) and [lint](capabilities/linter.md) answer different questions and stay separate. |
+| `:read` | `search`, `index`, `dirs`, `stats`, `types`, `tags`, `files`, `references`, `catalog` | the [browser views as text](capabilities/read-views.md), plus the `index` map and [ranked search](capabilities/search.md). |
+| `:graph` | `graph` | its own group because it is the whole model at once, not a view onto part of it. |
+| `:extension` | *(whatever is installed)* | the only group with a printed heading — "where did this come from?" is a question only an addon raises. |
+
+Plus `version` / `--version` / `-v` and `help` / `--help` / `-h`.
+
+# `server` reads its mode from how many dirs you give it
+
+One verb covers three intentions, and the argument count is the whole interface —
+no `--hub` flag, no second verb:
+
+| Invocation | Serves |
+|------------|--------|
+| `okf server <dir>` | that bundle at `/` — the classic single server |
+| `okf server <dir> <dir>…` | those bundles behind a [hub](capabilities/graph-server.md), ephemerally (the first is the default); nothing is registered |
+| `okf server` | the [registry](registry.md), its first entry still on disk at `/` |
+
+Passing dirs never writes to the registry: an ad-hoc look at two bundles side by
+side should not enrol them in the user's durable list. Registering is always the
+explicit act of `okf registry set`.
+
+`registry` is an umbrella verb — `init`, `list`, `set`, `del`, `default`,
+`rename`, `group`, `ungroup`, `link`, `unlink`, `import` — over one persistent
+file, and it
+is **one row in the map**. It carried ten for a while, which made a third of `okf
+help` about registry management when registry management is not a third of what
+okf does; the row now points at `okf registry --help`, which prints the ten with
+their grammar and the `-g` they share. The map's job is to name the verbs. A verb
+whose own help is the manual is the same progressive disclosure the bundles are
+built on, applied to the CLI's front page — and the row has to *say* the help
+exists, since nothing else tells a reader an umbrella has subcommands at all. `$OKF_HOME` points every
+one of them at a different global registry, which is what keeps the tests off the
+real `~/.okf`; `registry init` and discovery add a [project-local](registry.md#global-by-default-project-local-by-discovery)
+one that replaces it while you stand in its tree, with `OKF_NO_DISCOVERY=1` to
+force the global one.
+
+## One lever, not two
+
+A *cross-cutting* lever is an env var, never a flag. An earlier design carried a
+`--home DIR` flag, which had to be remembered on the three verbs that offered it
+and forgotten on every other one — a flag whose whole job was to name a location
+the env var already named. `$OKF_HOME` composes where a flag cannot: it reaches
+every verb at once without being typed, it survives into a subprocess, and if the
+directory ever holds more than `registry.json` it keeps meaning the same thing.
+`OKF_NO_DISCOVERY` earns its keep the same way, and this is still why there is no
+`--global` on `lint`, on `search`, or on the eleven others: a per-verb flag for
+resolution would be fourteen places to thread it and fourteen to forget.
+
+The `registry` umbrella is the exception, and the line is *subject*, not
+convenience. Every other verb takes a bundle and merely happens to resolve a name
+through a registry; `registry`'s argument **is** a registry file. Saying which one
+is therefore an argument to that verb in the way `--as` is, not a lever bolted
+across the CLI — so `-g`/`--global` lives on its subcommands (all but `init`,
+whose whole job is to create a *local* file) and nowhere else. The env var is
+still the right answer for a whole session or a CI job; the flag is the right
+answer for one command, and for the plain fact that a capability reachable only
+through an env var is one most people never discover. Both name the same
+behavior, so neither can drift from the other.
+
+# Every output names its bundle, in the identity the caller used
+
+Two keys, one meaning each: `bundle` is always a directory, `slug` always a
+registry slug. Name a bundle by [@slug](registry.md) and the answer comes back in
+that identity — `OKF lint — @handbook (/path/to/one)`, and
+`{ "bundle": "/path/to/one", "slug": "handbook", … }`. The point is an agent
+holding several bundles at once: an output that names only a path forces it to
+remember which invocation produced which answer, and remembering is where a
+model confabulates. [Cross-bundle search](capabilities/search.md) goes further
+and maps every slug to its dir in the head, so a hit resolves to a file with no
+second call.
+
+A bundle named by *path* carries no slug, deliberately. It may not have one, and
+inventing a name it was never given would imply a registration that does not
+exist — while looking one up would cost a registry read on every plain-dir run,
+which is the laziness that keeps unregistered use free. The identity the caller
+used is the identity they get back.
+
+# @slug: the registry names bundles for every verb
+
+Wherever a `<dir>` goes, `@slug` resolves a [registered bundle](registry.md)
+and bare `@` the registry's default — one resolution seam (`resolve_ref`, shared
+by the positional parsers and search's ref list), inherited by all verbs at once,
+so `okf lint @handbook` works from any directory. They read the
+[active registry](registry.md#global-by-default-project-local-by-discovery) — a
+project-local one discovered from the working directory, else `$OKF_HOME` — which
+is why the not-registered error names the registry file it consulted, so a
+mismatch self-diagnoses rather than reading as "never registered".
+
+A leading `@` always means the registry (`./@name` keeps an odd directory
+reachable), the registry file loads only when a ref appears, and an explicit ask
+fails hard: an unknown slug, a registered-but-gone directory, or a malformed
+registry is a usage error whose message names the next move, never a silent skip.
+The normalization is the subtle part — a slug is normalized exactly as
+registration normalized it, so `@One` finds the bundle from dir `One`, but
+*without* the placeholder that minting a slug from a basename needs: a name has
+to come out of `slugify("!!!")`, and nothing may come out of a lookup, or `@***`
+would quietly resolve to whatever bundle is slugged `bundle`.
+
+A `server` `@slug` carries its registered slug to the mount, and reserves it before any
+plain dir's basename is deduped — otherwise `server ./two @two` would hand `/b/two/`
+to the *unregistered* directory and a bookmark would open the wrong graph. (The
+first argument still lands at `/`; the registry's own order applies only to a
+bundle-less run.) [`search`](capabilities/search.md) is the one verb that *merges*
+several bundles into one answer — several @slugs, or `@all`.
+
+`@all` is a ref, not a flag, and only `search` expands it. That restraint is the
+point: through the shared seam, `okf lint @all` would resolve to one bundle when
+one is registered (and lint it) and to two when two are (exit 2 by the
+[second-bundle rule](#exit-codes)) — the same command's meaning tracking the size
+of the registry, which is the silent-wrong-answer shape the rule exists to stop.
+So every other verb refuses `@all` by name instead, and `all` is reserved as a
+slug so the refusal can never be wrong.
+
+# Exit codes
+
+The contract every verb keeps:
+
+| Code | Meaning |
+|------|---------|
+| `0` | success — including a bundle with lint findings (`lint` is advisory) |
+| `1` | a non-conformant bundle (`validate`) or a `lint --fail-on warn` threshold crossed |
+| `2` | usage error — unknown command, missing directory, bad flag, a bad `-o` path, or a *second* positional |
+
+That last one is the subtle member: only [`search`](capabilities/search.md) merges
+several bundles and only `server` mounts them, so a second bundle handed to any
+other verb is a question it cannot answer. Reading the first and dropping the rest
+would answer confidently about a bundle nobody asked about, which is why it is a
+usage error rather than a convenience — the same reason a bad `-o` path is exit 2
+and not a backtrace.
+
+It is a rule about the **positional**, not about bundles, and stating it the
+narrow way is how it came to be broken. `skill` takes a destination rather than a
+`<dir>`, so it read as outside the rule, hand-rolled its own argument shift, and
+accepted a second destination — installing into the first, ignoring the second,
+exiting 0. It goes through the same shared pair as every other single-positional
+verb now (`positional` for the value, `no_extras?` for what must not follow it),
+because a guarantee that lives in a helper is only as wide as the verbs that
+call it.
+
+# Best-effort reads
+
+`graph`, `server`, `render`, and the read views are best-effort under §11: a file
+the reader cannot use is kept in `bundle.unparseable`, skipped, and *noted on
+stderr* (so JSON on stdout stays clean) rather than aborting the whole command.
+One bad file never breaks the rest. Run [validate](capabilities/validator.md) for
+the details of what was skipped — the note counts, `validate` names each file and
+why.
+
+Two causes reach that bucket, and the tolerance has to cover both or it is not a
+posture but a coincidence: frontmatter that will not **parse**, and a file that
+will not **open** at all. The second was the gap — an unreadable file threw its
+errno out of the reader, and since the read is the one path every verb shares, a
+single locked file took the whole bundle down through all of them, as a backtrace
+under an exit code that claims *non-conformant*. It is one unusable file. It
+reports as one, under §11 condition 1, naming the file and the errno.
+<!-- rule:okf-read-best-effort -->
+
+The boundary: `Path.join_under!` still raises. A path leaving the bundle root is
+not a bad file — it is a bundle lying about its shape, and best-effort is
+tolerance for damage, never for a claim.