okf 2.0.0 → 2.1.1

data/.okf/model/bundle.md

@@ -0,0 +1,47 @@
+---
+type: Component
+title: OKF::Bundle
+description: The pure in-memory collection of concepts that validate, lint, and graph run over.
+resource: gems/okf/lib/okf/bundle.rb
+tags: [pure]
+generated:
+  by: human:maintainer
+  at: 2026-08-13T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/bundle.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/bundle.rb
+---
+
+# Overview
+
+`OKF::Bundle` is a set of [concepts](concept.md) held together in memory, with no
+disk involved. It is the object the three judging capabilities operate on:
+`#validate`, `#lint`, and `#graph` each hand the bundle to a dedicated pure
+class and return a result. A bundle also carries the reserved files
+(`index.md`, `log.md`) and — importantly — an `unparseable` list.
+
+# Best-effort by construction
+
+When a bundle is built from disk, files the reader cannot use do not vanish and do
+not abort the build: they are collected in `bundle.unparseable` — frontmatter that
+would not parse, and files that would not open, since a locked file is one file's
+problem and not the bundle's. That is what
+lets [graph](graph.md), the [server](../capabilities/graph-server.md), and the
+[read views](../capabilities/read-views.md) render everything that *is* valid
+while the [CLI](../cli.md) notes the skips on stderr — §11's best-effort posture,
+made structural.
+
+# Build it from data, not only from files
+
+Because the bundle is pure, an embedding application can construct concepts
+straight from its own records — no Markdown round-trip — and still get validate,
+lint, and graph for free. This is the surface the
+[library API](../capabilities/library-api.md) exposes to, say, a Rails store that
+already holds knowledge as rows. It also feeds the shared `#catalog`, the data
+behind every read view — and the rollups beside it, each kept in one home
+after a hand copy diverged: `#stats` (whose `by_dir` reads the directory
+index, so an empty directory reports its honest zero), `#tag_groups` (the
+vocabulary-curation cut, within-group counts beside cross-set totals), and
+`Bundle::References` (the §6.3 inventory — the one model that sees a bundle's
+non-markdown files, fed a manifest by the shell). The CLI verbs and the MCP
+tools consume the same three.

data/.okf/model/concept.md

@@ -0,0 +1,75 @@
+---
+type: Component
+title: OKF::Concept
+description: The pure in-memory model of a single OKF file — frontmatter, body, and a stable id.
+resource: gems/okf/lib/okf/concept.rb
+tags: [pure]
+generated:
+  by: human:maintainer
+  at: 2026-08-14T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/concept.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/concept.rb
+---
+
+# Overview
+
+`OKF::Concept` is the atomic node: a `path`, a parsed
+`frontmatter` (`@okf-eco format/frontmatter`) hash, and a Markdown `body`. It is
+[pure](../design/core-shell-split.md) — it holds no file handle and does no I/O.
+The on-disk counterpart is `OKF::Concept::File`, part of the
+[library API](../capabilities/library-api.md).
+
+# The id is the concept's identity
+
+`#id` is the concept's **stable identifier** across the whole system — the graph
+node key, the link target, and the thing you name a concept for. By default it is
+the `path` minus `.md` (e.g. `model/graph.md` → `model/graph`), which is why you
+name a file for what it *is*, not where it sits. A frontmatter `id`, when set,
+pins the identity explicitly — the path-derived name is the fallback, not the only
+source — so a concept can keep its id across a move.
+
+The override is this gem's **extension, not spec**: §2 defines the concept id
+as the path minus `.md`, full stop. Pinning one puts the concept in two worlds
+on purpose — the identity views ([catalog, hubs, `--dir`,
+search](../capabilities/read-views.md)) follow the id, because the edges do,
+while the physical views (`index`, `dirs`, stats' `by_dir`) keep the file where
+it lives, because an index is a physical listing. An integration test holds a
+concept whose id leaves its directory and asserts both worlds at once, so the
+split stays a decision; the authoring advice is the default's — rename the
+file, not the id.
+
+# What it derives from its own content
+
+The concept parses its body on demand into the structural facts the rest of the
+gem consumes:
+
+- `#type`, `#title`, `#description`, `#resource`, `#tags` — typed reads over
+  the frontmatter;
+- the §5 families, each carrying §13.1's fallbacks inline: `#generated` /
+  `#generated_at` / `#generated_by` (a legacy `timestamp` lifts into `at`,
+  per-key, with no actor ever invented), `#sources` (the native list, or the
+  legacy `# Citations` (`@okf-eco format/citations`) body list whenever the native
+  value yields zero mappings), `#verified` (a bare mapping reads as a
+  one-element list; degenerate shapes fold to unverified), `#trust_tier` /
+  `#trust` (derived per §5.3, never stored), `#status`/`#declared_status`
+  (absent reads stable; both keep the producer's spelling, because every
+  surface that *displays* a status prints what was written — the fold belongs
+  to `.effective_status`, which is what narrowing compares through), `#stale_after_date`/`#stale_on?(today)` (§5.5 — stale
+  on the day itself; the clock is always an argument, never read);
+- the §10 contract of an Attested Computation: `#runtime`, `#parameters`,
+  `#computation`, `#executor`, `#attester`, `#attested_computation?`;
+- `#usage_window` — validated for shape, deliberately consumed by nothing: no
+  gem surface computes over usage counts, so an effective-window resolver
+  would be speculative;
+- `#declared_generated?`, `#legacy_timestamp?`, `#legacy_citations?` — raw-key
+  detection for lint and the surfaces; detection never influences reading;
+- `#links` — every raw cross-link (`@okf-eco format/cross-links`) target in the body, in order; the bundle-relative ones become graph edges;
+- `#external_links` — the subset of those that are URLs or `mailto:` (not edges);
+- `#to_markdown` — the inverse of the frontmatter parser (`#citations` is gone,
+  subsumed by `#sources`);
+- `#lint` — the concept-scoped [lint](../capabilities/linter.md) checks in isolation.
+
+A concept never decides conformance alone; a [bundle](bundle.md) does, because
+some checks (duplicate titles, missing link targets) are only meaningful across
+the set.

data/.okf/model/graph.md

@@ -0,0 +1,59 @@
+---
+type: Component
+title: OKF::Bundle::Graph
+description: The in-memory knowledge graph — concepts as nodes, cross-links as directed edges, with type and tag indexes.
+resource: gems/okf/lib/okf/bundle/graph.rb
+tags: [graph, pure]
+generated:
+  by: human:maintainer
+  at: 2026-08-13T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/bundle/graph.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/bundle/graph.rb
+---
+
+# Overview
+
+`OKF::Bundle::Graph` turns a [bundle](bundle.md) into nodes and edges:
+[concepts](concept.md) become nodes keyed by id, and bundle-relative
+cross-links (`@okf-eco format/cross-links`) become directed edges. It is pure — it
+carries no presentation concerns; sizing and colour belong to a renderer like
+the [graph server](../capabilities/graph-server.md).
+
+# Fidelity is a build option
+
+The same graph ships at three weights, so a client downloads only what it needs
+and fetches the rest on demand:
+
+| Build | Node payload |
+|-------|--------------|
+| default (`body: true`) | id, type, title, description, tags, **body** |
+| `body: false` | everything but the body |
+| `minimal: true` | just id and title — the leanest payload to draw |
+
+# Indexes come free at every weight
+
+Regardless of node fidelity, the graph exposes two inverted indexes computed from
+every concept:
+
+- `type_index` — `{ type => [id, …] }`, so even a minimal client can colour nodes
+  by [`type`](concept.md). A concept whose type is missing *or blank* indexes
+  under `Untyped`: §11 condition 2 rejects the two identically (the
+  [validator](../capabilities/validator.md) asks `OKF.blank?`, not `empty?`), so
+  sorting them into different buckets would give `type: "  "` a row of its own,
+  labelled with spaces;
+- `tag_index` — `{ tag => [id, …] }`, so it can filter by tag.
+
+Those indexes, plus `unlinked_ids` (degree-0 nodes), are what the
+[read views](../capabilities/read-views.md) — `types`, `tags`, `stats`, `loose`
+— are built from, and what their `--type`/`--dir`/`--tag` filters match against.
+
+# Reduced to a skeleton
+
+Where this graph is the full wiring, the [skeleton](skeleton.md) is the same
+graph made holdable: concepts collapsed into their directory, the links between
+two directories collapsed into one weighted arc, and every link tagged with the
+cut it survives. It is the reduction [`graph --traffic`](../capabilities/read-views.md)
+reads for cohesion and the [graph page](../capabilities/graph-server.md) lays a
+large bundle out on — built from this graph's own nodes and edges, and just as
+pure.

data/.okf/model/index.md

@@ -0,0 +1,9 @@
+# The model
+
+The pure, in-memory data structures the gem builds a bundle out of — no disk, no
+stdio. Everything else reads or renders these.
+
+* [Concept](concept.md) - one file's worth of knowledge: frontmatter plus body, with a stable id.
+* [Bundle](bundle.md) - a collection of concepts you validate, lint, and graph.
+* [Graph](graph.md) - concepts as nodes, cross-links as edges, plus type and tag indexes.
+* [Skeleton](skeleton.md) - the graph reduced: directories, the weighted arcs between them, and each link with the cut it survives.

data/.okf/model/skeleton.md

@@ -0,0 +1,76 @@
+---
+type: Component
+title: OKF::Bundle::Skeleton
+description: The graph reduced to what a reader can hold — directories, the weighted arcs between them, and each link with the cut it survives.
+resource: gems/okf/lib/okf/bundle/skeleton.rb
+tags: [graph, pure]
+generated:
+  by: human:maintainer
+  at: 2026-07-23T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/bundle/skeleton.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/bundle/skeleton.rb
+  - title: gems/okf/lib/okf/cli/graph.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/cli/graph.rb
+---
+
+# Overview
+
+`OKF::Bundle::Skeleton` is the [graph](graph.md) reduced to what a reader can
+hold in their head. It is built from a graph's nodes and edges, does no I/O, and
+decides nothing about how any of it is drawn — the same purity the graph keeps,
+one level of abstraction up. Two consumers read it: [`graph
+--traffic`](../capabilities/read-views.md) prints its directory reduction, and
+the [graph page](../capabilities/graph-server.md)'s link layer lays a large
+bundle out on the backbone it names.
+
+A dense bundle is not dense the way a hub-and-spoke picture is. Measured on a
+47-concept bundle with 227 links, the top hub takes 13 inbound and the median 4 —
+no 80/20 to exploit, so dropping two-thirds of the *concepts* still leaves 53
+edges. The density lives **between directories**: 173 of those 227 links (76%)
+cross a directory boundary. That is the reduction worth drawing, and it is why
+this class exists at all.
+
+# The two things it produces
+
+- **`dirs` + `arcs`** — the reduction as counts: one row per directory, one
+  weighted arc per ordered pair of directories. This is what `graph --traffic`
+  prints, with **cohesion** (a directory's internal share of its own traffic)
+  derived from them. Directories come off the concept *id* (`OKF.dir_of`), not
+  the file path, so this agrees with the graph's own `catalog` and `--dir`
+  filter — the side that follows the id, because the edges do.
+- **`edges`, each with its `keep_at`** — the smallest cut at which a link
+  survives. Nothing prints these; they are what lets the graph page lay a large
+  bundle out on its strongest links first, inlined into the page as `EDGE_CUT`
+  because the layout needs them before any `fetch()` could answer.
+
+Both are emitted **unthresholded**, and `#suggested_cut` *names* where to cut
+rather than cutting — so a caller narrows the picture without this class ever
+having to know what a picture is.
+
+# The cut is fitted, not fixed
+
+A fixed arc cut cannot serve both ends of the size range: measured at weight 3
+across ten bundles, it left **2 arcs on one and 136 on another** — too tight to
+be a picture at one end, no reduction at all at the other. What stays roughly
+constant as a bundle grows is not the arc count but the arcs *per box*, since a
+node-link diagram reads at about one to two edges per node regardless of size. So
+`#suggested_cut` targets 1.5 arcs per directory and reports the weight that
+delivers it, floored at 8 for the small end. Cohesion is computed over **every**
+arc regardless of the cut, so narrowing the drawn picture never moves the
+evidence under it.
+
+# The spine is a sparsifier, not a sample
+
+The `keep_at === 0` set is the **spine**: each concept's single most-connected
+neighbour. It is chosen, not sampled, and the property that earns it the name is
+that it **touches every linked concept**, so a layout run over it alone strands
+nothing and the arrangement is a real one rather than a sketch to be redone.
+
+It is the local-degree sparsifier (Lindner et al.) with a union rule — an edge
+survives if *either* endpoint kept it — which is what stops it from stranding the
+quiet half of a bundle the way a global "drop the weakest edges" rule does. It is
+**not** the disparity filter, the usual name in this territory: that reads an
+edge's weight against its endpoint's total, and every link here weighs exactly 1,
+which makes every proportion identical and the filter a coin toss. Weighted-graph
+tools do not transfer to an unweighted graph just because both are graphs.

data/.okf/overview.md

@@ -0,0 +1,87 @@
+---
+type: Overview
+title: okf at a glance
+description: A light Ruby gem that reads, searches, validates, lints, and serves Open Knowledge Format v0.2 bundles.
+tags: [okf, gem, diagram]
+generated:
+  by: human:maintainer
+  at: 2026-08-13T12:00:00Z
+sources:
+  - title: README.md
+    resource: https://github.com/serradura/okf/blob/main/README.md
+  - title: AGENTS.md
+    resource: https://github.com/serradura/okf/blob/main/AGENTS.md
+---
+
+# Overview
+
+**okf** — the gem on RubyGems — operates on OKF v0.2 (`@okf-eco format/okf-format`)
+bundles: directories of Markdown files with YAML frontmatter that humans and
+agents both read from one source. It does not define new knowledge storage; it
+gives you leverage over knowledge that already lives as Markdown.
+
+```mermaid
+flowchart LR
+  skill["companion<br/>agent skill"] -. authors/curate .-> bundle[("OKF v0.2 bundle<br/>Markdown + YAML")]
+  bundle --> model["pure model<br/>Concept · Bundle · Graph"]
+  skill -. execute .-> cli
+  subgraph cli ["okf CLI"]
+    validate["validate — legal? §11"]
+    lint["lint — well-curated?"]
+    search["search — which concept?"]
+    server["server — explore"]
+  end
+  model --> cli
+  model --> library["library API<br/>embed in Ruby"]
+```
+
+Over such a bundle the gem gives you seven capabilities behind one
+[command-line tool](cli.md):
+
+| Capability                                               | What it answers                   | Verb             |
+| -------------------------------------------------------- | --------------------------------- | ---------------- |
+| [Companion agent skill](capabilities/agent-skill.md)     | Can an agent author it?           | `skill`          |
+| [Conformance validator](capabilities/validator.md)       | Is this a legal OKF bundle? (§11)  | `validate`       |
+| [Curation linter](capabilities/linter.md)                | Is it navigable, complete, fresh? | `lint` / `loose` |
+| [Ranked text search](capabilities/search.md)             | Which concept covers X?           | `search`         |
+| [Interactive graph server](capabilities/graph-server.md) | Can I explore it visually?        | `server`         |
+| [Static render](capabilities/render.md)                  | Can I ship a serverless snapshot? | `render`         |
+| [Library API](capabilities/library-api.md)               | Can my Ruby program use it?       | (in-process)     |
+
+Beside the gem's seven, the sibling surfaces. The
+MCP server (`@okf-mcp design/the-tool-set`) (`okf-mcp`) projects the same kernel
+onto the Model Context Protocol so any MCP-capable agent host reads these
+bundles without a terminal — ten read-only tools, concepts as resources a host
+can attach on its own, and the [skill's](capabilities/agent-skill.md) playbooks
+as prompts. The enforcement layer (`@okf-eco gems/okf-pro`) (`okf-pro`)
+goes the other way and is the only surface here that **writes**: it generates an
+agent's knowledge repository — bundle, hooks, pre-commit, CI, skill — and then
+holds it to a few invariants at all three doors, under a contract where a gate
+that cannot check refuses rather than shrugs.
+
+Alongside those, a family of [read views](capabilities/read-views.md) —
+`index`, `catalog`, `files`, `types`, `tags`, `stats`, `graph` — print the bundle at a
+glance so an agent reads it without a browser.
+
+Knowledge rarely lives in one bundle, so `okf server` hosts one, several, or every
+bundle in a per-user [registry](registry.md) — one hub, one switcher, no per-repo
+server to remember.
+
+# The two ideas it inherits from the format
+
+- **Dual audience.** Every file serves a human skimming it _and_ an agent
+  extracting from it, so bodies are structural Markdown and
+  links (`@okf-eco format/cross-links`) are plain Markdown links — both readers already
+  understand them.
+- **The graph is emergent.** Files are nodes, Markdown links are edges. You never
+  declare a graph; the gem [builds one](model/graph.md) from how concepts link.
+
+# Design ethos
+
+The gem is deliberately light so it runs on the Ruby an OS already ships. That
+ethos is not incidental — it is enforced by [hard constraints](design/):
+a [Ruby 2.4 floor](design/ruby-floor.md), exactly
+[three runtime dependencies](design/runtime-dependencies.md), and a
+[core/shell split](design/core-shell-split.md) that keeps all logic pure and
+testable without disk. Everything else — no ActiveSupport, no build step, no
+JavaScript toolchain — follows from those.

data/.okf/registry.md

@@ -0,0 +1,265 @@
+---
+type: Component
+title: The bundle registry
+description: An ordered list of bundle references persisted as JSON — global under $OKF_HOME, or project-local via `okf registry init` and discovered from the working directory — the kernel behind a bare `okf server`.
+resource: gems/okf/lib/okf/registry.rb
+tags: [cli, shell, registry]
+generated:
+  by: human:maintainer
+  at: 2026-07-24T12:00:00Z
+sources:
+  - title: gems/okf/lib/okf/registry.rb
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/registry.rb
+---
+
+# Overview
+
+`OKF::Registry` is the gem's only piece of *durable user state*: an ordered list
+of bundle references, so `okf registry set` today and a bare `okf server`
+tomorrow share one list. It is a plain JSON file — `$OKF_HOME/registry.json`,
+`$OKF_HOME` defaulting to `~/.okf` — and that is a design choice, not a stopgap: a
+database would break the [two-dependency rule](design/runtime-dependencies.md),
+and the file is per-user, hand-editable, and greppable. It is part of the
+[shell](design/core-shell-split.md); it reads and writes a file. That is the
+*global* registry; a project can keep its own, discovered from the working
+directory — see [Global by default, project-local by discovery](#global-by-default-project-local-by-discovery).
+
+The registry stores *references*, never content. It holds a path, a slug, and a
+title — the bundles themselves stay where they are on disk, owned by the repos
+they document. Nothing is copied, so nothing can go stale except the path itself.
+
+# Slugs: implicit is forgiving, explicit is strict
+
+A slug is the bundle's mount key (`/b/<slug>/`) and its name in the
+[switcher](capabilities/graph-server.md). Where it comes from decides what a
+collision means:
+
+| Source | On collision | Why |
+|--------|--------------|-----|
+| the directory basename (`registry set ./docs`) | silently suffixed — `docs-2`, `docs-3` | you never asked for a name; the gem picks a free one |
+| an explicit `--as SLUG`, or `registry rename` | raises | you *did* ask for that name, so quietly serving a different one is a lie |
+
+That asymmetry is the whole rule: **the gem may invent a name, but it may never
+substitute one you chose.** Both paths run the same normalization the ephemeral
+(unregistered) bundles use, so a directory mounts under the same slug whether it
+was registered or passed straight to `okf server` — with exactly one exception,
+the reserved `all/` below, which the registry alone has a reason to rename.
+
+The rule extends cleanly to a name the grammar has already spoken for. `@all`
+means *every registered bundle* to [`search`](capabilities/search.md), so no one
+bundle may answer to `all` — it is reserved. A directory named `all/` therefore
+registers as `all-2` (the basename was only a guess, so a suffix is right), while
+`--as all` is refused (the ask was deliberate, so substituting `all-2` would be
+the lie).
+
+The reservation is the *registry's*, not the slug helper's, and that boundary is
+load-bearing in both directions. Inward, all three ways a slug enters this list
+are covered — minting, an explicit ask, and **reading the file**. The third is the
+one that cannot refuse. `all` reaches the file two ways nothing can take back: a
+release from before the name was reserved wrote it (a directory named `all/`
+slugged exactly that), or a hand typed it into the file the format invites you to
+edit. So the read *mints around it* — the entry lists, mounts, and answers to
+`all-2`, and the next write persists the name.
+
+**The read normalizes for the same reason**, and it is the same bug one step
+wider: two of the three ways in normalized and the third did not. A hand-typed
+`"slug": "My Docs"` listed perfectly well while `@my-docs` missed it — and so did
+`rename` and `default`, which look an entry up through the very normalization the
+read had skipped. The two verbs that could repair the entry were the two that
+could not see it. A slug registration would have handed back untouched is left
+alone (including one already suffixed, so fixing a sick entry never renames a
+healthy one); everything else is minted around what the other entries hold.
+<!-- rule:okf-registry-read-normalizes -->
+
+That asymmetry was also the [graph server](capabilities/graph-server.md)'s XSS
+trigger: slugs reach the bundle switcher's HTML, and the only way one could carry
+a quote was to arrive un-normalized through this read. Normalizing closes it at
+the source — the escape is hardened too, because a page whose safety depends on a
+guarantee three layers away is not one you can reason about locally.
+
+Refusing the file was the first answer here, and it was worth the correction it
+took. A name the grammar has taken makes **one entry** unnameable; rejecting the
+registry makes **every** entry unreachable — and takes `del` and `rename`, the two
+verbs that could fix it, down on the very read they need to survive, leaving
+hand-editing JSON as the only way out. A guard whose failure mode is worse than
+what it guards against is not a guard. Minting is also simply the rule already
+stated above, read one line further: the gem may invent a name, and here the name
+on disk cannot be used, so inventing one is the only move that is not a lie.
+<!-- rule:okf-registry-reserved-mint -->
+
+Outward, it stops there: an ephemeral `okf server ./all` has no
+registry and no refs, so there is no name to protect, and it mounts at `/b/all/` —
+suffixing it would invent a `/b/all-2/` whose `/b/all/` does not exist. `all/` is
+therefore the one directory whose registered slug and ephemeral slug differ, and
+they differ because only one of the two worlds has a grammar that spells `all`.
+
+The rule cuts one layer deeper, at the empty string. Minting a slug from a
+basename must *produce* something, so `slugify` falls back to a placeholder when
+nothing survives normalization. Looking one up must not: a lookup that inherits
+that fallback makes `@***` resolve to whatever bundle happens to be slugged
+`bundle` — the gem substituting a name you never chose, which is the one thing
+the rule forbids. So `normalize` (no fallback) backs every lookup and every
+explicit ask, and `slugify` (placeholder) backs only basename minting.
+
+# The default is a position, not a stored name
+
+The first entry still on disk is the bundle a bare `okf server` opens at `/`, and
+`registry default <slug>` moves that entry to the front. That is the whole
+feature.
+
+"Still on disk" is the one qualifier position needs, and it is not a fallback in
+disguise. The hub drops a bundle whose directory has vanished rather than serving
+a hole, so a default that ignored the gap would put `registry list`'s `*` on a
+bundle `/` never opens — the star names what `/` opens, so it has to skip what `/`
+skips. The rule stays derivable from the file plus the disk, with nothing stored
+and nothing to reconcile. Its mirror is that `registry default <slug>` *refuses* a
+vanished directory, exactly as `registry set` refuses to register one: both are
+explicit asks, and a move the default would then skip would answer with a slug the
+user did not type.
+
+The alternative — storing the chosen slug — looks simpler and is not. A stored
+slug is a *foreign key* into the same list it lives in, and a foreign key demands
+referential integrity from every operation that touches the list: carry it
+through a `rename`, re-point it when `add --as` renames in place, clear it on a
+`remove`, and fall back when it dangles anyway. Four obligations, each a place to
+forget. Position owes nothing: a rename touches the name and leaves the row where
+it is, a `del` lets the next row become first, and a default that is not in the
+list is *unrepresentable* rather than merely handled. The registry was already
+documented as ordered, so this is state it kept for free.
+
+What it costs is a file that visibly reorders, which is why `registry default`
+says so in its own help — the JSON is meant to be read and hand-edited, and a
+reordering write should never be a surprise.
+
+Identity is the **path**, not the slug: re-registering a directory already in the
+registry refreshes its title in place instead of adding a twin.
+
+# It names bundles for the whole CLI, not just the server
+
+The registry began as the server's boot list and grew into the
+[CLI](cli.md)'s name-resolution layer: wherever a verb takes a `<dir>`,
+`@slug` resolves through it and bare `@` picks the default — the same slugs the
+hub mounts at `/b/<slug>/`, so the name you click is the name you type. That is
+what turns registering from "tell the server" into "give this bundle a name":
+[`search`](capabilities/search.md) crosses several of them in one query, and no
+verb needs a path once the bundle has a slug.
+
+It is also no longer terminal-only. The graph page's ⚙ Bundles panel drives
+`default`, `rename` and `remove` from a browser, through
+[this class and its messages](capabilities/bundles-manager.md) rather than around
+them. `add` stays terminal-only, because a browser cannot hand over a filesystem
+path. The file stays the record: every write goes through here, and the hub
+re-reads it per request rather than trusting a snapshot, so an `okf registry
+rename` in another terminal shows on a refresh.
+
+# Groups: a named set of bundles
+
+A **group** is a slug that names not one bundle but a *list* of members — bundle
+or group slugs, so groups nest — and resolves, recursively and path-deduped, to
+the bundle leaves underneath. It is the durable form of typing `@a @b @c`: once
+several bundles earn a name together (`okf registry group backend @orders
+@billing`), `@backend` stands in for the set. `group`/`ungroup` add and remove
+members; emptying a group deletes it, since an empty set resolves to nothing.
+
+Groups live in **their own list** (`{ bundles: […], groups: […] }`), not among
+the entries — a deliberate separation. The first-is-default rule and every
+`File.directory?` guard assume an entry has a path, and a group has none;
+threading a nil path through all of them to host a pathless member would be the
+foreign-key tax the default rule already refused. A separate list leaves the
+bundle invariants untouched and makes a group exactly what it is: a view over
+them.
+
+**One namespace, two kinds.** A slug names a bundle *or* a group, never both, so
+`@backend` is unambiguous — the collision check that already spanned entries and
+the reserved `all` now spans groups too, in both directions (`registry set --as
+backend` is refused while a group holds it, and vice versa). And because a member
+list stores slugs, the two lifecycle verbs keep those references live: `rename`
+**cascades** the new name across every group that named the slug, and `del`
+**cascade-drops** it (a group emptied that way is deleted). Skipping either would
+orphan a member silently — the same drift the path-not-slug identity rule avoids
+for the default.
+
+**Only a set-taking verb consumes one.** [`search`](capabilities/search.md) and
+[`server`](capabilities/graph-server.md) are the two verbs that already take
+several bundles; a group feeds exactly them (`okf search @backend …` merges the
+members into one ranking, `okf server @backend` mounts each). Every single-bundle
+verb refuses a `@group` with exit 2 — the same second-bundle rule that stops
+`okf lint a b` from linting `a` and ignoring `b`, because a group resolving to
+three bundles is that ambiguity by another spelling. `@all` is unchanged: it
+still names every registered *bundle*, and a group is a named subset of what it
+already covers. A cycle is refused at write time and guarded again at resolution,
+since the file is hand-editable.
+<!-- rule:okf-registry-groups-cascade -->
+
+# It tolerates a world that changes underneath it
+
+A registry entry is a bet that a directory still exists, and the registry never
+prunes on its own — deleting a bundle from disk must not silently rewrite a list
+the user curated. Instead `listing` marks the entry `missing`, so
+[`registry list`](cli.md) shows the gap and the user decides. Reads are equally
+forgiving: the original bare-array file shape still parses, while a *corrupt*
+file raises with the fix — "fix or delete the file" —
+rather than starting from an empty list and silently dropping every bundle.
+
+That message invites a hand-edit, which is why the shape is checked and not just
+the syntax: valid JSON is not a valid registry, and an entry missing its `path`
+must fail here, as a usage error naming the file, rather than surviving to crash
+a `File.directory?` three frames away. The [CLI](cli.md) does its half by
+loading through a guard, so a broken file reaches the user as an error from
+whatever verb they ran — not a backtrace from a verb that never rescued one.
+
+Writes go to a temp file and are promoted with `rename`, the same atomic
+promotion the [bundle writer](capabilities/library-api.md) uses, so a booting
+server never reads a torn file. Two racing writers stay last-writer-wins: this is
+a per-user file, and locking would buy nothing worth the complexity.
+
+# Global by default, project-local by discovery
+
+The registry has two homes, and which one answers is decided by *where you stand*,
+not by a flag. The global one is the `$OKF_HOME/registry.json` above — one per
+user, shared across every repo. The project-local one is a `.okf-registry.json`
+that `okf registry init` drops in a directory; okf finds it by walking up from the
+working directory, and while you are inside its tree it **replaces** the global one
+— every registry op, and every [`@slug`](cli.md), resolves through it. So a bare
+`okf server` inside a repo serves that repo's bundles with no `$OKF_HOME` setup,
+and a project carries its own named set without touching the user's global list.
+
+**The file's presence is the whole state.** There is no stored "local mode", the
+same way the [default is a position, not a stored name](#the-default-is-a-position-not-a-stored-name):
+a mode flag would be one more thing to set, dangle, and reconcile, where the file
+being *there* is self-evident and self-cleaning. The nearest one on the path up
+wins, so nested registries resolve nearest-first, and `okf registry list` names the
+file it found so which one is answering is never a guess.
+
+`$OKF_HOME` still names *where the global registry lives*; it does **not** veto a
+nearer local one. That direction is deliberate: `$OKF_HOME` is commonly exported
+once and left, so letting it win would silently defeat the feature for exactly the
+users who set up a project registry. The escape hatch is therefore a per-invocation
+signal, not a second sticky variable — `OKF_NO_DISCOVERY=1`, set inline, forces the
+global registry for a fixed-cwd caller (CI, a tool) that cannot just `cd` out.
+
+# A project-local registry stores portable paths
+
+The global registry stores absolute paths — correct for `~/.okf`, whose bundles
+are scattered across the disk with no shared anchor. A committed project registry
+needs the opposite: a bundle **inside** the registry's own tree is stored *relative*
+to the `.okf-registry.json`, so the file travels with the repo — a checkout on
+another machine, or a container mounting it, resolves the same bundles unchanged. A
+bundle **outside** the tree keeps an absolute path, because a relative path that
+climbs out cannot be re-anchored anywhere useful, and being honest that it will not
+travel beats a `../../..` that breaks on the first move.
+
+The relative form lives **only on disk**. A path resolves to absolute the moment it
+is read, so `entry.path`, [`registry list`](cli.md), and the server mount all go on
+seeing the absolute paths they always did — the portability is a property of the
+file, invisible to every consumer. And because only the write side relativizes, an
+existing absolute local entry migrates to relative on its next write: a registry
+written before this existed heals itself the first time it changes.
+<!-- rule:okf-registry-local-discovery -->
+
+# It costs an embedding app nothing
+
+`require "okf"` does not load it. The registry is reached only from the
+[CLI](cli.md), which requires it at the moment a registry verb or a bare `server`
+runs — the same on-demand rule the [library API](capabilities/library-api.md)
+keeps for the command-line machinery.