okf 1.10.0 → 1.11.0

data/lib/okf/server/app.rb

@@ -30,12 +30,57 @@ 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)
         @folder = folder
@@ -50,6 +95,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 +116,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
@@ -147,6 +201,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+.
@@ -205,6 +192,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
@@ -339,6 +332,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 +370,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
@@ -533,14 +529,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>) +

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`).

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,7 +34,7 @@ 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
+     `okf stats`, tags spread thin across dirs in `okf tags --by dir`, hubs
      whose inbound links are mostly foreign in `okf graph --hubs` → offer
      **`refine`** (evidence-driven restructuring; it proposes before it
      touches anything).

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

@@ -19,14 +19,15 @@ 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

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

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

@@ -150,7 +150,7 @@ 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*,
+body); the shared `--type/--dir/--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
@@ -273,8 +273,30 @@ there, its child directories, and the concept listing. Run it first when picking
 an existing bundle: it is the cheapest high-signal orientation, and it surfaces
 enumeration drift a grep can't (you can't grep for a listing entry that is *missing*).
 
-`--area A` narrows to a directory and is **repeatable** — `--area model --area
-format` shows both; `root` names the bundle root. `--no-body` drops the prose to a
+`--dir PATH` narrows to a directory **and everything below it**, and is
+**repeatable** — `--dir model --dir format` shows both; `root` (or `.`) names the
+bundle root. A `--dir` also brings the **chain from the root down to it**, so a branch is
+never shown adrift of the authored context that says what it is — the root
+`index.md`'s prose first among it. Those rows print with a leading `↑` and carry
+`ancestor: true`; `--no-ancestors` drops them. Ascent and descent are separate
+axes, so `--depth` never bounds the chain: `--dir X --depth 0` is X alone, plus
+how you get to X. A `--dir` that names nothing gains no chain — a lone root row
+would read as a partial answer to a query that matched nothing.
+
+`--depth N` bounds how far below the starting point the map reaches
+(the `--dir` when one is given, else the bundle root), counted **relatively**:
+`--depth 1` is the top of the tree, `--dir X --depth 1` is one branch of it, and
+the pair walks down a level at a time.
+
+**On a bundle of any size the map is unreadable whole** — every directory is a
+section, and even `--no-body` keeps one listing row per *concept* — so narrow
+rather than paging it: `okf dirs` is the orientation, `--dir <branch> --depth 1`
+is the step down into it,
+and `--except body,listing` on top of either is the lean JSON skeleton. Full
+`index` output on a few hundred concepts runs to hundreds of KB; the same map at
+`--depth 1` is a couple of KB.
+
+`--no-body` drops the prose to a
 skeleton (headers, rollups, child pointers). For a directory that has concepts but
 **no `index.md`**, the listing is **synthesized** from the concepts' descriptions
 and tagged `(no index.md)` — §6 explicitly permits synthesizing a map on the fly.
@@ -283,7 +305,49 @@ It is a **read view**: advisory, always exit 0. A synthesized directory is a
 *signal* (a map worth writing), never a defect — `index` emits no lint findings and
 never fails a bundle. JSON: `{ bundle, count, directories: [{ dir, index_path,
 present, synthesized, count, types, tags, subdirs, body, listing: [{ id, title,
-description, type, tags }] }] }`.
+description, type, tags }] }] }` — `ancestor` marks a row that is there to place
+the branch rather than to answer about it.
+
+## dirs — the bundle's clusters and their sizes
+
+`okf dirs <dir>` lists every directory the bundle has — the ones holding
+concepts, the ones carrying an `index.md`, and the empty intermediates that only
+exist to connect the tree — with the number of concepts living **directly** in
+each and the number in its **subtree**. A cluster *is* a directory here, so this
+is the view that tells you what `--dir` can be pointed at and how much sits
+behind each choice.
+
+Two numbers, because one cannot answer the question. `count` is direct, so the
+column sums to the bundle's concept total and a dir holding only sub-directories
+reads `0` rather than a hidden rollup. `subtree` is defined as *exactly what
+`--dir <that row>` returns*, so the row and the flag can never disagree — which
+is also why the root's subtree is its own direct count (`.` is a prefix of
+nothing). Without it a truncated listing is all zeroes at the top of a deep tree,
+which is where you most need to know where the mass is. The human table shows the
+second column only where some dir actually nests.
+
+`--dir PATH` (repeatable) narrows to a directory and its subtree, and brings the
+**chain up to the root** with it so the branch is placed rather than shown
+adrift — those rows are marked `↑`, carry `ancestor: true`, and stay out of
+`total` (`--no-ancestors` drops them). `--depth N` keeps only N levels below the
+starting point — the `--dir` when one is given,
+the bundle root otherwise. Relative, not absolute, so `--dir a/b --depth 1`
+reads "a/b and one level under it" without your first working out how deep `a/b`
+is. `--depth 0` is the starting point alone. A `--depth` that is not a whole
+number is a usage error (exit 2).
+
+**This is the first command to run on a bundle you do not know** — the same first
+move [SKILL.md](../SKILL.md) prescribes. `okf dirs <dir>` is one row per
+directory, so its size tracks the tree rather than the concept count: it tells
+you the shape and where the weight sits, `--depth 1` trims it further on a deep
+bundle, and you then descend with `okf index --dir`, one level at a time.
+
+The root prints `(root)` and stores `.` — the split every grouped view keeps, so
+a table and its `--json` never disagree about which spelling is the data. JSON:
+`{ bundle, total, count, dirs: [{ dir, ancestor, count, subtree, subdirs }] }`,
+root first. `count` is rows printed, chain included; `total` sums the direct
+counts of the rows you actually asked for, which is what keeps a row's `subtree`
+equal to the `total` that `--dir` on that row returns.
 
 ## catalog / files / tags / types / stats — the server views, as text
 
@@ -293,7 +357,8 @@ All are advisory reads (exit 0) sharing one data source (per-concept metadata pl
 in/out link degree). Add `--json` to any for a machine substrate.
 
 - **`catalog`** — every concept with its metadata (type, status, tags, timestamp,
-  in/out link degree, description), grouped by top-level area. The "what's here, in
+  in/out link degree, description), grouped by top-level area (`dir` on every row
+  carries the full path). The "what's here, in
   detail" view. JSON: `{ bundle, count, concepts: [{ id, title, type, description,
   tags, timestamp, status, backlog_ref, dir, area, links_out, links_in }] }`.
 - **`files`** — the folder tree: each concept's filename + title, grouped by
@@ -301,7 +366,7 @@ in/out link degree). Add `--json` to any for a machine substrate.
   id, dir, type, title, description }] }`.
 - **`tags`** — every tag with the concepts that carry it, ordered by count
   descending. The "what themes dominate" view. JSON: `{ bundle, count, tags: [{ tag,
-  count, concepts: [id, …] }] }`. `--by type|area` regroups the list per concept
+  count, concepts: [id, …] }] }`. `--by type|dir` regroups the list per concept
   dimension with **within-group** counts (a tag spanning groups appears in each);
   each row also carries the tag's **total** across the narrowed set, printed
   `count/total` when they differ — so a tag's locality reads per row (a plain
@@ -313,18 +378,32 @@ in/out link degree). Add `--json` to any for a machine substrate.
 - **`types`** — every type with the concepts that carry it, ordered by count
   descending. The "what kinds of knowledge" view. JSON: `{ bundle, count, types:
   [{ type, count, concepts: [id, …] }] }`.
-- **`stats`** — bundle rollups: concept / area / type / cross-link / distinct-tag
-  totals plus per-type and per-area breakdowns. The "shape at a glance" view. JSON:
-  `{ bundle, concepts, areas, concept_types, cross_links, distinct_tags, by_type, by_area }`.
+- **`stats`** — bundle rollups: concept / dir / type / cross-link / distinct-tag
+  totals plus per-type and per-dir breakdowns. The "shape at a glance" view. JSON:
+  `{ bundle, concepts, dirs, areas, concept_types, cross_links, distinct_tags,
+  by_type, by_dir, by_area }` (`areas`/`by_area` are the deprecated first-segment
+  cut, kept for one release). `dirs`/`by_dir` cover every directory `okf dirs`
+  lists — counts are direct, so a directory holding nothing itself is present at
+  `0` rather than missing, and `by_dir.keys` is a complete list of what `--dir`
+  can address.
 
 The four list views narrow with the same filters the browser panels offer —
-`--type TYPE`, `--area AREA`, `--tag TAG`; each takes the ones orthogonal to
-itself (`tags` can't filter by tag). Matching is case-insensitive and exact; a
-concept at the bundle root lives in the `(root)` area, which `--area` also accepts
-as plain `root` (no shell quoting). A filter that matches nothing is an empty view,
-not an error: `okf tags <dir> --area billing --json` answers "which tags does the
-billing area use?", `okf catalog <dir> --tag auth` answers "what carries the auth
-tag?".
+`--type TYPE`, `--dir PATH`, `--tag TAG`; each takes the ones orthogonal to
+itself (`tags` can't filter by tag). Matching is case-insensitive; `--type` and
+`--tag` are exact, `--dir` takes the named directory **and everything below it**
+(`--dir platform` reaches `platform/services/api`). A concept at the bundle root
+lives in `.`, which `--dir` also accepts as plain `root` (no shell quoting). A
+filter that matches nothing is an empty view, not an error: `okf tags <dir> --dir
+billing --json` answers "which tags does the billing cluster use?",
+`okf catalog <dir> --tag auth` answers "what carries the auth tag?".
+
+**`--area` is deprecated.** It still works — matching the *first path segment*
+only, its old behavior unchanged — and prints `warning: --area is deprecated, use
+--dir` on stderr (stdout stays clean, so a `--json` consumer is unaffected). Same
+for `tags --by area`. Both go in a later release; write `--dir` in anything new.
+On `index` it combines with neither `--depth` nor `--dir` — exit 2, because it is
+*exact* and both of those select a range, so the pair used to return the area
+plus whatever the other flag selected: an answer to neither question.
 
 Reach for `stats` first to size a bundle, `catalog`/`files` to enumerate it, `tags`
 to find thematic clusters — all without standing up the server.
@@ -340,10 +419,13 @@ in a body render as diagrams, and a click (or tap) opens the diagram full
 screen with drag-to-pan and wheel/pinch zoom. Concepts render as nodes
 coloured by `type` and sized by degree, links as edges, with a detail panel
 (rendered markdown, "Links to" / "Linked from" backlinks), layout switching,
-type/area/tag filters on every view, and search. The authored layer is in the
+type/dir/tag filters on every view (the dir chips take a directory *and* its
+subtree, the same rule `--dir` uses), and search. Cluster mode groups the
+concepts into one box per directory, nested to a depth picked beside the layout
+select — depth 1 is the flat view, and a flat bundle is offered no control. The authored layer is in the
 UI too: the Files view carries **Files | Indexes** tabs — the Indexes tab
 lists the log first (the chronological index), then every `index.md` — and
-folder nodes in file-tree mode and area boxes in cluster mode open a
+folder nodes in file-tree mode and directory boxes in cluster mode open a
 directory's §6 map in the inspector (authored, or synthesized when none
 exists). Links to an `index.md`, `log.md`, or bare directory navigate instead
 of dead-ending, and the log is fetched fresh on every read, so a

data/lib/okf/version.rb

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

data/lib/okf.rb

@@ -25,6 +25,15 @@ module OKF
     value.respond_to?(:empty?) ? value.empty? : false
   end
 
+  # The directory a concept lives in, derived from its §2 id: the id *is* the
+  # path minus `.md`, so putting the suffix back and taking the dirname is the
+  # definition rather than a parse of it. One home for it because three views
+  # answer with a `dir` — the catalog, the search rows, the linter's per-directory
+  # checks — and a rule spelled three times is three things to keep in step.
+  def self.dir_of(id)
+    File.dirname("#{id}.md")
+  end
+
   require "okf/version"
 
   # ── kernel: cross-cutting primitives ──

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 1.10.0
+  version: 1.11.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -54,11 +54,22 @@ dependencies:
 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
-  Ruby-native way to work with it. Its companion agent skill authors and curates
-  a bundle; the `okf` command-line tool validates the result for v0.1 (§9)
-  conformance, lints its curation quality, and serves it as an interactive graph
-  (a mountable Rack app). The same validate, lint, and graph run in-process
-  through a library API (OKF::Bundle and friends).
+  Ruby-native way to work with it.
+
+  Its companion agent skill authors and curates a bundle. The `okf` command-line
+  tool validates the result for v0.1 (§9) conformance, lints its curation
+  quality, and answers questions about it: ranked full-text search, and a
+  progressive-disclosure map that reads a large bundle a directory at a time
+  rather than loading it whole. `okf server` opens it as an interactive
+  knowledge graph and `okf render` bakes that same page into one self-contained
+  HTML file you can host anywhere. A per-user registry names your bundles, so
+  every verb reaches them by @slug from any directory and one search can span
+  them all.
+
+  Everything the CLI does also runs in-process through a library API
+  (OKF::Bundle and friends), and the graph server is a mountable Rack app. It
+  adds no service to your stack: rack, webrick and minifts are the only runtime
+  dependencies, and it runs on every Ruby since 2.4.
 email:
 - rodrigo.serradura@gmail.com
 executables:
@@ -88,6 +99,7 @@ files:
 - lib/okf/cli.rb
 - lib/okf/cli/catalog.rb
 - lib/okf/cli/command.rb
+- lib/okf/cli/dirs.rb
 - lib/okf/cli/files.rb
 - lib/okf/cli/graph.rb
 - lib/okf/cli/index.rb
@@ -160,6 +172,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: 'The complete toolkit for the Open Knowledge Format: an agent skill, a CLI
-  and library, and a live knowledge graph. 100% local.'
+summary: 'The complete Open Knowledge Format toolkit: an agent skill, a CLI and library,
+  ranked search, and a live knowledge graph. 100% local.'
 test_files: []