okf 2.1.0 → 2.2.0

data/.okf/design/browser-tests.md

@@ -0,0 +1,211 @@
+---
+type: Constraint
+title: The graph page is proven in a real browser
+description: A string assertion over rendered HTML cannot see a collapsed canvas or a folded breakpoint, so the page is driven in Chromium — in both render modes, with any thrown error failing the run.
+resource: gems/okf/test/browser
+tags: [testing, render, server, architecture]
+generated:
+  by: human:maintainer
+  at: 2026-07-22T12:00:00Z
+sources:
+  - title: gems/okf/test/browser/README.md
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/test/browser/README.md
+  - title: gems/okf/test/browser/COVERAGE.md
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/test/browser/COVERAGE.md
+---
+
+# Overview
+
+[`okf render` and `okf server`](../capabilities/render.md) share one ERB
+template carrying ~1,300 lines of inline JS and CSS. Its regressions are not
+the kind a string assertion catches: a view that returns with a canvas
+Cytoscape measured at 0×0, a filter that stops composing with search, a
+breakpoint folding the wrong element, a handler that throws while the DOM
+still looks plausible. `okf/test/integration/render/` proves the page is
+*emitted* correctly and cannot prove it *works*.
+
+`okf/test/browser/` closes that gap with Playwright: real Chromium, DOM state and
+computed CSS at real viewport widths. It is the same argument
+[integration-first](integration-first.md) makes for the CLI, applied to the
+one surface the CLI cannot reach.
+
+# Every spec runs in both render modes
+
+The template has two data paths that diverge in a load-bearing way: served
+live it fetches `/node`, `/catalog`, `/index` and `/log` on demand; rendered
+statically it reads the same payloads out of a baked `EMBED` constant. A pass
+in one proves nothing about the other, so the suite defines two Playwright
+projects and runs every spec twice — one against a booted `okf server`, one
+against a `file://` static render generated fresh each run.
+
+Where the modes honestly differ the spec says so and asserts both answers.
+Full-text search is the worked example: bodies enter the index only when they
+are present, and they are present only in a static bake, so the same query
+finds a concept in one mode and not the other. Pinning a single expectation
+would certify a lie in whichever mode it did not describe.
+<!-- rule:okf-both-render-modes -->
+
+# A thrown error fails the run
+
+The shared fixture watches `pageerror` and console errors and fails the test
+even when every assertion passed. This is the check no per-behavior test
+provides: a handler that throws leaves a plausible-looking DOM that
+assertions walk straight past, and "I changed the filter and the catalog
+quietly stopped rendering" is exactly the failure this file keeps producing.
+It is also the only thing giving the suite reach into surfaces it does not
+otherwise test.
+
+# Outside the default task, and outside CI
+
+It needs node and a ~120MB Chromium, neither of which belongs on the
+[Ruby 2.4 floor](ruby-floor.md) matrix, and the gem takes on no
+[runtime dependency](runtime-dependencies.md) from it. So it is opt-in locally
+(`rake test:browser`) and does not run in CI at all.
+
+It did, for several releases, as a separate job marked `continue-on-error` — red
+when it failed, but never gating a merge. The argument was that this is a
+judgement about *what the signal is worth*: the page loads Cytoscape, marked and
+DOMPurify from a CDN at boot — a dependency the
+[trust boundary](server-trust-boundary.md) already names — so a red job can mean
+a regression or can mean jsdelivr was slow.
+
+The measurement settled it against the job. It failed **5 of its last 7 runs**
+while the Ruby matrix stayed green, so the check was wrong far more often than it
+was right, and the same sentence that justified it ("a check that cries wolf gets
+muted within a month") describes what it became. It also cost something the
+argument never priced: a ✗ on the repository's front page is read by a visitor as
+a broken gem, not as a slow CDN, and that reading is the expensive one.
+
+So the suite is a maintainer obligation run locally, enforced by nothing — the
+same standing as the 2.4 Docker floor and the PR shape. Restoring it to CI needs
+the flakiness gone first, not a second hedge on top of the first: cache
+`okf/test/browser/vendor/` between runs so a cold runner stops reaching for jsdelivr,
+and only then judge the signal on what is left.
+
+The suite now answers those requests from a local read-through cache
+(`okf/test/browser/vendor-cache.js`): a miss fetches and writes a gitignored
+`vendor/`, a hit serves from disk, and a warm run touches no network at all —
+proven by making the fetch path `throw` and watching 64 cases still pass. It is
+keyed on the **request URL**, not on a list of the versions the template pins,
+because such a list is a second copy of those pins that can drift into serving a
+library the page no longer loads — the one failure a cache is most likely to
+hide. Keyed on the URL, a version bump is simply a miss. `OKF_NO_VENDOR_CACHE=1`
+bypasses it entirely, which is the way to check the template's pins still
+resolve against the real CDN rather than against whatever `vendor/` kept.
+
+That cache is a developer's offline suite, not CI's: `vendor/` is build output, so
+a runner starts cold and still fetches from jsdelivr on the first boot. Which is
+why it did nothing for the failure rate above, and why restoring the directory
+between runs is the first move if the job is ever brought back.
+
+The cache was built to make the suite *faster* and does not, which is worth
+recording because the arithmetic that predicted otherwise is easy to re-derive
+and wrong. It ran: Playwright gives each test a fresh context with an empty
+cache, so the ~330 ms of boot scripts is re-paid across 400-odd cases. Chromium
+in fact reuses those subresources across contexts inside a worker's browser
+process, so the download was only ever paid once per worker. The controlled
+measurement — 34 cases pinned to a single worker — is 28.7 s without the cache
+and 29.0 s with it. Full-suite wall clock cannot settle the question at all:
+three runs of the same 412 cases came in at 3.4 m, 3.6 m and 2.8 m, a spread
+several times the effect, and reading the 2.8 m as a win is the mistake the
+noise invites. The suite is bound by CPU — around 500% across five workers, on
+rendering and Cytoscape layout — which is where the CDN wait was already
+hiding. The lesson generalizes past this cache: a per-request timing multiplied
+by a case count is a hypothesis, and the only thing that settles it is an A/B
+with the parallelism held down.
+
+Which leaves the obligation where it was: a change to the template is not done
+until the suite is green locally. An automated gate nobody trusts is weaker
+than a rule the maintainer keeps.
+<!-- rule:okf-browser-suite-before-merge -->
+
+# Coverage is measured against the page's own history
+
+The suite's worth is measured the same way
+[integration coverage](integration-first.md) is — as a map, not a score, and
+against the honest denominator. Reading all 44 commits behind the template
+yields ~230 behavioral contracts, ~94 of them fixes for bugs that actually
+shipped. A regression fix is the sharpest test target there is: a failure mode
+already proven reachable in this file.
+
+`okf/test/browser/COVERAGE.md` now enumerates every contract per-commit and marks
+each covered / partial / uncovered: of 181 net-live contracts, 176 (97%) are
+covered, with a ranked worklist of what remains — its Priority 1 (regression
+fixes reachable from the existing fixtures) is cleared, and Priority-2 is well
+underway. By the narrower
+regression-fix-only lens that is roughly 60 of 94, up from 10 — worked gap by gap,
+each new spec mutation-checked.
+It is strong on the interaction spine, the filters, the file tree, link
+resolution, both XSS defenses, the mobile chrome, the first-visit notes, the
+index layer, the diagram viewer and both halves of the command palette (the hub
+bundle-switcher is reached through a two-bundle server the config boots, down to
+the ⌘⏎ new-tab chord it honours; the Mermaid re-theme and the
+`prefers-color-scheme` boot fallback are pinned too). The one regression that
+resisted every external observable — one-camera-move-per-click, where settled
+position, pan-event bursts and motion span all failed to tell a gutted `centerOn`
+from the fix — was closed only by making the page observable: a test-only counter
+(`window.__camCenters`) the spec reads at the synchronous instant after the tap,
+0 when the pan is deferred and 1 when it fires immediately. That is the honest
+cost of a sub-frame timing contract, and it is deliberately the exception, not
+the pattern. Its sibling, the graph-collapse-on-return, needed no counter at all:
+once traced it turned out not to be a resize race but the boot fit landing on a
+hidden 0×0 canvas and clamping the zoom to minZoom, and it left a stable
+end-state signal (the clamped zoom) that closed it deterministically at the
+source.
+
+Three dividends of the work land here. Writing the specs turned up three real,
+shipped bugs no string assertion could see, all now fixed: cluster-mode selection
+faded the whole graph (a compound parent's opacity cascades to its nodes); a
+log's "Open in graph" button stayed visible though the code hides it, because
+`.btn.text{display:inline-flex}` outranked `.btn[hidden]` at equal specificity
+(fixed by a `.btn.text[hidden]` rule, the precedent already used for `.fp-head`);
+and the graph collapsed on return, whose cause was misdiagnosed as a resize race
+for months until the browser tools showed the one animation running was a *fit*
+of a hidden canvas (fixed by guarding `fitGraph` against a zero-size container).
+All three are the assert-the-collapsible rule below paying out: a defect
+invisible on inspection, caught by reading computed state, red before the fix and
+green after. The third also earns its own lesson — a load-sensitive flake was the
+symptom of a timer racing boot, not noise to route around with a `fixme`.
+`COVERAGE.md` carries the full ranked list and what remains — now chiefly the
+sub-frame periphery, both named camera defects having been closed.
+
+# Writing a spec: read the page, then assert
+
+Assertions must be able to fail for a real reason, which here means two things
+beyond the [test-first rule](integration-first.md).
+
+**Read what the page renders, not what the code looks like it renders.** Four
+of the first green run's assertions were wrong this way — panel labels are
+sentence-case in markup and uppercased by `text-transform`; the Index rail
+item opens a file rather than pressing the filter beside it.
+
+**Assert the thing that can actually collapse.** The suite's first
+canvas-resize test read `cy.width()`, which reports the live container and
+stays correct while the render is collapsed — it passed with every resize path
+deleted. A test that cannot fail is worse than no test, because it is counted.
+Mutation-check a new spec by breaking the code it covers and confirming it
+goes red for the predicted reason.
+<!-- rule:okf-assert-the-collapsible -->
+
+Both traps were hit again by the cluster-drag specs, which is why they are stated
+here rather than in a changelog. Asserting a node sits *inside* its box cannot
+fail: a compound parent is sized from its children, so it holds even when nothing
+was laid out. And aiming at the box's *bounding box* is not aiming at the box —
+measured, the label strip at the top and the bottom fifth fall through to the
+canvas, so the drag tested the background and would have passed with the bug in
+place. Both were rewritten against what was measured: coordinates that move, and
+a hit region of 0.25–0.65.
+
+**Wait for the signal, never for a duration.** A fixed sleep after clustering
+raced the layout: `clusterLayout` awaits a lazy CDN load, and under `animate:'end'`
+nothing moves *while* fcose computes — so two identical position samples arrive
+before the tiling does and read as "settled". The wait is now three facts in
+order: the layout started (`layoutstart`; `layoutstop` never fires here, and
+polling for it only ever timed out), it moved something, and it stopped.
+
+What is left after that is ~1 in 100, and the two drag specs carry `retries: 2`
+for it. That is a deliberate exception to the rule that retries mask defects, and
+it holds only because the race is in the **setup**: a real mouse gesture aimed at
+live geometry on a canvas whose camera is still animating. On a settled canvas the
+identical gesture succeeded 8/8, so the retry re-runs the aim, not the proof —
+and two failures running is a regression, not this.

data/.okf/design/core-shell-split.md

@@ -0,0 +1,73 @@
+---
+type: Constraint
+title: The core/shell split
+description: A pure functional core that never touches disk or stdio, and a thin shell that owns all I/O — enforced by a test.
+resource: gems/okf/test/unit/boundary_test.rb
+tags: [architecture, pure, testing, diagram]
+generated:
+  by: human:maintainer
+  at: 2026-07-18T19:00:00Z
+sources:
+  - title: gems/okf/test/unit/boundary_test.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/test/unit/boundary_test.rb
+---
+
+# Overview
+
+The gem is two halves. The **core** is pure — [`Concept`](../model/concept.md),
+[`Bundle`](../model/bundle.md), [`Graph`](../model/graph.md), the
+[validator](../capabilities/validator.md), the [linter](../capabilities/linter.md),
+the [search](../capabilities/search.md),
+the format layer (`@okf-eco format/`) — logic that returns data and does no I/O. The
+**shell** owns everything that touches the world: the on-disk handles
+(`Concept::File`, `Bundle::{Reader,Writer,Folder}`), the
+[renderer](../capabilities/render.md) that draws the page, the
+[server](../capabilities/graph-server.md) and its hub, the
+[registry](../registry.md), and the [CLI](../cli.md).
+
+```mermaid
+flowchart TB
+  subgraph shell ["Shell — the only layer that does I/O"]
+    CLI["CLI"]
+    Render["Render::Graph"]
+    Server["Server::App · Hub"]
+    Registry["Registry"]
+    RW["Reader · Writer · Folder"]
+    CF["Concept::File"]
+  end
+  subgraph core ["Core — pure: no File / Dir / stdio"]
+    Concept["Concept"]
+    Bundle["Bundle"]
+    Graph["Graph"]
+    VL["Validator · Linter · Search"]
+    MD["Markdown layer"]
+  end
+  shell ==>|depends on| core
+  core -. "never — boundary_test.rb fails the build" .-> shell
+```
+
+# It is enforced, not just intended
+
+`okf/test/unit/boundary_test.rb` fails the build if a core file names a shell class or
+reaches for `File` / `Dir` / `FileUtils` / stdio. The dependency rule is executable,
+so the boundary cannot rot silently: **put new I/O in the shell, put new logic in
+the core, pure.**
+
+"Pure" here means *no I/O*, not *no dependencies*: a core file may require a
+third-party library as long as the library is itself pure computation. `Search`
+requires [`minifts`](../design/runtime-dependencies.md) and stays in the core,
+because an in-memory index touches neither disk nor stdio. A gem that read a
+config file or logged to stderr would not get the same pass.
+
+# Why it pays off
+
+- **Testable without disk** — every feature runs against an in-memory
+  [bundle](../model/bundle.md), so the suite is fast and the 2.4 Docker check is
+  cheap. It is also what makes [integration first](integration-first.md)
+  affordable: a shell this thin can be driven for real, with argv and streams and
+  exit codes, in milliseconds — so the layer a user touches never has to be
+  proven by proxy.
+- **Embeddable** — the [library API](../capabilities/library-api.md) exposes the
+  pure core to host apps that never want the gem's filesystem opinions.
+- **Best-effort reads** — the reader collects unparseable files instead of
+  raising, so the pure graph still renders while the shell reports the skips.

data/.okf/design/index.md

@@ -0,0 +1,17 @@
+# Design constraints
+
+The boundaries that keep this gem light and honest. Each is enforced by
+something — a test, a build task, a CI job — rather than intended.
+
+The two that are *not* this gem's live in the repository bundle: the extension
+seam every sibling arrives through (`@okf-eco design/extension-points`) and the
+monorepo layout (`@okf-eco decisions/monorepo-layout`).
+
+* [The core/shell split](core-shell-split.md) - Pure logic and I/O are separated, and a test fails the build when they are not.
+* [Integration tests are the critical layer](integration-first.md) - The CLI is the product, so the suite that drives it end to end outranks the unit tests.
+* [The graph page is proven in a real browser](browser-tests.md) - A string assertion cannot see a collapsed canvas, so Chromium drives the page in both render modes.
+* [Ruby 2.4](ruby-floor.md) - The floor is rack's own, and the point is running on the Ruby an OS already ships.
+* [Runtime dependencies](runtime-dependencies.md) - Exactly three, and a fourth needs an argument as strong as the third's.
+* [Search engines](search-engines.md) - One facade, two engines, chosen by what the query needs rather than by name.
+* [The server trust boundary](server-trust-boundary.md) - What the server will answer for, and what it refuses regardless of flags.
+* [What ships, and the two ways it has gone wrong](packaging.md) - `spec.files` is subtractive, `.dockerignore` implies the reject list one way only, and a symlink installs dangling on the old half of the matrix.

data/.okf/design/integration-first.md

@@ -0,0 +1,140 @@
+---
+type: Constraint
+title: Integration tests are the critical layer
+description: The CLI is the product, so the suite that drives it end to end outranks the unit tests — and its coverage is measured alone, because the full number flatters.
+resource: gems/okf/test/integration/cli
+tags: [testing, cli, architecture]
+generated:
+  by: human:maintainer
+  at: 2026-07-20T12:00:00Z
+sources:
+  - title: gems/okf/AGENTS.md — Testing
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/AGENTS.md
+  - title: gems/gems/okf/test/integration/cli/cli_integration_case.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/test/integration/cli/cli_integration_case.rb
+---
+
+# Overview
+
+A unit test proves a method behaves; an integration test proves the *product*
+behaves. For this gem the product is the [CLI](../cli.md) — real argv, real
+streams, real exit codes, real files — so when the two compete for effort,
+integration wins. That is a ranking, not a slogan: `okf/test/integration/cli/` is
+where a new verb is proven, and a verb without its file is not done.
+
+The [core/shell split](core-shell-split.md) is what makes both layers cheap: the
+pure core is unit-testable without disk, and the shell is thin enough that
+driving it for real costs milliseconds.
+
+# The folders are the three ways a user names a bundle
+
+```
+okf/test/integration/cli/
+  cli_integration_case.rb   the shared base: okf(), with_registry(), okf_server()
+  fixtures/                 bundles more than one group uses
+  by_dir/                   `okf lint ./docs`      — named by path
+  by_registry/              `okf lint @handbook`   — named through the registry
+  across_bundles/           `okf search @a @b`     — several at once
+  cli_help_test.rb …        the verbs that name no bundle
+  cli_plugin_test.rb        the extension seam — a plugin on the load path
+```
+
+`cli_plugin_test.rb` is the odd one, deliberately: it names no bundle and tests
+no verb of ours. It writes `okf/plugin.rb` into a temp dir on `$LOAD_PATH`, which
+is indistinguishable from an installed gem's `lib/`, so the
+seam (`@okf-eco design/extension-points`) is driven for real without building and installing a
+gem to drive it.
+
+Same command, same flags, three identities — because the identity is where the
+CLI decides *what to answer about*, and a verb that works by path can still be
+broken by [ref](../registry.md). One file per command **and** per subcommand:
+`registry list`/`set`/`del`/`default`/`rename` are five files, since each is a
+surface invoked on its own.
+
+`across_bundles/` covers every bundle-taking verb, not only the two that merge.
+For the eleven with no multi-bundle form, the test proves a second bundle is
+*rejected* — that boundary was a real silent-wrong-answer bug (`okf lint a b`
+once linted `a`, ignored `b`, and exited `0`), so it is guarded, not assumed.
+
+# Coverage is measured on the layer alone
+
+```bash
+bundle exec rake test:integration   # + coverage/integration/
+```
+
+The full suite's number flatters: unit tests call classes directly and reach code
+no user can. Run integration by itself and the figure becomes a *map* instead of
+a score — read it that way. Low coverage in `bundle/writer.rb` or
+`concept/file.rb` is expected and honest: no CLI verb writes a bundle, so those
+belong to the [library API](../capabilities/library-api.md) to prove. Low coverage
+in `cli/`, `registry.rb`, or `server/` is a **hole** — a path a user can reach
+that no user-shaped test walks.
+
+And prove that completeness by **reading the uncovered lines, not by judgment**.
+A green run and a flattering aggregate hide the same thing — a branch only the
+unit tests reach — so after a feature, diff
+`coverage/integration/.resultset.json` for the uncovered lines in the files you
+changed. Three shapes hide there by habit, because a unit test walked them
+first: the *second* output format (the human listing when only `--json` was
+asserted, or the reverse), an *error* branch and the exit code it carries, and
+*malformed-input* robustness (a hand-edited [registry](../registry.md) — a
+cycle, an unnormalised slug, a missing field). The registry groups shipped with
+nine integration tests that read as exhaustive and left six such branches, a
+whole human-rendering path among them, proven only by unit tests until the
+resultset named them.
+
+# Fixtures are the cheap part
+
+`fixtures/` is the substrate the whole layer stands on: a committed bundle is
+cheaper than a mock, more honest, and a reviewer can read it. When a path is
+unreachable from the fixtures that exist, **add one** — never bend a test toward
+what the fixtures happen to make easy, and never leave a path untested because
+building its world felt like work.
+
+Two of them are the argument. `rooted` exists because `tags --by dir`'s `(root)`
+label — the one printed without a trailing slash — was unreachable from all twelve
+fixtures before it: none carried a *tagged* root-level concept. `mentions` exists
+because none contained a literal `@`, so
+[search](../capabilities/search.md)'s `-e '\@term'` escape could be shown not to
+error but never shown to *find*. A branch no fixture can reach is a branch nobody
+has ever proven.
+
+Fixtures follow **common closure**: one that a single group uses lives under that
+group, so it changes when those tests change; one that several share stays in the
+shared `fixtures/`. The base resolves group-local first, shared second, so a test
+says `fixture("navigation")` without knowing which it is.
+
+# Why it pays off
+
+The suite is not decoration — writing it is what found the bugs. The pass that
+built this layer turned up a `render -o` backtrace where the exit contract
+promised `2`, counts that disagreed with their nouns, three spellings of "no
+usable type" in three buckets, a [`graph`](../capabilities/read-views.md) that
+named no bundle at all, and the silent second-bundle answer above. Four
+independent reviewers had read the same code first and found none of them.
+
+Assertions must be able to fail for a real reason: run the CLI, read what it
+actually prints, then assert *that*. Asserting what you assume the code does is
+how a green suite certifies a bug.
+
+# The order is the proof
+
+A change starts with a failing integration test, not with the fix — and the
+failure has to be *read*, not merely observed: it must fail for the predicted
+reason, since a test that fails on a missing fixture or a typo'd regex has proven
+nothing about the bug. Then the code, then a re-run the test passes unedited.
+<!-- rule:okf-test-first -->
+
+That order is the only thing that establishes a test *can* fail. Written
+afterwards, a test can only certify the code it was read off; written alongside,
+a bug and its test come to agree with each other and stay wrong together — the
+green suite certifying a bug, arrived at from the other direction. Pure refactors
+are the exception rather than a licence, because they change no behavior: the
+existing suite is their test and a green run is the proof the contract held.
+
+The registry's [two derivations of the default](../registry.md) are the worked
+example. The star-versus-`/` disagreement was written as a red test first, and the
+run printed both halves of the bug at once — `/` redirecting to `conformant` while
+the listing starred a `doomed (missing)` entry. Neither the reviewer nor the fix
+had to be trusted: the test failed for exactly the predicted reason, the fix
+turned it green, and it has guarded the agreement since.

data/.okf/design/packaging.md

@@ -0,0 +1,65 @@
+---
+type: Constraint
+title: "What ships, and the two ways it has gone wrong"
+description: "`spec.files` is `git ls-files` minus a reject list, which makes `.dockerignore` imply the gemspec one way only — and a symlink in the package installs dangling on the old half of the supported matrix rather than failing."
+resource: gems/okf/okf.gemspec
+tags: [packaging, gemspec, docker, rubygems]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+sources:
+  - title: RubyGems Gem::Package::SymlinkError
+    resource: https://github.com/rubygems/rubygems/blob/master/lib/rubygems/package.rb
+---
+
+# The list is subtractive
+
+`spec.files` comes from `git ls-files` run with `chdir:` into the gem's own
+directory, minus a reject list: `test/`, `bin/`, the Gemfile, the Rakefile,
+`.gitignore`, `.rubocop.yml`, `AGENTS.md`, `CLAUDE.md`, and the gemspec itself.
+
+Two consequences follow from it being subtractive rather than additive.
+Everything at the repository root is invisible to it, so a new *root* file needs
+no reject at all. But a new top-level file **inside the gem** ships unless the
+gemspec rejects it — check `gem build` output when adding one.
+
+`.okf/` is deliberately not rejected: an installed okf carries a real bundle, its
+own — the [companion skill](../capabilities/agent-skill.md) ships the same way,
+from `lib/okf/skill/`, for a reader to open with the tool they just installed.
+`test/unit/packaging_test.rb` pins that it ships, and pins that `AGENTS.md` and
+`CLAUDE.md` do not — the guide is for someone with a checkout, and `CLAUDE.md`
+is one line pointing at it, so shipping the pointer without its target puts a
+reference to nothing inside the published gem.
+
+# `.dockerignore` implies the reject list, one way only
+
+Anything `.dockerignore` drops from under the gem's directory must **also** be
+rejected by the gemspec, or be gitignored. `git ls-files` reads the *index*, so
+a path excluded from the Docker build context is still listed in `spec.files`,
+and `gem build` then fails on a file that is not there.
+
+**The converse does not hold, and must not be "restored" for symmetry.** `bin/`,
+`Gemfile` and `Rakefile` are rejected from the gem and stay in the build context
+on purpose; nothing breaks by shipping them to the builder.
+
+One detail that looks like a bug and is not: `.dockerignore`'s bare `.okf` entry
+drops the *repository's* bundle, not this gem's, because Docker anchors a
+pattern with no `**` at the context root.
+
+# Nothing in `spec.files` may be a symlink
+
+`gem build` does not resolve one. It writes a symlink into the package, warns,
+and succeeds.
+
+What happens next depends on the installer's age, and the old half of the
+supported matrix is the dangerous half. RubyGems >= 3.2 refuses to extract a
+link pointing outside the gem (`Gem::Package::SymlinkError`) — loud, and
+survivable. **RubyGems < 3.2 has no guard at all**, so on Ruby 2.7 (RubyGems
+3.1.6, inside the supported range) `gem install` exits 0 and installs a
+*dangling* file. The gem installs cleanly and carries no licence, and nothing
+says so.
+
+So `LICENSE.txt` and `NOTICE` are real duplicates of the repository root's
+rather than links to them, and `test/unit/packaging_test.rb` pins three separate
+claims: that they are not symlinks, that they are byte-identical to the root's,
+and that they are actually in `spec.files`.

data/.okf/design/ruby-floor.md

@@ -0,0 +1,53 @@
+---
+type: Constraint
+title: The Ruby 2.4 floor
+description: The gem runs on every Ruby since 2.4 so it works on the interpreter an OS already ships.
+tags: [ruby, portability]
+generated:
+  by: human:maintainer
+  at: 2026-07-17T16:00:00Z
+sources:
+  - title: gems/okf/okf.gemspec
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/okf.gemspec
+  - title: gems/okf/AGENTS.md — The contract
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/AGENTS.md
+---
+
+# Overview
+
+`required_ruby_version >= 2.4.0`. The point is to run on the Ruby an operating
+system already ships, without asking anyone to install a newer one — the same
+floor as [rack](runtime-dependencies.md), the gem's core dependency. This is why
+the gem stays deliberately light.
+
+# The floor bans APIs RuboCop won't catch
+
+RuboCop parses at 2.4 and catches syntax, but **not** newer standard-library
+methods, so those are a manual discipline. A non-exhaustive list of what is off
+limits:
+
+- **2.5** — `delete_prefix`/`delete_suffix`, `transform_keys`, `Dir.children`,
+  `yield_self`;
+- **2.6** — `to_h { }`, `then`, endless string slices `str[i..]`, `YAML.safe_load`
+  keyword args (allowed **only** inside the
+  Frontmatter shim (`@okf-eco format/frontmatter`));
+- **2.7** — `filter_map`, `tally`, numbered block params;
+- **3.x** — endless methods, hash shorthand.
+
+These constraints apply to `okf/test/` too, because the suite runs on 2.4 as well.
+
+# The truth test
+
+"Works on my Ruby" is not verification here. The floor is checked in CI across
+every supported Ruby, and locally by copying the tree into a throwaway build dir,
+dropping `Gemfile.lock` (the lockfile is written by a modern Bundler that 2.4's
+own cannot read), and mounting the checkout **read-only** so the run cannot write
+one back. Run it from the **repository root** — `$PWD` becomes `/src`, and the
+command steps into the gem on the other side, because the floor is a property of
+`okf` rather than of the repository and the siblings (`@okf-eco decisions/monorepo-layout`) will
+not share it:
+
+```bash
+docker run --rm -v "$PWD":/src:ro ruby:2.4 bash -c \
+  "cp -a /src /build && cd /build/okf && rm -f Gemfile.lock && bundle install --quiet && bundle exec rake test"
+```

data/.okf/design/runtime-dependencies.md

@@ -0,0 +1,82 @@
+---
+type: Constraint
+title: Three runtime dependencies, each challenged
+description: The gem depends on rack, webrick and minifts only — no ActiveSupport, no build step, no JavaScript toolchain, and no native extension.
+resource: gems/okf/okf.gemspec
+tags: [rack, portability]
+generated:
+  by: human:maintainer
+  at: 2026-07-19T03:00:00Z
+sources:
+  - title: gems/okf/okf.gemspec
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/okf.gemspec
+  - title: minifts
+    resource: https://github.com/serradura/minifts
+---
+
+# Overview
+
+The runtime dependencies are exactly three, and a fourth is a design decision to
+be challenged, not a convenience:
+
+| Gem | Why |
+|-----|-----|
+| `rack` (`>= 2.2`) | the [server](../capabilities/graph-server.md) is a mountable Rack app |
+| `webrick` (`>= 1.4`) | the default runner — unbundled from Ruby in 3.0, so it must be declared |
+| `minifts` (`~> 1.0`) | [search](../capabilities/search.md)'s index engine — BM25+ ranking, prefix and fuzzy matching, on request |
+
+# What the third one had to prove
+
+`minifts` was admitted because it costs the footprint nothing that the two
+before it were chosen to protect. It is pure Ruby with **zero runtime
+dependencies of its own**, so it adds one gem rather than a subtree; it holds the
+same [Ruby 2.4 floor](ruby-floor.md); and it is not a native extension, which is
+the whole point — it is what lets ranked full-text search arrive *without*
+SQLite + FTS5 and the C toolchain, build step and platform matrix that come with
+it. The ceiling moves up; it does not disappear. A corpus large enough to
+outgrow an in-memory index is still FTS5's to answer.
+
+It buys a second thing that no third-party gem usually can. `minifts` is a
+bit-for-bit port of the JavaScript MiniSearch the [browser
+page](../capabilities/graph-server.md) already loads, so `--engine index` and the
+browser rank identically by construction rather than by two implementations
+agreeing for a while — and an index built in Ruby can be searched in the browser,
+which is what a cached, pre-built index would need.
+
+**The case got weaker, and the entry stays honest about it.** `minifts` now backs
+a **non-default** engine: the scan took the default back, because a one-shot CLI
+cannot amortize an index build (3.00 s against 0.24 s at 1,000 concepts) and
+because raw text has none of the tokenizer's recall holes. A dependency that only
+serves an opt-in path is a dependency carrying less weight than the one admitted
+here. It is not close to retirement — `--fuzzy` has no other implementation,
+BM25+ ranking has no other source, and page parity has no other route — but the
+argument that justified it was *ranked search by default*, and that is no longer
+what it delivers. If a cached prebuilt index makes the index viable as the
+default again, this entry is restored rather than merely re-argued.
+
+# No ActiveSupport, on purpose
+
+The gem refuses the usual reach for ActiveSupport. Two small pieces exist
+precisely so it is not needed:
+
+- `OKF.blank?` — the emptiness check;
+- `OKF::Markdown::Frontmatter.stringify_keys` — the key coercion, living in
+  the one YAML gateway (`@okf-eco format/frontmatter`).
+
+# What the leanness buys
+
+Together with the [Ruby 2.4 floor](ruby-floor.md), a three-dependency footprint —
+none of them native, none of them dragging a tree — is what lets the gem run on
+the interpreter an OS already ships: no build step, no bundler for the
+[served page](server-trust-boundary.md), no JavaScript toolchain. Leanness is a
+feature of this gem, not an accident.
+
+# A packaging note
+
+`spec.files` comes from `git ls-files` run with `chdir:` into the gem's own
+directory, minus `test/`, `bin/`, the `Gemfile`, the `Rakefile` and a couple more.
+Because of that `chdir:`, everything at the repository root is invisible to it —
+so a new *repo*-level file never ships, and needs no reject. A new top-level file
+**inside the gem** does ship unless the gemspec rejects it; check `gem build`
+output when adding one. See the monorepo layout (`@okf-eco decisions/monorepo-layout`) for the
+one-directional rule that ties the reject list to `.dockerignore`.