okf 2.0.0 → 2.1.1

data/.okf/structure/format-layer.md

@@ -0,0 +1,59 @@
+---
+type: Component
+title: The Format Layer
+description: "Pure, and the bottom of everything: path normalisation with a root-escape guard, the one YAML door, and the link and citation grammars §5 and §8 are written in."
+tags: [structure, format, pure, yaml, links]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/path.rb
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf.rb` | `OKF::Error`, `OKF.blank?`, `OKF.iso8601`, `OKF.dir_of`, `SPEC_VERSION` |
+| `lib/okf/version.rb` | `OKF::VERSION` |
+| `lib/okf/path.rb` | `Path.normalize_relative!`, `join_under!`, `under?` — and `Path::Error` |
+| `lib/okf/safe_read.rb` | `SafeRead.contained_path!`, `read!` — containment for a caller that already holds a root |
+| `lib/okf/markdown/frontmatter.rb` | parse, dump, `stringify_keys` — **the only** YAML door |
+| `lib/okf/markdown/links.rb` | §6: inline, reference and footnote links, and how a raw target resolves |
+| `lib/okf/markdown/citations.rb` | §8: the `# Citations` section and its entries |
+
+# Containment is a primitive here, not a habit
+
+`Path.normalize_relative!` rejects any `..` segment outright, which is what makes
+"a concept cannot link out of its own bundle" a property of the format rather
+than a convention. `join_under!` and `under?` are the two questions every writer
+and every reader asks before touching a path, and `SafeRead.read!` is the pair of
+them plus the read, for callers that already hold a root — it resolves symlinks
+and refuses one that leaves.
+
+Every layer above reaches for these rather than composing its own check. A second
+containment implementation is the shape this class of bug takes.
+
+# One YAML door
+
+**All YAML goes through `Markdown::Frontmatter`** — `safe_load`, with `Date` and
+`Time` permitted and aliases off. `PSYCH_KEYWORDS` is the Psych < 3.1
+positional-argument shim, and it lives here precisely so that
+`YAML.safe_load`/`YAML.load` is called in exactly one place in the gem.
+
+`stringify_keys` exists so that ActiveSupport does not, which is the same reason
+`OKF.blank?` does.
+
+# The link grammar is where the graph comes from
+
+`Links.extract` walks prose lines only — `FENCE` and `CODE_SPAN` take fenced
+blocks and code spans out first, because a link inside a code sample is a
+document about a link, not an edge. `INLINE_LINK`, `REFERENCE_LINK` and
+`DEFINITION` cover the three markdown spellings; `FOOTNOTE_REFERENCE` and
+`FOOTNOTE_DEFINITION` are §8's keying. `SCHEME` and `MAILTO` are what keep an
+external URL from being read as a relative path.
+
+What is built on top of these is [the-model](/structure/the-model.md).
+
+`Links.resolve` is the one that turns a raw target into a bundle-relative path,
+and it is why a link split across a newline produces no edge — the extractor
+reads a line at a time.

data/.okf/structure/index.md

@@ -0,0 +1,22 @@
+# Structure
+
+Every file under `lib/`, grouped by the layer that owns it. One concept owns
+each file, and `test/unit/bundle_catalog_test.rb` fails if that stops being true
+in either direction — a file no concept names, or a concept naming a file that
+is gone.
+
+Fifty files, eight layers, and one rule underneath all of them: **the core is
+pure and the shell does the I/O.** `test/unit/boundary_test.rb` fails if a pure
+file names a shell class or touches `File`, `Dir`, `FileUtils` or stdio. Put new
+logic in the core; put new I/O in the shell.
+
+Read it bottom-up — each layer depends only on the ones below it.
+
+* [The Format Layer](format-layer.md) - `lib/okf.rb`, `path.rb`, `safe_read.rb`, `version.rb`, `markdown/` — pure: paths, containment, frontmatter, links, citations.
+* [The Model](the-model.md) - `concept.rb`, `bundle.rb`, `bundle/graph.rb`, `references.rb`, `row_filter.rb`, `skeleton.rb` — pure: a bundle in memory, and every derived view of it.
+* [The Analysers](the-analysers.md) - `bundle/validator*.rb`, `bundle/linter*.rb` — pure: §11 conformance, and curation quality, kept deliberately apart.
+* [Search](search.md) - `bundle/search.rb` and its two engines — pure: the facade owns the rows, the engines own the matching.
+* [The Disk Shell](the-disk-shell.md) - `concept/file.rb`, `bundle/reader.rb`, `writer.rb`, `folder.rb`, `registry.rb` — where directories become bundles and back.
+* [The Server and the Page](the-server.md) - `server/app.rb`, `hub.rb`, `hub/not_found.rb`, `runner.rb`, `render/graph.rb` — one ERB template, served or baked.
+* [The CLI](the-cli.md) - `cli.rb`, `cli/command.rb`, and the seventeen verb files — the only layer that parses argv, prints, and exits.
+* [The Skill](the-skill.md) - `skill.rb` — the companion agent skill and its installer.

data/.okf/structure/search.md

@@ -0,0 +1,53 @@
+---
+type: Component
+title: Search — One Facade, Two Engines
+description: The facade owns the rows, the snippets, the ranking fields and the engine registry; an engine owns only matching, declares its capabilities, and is chosen by what the query needs.
+tags: [structure, search, pure, extension-point]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/bundle/search.rb
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf/bundle/search.rb` | the facade: rows, snippets, weights, the `Corpus`, and the engine registry |
+| `lib/okf/bundle/search/scan.rb` | the default engine — raw-text scan, the only one that does `regexp` |
+| `lib/okf/bundle/search/index.rb` | the minifts engine — BM25+, the only one that does `fuzzy` and `prefix` |
+
+# The split
+
+The facade decides **what a result is**: `WEIGHTS` (which field counts how much),
+`FIELDS`, `SNIPPET_FIELDS`, `SNIPPET_RADIUS`, and the row shape every caller
+reads. An engine decides only **which documents matched**, and says what it can
+do through `CAPABILITIES`.
+
+`Search.engine_for(required)` picks by capability, not by name: `ROUTABLE` is the
+set a query can *demand* (`regexp`, `fuzzy`), `DEFAULT_ENGINE` is `:scan`, and
+`UnsupportedQuery` / `UnknownEngine` are the two honest refusals. `available?`
+lets an engine decline at runtime — the index engine needs `minifts` present.
+
+`Corpus` is the cross-bundle form, behind `Search.across`.
+
+# Why scan leads
+
+The scan is the default because a one-shot CLI cannot amortise an index build:
+3.00 s versus 0.24 s at 1,000 concepts. That is a real argument against the
+`minifts` dependency and it is recorded as such — but `--fuzzy` and parity with
+the graph page's browser-side ranking both still need it, and a cached index
+would restore the case outright.
+
+Parity is the subtler half: the Ruby index engine is a bit-for-bit port of the
+browser's MiniSearch, pinned to the same version the page lazy-loads, so an
+`--engine index` result and a search typed into the page rank identically.
+
+The verb that drives it is in [the-cli](/structure/the-cli.md).
+
+# `Search.register` is an extension point
+
+Append-only, idempotent by id, duck-type checked at registration —
+**deliberately the same shape as `CLI.register`**. An engine is a module
+answering `id`, `capabilities`, `available?`, `call`, and optionally `prepare`.
+Adding one is a registration, not an edit to the facade.

data/.okf/structure/the-analysers.md

@@ -0,0 +1,60 @@
+---
+type: Component
+title: The Analysers — Validate and Lint, Kept Apart
+description: Two pure analysers with a boundary that is a spec requirement rather than a preference — conformance may not reject curation problems, and curation may not emit conformance errors.
+tags: [structure, validate, lint, pure, spec]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/bundle/validator.rb
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf/bundle/validator.rb` | §11 conformance: hard errors, plus soft convention warnings |
+| `lib/okf/bundle/validator/result.rb` | the errors/warnings collection and `valid?` |
+| `lib/okf/bundle/linter.rb` | the curation report — every check, and their severities |
+| `lib/okf/bundle/linter/report.rb` | findings by severity, the stats, and `healthy?` |
+
+# The boundary is the point
+
+**`validate` and `lint` stay separate**, and the line is the spec's, not taste.
+§11 forbids the validator from *rejecting* a broken cross-link or a missing
+optional field — those are warnings at most. Curation findings belong to lint,
+which never emits a conformance error.
+
+A new check goes to one side or the other, and getting it wrong changes what
+exit code a user's CI sees: 0 ok, 1 a failing bundle, 2 a usage error.
+
+`Validator::CONVENTION_CHECKS` is the soft half — the warnings that are about
+convention rather than conformance, so a caller can tell them apart.
+
+# Validator: one method per spec clause
+
+The private methods are named for what they check — `validate_families`,
+`validate_generated`, `validate_verified`, `validate_sources`,
+`validate_usage_window`, `validate_lifecycle`, `validate_computation`,
+`validate_parameters`, `validate_contract_mapping`, `validate_okf_version`,
+`validate_index`, `validate_log`, `validate_reserved`, `validate_unparseable`.
+A new §5 family is a new one of these; that is the shape to follow.
+
+`validate_unparseable` is the one worth noticing: a file the reader could not
+parse is an error, not an absence. A validator that skipped it would report
+clean over the file most likely to be broken.
+
+# Linter: severities are data, and downstream depends on them
+
+`SEVERITIES` is the whole check list with each check's level, and `CHECKS` is
+its keys. It is a public fact rather than an implementation detail — okf-pro
+pins a frozen snapshot of it, because a released kernel that reclassified a
+check would change what that gem's gate blocks on.
+
+`only:` and `except:` select checks; `stale_before:`/`today:` supply the clock
+that `expired` and `stale` need. **A check that could not run is reported, not
+dropped**: `Report#to_h` carries `skipped_checks`, and `healthy?` over a silent
+skip would be the same lie in a smaller box.
+
+`DEFAULT_MIN_BODY` and `HUB_LIMIT` are the two tunables; `ACTOR_FORMS` is the
+`generated.by` grammar, shared with the validator through `Concept`.

data/.okf/structure/the-cli.md

@@ -0,0 +1,99 @@
+---
+type: Component
+title: The CLI — a Registry, a Base Class, and One File per Verb
+description: The only layer that parses argv, prints and exits; a verb is a class answering four questions about itself and one about a run, and the require order at the bottom of `cli.rb` is the order `okf help` prints.
+tags: [structure, cli, shell, extension-point, plugins]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/cli.rb
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf/cli.rb` | the command registry, the dispatcher, plugin discovery, and `okf help` |
+| `lib/okf/cli/command.rb` | the base every verb inherits: streams, refs, shared flags, printers |
+
+And one file per verb, each registering itself at load:
+
+| verb file | verb |
+|---|---|
+| `lib/okf/cli/skill.rb` | `skill` |
+| `lib/okf/cli/server.rb` | `server` |
+| `lib/okf/cli/render.rb` | `render` |
+| `lib/okf/cli/registry.rb` | `registry` and its eight subcommands |
+| `lib/okf/cli/lint.rb` | `lint` |
+| `lib/okf/cli/loose.rb` | `loose` |
+| `lib/okf/cli/validate.rb` | `validate` |
+| `lib/okf/cli/search.rb` | `search` |
+| `lib/okf/cli/index.rb` | `index` |
+| `lib/okf/cli/dirs.rb` | `dirs` |
+| `lib/okf/cli/stats.rb` | `stats` |
+| `lib/okf/cli/types.rb` | `types` |
+| `lib/okf/cli/tags.rb` | `tags` |
+| `lib/okf/cli/files.rb` | `files` |
+| `lib/okf/cli/references.rb` | `references` |
+| `lib/okf/cli/catalog.rb` | `catalog` |
+| `lib/okf/cli/graph.rb` | `graph` |
+
+**That table's order is the require order at the bottom of `cli.rb`, and the
+require order IS the order `okf help` lists the verbs in.** A test pins the
+result, but the coupling is in the source. What each verb *answers* is the
+[cli](/cli.md)'s group table, pinned against `OKF::CLI.builtins` by
+the same test; the walk a new one owes is
+[adding-a-verb](/testing/adding-a-verb.md).
+
+# What a verb is
+
+A `CLI::Command` subclass answering four questions about itself — `.id`,
+`.group`, `.help_rows`, `.hidden?` — and one about a run: `#call(argv)`,
+returning the exit status. **Privacy is the boundary**: `#call` is the whole
+public surface, so a helper cannot become a verb by accident. `DUCK_TYPE` is
+that contract, checked at registration.
+
+`GROUPS` is the ordering of the sections `okf help` prints; `ROW_FIELDS` is the
+`--fields`/`--except` projection vocabulary.
+
+# What the base class already gives you
+
+Do not re-implement any of these in a verb:
+
+* **refs** — `all_ref?`, and the `@slug` / bare `@` / `@group` resolution every
+  verb inherits, so `okf lint @handbook` works without the verb knowing about
+  registries.
+* **flags** — `json_flags`, `help_flag`, `projection_flags`, `filter_flags`,
+  `depth_flag`. `FILTER_KEYS` is the shared filter vocabulary.
+* **filtering** — `filter_entries`, `dir_scope`, `under_dir?`, and the `--area`
+  deprecation shim in `fold_area`.
+* **printing** — `print_inverted_index` is the shared shape behind `types`,
+  `tags` and friends.
+* **arity** — `no_extras?` is what makes a second bundle an exit-2 usage error
+  for the verbs that take only one. That was a real silent-wrong-answer bug:
+  `okf lint a b` once linted `a`, ignored `b`, and exited 0.
+
+# `CLI.register` is the extension point
+
+Append-only, idempotent by id, duck-type checked — **deliberately the same shape
+as `Search.register`**. Any gem with `okf/plugin.rb` on its load path can
+register a verb and okf finds it, with no edit here and no list of known addons
+(a test greps `cli.rb` to keep it that way).
+
+Discovery is **lazy**: a built-in never triggers a scan, so only an unknown verb
+or `okf help` pays for it. A plugin that raises is skipped and reported on
+stderr, never fatal. `declined` and `register_declined` are how a collision is
+reported rather than silently won.
+
+`PLUGIN_GEM_PREFIX` is `okf-`: **only gems named `okf-*` are loaded**, the same
+convention Jekyll and Vagrant use. Argue it as a convention if it is revisited —
+the threat it closes is thin, and overselling it invites false confidence.
+
+One rule underneath it *is* load-bearing: **naming a gem must never load it.**
+`plugin_gem_name` reads the spec's `full_gem_path` and requires nothing, because
+a refusal that happens after the `require` is not a refusal; a test pins it. A
+path belonging to no gem stays trusted — `ruby -I`, a Gemfile `path:`, a
+checkout — someone put it there.
+
+`seal_builtins!` is the line between what ships and what was installed, and it
+is what `extension?` reads to print the "installed extensions" section.

data/.okf/structure/the-disk-shell.md

@@ -0,0 +1,67 @@
+---
+type: Component
+title: The Disk Shell
+description: Where a directory becomes a Bundle and back — the reader, the atomic writer that validates before it publishes, the folder handle everything above it uses, and the registry.
+tags: [structure, shell, io, registry, atomic]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/bundle/folder.rb
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf/concept/file.rb` | one concept as an on-disk handle: read, save, delete, reload |
+| `lib/okf/bundle/reader.rb` | a directory to a `Bundle`, unparseable files kept rather than dropped |
+| `lib/okf/bundle/writer.rb` | a `Bundle` to a directory — locked, validated, then promoted atomically |
+| `lib/okf/bundle/folder.rb` | the on-disk bundle handle every layer above actually holds |
+| `lib/okf/registry.rb` | which bundles a machine or a project knows, addressed as `@slug` |
+
+These are the shell. Everything they call into is pure, and
+`test/unit/boundary_test.rb` keeps the arrow pointing one way.
+
+# Folder is the handle, not a convenience
+
+`Folder.load(dir)` is what the CLI, the server, the TUI and the MCP shell all
+hold. It delegates `validate`, `lint`, `graph`, `skeleton`, `catalog`, `hubs`,
+`directories`, `directory_index`, `stats`, `tag_groups`, `references` and
+`log_entries` to the pure model, and adds only what needs the disk:
+`concept_source`, `reference_files`, `reload`, `save`, and `Folder.label`.
+
+Reach for `Folder`, not `Reader` — the reader is how a folder is built, once.
+
+# The writer publishes or it does not
+
+`Writer#call` takes a lock, writes the whole tree to a temporary path, runs the
+**validator** against it, and only then promotes it into place. A bundle that
+would not validate is never published, and a crash mid-write leaves the old tree
+intact. `AlreadyExistsError` and `ValidationErrorFromResult` are the two
+refusals; `safe_markdown_path!` is the containment check, borrowed from the
+format layer rather than rewritten.
+
+No CLI verb writes a bundle. This is the library API's surface, which is why its
+integration coverage is low *by design*, and why a new verb reaching for it is
+worth a second look — [adding-a-verb](/testing/adding-a-verb.md) says where
+logic belongs instead.
+
+# Registry: two files, one answer
+
+`Registry` is the `@slug` layer. `HOME_ENV`/`DEFAULT_HOME` is the global
+registry under `$OKF_HOME` (default `~/.okf`); `LOCAL_FILE` is the project-local
+`.okf-registry.json` that `discover` finds by walking up from the working
+directory. **A discovered local registry replaces the global one outright** — it
+does not merge — and `NO_DISCOVERY_ENV` (`OKF_NO_DISCOVERY=1`) is the escape
+hatch that forces the global one, which is what a test that must not see the
+developer's registry sets.
+
+`relative_base` is why a local registry's paths stay relative and the file
+travels with the repository. `Registry#reopen` preserves it; `Registry.new(path)`
+does not, and reaching for the latter is how a reload comes to resolve every
+bundle against the wrong base.
+
+`Group` is a named, recursive set of bundles. `RESERVED_SLUGS` is `all`, because
+`@all` means every bundle and may not be shadowed. `slugify`, `dedupe`,
+`normalize` and `path_shaped?` are the naming rules a `registry set` goes
+through.

data/.okf/structure/the-model.md

@@ -0,0 +1,81 @@
+---
+type: Component
+title: The Model
+description: A bundle and its concepts in memory, with no disk and no stdio anywhere in it — plus the four derived views every other layer reads instead of recomputing.
+tags: [structure, model, pure, graph]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/bundle.rb
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf/concept.rb` | one concept: frontmatter, body, and every §5 question about it |
+| `lib/okf/bundle.rb` | the set: concepts, reserved files, and the rollups |
+| `lib/okf/bundle/graph.rb` | nodes and edges, plus the type and tag indexes |
+| `lib/okf/bundle/references.rb` | the `references/` inventory and who cites what |
+| `lib/okf/bundle/row_filter.rb` | one predicate for `--type/--dir/--tag/--status/--trust` |
+| `lib/okf/bundle/skeleton.rb` | directories, the arcs between them, and the suggested cut |
+
+All six are **pure**. No `File`, no `Dir`, no stdio — `test/unit/boundary_test.rb`
+fails the build if that changes.
+
+# Concept: the §5 vocabulary lives here
+
+`Concept` is where the spec's provenance model is implemented, and the parts
+worth knowing before adding a field:
+
+* `RESERVED_FILENAMES` and `reserved?` — `index.md` and `log.md` are not concepts.
+* `STATUSES` / `DEFAULT_STATUS` / `effective_status` — §4.1's lifecycle, with the
+  default applied once so no caller has to remember it.
+* `generated`, `generated_at`, `generated_by`, `declared_generated?` — a
+  *declared* provenance, never a derived one.
+* `verified`, `fold_tier`, `shows_trust?` — the trust tiers, and the predicate
+  that decides whether a bundle even has a trust dimension to show. That last one
+  is a single predicate on purpose: a UI that gates a chip one way and a facet
+  another promises rows it will not return.
+* `ISO_DATE`, `ISO_CUTOFF`, `ATTESTED_COMPUTATION`, `HUMAN_ACTOR` — the literals
+  the validator and the linter both read, rather than each spelling them.
+
+`CONCEPT_SCOPED_CHECKS` is the list of lint checks that are about one concept, and
+it is here rather than in the linter because it is a fact about the model.
+
+# Bundle: the rollups every other layer reads
+
+`Bundle` holds `concepts`, `reserved` and `unparseable` — an unreadable file is
+kept as an `Entry` with its error rather than dropped, because a validator that
+silently skips what it could not parse reports a clean bundle.
+
+`catalog`, `stats`, `hubs`, `directories`, `directory_index`, `tag_groups` and
+`paths_by_id` are the derived views. Read one rather than recomputing it: the
+CLI, the server, the TUI and the MCP shell all answer from these, which is what
+keeps four surfaces from disagreeing about the same number.
+
+`okf_version` is what the bundle *declares* (§12), never a literal — the health
+of every downstream v0.1-versus-v0.2 decision depends on that distinction.
+`VIRTUAL_ROOT` is the path a rootless in-memory bundle is contained against.
+
+The two analysers that read all of this are [the-analysers](/structure/the-analysers.md).
+
+# Graph, Skeleton, References, RowFilter
+
+`Graph.build` turns concepts into nodes and their links into edges, with
+`type_index` and `tag_index` alongside. `unlinked_ids` is the orphan set.
+`minimal:` and `body:` are how a caller asks for less than the whole thing —
+the payload the graph page embeds is not the payload `okf graph --json` prints.
+
+`Skeleton` is the directory-level view: `dirs`, `arcs` between them, and
+`suggested_cut` — the weight at which the arc diagram stops being a hairball.
+`cuts_for` maps that back onto concrete edges.
+
+`References` inventories the `references/` folder and the concepts citing each
+file, including the dangling ones.
+
+`RowFilter.matches?` is the *single* predicate behind every `--type`, `--dir`,
+`--tag`, `--status` and `--trust` filter in the CLI, the server and the TUI.
+`shows_trust?` is the same gate `Concept` exposes, reachable from a catalog row.
+A second filter implementation is how two views come to disagree about what
+"matching" means.

data/.okf/structure/the-server.md

@@ -0,0 +1,74 @@
+---
+type: Component
+title: The Server and the Page
+description: One ERB template that is the whole UI, served by a Rack app or baked to a file by `render` — plus the hub that mounts many bundles and owns the only writes in the server.
+tags: [structure, server, rack, render, xss]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/render/graph.rb
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf/render/graph.rb` | the ERB render — `Graph.static` bakes a file, the same class serves the page |
+| `lib/okf/server/app.rb` | the Rack app for one bundle: the page and its JSON endpoints |
+| `lib/okf/server/hub.rb` | N bundles at `/b/<slug>/`, plus the routes only a set can answer |
+| `lib/okf/server/hub/not_found.rb` | the 404 page: what was asked for, what exists, and the nearest match |
+| `lib/okf/server/runner.rb` | the built-in WEBrick to Rack bridge — no rackup file needed |
+
+The template itself is `graph/template.html.erb` beside `render/graph.rb`, and it
+is ~1,300 lines of inline JS and CSS. Both halves open with a section map; the JS
+one also names the three seams that actually couple the sections
+(`applyGraphFilter`, `setView`, the lazy caches). Read it before editing —
+`grep -n '── '` on the template prints the same list with live line numbers.
+
+# One template, two modes
+
+`Render::Graph.static` bakes a self-contained file with the payload embedded;
+`Server::App` serves the same template and lets the browser `fetch()` bodies on
+demand. **The two modes diverge exactly there** — baked `EMBED` versus fetched
+endpoints — which is why every browser spec runs twice, once against each.
+
+`LAYOUTS` is the five Cytoscape layouts; `MIN_SIZE`/`MAX_SIZE` the node scaling.
+
+# The page stays self-contained, and two XSS defenses hold the line
+
+Only Cytoscape, marked and DOMPurify load from a CDN at boot; Mermaid, Panzoom,
+MiniSearch and the extra layout engines lazy-load on first use. No htmx, no
+bundler, no build step.
+
+Two defenses, and a new render path that skips either one reopens the hole:
+
+* **`json_for_script`** escapes `<` so inlined data cannot break out of its
+  `<script>` — `LT_ESCAPE` is that literal.
+* **`DOMPurify.sanitize(marked.parse(...))`** runs on every fetched body before
+  it reaches `innerHTML`.
+
+# App: the endpoints
+
+`/` is the page; `/node`, `/node/meta`, `/catalog`, `/tags`, `/types`, `/index`
+and `/log` are the JSON it pulls. `SEARCH_ENGINE` is `:index` here — a server
+*can* amortise the build, which is the opposite of the CLI's default — and
+`warm_search` is where that build happens, at boot rather than on the first
+query.
+
+The bundles it serves are loaded through [the-disk-shell](/structure/the-disk-shell.md).
+
+# Hub: many bundles, and the only writes
+
+`Hub` mounts each bundle under `MOUNT` (`/b/<slug>/`) and adds the routes a set
+can answer that one bundle cannot: `GET /search` across all of them, `GET /b/`
+for the listing, and `POST /registry/{default,rename,remove,add}`.
+
+**Those four writes are the only writes in the whole server**, they are off
+unless `writable:`, and they are guarded: `authentic?` and `same_origin?` with a
+`token`, because a page that can rename a bundle is a page a hostile site would
+like to submit a form to.
+
+`Hub::NotFound` is a real page rather than a status code — it names what was
+asked for, lists what exists, and offers the nearest slug by edit distance. It
+carries its own CSS, mark and script because the 404 must render when the
+bundle it was asked for does not exist.

data/.okf/structure/the-skill.md

@@ -0,0 +1,52 @@
+---
+type: Component
+title: The Skill and Its Installer
+description: The companion agent skill ships from exactly one tree in this gem, and two generated copies elsewhere in the repository are regenerated rather than edited.
+tags: [structure, skill, generated, single-source]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/skill.rb
+---
+
+# The file
+
+| file | what it owns |
+|---|---|
+| `lib/okf/skill.rb` | `Skill.install` — the installer, its `ASSETS` tree, and `Skill::Error` |
+
+`ASSETS` points at `lib/okf/skill/`, and **that tree is the single canonical
+copy of the skill.** `okf skill <dest>` installs from it, so edit it there and
+nowhere else.
+
+`NAME` is `okf`, `SKILLS_DIR` is `skills`, and `nest:` decides whether the
+install lands in a `skills/okf/` subdirectory or directly in the destination —
+`--here` is the flag that turns it off. `force:` overwrites.
+
+# Two generated copies exist, and neither is editable
+
+`plugin/skills/okf` and `skills/okf` at the repository root are *generated*
+copies — the Claude Code plugin's, and the one a generic skill installer reads.
+`rake skill:sync` writes both from this tree and stamps the plugin manifest's
+version.
+
+Two guards fail on drift, both by file list **and** SHA-256 checksum:
+`rake skill:verify`, which `build` depends on, and `test/plugin/sync_test.rb`.
+So a release with a stale copy is impossible rather than a CI failure after the
+fact.
+
+# The markers in the skill text
+
+Guidance lines in the skill carry stable anchors — `<!-- check:<lint-check-id> -->`
+where a deterministic check enforces the point, `<!-- rule:okf-<slug> -->` for
+pure-judgment craft. They render invisibly and sync verbatim into every copy, so
+keep them on the line they annotate when you edit it. They exist so an eval can
+pin a claim and a concept can cite one.
+
+# Loading
+
+The other shell that loads on demand is [the-cli](/structure/the-cli.md).
+
+`skill.rb` is one of the two argv-facing shells that **do not** load with
+`require "okf"` — the CLI is the other. `exe/okf` requires them, and so must any
+test that drives them. An embedding application never pays for either.

data/.okf/testing/adding-a-verb.md

@@ -0,0 +1,76 @@
+---
+type: Playbook
+title: Adding a Verb, or a Subcommand
+description: The steps a new command owes, in order — the file it lives in, the base class it must not re-implement, the three folders it earns a test in, and the catalogue entry the pin will demand.
+tags: [testing, playbook, cli]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+resource: lib/okf/cli/command.rb
+---
+
+# Before adding one, check it is not already there
+
+Seventeen commands and eight subcommands already exist, catalogued in
+[cli](/cli.md) and [read-views](/capabilities/read-views.md), and `okf help`
+prints the same list. Most of what a new verb would want is a *flag* on an
+existing view rather than a view of its own: the shared filters and projections
+— `--type/--dir/--tag/--status/--trust` and `--fields/--except` — compose with
+every list already.
+
+# The walk
+
+1. **Write the failing test first**, in `test/integration/cli/`, in a file named
+   for the verb. Run it. It must fail for the reason you predicted — not because
+   a fixture is missing or a regex has a typo, which prove nothing about the
+   behaviour. A test written *after* the fix certifies only the code it was read
+   off.
+2. **One file per verb**, at `lib/okf/cli/<verb>.rb`, registering itself at load.
+   A subcommand family stays in its parent's file, but earns its own *test*
+   file — `registry set` is a surface a user invokes on its own.
+3. **Subclass `CLI::Command` and add nothing it already has.** Refs, the shared
+   flags, `filter_entries`, `print_inverted_index`, `no_extras?` — the list is in
+   [the-cli](/structure/the-cli.md). Re-implementing one of these is how two
+   verbs come to disagree about what `--dir` means.
+4. **`#call` is the whole public surface.** Everything else is private, so a
+   helper cannot become a verb by accident. Answer `.id`, `.group`,
+   `.help_rows`, `.hidden?`.
+5. **Add its `require` to the block at the bottom of `cli.rb`**, in the position
+   you want it to appear in `okf help` — that order *is* the help order, and a
+   test pins the result.
+6. **Decide the arity, explicitly.** If it takes one bundle, `no_extras?` must
+   make a second an exit-2 usage error. If it takes several, it belongs in the
+   `across_bundles/` group with the ones that do.
+7. **Prove it in every folder it has** — `by_dir/`, `by_registry/`, and
+   `across_bundles/` (which for a single-bundle verb means proving the *refusal*).
+   Then exercise the whole surface, not the happy path: every flag once, every
+   output format it offers, every exit code it can return, and the combinations
+   that actually interact.
+8. **Update what describes it.** A new file under `lib/` needs its line in the
+   concept in [structure/](/structure/) that owns its layer, and the verb needs
+   its cell in [cli](/cli.md)'s group table.
+   `test/unit/bundle_catalog_test.rb` fails on either. So does the gem's README,
+   which owes a line for every verb; nothing enforces that one.
+9. **Run the same test unedited**, then read the uncovered lines:
+   `bundle exec rake test:integration`, then diff
+   `coverage/integration/.resultset.json` for the files you changed. Three
+   shapes hide there by habit, because a unit test walked them first: the
+   *second* output format, an *error* branch and the exit code it carries, and
+   *malformed-input* robustness.
+
+# Where the logic goes
+
+Not in the verb. The CLI parses argv, prints and exits; the question belongs to
+the pure model or to an analyser, so that the server, the TUI and the MCP shell
+get the same answer without asking the CLI. If a verb is computing something,
+it is probably a method on `Bundle` that has not been written yet.
+
+New I/O goes in the shell, new logic in the core, and
+`test/unit/boundary_test.rb` fails the build if a pure file forgets.
+
+# The exit codes are a contract
+
+`0` ok, `1` a failing bundle, `2` a usage error. And the older half of that
+contract: **`validate` and `lint` stay separate** — a conformance check may not
+live in lint and a curation finding may not fail validate. See
+[structure/the-analysers](/structure/the-analysers.md).

data/.okf/testing/index.md

@@ -0,0 +1,12 @@
+# Testing
+
+Why the suite is shaped the way it is — integration first, its coverage read as
+a map rather than a score, and the graph page proven in a real browser — is in
+[Design](/design/): [integration-first](/design/integration-first.md) and
+[browser-tests](/design/browser-tests.md).
+
+What is here is the procedure: the ordered walk a new surface owes, ending at the
+checks that will refuse it if a step is skipped.
+
+* [Adding a Verb](adding-a-verb.md) - The steps a new command or subcommand owes, in order.
+* [The test harness](the-harness.md) - One base class for the whole suite, and why the 2.4 floor binds `test/` exactly as it binds `lib/`.