okf 1.7.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64b163bdb5b0e234c879f6d5424279b8b329a797292b6322af0379741e06565c
-  data.tar.gz: 816d6456345e3cd6e507be229b757f8143987ba2c98ffb1bcc26d45c19bdfba2
+  metadata.gz: 24f81d695477c347d78e44d89131ebdb7c5eec4f380c2f8ba7596292bf043e39
+  data.tar.gz: 14bc57ccda962eb9abfbcb9906e95c74b9fb808d2e46850dbfec234aafb933f7
 SHA512:
-  metadata.gz: 9ee06f232154bf609ce24882447de92f26e8a33ebddd593ff462bb83ad993d4f79c797a0c88f7647cbea9bba05b190a0b1da127e01e53d99a9b5e99d952eb76b
-  data.tar.gz: 69a26c944a1a393f7bcb58cdfd554ed1991c0617fe3fe9d7e138af7dd9847763df947d393a9cea1ff99182430b5f79b488bde78a79f0915740beab088501c4bd
+  metadata.gz: d746db4e46fd17179f8eb82275749a1a2d1077c58e0d892d2e694dcd15f052e40dfe5526e17656ba2b21adb1fc63d1fa4885d06dce44c9edb584028445703444
+  data.tar.gz: 5f41214c5b0829c6d50a99cde236d5b768256d062ea6a6faa13270bc5ab3c2416fc6ff562be34c5c7067157da36fbd91f547db4120950dc2e9a8b6376a551f8c

data/CHANGELOG.md

@@ -1,5 +1,373 @@
 # Changelog
 
+## [1.9.0] - 2026-07-19
+
+- **`okf search` gains an opt-in full-text index engine.** `--engine index` — and
+  `--fuzzy`, which implies it — routes to
+  [minifts](https://github.com/serradura/minifts), the pure-Ruby port of the same
+  MiniSearch build the graph page loads. It is the gem's third runtime
+  dependency, admitted because it costs the footprint nothing the first two were
+  chosen to protect: no native extension, no dependency tree of its own, the same
+  Ruby 2.4 floor. Three things it adds, and nothing else does:
+  - **BM25+ relevance ranking**, where the default scores by summed field weight;
+  - **`--fuzzy`** — typo tolerance at edit distance `0.2 × term length`, the
+    browser's own setting. Search stays exact unless you ask;
+  - **parity with the graph page**, which runs the same MiniSearch build, so the
+    two rank identically when the index is named.
+- **The default search is unchanged** — literal, case-insensitive substring
+  matching over the same fields with the same weights as 1.8.0. The index is
+  opt-in rather than default because a one-shot CLI builds an index, asks one
+  question, and exits: end to end, **3.00 s against 0.24 s at 1,000 concepts**,
+  the build accounting for ~95% of that. The ~44–56× per-query throughput that
+  recommends minifts is the right measure for a long-lived index — a page, a
+  server — and the wrong one for a process that exits. A cached prebuilt index is
+  what would change that arithmetic.
+  - **Know what the index costs before naming it.** Its tokenizer splits on
+    punctuation, so `customer_id` becomes `customer` + `id` and `7.2.0` becomes
+    `7`, `2`, `0`; an infix (`ustomer`) finds nothing; and a backtick is Unicode
+    `Sk` rather than punctuation, so a word inside a code span indexes as
+    `` `minifts` `` and the query `minifts` does not match it — 409 such tokens
+    on this repo's own bundle. Ranking does not rescue it: BM25 normalizes by
+    field length, so a short concept dense in `7`, `2` and `0` can outrank the one
+    that actually says `7.2.0`. The default has none of these, because raw-text
+    matching has no tokenizer.
+- **`--engine NAME` picks the engine outright**, for the case a capability flag
+  cannot express: a matching *model* requires nothing, so no flag selects one.
+  Naming an engine that cannot do what was also asked is a usage error naming one
+  that can (`--engine index -e` → *try --engine scan*), and an unknown name lists
+  what is available. `--help` reads the registry, so an addon's engine appears
+  without the CLI knowing it exists.
+- **Search engines are adapters.** `OKF::Bundle::Search` became a facade over N
+  engines instead of one class with a `regexp ? scan : index` branch. The facade
+  keeps everything that defines a result — documents, the row and its key order,
+  the snippet, the sort — and an engine answers only which documents match, how
+  well, and where. The built-ins are `Search::Scan` (raw text, the default,
+  `regexp`) and `Search::Index` (minifts, `fuzzy`/`prefix`).
+  - **Selection is by capability when the query requires one** — `--fuzzy`
+    requires `:fuzzy`, so it routes to the index without naming it — and that
+    routing prints **nothing**: no note, no header change, no new JSON key.
+  - **`Search.register` is a published extension point** — append-only,
+    idempotent by id, capabilities checked against a fixed vocabulary. This is
+    the seam a future SQLite/FTS5 addon plugs into; no addon code ships here.
+  - **A shared conformance suite replaces the "kernel is the oracle" rule**,
+    which multiple engines made impossible: the index and the scan disagree about
+    match sets by design, so neither can be the oracle. Every registered engine
+    runs the same contract, with capability-gated blocks for its own semantics,
+    and a registered engine with no conformance class fails the suite.
+- **Cross-bundle search ranks one corpus under `--engine index`.** BM25 prices a
+  term by how rare it is, so ranking each bundle separately and interleaving the
+  lists would produce a ranking that looks sorted and compares nothing; the
+  searched bundles are indexed together instead. The visible consequence, under
+  that engine only: a score is relative to the whole answer, so the same concept
+  scores lower searched beside other bundles than alone. The default's scores are
+  absolute and need no such treatment.
+
+- **The graph can draw the index layer, under any layout.** The §6 map was
+  visible only inside file-tree mode, where a folder node stood in for a
+  directory's `index.md`. **Show indexes** makes it a layer: each map is a tile
+  edged to the concepts it lists and the maps below it, dressed by the same
+  selector as file-tree mode's folder node, because the two are the same thing
+  twice over — clicking either opens that directory's `index.md`. Both are accent
+  squares with dashed edges into them, so colour separates *kinds* rather than
+  modes: a directory is not a concept and no longer reads as one. Authorship shows
+  as form — solid where an author wrote a map, hollow and dashed where the bundle
+  only implies one — so the toggle reads as curation as much as navigation.
+  - **Moving between the modes lands in one click.** Tearing the layer down ran
+    its own layout while file-tree mode ran `breadthfirst` a beat later, two
+    layouts racing the same canvas; and because the layer is fetched, a promise
+    resolving after a mode change could land inside file-tree mode. A `relayout`
+    flag settles the first, a per-toggle ticket the second.
+  - **File-tree mode disables the toggle** rather than doubling the folders it
+    already draws.
+  - **One label on every file's graph button.** It read "Explore the knowledge
+    graph" on the root index and "Open core/ in graph" on a nested one, which made
+    a single action look like three. The question is the same whatever is open, so
+    the label is too — and it lives in the markup, where it cannot go stale.
+  - **Opening a map from the reader keeps the reader's graph.** It forced
+    file-tree mode, discarding whatever layout was running, and dimmed the canvas
+    to the map's immediate neighbours. It now switches the *layer* on rather than
+    the *mode* and leaves the layout alone. A reader already in file-tree mode
+    stays there.
+  - **Selecting anything emphasises it the same way.** A concept dimmed the graph
+    to its neighbourhood, a map did nothing at all, and a folder node did nothing
+    either — three meanings for one gesture. One `focusNode` now serves all three.
+  - **Drawn, never modelled.** `index.md` is reserved, so these nodes are built
+    from `/index` straight onto the canvas; `NODES`, `/catalog` and the type and
+    tag indexes never learn they exist. Filters pass them over — a map has no type
+    or tags — but a map whose concepts are all filtered away leaves with them.
+- **Collapsing the root folds the file list away** on phones and tablets, where
+  the list is stacked on top of the reader and closing the root otherwise left a
+  single row above a column of nothing. Reopening the list undoes that collapse,
+  so it is one gesture rather than two states to dig out of — the fold remembers
+  *why* it happened, and a list folded because a file was opened comes back
+  exactly as it was left.
+- **The bundle names its own root.** `(root)` and `/` are what a filesystem calls
+  it, not what a reader does. The tree's root row, file-tree mode's root node, the
+  index layer's root map and the inspector's directory map now all carry the name
+  the page header already shows, `--title` included. `areaOf` keeps its own
+  `(root)`: that is the area vocabulary `okf stats --by area` and `tags --by area`
+  print, not a UI label.
+- **The Indexes tab dissolves into the file tree.** The authored layer lived on a
+  second tab as a flat list of paths, which put a directory's own map somewhere
+  other than the directory. `index.md` and `log.md` are rows now, at the top of
+  the folder they document, and **Indexes only** is a toggle over the same tree —
+  same rows, fewer of them, structure intact. The toggle yields only when it would
+  hide what was just opened — a map stays under it, a concept releases it — so
+  browsing the authored layer no longer destroys the list being browsed. A log
+  offers no graph button at all: it is a chronology, not a place in the graph, and
+  the button had been opening the root index's node.
+  Narrowed, a folder owns exactly one row, so the row stands where the folder
+  header stood — at that folder's depth, carrying the path — rather than nesting
+  a single child under a header.
+  - **The rail's Index becomes an action, not a fake view.** It had no
+    `#view-index` behind it — the files view showing its other tab — so
+    `activeRail()` answered a question of view *and* tab. The shortcut stays,
+    opening the root map through the same `readIndex()` the first-visit note
+    uses; `activeRail()` answers with the view it lands on, so Files highlights
+    and nothing invents a place for Index to be. `?view=index` resolves to the
+    same action.
+  - **Fixed on the way:** the reader header rendered empty — an unlabelled badge
+    and a graph button pointing nowhere — whenever no file was open, because
+    `.fp-head{display:flex}` outranks the UA sheet's `[hidden]{display:none}`.
+- **A first-visit note tells a newcomer the index exists.** The `index.md` an
+  author wrote to be read first was reachable only by finding the Indexes tab and
+  clicking a row, so a reader meeting a bundle for the first time met unlabelled
+  dots with no way in. The page still opens on the graph — it is what makes a
+  bundle legible at a glance, at every width — and a dismissible note at the
+  bottom now says what the picture is, how to touch it, and where the index is.
+  **Read the index** goes straight there; the dismissal is remembered.
+  - **It absorbed the old mobile-only tip** rather than stacking a second banner
+    under it, and it is written for a finger throughout, since a phone is where a
+    first-time reader is least oriented.
+  - **The wording follows the device on two gates, not one.** What a reader does
+    follows `(pointer:coarse)` — a touch tablet in landscape is wider than 768px
+    and still taps; a narrow desktop window is narrower and still clicks. What a
+    reader can reach follows `(max-width:768px)`, because that is when the rail
+    collapses behind `☰`. Short viewports tighten; short *and* wide puts the
+    question beside the button, taking a landscape phone from half the screen to
+    under a third.
+  - **A second note points at `☰`** on compact layouts only, anchored under the
+    button it names rather than at the bottom of the screen. It fires on leaving
+    the graph by any route, so dismissing the first note does not cost it, and
+    opening `☰` answers it — but only once it is on screen, since `☰` is the only
+    way off the graph there and the first tap always comes first.
+  - **Deep links are unaffected**, and `?select=`/`#hash` now switch to the graph
+    before selecting, since the page can be standing elsewhere when they are read.
+- **The file tree nests.** Directories were a sorted list of full paths, which
+  made `core` and `core/configurations` read as two unrelated folders and left
+  the shape of a bundle invisible. Each row is now one path segment indented by
+  depth, folders before files, and collapsing a folder takes its subtree with it.
+  A directory holding nothing but directories still renders, so the chain to its
+  children never breaks.
+  - **"Collapse all" folds into the root, not over it** — everything inside the
+    root closes and the root stays open, so the click leaves the top-level
+    folders standing instead of a single `(root)` row. Unfolding clears the whole
+    set, root included, so a root closed by hand is still reversible from there.
+
+- The graph page's search box grows a full-text index. One MiniSearch index —
+  lazy-loaded from the CDN on first search, pinned to the `7.2.0` the Ruby
+  MiniSearch port tracks so an `okf search --engine index` result and the
+  browser's rank identically — now backs the graph, catalog and files views: ranked, multi-term
+  (`AND`), prefix (as-you-type) and typo-tolerant, over title, id, type, tags and
+  **description** — plus each concept's **body** wherever the page already holds
+  it (`okf render` bakes every body in, so a static file searches bodies offline;
+  the live server keeps bodies lazy, so its index stays metadata-only until a
+  backend body index arrives). The graph could not be searched by a leaf's
+  description before; now it can. The Files view's **Indexes** tab gets its own
+  full-text index too, over each `index.md`/`log.md`'s body — not just its
+  filename. Until an index loads — or if the CDN is unreachable — each view falls
+  back to its own substring filter, so the box is never dead.
+- The Files tree's folder collapse works during a search. An active search or
+  type/tag filter used to force every folder open, so fold clicks did nothing;
+  folders now honor their collapsed state always (a collapsed group still shows
+  its header, so a match is never hidden). A **fold/unfold-all** control in the
+  Files tab header collapses or expands every visible group at once.
+- Clustering no longer leaves phantom empty boxes. When a filter or a search hid
+  every concept in an area, the cluster's labelled box lingered as an empty
+  rectangle; the box now hides when no child survives and returns when one does —
+  the same rule the fit already used to leave stale boxes out of view, now
+  applied to what is drawn.
+- `Esc` clears the graph selection. A dense graph leaves almost no empty canvas
+  to click for deselecting; `Esc` now drops the highlight (and lets the URL hash
+  forget the node) the same way tapping empty canvas does.
+- A title-less concept now wears one name in every view. `catalog` and the §6
+  index listing fell back a concept with no `title` to its full id — `area/thing`
+  — while the graph node fell back blank-aware to the basename — `thing` — so the
+  same concept answered to two labels across two views of one bundle, and a
+  `title: ""` slipped past the nil-only `||` to catalog as an empty string. Both
+  now fall back the graph's way (`File.basename`, blank-aware), so the label is
+  the same wherever the concept appears.
+- `okf render` stops baking a redundant description map. The static page derived
+  its `/node/meta` fragments from a separate `meta` payload that held nothing but
+  each concept's description, HTML-escaped — data the embedded `catalog` already
+  carries raw. The page now escapes the catalog's description on the client (the
+  same escape the server applies at `/node/meta`), so the `meta` key leaves the
+  baked payload and the description lives in one place. Both XSS guards are
+  unchanged; `okf server` is untouched.
+- The bare not-a-directory error now teaches the registry grammar. A verb given
+  a target that is neither a directory nor an `@ref` moved from
+  `error: <arg> is not a directory` to
+  `… is not a directory or a registry ref (@slug names a registered bundle, @ the default; okf registry list)`,
+  so a consumer who typed a query or a bad path meets `@slug` addressing at the
+  error instead of hunting for it. (`@all` stays out of the message — it is
+  `search`'s alone, and the error seam is shared by every verb.)
+- The bundled skill teaches `@slug` as a first-class target and stops probing for
+  the CLI. `SKILL.md`'s "Which directory?" is now "Which target?" — a leading `@`
+  is a registry ref routed straight to `okf <verb> @slug`, with the fallback
+  "no bundle in the cwd → `okf registry list`" — and the consume/search playbooks
+  name `@slug` in their orientation steps. The per-run `command -v okf` presence
+  probe is gone: run the verb, and treat a shell `command not found` as the only
+  signal to install, so the common case pays no guard round.
+
+## [1.8.0] - 2026-07-17
+
+- A persistent bundle registry and a multi-bundle hub. `okf registry`
+  (list / set / del / default / rename) keeps a per-user list in a plain JSON
+  file at `$OKF_HOME/registry.json` (default `~/.okf`), and `okf server` reads
+  its mode from its arguments: one dir is the classic single bundle at `/`,
+  several mount ephemerally behind a hub at `/b/<slug>/`, none serves the whole
+  registry with its default at `/`. Behind a hub the page gains a bundle
+  switcher (⌘/Ctrl-K, or the rail button), `/b/` is a browsable index, and an
+  unknown slug 404s as a page with a way home. The hub reads its bundles at
+  boot — restart after registry changes.
+- The registry is **ordered, and the first entry still on disk is the default** —
+  the bundle a bare `okf server` opens at `/`. `okf registry default @slug` moves
+  that entry to the front, and `okf registry set --default` registers straight to
+  it; until you do either, the first bundle you registered is the default. Nothing
+  else has to be maintained: a rename keeps its position, a `del` promotes
+  whatever is next, and the file cannot name a default that is not there. A
+  vanished directory is stepped over rather than starred — `registry list`'s `*`
+  always names the bundle `/` opens — and `registry default @slug` refuses one,
+  just as `registry set` refuses to register a directory that is not there.
+- `$OKF_HOME` is the single lever on which registry a command reads: set it and
+  every verb follows, from `okf registry list` to an `@slug` on `okf lint`. It
+  names exactly one registry, with no fallback to `~/.okf` behind it, and an
+  empty value counts as unset rather than planting `registry.json` in the
+  current directory.
+- `@slug`: wherever a command takes a `<dir>`, `@slug` names a registered
+  bundle and bare `@` the registry default — `okf lint @handbook`,
+  `okf render @ -o graph.html`. A slug is normalized like registration was
+  (`@One` finds the bundle from dir `One`) but never to a placeholder, so
+  `@***` is a bad ref rather than a silent hit. An unknown slug, a
+  registered-but-gone directory, or a malformed registry file is a usage error
+  naming the registry file and the next move. A hub built from `@slug`s
+  (`okf server @a @b`) mounts each bundle under its registered slug, the first
+  at `/`, and a registered slug reserves its mount ahead of any plain
+  directory that shares the name.
+- `@slug` is spelled where it is used, not just where it is explained, and it is
+  the one token — `okf help`'s map (`lint <dir|@slug>`) and each command's own
+  banner show it the same way, with a note under the map defining it: the slug
+  from `okf registry set`, or bare `@` for the default. It was documented once,
+  in prose at the foot of `okf help`, past where a reader who already knows the
+  verb ever looks, so seventeen surfaces took a registered bundle while
+  advertising a bare `<dir>`. The registry-editing verbs — `del`, `default`,
+  `rename` — take the slug bare (no `@`) or as an `@slug`; the read verbs need
+  the `@`, since a bare word there is a path.
+- `okf <command> -h` prints that command's own banner and flags. Help now answers
+  on stdout with an exit code like every other command: it was OptionParser's
+  officious handler, which printed past the caller's injected streams and ended
+  the process with `exit` instead of returning a status.
+- `okf search` spans bundles: several leading `@slug`s, or `@all` for every
+  registered one. Rankings merge across bundles with every row labeled by its
+  bundle's slug (a `bundles` list and a per-match `slug` key in the JSON).
+  Asking for everything tolerates gaps — `@all` skips a bundle whose directory
+  has vanished, with a note — while naming one insists on it, and `@all @docs`
+  simply dedupes. `all` is reserved *in the registry*, on all three ways in: a
+  directory named `all/` registers as `all-2`, `--as all` is refused, and a row
+  already claiming the name in the registry file — hand-typed, or written before
+  the name was reserved — is read as `all-2`, so the reservation never strands a
+  registry it inherited. An ephemeral `okf server ./all` still mounts at
+  `/b/all/` — no registry, no refs, nothing to reserve.
+- The registry validates its file's shape, not just its JSON syntax: a
+  hand-edited entry missing `path` is a usage error naming the file instead of
+  a `TypeError`, and `okf registry --json set <dir>` — a subcommand behind a
+  flag — is a usage error rather than silently listing and exiting 0.
+- The graph page's ⌘/Ctrl-K palette opens in **every** mode and reaches a view as
+  well as a bundle. It was wired only behind a hub, so a standalone
+  `okf server ./docs` and every `okf render` page — the two modes most people meet
+  first — had no palette at all. Bundles still lead it and own the empty box,
+  because switching bundles is what it is for; views wait until what you type
+  reaches one, arrive underneath, and stay muted until the cursor does. Each view
+  carries the rail's own icon and label, read from the rail so the two cannot
+  drift. Where there is no hub there is no bundle to switch to, and views become
+  the whole list.
+- The inspector's type and tags are filter handles: clicking one focuses the
+  graph on that facet — the same jump the stats bars make — and clicking it again
+  clears it. The chip lights while its facet is the only filter in play, which is
+  exactly when a second click is an undo, so what you see and what the next click
+  does are the same question. With another filter set it re-focuses instead,
+  rather than throwing away more than the click put there.
+- The inspector's *Links to* / *Linked from* rows read as concepts rather than a
+  wall of accent-coloured text. Each carries its type's dot — the colour that node
+  already wears in the graph beside it — with the type named and the section
+  counted, so the column answers what kind of neighbourhood a concept has before a
+  title is read. The rows share one panel with hairline dividers and a hover fill:
+  the container carries the click affordance, which leaves colour free to mean type
+  and nothing else.
+- The inspector's widen chevron splits the screen instead of taking 70% of it. The
+  panel drag-resizes, so the chevron is a preset rather than a maximum, and burying
+  the graph to read one concept was the wrong thing to default to.
+- The graph page answers `?` with a sheet of every keyboard shortcut, reachable
+  from a rail button too — a shortcut list you can only open with a shortcut helps
+  whoever needs it least. `/` focuses the current view's search where it has one,
+  skipping the view that only reads; the sheet is written against the key handler
+  it documents, since a shortcut list that has drifted is worse than none.
+- Fixed: a file the reader could not **open** (permissions) threw its errno out
+  of the read, so a single locked file took the whole bundle down through every
+  verb that reads one — `lint`, `validate`, `catalog`, `server`, `registry set`
+  — as a backtrace, under an exit code claiming the bundle was non-conformant.
+  §9's best-effort promise covers it now, the same as frontmatter that will not
+  parse: the file is skipped, noted on stderr, and reported by `validate` under
+  §9.1 naming the file and the errno. One bad file never breaks the rest.
+  The stderr note reads `skipped N unusable file(s)` — it counts two kinds now,
+  so it names neither and points at `validate`, which names both.
+
+- Fixed: `okf registry del <path>` could delete the wrong bundle. A path that
+  matched no registered directory fell through to a normalized *slug* lookup, so
+  `del ./notes` — naming a local directory — removed whichever entry happened to
+  be slugged `notes`, wherever it pointed, and reported `removed notes` with exit
+  0. An argument with a `/` in it now names a location and only a location.
+- Fixed: the registry read trusted stored slugs verbatim while both write paths
+  normalized, so a hand-typed `"slug": "My Docs"` listed fine but could not be
+  named by `@my-docs`, `registry rename`, or `registry default` — the verbs that
+  could repair it were the ones that could not see it. The read normalizes now,
+  leaving an already-usable slug untouched. This also removes the only way a
+  quote could reach a slug, and with it a DOM XSS in the server's bundle
+  switcher, whose JS escape covered `& < >` but not quotes; the escape now covers
+  quotes too, so the page does not depend on a guarantee three layers away.
+- Fixed: `okf lint` bucketed a whitespace-only `type` under its own literal
+  heading while `types`/`graph`/`stats` bucketed it as `Untyped`, so two verbs
+  reported type inventories for the same bundle that would not reconcile. §9.2
+  makes a blank type as non-conformant as a missing one; both sides say so now.
+- Fixed: `okf search <dir> --fields slug` passed the field guard and returned one
+  empty object per match with exit 0. Only registry mode labels rows with a slug,
+  so the two modes now declare the shape each actually emits and a path-named
+  search names the fields it does have.
+- Fixed: `okf registry set` reported `(0 concepts)` for a bundle whose files it
+  could not read; it notes the skipped files like every other reading verb.
+  `okf registry rename DOCS handbook` echoed the argv rather than the slug it
+  renamed, naming a bundle that never existed. An unwritable `$OKF_HOME` raised
+  a bare `Errno::EACCES` at exit 1 instead of a usage error at exit 2.
+- Fixed: a long path in the Files view's Indexes tab pushed its `map`/`log` badge
+  past the right edge of the list. The badge was already pinned and unshrinkable;
+  the filename beside it was the problem — a bare text node, and an anonymous flex
+  item's automatic minimum size is the full width of its text, so it refused to
+  give way and drove the badge out instead. It truncates now, with the full path on
+  hover. Only a wide enough path in a narrow enough pane reached it, which is why
+  it never showed on mobile, where the list runs full width.
+- Fixed: the bundle switcher scrolled its own first row out of view as it opened.
+  It rendered, and scrolled the active row into view, while the dialog was still
+  hidden — and a list that is not being displayed measures zero, so the scroll
+  landed arbitrarily.
+- Fixed: the `3` (Files) shortcut did nothing once the Indexes tab was open, and
+  the palette's Index row would have blanked the page. "Index" is not a view —
+  there is no `#view-index`, only the Files view showing its Indexes tab — so
+  `setView('files')` from that tab early-returned, and `setView('index')` named a
+  view that does not exist. The keyboard and the palette each re-implemented what
+  the rail button already did right; both now click the rail item, so the one
+  correct path is the only one, and the palette's `current` badge reads the same
+  active-tab answer the rail's own highlight does.
+
 ## [1.7.0] - 2026-07-16
 
 - `okf server`: responses are gzipped when the client accepts it

data/README.md

@@ -35,7 +35,7 @@ The package, end to end:
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset=".github/overview-dark.png">
-    <img src=".github/overview-light.png" width="760" alt="The package: the Agent Skill (your coding agent authors and curates, you stay the editor) writes and maintains the bundle, a folder of Markdown + YAML in your repo where one concept is one file and links between files are the knowledge graph. The bundle is read by the CLI/Lib (validate: legal OKF per section 9; lint: well-curated and fresh; search: ranked retrieval; require okf for Ruby objects) and by the Graph, in three modes: okf server (a live local server), okf render (the same page exported as one static, self-contained HTML file you can host anywhere), and OKF::Server::App (the Rack app mounted in a Rails route). One gem, 100% local, Ruby 2.4 or newer, only rack and webrick as dependencies.">
+    <img src=".github/overview-light.png" width="760" alt="The package: the Agent Skill (your coding agent authors and curates, you stay the editor) writes and maintains the bundle, a folder of Markdown + YAML in your repo where one concept is one file and links between files are the knowledge graph. The bundle is read by the CLI/Lib (validate: legal OKF per section 9; lint: well-curated and fresh; search: ranked retrieval; require okf for Ruby objects) and by the Graph, in four modes: okf server (a live local server), okf render (the same page exported as one static, self-contained HTML file you can host anywhere), okf registry (every registered bundle behind one hub), and OKF::Server::App (the Rack app mounted in a Rails route). One gem, 100% local, Ruby 2.4 or newer, only rack, webrick and minifts as dependencies.">
   </picture>
 </p>
 
@@ -44,13 +44,20 @@ command-line tool (the library API is also usable in-process). Each capability
 below links to the concept that documents it: this gem's own knowledge is an OKF
 bundle, so you can read its design in the format it defends.
 
-| Capability                                                | What it answers                   | Verb                |
-| --------------------------------------------------------- | --------------------------------- | ------------------- |
-| [Companion agent skill](.okf/capabilities/agent-skill.md) | Can an agent author it?           | `skill`             |
-| [Conformance validator](.okf/capabilities/validator.md)   | Is this a legal OKF bundle? (§9)  | `validate`          |
-| [Curation linter](.okf/capabilities/linter.md)            | Is it navigable, complete, fresh? | `lint` / `loose`    |
-| [Interactive graph](.okf/capabilities/graph-server.md)    | Explore it — live or static?      | `server` / `render` |
-| [Library API](.okf/capabilities/library-api.md)           | Can my Ruby program use it?       | in-process          |
+| Capability                                                    | What it answers                   | Verb             |
+| ------------------------------------------------------------- | --------------------------------- | ---------------- |
+| [Companion agent skill](.okf/capabilities/agent-skill.md)     | Can an agent author it?           | `skill`          |
+| [Conformance validator](.okf/capabilities/validator.md)       | Is this a legal OKF bundle? (§9)  | `validate`       |
+| [Curation linter](.okf/capabilities/linter.md)                | Is it navigable, complete, fresh? | `lint` / `loose` |
+| [Ranked text search](.okf/capabilities/search.md)             | Which concept covers X?           | `search`         |
+| [Interactive graph server](.okf/capabilities/graph-server.md) | Can I explore it visually?        | `server`         |
+| [Static render](.okf/capabilities/render.md)                  | Can I ship a serverless snapshot? | `render`         |
+| [Library API](.okf/capabilities/library-api.md)               | Can my Ruby program use it?       | in-process       |
+
+And because knowledge rarely lives in one bundle, a per-user
+[registry](.okf/registry.md) gives each bundle a name: `okf registry set ./docs`
+once, then `@docs` works anywhere a `<dir>` does — from any directory — and a
+bare `okf server` hosts every registered bundle behind one hub.
 
 > [!TIP]
 > **Browse the gem as knowledge, not just docs.** This README is the front door;
@@ -65,10 +72,13 @@ It is deliberately light so it runs on the Ruby your OS already ships:
 
 - works on every Ruby since 2.4, the same floor as [rack](https://github.com/rack/rack),
   its core dependency;
-- only two runtime dependencies: `rack` (the server is a mountable Rack app)
-  and `webrick` (unbundled from Ruby in 3.0);
-- no ActiveSupport, no build step, no JavaScript toolchain — the
-  [design constraints](.okf/design/) that hold this line are enforced by tests.
+- only three runtime dependencies: `rack` (the server is a mountable Rack app),
+  `webrick` (unbundled from Ruby in 3.0), and
+  [`minifts`](https://github.com/serradura/minifts) (the search engine — pure
+  Ruby, no dependencies of its own, same 2.4 floor);
+- no ActiveSupport, no native extension, no build step, no JavaScript
+  toolchain — the [design constraints](.okf/design/) that hold this line are
+  enforced by tests.
 
 That range is not aspirational: CI runs the full test suite and RuboCop on every
 one of these on each push.
@@ -218,7 +228,7 @@ docker run --rm -v "$PWD:/data" -p 8808:8808 ghcr.io/serradura/okf server . --bi
 Then open <http://127.0.0.1:8808>. Images are published for `linux/amd64` and
 `linux/arm64` on
 [ghcr.io](https://github.com/serradura/okf-gem/pkgs/container/okf): `:latest`
-tracks the newest release, or pin a version like `:1.5.0`.
+tracks the newest release, or pin a version like `:1.9.0`.
 
 Tired of the long line? Install a Docker-backed [`okf` command](https://docker.okfgem.com),
 so every verb drops the `docker run` prefix and reads exactly like the native CLI
@@ -237,15 +247,30 @@ instead: `irm https://docker.okfgem.com/install.ps1 | iex`.
 ## Command line
 
 ```bash
-okf validate  <dir> [--json]                            # check OKF v0.1 conformance (§9)
-okf lint      <dir> [--json] [--fail-on warn] [...]     # report curation-quality issues
-okf loose     <dir> [--json]                            # list files with no graph links, by folder
-okf search    <dir> <term…> [-e] [--in a,b] [...]       # ranked text retrieval across metadata + bodies
-okf index     <dir> [--json] [--area A] [--no-body]     # progressive-disclosure map (§6): bodies, rollups, listings
-okf server    <dir> [-p PORT] [--bind ADDR] [...]       # serve the interactive graph over HTTP
-okf render    <dir> [-o FILE] [--layout NAME] [...]     # export the graph as one static, self-contained HTML file
-okf graph     <dir> [--json] [--minimal] [--no-body]    # print the knowledge graph
-okf catalog | files | tags | types | stats  <dir> [--json]   # the browser views, on the CLI
+okf validate  <dir|@slug> [--json]                         # check OKF v0.1 conformance (§9)
+okf lint      <dir|@slug> [--json] [--fail-on warn] [...]  # report curation-quality issues
+okf loose     <dir|@slug> [--json]                         # list files with no graph links, by folder
+okf search    <dir|@slug…|@all> <term…> [-e|--fuzzy] [...] # ranked retrieval; @slugs or @all span bundles
+okf index     <dir|@slug> [--json] [--area A] [--no-body]  # progressive-disclosure map (§6): bodies, rollups, listings
+okf server    [DIR|@slug…] [-p PORT] [--bind ADDR] [...]   # serve one bundle, or many behind a hub (⌘K to switch)
+okf render    <dir|@slug> [-o FILE] [--layout NAME] [...]  # export the graph as one static, self-contained HTML file
+okf registry  list [--json]                                # list registered bundles (* marks the default)
+okf registry  set <dir|@slug> [--as SLUG] [--default]      # add or update a bundle (a bare `server` serves it)
+okf registry  del <dir|@slug>                              # remove a bundle from the registry
+okf registry  default <@slug> | rename <@slug> <new>       # move a bundle to the front (the default) / rename it
+
+# The registry is a plain JSON file at $OKF_HOME/registry.json (default ~/.okf).
+# It is ordered, and the first entry is the default: `registry default @slug`
+# moves that entry to the front. The subcommand leads and flags follow it:
+# `registry set <dir> --as X`, never `registry --json set <dir>`.
+# A running server reads it at boot — restart after changes.
+# Behind a multi-bundle server, /b/ lists every bundle and ⌘/Ctrl-K switches.
+# @slug names a registered bundle instead of a path — the slug from `registry
+# set`, or bare @ for the default. Anywhere a <dir> goes, an @slug goes:
+# okf lint @handbook works from anywhere. Set $OKF_HOME to point every verb
+# at another registry.
+okf graph     <dir|@slug> [--json] [--minimal] [--no-body]        # print the knowledge graph
+okf catalog | files | tags | types | stats  <dir|@slug> [--json]  # the browser views, on the CLI
 okf skill     <dest> [--here] [--force]                 # install the companion agent skill
 okf --version
 ```
@@ -276,10 +301,39 @@ _The graph server on this repo's own [`.okf`](.okf) bundle, with the
 `capabilities/graph-server` concept selected. Try it live at
 **[demo.okfgem.com](https://demo.okfgem.com)**._
 
+The page is one template from a phone to a desktop: on small screens the
+navigation rail becomes a drawer, the toolbar folds into a `⚙` sheet, and the
+panels go full-bleed — rotate a tablet and the layout re-evaluates. It is
+keyboard-first too: `⌘/Ctrl-K` opens a command palette in every mode (views
+always; bundles too when a [hub](#one-registry-many-bundles) is serving), `/`
+jumps to the current view's search, and `?` answers with a sheet of every
+shortcut.
+
 To skip the server entirely, **`okf render <dir>`** writes that same page as one
 self-contained HTML file, the whole bundle baked in, so you can publish the
 graph on GitHub Pages or any static host.
 
+### One registry, many bundles
+
+The [registry](.okf/registry.md) is a per-user, ordered list of bundles in one
+plain JSON file (`$OKF_HOME/registry.json`, default `~/.okf`) — hand-editable,
+greppable, no database. It stores references, never content: the bundles stay in
+the repos that own them.
+
+```bash
+okf registry set ./docs --as handbook   # give the bundle a name
+okf lint @handbook                      # @slug works wherever a <dir> does, from anywhere
+okf search @all rate limit              # ranked retrieval across every registered bundle
+okf server                              # no args: the whole registry behind one hub
+```
+
+The first entry still on disk is the **default** — the bundle a bare `okf
+server` opens at `/` and a bare `@` names; `okf registry default @slug` moves an
+entry to the front. Behind the hub each bundle mounts at `/b/<slug>/`, `/b/` is
+a browsable index, and the `⌘/Ctrl-K` palette switches bundles without leaving
+the page. The hub reads the registry at boot, so restart it after registry
+changes; set `$OKF_HOME` to point every verb at a different registry.
+
 `graph` and `server` are best-effort (§9): a file with invalid frontmatter is
 skipped (and noted on stderr), not fatal, so one bad file never breaks the rest.
 The [graph server](.okf/capabilities/graph-server.md) concept walks the request
@@ -519,8 +573,8 @@ ruby -Ilib exe/okf validate <dir>   # run the CLI from a checkout
 The suite runs on every supported Ruby; to check the 2.4 floor locally:
 
 ```bash
-docker run --rm -v "$PWD":/app -w /app ruby:2.4 \
-  bash -c "bundle install && bundle exec rake test"
+docker run --rm -v "$PWD":/src:ro ruby:2.4 bash -c \
+  "cp -a /src /build && cd /build && rm -f Gemfile.lock && bundle install --quiet && bundle exec rake test"
 ```
 
 ## Contributing

data/lib/okf/bundle/folder.rb

@@ -50,12 +50,29 @@ module OKF
         @bundle.directory_index
       end
 
+      # Every log.md with its content, root scope first — read live from disk so a
+      # just-appended entry shows without a reload; the reserved snapshot is the
+      # fallback if the file has since vanished. Shared by `okf render`'s bake
+      # (OKF::Render::Graph.payload) and OKF::Server::App's /log endpoint.
+      def log_entries
+        @bundle.log_files.sort_by { |path| [ path == "log.md" ? 0 : 1, path ] }.map do |path|
+          { path: path, dir: File.dirname(path), content: log_content(path) }
+        end
+      end
+
       # Human-readable "parent/dir" name — the default HTML title.
-      def name
-        pathname = Pathname.new(@root)
+      # The bundle's display label, "parent/dir" — path arithmetic, no disk. It
+      # is a class method so a caller that only wants the label (the registry
+      # naming an entry) can have it without a Reader.read of every file.
+      def self.label(root)
+        pathname = Pathname.new(root)
         "#{pathname.parent.basename}/#{pathname.basename}"
       end
 
+      def name
+        self.class.label(@root)
+      end
+
       # A single-file handle for one concept id (read live from disk), or nil when no
       # concept in the loaded bundle has that id. The id may be a frontmatter `id`, so
       # it is resolved to a path through the bundle rather than assumed to be "id.md".
@@ -89,6 +106,12 @@ module OKF
                .select { |entry| File.basename(entry.path) == basename }
                .each_with_object({}) { |entry, hash| hash[entry.path] = entry.content }
       end
+
+      def log_content(path)
+        File.read(File.join(@root, path), encoding: "UTF-8")
+      rescue SystemCallError
+        @bundle.reserved_content(path)
+      end
     end
   end
 end

data/lib/okf/bundle/graph.rb

@@ -86,8 +86,12 @@ module OKF
         concept.tags.is_a?(Array) ? concept.tags : []
       end
 
+      # Blank, not just nil: §9.2 makes a whitespace-only `type` as non-conformant
+      # as a missing one (the validator says so with the same OKF.blank?), so the
+      # index must not sort them into different buckets. Otherwise `type: "  "`
+      # earns its own row, labelled with spaces, next to Untyped.
       def self.default(value, fallback)
-        value.nil? ? fallback : value.to_s
+        OKF.blank?(value) ? fallback : value.to_s
       end
 
       def initialize(nodes:, edges:, type_index: {}, tag_index: {})

data/lib/okf/bundle/linter.rb

@@ -290,7 +290,12 @@ module OKF
         @report.stat(:backlog, count_findings(:missing_concept))
         @report.stat(:components, components.size)
         @report.stat(:hubs, hubs)
-        @report.stat(:types, frequency(@concepts.map { |c| c.type || "Untyped" }))
+        # Through Graph.default, not a second `|| "Untyped"`: §9.2 makes a
+        # whitespace-only type as non-conformant as a missing one, so the two must
+        # land in one bucket. Spelling the rule twice is how lint came to report a
+        # `"  "` bucket that `types` and `graph` had never heard of — the same
+        # concepts counted by both verbs, into inventories that will not reconcile.
+        @report.stat(:types, frequency(@concepts.map { |c| Graph.default(c.type, "Untyped") }))
         @report.stat(:tags, frequency(@concepts.flat_map { |c| c.tags.is_a?(Array) ? c.tags : [] }))
       end