okf 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 464529d862280b3385f00fa36a309c81fa03f71db2d2534f11707a04fdca4679
-  data.tar.gz: 1487c71ef1e70340d0a6212b85f0202ae287c0a1df7b59489f643bdbf63dd05f
+  metadata.gz: 95f1db166e67b4a3c4b4fbd679bce25ef19e3de3f50f010e13e6b1630ddacfcf
+  data.tar.gz: cef59494dbd959585ba85f631b025eb5ba88ab94e38c6d440ac8aed1b2fbd61a
 SHA512:
-  metadata.gz: 6240c78b9b1c23b64c97f980db2aabe5d3126eb0c69e4eb853381bed2e5e1be991a4835c62a806cfb5e219fdb4b3bf4bf3ef8960063d6f30d5fcf2aaf630d8d2
-  data.tar.gz: 32d943f353984a9d6e7224c881169bf851008976adee4ef6e785878372f225162f4359021b2ab576cf0615dde0b23054b61826ee39b8937356e1759d0dbca0c4
+  metadata.gz: ff17b4c61c5e9fb63e63235fb19fb51b75ce7626acafdfaa88a367f5a6c40a2e9c2eabe7af0283fac5cf6edfd1349b22aa900fa23c321522bd29b19e76befd95
+  data.tar.gz: 8846d3604a36b3818024f21d88d04cc62bc91d374dac1a7fd34e17d6eb8269fcf72f7675191a1b3243144359d847c734cf049d4025cf962fb5bf7369f7cc8fac

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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

data/README.md

@@ -16,26 +16,26 @@
   <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:
 
-```mermaid
-flowchart LR
-  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?"]
-    server["server — explore"]
-  end
-  model --> cli
-  model --> library["library API<br/>embed in Ruby"]
-```
+<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
@@ -68,6 +68,9 @@ It is deliberately light so it runs on the Ruby your OS already ships:
 - 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
@@ -80,6 +83,22 @@ 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
@@ -119,6 +138,14 @@ That bundle is this gem's own documentation. Clone the repo and run
 
 ## 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
@@ -138,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
 ```
@@ -212,6 +240,21 @@ and template files that teach a coding agent to author, maintain, and consume OK
 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
@@ -347,6 +390,34 @@ The [server trust boundary](.okf/design/server-trust-boundary.md) concept has th
 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
 
 ```bash
@@ -378,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/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.1.0"
+  VERSION = "1.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -106,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