okf 2.1.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,44 @@ 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
@@ -1437,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,
@@ -1543,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
 
@@ -173,12 +343,22 @@ do not know.
 
 ## More
 
-The [project README](https://github.com/serradura/okf-gem#readme) carries the
+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-gem`). 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.
+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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.1.1
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -77,6 +77,47 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".okf/capabilities/agent-skill.md"
+- ".okf/capabilities/bundles-manager.md"
+- ".okf/capabilities/graph-server.md"
+- ".okf/capabilities/index.md"
+- ".okf/capabilities/library-api.md"
+- ".okf/capabilities/linter.md"
+- ".okf/capabilities/read-views.md"
+- ".okf/capabilities/render.md"
+- ".okf/capabilities/search.md"
+- ".okf/capabilities/validator.md"
+- ".okf/cli.md"
+- ".okf/design/browser-tests.md"
+- ".okf/design/core-shell-split.md"
+- ".okf/design/index.md"
+- ".okf/design/integration-first.md"
+- ".okf/design/packaging.md"
+- ".okf/design/ruby-floor.md"
+- ".okf/design/runtime-dependencies.md"
+- ".okf/design/search-engines.md"
+- ".okf/design/server-trust-boundary.md"
+- ".okf/index.md"
+- ".okf/log.md"
+- ".okf/model/bundle.md"
+- ".okf/model/concept.md"
+- ".okf/model/graph.md"
+- ".okf/model/index.md"
+- ".okf/model/skeleton.md"
+- ".okf/overview.md"
+- ".okf/registry.md"
+- ".okf/structure/format-layer.md"
+- ".okf/structure/index.md"
+- ".okf/structure/search.md"
+- ".okf/structure/the-analysers.md"
+- ".okf/structure/the-cli.md"
+- ".okf/structure/the-disk-shell.md"
+- ".okf/structure/the-model.md"
+- ".okf/structure/the-server.md"
+- ".okf/structure/the-skill.md"
+- ".okf/testing/adding-a-verb.md"
+- ".okf/testing/index.md"
+- ".okf/testing/the-harness.md"
 - CHANGELOG.md
 - LICENSE.txt
 - NOTICE
@@ -160,14 +201,14 @@ files:
 - lib/okf/skill/templates/log.md
 - lib/okf/skill/templates/root-index.md
 - lib/okf/version.rb
-homepage: https://github.com/serradura/okf-gem
+homepage: https://github.com/serradura/okf
 licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/serradura/okf-gem
-  source_code_uri: https://github.com/serradura/okf-gem
-  changelog_uri: https://github.com/serradura/okf-gem/blob/main/okf/CHANGELOG.md
+  homepage_uri: https://github.com/serradura/okf
+  source_code_uri: https://github.com/serradura/okf
+  changelog_uri: https://github.com/serradura/okf/blob/main/gems/okf/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: