okf 1.4.0 → 1.5.0

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.4.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.4.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.

data/.okf/capabilities/read-views.md

@@ -1,84 +0,0 @@
----
-type: Capability
-title: Read views (index, catalog, files, types, tags, stats, loose, graph)
-description: The server's browser panels reproduced on the CLI, plus the index map, so an agent reads a bundle at a glance without a browser.
-tags: [read, cli, json]
-timestamp: 2026-07-12T12:00:00Z
----
-
-# Overview
-
-The [graph server](graph-server.md) renders a bundle in a browser; these verbs
-render the same knowledge as text, so an agent (or a terminal) reads it directly.
-Each prints a scannable human view by default and machine JSON with `--json`, and
-all are advisory reads that exit `0`. They share
-[`OKF::Bundle#catalog`](../model/bundle.md) and the
-[graph indexes](../model/graph.md) for their data.
-
-# The views
-
-| Verb | Shows | Grouped by |
-|------|-------|------------|
-| `index` | each directory's index body, type/tag rollup, child dirs, and concept listing | directory (root first) |
-| `catalog` | concepts with type, tags, link counts, status | area |
-| `files` | files with titles | folder |
-| `types` | [types](../format/frontmatter.md) with their concepts | count |
-| `tags` | [tags](../format/frontmatter.md) with their concepts | count |
-| `stats` | rollups: concepts, areas, types, cross-links, tags | — |
-| `loose` | degree-0 concepts (no [links](../format/cross-links.md) in or out) | folder |
-| `graph` | the raw nodes and edges | — (`--minimal` / `--no-body`) |
-
-# `index` is the orient-first map (§6)
-
-Alone among the read views, `index` shows the reserved `index.md` layer: the
-concept views skip those structural files, so only `index` renders the
-[progressive-disclosure map](../format/okf-format.md) — one entry per directory
-(root first) with its authored index body, a type/tag rollup over the concepts
-living directly there, its child directories, and the concept listing. `--area`
-narrows to one directory and repeats (`root` names the bundle root); `--no-body`
-drops the prose to a skeleton. It is the cheapest orientation when picking up a
-bundle, and the only view that exposes *enumeration drift* — a listing entry that
-should exist but is missing, which no grep can find. A directory that holds
-concepts but no `index.md` gets its listing synthesized and tagged `(no index.md)`,
-a prompt to write a real map rather than a defect.
-
-# JSON output — compact, and projectable
-
-`--json` is **compact by default** — single-line, the token-efficient substrate an
-agent consumes; `--pretty` (which implies `--json`) indents the same JSON for a
-human. On the per-item list views — `index`, `catalog`, `files` — `--fields a,b`
-keeps only those properties and `--except a,b` drops them (mutually exclusive; an
-unknown name is a usage error that lists the valid ones). Projection runs before
-emission, so an agent never pays tokens for a field it dropped: `okf index <dir>
---except body,listing` is the lean directory skeleton, the difference between a few
-hundred bytes and hundreds of KB on a large bundle.
-
-# Narrowing and regrouping
-
-The four list views — `catalog`, `files`, `types`, `tags` — accept the filters
-*orthogonal* to how they group, so you ask a narrow question instead of paging
-the whole bundle (matching is case-insensitive):
-
-| View | Filters it accepts |
-|------|--------------------|
-| `catalog`, `files` | `--type`, `--area`, `--tag` |
-| `types` | `--area`, `--tag` (it already groups by type) |
-| `tags` | `--type`, `--area` (it already groups by tag) |
-
-`tags --by type|area` regroups the tag index under each concept dimension with
-within-group counts — the view for curating a
-[tag](../format/frontmatter.md) vocabulary: which tags cluster in which area,
-which type leans on which tags.
-
-# `loose` is a curation lens, not an error
-
-`loose` is the folder-grouped view over [lint](linter.md)'s `unlinked` check —
-distinct from `orphan`. An `index.md` listing makes a file *reachable* (not an
-orphan) but is **not a graph edge**, so a listed file can still float here. A
-loose file may be perfectly fine — a terminal leaf like a backlog item is loose
-by design — so `loose` surfaces the set for a human or agent to judge and always
-exits `0`.
-
-# Citations
-
-[1] [cli.md — read views](https://github.com/serradura/okf-gem/blob/main/lib/okf/skill/reference/cli.md) — the views and their flags.

data/.okf/capabilities/validator.md

@@ -1,40 +0,0 @@
----
-type: Capability
-title: Conformance validator (validate)
-description: Implements the spec's §9 conformance definition exactly — three hard conditions, everything else a warning.
-resource: lib/okf/bundle/validator.rb
-tags: [validation, conformance, cli]
-timestamp: 2026-07-11T12:00:00Z
----
-
-# Overview
-
-`okf validate` answers one question: *is this a legal [OKF](../format/okf-format.md)
-bundle?* `OKF::Bundle::Validator` implements §9 exactly and is the **only**
-capability that can fail a bundle — exit `1` on any hard error, `0` otherwise.
-
-# The three hard conditions (errors)
-
-| Rule | Condition |
-|------|-----------|
-| §9.1 | every non-reserved file has a parseable [frontmatter](../format/frontmatter.md) block |
-| §9.2 | every such block has a **non-empty `type`** |
-| §9.3 | every `index.md` / `log.md` present is well-formed (nested index has no frontmatter, root index carries only `okf_version`, log dates are ISO) |
-
-# Everything else is a warning
-
-The validator is **forbidden by §9** from rejecting a bundle for soft issues, so
-these are warnings that never change conformance:
-
-- missing recommended fields, non-list `tags`, an unparseable `timestamp`;
-- **broken [cross-links](../format/cross-links.md)** (§5.3) — consumers MUST
-  tolerate them.
-
-Judging those is the [linter](linter.md)'s job, and keeping the two apart is a
-[hard design contract](../design/core-shell-split.md). The
-[writer](library-api.md) runs this validator *before* publishing, so a saved
-bundle is never written non-conformant.
-
-# Citations
-
-[1] [lib/okf/bundle/validator.rb](https://github.com/serradura/okf-gem/blob/main/lib/okf/bundle/validator.rb) — the §9 implementation.