okf 1.7.0 → 1.9.0

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

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
+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
@@ -14,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
@@ -36,11 +42,38 @@ 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.
       # +embed+ is the render-mode payload (nil = server mode); see the class doc.
-      def initialize(graph, title: nil, link: nil, layout: "cose", node_endpoint: "node", meta_endpoint: "node/meta", embed: nil)
+      # +siblings+/+self_slug+/+hub_path+ carry the hub's bundle switcher into the
+      # page (server mode only). nil — the standalone-server and `okf render`
+      # default — injects an empty SIBLINGS, so the switcher never appears in a
+      # single bundle or a static file.
+      def initialize(graph, title: nil, link: nil, layout: "cose", node_endpoint: "node", meta_endpoint: "node/meta", embed: nil,
+                     siblings: nil, self_slug: nil, hub_path: nil)
         @graph = graph
         @title = title
         @link = link
@@ -48,6 +81,9 @@ module OKF
         @node_endpoint = node_endpoint
         @meta_endpoint = meta_endpoint
         @embed = embed
+        @siblings = siblings
+        @self_slug = self_slug
+        @hub_path = hub_path
       end
 
       def render
@@ -64,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
@@ -102,6 +144,20 @@ module OKF
         json_for_script(@embed)
       end
 
+      # The hub switcher's data: the other bundles (empty when standalone/static),
+      # this bundle's slug, and the hub root — all </script>-escaped like the rest.
+      def siblings_json
+        json_for_script(@siblings || [])
+      end
+
+      def self_slug_json
+        json_for_script(@self_slug)
+      end
+
+      def hub_path_json
+        json_for_script(@hub_path)
+      end
+
       # JSON-encode for safe embedding in an inline <script>: escaping every `<` to
       # its JSON unicode escape neutralizes </script>, <!-- and <script in one
       # stroke, and the result stays valid JSON *and* JavaScript.
@@ -120,8 +176,10 @@ module OKF
         end
       end
 
+      # Rack's, not a hand-rolled one — this output goes into attributes
+      # (`href="…"`), so the escape set is load-bearing rather than cosmetic.
       def html_escape(str)
-        str.to_s.gsub("&", "&amp;").gsub('"', "&quot;").gsub("<", "&lt;").gsub(">", "&gt;")
+        Rack::Utils.escape_html(str.to_s)
       end
     end
   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.
@@ -31,11 +31,18 @@ module OKF
     #                       dir, content} ] } (JSON; content read live from disk,
     #                       like a body — the log is the file that changes most)
     class App
-      def initialize(folder, title: nil, link: nil, layout: "cose")
+      # +siblings+/+self_slug+/+hub_path+ are set only when this app is hosted under
+      # a hub (OKF::Server::Hub): the other bundles the in-page switcher offers, this
+      # bundle's own mount slug, and the hub root. They stay nil for a standalone
+      # server and for `okf render`, so a static file never advertises a switcher.
+      def initialize(folder, title: nil, link: nil, layout: "cose", siblings: nil, self_slug: nil, hub_path: nil)
         @folder = folder
         @title = title
         @link = link
         @layout = layout
+        @siblings = siblings
+        @self_slug = self_slug
+        @hub_path = hub_path
       end
 
       def call(env)
@@ -55,11 +62,9 @@ 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
+      # 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" ] ]
       end
 
       private
@@ -85,45 +90,18 @@ 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(graph, title: @title || @folder.name, link: @link, layout: @layout).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) }
+        @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
 
       def node_body(id)
@@ -168,11 +146,11 @@ module OKF
       end
 
       def not_found
-        [ 404, { "content-type" => "text/plain; charset=utf-8" }, [ "not found\n" ] ]
+        self.class.not_found
       end
 
       def html_escape(str)
-        str.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+        Rack::Utils.escape_html(str.to_s)
       end
     end
   end

data/lib/okf/server/hub.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "rack"
+
+require "okf/server/app"
+
+module OKF
+  module Server
+    # Multiplexes N bundles behind one server. Each bundle is mounted at
+    # /b/<slug>/ and served by its own OKF::Server::App; `/` redirects to the
+    # default bundle (explicitly chosen, or the first), or shows an empty-state
+    # page when none are registered. The graph page is already mount-relative (its fetch endpoints
+    # are relative), so hosting under a prefix needs only a clean PATH_INFO strip
+    # here plus a trailing-slash redirect. Part of the shell — it is a Rack app.
+    #
+    #   GET /               302 -> /b/<default>/   (empty-state page when no bundles)
+    #   GET /b/             the bundle index — every hosted bundle, default marked
+    #   GET /b/<slug>       301 -> /b/<slug>/      (query string preserved)
+    #   GET /b/<slug>/...   delegated to that bundle's App (the prefix stripped)
+    #   GET (unknown slug)  404 as a page listing the hosted bundles — a stale
+    #                       bookmark after a rename gets a way home, not bare text
+    #
+    # +bundles+ is an ordered array of Hub::Bundle (slug, folder, title). Apps are
+    # built up front, each carrying the *other* bundles as siblings so the in-page
+    # switcher can jump between them; static `okf render` files get no siblings and
+    # so cannot switch.
+    class Hub
+      MOUNT = "/b"
+
+      # One hosted bundle: its +slug+ (unique mount key), the on-disk +folder+, and
+      # its display +title+.
+      Bundle = Struct.new(:slug, :folder, :title)
+
+      # Shared style for the hub's own pages (empty landing, /b/ index, 404) —
+      # self-contained and theme-aware, no external requests, in keeping with the
+      # graph page's own no-CDN-at-rest rule.
+      STYLE = <<~CSS
+        body{margin:0;min-height:100vh;display:grid;place-items:center;background:#f4f5f7;color:#1f2328;font:15px/1.5 system-ui,-apple-system,Segoe UI,Roboto,sans-serif}
+        main{max-width:34rem;width:calc(100% - 4rem);padding:2rem}h1{font-size:1.3rem;margin:0 0 .5rem}
+        code{background:#e6e8eb;padding:.15rem .4rem;border-radius:.35rem}
+        ul.bundles{list-style:none;margin:1rem 0 0;padding:0}
+        ul.bundles li{padding:.45rem 0;border-top:1px solid #e6e8eb;display:flex;justify-content:space-between;gap:1rem;align-items:baseline}
+        ul.bundles a{color:inherit;font-weight:600;text-decoration:none}ul.bundles a:hover{text-decoration:underline}
+        .meta{color:#63697a;font-size:.85rem;white-space:nowrap}
+        .def{margin-left:.5rem;padding:.05rem .45rem;border-radius:99px;background:#e6e8eb;font-size:.75rem}
+        @media(prefers-color-scheme:dark){body{background:#111318;color:#eceef1}code,.def{background:#232833}
+        ul.bundles li{border-color:#2a2e36}.meta{color:#9aa0aa}}
+      CSS
+
+      # The hosted bundles in mount order, and the one `/` redirects to — so a
+      # caller printing the mount table asks the hub instead of re-deriving the
+      # rule and drifting from it.
+      attr_reader :bundles, :default
+
+      # The first bundle is the one `/` redirects to — the registry hands them over
+      # in its own order, where first *is* the default (`okf registry default`
+      # moves an entry to the front), and an ephemeral run takes the dirs as typed.
+      def initialize(bundles, layout: "cose")
+        @bundles = bundles
+        @default = bundles.first
+        @apps = build_apps(layout)
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        return not_found unless request.get?
+
+        path = request.path_info
+        query = request.query_string.to_s
+        # Everything this class *emits* must carry the prefix a host mounted it
+        # under; PATH_INFO is already relative to it.
+        base = env["SCRIPT_NAME"].to_s
+        return landing(base, query) if [ "", "/" ].include?(path)
+        return html(200, index_page(base)) if [ MOUNT, "#{MOUNT}/" ].include?(path)
+
+        slug, rest = split(path)
+        app = slug && @apps[slug]
+        return html(404, missing_page(base, path)) unless app
+        return redirect("#{base}#{MOUNT}/#{slug}/", 301, query) if rest.empty?
+
+        app.call(mounted(env, slug, rest))
+      end
+
+      private
+
+      # Split "/b/<slug>/rest" into [ "<slug>", "/rest" ] (rest "" for just
+      # "/b/<slug>"). A path outside the mount prefix, or an empty slug, is [ nil, nil ].
+      def split(path)
+        prefix = "#{MOUNT}/"
+        return [ nil, nil ] unless path.start_with?(prefix)
+
+        slug, slash, rest = path[prefix.length..-1].partition("/")
+        return [ nil, nil ] if slug.empty?
+
+        [ slug, slash + rest ]
+      end
+
+      # Concept counts for the listing pages, computed once. Bundle#graph is not
+      # memoized (App memoizes its own), and /b/ and every stray 404 render this
+      # list — without the memo a 404 flood reparses every hosted bundle.
+      def counts
+        @counts ||= @bundles.each_with_object({}) do |bundle, memo|
+          memo[bundle.slug] = bundle.folder.graph(minimal: true).nodes.size
+        end
+      end
+
+      # A copy of env aimed at the bundle's App: the /b/<slug> prefix moves from
+      # PATH_INFO to SCRIPT_NAME. The App ignores SCRIPT_NAME (its endpoints are
+      # relative), but keeping the split correct leaves the env well-formed.
+      def mounted(env, slug, rest)
+        env.merge(
+          "SCRIPT_NAME" => "#{env["SCRIPT_NAME"]}#{MOUNT}/#{slug}",
+          "PATH_INFO" => rest
+        )
+      end
+
+      def build_apps(layout)
+        @bundles.each_with_object({}) do |bundle, apps|
+          apps[bundle.slug] = App.new(
+            bundle.folder,
+            title: bundle.title,
+            layout: layout,
+            siblings: siblings_of(bundle),
+            self_slug: bundle.slug,
+            hub_path: "/"
+          )
+        end
+      end
+
+      # Every other bundle, as { slug:, title:, path:, default: } — what the
+      # switcher lists; default marks the bundle `/` opens. The path is
+      # *relative* because these are baked into each App at boot, before any
+      # request names a SCRIPT_NAME: every page lives at <prefix>/b/<slug>/, so
+      # "../<other>/" reaches its sibling under any mount and needs no prefix.
+      def siblings_of(bundle)
+        @bundles.reject { |other| other.slug == bundle.slug }
+                .map { |other| { slug: other.slug, title: other.title, path: "../#{other.slug}/", default: other.equal?(@default) } }
+      end
+
+      def landing(base, query = "")
+        return redirect("#{base}#{MOUNT}/#{@default.slug}/", 302, query) if @default
+
+        html(200, page("OKF · no bundles", <<~BODY))
+          <h1>No bundles registered</h1>
+          <p>Register one with <code>okf registry set &lt;dir&gt;</code>, then restart <code>okf server</code>.</p>
+        BODY
+      end
+
+      # The /b/ index — every hosted bundle with its mount link, concept count,
+      # and the default marked. The browser counterpart of `okf registry`.
+      def index_page(base)
+        page("OKF · bundles", "<h1>Bundles</h1>#{bundle_list(base)}")
+      end
+
+      # The 404 for a slug the hub does not host: name what was asked for, then
+      # list what exists — a stale bookmark after a rename gets a way home.
+      def missing_page(base, path)
+        body = "<h1>No bundle here</h1><p><code>#{escape(path)}</code> does not match a hosted bundle.</p>"
+        body += bundle_list(base) unless @bundles.empty?
+        page("OKF · not found", body)
+      end
+
+      def bundle_list(base)
+        rows = @bundles.map do |bundle|
+          count = counts[bundle.slug]
+          badge = bundle.equal?(@default) ? %(<span class="def">default</span>) : ""
+          %(<li><a href="#{escape(base)}#{MOUNT}/#{escape(bundle.slug)}/">#{escape(bundle.title)}</a>) +
+            %(<span class="meta">#{escape(bundle.slug)} · #{count} concepts#{badge}</span></li>)
+        end
+        %(<ul class="bundles">#{rows.join}</ul>)
+      end
+
+      def page(title, body)
+        <<~HTML
+          <!doctype html><html lang="en"><head><meta charset="utf-8">
+          <meta name="viewport" content="width=device-width,initial-scale=1">
+          <title>#{escape(title)}</title>
+          <style>#{STYLE}</style>
+          </head><body><main>#{body}</main></body></html>
+        HTML
+      end
+
+      def html(status, body)
+        [ status, { "content-type" => "text/html; charset=utf-8" }, [ body ] ]
+      end
+
+      # Keep the query string across redirects — `/b/notes?view=files` must land
+      # on the Files view, not reset to the default graph.
+      def redirect(location, status, query = "")
+        location += "?#{query}" unless query.empty?
+        [ status, { "location" => location, "content-type" => "text/plain; charset=utf-8" }, [ "" ] ]
+      end
+
+      def not_found
+        OKF::Server::App.not_found
+      end
+
+      # Rack's, not a fourth hand-rolled one: the server layer had three, each
+      # escaping a different set — App's left `"` alone, which is safe only
+      # while nothing interpolates it into an attribute. Rack::Utils covers
+      # & " ' < > and ships with the dependency we already have.
+      def escape(str)
+        Rack::Utils.escape_html(str.to_s)
+      end
+    end
+  end
+end

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
@@ -150,7 +161,7 @@ Read the referenced playbook before executing — it *is* the procedure.
 | `consume`  | Use    | use the bundle as context for a task | [playbooks/consume.md](playbooks/consume.md) |
 | `curate`   | Curate | structural upkeep as it stands: validate + lint + loose | [playbooks/curate.md](playbooks/curate.md) |
 | `doctor`   | Setup  | install and verify the CLI, then doctor the bundle | [playbooks/doctor.md](playbooks/doctor.md) |
-| `<okf-cli-verb>` | Read | validate, lint, loose, index, catalog, files, tags, types, stats, graph, server, render, skill | `okf <verb> --help` + [reference/cli.md](reference/cli.md) |
+| `<okf-cli-verb>` | Read | validate, lint, loose, index, catalog, files, tags, types, stats, graph, server, render, registry, skill | `okf <verb> --help` + [reference/cli.md](reference/cli.md) |
 
 Two boundaries worth keeping sharp: `curate` is structural upkeep only — when
 the *content* no longer matches reality, that is `maintain` — and `doctor` is

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,10 +21,42 @@ 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
+   @slugs (`okf search @handbook @notes <terms>`) or `@all` for every registered
+   one — and read the per-row bundle slug before following an id home.
 4. **Read only the winners.** A match row's `id` is its file: `<dir>/<id>.md`.
    Read that file — not its folder, never the whole tree. Follow its links (§5)
    one hop at a time; check `log.md` when freshness matters.
@@ -37,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.