okf 1.8.0 → 1.9.0

data/lib/okf/{server → render}/graph.rb

@@ -3,10 +3,14 @@
 require "rack/utils"
 
 module OKF
-  module Server
-    # Renders an OKF::Bundle::Graph as the interactive graph page served by
-    # OKF::Server::App. The markup lives in graph/template.html.erb; #render
-    # returns the HTML string.
+  # The view layer: turns a bundle into the interactive graph page. Pairs with the
+  # pure OKF::Bundle::Graph (the data model) — Bundle builds the graph, Render
+  # draws it. A shell (reads the template, escapes with rack/utils), but knows
+  # nothing about HTTP: OKF::Server::App serves what this produces, and `okf
+  # render` writes it to a file, from the one class.
+  module Render
+    # Renders an OKF::Bundle::Graph as the interactive graph page. The markup lives
+    # in graph/template.html.erb; #render returns the HTML string.
     #
     # The page boots from a *minimal* payload — nodes carry only id + title, plus
     # compact TYPES/TAGS inverted indexes for colouring and filtering. It has two
@@ -16,9 +20,9 @@ module OKF
     #     metadata, catalog, index and log are pulled from OKF::Server::App on
     #     demand via fetch, so the initial payload stays small and bodies read
     #     live from disk (edits show without a restart). Nothing extra embedded.
-    #   render mode (embed: payload) — `okf render` bakes the whole bundle in:
-    #     the same fetch getters resolve from the injected payload instead, so
-    #     the single file needs no server (e.g. hosting on GitHub Pages).
+    #   render mode (embed: payload) — `okf render` bakes the whole bundle in via
+    #     .static below: the same fetch getters resolve from the injected payload
+    #     instead, so the single file needs no server (e.g. GitHub Pages).
     #
     # NOTE (trust boundary): the page loads Cytoscape + marked from a CDN, so it
     # needs network for those libraries even in render mode. Fetched/embedded
@@ -38,6 +42,28 @@ module OKF
       # built from the backslash code point so no literal escape appears here.
       LT_ESCAPE = (92.chr(Encoding::UTF_8) + "u003c").freeze
 
+      # `okf render`: the whole page as one self-contained file, the bundle baked
+      # in, so it hosts where no server answers a fetch. Takes any bundle handle
+      # (an OKF::Bundle::Folder) and returns the HTML string.
+      def self.static(folder, title: nil, link: nil, layout: "cose")
+        new(folder.graph(minimal: true), title: title || folder.name, link: link, layout: layout, embed: payload(folder)).render
+      end
+
+      # What the baked page carries in place of the endpoints a live server would
+      # answer. Every key here is data a client getter reads from EMBED instead of
+      # fetching — and each derives from the *same* folder method the matching
+      # OKF::Server::App endpoint uses, so the bake and the live server cannot
+      # drift (/node/meta is the exception: the fragment is derived on the client
+      # from the catalog's raw description, so no map is baked for it).
+      def self.payload(folder)
+        {
+          catalog: folder.catalog,
+          index: folder.directory_index,
+          logs: folder.log_entries,
+          bodies: folder.concepts.each_with_object({}) { |concept, map| map[concept.id] = concept.body.to_s }
+        }
+      end
+
       # +node_endpoint+/+meta_endpoint+ are the (mount-relative) URLs the page
       # fetches a concept's raw markdown and metadata fragment from — relative so
       # the page works whether served at "/" or mounted under a Rails prefix.
@@ -74,6 +100,12 @@ module OKF
         html_escape(graph_name)
       end
 
+      # The bundle's own name, for the client: what the header already shows, so
+      # the page can label the root with it instead of `(root)` or `/`.
+      def name_json
+        json_for_script(graph_name)
+      end
+
       def og_title
         html_escape("OKF · #{graph_name}")
       end

data/lib/okf/server/app.rb

@@ -2,7 +2,7 @@
 
 require "rack"
 
-require "okf/server/graph"
+require "okf/render/graph"
 
 module OKF
   module Server
@@ -11,7 +11,7 @@ module OKF
     #
     #   mount OKF::Server::App.new(folder) => "/knowledge"
     #
-    # The page (OKF::Server::Graph) boots from a *minimal* graph (id + title + edges
+    # The page (OKF::Render::Graph) boots from a *minimal* graph (id + title + edges
     # + type/tag indexes) and pulls each concept's markdown body and description from
     # here on demand, so the initial payload stays small and bodies are read live
     # from disk (edits show without a restart). Part of the shell — it does I/O.
@@ -62,13 +62,6 @@ module OKF
         end
       end
 
-      # The same interactive page, but with the whole bundle baked in — bodies,
-      # catalog, index and logs — so it needs no server. This is what `okf render`
-      # writes: the fetch getters resolve from the embedded payload, not from here.
-      def render_static
-        Graph.new(graph, title: @title || @folder.name, link: @link, layout: @layout, embed: embed_payload).render
-      end
-
       # The 404 both this app and the Hub answer with, so the two cannot drift.
       def self.not_found
         [ 404, { "content-type" => "text/plain; charset=utf-8" }, [ "not found\n" ] ]
@@ -97,50 +90,20 @@ module OKF
         { directories: @folder.directory_index }
       end
 
-      # Every log.md with its content, root scope first. Content is read live
-      # from disk so a just-appended entry shows without a restart; paths come
-      # from the loaded bundle, never from the request.
+      # The §7 history the Log panel renders: every log.md with its content, root
+      # scope first, read live from disk. Built by OKF::Bundle::Folder#log_entries,
+      # shared with `okf render`'s bake so the served and baked logs cannot drift.
       def logs
-        entries = @folder.bundle.log_files.sort_by { |path| [ path == "log.md" ? 0 : 1, path ] }
-        { logs: entries.map { |path| { path: path, dir: File.dirname(path), content: log_content(path) } } }
-      end
-
-      def log_content(path)
-        File.read(File.join(@folder.root, path), encoding: "UTF-8")
-      rescue SystemCallError
-        @folder.bundle.reserved_content(path)
+        { logs: @folder.log_entries }
       end
 
       def page
-        @page ||= Graph.new(
+        @page ||= OKF::Render::Graph.new(
           graph, title: @title || @folder.name, link: @link, layout: @layout,
           siblings: @siblings, self_slug: @self_slug, hub_path: @hub_path
         ).render
       end
 
-      # Everything the on-demand endpoints would serve, baked for render mode. The
-      # arrays match what each client getter extracts from the JSON envelope; the
-      # per-concept maps mirror /node (raw, unstripped body) and /node/meta (the
-      # same escaped fragment). Read from the in-memory bundle — no live disk read,
-      # since a static file is a snapshot, not a window on edits.
-      def embed_payload
-        {
-          catalog: @folder.catalog,
-          index: @folder.directory_index,
-          logs: logs[:logs],
-          bodies: bodies,
-          meta: meta
-        }
-      end
-
-      def bodies
-        @folder.bundle.concepts.each_with_object({}) { |concept, map| map[concept.id] = concept.body.to_s }
-      end
-
-      def meta
-        @folder.bundle.concepts.each_with_object({}) { |concept, map| map[concept.id] = description_fragment(concept) }
-      end
-
       def node_body(id)
         concept = concept_for(id)
         return not_found if concept.nil?

data/lib/okf/skill/SKILL.md

@@ -5,14 +5,15 @@ description: >-
   directory of markdown files with YAML frontmatter that humans and agents read
   from one source. Use when capturing knowledge into a bundle (a service, schema,
   metric, decision, runbook: "document this in OKF", "capture this as a concept"),
+  converting existing docs into one ("migrate/OKFy our docs into a bundle"),
   retrieving from one without reading it whole ("what do we know about X?", "where
-  is X documented?", "search the bundle"), updating one after code or docs change
-  ("update the knowledge bundle"), checking its conformance or curation quality
-  ("validate/lint the bundle"), serving or rendering it as a graph, or working in a
-  repo that already carries an OKF bundle — a `.okf/` directory or a root `index.md`
-  carrying `okf_version`.
+  is X documented?", "search the bundle"), updating one after code or docs
+  change ("update the knowledge bundle"), checking its conformance or curation
+  quality ("validate/lint the bundle"), serving or rendering it as a graph, or
+  working in a repo that already carries an OKF bundle — a `.okf/` directory or a
+  root `index.md` carrying `okf_version`.
 user-invocable: true
-argument-hint: "[search|produce|maintain|consume|<okf-cli-verb>] [dir] [--flags]"
+argument-hint: "[search|produce|migrate|maintain|consume|curate|doctor|<okf-cli-verb>] [dir|@slug] [--flags]"
 allowed-tools: Read Write Edit Grep Glob Bash
 ---
 
@@ -66,12 +67,16 @@ earn your keep as the expert, not the executable.
 
 ## The CLI is your eyes — you are the judgment
 
-Guard once, then trust it — the `okf` executable answers every mechanical question
-deterministically, and its read views show everything the browser UI does:
-
-```bash
-command -v okf >/dev/null || echo "okf CLI missing — install: gem install okf (or from a checkout: cd gem && bundle exec rake install)"
-```
+The `okf` executable answers every mechanical question deterministically, and its
+read views show everything the browser UI does. **Don't probe for it — just run
+the verb.** A proactive `command -v okf` before every task spends a whole tool
+round proving what the next command reveals for free; the CLI's own failure is a
+cheaper, truer signal. (The two deliberate exceptions are [menu](playbooks/menu.md)
+and [doctor](playbooks/doctor.md) — both decide *whether to install*, so they check
+first.) The one distinction to hold: a shell `okf: command not
+found` is the *only* thing that means "install it" (→ [doctor](playbooks/doctor.md));
+every line that starts `error:` is okf *answering* — a bundle or usage result to
+read and act on, never a missing toolchain to send to doctor.
 
 Don't memorize the surface — `okf --help` maps every verb, `okf <verb> --help` its
 flags. The division of labour is the whole game:
@@ -98,7 +103,7 @@ shapes, the tag-curation views, the server's trust boundary.
 ## Orient before you touch anything
 
 Picking up a bundle you don't already know — to consume or maintain — run `okf
-index <dir>` (the §6 map: every directory's index body, rollups, and listings) and
+index <dir|@slug>` (the §6 map: every directory's index body, rollups, and listings) and
 read `log.md` (the §7 baseline of what changed last) **before** greping or opening
 leaves. It is the cheapest high-signal context, and the only reliable way to catch
 enumeration drift: **grep cannot find an index entry that is missing** — you can't
@@ -123,9 +128,15 @@ is X documented" → `search`; a repo already carrying a bundle plus a task
 needing its knowledge → `consume`; "check / graph / preview it" → run the
 matching CLI verb and interpret the result. When genuinely ambiguous, ask.
 
-**Which directory?** Use the path given. Otherwise default to `.okf/` at the repo
-root, but first detect whether the project already keeps its bundle elsewhere
-(e.g. `docs/`) and prefer that. Commit the bundle alongside the code it describes.
+**Which target?** A leading `@` is a *registry ref*, not a path: `@slug` names a
+bundle registered with `okf registry set`, bare `@` the default — route it
+straight to `okf <verb> @slug` and skip the directory hunt (`okf search` spans
+several: `@a @b`, or `@all`). A plain path is used as given. Given no target and a
+cwd that carries no bundle, `okf registry list` is the next move, not a hunt
+across sibling directories. Producing a *new* bundle with no path? Default to
+`.okf/` at the repo root, but first detect whether the project already keeps its
+bundle elsewhere (e.g. `docs/`) and prefer that; commit it alongside the code it
+describes.
 
 **Target isn't a bundle?** When a verb points at a directory that holds markdown
 but no root `index.md` carrying `okf_version` — `validate` failing wholesale on

data/lib/okf/skill/playbooks/consume.md

@@ -1,8 +1,10 @@
 # Playbook: consume — use a bundle as context
 
-1. **Orient first** (the [SKILL.md](../SKILL.md) reflex): `okf index <dir>` maps the
-   whole bundle in one pass — every directory's index body, rollups, and listings —
-   and `log.md` gives recent history. Then follow links only into the concepts the
+1. **Orient first** (the [SKILL.md](../SKILL.md) reflex): `okf index <dir|@slug>` maps
+   the whole bundle in one pass — every directory's index body, rollups, and listings —
+   and `log.md` gives recent history. Address a registered bundle by `@slug` (bare
+   `@` = the default); if the cwd carries no bundle, `okf registry list` finds one
+   instead of a directory hunt. Then follow links only into the concepts the
    task needs. For a *pointed question* rather than broad context, switch to the
    [search playbook](search.md): map → finder (`okf search`) → only the winning
    bodies. For a large bundle, `okf graph --json --minimal` gives the whole link

data/lib/okf/skill/playbooks/maintain.md

@@ -43,7 +43,7 @@ up. The modelling craft behind steps 3 and 7 lives in
      by design only through its index — leave it. **Terminal-by-design is not a
      defect.** Loose ≠ orphan: an index listing makes a file *reachable* (not an
      orphan) but is not a graph edge, so an indexed file can still float here.
-7. **Curate the tag vocabulary** <!-- rule:okf-tag-vocabulary --> when the pass
+7. **Curate the tag vocabulary** when the pass
    touched tags, or when `okf tags <dir>` shows a long tail of singletons. Run `okf tags <dir> --by area` and
    `--by type` — the grouped view is the analysis; read each group top-down:
    - **twins** — two tags riding the exact same concepts (equal counts sort them

data/lib/okf/skill/playbooks/search.md

@@ -6,9 +6,13 @@ can query cheaply is dead weight. The discipline is progressive disclosure
 (spec §6): every step pays a few hundred bytes to decide what the next step
 reads, and full bodies are read last, and only the winners.
 
-1. **Guard once**: `command -v okf`. Missing → [doctor](doctor.md). No CLI at
-   all → read the root `index.md`, then each relevant area's `index.md`, by hand.
-2. **Ingest the map and decide where to look.** `okf index <dir> --no-body` is
+1. **Just run it — no presence probe.** Point the finder at a path or an `@slug`
+   (a registered bundle; bare `@` = the default). Only a shell `okf: command not
+   found` means install (→ [doctor](doctor.md)); with no CLI possible at all, read
+   the root `index.md` then each relevant area's `index.md` by hand. No bundle in
+   the cwd? `okf registry list` names the registered ones — address them by
+   `@slug`, don't hunt sibling directories.
+2. **Ingest the map and decide where to look.** `okf index <dir|@slug> --no-body` is
    the skeleton: every directory with its concept count, types, tags, children.
    *You* do the semantic matching here — the question names a meaning, the map
    names areas; connect them by judgment, not string equality. When an area
@@ -17,8 +21,37 @@ reads, and full bodies are read last, and only the winners.
    <!-- rule:okf-search-map-first -->
 3. **Cut across with the finder when the question is lexical.** An exact
    symbol, an error code, a column name, a phrase — things structure won't
-   surface — go to `okf search <dir> <terms>` (terms AND together; `--regexp`
-   for patterns like `err_[a-z]+_409`). Scope it with what the map taught you:
+   surface — go to `okf search <dir> <terms>`. Terms AND together and are matched
+   **literally against raw text**, so an exact query means what it looks like: a
+   phrase, a dotted version (`7.2.0`), an underscored identifier (`customer_id`),
+   a mid-word fragment (`ustomer`) and a word written in `backticks` all match
+   the way you typed them. <!-- rule:okf-search-exact-identifiers -->
+
+   **Match the engine to the shape of the query, not to habit** — the default
+   answers most of them, and the two engines fail in opposite directions:
+   <!-- rule:okf-search-engine-choice -->
+
+   | Your query is | Reach for | Because |
+   |---|---|---|
+   | an identifier, version, path, phrase, or anything in `` `backticks` `` | *nothing — the default* | matched literally; the index shatters all of these |
+   | a mid-word fragment (`ustomer`) | *nothing — the default* | an infix is not a token, so the index cannot reach it |
+   | a pattern (`err_[a-z]+_409`) | `-e` | Ruby regexp over raw text; still the scan |
+   | a partial word (`dedup` → `deduplication`) | *nothing — the default* | substring covers prefixes, and suffixes and infixes too |
+   | a theme, where you want the best match to lead | `--engine index` | BM25+ ranks by relevance, not by summed field weight |
+   | possibly mistyped | `--fuzzy` | edit distance 0.2 × term length — the index's alone |
+   | being reconciled with the browser page | `--engine index` | same MiniSearch build, so the two rank alike |
+
+   The index has exactly **three** things the default lacks: relevance ranking,
+   typo tolerance, and page parity. Its `prefix` capability is not a fourth — a
+   substring match already reaches every prefix, so `prefix` is what the index
+   needs to *catch up*, not a reason to choose it.
+
+   **`--fuzzy` is an engine switch, not a mode.** It routes to the index, so a
+   run that only wanted a typo forgiven also gets token matching, shattered
+   identifiers and unfindable code spans. Fix the spelling and stay on the
+   default when you can. <!-- rule:okf-search-fuzzy-is-a-switch -->
+
+   Scope any of them with what the map taught you:
    `--area billing`, `--type Decision`, `--tag idempotency`, `--in body`.
    Matches rank by where they hit, and the snippet often *is* the answer.
    When the answer may live in another registered bundle, span them — leading
@@ -40,6 +73,13 @@ Anti-patterns, each a real token bill:
 - **Grep before map.** Grep cannot find the entry that is *missing*, and it
   returns line noise where `search` returns ranked concepts. Grep is the
   fallback when the CLI is absent, not the first move.
-- **Mechanical synonym retries.** The finder is exact by design; *you* are the
+- **Mechanical synonym retries.** The finder is exact by default; *you* are the
   fuzzy layer. When terms miss, learn the bundle's vocabulary — `okf tags
-  <dir>`, `okf types <dir>` — and re-ask in its own words.
+  <dir>`, `okf types <dir>` — and re-ask in its own words. `--fuzzy` forgives a
+  *typo*, not a wrong vocabulary, so it is the wrong reach for this.
+- **Flag-shopping a query that found nothing.** Cycling `--fuzzy`, then
+  `--engine index`, then `-e` over the same terms is guessing, and each engine
+  fails differently enough that one of them eventually returns *something* —
+  which is how a wrong answer gets found. Zero matches is usually a vocabulary
+  result, not an engine result: go back to the map and the tag list. Reach for a
+  different engine when you can say which property of the query needs it.

data/lib/okf/skill/reference/authoring.md

@@ -115,8 +115,9 @@ bundle-root [root-index](../templates/root-index.md), [log](../templates/log.md)
 ## Playbooks
 
 The step-by-step playbooks live in [../playbooks/](../playbooks/), one file per
-verb (produce, maintain, consume, curate, doctor), routed by the Commands table
-in [SKILL.md](../SKILL.md). The Closeout below is their shared finishing gate.
+verb (search, produce, migrate, maintain, consume, curate, doctor), routed by the
+Commands table in [SKILL.md](../SKILL.md). The Closeout below is their shared
+finishing gate.
 
 ## Closeout — the finishing gate
 

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

@@ -6,14 +6,13 @@ reimplemented in this skill. They run the deterministic `okf` executable shipped
 the companion gem — the single source of truth for OKF mechanics. Your job is to
 invoke it correctly and interpret the result, not to reason out conformance by hand.
 
-## Presence guard
+## When it isn't installed
 
-Check the tool exists before relying on it. If it is missing, the gem is not
-installed — say so and stop; never fabricate a result:
-
-```bash
-command -v okf >/dev/null || echo "okf CLI not found — install it: 'gem install okf' (or from a checkout: 'cd gem && bundle exec rake install')"
-```
+Don't probe for the tool before using it — just run the verb. A shell `okf:
+command not found` is the only thing that means the gem isn't installed: say so
+and stop (`gem install okf`, or from a checkout `cd gem && bundle exec rake
+install`); never fabricate a result. Any line that starts `error:` is the CLI
+*answering* — a bundle or usage result to read, not a missing toolchain.
 
 ## Invocation
 
@@ -140,16 +139,74 @@ defect — a terminal leaf (a backlog item, a spec reference) can be loose by de
 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 — as case-insensitive substrings, or as Ruby regular
-expressions with `--regexp`/`-e` (an invalid pattern is a usage error, exit 2).
+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,
 body); the shared `--type/--area/--tag` 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.
-The per-bundle rankings merge — scores are absolute term weights, so they
-compare across bundles — and each row carries its bundle's slug. This is the
+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 -->
 
@@ -178,12 +235,14 @@ which has no slug to give. Two sharp edges: every *leading* @-arg is taken as a
 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 over matched fields — and carry one bounded context snippet from
-the strongest match that needs context (description or body). Deliberately not
-fuzzy: 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. Advisory read: **exit 0 even with zero matches**.
+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,
 area, tags, matched, score, snippet }] }`. Registry mode — any leading @ref,
 `@all` among them — swaps the envelope: `{ bundles: [{ slug, dir }, …],

data/lib/okf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OKF
-  VERSION = "1.8.0"
+  VERSION = "1.9.0"
 end

data/lib/okf.rb

@@ -40,6 +40,14 @@ module OKF
   require "okf/bundle"
   require "okf/bundle/graph"
   require "okf/bundle/search"
+  # These two lines ARE the engine preference order. Each engine registers itself
+  # at load, `Search.engines` is registration order, and the router walks it after
+  # putting DEFAULT_ENGINE first — so reordering these requires reorders which
+  # engine answers a query two engines could both answer. `loading_test.rb` pins
+  # the result (`[:index, :scan]`) so the coupling cannot drift unnoticed, but the
+  # coupling is here, not there.
+  require "okf/bundle/search/index"
+  require "okf/bundle/search/scan"
   require "okf/bundle/validator"
   require "okf/bundle/validator/result"
   require "okf/bundle/linter"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 1.8.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: minifts
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 description: |
   OKF (Open Knowledge Format) is portable knowledge: Markdown files with YAML
   frontmatter that both humans and agents read from one source. This gem is the
@@ -66,6 +80,8 @@ files:
 - lib/okf/bundle/linter/report.rb
 - lib/okf/bundle/reader.rb
 - lib/okf/bundle/search.rb
+- lib/okf/bundle/search/index.rb
+- lib/okf/bundle/search/scan.rb
 - lib/okf/bundle/validator.rb
 - lib/okf/bundle/validator/result.rb
 - lib/okf/bundle/writer.rb
@@ -77,9 +93,9 @@ files:
 - lib/okf/markdown/links.rb
 - lib/okf/path.rb
 - lib/okf/registry.rb
+- lib/okf/render/graph.rb
+- lib/okf/render/graph/template.html.erb
 - lib/okf/server/app.rb
-- lib/okf/server/graph.rb
-- lib/okf/server/graph/template.html.erb
 - lib/okf/server/hub.rb
 - lib/okf/server/runner.rb
 - lib/okf/skill.rb