okf 2.0.0 → 2.1.1

data/.okf/testing/the-harness.md

@@ -0,0 +1,45 @@
+---
+type: Component
+title: The test harness
+description: One base class for the whole suite — plain Minitest plus `test "..."` and block setup/teardown — and it runs on 2.4, so the gem's API floor binds the tests exactly as it binds `lib/`.
+resource: gems/okf/test/test_helper.rb
+tags: [testing, minitest, ruby-floor]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+---
+
+# One base class
+
+Every test in this gem subclasses `OKF::TestCase`, defined in
+`test/test_helper.rb`. It is plain Minitest with two pieces of sugar:
+
+* `test "a sentence" do … end` instead of `def test_a_sentence`, so a failure
+  names the behaviour in prose rather than in snake case;
+* block `setup` / `teardown`, which compose rather than requiring `super`.
+
+Nothing else is the base class. A test that reaches for `Minitest::Test`
+directly loses both and reads unlike its neighbours, which is the whole reason
+the sugar exists — the three siblings each ported the same class for the same
+reason, so the suites read alike across the monorepo.
+
+# It runs on 2.4, so the floor binds it
+
+The suite runs on every supported Ruby, 2.4 included. That makes the
+[Ruby floor](../design/ruby-floor.md)'s forbidden-API list a rule about `test/`
+as much as about `lib/` — a `filter_map` in a test fails the floor container
+exactly as one in a source file does, and RuboCop will not catch either.
+
+SimpleCov is the one exception, and it is conditional rather than absent: it
+needs 2.5+, so `test_helper.rb` loads it inside a `begin`/`rescue` and the suite
+simply runs without coverage where it cannot load. Coverage is a reporting
+convenience; the floor is a contract, and the contract wins.
+
+# What a test may assume about the disk
+
+Fixtures are real directories under `test/fixtures/`, not mocks. A branch that
+no fixture can reach is a branch nobody has ever proven, so the answer to an
+unreachable path is a new fixture rather than a bent assertion — the general
+form of that obligation is `@okf-eco design/how-a-change-is-proven`, and how the
+critical layer is organised is
+[integration first](../design/integration-first.md).

data/CHANGELOG.md

@@ -5,6 +5,71 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.1] - 2026-08-20
+
+### Fixed
+
+- **The package metadata follows the `gems/` move and the repository rename.**
+  Two URLs on the package page were about to be wrong at once. `changelog_uri`
+  named `blob/main/okf/CHANGELOG.md`, a path that stopped existing when the
+  four gems moved under `gems/`; `homepage` named `serradura/okf-gem`, and the
+  repository is now **`serradura/okf`** — the name the command has had all
+  along. rubygems.org serves whatever the last release published, so neither
+  corrects itself: only a release republishes metadata, and this is that
+  release. Both land in one round rather than two, which is the whole reason
+  the rename waited for the paths to stop moving.
+
+  `homepage_uri`, `source_code_uri` and `changelog_uri` are all derived from
+  `homepage`, so one line moves four pieces of this gem's metadata. GitHub
+  redirects the old URLs permanently, so anything already published keeps
+  resolving.
+
+### Added
+
+- **The gem ships a file-level map of itself, at `.okf/`.** `structure/` names
+  every one of the fifty files under `lib/`, grouped by the layer that owns it,
+  and `testing/adding-a-verb.md` is the ordered walk a new command owes. It is
+  the gem's own documentation rather than a sample, so an installed okf now
+  carries a real bundle for a reader to open with the tool they just installed:
+  `okf server "$(gem contents okf --show-install-dir)/.okf"`.
+
+  It deliberately copies nothing from the repository's own bundle, which still
+  holds okf's format, model, capabilities and design constraints — a second copy
+  of a catalogue is worse than none.
+
+  `test/unit/bundle_catalog_test.rb` pins both halves: a file under `lib/` named
+  by no concept, a concept naming a file that is gone, or the repository
+  bundle's `cli.md` group table disagreeing with `OKF::CLI.builtins` all fail
+  the suite. That group table was code-derived and unchecked until now.
+  `test/unit/packaging_test.rb` pins that the bundle actually ships.
+
+## [2.1.0] - 2026-08-17
+
+### Changed
+
+- **The skill's CLI reference is an index and seven leaves.** `reference/cli.md`
+  answered every question about every verb in one 46,234-byte file, so an agent
+  asking about `search` paid for `serve`, `registry` and the graph too. The
+  shared contract — refs, exit codes, `--json`, the filters — stays in `cli.md`
+  and routes to one file per surface under `reference/cli/`. Measured on the
+  worst question rather than the mean: 9,084 bytes for a routing question,
+  19,533 for the heaviest leaf. `reference/spec-map.md` is the other half, a
+  pointer from a spec clause to the file that answers it, so the vendored
+  `SPEC.md` keeps its index beside it instead of cut into it.
+- **Cross-file citations in the skill name a `rule:` marker**, not a section
+  anchor: the key travels with the paragraph the next time anything moves.
+- **`okf help` prints one row per extension**, plus a pointer to
+  `okf <verb> --help` for the rest. An addon with an umbrella verb and several
+  subcommands used to dwarf the built-ins the map exists to teach.
+
+### Added
+
+- **The skill teaches what a log records.** `log.md` carries durable knowledge
+  and shipped behavior, never the process that produced them —
+  `rule:okf-log-durable-only` in `reference/authoring.md`, cited by the maintain
+  playbook and the Closeout gate. It was the okf-gem repository's own contract
+  before this, which an agent maintaining any other bundle never reads.
+
 ## [2.0.0] - 2026-08-14
 
 > Major, not minor. The Breaking entries below change public shapes a shipped
@@ -1410,7 +1475,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Claude Code plugin. The repository now doubles as a plugin marketplace:
-  `/plugin marketplace add serradura/okf-gem`, then `/plugin install okf@okfgem`.
+  `/plugin marketplace add serradura/okf`, 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,
@@ -1516,18 +1581,20 @@ Initial release.
 
 - Runs on Ruby >= 2.4 with two runtime dependencies: rack and webrick.
 
-[2.0.0]: https://github.com/serradura/okf-gem/compare/v1.13.0...v2.0.0
-[1.13.0]: https://github.com/serradura/okf-gem/compare/v1.12.0...v1.13.0
-[1.12.0]: https://github.com/serradura/okf-gem/compare/v1.11.0...v1.12.0
-[1.11.0]: https://github.com/serradura/okf-gem/compare/v1.10.0...v1.11.0
-[1.10.0]: https://github.com/serradura/okf-gem/compare/v1.9.0...v1.10.0
-[1.9.0]: https://github.com/serradura/okf-gem/compare/v1.8.0...v1.9.0
-[1.8.0]: https://github.com/serradura/okf-gem/compare/v1.7.0...v1.8.0
-[1.7.0]: https://github.com/serradura/okf-gem/compare/v1.6.0...v1.7.0
-[1.6.0]: https://github.com/serradura/okf-gem/compare/v1.5.0...v1.6.0
-[1.5.0]: https://github.com/serradura/okf-gem/compare/v1.4.0...v1.5.0
-[1.4.0]: https://github.com/serradura/okf-gem/compare/v1.3.0...v1.4.0
-[1.3.0]: https://github.com/serradura/okf-gem/compare/v1.2.0...v1.3.0
-[1.2.0]: https://github.com/serradura/okf-gem/compare/v1.1.0...v1.2.0
-[1.1.0]: https://github.com/serradura/okf-gem/compare/v1.0.0...v1.1.0
-[1.0.0]: https://github.com/serradura/okf-gem/releases/tag/v1.0.0
+[2.1.1]: https://github.com/serradura/okf/compare/v2.1.0...v2.1.1
+[2.1.0]: https://github.com/serradura/okf/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/serradura/okf/compare/v1.13.0...v2.0.0
+[1.13.0]: https://github.com/serradura/okf/compare/v1.12.0...v1.13.0
+[1.12.0]: https://github.com/serradura/okf/compare/v1.11.0...v1.12.0
+[1.11.0]: https://github.com/serradura/okf/compare/v1.10.0...v1.11.0
+[1.10.0]: https://github.com/serradura/okf/compare/v1.9.0...v1.10.0
+[1.9.0]: https://github.com/serradura/okf/compare/v1.8.0...v1.9.0
+[1.8.0]: https://github.com/serradura/okf/compare/v1.7.0...v1.8.0
+[1.7.0]: https://github.com/serradura/okf/compare/v1.6.0...v1.7.0
+[1.6.0]: https://github.com/serradura/okf/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/serradura/okf/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/serradura/okf/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/serradura/okf/compare/v1.2.0...v1.3.0
+[1.2.0]: https://github.com/serradura/okf/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/serradura/okf/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/serradura/okf/releases/tag/v1.0.0

data/README.md

@@ -5,7 +5,7 @@ ranked search, and a live knowledge graph. 100% local.**
 
 [Site](https://okfgem.com) · [Docs](https://okfgem.com/docs/) ·
 [Live demo](https://demo.okfgem.com) ·
-[Project README](https://github.com/serradura/okf-gem#readme)
+[Project README](https://github.com/serradura/okf#readme)
 
 OKF (Open Knowledge Format) is portable project knowledge: Markdown files with
 YAML frontmatter that both humans and agents read from one source. This gem is
@@ -22,20 +22,41 @@ on every Ruby since **2.4** — the one your OS already ships.
 
 ## Install
 
+> **In Claude Code**, the plugin is the fastest path: two commands install the whole
+> toolchain (skill, `/okf:gem`, and the curation hook). See the
+> [project README](https://github.com/serradura/okf#claude-code-plugin).
+> Everywhere else, install the gem:
+
 ```bash
 gem install okf
 # or, in a project
 bundle add okf
 ```
 
-No Ruby? The official image carries the CLI:
+Tested and supported on every Ruby from **2.4 through 4.0**. From a checkout,
+`bundle exec rake install` builds and installs it locally.
+
+## No Ruby? Use Docker
+
+The official image bundles the CLI, so every `okf` command runs against a bundle
+you mount at `/data`:
 
 ```bash
 docker run --rm -v "$PWD:/data" ghcr.io/serradura/okf validate .
+docker run --rm -v "$PWD:/data" -p 8808:8808 ghcr.io/serradura/okf server . --bind 0.0.0.0
 ```
 
-The Docker-backed [`okf` command](https://docker.okfgem.com) drops the prefix so
-every verb reads exactly like the native CLI.
+Tired of the long line? The Docker-backed [`okf` command](https://docker.okfgem.com)
+drops the prefix so every verb reads exactly like the native CLI:
+
+```bash
+curl -fsSL https://docker.okfgem.com/install.sh | sh   # PowerShell: irm https://docker.okfgem.com/install.ps1 | iex
+okf validate .
+okf server .
+```
+
+Images are published for `linux/amd64` and `linux/arm64` on
+[ghcr.io](https://github.com/serradura/okf/pkgs/container/okf).
 
 ## Four steps to your first bundle
 
@@ -55,6 +76,41 @@ okf server <folder>     # 4. explore what you got, as a live graph
 
 Then `/okf maintain` keeps it in sync as the code changes.
 
+What the gem does, and which verb does it. This table is the map; **[the
+docs](https://okfgem.com/docs/)** are the manual.
+
+| Capability                                                    | What it answers                   | Verb                       |
+| ------------------------------------------------------------- | --------------------------------- | -------------------------- |
+| [Companion agent skill](https://okfgem.com/docs/skill/)     | Can an agent author it?           | `skill`                    |
+| [Conformance validator](https://okfgem.com/docs/cli/validate/)       | Is this a legal OKF bundle?      | `validate`                 |
+| [Curation linter](https://okfgem.com/docs/cli/lint/)                | Is it navigable, complete, fresh? | `lint` / `loose`           |
+| [Ranked text search](https://okfgem.com/docs/cli/search/)             | Which concept covers X?           | `search`                   |
+| [Read views](https://okfgem.com/docs/cli/)                 | What is in here, and where?       | `index` / `dirs` / `catalog` |
+| [Interactive graph server](https://okfgem.com/docs/cli/server/) | Can I explore it visually?        | `server`                   |
+| [Static render](https://okfgem.com/docs/cli/render/)                  | Can I ship a serverless snapshot? | `render`                   |
+| [Library API](https://okfgem.com/docs/library/)               | Can my Ruby program use it?       | in-process                 |
+
+And because knowledge rarely lives in one bundle, a registry gives each one a
+name — see [one registry, many bundles](#one-registry-many-bundles) below.
+
+## The graph
+
+One page, from a phone to a desktop: the navigation rail becomes a drawer, the
+toolbar folds into a `⚙` sheet, and a tap opens a preview card at the bottom edge
+rather than a panel over the whole viewport, so the graph stays live while you
+read. Drag the card up for the neighbourhood, tap a link and it walks there in
+place.
+
+It is keyboard-first: **`⌘/Ctrl-K`** opens a command palette that searches
+concepts, jumps to a view, and — behind a [hub](#one-registry-many-bundles) —
+switches bundles. **`/`** jumps to the current view's search, **`?`** answers with
+every shortcut. Cluster mode boxes the graph by directory and nests as deep as
+your tree does.
+
+To skip the server entirely, **`okf render <dir>`** writes that same page as one
+self-contained HTML file, the whole bundle baked in, so you can publish the graph
+on GitHub Pages or any static host.
+
 ## The command line
 
 Written to be read by an **agent first and a person second** — that is what the
@@ -83,16 +139,130 @@ Exit codes: `0` success, `1` non-conformant bundle (or a `lint --fail-on`
 threshold crossed), `2` usage error. Every flag is in `okf <verb> --help` and in
 [the docs](https://okfgem.com/docs/).
 
-**A registry names your bundles.** `okf registry set ./docs --as handbook` once,
-then `@handbook` works anywhere a `<dir>` does, from any directory; `okf search
-@all rate limit` spans every one of them, and a bare `okf server` hosts them all
-behind one hub. `okf registry init` scopes one to a single project instead, and a
-committed `.okf-registry.json` travels with the repo.
+```bash
+$ okf validate docs
+OKF v0.2 conformance — docs
+  concepts: 37   index.md: 10   log.md: 1
+  ! warn  features/link-suggestions.md: cross-link target not found: `/graph-view.md` (tolerated under §6.1)
+  …
+  ✓ conformant (33 warning(s))
+
+$ okf server docs
+serving 37 concepts at http://127.0.0.1:8808 (Ctrl-C to stop)
+
+$ okf render docs > public/index.html   # the same page, static — host it anywhere
+```
 
-**A big bundle is read a level at a time.** `okf index --depth 1 --except
-body,listing` is the map an agent orients on — on a 414-concept bundle, 2.8 KB
-against the full 313 KB — and `--dir` then opens one branch, bringing the
-ancestors that say what it is.
+## One registry, many bundles
+
+The registry is a per-user, ordered list of bundles in one plain JSON file (`$OKF_HOME/registry.json`, default `~/.okf`) — hand-editable,
+greppable, no database. It stores references, never content: the bundles stay in
+the repos that own them.
+
+```bash
+okf registry set ./docs --as handbook   # give the bundle a name
+okf lint @handbook                      # @slug works wherever a <dir> does, from anywhere
+okf search @all rate limit              # ranked retrieval across every registered bundle
+okf server                              # no args: the whole registry behind one hub
+```
+
+Related bundles can share a name: `okf registry group backend @handbook @runbooks`
+makes `@backend` stand for the set (members can be groups too, so they nest), and
+`okf search @backend rate limit` or `okf server @backend` then targets all of them
+at once — a durable subset for the two verbs that take several bundles.
+
+The registry lives under `$OKF_HOME` (default `~/.okf`) — one per user. For one
+scoped to a single project instead, `okf registry init` drops a
+`.okf-registry.json` in the current directory; okf then discovers it by walking up
+from wherever you run, and every registry op — and every `@slug` — resolves through
+it in place of the global one. So a bare `okf server` inside that repo serves *its*
+bundles with no `$OKF_HOME` setup. The nearest registry wins, and
+`OKF_NO_DISCOVERY=1` forces the global one.
+
+Commit that file and it travels with the repo: a bundle under the project root is
+stored relative to the registry, so a checkout on another machine — or a container
+that mounts the repo — resolves the same bundles unchanged. (Bundles outside the
+tree keep absolute paths, which do not travel.)
+
+Behind the hub each bundle mounts at `/b/<slug>/`, `/b/` lists them all, and the
+`⌘/Ctrl-K` palette both switches bundles and **searches every one at once** — type
+a few words and the matching concepts appear with their bundle and a snippet, from
+wherever you are.
+
+The ⚙ rail opens **Bundles**, the registry on the graph page itself: make
+default, rename, remove, where you are already reading. Those controls are the one
+thing that does not follow you onto a network — bind anywhere but loopback and
+they are refused outright, since `--bind 0.0.0.0` is how a personal tool becomes a
+public one.
+
+## Reading a big bundle a level at a time
+
+A few hundred concepts is a map nobody reads whole, so `index` and `dirs` descend
+instead of dumping. `--dir` takes a directory **and everything under it**,
+`--depth N` bounds how far below that it goes, and the two compose the way you
+actually walk a tree:
+
+```bash
+okf dirs  @handbook                       # the shape: every dir, what it holds directly and below
+okf index @handbook --depth 1 --no-body   # the top of the map, no prose
+okf index @handbook --dir platform/api    # now open one branch — with the chain that places it
+```
+
+Naming a `--dir` brings its ancestors along, marked `↑`, so a branch is never
+shown adrift of the context that says what it is — the root `index.md`'s prose
+first among it.
+
+For an agent the saving is the whole point. On a 400-concept bundle the full
+`okf index --json` is 313 KB; the skeleton it orients on is 2.8 KB:
+
+```bash
+okf index @handbook --json --depth 1 --except body,listing
+```
+
+## The agent skill
+
+The gem carries the [companion OKF agent skill](https://okfgem.com/docs/skill/):
+a `SKILL.md` plus reference and template files that teach a coding agent to
+author, maintain, and consume OKF bundles and to drive
+[the command line](#the-command-line).
+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.
+
+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                                              |
+| `search`         | Answer a question from the bundle, token-lean: the map, the finder, only the winning bodies                 |
+| `produce`        | Create or extend a bundle from code, docs, or knowledge in people's heads                                   |
+| `migrate`        | Adopt existing Markdown docs in place: frontmatter and reserved files added, bodies kept verbatim           |
+| `maintain`       | Sync the bundle's content with reality after the code or docs change                                        |
+| `refine`         | Restructure it for retrieval: evidence-first, cohesion over balance — proposes, never applies               |
+| `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`, `search`, `index`, `server`, the read views) and interpret its output |
+
+Three of those look alike and are not, which is the distinction worth learning
+first: **`curate`** keeps the bundle *sound* (the structure as it stands),
+**`maintain`** keeps it *true* (the code changed, so the content must catch up),
+and **`refine`** changes *where knowledge lives* — the folder a concept sits in,
+a fact re-explained in three overviews. Reach for `refine` when nothing is wrong
+and everything is hard to find. It reads the evidence, then hands you a proposal
+— it never rearranges your bundle on its own.
+
+Point it at your agent's config directory and the tree settles in its own
+`skills/okf/` folder, so a shared skills directory never gets the files loose:
+
+```bash
+okf skill .claude     # Claude Code      -> .claude/skills/okf
+okf skill .agents     # agent-agnostic   -> .agents/skills/okf
+```
+
+The resolved directory must be empty unless you pass `--force`, so a customized
+skill is never clobbered.
 
 ## The library
 
@@ -158,9 +328,12 @@ without ever failing it.
 Publish a gem named `okf-*` carrying an `okf/plugin.rb` and installing it is the
 whole installation: your verb answers to `okf` and behaves like a built-in.
 Nothing an addon registers can displace one, and a broken addon is skipped rather
-than taking the CLI down. [`okf-mcp`](https://rubygems.org/gems/okf-mcp) is the
-first one — install it and `okf mcp` serves your bundles over the Model Context
-Protocol, with nothing in this gem naming it.
+than taking the CLI down. Three ship alongside this one, with nothing in this
+gem naming any of them: [`okf-mcp`](https://rubygems.org/gems/okf-mcp) serves
+your bundles over the Model Context Protocol,
+[`okf-tui`](https://rubygems.org/gems/okf-tui) browses them full-screen in a
+terminal, and [`okf-pro`](https://rubygems.org/gems/okf-pro) writes an
+agent's knowledge repository and enforces it at three doors.
 
 The graph page treats a bundle as untrusted content: inlined data is escaped and
 every concept body is sanitized before it reaches the DOM, so a script hidden in
@@ -170,11 +343,22 @@ do not know.
 
 ## More
 
-The [project README](https://github.com/serradura/okf-gem#readme) carries the
-diagrams, the comparison with `CLAUDE.md`, agent auto-memory and wikis, and the
-Claude Code plugin. The [docs](https://okfgem.com/docs/) are the manual. And the
-repo documents *itself* in OKF — clone it and run `okf server .okf` to read this
-gem's own knowledge as a graph.
+The [project README](https://github.com/serradura/okf#readme) carries the
+diagrams, the comparison with `CLAUDE.md`, agent auto-memory and wikis, the
+Claude Code plugin, and the way to install the skill into any agent without this
+gem (`npx skills add serradura/okf`). The [docs](https://okfgem.com/docs/) are the manual.
+
+And the gem documents *itself* in OKF. `.okf/` ships inside it — a map of what
+every file under `lib/` does, and the walk a new verb owes — so from an
+installed copy:
+
+```bash
+okf server "$(gem contents okf --show-install-dir)/.okf"
+```
+
+reads this gem's own knowledge as a graph, in this gem. That is the shortest
+honest demonstration there is: the format is good enough that the tool's
+maintainers use it on the tool.
 
 ## License
 

data/lib/okf/cli.rb

@@ -92,7 +92,7 @@ module OKF
       [ :judge, nil ],
       [ :read, nil ],
       [ :graph, nil ],
-      [ :extension, "  installed extensions:" ]
+      [ :extension, "  installed extensions (`okf <verb> --help` for each):" ]
     ].freeze
 
     # Everything the map's grammar column cannot say for itself. A test finds the
@@ -476,13 +476,31 @@ module OKF
     end
 
     def print_group(io, group, heading)
-      rows = self.class.commands.reject(&:hidden?).select { |command| command.group == group }.flat_map(&:help_rows)
+      commands = self.class.commands.reject(&:hidden?).select { |command| command.group == group }
+      rows = group == :extension ? extension_rows(commands) : commands.flat_map(&:help_rows)
       return if rows.empty?
 
       io.puts heading if heading
       rows.each { |left, desc| io.puts "  #{left.to_s.ljust(56)}#{desc}" }
       io.puts
     end
+
+    # One line per extension, whatever it declares — its FIRST row, which is why
+    # an addon's first row should be its summary.
+    #
+    # Enforced here rather than asked of each addon, because a rule an addon has
+    # to remember is a rule this map cannot rely on. An umbrella verb is a shape
+    # an addon legitimately has — the built-in `registry` has it too — and one
+    # arriving with eight subcommands made this block the longest section on the
+    # page, dwarfing the built-ins above it and burying the single-line addons
+    # beside it.
+    #
+    # A built-in keeps every row: those are this gem's own surface, they are what
+    # the map exists to teach, and there is no second place to read them. An
+    # extension has one — `okf <verb> --help`, which the heading points at.
+    def extension_rows(commands)
+      commands.map { |command| command.help_rows.first }.compact
+    end
   end
 end
 

data/lib/okf/skill/SKILL.md

@@ -96,11 +96,18 @@ The one trap worth carrying in your head: **the age cutoff is off by default**
 a plain `okf lint` reports concepts past their own declared `stale_after` (the
 `expired` check reads the clock the CLI supplies), but never judges *age*; pass
 `--stale-after <90d|12w|ISO-date>` when you want anything not touched since then
-flagged too. <!-- 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
-shapes, the tag-curation views, the server's trust boundary.
+flagged too — the two mechanisms share a spelling and nothing else
+([cli/checks.md](reference/cli/checks.md), rule `okf-two-clocks`).
+<!-- check:stale -->
+
+Read [cli.md](reference/cli.md) before *interpreting* a verb's output in depth.
+It is the index and the shared contract — refs, exit codes, `--json`, the
+filters — and its table routes to the one file the verb lives in:
+[checks](reference/cli/checks.md) (what `validate` may and may not reject, lint's
+categories and check ids), [search](reference/cli/search.md),
+[map](reference/cli/map.md) (`index`/`dirs`), [views](reference/cli/views.md)
+(the tag-curation views), [serve](reference/cli/serve.md) (the trust boundary),
+[registry](reference/cli/registry.md), [graph](reference/cli/graph.md).
 
 ## Orient before you touch anything
 
@@ -123,8 +130,9 @@ playbooks (the Commands table below; no `okf` installed? read the root
 `consume` (use it as context) carry the judgment the executable can't — this is
 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.
+producing or maintaining. When you need chapter and verse, go through
+[spec-map.md](reference/spec-map.md) — which § settles which question — into the
+verbatim [SPEC.md](reference/SPEC.md).
 
 **No subcommand?** Infer intent: "document this / capture X" → `produce`;
 "convert / migrate / OKFy these existing docs into a bundle" → `migrate`; "the

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

@@ -25,7 +25,9 @@ lives in [authoring.md](../reference/authoring.md).
    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
+   its directory's index listing too. Append a dated `log.md` entry — what changed and why it
+   matters, never the rounds it took (rule `okf-log-durable-only` in
+   [authoring.md](../reference/authoring.md)). 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 —

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

@@ -4,7 +4,8 @@ The craft that makes these steps land well — granularity, choosing `type`, tag
 vocabulary, topology, links, sources — 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.
+1. Unsure of a rule? [spec-map.md](../reference/spec-map.md) names the § that
+   settles it; read that section of [SPEC.md](../reference/SPEC.md).
 2. Pick the source(s): **code** (derive concepts from source, READMEs, docstrings,
    config), **docs/wiki** (distill pages into concepts; record the originals in
    `sources:` and key claims with `[^id]` footnotes), **manual** (decisions,
@@ -27,5 +28,6 @@ vocabulary, topology, links, sources — lives in
    `okf_version: "0.2"`. 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))
+   (`validate` + `lint` are part of it, see
+   [cli/checks.md](../reference/cli/checks.md))
    before finishing.

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

@@ -1,33 +1,13 @@
 # Authoring OKF well — the craft
 
-The spec ([SPEC.md](SPEC.md)) tells you what is *legal*. This file is what is
-*good* — the modelling judgment that turns a pile of conformant files into
+The spec ([SPEC.md](SPEC.md)) tells you what is *legal*, and
+[spec-map.md](spec-map.md) says which § settles which question. This file is
+what is *good* — the modelling judgment that turns a pile of conformant files into
 knowledge worth consuming. Read it before `produce` or `maintain`, and keep the
 §11 conformance rules in mind (parseable frontmatter, a non-empty `type`, and
 well-formed reserved files — the hard rules in [SKILL.md](../SKILL.md));
 everything else is guidance a consumer must tolerate.
 
-## What each SPEC section governs
-
-Consult the right section on demand instead of re-reading all of [SPEC.md](SPEC.md):
-
-| § | Governs | Reach for it when |
-|---|---------|-------------------|
-| §3 | bundle structure, reserved filenames | laying out directories |
-| §4 | concept documents & frontmatter | writing or validating a concept |
-| §5.1 | provenance — `sources` and its credibility signals | any external or empirical claim |
-| §5.2 / §5.3 | trust — `generated`, `verified`, and the derived tiers | recording who wrote or confirmed content |
-| §5.4 / §5.5 | lifecycle — `status`, `stale_after` | marking drafts, deprecations, expiries |
-| §6 / §6.1 | cross-links; **broken links are tolerated** | linking; judging a "broken" link |
-| §6.2 / §6.3 | path-valued fields; the `references/` convention | pointing at non-concept assets |
-| §7 | the actor convention | filling any `by` |
-| §8 | index files & progressive disclosure | orienting; writing or synthesizing an index |
-| §9 | log files | recording history |
-| §10 | attested computations | a concept that *is* a sanctioned computation |
-| §11 | conformance — the hard gate | what `validate` may and may not reject |
-| §12 | versioning (`okf_version`) | the root index's one allowed field |
-| §13 | changes from v0.1 | migrating a bundle; reading an unmigrated one |
-
 ## Modelling principles
 
 These are the decisions that make or break a bundle. None are enforced by the
@@ -177,7 +157,8 @@ declare it only when it says something. `stale_after` is an absolute
 the day itself. Use it for knowledge with a known shelf life (a quota, a
 migration window); `lint`'s `expired` check reports the ones whose date has
 passed. It is a declared expiry, distinct from the `--stale-after` *flag*,
-which is a reader-supplied age cutoff — see [cli.md](cli.md).
+which is a reader-supplied age cutoff — see [cli/checks.md](cli/checks.md),
+rule `okf-two-clocks`.
 
 ### 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
@@ -217,6 +198,21 @@ concepts. Templates: [concept](../templates/concept.md),
 nested [index](../templates/index.md), bundle-root
 [root-index](../templates/root-index.md), [log](../templates/log.md).
 
+### The log records what shipped, not how it shipped <!-- rule:okf-log-durable-only -->
+`log.md` carries durable knowledge and shipped behavior — never the process that
+produced them. A bug fixed in a release is an entry; the review rounds that found
+it are not. A capability that shipped is an entry; the iterations it took to
+stabilize it before it shipped are not. When a change taught a lesson, the lesson
+belongs in the concept it is about, stated as a principle, and the log entry
+*points* at that concept instead of re-narrating the rounds — a reader finds it
+where the subject lives, not by reading history.
+
+The bar is what a reader six months out needs: *what changed and why it matters*,
+never *how many passes it took to get there*. Watch for the shape this invites —
+the newest entries sit at the top where every reader lands, so a stretch of work
+stabilized by iteration accretes "round N found M defects" exactly where a durable
+summary belongs.
+
 ## Migrating from v0.1 (§13)
 
 A v0.1 bundle is consumable forever — §13.1 sanctions reading `timestamp` as
@@ -237,7 +233,7 @@ verb (search, produce, migrate, maintain, consume, curate, doctor), routed by th
 Commands table in [SKILL.md](../SKILL.md). The Closeout below is their shared
 finishing gate.
 
-## Closeout — the finishing gate
+## Closeout — the finishing gate <!-- rule:okf-closeout-gate -->
 
 `produce` step 6 and `maintain` steps 4–7 both land here: before calling an
 authoring task done, walk this once. It is the repo's "turn every task into a check
@@ -247,7 +243,8 @@ grep can't:
 - **Index enumerations** — every `index.md` that lists what you added, renamed, or
   removed is updated; re-run `okf index` and eyeball each listing against reality.
   Easy to skip, expensive to miss — this is the check that was missing.
-- **`log.md`** — a dated entry, newest first.
+- **`log.md`** — a dated entry, newest first, and durable only (rule
+  `okf-log-durable-only` above).
 - **`generated.at`** bumped on the concepts you touched (and `generated.by` says
   who touched them — you, in §7's spelling).
 - **`validate`** — zero §11 errors.