okf 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1f08bf7a4a1a49ef0bea5953b380df85bdbe79e1b30998e0d168d122d4a20c2
-  data.tar.gz: 97aff0312275def9b514c0e50bcc3872a73e3a304efa7ac8d85046a846711a7f
+  metadata.gz: 95f1db166e67b4a3c4b4fbd679bce25ef19e3de3f50f010e13e6b1630ddacfcf
+  data.tar.gz: cef59494dbd959585ba85f631b025eb5ba88ab94e38c6d440ac8aed1b2fbd61a
 SHA512:
-  metadata.gz: '09c1784bee88f5a74087345fa3ee26a13ba2875ff9447559852c23cf294f6f05ffa457eabdd67cbbac4bc5e255b3cc91f128863fab92d9b5a88f3ae41062e871'
-  data.tar.gz: d26885ca8683d2de6ad036d7a158089ba4b7e12437131b617687bad51bd15157f64dd148bcd7f8f502a95ae48d644f9c5674464e82ff3f97bc34faf61a24dc24
+  metadata.gz: ff17b4c61c5e9fb63e63235fb19fb51b75ce7626acafdfaa88a367f5a6c40a2e9c2eabe7af0283fac5cf6edfd1349b22aa900fa23c321522bd29b19e76befd95
+  data.tar.gz: 8846d3604a36b3818024f21d88d04cc62bc91d374dac1a7fd34e17d6eb8269fcf72f7675191a1b3243144359d847c734cf049d4025cf962fb5bf7369f7cc8fac

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

@@ -4,14 +4,15 @@ 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-11T12:00:00Z
+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. Because
+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.
@@ -19,8 +20,9 @@ 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 and marked from a CDN — plus Mermaid, lazy-loaded
-only when a concept body actually contains a diagram; everything else is inlined.
+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.
 
@@ -35,7 +37,7 @@ sequenceDiagram
   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 UNSANITIZED — trust boundary
+  Note over A,B: marked renders it, DOMPurify sanitizes it — safe
 ```
 
 # Endpoints
@@ -49,11 +51,12 @@ sequenceDiagram
 
 # Trust boundary
 
-Fetched Markdown bodies are rendered **without sanitization**, so only serve
-bundles you trust. Data inlined into the page is safe — it goes through
-`json_for_script`, which escapes `<` so it cannot break out of its `<script>` —
-but the on-demand body is not. See the
-[server trust boundary](../design/server-trust-boundary.md) for the full picture.
+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
 

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

@@ -4,7 +4,7 @@ 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-11T12:00:00Z
+timestamp: 2026-07-12T12:00:00Z
 ---
 
 # Overview
@@ -18,6 +18,11 @@ gives you two layers, split cleanly by the [core/shell rule](../design/core-shel
 - **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 {

data/.okf/design/index.md

@@ -7,4 +7,4 @@ the code looks the way it does.
 * [Core/shell split](core-shell-split.md) - pure logic must never touch disk, stdio, or the shell layer; a test enforces it.
 * [Ruby 2.4 floor](ruby-floor.md) - runs on the Ruby an OS already ships; newer APIs are banned.
 * [Runtime dependencies](runtime-dependencies.md) - exactly `rack` and `webrick`, no ActiveSupport.
-* [Server trust boundary](server-trust-boundary.md) - the served page renders concept bodies unsanitized.
+* [Server trust boundary](server-trust-boundary.md) - the served page sanitizes concept bodies and escapes inlined data; both XSS paths are closed.

data/.okf/design/server-trust-boundary.md

@@ -1,35 +1,40 @@
 ---
 type: Constraint
 title: The server trust boundary
-description: The served page renders concept bodies without sanitization, so only serve bundles you trust.
+description: The served page sanitizes each concept body before rendering and escapes inlined data, so both XSS paths into the page are closed.
 resource: lib/okf/server/templates/graph.html.erb
 tags: [security, server, xss]
-timestamp: 2026-07-11T12:00:00Z
+timestamp: 2026-07-12T12:00:00Z
 ---
 
 # Overview
 
-The [graph server](../capabilities/graph-server.md) is designed for trusted
-bundles. Its page renders each concept's Markdown body **without sanitization**
-(marked, no sanitizer), so a hostile bundle could carry active content. The rule
-is simple: **only serve bundles you trust.**
+The [graph server](../capabilities/graph-server.md) renders whatever bundle you
+point it at, and a bundle is just files, so the page has to assume a body might
+carry active content. Two defenses handle that — one for each path into the page.
 
 # Where the boundary sits
 
-There are two different data paths into the page, and only one is escaped:
+There are two data paths into the page, and each carries its own guard:
 
 | Path | Handling | Safe? |
 |------|----------|-------|
 | Graph data **inlined** into the page | through `json_for_script`, which escapes `<` | yes — it cannot break out of its `<script>` |
-| Concept bodies **fetched** on demand (`/node?id=`) | rendered as Markdown, unsanitized | no — this is the trust boundary |
+| Concept bodies **fetched** on demand (`/node?id=`) | `marked` renders the Markdown, then `DOMPurify.sanitize` scrubs it before it reaches the DOM | yes — scripts, handlers, and `javascript:` URLs are stripped |
 
-So the XSS boundary is not the inlined data (that is handled); it is the
-on-demand [body](../format/cross-links.md) render. The
-[self-contained page](../capabilities/graph-server.md) keeps external assets down
-to Cytoscape and marked from a CDN, but that does not make the rendered body
-safe.
+The [description](../format/cross-links.md) shown in the inspector takes a third
+path and never needs the client's help: the server escapes it
+(`OKF::Server::App#description_fragment`) before sending it, so it arrives inert.
+
+# What sanitizing does not cover
+
+DOMPurify removes the code, not the content. The page still fetches and shows the
+links, images, and Mermaid diagrams a body names (Mermaid runs in its `strict`
+mode), and it pulls Cytoscape, marked, and DOMPurify from a CDN. So the rule is no
+longer *only serve bundles you trust* — it is the ordinary care you would give any
+document from a source you do not know.
 
 # Citations
 
-[1] [README.md — Server trust boundary](https://github.com/serradura/okf-gem/blob/main/README.md) — the unsanitized-render warning.
-[2] [lib/okf/server/templates/graph.html.erb](https://github.com/serradura/okf-gem/blob/main/lib/okf/server/templates/graph.html.erb) — `json_for_script` and the body render.
+[1] [README.md — Server trust boundary](https://github.com/serradura/okf-gem/blob/main/README.md) — the two-defense summary.
+[2] [lib/okf/server/templates/graph.html.erb](https://github.com/serradura/okf-gem/blob/main/lib/okf/server/templates/graph.html.erb) — `json_for_script` and the `DOMPurify.sanitize(marked.parse(...))` render.

data/.okf/log.md

@@ -1,6 +1,7 @@
 # Update Log
 
 ## 2026-07-12
+* **Sync**: caught the bundle up with the gem at 1.1.0 — the [graph server](capabilities/graph-server.md) now sanitizes each fetched body with DOMPurify before rendering, so the [server trust boundary](design/server-trust-boundary.md) closes the on-demand render path (its [design listing](design/) reworded to match), and the [library API](capabilities/library-api.md) notes that `require "okf"` loads the library alone now that the CLI and skill load on demand.
 * **Sync**: caught the bundle up with the CLI at 1.0.0 — documented the new `index` command (the §6 progressive-disclosure map, the read view that sees the reserved `index.md` layer), compact-by-default JSON with `--pretty`, and `--fields`/`--except` projection on the list views, in [read views](capabilities/read-views.md) plus the `index`-verb enumerations in the [CLI](cli.md), the [overview](overview.md), and the [capabilities](capabilities/) index listing.
 
 ## 2026-07-11

data/.okf/overview.md

@@ -15,8 +15,9 @@ gives you leverage over knowledge that already lives as Markdown.
 
 ```mermaid
 flowchart LR
-  skill["companion<br/>agent skill"] -. authors .-> bundle[("OKF v0.1 bundle<br/>Markdown + YAML")]
+  skill["companion<br/>agent skill"] -. authors/curate .-> bundle[("OKF v0.1 bundle<br/>Markdown + YAML")]
   bundle --> model["pure model<br/>Concept · Bundle · Graph"]
+  skill -. execute .-> cli
   subgraph cli ["okf CLI"]
     validate["validate — legal? §9"]
     lint["lint — well-curated?"]
@@ -29,13 +30,13 @@ flowchart LR
 Over such a bundle the gem gives you five capabilities behind one
 [command-line tool](cli.md):
 
-| Capability | What it answers | Verb |
-|------------|-----------------|------|
-| [Conformance validator](capabilities/validator.md) | Is this a legal OKF bundle? (§9) | `validate` |
-| [Curation linter](capabilities/linter.md) | Is it navigable, complete, fresh? | `lint` / `loose` |
-| [Interactive graph server](capabilities/graph-server.md) | Can I explore it visually? | `server` |
-| [Library API](capabilities/library-api.md) | Can my Ruby program use it? | (in-process) |
-| [Companion agent skill](capabilities/agent-skill.md) | Can an agent author it? | `skill` |
+| Capability                                               | What it answers                   | Verb             |
+| -------------------------------------------------------- | --------------------------------- | ---------------- |
+| [Companion agent skill](capabilities/agent-skill.md)     | Can an agent author it?           | `skill`          |
+| [Conformance validator](capabilities/validator.md)       | Is this a legal OKF bundle? (§9)  | `validate`       |
+| [Curation linter](capabilities/linter.md)                | Is it navigable, complete, fresh? | `lint` / `loose` |
+| [Interactive graph server](capabilities/graph-server.md) | Can I explore it visually?        | `server`         |
+| [Library API](capabilities/library-api.md)               | Can my Ruby program use it?       | (in-process)     |
 
 Alongside those, a family of [read views](capabilities/read-views.md) —
 `index`, `catalog`, `files`, `tags`, `stats`, `graph` — print the bundle at a
@@ -43,7 +44,7 @@ glance so an agent reads it without a browser.
 
 # The two ideas it inherits from the format
 
-- **Dual audience.** Every file serves a human skimming it *and* an agent
+- **Dual audience.** Every file serves a human skimming it _and_ an agent
   extracting from it, so bodies are structural Markdown and
   [links](format/cross-links.md) are plain Markdown links — both readers already
   understand them.

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [1.2.0] - 2026-07-12
+
+- Claude Code plugin. The repository now doubles as a plugin marketplace:
+  `/plugin marketplace add serradura/okf-gem`, then `/plugin install okf@okfgem`.
+  The plugin carries the canonical skill (a generated copy; `rake plugin:sync`
+  keeps it in lockstep with `lib/okf/skill`, and a test fails on drift), one
+  front-door command (`/okf:gem`: no arguments orients on the CLI, the bundle,
+  and what `validate`/`lint` report and recommends the highest-value next move
+  without running one, `doctor` installs the gem and doctors the repo's bundle,
+  `curate` runs the full validate + lint + loose cycle, anything else hands the
+  task to the skill), and a PostToolUse hook that runs `okf validate` +
+  `okf lint` after every edit inside a bundle and hands the relevant findings
+  back as context: every conformance error, plus the warnings and lint findings
+  that concern the edited file. The checks are the CLI's own, so the feedback is
+  deterministic. The hook stays silent outside bundles, and when the CLI is
+  missing it suggests `/okf:gem` once per session instead of erroring on each
+  edit. It is config-free to silence: `OKF_CURATE_DISABLED=1` turns it off,
+  `OKF_CURATE_QUIET=1` keeps the findings but drops that suggestion, and an
+  `<!-- okf-disable -->` comment in a file skips curation for that one. The skill
+  routes through per-verb playbooks (`playbooks/`), and its signature guidance
+  lines carry stable `<!-- check:… -->` / `<!-- rule:okf-… -->` markers.
+  Nothing under `plugin/` ships in the gem.
+
+## [1.1.0] - 2026-07-12
+
+- The graph server now sanitizes every concept body before rendering it. The
+  page runs marked's HTML output through [DOMPurify](https://github.com/cure53/DOMPurify)
+  (loaded from the same CDN as Cytoscape and marked) on the way to the DOM, so a
+  bundle carrying active content in a Markdown body can no longer script the
+  viewer. Inlined graph data was already escaped through `json_for_script`; this
+  closes the other path.
+- `require "okf"` now loads the pure library only. The two argv-facing shells —
+  `OKF::CLI` and the `OKF::Skill` installer — load on demand, from `exe/okf` or
+  an explicit `require "okf/cli"` / `require "okf/skill"`. `optparse` moves with
+  the CLI, so an embedding app (e.g. a Rails store) that only reaches for the
+  in-memory model and on-disk handles no longer pulls in the command-line
+  machinery. The CLI itself is unchanged.
+
 ## [1.0.0] - 2026-07-12
 
 Initial release.

data/README.md

@@ -5,17 +5,59 @@
 </h1>
 </p>
 
-> A rough project, cut and polished into a jewel. And like any jewel, what it is
-> worth comes down to what it does with knowledge: reading it, validating it,
-> curating it, and putting it on display.
-
-**okf-gem** reads, validates, lints, and serves **Open Knowledge Format (OKF)**
-v0.1 bundles. OKF is portable knowledge: a directory of Markdown files with YAML
-frontmatter that both humans and agents read. Each file is a _concept_; a
-directory of them is a _bundle_. Over such a bundle the gem gives you five
-things: a library API, a conformance validator, a curation linter, an
-interactive graph server, and a companion agent skill. All but the library API
-are reachable through one `okf` command-line tool.
+<p align="center">
+  <i>A lightweight Ruby gem for OKF: author, curate, and serve bundles as an interactive graph.</i>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/okf"><img src="https://img.shields.io/gem/v/okf" alt="Gem version"></a>
+  <a href="https://rubygems.org/gems/okf"><img src="https://img.shields.io/gem/dt/okf" alt="Downloads"></a>
+  <a href="https://github.com/serradura/okf-gem/actions/workflows/main.yml"><img src="https://github.com/serradura/okf-gem/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/serradura/okf-gem"><img src="https://img.shields.io/badge/ruby-%3E%3D%202.4-black" alt="Ruby >= 2.4"></a>
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License: Apache-2.0"></a>
+  <a href="lib/okf/skill/reference/SPEC.md"><img src="https://img.shields.io/badge/OKF-v0.1-6E56CF" alt="OKF v0.1"></a>
+  <a href="#claude-code-plugin"><img src="https://img.shields.io/badge/Claude%20Code-plugin-D97757" alt="Claude Code plugin"></a>
+</p>
+
+**okf-gem** — `okf` on RubyGems — reads, validates, lints, and serves
+**Open Knowledge Format (OKF)** v0.1 bundles: directories of Markdown files with YAML frontmatter that humans and agents read from one source. It does not define a new place to keep knowledge; it gives you leverage over knowledge that already lives as Markdown. Each file is a _concept_; a directory of them is a _bundle_.
+
+> **Quick start.** One skill, one command, a curation hook, and a CLI that
+> validates, lints, indexes, and serves your Markdown as a graph. In Claude Code,
+> add the plugin and let it set everything up: `/plugin marketplace add
+serradura/okf-gem`, then `/plugin install okf@okfgem`, then `/okf:gem`. On the
+> command line: `gem install okf`, then `okf validate <dir>`.
+
+Here is what it is able to do:
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset=".github/overview-dark.png">
+    <img src=".github/overview.png" width="100%" alt="The companion agent skill authors and curates an OKF v0.1 bundle (Markdown + YAML). A pure model (Concept, Bundle, Graph) reads that bundle and feeds both the okf CLI (validate — legal per §9; lint — well-curated; server — explore) and a library API you embed in Ruby.">
+  </picture>
+</p>
+
+Over a bundle the gem gives you the `okf`
+command-line tool (the library API is also usable in-process). Each capability
+below links to the concept that documents it: this gem's own knowledge is an OKF
+bundle, so you can read its design in the format it defends.
+
+| Capability                                                    | What it answers                   | Verb             |
+| ------------------------------------------------------------- | --------------------------------- | ---------------- |
+| [Companion agent skill](.okf/capabilities/agent-skill.md)     | Can an agent author it?           | `skill`          |
+| [Conformance validator](.okf/capabilities/validator.md)       | Is this a legal OKF bundle? (§9)  | `validate`       |
+| [Curation linter](.okf/capabilities/linter.md)                | Is it navigable, complete, fresh? | `lint` / `loose` |
+| [Interactive graph server](.okf/capabilities/graph-server.md) | Can I explore it visually?        | `server`         |
+| [Library API](.okf/capabilities/library-api.md)               | Can my Ruby program use it?       | in-process       |
+
+> [!TIP]
+> **Browse the gem as knowledge, not just docs.** This README is the front door;
+> the depth lives in the [`.okf/`](.okf) bundle this repo ships. Start at the
+> [overview](.okf/overview.md), then follow the graph into the
+> [capabilities](.okf/capabilities/) (what it does), the
+> [design constraints](.okf/design/) (why it stays this light), and the
+> [format itself](.okf/format/) (what it operates on). Run `okf server .okf` to
+> walk the same bundle as an interactive graph.
 
 It is deliberately light so it runs on the Ruby your OS already ships:
 
@@ -23,10 +65,87 @@ It is deliberately light so it runs on the Ruby your OS already ships:
   its core dependency;
 - only two runtime dependencies: `rack` (the server is a mountable Rack app)
   and `webrick` (unbundled from Ruby in 3.0);
-- no ActiveSupport, no build step, no JavaScript toolchain.
+- no ActiveSupport, no build step, no JavaScript toolchain — the
+  [design constraints](.okf/design/) that hold this line are enforced by tests.
+
+That range is not aspirational: CI runs the full test suite and RuboCop on every
+one of these on each push.
+
+## Why OKF
+
+Project knowledge (why a service exists, what a metric really measures, the
+reasoning a schema encodes) lives scattered across wikis, code comments, and
+whoever happened to be in the room, and an agent re-derives it every session. OKF
+gives it one durable, diffable home, versioned next to the code it describes and
+read from the same file by people and agents alike. [OKF][okf] is an open,
+vendor-neutral format (Google Cloud, 2026); this gem is the Ruby-native way to
+work with it.
+
+[okf]: https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
+
+Knowledge already has several homes near an agent, and each holds a different
+thing. None of the others is built for curated, durable team knowledge:
+
+|                                | OKF bundle (this)                               | `CLAUDE.md` / `AGENTS.md`  | Agent auto-memory        | Wiki / Notion    |
+| ------------------------------ | ----------------------------------------------- | -------------------------- | ------------------------ | ---------------- |
+| Holds                          | curated team knowledge                          | standing instructions      | what one agent picked up | human docs       |
+| Versioned with the code        | ✅                                              | ✅                         | ❌                       | ❌               |
+| Portable across agents         | ✅ plain Markdown + YAML                        | ⚠️ per-harness conventions | ❌ per-agent store       | ⚠️ export needed |
+| Typed and queryable            | ✅ frontmatter + graph                          | ❌ prose                   | ❌                       | ⚠️ partially     |
+| Reviewed in PRs                | ✅                                              | ✅                         | ❌ implicit              | ⚠️ rarely        |
+| Scales past one context window | ✅ progressive disclosure (`okf index`)         | ❌ loaded whole            | ⚠️ partially             | n/a              |
+| Checked by tooling             | ✅ (`okf validate` + `lint`), exit codes for CI | ❌                         | ❌                       | ❌               |
+
+The last row is this gem's job. The other homes have no detector, so their
+drift stays invisible; a bundle's drift shows up as findings you can gate on.
+
+## What a bundle looks like
+
+A bundle is just a directory; each concept is one Markdown file whose path is its
+id. This repo documents _itself_ in OKF, so the tree below is real:
+
+```
+.okf/
+├── index.md                       # progressive-disclosure map (root carries okf_version)
+├── log.md                         # ISO-dated change history, newest first
+├── overview.md
+├── format/frontmatter.md
+├── model/graph.md
+└── capabilities/graph-server.md   # one concept = one file
+```
+
+The only hard requirement is YAML frontmatter with a non-empty `type`; everything
+else is optional and tolerated when missing. A concept (here the real
+`capabilities/graph-server.md`, body trimmed) reads:
+
+```markdown
+---
+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-11T12:00:00Z
+---
+
+# Overview
+
+`okf server` boots an interactive view of the [graph](../model/graph.md) …
+```
+
+That bundle is this gem's own documentation. Clone the repo and run
+`okf server .okf` to browse it as the graph diagrammed at the top of this file.
 
 ## Installation
 
+> **In Claude Code**, the plugin is the fastest path: two commands install the whole
+> toolchain (skill, `/okf:gem`, and the curation hook). See
+> [Claude Code plugin](#claude-code-plugin). Everywhere else, install the gem:
+
+| Ruby version     | 2.4 | 2.5 | 2.6 | 2.7 | 3.0 | 3.1 | 3.2 | 3.3 | 3.4 | 4.0 |
+| ---------------- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Tested/Supported | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  | ✅  |
+
 ```bash
 gem install okf
 # or, in a project
@@ -46,9 +165,10 @@ bundle exec rake install
 okf validate  <dir> [--json]                            # check OKF v0.1 conformance (§9)
 okf lint      <dir> [--json] [--fail-on warn] [...]     # report curation-quality issues
 okf loose     <dir> [--json]                            # list files with no graph links, by folder
+okf index     <dir> [--json] [--area A] [--no-body]     # progressive-disclosure map (§6): bodies, rollups, listings
 okf server    <dir> [-p PORT] [--bind ADDR] [...]       # serve the interactive graph over HTTP
 okf graph     <dir> [--json] [--minimal] [--no-body]    # print the knowledge graph
-okf catalog | files | tags | stats  <dir> [--json]      # the browser views, on the CLI
+okf catalog | files | tags | types | stats  <dir> [--json]   # the browser views, on the CLI
 okf skill     <dest> [--here] [--force]                 # install the companion agent skill
 okf --version
 ```
@@ -56,10 +176,6 @@ okf --version
 Exit codes: `0` success, `1` non-conformant bundle (or a `lint --fail-on`
 threshold crossed), `2` usage error.
 
-> [!NOTE]
-> Section numbers like §5, §8, and §9 refer to the OKF v0.1 spec, bundled with
-> the skill at [`lib/okf/skill/reference/SPEC.md`](lib/okf/skill/reference/SPEC.md).
-
 ```bash
 $ okf validate docs
 OKF v0.1 conformance — docs
@@ -82,11 +198,13 @@ _The graph server on this repo's own [`.okf`](.okf) bundle, with the
 
 `graph` and `server` are best-effort (§9): a file with invalid frontmatter is
 skipped (and noted on stderr), not fatal, so one bad file never breaks the rest.
-Before serving a bundle you did not author, read the
-[server trust boundary](#server-trust-boundary).
+The [graph server](.okf/capabilities/graph-server.md) concept walks the request
+flow and endpoints; the [server trust boundary](#server-trust-boundary) below
+explains how the page handles a bundle you did not author.
 
-`lint` reports curation quality (reachability, backlog, completeness, freshness,
-provenance, and hygiene) separately from `validate`. It is advisory: it exits
+`lint` (the [curation linter](.okf/capabilities/linter.md)) reports curation
+quality (reachability, backlog, completeness, freshness, provenance, and hygiene)
+separately from `validate`. It is advisory: it exits
 `0` even with findings unless you opt into gating with `--fail-on warn`.
 
 ```bash
@@ -116,11 +234,27 @@ always exits `0`.
 
 ## Agent skill
 
-The gem carries the companion OKF agent skill: a `SKILL.md` plus reference
+The gem carries the [companion OKF agent skill](.okf/capabilities/agent-skill.md):
+a `SKILL.md` plus reference
 and template files that teach a coding agent to author, maintain, and consume OKF
 bundles and to drive the commands above. Because the skill ships inside the gem,
 installing the gem already puts the skill on your machine, and the skill's
 CLI reference can never drift from the executable it was released with.
+Using Claude Code? The [plugin](#claude-code-plugin) below installs this same
+skill plus a post-edit curation hook.
+
+The skill routes a small set of verbs. In Claude Code they run as `/okf:gem
+<verb>`; used standalone, the skill infers the verb from your request.
+
+| Verb             | What it does                                                                                      |
+| ---------------- | ------------------------------------------------------------------------------------------------- |
+| _(none)_         | Orient on the bundle and recommend the highest-value next move                                    |
+| `produce`        | Create or extend a bundle from code, docs, or knowledge in people's heads                         |
+| `maintain`       | Sync the bundle's content with reality after the code or docs change                              |
+| `consume`        | Use the bundle as context for a task, writing back what you learn                                 |
+| `curate`         | Structural upkeep as it stands: `validate` + `lint` + `loose`                                     |
+| `doctor`         | Install and verify the CLI, then doctor the bundle                                                |
+| `<okf-cli-verb>` | Run any CLI verb (`validate`, `lint`, `index`, `server`, the read views) and interpret its output |
 
 Point it at your agent's config directory (or its skills directory) and the tree
 settles in its own `skills/okf/` folder, so a shared skills directory never gets
@@ -139,7 +273,8 @@ is never clobbered.
 
 ## Library
 
-The gem is two layers: pure in-memory data (`OKF::Concept`, `OKF::Bundle`)
+The gem (the [library API](.okf/capabilities/library-api.md)) is two layers: pure
+in-memory data (`OKF::Concept`, `OKF::Bundle`)
 you build, interrogate, and analyze with no disk involved, and on-disk
 handles (`OKF::Concept::File`, `OKF::Bundle::Folder`) that add
 load/save/reload/delete, an "ActiveRecord for the filesystem".
@@ -199,7 +334,8 @@ The lower-level pieces are usable on their own too: `OKF::Bundle::Validator.call
 
 ### Conformance model
 
-`validate` implements the spec's [§9 conformance definition](lib/okf/skill/reference/SPEC.md#9-conformance)
+`validate` (the [conformance validator](.okf/capabilities/validator.md)) implements
+the spec's [§9 conformance definition](lib/okf/skill/reference/SPEC.md#9-conformance)
 exactly. There are three hard conditions, all errors:
 
 - **§9.1** every non-reserved file has a parseable YAML frontmatter block;
@@ -236,12 +372,51 @@ is the structured input an agent consumes to reason about those.
 
 ## Server trust boundary
 
-> [!WARNING]
-> The served page loads its JavaScript (Cytoscape, marked, mermaid, and layout
-> plugins) from a CDN and renders each concept's Markdown body **without
-> sanitization**, so only serve bundles you trust. Inlined graph data still
-> cannot break out of its `<script>` (`<` is escaped), but the fetched Markdown
-> is rendered unsanitized.
+> [!NOTE]
+> The graph page defends against a bundle that carries active content in two
+> places. It escapes any graph data inlined into the page (`<` becomes `&lt;`),
+> which keeps that data from breaking out of its `<script>`. And it fetches each
+> concept body on demand, then runs marked's HTML output through
+> [DOMPurify](https://github.com/cure53/DOMPurify) before it reaches the DOM, so
+> a script or event handler hidden in a Markdown body is stripped rather than
+> executed. Descriptions are escaped on the server.
+>
+> That covers the paths that could run code. The page still loads Cytoscape,
+> marked, and DOMPurify from a CDN and renders whatever links and diagrams a body
+> contains, so treat an unfamiliar bundle the way you would treat any document
+> from a source you do not know.
+
+The [server trust boundary](.okf/design/server-trust-boundary.md) concept has the
+full write-up: the two data paths, what sanitizing does, and what it leaves to
+your judgment.
+
+## Claude Code plugin
+
+This repository doubles as a Claude Code plugin marketplace, so the whole
+toolchain installs with two commands inside Claude Code:
+
+```
+/plugin marketplace add serradura/okf-gem
+/plugin install okf@okfgem
+```
+
+The plugin carries three pieces:
+
+| Piece         | What it does                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `okf` skill   | The [companion skill](#agent-skill) above, bundled with the plugin (a generated copy that `rake plugin:sync` keeps identical to `lib/okf/skill`).                                                                                                                                                                                                                                                                        |
+| `/okf:gem`    | The front door, routed by argument. No arguments: orients on the CLI, the bundle, and what `validate`/`lint` report, then recommends the highest-value next move (never auto-runs). `doctor`: installs and verifies the `okf` CLI, then doctors the repo's bundle. `curate`: the full curation cycle (`validate` + `lint` + `loose`). Anything else (`produce`, `maintain`, `consume`, a CLI verb): handed to the skill. |
+| Curation hook | After every Write or Edit inside a bundle, runs `okf validate` + `okf lint` and returns the findings as context. The checks are the CLI's own, so the feedback is deterministic.                                                                                                                                                                                                                                         |
+
+The hook stays silent outside bundles, and when the CLI is missing it suggests
+`/okf:gem` once per session instead of failing on each edit. It is config-free to
+switch off: set `OKF_CURATE_DISABLED=1` to turn it off, `OKF_CURATE_QUIET=1` to
+keep the findings but drop that suggestion, or drop an `<!-- okf-disable -->`
+comment into a file to skip curation for that one.
+
+Prefer no plugin? `gem install okf && okf skill .claude` installs the skill
+alone, and the skill itself instructs the agent to run the same checks after
+editing a bundle.
 
 ## Development
 
@@ -274,3 +449,9 @@ The gem is available as open source under the terms of the
 is authored by Google Cloud Platform and included under its own Apache-2.0
 license, Copyright (c) Google LLC. See `NOTICE` and
 `lib/okf/skill/reference/APACHE-2.0.txt`.
+
+[okf-skills](https://github.com/scaccogatto/okf-skills) by Marco Boffo, a Python
+OKF toolkit for Claude Code with a feature-rich interactive graph view, was an
+early inspiration for this gem's Claude Code plugin and for the knowledge-as-code
+comparison in [Why OKF](#why-okf). okf-gem takes a different shape: a Ruby-native
+gem built around the `okf` CLI and an embeddable library.

data/exe/okf

@@ -2,5 +2,7 @@
 # frozen_string_literal: true
 
 require "okf"
+require "okf/skill"
+require "okf/cli"
 
 exit OKF::CLI.start(ARGV)

data/lib/okf/cli.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "optparse"
+
 module OKF
   # Command-line front end: `okf graph|validate|lint|loose|index|catalog|files|tags|types|stats|server <dir>`.
   # This is the

data/lib/okf/server/templates/graph.html.erb

@@ -11,6 +11,7 @@
 <link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600;700&display=swap" rel="stylesheet">
 <script src="https://cdn.jsdelivr.net/npm/cytoscape@3.30.2/dist/cytoscape.min.js"></script>
 <script src="https://cdn.jsdelivr.net/npm/marked@14/marked.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/dompurify@3/dist/purify.min.js"></script>
 <style>
  :root{
   --bg:#ffffff; --panel:#ffffff; --panel-2:#f6f7f8; --canvas:#f4f5f7; --ink:#1f2328; --ink-soft:#333333;
@@ -466,7 +467,7 @@ function rethemeMermaid(){if(!window.mermaid)return;const nodes=[...document.que
  window.mermaid.initialize({startOnLoad:false,securityLevel:'strict',theme:isDark()?'dark':'default'});
  nodes.forEach(d=>{if(d.dataset.src){d.removeAttribute('data-processed');d.innerHTML='';d.textContent=d.dataset.src;}});
  window.mermaid.run({nodes}).catch(()=>{});}
-function renderMarkdown(el,text){el.innerHTML=text?marked.parse(text):'<span class="empty">empty body</span>';processMermaid(el);}
+function renderMarkdown(el,text){el.innerHTML=text?DOMPurify.sanitize(marked.parse(text)):'<span class="empty">empty body</span>';processMermaid(el);}
 
 /* ── inspector ── */
 const gbody=document.querySelector('.graph-body'), sideBody=document.getElementById('side-body');

data/lib/okf/skill/SKILL.md

@@ -88,7 +88,7 @@ flags. The division of labour is the whole game:
 
 The one trap worth carrying in your head: **freshness is off by default** — a plain
 `okf lint` never reports stale concepts; pass `--stale-after <90d|12w|ISO-date>`
-when the bundle carries timestamps.
+when the bundle carries timestamps. <!-- check:stale -->
 
 Read [cli.md](reference/cli.md) before *interpreting* a verb's output in depth:
 what `validate` may and may not reject, lint's categories and check ids, the JSON
@@ -101,17 +101,19 @@ index <dir>` (the §6 map: every directory's index body, rollups, and listings)
 read `log.md` (the §7 baseline of what changed last) **before** greping or opening
 leaves. It is the cheapest high-signal context, and the only reliable way to catch
 enumeration drift: **grep cannot find an index entry that is missing** — you can't
-search for the word that should be there but isn't. Per-verb steps are in
-[authoring.md](reference/authoring.md) (no `okf` installed? read the root
+search for the word that should be there but isn't. <!-- rule:okf-orient-index -->
+Per-verb steps are in the
+playbooks (the Commands table below; no `okf` installed? read the root
 `index.md` plus each area's `index.md`).
 
 ## The authoring verbs — the craft
 
 `produce` (create or extend a bundle), `maintain` (sync it with reality),
 `consume` (use it as context) carry the judgment the executable can't — this is
-where the skill earns its keep. Read [authoring.md](reference/authoring.md)
-before doing them, and the verbatim spec [SPEC.md](reference/SPEC.md) when you
-need chapter and verse.
+where the skill earns its keep. Each has a playbook (the Commands table below);
+read the modelling craft in [authoring.md](reference/authoring.md) before
+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
@@ -123,11 +125,35 @@ ask.
 root, but first detect whether the project already keeps its bundle elsewhere
 (e.g. `docs/`) and prefer that. Commit the bundle alongside the code it describes.
 
+## Commands
+
+The first word of the arguments picks a row. **No arguments at all** — someone
+asking "what should I do?" — is its own row: read `playbooks/menu.md`, orient on
+the signals, and recommend the highest-value move without running one. When there
+is wording but no matching first word, infer intent as in "No subcommand?" above.
+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) |
+| `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) |
+| `curate`   | Curate | structural upkeep as it stands: validate + lint + loose | [playbooks/curate.md](playbooks/curate.md) |
+| `doctor`   | Setup  | install and verify the CLI, then doctor the bundle | [playbooks/doctor.md](playbooks/doctor.md) |
+| `<okf-cli-verb>` | Read | validate, lint, loose, index, catalog, files, tags, types, stats, graph, server, skill | `okf <verb> --help` + [reference/cli.md](reference/cli.md) |
+
+Two boundaries worth keeping sharp: `curate` is structural upkeep only — when
+the *content* no longer matches reality, that is `maintain` — and `doctor` is
+the one playbook that does not assume the CLI is installed. In Claude Code with
+the okf plugin, `/okf:gem` routes these same verbs.
+
 ## The lifecycle is a flywheel, not phases
 
 produce seeds a bundle; consume reads it; **maintain** runs whenever reality drifts
 *or* whenever consuming teaches you something durable — that write-back reflex is
 what keeps a bundle alive instead of rotting into folklore. When you learn
-something while consuming, switch to maintain and record it. Full playbooks and the
-modelling craft (granularity, choosing `type`, tag vocabulary, topology,
-`resource`, links, citations) are in [reference/authoring.md](reference/authoring.md).
+something while consuming, switch to maintain and record it. The playbooks live
+one per verb in `playbooks/` (the Commands table above); the modelling craft
+(granularity, choosing `type`, tag vocabulary, topology, `resource`, links,
+citations) is in [reference/authoring.md](reference/authoring.md).

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

@@ -0,0 +1,12 @@
+# Playbook: consume — use a bundle as context
+
+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.
+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 —
+   switch to [maintain](maintain.md) and record it. That reflex is what keeps the
+   bundle alive.

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

@@ -0,0 +1,33 @@
+# Playbook: curate an OKF bundle
+
+Run the complete curation cycle over the whole bundle and act on the findings
+with the okf skill's judgment. If the `okf` CLI is missing, stop and follow
+[doctor.md](doctor.md) first (in Claude Code: `/okf:gem doctor`).
+
+Curation is structural upkeep of the bundle *as it stands*: conformance,
+reachability, backlog, completeness, hygiene. It is not `maintain`, the
+skill's workflow for when the project changed and the bundle's *content*
+must catch up with reality; reach for that one when what is written stopped
+being true. Curating can surface semantic staleness, and when it does,
+switch to `maintain` for those concepts.
+
+1. Locate the bundle: the directory you were given, if any; otherwise a
+   `.okf/` directory or a root `index.md` whose frontmatter carries
+   `okf_version`.
+2. Measure: `okf validate <root> --json`, `okf lint <root> --json`,
+   `okf loose <root> --json`.
+3. Interpret through the three lenses the okf skill teaches, and keep them
+   separate:
+   - conformance errors (§9) are the only hard failures; fix them first,
+     always;
+   - lint findings are curation debt across reachability, backlog,
+     completeness, freshness, provenance, and hygiene. They are advisory;
+     rank them by how much each hurts a reader navigating the graph;
+   - loose files can be legitimate terminal leaves, so judge each one before
+     linking it anywhere.
+4. Propose, then apply: list the fixes worth making (must-fix errors first,
+   then the debt worth settling, then the judgment calls), apply the ones the
+   user confirms, or all the obvious ones when the user asked you to just
+   clean up.
+5. Re-measure: run validate + lint again and report the before and after in
+   two lines.

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

@@ -0,0 +1,55 @@
+# Playbook: set up the okf CLI and doctor the bundle
+
+You are the installer and doctor for the Open Knowledge Format toolchain. Work
+through the steps in order and report what you find at each one. Ask before any
+install that touches the user's system; everything else, just do.
+
+## 1. Is the CLI already here?
+
+Run `okf --version`. If it prints a version, skip to step 3.
+
+## 2. Install the gem
+
+Find a Ruby first. The gem runs on any Ruby >= 2.4, so whatever the OS or a
+version manager already ships will do:
+
+- `ruby --version`; if absent, check the managers: `rbenv versions`,
+  `asdf list ruby`, `mise ls ruby`.
+- Repo has a Gemfile and okf belongs to the project? `bundle add okf`, then use
+  `bundle exec okf` everywhere below.
+- Otherwise: `gem install okf`.
+
+Troubleshooting, in order of likelihood:
+
+- `okf: command not found` right after a successful install: the gem bindir is
+  not on PATH. `ruby -e 'puts Gem.bindir'` shows where the executable landed;
+  add that to PATH, or refresh the manager's shims (`rbenv rehash`,
+  `asdf reshim ruby`).
+- Permission error on the system Ruby: do not reach for sudo. Use
+  `gem install --user-install okf` and add `$(ruby -e 'puts Gem.user_dir')/bin`
+  to PATH.
+- Windows: a RubyInstaller Ruby works. Run the install from the same shell that
+  has `ruby` on PATH, and note the executable is `okf.bat` under Gem.bindir.
+
+Verify with `okf --version` before moving on.
+
+## 3. Doctor the bundle
+
+1. Locate a bundle: the directory you were given, if any; otherwise a `.okf/`
+   directory, or a root `index.md` whose frontmatter carries `okf_version`.
+2. Found one? Run `okf validate <root>` and `okf lint <root>`, then summarize
+   in a few lines: conformant or not (and the errors if not), the warning
+   count, and the top curation findings by category.
+3. No bundle? Offer to bootstrap one. The okf skill knows how (its "produce"
+   workflow); do not scaffold anything without the user's yes.
+
+## 4. Say what changes now
+
+Close with a short orientation. In Claude Code with the okf plugin active:
+every Write or Edit that touches an OKF bundle runs `okf validate` and
+`okf lint` automatically, and the findings come back as context to act on.
+The checks are the CLI's own, so the feedback is deterministic. `/okf:gem
+curate` runs the same cycle over the whole bundle on demand, and `/okf:gem`
+with any other arguments (produce, maintain, consume, or a CLI verb) hands
+the task straight to the skill. Without the plugin, the skill itself
+instructs the agent to run the same checks after editing a bundle.

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

@@ -0,0 +1,67 @@
+# Playbook: maintain — keep a bundle in sync with reality
+
+Reach for this when the project changed and the bundle's *content* must catch
+up. The modelling craft behind steps 3 and 7 lives in
+[authoring.md](../reference/authoring.md).
+
+1. **Orient before hunting.** Run `okf index <dir>` (the §6 map — every directory's
+   index body, rollups, and listings), read `log.md` (the §7 baseline: what changed
+   last), and `okf stats <dir>` (size and shape) *before* you grep. It is the
+   cheapest context and it primes the hunt — and it is the only reliable way to
+   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.
+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.
+4. **Update every enumeration that names what you changed — including `index.md`
+   bodies**, not just the concept files: a new, renamed, or removed concept changes
+   its directory's index listing too. Append a dated `log.md` entry. Step 1's map
+   is how you verify this — re-run `okf index` and confirm each listing matches
+   reality.
+5. Run `validate`, then `lint` to catch the curation drift the change introduced —
+   new orphans, broken citations, dangling index entries. Add `--stale-after`
+   (e.g. `90d`) if concepts carry timestamps: freshness is off by default, so a
+   plain `lint` will not tell you what the change left stale.
+6. **Review loose files** <!-- check:unlinked --> — run `okf loose <dir>` (the
+   folder-grouped view of `lint`'s `unlinked` check): the concepts with **no
+   cross-links in or out**, which
+   float in the graph. This is a semantic pass the tool cannot do for you — for each
+   floater, judge intent:
+   - **should it link out?** the concept relates to others but says so nowhere —
+     write the sentence that explains the relationship and put the link in it;
+   - **should something link to it?** it is knowledge others should reach by
+     following links, not just via an index — add the inbound link from where it
+     belongs;
+   - **legitimately terminal?** a backlog item, a spec reference, a leaf reachable
+     by design only through its index — leave it. **Terminal-by-design is not a
+     defect.** Loose ≠ orphan: an index listing makes a file *reachable* (not an
+     orphan) but is not a graph edge, so an indexed file can still float here.
+7. **Curate the tag vocabulary** <!-- rule:okf-tag-vocabulary --> when the pass
+   touched tags, or when `okf tags <dir>` shows a long tail of singletons. Run `okf tags <dir> --by area` and
+   `--by type` — the grouped view is the analysis; read each group top-down:
+   - **twins** — two tags riding the exact same concepts (equal counts sort them
+     adjacent). Merge into one unless each genuinely names a different theme.
+   - **group-name echoes** — a tag matching its own group's name (a `format` tag
+     inside `format/`, an `overview` tag on an Overview). It restates an axis the
+     concept already carries; drop it from those concepts.
+   - **singletons** — for each, ask: would an existing tag serve? is it an
+     anticipated cluster that concepts landing soon will join? is it a deliberate
+     marker (`security`, `deprecated`)? Merge, keep, or drop accordingly — a
+     count of 1 is a question, never a verdict.
+   - **connective tags** — recurring across groups: these are the vocabulary's
+     spine. Protect them; prefer merging others *into* them over renaming them,
+     because consumers learn these keys and stability is part of their value.
+   The trap in this pass is optimizing the numbers instead of the vocabulary:
+   you can reach zero singletons by deleting every tag, and perfect cohesion by
+   tagging everything alike. The goal is a small set of tags where each one
+   either connects or marks — judged, not counted.
+
+Before calling the pass done, walk the
+[Closeout gate](../reference/authoring.md#closeout--the-finishing-gate) once:
+steps 4–7 above cover most of it, and the gate is the check that nothing was
+skipped.

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

@@ -0,0 +1,34 @@
+# Playbook: menu — "what should I do?" the no-argument front door
+
+Reached when `/okf:gem` (or the skill) runs with no verb and no task. Do not
+guess a workflow and do not run one on your own: **orient on the signals, then
+recommend the two or three highest-value moves and let the user pick.** The full
+Commands table in [SKILL.md](../SKILL.md) is the fallback menu; the recommendation
+is the lede.
+
+1. **CLI present?** `okf --version`. If it is missing, the only useful move is
+   setup: follow [doctor.md](doctor.md) (install and verify the CLI) and stop
+   here. Everything below needs the CLI.
+2. **Bundle present?** Locate one: the directory you were given, else a `.okf/`
+   directory or a root `index.md` whose frontmatter carries `okf_version`.
+   - **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:
+   - **`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.
+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.
+
+Keep it to two or three pointed picks, each with the exact `/okf:gem <verb>` to
+run and a one-line reason from the signals. Never auto-run a workflow from here.

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

@@ -0,0 +1,23 @@
+# Playbook: produce — create or extend a bundle
+
+The craft that makes these steps land well — granularity, choosing `type`, tag
+vocabulary, topology, links, citations — lives in
+[authoring.md](../reference/authoring.md). Read it before a non-trivial produce.
+
+1. Read [SPEC.md](../reference/SPEC.md) if you are unsure of any rule.
+2. Pick the source(s): **code** (derive concepts from source, READMEs, docstrings,
+   config), **docs/wiki** (distill pages into concepts; cite the originals under
+   `# Citations`), **manual** (decisions, playbooks, metrics that live only in
+   people's heads).
+3. Choose a domain-based directory layout. One concept per file.
+4. Write each concept from [templates/concept.md](../templates/concept.md): a
+   descriptive `type` from the bundle's vocabulary, recommended fields filled,
+   cross-links to related concepts written into prose.
+5. Add or refresh `index.md` per directory from
+   [templates/index.md](../templates/index.md); for the bundle root use
+   [templates/root-index.md](../templates/root-index.md) so it carries
+   `okf_version: "0.1"`. Append a dated entry to `log.md`.
+6. **Close out** — walk the
+   [Closeout gate](../reference/authoring.md#closeout--the-finishing-gate)
+   (`validate` + `lint` are part of it, see [cli.md](../reference/cli.md))
+   before finishing.

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

@@ -27,7 +27,7 @@ Consult the right section on demand instead of re-reading all of [SPEC.md](SPEC.
 These are the decisions that make or break a bundle. None are enforced by the
 tools — they are yours to get right.
 
-### One concept = one file — but what is a concept?
+### One concept = one file — but what is a concept? <!-- rule:okf-atomic-concept -->
 A concept is the smallest unit of knowledge someone would want to **link to or
 cite on its own**. If two things are always referenced together, they are one
 concept; if either is referenced alone, split them. Err atomic — it is cheap to
@@ -36,7 +36,7 @@ file should split: two `type`s fighting for the frontmatter, two audiences, or a
 heading that others would plausibly link to directly. The file path (minus `.md`)
 is the concept's stable ID, so name it for what it *is*, not where it sits today.
 
-### `type` is the graph's vocabulary
+### `type` is the graph's vocabulary <!-- rule:okf-type-vocabulary -->
 `type` is the only required field, and it is the dimension every consumer groups
 and colours by (the graph server colours nodes by it; graph analysis clusters by
 it). It is freeform — the spec does not enumerate types — and that freedom is a
@@ -46,7 +46,7 @@ types across files is what makes the graph legible; inventing a new type per fil
 makes `type` meaningless. Before adding a new type, check what the bundle already
 uses.
 
-### Tags are the connective axis — curate them like a vocabulary
+### Tags are the connective axis — curate them like a vocabulary <!-- rule:okf-tag-vocabulary -->
 `type` says what a concept *is*; the directory says where it *lives*; `tags` are
 the only axis that cuts across both. A tag earns its place one of two ways: by
 **connecting** concepts that type and area don't already group (a `billing` tag
@@ -57,14 +57,14 @@ a tag's clothes. Reuse before minting: run `okf tags <dir>` and pick from the
 existing vocabulary first; 2–4 tags per concept is plenty. Scattered singletons
 are how a vocabulary rots into one label per file.
 
-### Topology: organize by domain, not by type
+### Topology: organize by domain, not by type <!-- rule:okf-domain-topology -->
 Lay out directories by what the knowledge is *about* (`services/`, `datasets/`,
 `decisions/`), not by concept type. The directory tree is itself knowledge — it
 shows a reader how the system decomposes, and it usually mirrors the shape of the
 codebase or the org. A `types/`-first layout scatters related concepts and buries
 the domain.
 
-### `resource` is the bridge to reality
+### `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
@@ -72,7 +72,7 @@ grepping for that URI. Abstract concepts — a decision, a principle, a metric
 definition — have no resource, and **omitting it is meaningful**, not laziness. Do
 not invent placeholder URIs.
 
-### Links are untyped on purpose
+### Links are untyped on purpose <!-- rule:okf-untyped-links -->
 A markdown link asserts only "these two relate." The *kind* of relationship —
 depends-on, supersedes, derived-from, owns — lives in the **prose around the
 link**, never in a made-up typed-edge syntax. Write the sentence that explains the
@@ -81,14 +81,14 @@ relationship and put the link inside it. Prefer absolute bundle-relative targets
 does not exist yet is fine — it is not-yet-written knowledge (§5.3), and `lint`'s
 backlog will surface it as demand.
 
-### Provenance is what makes knowledge trustworthy (§8)
+### Provenance is what makes knowledge trustworthy (§8) <!-- check:uncited_external -->
 Any external or empirical claim — a latency number, an approval, a quota, a
 "because X team decided Y" — should carry a citation to its source under a
 `# Citations` heading. Uncited claims are exactly how a bundle decays into folklore
 nobody trusts. `lint`'s provenance category exists to catch missing and broken
 citations; write them as you go so you never have to reconstruct them.
 
-### Capture the non-obvious — not what code already says
+### Capture the non-obvious — not what code already says <!-- rule:okf-non-obvious -->
 A bundle that restates function signatures or config keys goes stale the moment
 the code changes and adds no knowledge. Capture what you **cannot** derive by
 reading one source file: the *why* behind a design, cross-cutting relationships,
@@ -96,14 +96,14 @@ decisions and their tradeoffs, operational tribal knowledge, the metric that
 actually matters. If the code or git history already records it faithfully, link
 to it rather than duplicating it.
 
-### Write for both readers at once
+### Write for both readers at once <!-- rule:okf-dual-audience -->
 Use structural markdown so an agent can extract deterministically and a human can
 skim: headings, tables, fenced code, lists. Conventional headings a reader expects
 are `# Schema` (field/column tables), `# Examples`, and `# Citations`. Fill
 recommended frontmatter — `title`, `description`, `tags`, `timestamp` (ISO 8601) —
 whenever it aids consumption.
 
-### Reserved files
+### Reserved files <!-- rule:okf-reserved-files -->
 `index.md` is a directory listing and carries **no frontmatter** — with one
 exception: the **bundle-root** `index.md` is the only index that may carry
 frontmatter, and it may carry *only* `okf_version: "0.1"` (§11; `validate` §9.3
@@ -114,90 +114,9 @@ bundle-root [root-index](../templates/root-index.md), [log](../templates/log.md)
 
 ## Playbooks
 
-### produce — create or extend a bundle
-1. Read [SPEC.md](SPEC.md) if you are unsure of any rule.
-2. Pick the source(s): **code** (derive concepts from source, READMEs, docstrings,
-   config), **docs/wiki** (distill pages into concepts; cite the originals under
-   `# Citations`), **manual** (decisions, playbooks, metrics that live only in
-   people's heads).
-3. Choose a domain-based directory layout. One concept per file.
-4. Write each concept from [templates/concept.md](../templates/concept.md): a
-   descriptive `type` from the bundle's vocabulary, recommended fields filled,
-   cross-links to related concepts written into prose.
-5. Add or refresh `index.md` per directory from
-   [templates/index.md](../templates/index.md); for the bundle root use
-   [templates/root-index.md](../templates/root-index.md) so it carries
-   `okf_version: "0.1"`. Append a dated entry to `log.md`.
-6. **Close out** — walk the Closeout gate below (`validate` + `lint` are part of it,
-   see [cli.md](cli.md)) before finishing.
-
-### maintain — keep a bundle in sync with reality
-1. **Orient before hunting.** Run `okf index <dir>` (the §6 map — every directory's
-   index body, rollups, and listings), read `log.md` (the §7 baseline: what changed
-   last), and `okf stats <dir>` (size and shape) *before* you grep. It is the
-   cheapest context and it primes the hunt — and it is the only reliable way to
-   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.
-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.
-4. **Update every enumeration that names what you changed — including `index.md`
-   bodies**, not just the concept files: a new, renamed, or removed concept changes
-   its directory's index listing too. Append a dated `log.md` entry. Step 1's map
-   is how you verify this — re-run `okf index` and confirm each listing matches
-   reality.
-5. Run `validate`, then `lint` to catch the curation drift the change introduced —
-   new orphans, broken citations, dangling index entries. Add `--stale-after`
-   (e.g. `90d`) if concepts carry timestamps: freshness is off by default, so a
-   plain `lint` will not tell you what the change left stale.
-6. **Review loose files** — run `okf loose <dir>` (the folder-grouped view of
-   `lint`'s `unlinked` check): the concepts with **no cross-links in or out**, which
-   float in the graph. This is a semantic pass the tool cannot do for you — for each
-   floater, judge intent:
-   - **should it link out?** the concept relates to others but says so nowhere —
-     write the sentence that explains the relationship and put the link in it;
-   - **should something link to it?** it is knowledge others should reach by
-     following links, not just via an index — add the inbound link from where it
-     belongs;
-   - **legitimately terminal?** a backlog item, a spec reference, a leaf reachable
-     by design only through its index — leave it. **Terminal-by-design is not a
-     defect.** Loose ≠ orphan: an index listing makes a file *reachable* (not an
-     orphan) but is not a graph edge, so an indexed file can still float here.
-7. **Curate the tag vocabulary** when the pass touched tags, or when `okf tags
-   <dir>` shows a long tail of singletons. Run `okf tags <dir> --by area` and
-   `--by type` — the grouped view is the analysis; read each group top-down:
-   - **twins** — two tags riding the exact same concepts (equal counts sort them
-     adjacent). Merge into one unless each genuinely names a different theme.
-   - **group-name echoes** — a tag matching its own group's name (a `format` tag
-     inside `format/`, an `overview` tag on an Overview). It restates an axis the
-     concept already carries; drop it from those concepts.
-   - **singletons** — for each, ask: would an existing tag serve? is it an
-     anticipated cluster that concepts landing soon will join? is it a deliberate
-     marker (`security`, `deprecated`)? Merge, keep, or drop accordingly — a
-     count of 1 is a question, never a verdict.
-   - **connective tags** — recurring across groups: these are the vocabulary's
-     spine. Protect them; prefer merging others *into* them over renaming them,
-     because consumers learn these keys and stability is part of their value.
-   The trap in this pass is optimizing the numbers instead of the vocabulary:
-   you can reach zero singletons by deleting every tag, and perfect cohesion by
-   tagging everything alike. The goal is a small set of tags where each one
-   either connects or marks — judged, not counted.
-
-### consume — use a bundle as context
-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.
-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 —
-   switch to `maintain` and record it. That reflex is what keeps the bundle alive.
+The step-by-step playbooks live in [../playbooks/](../playbooks/), one file per
+verb (produce, maintain, consume, curate, doctor), routed by the Commands table
+in [SKILL.md](../SKILL.md). The Closeout below is their shared finishing gate.
 
 ## Closeout — the finishing gate
 

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

@@ -105,7 +105,8 @@ But an index listing is **not a graph edge**: a file can be listed in an index y
 have no cross-links, so it floats in the graph while `lint` reports it as reachable.
 `loose`/`unlinked` catch exactly that gap. A loose file is not automatically a
 defect — a terminal leaf (a backlog item, a spec reference) can be loose by design;
-`loose` surfaces the set so you can judge intent (see `maintain` in authoring.md).
+`loose` surfaces the set so you can judge intent (see the
+[maintain playbook](../playbooks/maintain.md)).
 
 ## index — the progressive-disclosure map (§6)
 
@@ -148,8 +149,8 @@ in/out link degree). Add `--json` to any for a machine substrate.
   descending. The "what themes dominate" view. JSON: `{ bundle, count, tags: [{ tag,
   count, concepts: [id, …] }] }`. `--by type|area` regroups the list per concept
   dimension with **within-group** counts (a tag spanning groups appears in each) —
-  the substrate for tag curation; the judgment recipe lives in
-  [authoring.md](authoring.md)'s maintain playbook. JSON: `{ bundle, count, by,
+  the substrate for tag curation; the judgment recipe lives in the
+  [maintain playbook](../playbooks/maintain.md). JSON: `{ bundle, count, by,
   groups: [{ <dim>, count, tags: […] }] }`.
 - **`types`** — every type with the concepts that carry it, ordered by count
   descending. The "what kinds of knowledge" view. JSON: `{ bundle, count, types:

data/lib/okf/version.rb

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

data/lib/okf.rb

@@ -4,7 +4,6 @@ require "erb"
 require "fileutils"
 require "date"
 require "json"
-require "optparse"
 require "pathname"
 require "securerandom"
 require "set"
@@ -50,6 +49,4 @@ module OKF
   require "okf/bundle/reader"
   require "okf/bundle/writer"
   require "okf/bundle/folder"
-  require "okf/skill"
-  require "okf/cli"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -38,11 +38,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.4'
 description: |
-  OKF is portable knowledge — Markdown files with YAML frontmatter that both
-  humans and agents read. This gem reads OKF bundles, checks them for v0.1 (§9)
-  conformance, and serves them as an interactive graph (a mountable Rack app).
-  It ships a library API (OKF::Bundle and friends) plus an `okf` command-line
-  tool (validate / lint / loose / server / graph / skill).
+  OKF (Open Knowledge Format) is portable knowledge: Markdown files with YAML
+  frontmatter that both humans and agents read from one source. This gem is the
+  Ruby-native way to work with it. Its companion agent skill authors and curates
+  a bundle; the `okf` command-line tool validates the result for v0.1 (§9)
+  conformance, lints its curation quality, and serves it as an interactive graph
+  (a mountable Rack app). The same validate, lint, and graph run in-process
+  through a library API (OKF::Bundle and friends).
 email:
 - rodrigo.serradura@gmail.com
 executables:
@@ -104,6 +106,12 @@ files:
 - lib/okf/server/templates/graph.html.erb
 - lib/okf/skill.rb
 - lib/okf/skill/SKILL.md
+- lib/okf/skill/playbooks/consume.md
+- lib/okf/skill/playbooks/curate.md
+- lib/okf/skill/playbooks/doctor.md
+- lib/okf/skill/playbooks/maintain.md
+- lib/okf/skill/playbooks/menu.md
+- lib/okf/skill/playbooks/produce.md
 - lib/okf/skill/reference/APACHE-2.0.txt
 - lib/okf/skill/reference/SPEC.md
 - lib/okf/skill/reference/authoring.md
@@ -138,5 +146,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: Read, validate, and serve Open Knowledge Format (OKF) v0.1 bundles.
+summary: 'A lightweight Ruby gem for OKF: author, curate, and serve bundles as an
+  interactive graph.'
 test_files: []