okf 1.11.0 → 1.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fae00b0ef2e7029cf0869ec73339321f6a54d58bd566aa6139cf6d5143999b9
-  data.tar.gz: e337a96fadc268338e4f23984bb85b7b6ad54cee9b13f79a8301ae0179d4eec0
+  metadata.gz: 9a83101e62e3b3bc97d7351580d50ecc017be391a5edbde2e8f52388de529111
+  data.tar.gz: 040be5295642da56cbeed342424872469d1c2b15efcb1b477f10076d7c90fafc
 SHA512:
-  metadata.gz: ec66b51cd4a4cba56998248a85bf0470ad62db32487f7c5d0c66780057bcdb839b0f6b521fe6649fb438a0010da2c9d3a82b2781fbeb59c90de5d96971b5ab39
-  data.tar.gz: 181388d7be611d1af0fb811a50a326f7d72b159d4ea09b632007d5a355042faf6bca7c27f6d5d67d396fad03f868450ec2ed0234655b3a7861074b43b3356135
+  metadata.gz: 47fb84d8dffc04eee30eb65adfaca756ae43315e2d152e62692084a5bd04c6a7992529d243b2375412a8339a55db891c3ae18d679e171d5709e9426b93686047
+  data.tar.gz: 30390e1eecc1570b28531c374b21200309630aad87f821a7c3f25b631ca5285e03b91baab9048f69127931a09368da1ab38a089fc9bc25473c05da3c0fadfe2b

data/CHANGELOG.md

@@ -5,6 +5,97 @@ 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).
 
+## [1.12.0] - 2026-07-24
+
+### Added
+
+- **`okf graph --traffic`** — the link graph read one grain coarser. `--hubs`
+  measures concepts, but the refine playbook's directory judgements ("does this
+  directory prune? a concern, or a container?") had nothing measured at their
+  grain. `--traffic` collapses each concept into its directory and the links
+  between two directories into one weighted arc, so every row carries its
+  internal / out / in traffic and a **cohesion** — its internal share of that
+  total. That is cohesion versus coupling on a knowledge tree: near-zero cohesion
+  under heavy inbound is a shared vocabulary doing its job, heavy outbound with
+  nothing back is a projection wearing a directory. The rows sort by cohesion
+  ascending, so the directories with a case to answer come first, and a directory
+  with no traffic at all prints `—` rather than a `0%` it did not earn. The arc
+  **cut** is fitted to the bundle, not fixed — at weight 3, ten bundles ranged
+  from 2 arcs to 136 — and `--cut N` overrides it; cohesion is computed over
+  *every* arc regardless, so narrowing the drawn picture never moves the
+  evidence. JSON: `{ bundle, cut, fitted, dirs, arcs, total_arcs }`. The pure
+  model underneath is `Bundle::Skeleton` — concepts folded to directories, links
+  to weighted arcs, every edge tagged with the cut it survives (a local-degree
+  sparsifier, union rule, so no linked concept is ever stranded) — and it does no
+  I/O and draws nothing: it names a cut rather than taking one, so both the graph
+  page and the CLI narrow the same emission their own way.
+- **The graph page draws links in three amounts, and opens dense on its spine.**
+  227 links over 47 concepts at degree 9.7 is unreadable because of its arrows,
+  not its dots — so links become a layer: **every** link, the **spine** (each
+  concept's strongest edge — the Skeleton's `keep_at===0` set, chosen so it
+  touches every linked concept), or **none**, with a selected concept's own links
+  always shown in full. A dense bundle now opens on its spine rather than greeting
+  the reader with the thicket; the trigger is undirected degree above a floor set
+  between a tree's ~2 and the 9.7 that drove it, and `--map` overrides to none
+  with the directories boxed. Above 800 edges the first layout runs on the spine
+  alone and the rest arrive a frame later with no re-layout — **6.25 s → 3.29 s**
+  on 414 concepts, nothing on screen moving. Proven in both render modes on a
+  committed 110-concept / 880-link fixture, the only one over both floors.
+- **Registry groups — a named, recursive set of bundles.** A group is a registry
+  slug that names a list of members (bundle *or* group slugs, so they nest) and
+  resolves recursively, path-deduped, to its bundle leaves. `okf registry group
+  <slug> <@member…>` creates one or adds to it, `ungroup` removes members (and
+  emptying a group deletes it), and `del`/`rename` now span a group slug too —
+  one name cascades across every member list, one `del` cascade-drops the slug and
+  deletes any group it empties. Groups live in their own list in the registry
+  JSON, so the first-is-default rule and the `File.directory?` guards never meet a
+  pathless entry. `okf search @backend` merges the members into one ranking and
+  `okf server @backend` mounts each (the first at `/`), both skipping a vanished
+  member with a note, exactly as `@all` does. Every single-bundle verb **refuses**
+  a `@group` (exit 2) — the same rule that refuses a second bundle, through the
+  same `resolve_registered` seam.
+- **`okf registry init`** — create a project-local `.okf-registry.json` in the
+  current directory. Once it exists, okf discovers it by walking up from the
+  working directory, and every registry operation — and every `@slug` — resolves
+  through it in place of the global `$OKF_HOME` registry, so a bare `okf server`
+  inside a repo serves that repo's bundles with no global setup. The nearest one
+  on the path wins (nested registries resolve nearest-first), `okf registry list`
+  names the local file it found, and `OKF_NO_DISCOVERY=1` forces the global one —
+  the escape hatch for a fixed-cwd caller (CI, a tool).
+- **A local registry stores portable, relative paths.** A bundle inside the
+  registry's own tree is written relative to the `.okf-registry.json`, so the file
+  can be committed and travels with the repo — a checkout on another machine, or a
+  container that mounts it, resolves the same bundles unchanged. A bundle outside
+  the tree keeps an absolute path (it cannot travel). Paths still read back
+  absolute everywhere the CLI reports them; the relative form lives only on disk,
+  and an existing absolute local entry migrates to relative on its next write. The
+  global `$OKF_HOME` registry is unchanged — it stores absolute paths as before.
+
+### Changed
+
+- **The derived `area` field is renamed `top_dir`** — the first-path-segment
+  rollup the catalog, search, `stats`, and `graph --hubs` carry. `area` was never
+  the OKF spec's word (the spec speaks only of `dir`), so the rollup now names
+  itself in the spec's vocabulary: it is the `dir` at the top level. The `--json`
+  keys move with it — catalog/search rows carry `top_dir` in place of `area`,
+  `stats` emits `top_dirs`/`by_top_dir`, and `graph --hubs` emits
+  `top_dir`/`by_top_dir`. The **deprecated `--area`/`--by area` input flags are
+  unchanged** — they still warn and map to `--dir`/`--by dir`, and now source the
+  renamed field internally. No behavior changes; the well-homed-hub numbers are
+  identical.
+
+### Fixed
+
+- **A local-registry server preserves its relative-path anchor across a
+  re-open.** The hub re-read its boot registry with `OKF::Registry.new(path)`,
+  which drops the `relative_base` a discovered `.okf-registry.json` carries — so
+  on a project-local server the Bundles panel matched each mounted bundle's
+  absolute root against the re-read entry's *relative* path, missed, and drew
+  every in-tree bundle as "folder is gone", while a browser add flattened the new
+  bundle to an absolute path, undoing the portability relative storage exists for.
+  `Registry#reopen` re-reads the same file anchored the same way, and both hub
+  re-open sites use it.
+
 ## [1.11.0] - 2026-07-22
 
 ### Added
@@ -205,7 +296,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   rendered `(root)` for humans — and "cluster" stays prose for what a dir
   groups. Both deprecated spellings keep their **old behavior exactly** and warn
   once per run on stderr (`--json` on stdout is unaffected); they go in a later
-  release, along with `by_area` and the `area` row field.
+  release.
 
 ## [1.10.0] - 2026-07-21
 

data/README.md

@@ -227,72 +227,26 @@ okf server .
 Images are published for `linux/amd64` and `linux/arm64` on
 [ghcr.io](https://github.com/serradura/okf-gem/pkgs/container/okf).
 
-## Command line
-
-These verbs are written to be read by an **agent first and a person second** —
-that is what the skill drives, with no wrapper in between. Every read verb takes
-`--json`, the list views project down to the fields you ask for
-(`--fields`/`--except`), so nothing pays for output it will not read, and the
-exit codes are stable enough to branch on in CI. The same commands render as
-scannable plain text when a human is the one looking.
-
-```bash
-okf validate  <dir|@slug>                        # is this legal OKF?
-okf lint      <dir|@slug> [--fail-on warn]       # is it navigable, complete, fresh?
-okf loose     <dir|@slug>                        # concepts with no links in or out
-okf search    <dir|@slug…|@all> <term…>          # ranked retrieval; @all spans every bundle
-okf index     <dir|@slug> [--dir D] [--depth N]  # the §6 map: index bodies, rollups, listings
-okf dirs      <dir|@slug> [--dir D] [--depth N]  # the shape: every directory and what it holds
-okf catalog | files | tags | types | stats  <dir|@slug>   # the browser views, on the CLI
-okf graph     <dir|@slug> [--hubs]               # the raw graph; --hubs ranks by inbound links
-okf server    [DIR|@slug…] [-p PORT] [--bind ADDR]   # the live graph: one bundle, or all of them
-okf render    <dir|@slug> [-o FILE]              # the same page as one static, self-contained file
-okf registry  list | set | del | default | rename    # name your bundles (see below)
-okf skill     <dest>                             # install the companion agent skill
-okf --version
-```
-
-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/).
-
-```bash
-$ okf validate docs
-OKF v0.1 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 §5.3)
-  …
-  ✓ 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
-```
-
-### 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
-```
+## Where to go next
+
+Installed. The rest of this page is each surface the gem gives you over a bundle,
+in the order most people meet them:
+
+- **[The graph](#the-graph)** — the whole bundle on one page, live or baked into a
+  single HTML file you can host anywhere. Start here if you want to *see* it.
+- **[Agent skill](#agent-skill)** — the verbs your agent runs to author, maintain
+  and answer from a bundle, so you stay the editor rather than the typist.
+- **[Claude Code plugin](#claude-code-plugin)** — that skill, a slash command and a
+  post-edit curation hook, in two lines.
+- **[Command line](#command-line)** — every view as scannable text or as JSON, with
+  exit codes stable enough to gate CI on.
+- **[Library](#library)** — `OKF::Bundle` in your own Ruby, and the graph as a Rack
+  app you can mount in an app you already have.
+- **[Extending okf](#extending-okf-and-running-it-safely)** — ship a verb as a gem,
+  and what the page does and does not trust in a bundle you did not write.
+
+Full reference for every verb and flag lives in
+**[the docs](https://okfgem.com/docs/)**.
 
 ## The graph
 
@@ -335,6 +289,24 @@ okf search @all rate limit              # ranked retrieval across every register
 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
@@ -350,7 +322,8 @@ public one.
 
 The gem carries the [companion OKF agent skill](.okf/capabilities/agent-skill.md):
 a `SKILL.md` plus reference and template files that teach a coding agent to
-author, maintain, and consume OKF bundles and to drive the commands above.
+author, maintain, and consume OKF bundles and to drive the
+[commands below](#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.
@@ -390,6 +363,99 @@ 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.
 
+## 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: the [`okf` skill](#agent-skill) above;
+**`/okf:gem`**, a front door that hands its arguments to the skill unchanged (no
+arguments: it orients on your bundle and recommends the next move, never
+auto-runs); and a **curation hook** that runs `okf validate` + `okf lint` after
+every edit inside a bundle 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 it is config-free to switch off:
+`OKF_CURATE_DISABLED=1` turns it off, `OKF_CURATE_QUIET=1` keeps the findings
+without the install suggestion, and an `<!-- okf-disable -->` comment skips one
+file.
+
+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.
+
+## Command line
+
+These verbs are written to be read by an **agent first and a person second** —
+that is what the skill drives, with no wrapper in between. Every read verb takes
+`--json`, the list views project down to the fields you ask for
+(`--fields`/`--except`), so nothing pays for output it will not read, and the
+exit codes are stable enough to branch on in CI. The same commands render as
+scannable plain text when a human is the one looking.
+
+```bash
+okf validate  <dir|@slug>                        # is this legal OKF?
+okf lint      <dir|@slug> [--fail-on warn]       # is it navigable, complete, fresh?
+okf loose     <dir|@slug>                        # concepts with no links in or out
+okf search    <dir|@slug…|@all> <term…>          # ranked retrieval; @all spans every bundle
+okf index     <dir|@slug> [--dir D] [--depth N]  # the §6 map: index bodies, rollups, listings
+okf dirs      <dir|@slug> [--dir D] [--depth N]  # the shape: every directory and what it holds
+okf catalog | files | tags | types | stats  <dir|@slug>   # the browser views, on the CLI
+okf graph     <dir|@slug> [--hubs] [--traffic]   # the raw graph; --hubs ranks concepts, --traffic dirs
+okf server    [DIR|@slug…] [-p PORT] [--bind ADDR]   # the live graph: one bundle, or all of them
+okf render    <dir|@slug> [-o FILE]              # the same page as one static, self-contained file
+okf registry  init | list | set | del | default | rename | group | ungroup   # name & group your bundles; @slug works anywhere
+okf skill     <dest>                             # install the companion agent skill
+okf --version
+```
+
+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/).
+
+```bash
+$ okf validate docs
+OKF v0.1 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 §5.3)
+  …
+  ✓ 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
+```
+
+### 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
+```
+
 ## Library
 
 `require "okf"` gives you the whole thing as Ruby objects — two layers: pure
@@ -412,17 +478,17 @@ OKF::Server::App.new(folder)     # => a Rack app: the interactive graph, mountab
 
 That last line is the point of the Rack app: the graph mounts inside an app you
 already have, auth included. The [Rails guide](https://okfgem.com/docs/guides/rails/)
-walks it, and the [library API](.okf/capabilities/library-api.md) concept covers
+walks it, and the [library API](https://okfgem.com/docs/library/) covers
 the pure layer, the writer, and the lower-level pieces.
 
 ### validate and lint are two different questions
 
-`validate` (the [conformance validator](.okf/capabilities/validator.md)) asks
+`validate` (the [conformance validator](https://okfgem.com/docs/cli/validate/)) asks
 _"is this legal OKF?"_ and implements the spec's
 [§9](lib/okf/skill/reference/SPEC.md#9-conformance) exactly — which means it is
 *forbidden* to reject a bundle for a broken link or a missing optional field.
 
-`lint` (the [curation linter](.okf/capabilities/linter.md)) asks the
+`lint` (the [curation linter](https://okfgem.com/docs/cli/lint/)) asks the
 complementary question, _"is this well-curated, navigable, trustworthy?"_, over
 exactly those tolerated things: reachability, backlog, completeness, freshness,
 provenance, hygiene. It is advisory and exits `0` even with findings unless you
@@ -447,32 +513,6 @@ treat an unfamiliar bundle the way you would treat any document from a source yo
 do not know. Full write-up:
 [server trust boundary](.okf/design/server-trust-boundary.md).
 
-## 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: the [`okf` skill](#agent-skill) above;
-**`/okf:gem`**, a front door that hands its arguments to the skill unchanged (no
-arguments: it orients on your bundle and recommends the next move, never
-auto-runs); and a **curation hook** that runs `okf validate` + `okf lint` after
-every edit inside a bundle 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 it is config-free to switch off:
-`OKF_CURATE_DISABLED=1` turns it off, `OKF_CURATE_QUIET=1` keeps the findings
-without the install suggestion, and an `<!-- okf-disable -->` comment skips one
-file.
-
-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

data/lib/okf/bundle/folder.rb

@@ -42,6 +42,10 @@ module OKF
         @bundle.graph(minimal: minimal, body: body)
       end
 
+      def skeleton
+        @bundle.skeleton
+      end
+
       def catalog
         @bundle.catalog
       end

data/lib/okf/bundle/search.rb

@@ -279,7 +279,7 @@ module OKF
       end
 
       # Ranked match rows, catalog-style identity plus where the terms hit:
-      # [{ slug:, id:, title:, type:, dir:, area:, tags:, matched: [field, …], score:, snippet: }, …]
+      # [{ slug:, id:, title:, type:, dir:, top_dir:, tags:, matched: [field, …], score:, snippet: }, …]
       # ordered by score descending, then slug, then id. `slug` is present only
       # when searching across bundles. No terms means no matches.
       def results
@@ -367,7 +367,7 @@ module OKF
           title: (concept.title || concept.id).to_s,
           type: concept.type.to_s,
           dir: OKF.dir_of(concept.id),
-          area: area_of(concept.id),
+          top_dir: top_dir_of(concept.id),
           tags: Array(concept.tags).map(&:to_s),
           matched: matched,
           score: score.round(4),
@@ -421,9 +421,9 @@ module OKF
         end
       end
 
-      # A concept's top-level area, mirroring the catalog's definition. Deprecated
-      # in favour of OKF.dir_of, which keeps the levels this one throws away.
-      def area_of(id)
+      # A concept's top-level dir, mirroring the catalog's definition — the first
+      # path segment. OKF.dir_of keeps the levels this one rolls up.
+      def top_dir_of(id)
         id.include?("/") ? id.split("/").first : "(root)"
       end
     end