okf 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3df6877dab7b0fa0bd7353d288b9bbec2657056744ad9d5513c1817921659875
-  data.tar.gz: 68f3b956056874fac093ec3114eea5ba420173727458ae1d97c562c3c22ff28c
+  metadata.gz: 45d6619cf9144fbaf4026e51ad238213e916c6796ffd1199d189d6b64c47352e
+  data.tar.gz: c26b86f1b2173feefd02159a2dd280f93a4e8ee915eb077ef49558fced6c8ac3
 SHA512:
-  metadata.gz: 2e9da0cf2f912c2473302266307e0180ac038c97c75636f06299e7b25adeb64cb38220f755bf4101bee6edbdb52ae9a4cb696b2b14f2c8b54dd28ce3225d4b5c
-  data.tar.gz: 0eb35fde3097549a55fde740816178d830628ade3639a356e1e2eea5e195ee3ea28b321ccb4bd9211284103a90c5ab33830fb1218a298034788d258a06cf5dab
+  metadata.gz: 254038bdb6383fe94882793c6b2d2433917536793670d23fad1be4c2678e9a8c042164c997ba8ae64950ced447ca850e4263bb1eee9ab2230b33b2b83f8efd94
+  data.tar.gz: 1ada5ef52a4848d340619a1ccf10bc35ddbae7504c3e53cc447f824e44f90d145579a024ae17c15c38eb84cc0592353b20967adda709c631a38a298161e6f99f

data/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog
 
+## [1.6.0] - 2026-07-15
+
+- New CLI verb: `okf render <dir> [-o FILE]` — the live graph as one static,
+  self-contained HTML file, so it hosts where a server can't (GitHub Pages, an
+  object store, an attachment). It is the same page `okf server` serves, one
+  switch apart: the browser's five on-demand reads — bodies, descriptions,
+  catalog, index, logs — now route through named getters that resolve from an
+  injected `EMBED` payload instead of the network, so the whole bundle rides
+  inside the file with no server and no build step. Prints to stdout (`okf
+  render docs > public/index.html`) or writes `-o FILE`. The embedded data is
+  `</script>`-escaped exactly like the boot payload and every body still renders
+  through `DOMPurify.sanitize(marked.parse(...))`, so the trust boundary holds;
+  the trade-off is weight — each body is inlined, so a big bundle makes a big
+  file, and `okf server` stays the choice at scale.
+- Official Docker image: `ghcr.io/serradura/okf`, a portable CLI that runs every
+  `okf` command (the graph server included) with no Ruby on the host. It is built
+  from source and published multi-arch (`linux/amd64`, `linux/arm64`) to the
+  GitHub Container Registry on each release tag, so the image always matches the
+  gem. Mount a bundle at `/data`; for `server`, add `--bind 0.0.0.0` and publish
+  `-p 8808:8808`. See the README's Docker section.
+
+## [1.5.0] - 2026-07-13
+
+- New CLI verb: `okf search <dir> <term…>` — deterministic ranked retrieval
+  over concept metadata *and bodies*, the browser page's search brought to the
+  CLI. Terms AND together as case-insensitive substrings, or as Ruby regexps
+  with `--regexp`/`-e`; `--in` restricts the searched fields; the shared
+  `--type/--area/--tag` filters and `--fields/--except` projections apply.
+  Matches rank by where they hit (title > id > tags > type/description > body)
+  and carry a bounded context snippet, so "which concept covers X?" costs a
+  few rows instead of a body read. Advisory read: exit 0 even with no matches.
+  Deliberately not fuzzy — the consuming agent is the fuzzy layer.
+- The skill learns retrieval as a first-class verb: a new `search` playbook
+  (progressive disclosure end to end: ingest `okf index`, decide where to
+  look, cut across with `okf search`, read only the winning bodies),
+  search-aware routing in SKILL.md and the menu/consume playbooks, and
+  `/okf:gem search <query>` first in the Claude Code plugin's routing.
+- Retrieval eval in the suite: the progressive path (index skeleton → search →
+  one body) must answer a planted question in under 25% of the bytes of the
+  full graph dump, so the playbook's economics stay true by construction.
+- Graph server: the authored layer joins the UI. The Files view carries two
+  tabs — **Files** (the per-directory concept groups, foldable) and
+  **Indexes** (the log first, as the chronological index, then every
+  `index.md`, root before nested) — with the files filters moved up into the
+  top bar. The rail's **Index** item, the `2` key, and `?view=index` are
+  shortcuts straight to the Indexes tab. Folder nodes in file-tree mode and
+  area boxes in cluster mode are clickable and open that directory's §6 map
+  in the inspector (authored, or the synthesized listing when none exists).
+  Links to an `index.md`, a `log.md`, or a bare directory (`model/`) navigate
+  everywhere a body renders instead of striking through as dead, and the log
+  is fetched fresh on every read, so a just-appended entry shows without a
+  restart. A reserved file's "Open in graph" jumps to its folder in the file
+  tree, map in the inspector. New `/index` and `/log` endpoints back it all.
+- Graph server: Mermaid diagrams in concept bodies are click-to-inspect. A
+  click (or tap) opens the diagram full screen — drag to pan, wheel or pinch
+  to zoom, buttons and double-click reset, Esc closes — powered by
+  [Panzoom](https://github.com/timmywil/panzoom), lazy-loaded from the CDN
+  exactly like Mermaid itself.
+- The Claude Code plugin's `/okf:gem` command now weighs the shape of a
+  free-form ask: a question about what the bundle knows routes through the
+  search playbook and answers from retrieved concepts instead of guessing.
+- Skill efficiency audit: every playbook now takes the CLI's lean paths.
+  `maintain` hunts affected concepts with `okf search` and pulls edges via
+  `graph --json --minimal` instead of the full-body dump, `menu` reads the
+  plain-text reports it only scans, and SKILL.md pins the discipline as a
+  rule: skeleton first, bodies last.
+- Docs: the CLI reference's server section now reflects the DOMPurify
+  sanitization that landed in 1.1.0 (it still said bodies render unsanitized),
+  and the server page's link-preview image points at the renamed
+  `okfgem.com/og-demo-v2.png`.
+
 ## [1.4.0] - 2026-07-12
 
 - Graph server UX round. Selecting a node now makes one camera move instead of

data/README.md

@@ -2,7 +2,7 @@
   <a href="https://okfgem.com">
     <picture>
       <source media="(prefers-color-scheme: dark)" srcset=".github/hero-dark.png">
-      <img src=".github/hero-light.png" width="100%" alt="okf-gem: your project's knowledge as a living graph. A lightweight Ruby gem for the Open Knowledge Format that authors, curates, and serves bundles of Markdown + YAML as an interactive graph.">
+      <img src=".github/hero-light.png" width="100%" alt="okf-gem: the complete harness for the Open Knowledge Format. An Agent Skill, a CLI and library, and a Graph let your agent author, curate, and consume your project's knowledge. 100% local.">
     </picture>
   </a>
 </p>
@@ -10,6 +10,7 @@
 <p align="center">
   <a href="https://rubygems.org/gems/okf"><img src="https://img.shields.io/gem/v/okf" alt="Gem version"></a>
   <a href="https://rubygems.org/gems/okf"><img src="https://img.shields.io/gem/dt/okf" alt="Downloads"></a>
+  <a href="https://github.com/serradura/okf-gem/pkgs/container/okf"><img src="https://img.shields.io/badge/ghcr.io-okf-2496ED?logo=docker&logoColor=white" alt="Docker image"></a>
   <a href="https://github.com/serradura/okf-gem/actions/workflows/main.yml"><img src="https://github.com/serradura/okf-gem/actions/workflows/main.yml/badge.svg" alt="CI"></a>
   <a href="https://github.com/serradura/okf-gem"><img src="https://img.shields.io/badge/ruby-%3E%3D%202.4-black" alt="Ruby >= 2.4"></a>
   <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache-2.0"></a>
@@ -18,26 +19,23 @@
 </p>
 
 <p align="center">
-  <b><a href="https://okfgem.com">Website</a></b> &nbsp;·&nbsp;
+  <b><a href="https://okfgem.com">Site</a></b> &nbsp;·&nbsp;
+  <b><a href="https://okfgem.com/docs/">Docs</a></b> &nbsp;·&nbsp;
   <b><a href="https://demo.okfgem.com">Live demo</a></b> &nbsp;·&nbsp;
-  <b><a href="https://claude.okfgem.com">Claude Code plugin</a></b>
+  <b><a href="https://claude.okfgem.com">Claude plugin</a></b> &nbsp;·&nbsp;
+  <b><a href="https://docker.okfgem.com">Docker image</a></b>
 </p>
 
-**okf-gem** — `okf` on RubyGems — reads, validates, lints, and serves
-**Open Knowledge Format (OKF)** v0.1 bundles: directories of Markdown files with YAML frontmatter that humans and agents read from one source. It does not define a new place to keep knowledge; it gives you leverage over knowledge that already lives as Markdown. Each file is a _concept_; a directory of them is a _bundle_.
+**okf-gem** (`okf` on RubyGems) is the complete harness for
+**Open Knowledge Format (OKF)** v0.1 bundles: create, maintain, and consume
+your project's knowledge with your agent. The package is **Agent Skill + CLI/Lib + Graph**: an agent skill that authors and curates, a CLI and Ruby library that validate, lint, search, and embed, and a graph to explore, live or static, in one gem that runs 100% local. A bundle is a directory of Markdown files with YAML frontmatter that humans and agents read from one source; each file is a _concept_. The gem does not define a new place to keep knowledge; it gives you leverage over knowledge that already lives as Markdown.
 
-> **Quick start.** One skill, one command, a curation hook, and a CLI that
-> validates, lints, indexes, and serves your Markdown as a graph. In Claude Code,
-> add the plugin and let it set everything up: `/plugin marketplace add
-serradura/okf-gem`, then `/plugin install okf@okfgem`, then `/okf:gem`. On the
-> command line: `gem install okf`, then `okf validate <dir>`.
-
-Here is what it is able to do:
+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="100%" alt="The companion agent skill authors and curates an OKF v0.1 bundle (Markdown + YAML). A pure model (Concept, Bundle, Graph) reads that bundle and feeds both the okf CLI (validate — legal per §9; lint — well-curated; server — explore) and a library API you embed in Ruby.">
+    <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.">
   </picture>
 </p>
 
@@ -46,13 +44,13 @@ 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 server](.okf/capabilities/graph-server.md) | Can I explore it visually?        | `server`         |
-| [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`    |
+| [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          |
 
 > [!TIP]
 > **Browse the gem as knowledge, not just docs.** This README is the front door;
@@ -90,18 +88,21 @@ work with it.
 Knowledge already has several homes near an agent, and each holds a different
 thing. None of the others is built for curated, durable team knowledge:
 
-|                                | OKF bundle (this)                               | `CLAUDE.md` / `AGENTS.md`  | Agent auto-memory        | Wiki / Notion    |
-| ------------------------------ | ----------------------------------------------- | -------------------------- | ------------------------ | ---------------- |
-| Holds                          | curated team knowledge                          | standing instructions      | what one agent picked up | human docs       |
-| Versioned with the code        | ✅                                              | ✅                         | ❌                       | ❌               |
-| Portable across agents         | ✅ plain Markdown + YAML                        | ⚠️ per-harness conventions | ❌ per-agent store       | ⚠️ export needed |
-| Typed and queryable            | ✅ frontmatter + graph                          | ❌ prose                   | ❌                       | ⚠️ partially     |
-| Reviewed in PRs                | ✅                                              | ✅                         | ❌ implicit              | ⚠️ rarely        |
-| Scales past one context window | ✅ progressive disclosure (`okf index`)         | ❌ loaded whole            | ⚠️ partially             | n/a              |
-| Checked by tooling             | ✅ (`okf validate` + `lint`), exit codes for CI | ❌                         | ❌                       | ❌               |
-
-The last row is this gem's job. The other homes have no detector, so their
-drift stays invisible; a bundle's drift shows up as findings you can gate on.
+|                                | OKF bundle (this)                                     | `CLAUDE.md` / `AGENTS.md`  | Agent auto-memory        | Wiki / Notion    |
+| ------------------------------ | ----------------------------------------------------- | -------------------------- | ------------------------ | ---------------- |
+| Holds                          | curated team knowledge                                | standing instructions      | what one agent picked up | human docs       |
+| Versioned with the code        | ✅                                                    | ✅                         | ❌                       | ❌               |
+| Portable across agents         | ✅ plain Markdown + YAML                              | ⚠️ per-harness conventions | ❌ per-agent store       | ⚠️ export needed |
+| Typed and queryable            | ✅ frontmatter + graph                                | ❌ prose                   | ❌                       | ⚠️ partially     |
+| Reviewed in PRs                | ✅                                                    | ✅                         | ❌ implicit              | ⚠️ rarely        |
+| Scales past one context window | ✅ progressive disclosure<br>(`okf index` + `search`) | ❌ loaded whole            | ⚠️ partially             | n/a              |
+| Checked by tooling             | ✅ exit codes for CI<br>(`okf validate` + `lint`)     | ❌                         | ❌                       | ❌               |
+
+The last two rows are this gem's job. Scaling past one context window is
+progressive disclosure — `okf index` reads the map, `okf search` pulls only the
+concepts a task needs, so the bundle is never loaded whole. And drift never
+hides here: the other homes have no detector, but `okf validate` and `lint` turn
+a bundle's drift into findings you can gate on in CI.
 
 ## What a bundle looks like
 
@@ -163,14 +164,48 @@ putting the `okf` command on your `PATH`:
 bundle exec rake install
 ```
 
+### Run it with Docker (no Ruby needed)
+
+Prefer not to install Ruby? The official image bundles the CLI, so every `okf`
+command runs against a bundle you mount at `/data`:
+
+```bash
+# validate / lint / search / index … mirror the CLI, over the mounted bundle
+docker run --rm -v "$PWD:/data" ghcr.io/serradura/okf validate .
+
+# serve the live graph: bind 0.0.0.0 so the host can reach it, and publish the port
+docker run --rm -v "$PWD:/data" -p 8808:8808 ghcr.io/serradura/okf server . --bind 0.0.0.0
+```
+
+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`.
+
+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
+(mount, port, and bind handled for you). Do this only on a machine without the
+gem:
+
+```bash
+curl -fsSL https://docker.okfgem.com/install.sh | sh   # or grab the script by hand
+okf validate .
+okf server .
+```
+
+On Windows the image runs under Docker Desktop (WSL2); install with PowerShell
+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 skill     <dest> [--here] [--force]                 # install the companion agent skill
@@ -190,17 +225,23 @@ OKF v0.1 conformance — docs
 
 $ okf server docs
 serving 37 concepts at http://127.0.0.1:8808 (Ctrl-C to stop)
+
+$ okf render docs > public/index.html   # the same page, static — host it anywhere
 ```
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset=".github/server-dark.png">
-  <img src=".github/server-dark.png" alt="The okf graph server: a force-directed knowledge graph with a concept selected, its neighbors highlighted, and the inspector panel showing the concept's type, tags, cross-links, and rendered Markdown body.">
+  <img src=".github/server-light.png" alt="The okf graph server: a force-directed knowledge graph with a concept selected, its neighbors highlighted, and the inspector panel showing the concept's type, tags, cross-links, and rendered Markdown body.">
 </picture>
 
 _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)**._
 
+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.
+
 `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
@@ -251,15 +292,16 @@ skill plus a post-edit curation hook.
 The skill routes a small set of verbs. In Claude Code they run as `/okf:gem
 <verb>`; used standalone, the skill infers the verb from your request.
 
-| Verb             | What it does                                                                                      |
-| ---------------- | ------------------------------------------------------------------------------------------------- |
-| _(none)_         | Orient on the bundle and recommend the highest-value next move                                    |
-| `produce`        | Create or extend a bundle from code, docs, or knowledge in people's heads                         |
-| `maintain`       | Sync the bundle's content with reality after the code or docs change                              |
-| `consume`        | Use the bundle as context for a task, writing back what you learn                                 |
-| `curate`         | Structural upkeep as it stands: `validate` + `lint` + `loose`                                     |
-| `doctor`         | Install and verify the CLI, then doctor the bundle                                                |
-| `<okf-cli-verb>` | Run any CLI verb (`validate`, `lint`, `index`, `server`, the read views) and interpret its output |
+| Verb             | What it does                                                                                                |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| _(none)_         | Orient on the bundle and recommend the highest-value next move                                              |
+| `search`         | Answer a question from the bundle, token-lean: the map, the finder, only the winning bodies                 |
+| `produce`        | Create or extend a bundle from code, docs, or knowledge in people's heads                                   |
+| `maintain`       | Sync the bundle's content with reality after the code or docs change                                        |
+| `consume`        | Use the bundle as context for a task, writing back what you learn                                           |
+| `curate`         | Structural upkeep as it stands: `validate` + `lint` + `loose`                                               |
+| `doctor`         | Install and verify the CLI, then doctor the bundle                                                          |
+| `<okf-cli-verb>` | Run any CLI verb (`validate`, `lint`, `search`, `index`, `server`, the read views) and interpret its output |
 
 Point it at your agent's config directory (or its skills directory) and the tree
 settles in its own `skills/okf/` folder, so a shared skills directory never gets
@@ -323,6 +365,8 @@ folder.bundle                    # => OKF::Bundle  (the pure bundle it read)
 folder.concepts                  # => [OKF::Concept]  (reserved files excluded)
 folder.validate; folder.lint; folder.graph   # delegate to the pure core
 folder.concept("tables/orders")  # => OKF::Concept::File
+
+require "okf/server/app"         # the server loads on demand, like the CLI does
 OKF::Server::App.new(folder)     # => a Rack app: the interactive graph server
 
 # build in memory, then write it out (validates §9 before publishing):
@@ -335,7 +379,8 @@ file.save; file.delete; file.reload
 
 The lower-level pieces are usable on their own too: `OKF::Bundle::Validator.call(bundle)`,
 `OKF::Bundle::Linter.call(bundle, min_body: 50)`, `OKF::Bundle::Graph.build(bundle)`,
-`OKF::Markdown::Frontmatter.parse(markdown)`.
+`OKF::Markdown::Frontmatter.parse(markdown)`. Mounting the graph in Rails, auth
+included: the [Rails guide](https://okfgem.com/docs/guides/rails/) walks it.
 
 ### Conformance model
 

data/lib/okf/bundle/search.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module OKF
+  class Bundle
+    # Deterministic text retrieval over an in-memory bundle — the browser page's
+    # search brought server-side and extended to bodies. Terms are ANDed: every
+    # term must hit at least one searched field, though not necessarily the same
+    # one. A term is a case-insensitive substring, or a Ruby regular expression
+    # with `regexp: true`. Matches rank by where they hit (a title hit outranks a
+    # body hit) and carry one bounded context snippet, so answering "which concept
+    # covers X?" costs a row, not a body read.
+    #
+    # Deliberately not fuzzy: the consuming agent is the fuzzy layer — synonyms
+    # and vocabulary drift are judgment over the index map, not string distance.
+    #
+    # Pure — no disk, no stdio. The CLI's `okf search` and any embedding app share
+    # it: OKF::Bundle::Search.call(bundle, [ "dedup", "key" ]).
+    class Search
+      # The searchable fields with their rank weight, strongest signal first.
+      # A concept's score sums the weights of the fields that matched; hitting a
+      # field twice does not stack. Tags match against the space-joined list,
+      # mirroring the server page's haystack.
+      WEIGHTS = {
+        "title" => 5,
+        "id" => 4,
+        "tags" => 3,
+        "type" => 2,
+        "description" => 2,
+        "body" => 1
+      }.freeze
+
+      FIELDS = WEIGHTS.keys.freeze
+
+      # Fields whose match is only meaningful with surrounding context. The other
+      # fields already appear whole on the result row.
+      SNIPPET_FIELDS = %w[description body].freeze
+
+      # Characters of context kept on each side of the first matched term.
+      SNIPPET_RADIUS = 44
+
+      def self.call(bundle, terms, fields: nil, regexp: false)
+        new(bundle, terms, fields: fields, regexp: regexp).results
+      end
+
+      # Raises RegexpError on an invalid pattern with `regexp: true` — the caller
+      # owns turning that into a usage error.
+      def initialize(bundle, terms, fields: nil, regexp: false)
+        @bundle = bundle
+        raw = Array(terms).reject { |term| OKF.blank?(term) }
+        @matchers = raw.map { |term| regexp ? Regexp.new(term.to_s, Regexp::IGNORECASE) : term.to_s.downcase }
+        @fields = fields.nil? || fields.empty? ? FIELDS : fields
+      end
+
+      # Ranked match rows, catalog-style identity plus where the terms hit:
+      # [{ id:, title:, type:, area:, tags:, matched: [field, …], score:, snippet: }, …]
+      # ordered by score descending, then id. No terms means no matches.
+      def results
+        return [] if @matchers.empty?
+
+        @bundle.concepts
+               .map { |concept| match(concept) }
+               .compact
+               .sort_by { |row| [ -row[:score], row[:id] ] }
+      end
+
+      private
+
+      def match(concept)
+        texts = searchable_texts(concept)
+        matched = matched_fields(texts)
+        return nil if matched.nil?
+
+        {
+          id: concept.id,
+          title: (concept.title || concept.id).to_s,
+          type: concept.type.to_s,
+          area: area_of(concept.id),
+          tags: Array(concept.tags).map(&:to_s),
+          matched: matched,
+          score: matched.map { |field| WEIGHTS[field] }.reduce(0, :+),
+          snippet: snippet(texts, matched)
+        }
+      end
+
+      # { field => original-case text } for the fields this search reads.
+      def searchable_texts(concept)
+        texts = {
+          "id" => concept.id,
+          "title" => concept.title.to_s,
+          "type" => concept.type.to_s,
+          "description" => concept.description.to_s,
+          "tags" => Array(concept.tags).join(" "),
+          "body" => concept.body
+        }
+        texts.each_with_object({}) do |(field, text), acc|
+          acc[field] = text if @fields.include?(field)
+        end
+      end
+
+      # The union of fields any term hit, in WEIGHTS order — or nil when some term
+      # hit nothing (terms are ANDed).
+      def matched_fields(texts)
+        hits = @matchers.map do |matcher|
+          fields = texts.keys.select { |field| hit?(matcher, texts[field]) }
+          return nil if fields.empty?
+
+          fields
+        end
+        FIELDS.select { |field| hits.flatten.include?(field) }
+      end
+
+      def hit?(matcher, text)
+        matcher.is_a?(Regexp) ? matcher.match?(text) : text.downcase.include?(matcher)
+      end
+
+      # One bounded context window around the first term that hit the strongest
+      # snippet-worthy field; "" when the match needs no context (id/title/type/tags).
+      def snippet(texts, matched)
+        field = SNIPPET_FIELDS.find { |candidate| matched.include?(candidate) }
+        return "" if field.nil?
+
+        matcher = @matchers.find { |candidate| hit?(candidate, texts[field]) }
+        context(texts[field], matcher)
+      end
+
+      def context(text, matcher)
+        flat = text.gsub(/\s+/, " ").strip
+        at, length = locate(flat, matcher)
+        from = [ at - SNIPPET_RADIUS, 0 ].max
+        to = at + length + SNIPPET_RADIUS
+        clip = flat[from, to - from].to_s.strip
+        clip = "…#{clip}" if from.positive?
+        clip = "#{clip}…" if to < flat.length
+        clip
+      end
+
+      # [ position, length ] of the matcher's first hit in the flattened text —
+      # [ 0, 0 ] when a pattern that hit the raw text cannot be found again after
+      # whitespace collapsing (e.g. an explicit \n), so the window opens at the top.
+      def locate(flat, matcher)
+        if matcher.is_a?(Regexp)
+          found = matcher.match(flat)
+          found ? [ found.begin(0), found[0].length ] : [ 0, 0 ]
+        else
+          [ flat.downcase.index(matcher) || 0, matcher.length ]
+        end
+      end
+
+      # A concept's top-level area, mirroring the catalog's definition.
+      def area_of(id)
+        id.include?("/") ? id.split("/").first : "(root)"
+      end
+    end
+  end
+end

data/lib/okf/bundle.rb

@@ -136,8 +136,8 @@ module OKF
     # the map on the fly (§6 permits exactly that). Grouped by the concept's file
     # path — index files are physical directory listings, so a custom frontmatter
     # `id` must not move a concept out of the directory it lives in. Pure: derived
-    # from the concepts and the reserved index text, no disk. Shared by the `okf
-    # index` view and the server's /index endpoint.
+    # from the concepts and the reserved index text, no disk. Shared by the
+    # `okf index` view and the server's Index panel (/index).
     def directory_index
       by_dir = concepts.group_by { |concept| File.dirname(concept.path) }
       dirs = directory_set(by_dir.keys)