okf 1.3.0 → 1.5.0

data/lib/okf/server/graph.rb

@@ -21,8 +21,8 @@ module OKF
       LAYOUTS = %w[cose concentric breadthfirst circle grid].freeze
 
       # Node-diameter range in px; the template scales within it by node degree.
-      MIN_SIZE = 24
-      MAX_SIZE = 70
+      MIN_SIZE = 14
+      MAX_SIZE = 44
 
       # The 6-character JSON unicode escape for `<` (backslash, u, 0, 0, 3, c),
       # built from the backslash code point so no literal escape appears here.

data/lib/okf/skill/SKILL.md

@@ -7,14 +7,16 @@ description: >-
   what the tools report — and routes every mechanical question (validation,
   linting, views, the graph server) to the installed `okf` CLI. Use whenever
   capturing project knowledge (services, APIs, schemas, metrics, runbooks,
-  decisions) into a bundle, updating one after code or docs change, checking a
-  bundle's conformance or curation quality, rendering it as a graph, or working in
+  decisions) into a bundle, retrieving an answer from a bundle without reading
+  it whole, updating one after code or docs change, checking a bundle's
+  conformance or curation quality, rendering it as a graph, or working in
   a repo that contains an OKF bundle — a `.okf/` directory or a root `index.md`
   carrying `okf_version`. Triggers on: "document this in OKF", "update the
-  knowledge bundle", "capture this as a concept", "validate/lint/serve the
+  knowledge bundle", "capture this as a concept", "what do we know about X?",
+  "where is X documented?", "search the bundle", "validate/lint/serve the
   bundle", or a task needing knowledge from an OKF bundle already in the repo.
 user-invocable: true
-argument-hint: "[produce|maintain|consume|<okf-cli-verb>] [dir] [--flags]"
+argument-hint: "[search|produce|maintain|consume|<okf-cli-verb>] [dir] [--flags]"
 allowed-tools: Read Write Edit Grep Glob Bash
 ---
 
@@ -79,9 +81,12 @@ Don't memorize the surface — `okf --help` maps every verb, `okf <verb> --help`
 flags. The division of labour is the whole game:
 
 - **Shell out — never eyeball —** anything a verb computes: conformance (§9), what
-  exists, what links where, what's stale, the map. Every read verb takes `--json`
-  and the list views filter by type/area/tag, so ask the narrow question instead of
-  paging the bundle.
+  exists, what links where, where a term lives, what's stale, the map. Every read
+  verb takes `--json` and the list views filter by type/area/tag, so ask the narrow
+  question instead of paging the bundle.
+- **Skeleton first, bodies last.** `index --no-body`, `search`, `graph --minimal`,
+  and `--fields` projections each answer for a fraction of a dump's bytes; full
+  bodies are the final step of a retrieval, never the first. <!-- rule:okf-skeleton-first -->
 - **You judge — the CLI can't —** meaning: contradictions, semantic staleness
   (parses fine, no longer true), whether a loose file is terminal-by-design, whether
   a singleton tag is a deliberate marker. Tool output is evidence, never a verdict.
@@ -116,10 +121,10 @@ producing or maintaining, and the verbatim spec [SPEC.md](reference/SPEC.md)
 when you need chapter and verse.
 
 **No subcommand?** Infer intent: "document this / capture X" → `produce`; "the
-code changed, update the docs" → `maintain`; a repo already carrying a bundle
-plus a task needing its knowledge → `consume`; "check / graph / preview it" →
-run the matching CLI verb and interpret the result. When genuinely ambiguous,
-ask.
+code changed, update the docs" → `maintain`; "what do we know about X / where
+is X documented" → `search`; a repo already carrying a bundle plus a task
+needing its knowledge → `consume`; "check / graph / preview it" → run the
+matching CLI verb and interpret the result. When genuinely ambiguous, ask.
 
 **Which directory?** Use the path given. Otherwise default to `.okf/` at the repo
 root, but first detect whether the project already keeps its bundle elsewhere
@@ -136,6 +141,7 @@ Read the referenced playbook before executing — it *is* the procedure.
 | Verb | Category | What it does | Reference |
 |------|----------|--------------|-----------|
 | *(none)*   | Orient | recommend the highest-value next move; never auto-run | [playbooks/menu.md](playbooks/menu.md) |
+| `search`   | Use    | answer a question from the bundle: map → finder → only the winning bodies | [playbooks/search.md](playbooks/search.md) |
 | `produce`  | Author | create or extend a bundle | [playbooks/produce.md](playbooks/produce.md) |
 | `maintain` | Author | sync the bundle's content with reality after a change | [playbooks/maintain.md](playbooks/maintain.md) |
 | `consume`  | Use    | use the bundle as context for a task | [playbooks/consume.md](playbooks/consume.md) |

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

@@ -3,8 +3,10 @@
 1. **Orient first** (the [SKILL.md](../SKILL.md) reflex): `okf index <dir>` maps the
    whole bundle in one pass — every directory's index body, rollups, and listings —
    and `log.md` gives recent history. Then follow links only into the concepts the
-   task needs. For a large bundle, `okf graph --json` gives the whole link structure
-   at once so you can plan a traversal without opening every file.
+   task needs. For a *pointed question* rather than broad context, switch to the
+   [search playbook](search.md): map → finder (`okf search`) → only the winning
+   bodies. For a large bundle, `okf graph --json --minimal` gives the whole link
+   structure at once so you can plan a traversal without opening every file.
 2. Treat broken links as not-yet-written knowledge, not errors.
 3. **Write-back reflex:** if you learn something durable while working — a fact the
    bundle lacks, a link it is missing, a concept that no longer matches reality —

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

@@ -11,10 +11,12 @@ up. The modelling craft behind steps 3 and 7 lives in
    catch enumeration drift, because **grep cannot find an index entry that is
    missing.** (This is the always-on reflex in [SKILL.md](../SKILL.md).)
 2. **Find *every* affected concept** — the failure mode is fixing only the obvious
-   one. Don't rely on reading the whole bundle; that only scales on tiny ones. Grep
-   the changed asset's `resource` URI across the bundle, grep its path/name, and use
-   `okf graph --json` to pull the concepts that link *to* the ones you're touching.
-   Let grep and the graph find them so nothing drifts silently.
+   one. Don't rely on reading the whole bundle; that only scales on tiny ones. Run
+   `okf search <dir> <resource-URI-or-name>` — it hits frontmatter *and* bodies and
+   returns ranked concept ids, not line noise; grep is the backstop for what search
+   cannot express — and `okf graph <dir> --json --minimal` to pull the edges (the
+   concepts that link *to* the ones you're touching) without paying for every body.
+   Let search and the graph find them so nothing drifts silently.
 3. Update bodies and `timestamp`; fix or add cross-links; create new concepts for
    new assets; mark retired assets with a `**Deprecation**` note rather than
    silently deleting the context that explains them.

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

@@ -14,18 +14,22 @@ is the lede.
    - **No bundle** → lead with **`produce`** (create the first bundle from the
      code, docs, or what lives only in people's heads). Nothing else applies yet.
 3. **Read the bundle's state** from the CLI, not by eyeballing:
-   `okf validate <root> --json`, `okf lint <root> --json`, `okf loose <root>
-   --json`. Then recommend by what they report, most-blocking first:
+   `okf validate <root>`, `okf lint <root>`, `okf loose <root>` — the plain
+   text views, which are lighter than `--json` when you are reading a report
+   rather than extracting structure from it. Then recommend by what they
+   report, most-blocking first:
    - **`validate` has errors** → lead with **`curate`**: §9 conformance errors are
      the only hard failures, and curate fixes them before anything else.
    - **clean `validate`, but `lint`/`loose` findings** → lead with **`curate`** to
      settle the curation debt (reachability, backlog, completeness, hygiene),
      naming the top one or two categories from the report.
    - **clean across the board** → the bundle is healthy, so lead with **`consume`**
-     (put it to work on the task at hand) and offer **`maintain`** as the move for
-     when the code or docs have since changed. If the working tree has uncommitted
-     changes to the code the bundle describes (`git status`), prefer **`maintain`**:
-     that is exactly the drift it exists to close.
+     (put it to work on the task at hand) — or **`search`** when what the user
+     actually has is a question ("what do we know about X?") — and offer
+     **`maintain`** as the move for when the code or docs have since changed. If
+     the working tree has uncommitted changes to the code the bundle describes
+     (`git status`), prefer **`maintain`**: that is exactly the drift it exists
+     to close.
 4. **Freshness is off by default.** If the bundle carries timestamps, note that a
    plain `lint` said nothing about staleness and `okf lint <root> --stale-after
    90d` is the check that would.

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

@@ -0,0 +1,42 @@
+# Playbook: search — retrieve knowledge without paying for the whole bundle
+
+Reached by `search <query…>` — the query is everything after the verb; given no
+query, ask what to find. Retrieval matters as much as curation: a bundle nobody
+can query cheaply is dead weight. The discipline is progressive disclosure
+(spec §6): every step pays a few hundred bytes to decide what the next step
+reads, and full bodies are read last, and only the winners.
+
+1. **Guard once**: `command -v okf`. Missing → [doctor](doctor.md). No CLI at
+   all → read the root `index.md`, then each relevant area's `index.md`, by hand.
+2. **Ingest the map and decide where to look.** `okf index <dir> --no-body` is
+   the skeleton: every directory with its concept count, types, tags, children.
+   *You* do the semantic matching here — the question names a meaning, the map
+   names areas; connect them by judgment, not string equality. When an area
+   looks right, `okf index <dir> --area <name>` buys its authored index body and
+   listing (titles + descriptions) for the price of one directory.
+   <!-- rule:okf-search-map-first -->
+3. **Cut across with the finder when the question is lexical.** An exact
+   symbol, an error code, a column name, a phrase — things structure won't
+   surface — go to `okf search <dir> <terms>` (terms AND together; `--regexp`
+   for patterns like `err_[a-z]+_409`). Scope it with what the map taught you:
+   `--area billing`, `--type Decision`, `--tag idempotency`, `--in body`.
+   Matches rank by where they hit, and the snippet often *is* the answer.
+4. **Read only the winners.** A match row's `id` is its file: `<dir>/<id>.md`.
+   Read that file — not its folder, never the whole tree. Follow its links (§5)
+   one hop at a time; check `log.md` when freshness matters.
+5. **Answer, then write back.** Cite the concept ids you used. If the answer
+   was missing, stale, or needlessly hard to find — a gap, a broken link, an
+   index entry that should exist — switch to [maintain](maintain.md) and record
+   it. Retrieval friction is curation signal. <!-- rule:okf-search-write-back -->
+
+Anti-patterns, each a real token bill:
+
+- **The dump.** `okf graph --json` with bodies, or `cat`-ing the tree "for
+  context", costs more than every step above combined. Retrieval needs at most
+  `graph --json --minimal`, and only to plan a multi-hop traversal.
+- **Grep before map.** Grep cannot find the entry that is *missing*, and it
+  returns line noise where `search` returns ranked concepts. Grep is the
+  fallback when the CLI is absent, not the first move.
+- **Mechanical synonym retries.** The finder is exact by design; *you* are the
+  fuzzy layer. When terms miss, learn the bundle's vocabulary — `okf tags
+  <dir>`, `okf types <dir>` — and re-ask in its own words.

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

@@ -67,8 +67,8 @@ the domain.
 ### `resource` is the bridge to reality <!-- rule:okf-resource-bridge -->
 Set `resource` (a canonical URI) **only** when a concept *is* a real, addressable
 asset — a table (`bigquery://…`), a service repo, a dashboard, an endpoint. Its
-presence is what lets `maintain` find every concept affected by a changed asset by
-grepping for that URI. Abstract concepts — a decision, a principle, a metric
+presence is what lets `maintain` find every concept affected by a changed asset in
+one `okf search <dir> <uri>` call. Abstract concepts — a decision, a principle, a metric
 definition — have no resource, and **omitting it is meaningful**, not laziness. Do
 not invent placeholder URIs.
 

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

@@ -1,7 +1,7 @@
 # OKF tool verbs — the `okf` CLI
 
-`validate`, `lint`, `loose`, `index`, `catalog`, `files`, `tags`, `types`, `stats`,
-`server`, and `graph` are **not** eyeball passes and are not
+`validate`, `lint`, `loose`, `search`, `index`, `catalog`, `files`, `tags`, `types`,
+`stats`, `server`, and `graph` are **not** eyeball passes and are not
 reimplemented in this skill. They run the deterministic `okf` executable shipped by
 the companion gem — the single source of truth for OKF mechanics. Your job is to
 invoke it correctly and interpret the result, not to reason out conformance by hand.
@@ -108,11 +108,34 @@ defect — a terminal leaf (a backlog item, a spec reference) can be loose by de
 `loose` surfaces the set so you can judge intent (see the
 [maintain playbook](../playbooks/maintain.md)).
 
+## search — ranked text retrieval (metadata + body)
+
+The browser page's search brought to the CLI and extended to bodies, so "which
+concept covers X?" costs rows, not body reads. `okf search <dir> <term…>`:
+terms AND together — every term must hit at least one searched field, not
+necessarily the same one — as case-insensitive substrings, or as Ruby regular
+expressions with `--regexp`/`-e` (an invalid pattern is a usage error, exit 2).
+`--in a,b` restricts the searched fields (title, id, tags, type, description,
+body); the shared `--type/--area/--tag` filters narrow the candidates *first*,
+so a search scoped by what `index` taught you stays surgical.
+
+Rows rank by **where** they hit — title 5, id 4, tags 3, type/description 2,
+body 1, summed over matched fields — and carry one bounded context snippet from
+the strongest match that needs context (description or body). Deliberately not
+fuzzy: the consuming agent is the fuzzy layer — when terms miss, learn the
+bundle's vocabulary from `tags`/`types` and re-ask in its own words, rather
+than hammering synonyms. Advisory read: **exit 0 even with zero matches**.
+JSON: `{ bundle, query, count, matches: [{ id, title, type, area, tags,
+matched, score, snippet }] }`, projectable with `--fields/--except`. The
+retrieval procedure that puts this verb in sequence — map first, finder second,
+bodies last — is the [search playbook](../playbooks/search.md).
+
 ## index — the progressive-disclosure map (§6)
 
-The "orient before you read" view, and the one read verb that sees the layer the
-others can't: `index.md` files are reserved/structural, so `catalog`/`files`/… (all
-concept views) never show them. `okf index <dir>` prints one entry per directory
+The "orient before you read" view, and the read verb that sees the layer the
+concept views can't: `index.md` files are reserved/structural, so
+`catalog`/`files`/… never show them (in the browser, the Indexes tab and
+folder clicks render this same map). `okf index <dir>` prints one entry per directory
 that holds concepts or carries an `index.md`, root first — the authored index body
 (frontmatter stripped), a `type`/`tag` rollup over the concepts that live directly
 there, its child directories, and the concept listing. Run it first when picking up
@@ -177,21 +200,36 @@ Starts a local HTTP server (`okf server <dir>`; `-p`/`--port`, default 8808, and
 `--bind`) and prints its URL — stop it with Ctrl-C. The page boots from a lean
 payload (nodes carry only `id` and `title`, plus compact type/tag indexes) and
 fetches each concept's markdown body **live from disk** as you click it, so the
-initial load stays small and edits show without a restart. Concepts render as nodes
+initial load stays small and edits show without a restart. Mermaid code blocks
+in a body render as diagrams, and a click (or tap) opens the diagram full
+screen with drag-to-pan and wheel/pinch zoom. Concepts render as nodes
 coloured by `type` and sized by degree, links as edges, with a detail panel
 (rendered markdown, "Links to" / "Linked from" backlinks), layout switching,
-type/area/tag filters on every view, and search. It is a Rack app, so the same
-server can be mounted in a host app (e.g. Rails).
-
-**Trust boundary:** the page loads Cytoscape and marked from a CDN and
-renders each concept's markdown body **without sanitization**, so only serve
-bundles you trust. Inlined graph data cannot break out of its `<script>` (every
-`<` is escaped), but the fetched markdown is rendered unsanitized.
+type/area/tag filters on every view, and search. The authored layer is in the
+UI too: the Files view carries **Files | Indexes** tabs — the Indexes tab
+lists the log first (the chronological index), then every `index.md` — and
+folder nodes in file-tree mode and area boxes in cluster mode open a
+directory's §6 map in the inspector (authored, or synthesized when none
+exists). Links to an `index.md`, `log.md`, or bare directory navigate instead
+of dead-ending, and the log is fetched fresh on every read, so a
+just-appended entry shows without a restart. `?view=index` jumps straight to
+the Indexes tab. It is a Rack app, so the same server can be mounted in a
+host app (e.g. Rails).
+
+**Trust boundary:** the page renders each fetched markdown body through
+DOMPurify and escapes everything it inlines (every `<` in the graph data is
+escaped, so it cannot break out of its `<script>`), but it still loads its
+viewer libraries (Cytoscape, marked, DOMPurify — plus Mermaid and Panzoom,
+lazy-loaded on first use) from a CDN and renders whatever
+links the bundle carries — so only serve bundles you trust.
 
 ## graph — the raw structure
 
 Prints the node/edge graph. `--json` emits a machine-readable dump (`nodes` with
-`id`/`type`/`title`/`description`/`tags`, and `edges`) you can pipe into other
-analysis or use to plan a traversal before consuming a large bundle. `--no-body`
-drops each node's body; `--minimal` ships only `id`/`title` plus the type/tag
-indexes — the lean shape the `server` page boots from.
+`id`/`type`/`title`/`description`/`tags` **and, by default, every `body`** — the
+part that dominates the bytes on a real bundle — plus `edges`) you can pipe into
+other analysis. To *plan* a traversal, structure is all you need: `--no-body`
+drops each node's body, and `--minimal` ships only `id`/`title` plus the type/tag
+indexes — the lean shape the `server` page boots from. Reach for the full dump
+only when the task truly consumes every body; for one question, the
+[search verb](#search--ranked-text-retrieval-metadata--body) is orders cheaper.

data/lib/okf/version.rb

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

data/lib/okf.rb

@@ -39,6 +39,7 @@ module OKF
   require "okf/concept"
   require "okf/bundle"
   require "okf/bundle/graph"
+  require "okf/bundle/search"
   require "okf/bundle/validator"
   require "okf/bundle/validator/result"
   require "okf/bundle/linter"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -52,31 +52,6 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
-- ".okf/capabilities/agent-skill.md"
-- ".okf/capabilities/graph-server.md"
-- ".okf/capabilities/index.md"
-- ".okf/capabilities/library-api.md"
-- ".okf/capabilities/linter.md"
-- ".okf/capabilities/read-views.md"
-- ".okf/capabilities/validator.md"
-- ".okf/cli.md"
-- ".okf/design/core-shell-split.md"
-- ".okf/design/index.md"
-- ".okf/design/ruby-floor.md"
-- ".okf/design/runtime-dependencies.md"
-- ".okf/design/server-trust-boundary.md"
-- ".okf/format/citations.md"
-- ".okf/format/cross-links.md"
-- ".okf/format/frontmatter.md"
-- ".okf/format/index.md"
-- ".okf/format/okf-format.md"
-- ".okf/index.md"
-- ".okf/log.md"
-- ".okf/model/bundle.md"
-- ".okf/model/concept.md"
-- ".okf/model/graph.md"
-- ".okf/model/index.md"
-- ".okf/overview.md"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
@@ -90,6 +65,7 @@ files:
 - lib/okf/bundle/linter.rb
 - lib/okf/bundle/linter/report.rb
 - lib/okf/bundle/reader.rb
+- lib/okf/bundle/search.rb
 - lib/okf/bundle/validator.rb
 - lib/okf/bundle/validator/result.rb
 - lib/okf/bundle/writer.rb
@@ -112,6 +88,7 @@ files:
 - lib/okf/skill/playbooks/maintain.md
 - lib/okf/skill/playbooks/menu.md
 - lib/okf/skill/playbooks/produce.md
+- lib/okf/skill/playbooks/search.md
 - lib/okf/skill/reference/APACHE-2.0.txt
 - lib/okf/skill/reference/SPEC.md
 - lib/okf/skill/reference/authoring.md

data/.okf/capabilities/agent-skill.md

@@ -1,46 +0,0 @@
----
-type: Capability
-title: Companion agent skill (skill)
-description: A SKILL.md plus references and templates, shipped inside the gem, that teaches an agent to author OKF.
-resource: lib/okf/skill.rb
-tags: [skill, agent, install]
-timestamp: 2026-07-11T12:00:00Z
----
-
-# Overview
-
-The gem carries the **OKF agent skill** — a `SKILL.md` with reference and
-template files that teach a coding agent to *produce*, *maintain*, and *consume*
-[OKF](../format/okf-format.md) bundles and to drive the [CLI](../cli.md). The
-authoring judgment the executable can't encode lives here; the executable handles
-the mechanics.
-
-# `okf skill <dest>` installs it
-
-`OKF::Skill.install` copies the skill into a destination you name — Claude Code's
-`.claude`, an agent-agnostic `.agents`, wherever your agent looks. The rules are
-deliberate:
-
-- the **destination is required** — no magic default — so a user always decides
-  where the skill lands;
-- it lands in a **`skills/okf/` folder** by default (`.claude` →
-  `.claude/skills/okf`), because an agent discovers a skill as
-  `<skills-dir>/<name>/SKILL.md` — so the skill settles in its own folder, not
-  loose among the others. A `<dest>` already ending in `skills` only gains the
-  `okf/` leaf; one already named `okf` is used as-is (idempotent); `--here`
-  pastes straight into `<dest>`, wherever it is;
-- the resolved directory must be **empty unless `--force`**, so a customized
-  skill is never clobbered.
-
-# One canonical copy, versioned with the gem
-
-The skill ships **only** from `lib/okf/skill/**` — that tree is the single source,
-and `install` copies from it. Because the skill rides inside the gem, installing
-the gem already puts the skill on the machine, and the skill's CLI reference can
-**never drift** from the executable it was released with. Local installs
-elsewhere are gitignored so they never masquerade as the source.
-
-# Citations
-
-[1] [lib/okf/skill.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/skill.rb) — the installer.
-[2] [lib/okf/skill/SKILL.md](https://github.com/serradura/okf-gem/blob/main/lib/okf/skill/SKILL.md) — the skill itself.

data/.okf/capabilities/graph-server.md

@@ -1,63 +0,0 @@
----
-type: Capability
-title: Interactive graph server (server)
-description: A self-contained HTML knowledge graph served over HTTP, and a mountable Rack app.
-resource: lib/okf/server/app.rb
-tags: [server, graph, rack, diagram]
-timestamp: 2026-07-12T12:00:00Z
----
-
-# Overview
-
-`okf server` boots an interactive view of the [graph](../model/graph.md):
-`OKF::Server::App` is a Rack app that serves one self-contained HTML page which
-draws the bundle with Cytoscape and renders concept bodies with marked, sanitized
-by DOMPurify. Because
-it is a plain Rack app, it also mounts inside a host application (e.g. a Rails
-route) — the built-in WEBrick runner is just the default, injected so tests drive
-it without opening a socket.
-
-# The page stays self-contained
-
-One ERB template, inline CSS and JS, no build step and no bundler. The only
-external assets are Cytoscape, marked, and DOMPurify from a CDN — plus Mermaid,
-lazy-loaded only when a concept body actually contains a diagram; everything else
-is inlined.
-The graph draws from a **minimal** node payload and pulls each concept's body
-**on demand** via `fetch()`, which is why even a large bundle loads fast.
-
-# Request flow
-
-```mermaid
-sequenceDiagram
-  participant B as Browser
-  participant A as okf server (Rack app)
-  B->>A: GET /
-  A-->>B: HTML page + inlined minimal graph data
-  Note over A,B: angle brackets escaped (json_for_script) — safe
-  B->>A: GET /node?id=… (on demand)
-  A-->>B: concept Markdown body
-  Note over A,B: marked renders it, DOMPurify sanitizes it — safe
-```
-
-# Endpoints
-
-| Path | Serves |
-|------|--------|
-| `/` | the HTML page (graph + inlined minimal data) |
-| `/node?id=` | one concept's rendered body |
-| `/node/meta?id=` | one concept's metadata |
-| `/catalog`, `/tags`, `/types` | the JSON behind the browser panels |
-
-# Trust boundary
-
-Both paths into the page are guarded. Inlined data goes through `json_for_script`,
-which escapes `<` so it cannot break out of its `<script>`; each fetched body is
-run through `DOMPurify.sanitize(marked.parse(...))`, which strips any script or
-handler before it reaches the DOM. See the
-[server trust boundary](../design/server-trust-boundary.md) for what that does and
-does not cover.
-
-# Citations
-
-[1] [lib/okf/server/app.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/server/app.rb) — the Rack app and its routes.

data/.okf/capabilities/index.md

@@ -1,20 +0,0 @@
-# Capabilities
-
-The five things the gem does over a bundle, plus the read views that print it at
-a glance. All of them run over the same [pure model](../model/) and are fronted
-by the [CLI](../cli.md).
-
-# Judge
-
-* [Conformance validator](validator.md) - the §9 legal check; the only capability that can fail a bundle.
-* [Curation linter](linter.md) - advisory quality report across six categories; never rejects.
-
-# Serve & read
-
-* [Interactive graph server](graph-server.md) - a self-contained HTML graph over HTTP, mountable as a Rack app.
-* [Read views](read-views.md) - `index`, `catalog`, `files`, `types`, `tags`, `stats`, `loose`, `graph` — the browser views as text, plus the `index` map.
-
-# Use & author
-
-* [Library API](library-api.md) - the Ruby surface: pure model plus on-disk handles.
-* [Companion agent skill](agent-skill.md) - the skill shipped inside the gem that teaches an agent to author OKF.

data/.okf/capabilities/library-api.md

@@ -1,72 +0,0 @@
----
-type: Capability
-title: Library API
-description: The Ruby surface — a pure in-memory model plus on-disk handles, an "ActiveRecord for the filesystem".
-resource: lib/okf.rb
-tags: [library, api, ruby, diagram]
-timestamp: 2026-07-12T12:00:00Z
----
-
-# Overview
-
-Everything the [CLI](../cli.md) does is available in-process. `require "okf"`
-gives you two layers, split cleanly by the [core/shell rule](../design/core-shell-split.md):
-
-- **pure, in-memory** — [`OKF::Concept`](../model/concept.md) and
-  [`OKF::Bundle`](../model/bundle.md), which you build, interrogate, validate,
-  lint, and graph with **no disk involved**;
-- **on-disk handles** — `OKF::Concept::File` and `OKF::Bundle::Folder`, which add
-  `load` / `save` / `reload` / `delete` on top of the pure model.
-
-`require "okf"` stops at those two layers: the [CLI](../cli.md) and the skill
-installer load only when asked for (from `exe/okf`, or an explicit
-`require "okf/cli"` / `require "okf/skill"`), so an app embedding the library
-never drags in the command-line machinery.
-
-```mermaid
-classDiagram
-  class Concept {
-    <<pure>>
-  }
-  class Bundle {
-    <<pure>>
-  }
-  class Graph {
-    <<pure>>
-  }
-  class ConceptFile {
-    <<on-disk>>
-  }
-  class Folder {
-    <<on-disk>>
-  }
-  Bundle "1" o-- "*" Concept : contains
-  Bundle ..> Graph : builds
-  ConceptFile ..> Concept : wraps
-  Folder ..> Bundle : wraps
-```
-
-`ConceptFile` is `OKF::Concept::File`; `Folder` is `OKF::Bundle::Folder` — each
-on-disk handle wraps a pure counterpart and adds load/save/reload/delete.
-
-# Build knowledge without touching Markdown
-
-The pure layer is the surface an embedding app uses to reuse the gem over
-knowledge it already holds as records. Construct concepts from data, assemble a
-bundle, and call `#validate`, `#lint`, or `#graph` — no Markdown round-trip
-needed. The lower-level pieces work standalone too:
-`OKF::Bundle::Validator.call`, `OKF::Bundle::Linter.call`,
-`OKF::Bundle::Graph.build`, `OKF::Markdown::Frontmatter.parse`.
-
-# Folder is an ActiveRecord for the filesystem
-
-`OKF::Bundle::Folder.load(dir)` reads a directory into a pure bundle;
-`Folder.new(bundle:, root:).save` materializes one back — and **validates §9
-before publishing** through an atomic writer, so it never leaves a broken bundle
-on disk. `OKF::Server::App.new(folder)` turns a folder straight into the
-[graph server](graph-server.md).
-
-# Citations
-
-[1] [README.md — Library](https://github.com/serradura/okf-gem/blob/main/README.md) — worked examples of both layers.
-[2] [lib/okf.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf.rb) — the require surface.

data/.okf/capabilities/linter.md

@@ -1,49 +0,0 @@
----
-type: Capability
-title: Curation linter (lint)
-description: An advisory curation-quality report across six categories and sixteen checks — it never rejects a bundle.
-resource: lib/okf/bundle/linter.rb
-tags: [linting, curation, cli]
-timestamp: 2026-07-11T12:00:00Z
----
-
-# Overview
-
-`okf lint` answers the question [validate](validator.md) is forbidden to touch:
-*is this bundle well-curated — navigable, complete, trustworthy?* It reports over
-exactly the soft things §9 tolerates, has its own `OKF::Bundle::Linter` and
-report, and never emits a conformance error. It is **advisory**: exit `0` even
-with findings unless you opt in with `--fail-on warn`.
-
-# Six categories, sixteen checks
-
-| Category | Checks |
-|----------|--------|
-| Reachability | `orphan`, `not_in_index`, `disconnected_component`, `unlinked` |
-| Backlog | `missing_concept`, `broken_index_entry` |
-| Completeness | `stub`, `missing_title`, `missing_description`, `missing_timestamp` |
-| Freshness | `stale` |
-| Provenance | `uncited_external`, `broken_citation` |
-| Hygiene | `duplicate_title`, `unused_reference_def`, `undefined_reference`, `self_link` |
-
-Select with `--only` / `--except` (by check id), tune the stub threshold with
-`--min-body`, and get the whole report as a machine substrate with `--json`.
-
-# The freshness gotcha
-
-Freshness is **off by default** — a plain `lint` never reports `stale`. Pass
-`--stale-after <90d | 12w | 2026-01-01>` when concepts carry a
-[`timestamp`](../format/frontmatter.md). The CLI resolves that to an absolute
-cutoff so the pure linter never reads the clock.
-
-# Where lint stops and an agent begins
-
-`lint` is structural: it cannot judge **contradictions** or **semantic**
-staleness (a concept that parses fine but no longer matches reality). Those need
-meaning. `lint --json` is precisely the structured input an agent reasons over to
-close that gap. The [`loose`](read-views.md) view is a folder-grouped lens over
-the single `unlinked` check.
-
-# Citations
-
-[1] [lib/okf/bundle/linter.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/bundle/linter.rb) — the sixteen checks and their categories.