okf 1.10.0 → 1.12.0

data/lib/okf/render/graph.rb

@@ -45,8 +45,10 @@ module OKF
       # `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
+      def self.static(folder, title: nil, link: nil, layout: "cose", map: false)
+        graph = folder.graph(minimal: true)
+        new(graph, title: title || folder.name, link: link, layout: layout, embed: payload(folder),
+          cuts: folder.skeleton.cuts_for(graph.edges), map: map).render
       end
 
       # What the baked page carries in place of the endpoints a live server would
@@ -73,10 +75,17 @@ module OKF
       # default — injects an empty SIBLINGS, so the switcher never appears in a
       # single bundle or a static file. +search_endpoint+ rides along with them:
       # the hub's cross-bundle /search, which only a hub can answer.
+      # +cuts+ is one integer per edge, in @graph.edges order: the cut that edge
+      # survives (OKF::Bundle::Skeleton). It rides inline rather than being
+      # fetched because its only consumer needs it *before* the first layout
+      # runs, which is earlier than any request could answer. nil is allowed and
+      # simply turns the reduced first layout off.
       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, search_endpoint: nil,
-                     manage_root: nil, manage_token: nil)
+                     manage_root: nil, manage_token: nil, cuts: nil, map: false)
         @graph = graph
+        @cuts = cuts
+        @map = map
         @title = title
         @link = link
         @layout = layout
@@ -133,6 +142,21 @@ module OKF
         json_for_script(@graph.edges)
       end
 
+      # Index-aligned with EDGES: `EDGE_CUT[i]` is the cut `EDGES[i]` survives.
+      # An array of small integers rather than a keyed map, because keying it by
+      # "source target" would cost more bytes than the edge list it annotates.
+      def edge_cuts_json
+        json_for_script(@cuts)
+      end
+
+      # Whether the page opens in the Map view — every concept, boxed by the
+      # directory it lives in, with the cross-links undrawn until one is
+      # selected. A boot state rather than a different page: the toggle is the
+      # same one the reader can press, so `--map` only decides where they start.
+      def map_json
+        json_for_script(@map ? true : false)
+      end
+
       # { type => [id, …] } — the client builds an id→type map for node colour.
       def types_json
         json_for_script(@graph.type_index)

data/lib/okf/server/app.rb

@@ -21,7 +21,7 @@ module OKF
     #   GET /node/meta?id=… its description, as an escaped HTML fragment
     #   GET /catalog        rich per-concept metadata for the catalog/files/stats
     #                       views: { concepts: [ {id, title, type, description,
-    #                       tags, timestamp, status, area, dir, links_*} ] } (JSON)
+    #                       tags, timestamp, status, top_dir, dir, links_*} ] } (JSON)
     #   GET /tags           the tag index  { tag  => [id, …] } (JSON)
     #   GET /types          the type index { type => [id, …] } (JSON)
     #   GET /index          the §6 progressive-disclosure map for the Index panel:
@@ -30,18 +30,64 @@ module OKF
     #   GET /log            the §7 history for the Log panel: { logs: [ {path,
     #                       dir, content} ] } (JSON; content read live from disk,
     #                       like a body — the log is the file that changes most)
+    #   GET /search?q=…     ranked concepts in this bundle, for the ⌘K palette:
+    #                       { query, total, truncated, results: [ …rows… ] } (JSON)
     class App
+      # How many rows /search answers with. The palette shows a handful and the
+      # rest is scroll nobody reaches, but the count is reported alongside so a
+      # capped answer never reads as a complete one.
+      SEARCH_LIMIT = 50
+
+      # The engine /search runs on, named rather than inferred. `fuzzy: true`
+      # would route here on its own today — the index is the only registered
+      # engine that offers it — but that is correctness by coincidence, and an
+      # addon declaring :fuzzy would silently take the route.
+      #
+      # It is also the *right* engine here for a reason the CLI's default does
+      # not share: `okf search` is one-shot and cannot amortize an index build,
+      # while this is a long-lived server answering keystroke after keystroke.
+      # And the page's own MiniSearch is what minifts is a port of, so a palette
+      # hit and an in-page search rank alike instead of nearly alike.
+      SEARCH_ENGINE = :index
+
+      # The /search payload, defined once because two hosts answer it: this one
+      # bundle, or every bundle the hub hosts. The only difference is the corpus
+      # handed in — and a nil slug drops the `slug` key from a row, so a
+      # standalone server never answers as if it were a set.
+      #
+      # It takes a prepared corpus rather than the pairs, because that is what
+      # makes the index survive the request that built it.
+      def self.search_payload(corpus, query)
+        terms = query.to_s.split(/\s+/).reject(&:empty?)
+        rows = terms.empty? ? [] : OKF::Bundle::Search.with(corpus, terms, fuzzy: true, engine: SEARCH_ENGINE)
+        {
+          "query" => query.to_s.strip,
+          "total" => rows.length,
+          "truncated" => rows.length > SEARCH_LIMIT,
+          "results" => rows.first(SEARCH_LIMIT)
+        }
+      end
+
       # +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, the hub root, and the hub's cross-bundle search
       # route. They stay nil for a standalone server and for `okf render`, so a
       # static file never advertises a switcher or a search it cannot answer.
+      #
+      # +search_endpoint+ belongs to that group for the same reason, even though
+      # this app now answers /search itself: the page resolves it *relative to the
+      # URL the reader is on*, so only whoever mounted the app knows what to call
+      # it. `okf server` mounts at the root and passes "search"; a host doing
+      # `mount App.new(folder) => "/knowledge"` needs its own spelling, and a
+      # default would have pointed its palette at the host's root instead. The
+      # route answers either way — advertising it is the caller's call.
       def initialize(folder, title: nil, link: nil, layout: "cose", siblings: nil, self_slug: nil, hub_path: nil,
-                     search_endpoint: nil, manage_root: nil, manage_token: nil)
+                     search_endpoint: nil, manage_root: nil, manage_token: nil, map: false)
         @folder = folder
         @title = title
         @link = link
         @layout = layout
+        @map = map
         @siblings = siblings
         @self_slug = self_slug
         @hub_path = hub_path
@@ -50,6 +96,14 @@ module OKF
         @manage_token = manage_token
       end
 
+      # Build the search index now rather than on the first reader's keystroke.
+      # `okf server` calls this after the bundle is loaded, so the cost lands in
+      # boot — where it is expected and attributable — instead of in a request.
+      def warm_search
+        search_corpus
+        self
+      end
+
       def call(env)
         request = Rack::Request.new(env)
         return not_found unless request.get?
@@ -63,6 +117,7 @@ module OKF
         when "/types" then respond_json(graph.type_index)
         when "/index" then respond_json(directory_index)
         when "/log" then respond_json(logs)
+        when "/search" then respond_json(self.class.search_payload(search_corpus, request.params["q"]))
         else not_found
         end
       end
@@ -102,11 +157,20 @@ module OKF
         { logs: @folder.log_entries }
       end
 
+      # Only one thing is read off it here — #cuts_for, the per-link cut the page
+      # lays a large bundle out on. No endpoint serves it: the page needs those
+      # numbers before its first layout, which is earlier than a request could
+      # answer, so they ride inline with the graph instead. Built over the boot
+      # snapshot and held, like the graph itself.
+      def skeleton
+        @skeleton ||= @folder.skeleton
+      end
+
       def page
         @page ||= OKF::Render::Graph.new(
           graph, title: @title || @folder.name, link: @link, layout: @layout,
           siblings: @siblings, self_slug: @self_slug, hub_path: @hub_path, search_endpoint: @search_endpoint,
-          manage_root: @manage_root, manage_token: @manage_token
+          manage_root: @manage_root, manage_token: @manage_token, cuts: skeleton.cuts_for(graph.edges), map: @map
         ).render
       end
 
@@ -147,6 +211,13 @@ module OKF
         [ 200, { "content-type" => content_type }, [ body.to_s ] ]
       end
 
+      # Built on the first search and held for the life of the app, the way the
+      # graph is. `okf server` warms it at boot so the first reader does not pay
+      # for the whole corpus.
+      def search_corpus
+        @search_corpus ||= OKF::Bundle::Search.prepare([ [ nil, @folder.bundle ] ], engine: SEARCH_ENGINE)
+      end
+
       def respond_json(object)
         respond("application/json; charset=utf-8", JSON.generate(object))
       end

data/lib/okf/server/hub.rb

@@ -45,22 +45,9 @@ module OKF
       # names" is how a router becomes an eval.
       WRITES = %w[default rename remove add].freeze
 
-      # How many rows /search answers with. The palette shows a handful and the
-      # rest is scroll nobody reaches, but the count is reported alongside so a
-      # capped answer never reads as a complete one.
-      SEARCH_LIMIT = 50
-
-      # The engine /search runs on, named rather than inferred. `fuzzy: true`
-      # would route here on its own today — the index is the only registered
-      # engine that offers it — but that is correctness by coincidence, and an
-      # addon declaring :fuzzy would silently take the route.
-      #
-      # It is also the *right* engine here for a reason the CLI's default does
-      # not share: `okf search` is one-shot and cannot amortize an index build,
-      # while this is a long-lived server answering keystroke after keystroke.
-      # And the page's own MiniSearch is what minifts is a port of, so a palette
-      # hit and an in-page search rank alike instead of nearly alike.
-      SEARCH_ENGINE = :index
+      # The /search cap and engine live on App, which now defines the payload both
+      # hosts answer with (App.search_payload). Two copies of a constant is two
+      # places to raise the cap and one of them silently losing.
 
       # One hosted bundle: its +slug+ (unique mount key), the on-disk +folder+, and
       # its display +title+.
@@ -171,12 +158,13 @@ module OKF
       # is refused outright with no flag that says otherwise — `--bind 0.0.0.0`
       # turns a personal tool into a public one, and the write surface does not
       # follow it there at all.
-      def initialize(bundles, layout: "cose", registry: nil, writable: false)
+      def initialize(bundles, layout: "cose", registry: nil, writable: false, map: false)
         @bundles = bundles
         @default = bundles.first
         @boot_registry = registry
         @layout = layout
         @writable = writable
+        @map = map
         @apps = build_apps(layout)
       end
 
@@ -205,6 +193,12 @@ module OKF
       end
       private_class_method :load_entry
 
+      # See App#warm_search — same reason, one corpus over every hosted bundle.
+      def warm_search
+        search_corpus
+        self
+      end
+
       def call(env)
         request = Rack::Request.new(env)
         # Everything this class *emits* must carry the prefix a host mounted it
@@ -259,7 +253,7 @@ module OKF
       end
 
       def apply(verb, params)
-        registry = OKF::Registry.new(@boot_registry.path)
+        registry = @boot_registry.reopen
         message = mutate(verb, registry, params)
         reload(registry)
         json("ok" => true, "message" => message)
@@ -339,6 +333,9 @@ module OKF
         @apps = build_apps(@layout)
         @counts = nil
         @health = nil
+        # The corpus is a snapshot of the set, so a write that changes the set
+        # invalidates it. Without this a removed bundle keeps answering /search.
+        @search_corpus = nil
       end
 
       # Same-origin *and* the token. Neither alone is enough: the token lives in
@@ -374,14 +371,14 @@ module OKF
       # keystroke, and the box starts empty. `fuzzy: true` matches both the TUI
       # and the page's own MiniSearch, so all three forgive the same typos.
       def search(query)
-        terms = query.to_s.split(/\s+/).reject(&:empty?)
-        rows = terms.empty? ? [] : OKF::Bundle::Search.across(pairs, terms, fuzzy: true, engine: SEARCH_ENGINE)
-        json(
-          "query" => query.to_s.strip,
-          "total" => rows.length,
-          "truncated" => rows.length > SEARCH_LIMIT,
-          "results" => rows.first(SEARCH_LIMIT)
-        )
+        json(App.search_payload(search_corpus, query))
+      end
+
+      # One index over every hosted bundle — one corpus, so BM25 weighs a term
+      # against the whole set exactly as .across intends. Dropped whenever the
+      # bundle set changes, which is the only thing that can invalidate it.
+      def search_corpus
+        @search_corpus ||= OKF::Bundle::Search.prepare(pairs, engine: App::SEARCH_ENGINE)
       end
 
       # The /b/ manager's own rows, as JSON — what the graph page's Bundles panel
@@ -452,6 +449,7 @@ module OKF
             bundle.folder,
             title: bundle.title,
             layout: layout,
+            map: @map,
             siblings: siblings_of(bundle),
             self_slug: bundle.slug,
             hub_path: "/",
@@ -533,14 +531,26 @@ module OKF
           count: nil, health: "missing", word: word, default: false }
       end
 
+      # A bundle is addressed by its slug — `@orders` on the CLI, `/b/orders/`
+      # here — so the slug is its name and the folder is a fact about it. The row
+      # led with Folder.label instead, which put the address where the name goes;
+      # in a real registry that label is `…/.okf` on nearly every line, so the
+      # loudest column repeated the one word that tells no two bundles apart.
+      #
+      # The short label is gone rather than demoted: it only ever stood in for the
+      # path, and the path is right here on the row's second line.
+      #
+      # The name keeps its `@`, which the ref line used to carry: it is the exact
+      # spelling `okf lint @orders` takes, so the row teaches the CLI for free —
+      # and one element now does the whole job two were splitting.
       def manager_row(base, row)
         name = if row[:mount]
-                 %(<a class="name" href="#{escape(base)}#{MOUNT}/#{escape(row[:mount])}/">#{escape(row[:title])}</a>)
+                 %(<a class="name" href="#{escape(base)}#{MOUNT}/#{escape(row[:mount])}/">@#{escape(row[:slug])}</a>)
                else
-                 %(<span class="name off">#{escape(row[:title])}</span>)
+                 %(<span class="name off">@#{escape(row[:slug])}</span>)
                end
         %(<li class="row" data-health="#{escape(row[:health])}">) +
-          %(<div class="who">#{name}<div class="ref"><span class="slug">@#{escape(row[:slug])}</span>) +
+          %(<div class="who">#{name}<div class="ref">) +
           # The row shows the tail; the tooltip is where the whole path stays
           # reachable, since nothing else on the page carries it.
           %(<span class="dir" title="#{escape(row[:dir])}"><bdi>#{escape(row[:dir])}</bdi></span></div></div>) +
@@ -585,7 +595,7 @@ module OKF
       # `okf registry rename` in another terminal shows on the next refresh
       # instead of waiting for a restart.
       def registry
-        @boot_registry && OKF::Registry.new(@boot_registry.path)
+        @boot_registry&.reopen
       end
 
       # ok / warn / error, with the word that carries the same message for a

data/lib/okf/skill/SKILL.md

@@ -83,10 +83,10 @@ flags. The division of labour is the whole game:
 
 - **Shell out — never eyeball —** anything a verb computes: conformance (§9), what
   exists, what links where, where a term lives, what's stale, the map. Every read
-  verb takes `--json` and the list views filter by type/area/tag, so ask the narrow
+  verb takes `--json` and the list views filter by type/dir/tag, so ask the narrow
   question instead of paging the bundle.
-- **Skeleton first, bodies last.** `index --no-body`, `search`, `graph --minimal`,
-  and `--fields` projections each answer for a fraction of a dump's bytes; full
+- **Skeleton first, bodies last.** `dirs`, `search`, `graph --minimal`, and
+  `--fields` projections each answer for a fraction of a dump's bytes; full
   bodies are the final step of a retrieval, never the first. <!-- rule:okf-skeleton-first -->
 - **You judge — the CLI can't —** meaning: contradictions, semantic staleness
   (parses fine, no longer true), whether a loose file is terminal-by-design, whether
@@ -102,12 +102,15 @@ 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|@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
-search for the word that should be there but isn't. <!-- rule:okf-orient-index -->
+Picking up a bundle you don't already know — to consume or maintain — start with
+`okf dirs <dir|@slug>`: one row per *directory*, so it stays small on a bundle of
+any size and it names the branches every other view narrows to. Then open the one
+you want with `okf index <dir|@slug> --dir <branch>` (the §6 map: that directory's
+index body, rollups, and listing), and read `log.md` (the §7 baseline of what
+changed last) — all of it **before** greping or opening leaves. Reach for `index`
+rather than grep for the one reason that outranks convenience: **grep cannot find
+an index entry that is missing**, so enumeration drift is invisible to it — you
+can't search for the word that should be there but isn't. <!-- rule:okf-orient-index -->
 Per-verb steps are in the
 playbooks (the Commands table below; no `okf` installed? read the root
 `index.md` plus each area's `index.md`).
@@ -133,7 +136,11 @@ ambiguous, ask.
 **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
+several: `@a @b`, or `@all`). A `@slug` may instead name a **group** — a saved set
+of bundles (`okf registry group backend @a @b`, members nest); it resolves like
+any ref for the two set-taking verbs (`okf search @backend`, `okf server
+@backend`) and every single-bundle verb refuses it with exit 2, the message
+saying which two take a group. 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

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

@@ -1,8 +1,8 @@
 # Playbook: consume — use a bundle as context
 
-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
+1. **Orient first** (the [SKILL.md](../SKILL.md) reflex): `okf dirs <dir|@slug>`
+   gives the shape, `okf index <dir|@slug> --dir <branch>` opens the branch you
+   want — its index body, rollups and listing — 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

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

@@ -5,8 +5,9 @@ up. Restructuring the bundle itself — moving concepts, adding areas — is
 [refine](refine.md), not maintain. The modelling craft behind steps 3 and 7
 lives in [authoring.md](../reference/authoring.md).
 
-1. **Orient before hunting.** Run `okf index <dir>` (the §6 map — every directory's
-   index body, rollups, and listings), read `log.md` (the §7 baseline: what changed
+1. **Orient before hunting.** Run `okf dirs <dir>` (the shape), then `okf index
+   <dir> --dir <branch>` on the branch the change touches (the §6 map: its index
+   body, rollups and listing), read `log.md` (the §7 baseline: what changed
    last), and `okf stats <dir>` (size and shape) *before* you grep. It is the
    cheapest context and it primes the hunt — and it is the only reliable way to
    catch enumeration drift, because **grep cannot find an index entry that is
@@ -45,7 +46,7 @@ lives in [authoring.md](../reference/authoring.md).
      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** when the pass
-   touched tags, or when `okf tags <dir>` shows a long tail of singletons. Run `okf tags <dir> --by area` and
+   touched tags, or when `okf tags <dir>` shows a long tail of singletons. Run `okf tags <dir> --by dir` 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
      adjacent). Merge into one unless each genuinely names a different theme.

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

@@ -34,8 +34,9 @@ is the lede.
      (`git status`), prefer **`maintain`**: that is exactly the drift it exists
      to close.
    - **clean, but the shape strains** — one area dwarfing the rest in
-     `okf stats`, tags spread thin across areas in `okf tags --by area`, hubs
-     whose inbound links are mostly foreign in `okf graph --hubs` → offer
+     `okf stats`, tags spread thin across dirs in `okf tags --by dir`, hubs
+     whose inbound links are mostly foreign in `okf graph --hubs`, a directory
+     with almost no internal traffic in `okf graph --traffic` → offer
      **`refine`** (evidence-driven restructuring; it proposes before it
      touches anything).
 4. **Freshness is off by default.** If the bundle carries timestamps, note that a

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

@@ -19,18 +19,25 @@ relationship rides links and tags, never new directories. And cohesion outranks
 balance — a move has semantic cost, so balance is a tiebreaker and a fatness
 alarm, never the objective. <!-- rule:okf-cohesion-over-balance -->
 
-1. **Orient.** `okf index <dir|@slug> --no-body` (areas, fan-out, depth),
-   `log.md` (how the bundle grew), `okf stats` (totals). Additive growth
+1. **Orient.** `okf dirs <dir|@slug>` (directories, fan-out, depth — and
+   `subtree` says where the weight sits), `log.md` (how the bundle grew), `okf
+   stats` (totals). Additive growth
    optimizes each pass locally, never the whole — that is the drift this
    playbook corrects.
 2. **Measure — the CLI is the evidence.** Baseline `validate` / `lint
    --stale-after` / `loose` first: refine assumes a sound bundle, and hard
    errors are [curate](curate.md)'s job. Then the two structural reads:
-   - `okf tags <dir> --by area` — each row carries `count/total`, so a tag's
+   - `okf tags <dir> --by dir` — each row carries `count/total`, so a tag's
      **locality** reads directly: a tag wholly inside one area names a *domain*
      (the directories are right); one spread across areas names a *concern*.
    - `okf graph <dir> --hubs` — concepts ranked by inbound links, each with
      the areas those links come from: the **origin test** for every hub.
+   - `okf graph <dir> --traffic` — the same question one level up. Every
+     directory's link traffic split three ways (internal / out / in) with the
+     **cohesion** ratio, and the weighted arcs between directories. `--hubs`
+     measures concepts; step 3 decides about *directories*, and this is the
+     only read at that grain. Rows lead with the lowest cohesion, so the
+     directories with a case to answer are at the top.
 3. **Diagnose — you are the judgment.** The measurements are evidence, never
    verdicts:
    - **Concerns never become containers.** A directory built around a spread
@@ -42,6 +49,26 @@ alarm, never the objective. <!-- rule:okf-cohesion-over-balance -->
      exclusive, and roughly comparable in size. And small is not merge-worthy
      on its own — a two-concept area that is a genuinely distinct domain
      stays. <!-- rule:okf-directory-prunes -->
+   - **Cohesion discriminates the low rows, which are the ones the view floats
+     to the top.** High cohesion sorts to the bottom and means the directory
+     holds together — the shape the tree exists to express, nothing to do. The
+     rows that need reading are the near-zero ones, and two shapes land there
+     together. Heavy *outbound* with almost nothing coming back is the finding: a
+     directory that points at the bundle rather than holding a part of it is
+     behaving like a projection, and this playbook's own frame says a projection
+     rides an `index.md` or a tag, never a directory — ask what would be lost if
+     its concepts moved to the areas they point at and its listing became a map.
+     Heavy *inbound* with nothing outbound is its benign twin, a **shared
+     vocabulary**: everyone cites it, it cites nobody, a reference area doing its
+     job, not a mis-homing. Same low number, opposite verdicts — the direction of
+     the traffic is which one you are looking at.
+     <!-- rule:okf-cohesion-reads-the-container -->
+     Two cautions, both of which will otherwise generate false findings. A
+     directory holding one or two concepts has too little traffic for a ratio
+     to mean anything — read the raw counts, not the percentage. And in a
+     design bundle the central `decisions/` will read low for exactly the
+     reason its concepts fail the hub origin test: that is centrality, and the
+     measurement is confirming the bundle works, not that it is broken.
    - **The hub origin test.** Inbound majority from the hub's own area:
      well-homed, leave it. A dominant *foreign* area: that area is the better
      home. Foreign majority with *no* dominant area: a shared primitive — the

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

@@ -12,12 +12,12 @@ reads, and full bodies are read last, and only the winners.
    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
-   looks right, `okf index <dir> --area <name>` buys its authored index body and
-   listing (titles + descriptions) for the price of one directory.
+2. **Ingest the map and decide where to look.** `okf dirs <dir|@slug>` is the
+   skeleton: every directory with what lives under it. *You* do the semantic
+   matching here — the question names a meaning, the map names directories;
+   connect them by judgment, not string equality. When one looks right, `okf
+   index <dir|@slug> --dir <name>` buys its authored index body and listing
+   (titles + descriptions) for the price of one directory.
    <!-- 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
@@ -52,7 +52,7 @@ reads, and full bodies are read last, and only the winners.
    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`.
+   `--dir 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