okf 2.1.1 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ee1290010aa1d32e2f38408b2c630666cec67265f41e7c7186297274748120fa
-  data.tar.gz: a6b6218572fe7a74c38d0445940954c0fdbe591adab3e820d7de5aed71809828
+  metadata.gz: 0aee1cdfc7b13016c423050f98de4994431fa68ae4afe3869b5555b5408c3315
+  data.tar.gz: '058369e3e6131e6af6de0b3e599bdc7716e3296f0ff1caacd59f905088e5c4ce'
 SHA512:
-  metadata.gz: a7d0af2ca85fd75d51587f513c53f667e77c13b3f407da10fb6463d921e3796ba5b6746fb77e5c5c11c26a700a54e00ee3e805310f98179cf328a858d7496195
-  data.tar.gz: c3a0276b516320e16f54cf3f647e3c6d6ea94625fd2341df6640903a7e5fc64b20c2a9e2b82065cf64519852db0cf2aec35cdc79ddad783852890a123c8e4911
+  metadata.gz: 7d91fe567c067d175cfa3274773e984720384315d2eb8fb790da247ee256706b48e079ba4a4d9e5b909a4e6f480f968574d4526e6d6b80b4e443b57785d9ac36
+  data.tar.gz: e075baf062df84f4567200cfe4d375280dcf5cd9b76aad7d9802d1ae28cc00245982c6604e7e5fea080b15c47cee0644c5f75b7e2468379fc386de985ad1fe45

data/.okf/capabilities/bundles-manager.md

@@ -53,6 +53,17 @@ red. The verdict keeps the [validate/lint separation](validator.md): a curation
 finding is a warning and the bundle stays open, and only a non-conformant bundle
 reads as broken.
 
+A bundle that arrived through a registry [link](../registry.md) is listed,
+mounted and served like any other, and is **read-only**: the file that owns it is
+another registry, so the model refuses `rename`, `remove` and `default` against
+it. The page carries that in both halves, because one without the other is a
+worse page than neither. The row shows `via @onm` and **offers no actions menu** —
+three buttons that can only fail are not a menu — and the request is refused
+anyway if it arrives, since the guard lives in `Registry` rather than here. That
+is the same "hiding a button is a UI, refusing the request is the boundary" split
+the read-only gate above keeps, reached from the other direction: there the
+server declines to write at all, here one row does.
+
 Rows are matched to entries by **directory**, not by slug. A rename changes the
 slug and nothing else, and a row that lost its identity over a rename is the bug
 that avoids.

data/.okf/capabilities/search.md

@@ -225,7 +225,9 @@ even with zero matches — only an invalid `--regexp` pattern, `-e` paired with
 Knowledge rarely lives in one bundle, so search is the one verb that spans the
 [registry](../registry.md): leading @slugs pick bundles explicitly
 (`okf search @handbook @notes auth`), and `@all` is the ref that means every
-registered one. Every row is labeled by its bundle's slug.
+registered one — including the bundles a [link](../registry.md) folds in, since
+those are registered here in every sense that matters to a reader looking for an
+answer. Every row is labeled by its bundle's slug.
 
 **Merged rows are comparable by construction, and each engine earns that
 differently.** The scan's score is absolute — summed field weights, with no

data/.okf/cli.md

@@ -74,21 +74,42 @@ side should not enrol them in the user's durable list. Registering is always the
 explicit act of `okf registry set`.
 
 `registry` is an umbrella verb — `init`, `list`, `set`, `del`, `default`,
-`rename`, `group`, `ungroup` — over one persistent file. `$OKF_HOME` points every
+`rename`, `group`, `ungroup`, `link`, `unlink`, `import` — over one persistent
+file, and it
+is **one row in the map**. It carried ten for a while, which made a third of `okf
+help` about registry management when registry management is not a third of what
+okf does; the row now points at `okf registry --help`, which prints the ten with
+their grammar and the `-g` they share. The map's job is to name the verbs. A verb
+whose own help is the manual is the same progressive disclosure the bundles are
+built on, applied to the CLI's front page — and the row has to *say* the help
+exists, since nothing else tells a reader an umbrella has subcommands at all. `$OKF_HOME` points every
 one of them at a different global registry, which is what keeps the tests off the
 real `~/.okf`; `registry init` and discovery add a [project-local](registry.md#global-by-default-project-local-by-discovery)
 one that replaces it while you stand in its tree, with `OKF_NO_DISCOVERY=1` to
 force the global one.
 
-One lever, not two — and the levers that exist are env vars, never flags. An
-earlier design also carried a `--home DIR` flag, which had to be remembered on the
-three verbs that offered it and forgotten on every other one — a flag whose whole
-job was to name a location the env var already named. `$OKF_HOME` composes where a
-flag cannot: it reaches every verb at once without being typed, it survives into a
-subprocess, and if the directory ever holds more than `registry.json` it keeps
-meaning the same thing. `OKF_NO_DISCOVERY` earns its keep the same way — one signal
-that reaches every verb, so project-local resolution has no per-verb `--global` to
-thread and forget.
+## One lever, not two
+
+A *cross-cutting* lever is an env var, never a flag. An earlier design carried a
+`--home DIR` flag, which had to be remembered on the three verbs that offered it
+and forgotten on every other one — a flag whose whole job was to name a location
+the env var already named. `$OKF_HOME` composes where a flag cannot: it reaches
+every verb at once without being typed, it survives into a subprocess, and if the
+directory ever holds more than `registry.json` it keeps meaning the same thing.
+`OKF_NO_DISCOVERY` earns its keep the same way, and this is still why there is no
+`--global` on `lint`, on `search`, or on the eleven others: a per-verb flag for
+resolution would be fourteen places to thread it and fourteen to forget.
+
+The `registry` umbrella is the exception, and the line is *subject*, not
+convenience. Every other verb takes a bundle and merely happens to resolve a name
+through a registry; `registry`'s argument **is** a registry file. Saying which one
+is therefore an argument to that verb in the way `--as` is, not a lever bolted
+across the CLI — so `-g`/`--global` lives on its subcommands (all but `init`,
+whose whole job is to create a *local* file) and nowhere else. The env var is
+still the right answer for a whole session or a CI job; the flag is the right
+answer for one command, and for the plain fact that a capability reachable only
+through an env var is one most people never discover. Both name the same
+behavior, so neither can drift from the other.
 
 # Every output names its bundle, in the identity the caller used
 

data/.okf/log.md

@@ -1,5 +1,67 @@
 # Update Log
 
+## 2026-08-22
+
+* **The registry can now take a row out of another registry file, and the
+  project-local file has a shorter name.** [`registry
+  import`](/registry.md#import-the-copy-that-owns-what-it-takes) is the opposite
+  trade from `link`: a link holds a live pointer to a whole file and the other
+  side keeps owning what it lends, while an import copies chosen references and
+  hands over ownership. Both are needed because they answer different questions —
+  "compose that repository's curation" against "I want *that one bundle*, here,
+  as mine". Without it the second had one answer: read the path out of `okf
+  registry list -g` and retype it into `registry set`, laundering through the
+  clipboard information already on screen.
+
+  Three decisions did the work. The source is `--from`, not a second meaning for
+  `-g`, because `-g` names the registry acted *on* across all ten sibling
+  subcommands and a verb that names two files should name the second rather than
+  invert the first. Slugs are preserved and a collision **refuses**, which is
+  where import and link deliberately disagree: a linked name was never chosen
+  here so `link_slug` mints around it, an imported one was typed so the "never
+  substitute a name you chose" rule applies in full. And a group brings the
+  groups nested inside it, because recreating a name here that resolved to a
+  larger set there is that same substitution with nothing on screen to reveal it.
+  Everything is validated before anything is written, so an import lands whole or
+  leaves the file byte-for-byte alone — a refusal that already moved three of four
+  rows is not a refusal.
+
+* **`.okf.json` is the project-local registry's name; `.okf-registry.json` is
+  still discovered.** The file is committed, so retiring the old name outright
+  would break every repository carrying one to save eight characters. Both are
+  checked *per directory* on the way up rather than one name swept to the root
+  and then the other, or a legacy file at a repo root would beat a `.okf.json`
+  two levels down and "the nearest one wins" would quietly mean something else.
+  The deprecation note is the `registry` umbrella's alone — the one verb whose
+  subject is a registry file, and the one nobody runs in a loop or pipes into
+  something else, which is exactly what `lint` and `search` are.
+
+## 2026-08-21
+
+* **The [registry](/registry.md) composes other registry files, and its umbrella
+  grew a `-g`.** A repository that curates its own bundles — this one commits a
+  `.okf-registry.json` naming five — could not lend that curation to `~/.okf`
+  without registering every row again by hand and re-syncing forever. `okf
+  registry link <name> <file>` points the global registry at the file instead:
+  its bundles resolve here at read time under their own slugs, `@<name>` is the
+  set, and nothing is copied, so the target goes on owning its rows. Two
+  restrictions carry the whole design. Only the *global* registry follows links,
+  which makes depth one structural rather than enforced — a linked file's own
+  links are never read, so no chain forms and there is no cycle to detect. And a
+  link is read-only: `rename`, `del`, `default`, `set --as` and `group` all
+  refuse a slug it owns, from the `⚙ Bundles` panel as from the terminal, because
+  the guard lives in the model rather than in the [CLI](/cli.md).
+
+  A linked name is minted around a collision rather than refused (`central` →
+  `onm-central`), which is the "implicit is forgiving" rule reaching a name this
+  registry did not choose — and it is the design's one *computed* slug, so
+  `registry list` prints the moved row with the name it carries in its source
+  file. `-g`/`--global` is the smaller half: `OKF_NO_DISCOVERY=1` already forced
+  the global registry, but a lever reachable only through an env var is one most
+  people never find. It is the `registry` umbrella's alone — the one verb whose
+  subject *is* a registry file — so [the env-var rule](/cli.md#one-lever-not-two)
+  keeps its scope rather than losing its edge.
+
 ## 2026-08-19
 
 * **This bundle became okf's own, and holds everything about okf.** It began the

data/.okf/registry.md

@@ -1,7 +1,7 @@
 ---
 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`.
+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, composable through links to other registry files and able to import rows out of them — the kernel behind a bare `okf server`.
 resource: gems/okf/lib/okf/registry.rb
 tags: [cli, shell, registry]
 generated:
@@ -217,7 +217,7 @@ a per-user file, and locking would buy nothing worth the complexity.
 
 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`
+user, shared across every repo. The project-local one is a `.okf.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
@@ -238,12 +238,36 @@ users who set up a project registry. The escape hatch is therefore a per-invocat
 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.
 
+That file was called `.okf-registry.json` first, and both names are still
+discovered — a local registry is *committed*, so retiring the old one outright
+would break every repository carrying it to save eight characters. The two are
+checked **per directory** on the way up, not one name swept to the root and then
+the other: otherwise a legacy file at a repo's root would beat a `.okf.json` two
+levels down, and "the nearest one wins" would quietly mean something else. Inside
+one directory the short name wins.
+
+The deprecation is said **once, by the `registry` umbrella, and nowhere else**.
+That verb is the one whose subject *is* a registry file and the one nobody runs in
+a loop or pipes into something, which is exactly what `lint` and `search` are — a
+note there is noise people learn to redirect away rather than act on. A legacy
+file that is in force gets the one move that retires it; a legacy file sitting
+beside the `.okf.json` that beat it gets named too, because reading one while the
+other lies there unread is a silent wrong answer unless somebody says so.
+
+`-g`/`--global` is that same signal spelled as an argument, and it is the
+`registry` umbrella's alone (see [the CLI](cli.md#one-lever-not-two)). It exists
+because a lever reachable only through an env var is a lever most users never
+find — and the umbrella is the one verb whose *subject* is a registry file, so
+naming which file to act on is an argument to it rather than a flag bolted onto
+fourteen unrelated verbs. `init` is the exception that proves it: its whole job is
+to create a *local* file, so `-g` there names nothing and is refused.
+
 # 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
+to the `.okf.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
@@ -257,6 +281,149 @@ 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 -->
 
+# Links: the global registry composes other registry files
+
+A **link** is a pointer from the global registry to another registry file. That
+file's bundles resolve through the pointer at read time, under their own slugs,
+and nothing is copied — the same "stores references, never content" rule the
+entries keep, one level up. `okf registry link onm ~/ONM/registry.json` and
+`@onm-central` (or whatever slugs that file holds) answer here; the link name
+itself resolves as a group over exactly its bundles, so `@onm` is the set.
+
+The case it exists for is **a repository that already curates its own bundles**.
+This repo commits a `.okf.json` naming five; before links, using them
+from `~/.okf` meant registering all five again by hand and re-syncing whenever
+the repo's list changed. A link points at the file the repo already maintains, so
+the curation is composed rather than duplicated, and it keeps resolving its own
+relative paths because the target is anchored on its own directory — exactly as
+it would from inside that checkout. Two registry files stop being two worlds you
+switch `$OKF_HOME` between and become one view.
+
+**Only the global registry follows links.** A project-local one parses them and
+preserves them across a write, but never resolves them — and that single
+restriction is the whole depth rule. A linked file's own links are not read, so
+no chain forms, no prefix compounds, and there is no cycle to detect. The
+alternative was transitive resolution, and it fails on ownership rather than on
+effort: the target is a file this registry does not own, so a cycle-check at
+write time goes stale the moment someone adds a link back on the other side.
+Transitivity would move cycle detection from write time — cheap, one file,
+refusable — to read time, across N files, with nobody to blame. The groups above
+nest safely for exactly the reason links do not: every member lives in one file,
+behind one guard.
+<!-- rule:okf-registry-links-global-only -->
+
+# A linked name is minted around a collision, never refused
+
+A slug arriving from a linked file answers to itself when the name is free, and
+to `<link>-<slug>` when it is not (`-2` beyond that, through the same `dedupe` a
+basename goes through). That is the [implicit is forgiving, explicit is
+strict](#slugs-implicit-is-forgiving-explicit-is-strict) table one row wider, and
+the row falls on the forgiving side for the reason the table gives: a name in
+someone else's file was never *chosen* here, so inventing around it is licensed —
+while refusing would let one foreign row take down an entire link. The link
+*name* is the strict half, and is refused on collision like any `--as`: you typed
+that one.
+
+Precedence is fixed so the derivation is reproducible: the registry's own bundles
+always win the bare name, and between links the file's order decides. Both are
+position, which is state the registry already keeps — the same reason the
+[default](#the-default-is-a-position-not-a-stored-name) is one.
+
+What this costs, and it is the design's one genuinely computed name: a slug can
+*move* when an unrelated link is added. Everything else in this file is stable in
+the file. The mitigation is disclosure rather than a mechanism — `registry link`
+says what it moved as it writes, and `registry list` prints the moved row with the
+slug it carries in its source file (`onm-central … [central]`), which is the only
+place a shifted ref is visible. Linked entries also append **after** the local
+ones, so while this registry owns any bundle at all the default stays local.
+
+**A linked group is listed with the rest, not beside them.** `groups_listing`
+returns this registry's own groups first, then the linked ones, each carrying the
+`link` it came from — one list, because `group?` *resolves* a linked group and a
+listing that named only the local half would answer about a smaller set than the
+same object can resolve. That gap is invisible at the call site and inherited by
+every consumer: `okf-mcp`'s `list_bundles` and the TUI's groups view both read
+this one method, and both would have hidden a group they could already open. A
+caller that wants only the groups it may edit filters on `link` — which is the
+question they are actually asking, and it is now askable.
+
+# A link is read-only, and the refusal lives in the model
+
+`rename`, `del`, `default`, `set --as` and `group` all refuse a slug a link owns,
+with a message naming the file that does own it and the `unlink` that would drop
+it. Two of those are worth their own line. A **group** may not hold a linked slug:
+a group stores names, and a linked name lives only while its link resolves, so
+holding one would dangle the group the moment the link goes — the foreign key the
+default rule already refused. And **`registry set` on a directory a link already
+carries** is refused rather than quietly adding a twin, because entries are
+identified by path and the path is already spoken for.
+
+The third was a hole this rule had left open, and it failed in the worst
+available way. A group's slug is its *update* path everywhere else — `registry
+group backend @more` adds to the existing one — so `group onm @alpha`, naming a
+link or a group that came with one, took that path: it merged the member, printed
+`grouped onm → …`, and lost it, because `write` persists only the groups this
+registry owns. A refusal is the fix, but the shape is what matters: a write that
+reports success and does not happen is worse than one that raises, and it was
+reachable from the CLI, the TUI and the browser panel alike.
+
+The refusals live in this class, not in the [CLI](cli.md), and that placement is
+load-bearing: the graph page's ⚙ Bundles panel posts into these same methods
+([bundles manager](capabilities/bundles-manager.md)), so a guard one layer up
+would leave the browser doing what the terminal refuses. A link whose target has
+gone or cannot be parsed is *reported* — `(missing)`, `(unreadable)` — and
+resolves to nothing, the same tolerance a vanished bundle directory gets, because
+one dead pointer must not take down the registry that holds it.
+
+# Import: the copy that owns what it takes
+
+`okf registry import <@slug…>` copies chosen bundles — and the groups that hold
+them — out of another registry file into the one in force. It is the **opposite
+trade** from a link, and the pair is the point:
+
+| | link | import |
+| --- | --- | --- |
+| what moves | nothing; a pointer | the reference, copied |
+| scope | the whole target file | the slugs you name |
+| ownership | the target keeps it, read-only | yours, editable |
+| freshness | live on every read | a snapshot |
+
+Copying a *reference* is not copying content, so the rule at the top of this file
+still holds: the bundle stays in the repository that owns it, and what lands here
+is the same path-and-name row `registry set` would have written. What import saves
+is the laundering. The scenario is standing inside a repo, running `okf registry
+list -g` to see what the global registry holds, and wanting one of them here — the
+path is already on screen, and without this verb the only way to move it is
+through the clipboard.
+
+The source is `--from`, defaulting to the global registry, which inside a repo is
+the only other one you have. It is a second flag rather than a second meaning for
+`-g` because [`-g` names the registry acted *on*](cli.md#one-lever-not-two) on
+every other subcommand; this verb names two files, so the second gets its own
+name rather than inverting the first.
+
+**A collision refuses.** This is where import and link disagree, and the
+disagreement is the slug rule, not an inconsistency: a linked name was never
+chosen here, so it is [minted around](#a-linked-name-is-minted-around-a-collision-never-refused);
+an imported name lands in *this* file because you typed it, so it is refused
+exactly as `rename` refuses. The gem may invent a name it made up; it may not
+substitute one you chose. A bundle already registered here under a different name
+refuses too, and *first* — when both are true, "that bundle is already here as
+@docs" is the answer and "the name is taken" is only the symptom.
+
+**A group brings everything it reaches**, including a group nested inside it.
+Recreating a name here that resolved to a larger set there would be that same
+quiet substitution, with nothing on screen to reveal it. Members are stored
+verbatim, which is the payoff of preserving slugs: a name means the same thing on
+both sides, so there is nothing to remap — the work `fold_linked_bundles` must do
+precisely because a link mints its names.
+
+**Nothing is applied until everything is checked.** Every ask is resolved and
+refused against the current state first, then one `write` publishes the lot. Half
+an import is a registry the user has to unpick by hand, reported as a success —
+and a refusal that already moved three of four rows is not a refusal.
+<!-- rule:okf-registry-import-all-or-nothing -->
+
 # It costs an embedding app nothing
 
 `require "okf"` does not load it. The registry is reached only from the

data/.okf/structure/the-cli.md

@@ -23,7 +23,7 @@ And one file per verb, each registering itself at load:
 | `lib/okf/cli/skill.rb` | `skill` |
 | `lib/okf/cli/server.rb` | `server` |
 | `lib/okf/cli/render.rb` | `render` |
-| `lib/okf/cli/registry.rb` | `registry` and its eight subcommands |
+| `lib/okf/cli/registry.rb` | `registry` and its eleven subcommands |
 | `lib/okf/cli/lint.rb` | `lint` |
 | `lib/okf/cli/loose.rb` | `loose` |
 | `lib/okf/cli/validate.rb` | `validate` |

data/.okf/structure/the-disk-shell.md

@@ -50,17 +50,26 @@ logic belongs instead.
 
 `Registry` is the `@slug` layer. `HOME_ENV`/`DEFAULT_HOME` is the global
 registry under `$OKF_HOME` (default `~/.okf`); `LOCAL_FILE` is the project-local
-`.okf-registry.json` that `discover` finds by walking up from the working
+`.okf.json` (or the legacy `.okf-registry.json`) that `discover` finds by walking up from the working
 directory. **A discovered local registry replaces the global one outright** — it
 does not merge — and `NO_DISCOVERY_ENV` (`OKF_NO_DISCOVERY=1`) is the escape
 hatch that forces the global one, which is what a test that must not see the
-developer's registry sets.
+developer's registry sets. `Registry.load`'s `follow_links:` is the same
+decision one step further: it is true only for the global registry, so a local
+one parses links and never resolves them.
 
 `relative_base` is why a local registry's paths stay relative and the file
 travels with the repository. `Registry#reopen` preserves it; `Registry.new(path)`
 does not, and reaching for the latter is how a reload comes to resolve every
 bundle against the wrong base.
 
+`Link` points the global registry at another registry file; `resolve_links`
+folds that file's bundles in (through `link_slug`, which prefixes only on a
+collision) and `refuse_linked` is the single guard every write goes through —
+here rather than in the CLI, because the server's bundles panel calls these same
+methods. `open_linked` constructs the target with `follow_links: false`, which is
+the whole of the depth rule.
+
 `Group` is a named, recursive set of bundles. `RESERVED_SLUGS` is `all`, because
 `@all` means every bundle and may not be shadowed. `slugify`, `dedupe`,
 `normalize` and `path_shaped?` are the naming rules a `registry set` goes

data/.okf/testing/adding-a-verb.md

@@ -11,7 +11,7 @@ resource: lib/okf/cli/command.rb
 
 # Before adding one, check it is not already there
 
-Seventeen commands and eight subcommands already exist, catalogued in
+Seventeen commands and eleven subcommands already exist, catalogued in
 [cli](/cli.md) and [read-views](/capabilities/read-views.md), and `okf help`
 prints the same list. Most of what a new verb would want is a *flag* on an
 existing view rather than a view of its own: the shared filters and projections

data/CHANGELOG.md

@@ -5,6 +5,111 @@ 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.2.0] - 2026-08-22
+
+### Added
+
+- **`okf registry import <@slug…> [--from FILE]` — copy chosen bundles out of
+  another registry file into the one in force, where they become yours.** It is
+  the opposite trade from `link` and the pair is the point: a link holds a live
+  pointer to a whole file and the other side keeps owning what it lends, while an
+  import copies chosen references and hands over ownership, so what lands renames,
+  defaults and groups like anything you registered by hand. The case it exists for
+  is standing in a repo, running `okf registry list -g`, and wanting one of the
+  bundles it shows — before this the only way to move it was to read the path off
+  the screen and retype it into `registry set`.
+
+  The source is `--from`, defaulting to the global registry, because `-g` goes on
+  meaning the registry acted *on*, as it does on every sibling subcommand. A group
+  ask brings its members and any group nested inside it, recreated under the same
+  names. Slugs are preserved, so a collision **refuses** (`--as` renames a single
+  ask) rather than being minted around the way a linked name is — a linked name was
+  never chosen here, an imported one was typed. A bundle already registered here
+  under another name refuses first, naming that name. Every ask is validated before
+  anything is written, so an import lands whole or leaves the file byte-for-byte
+  alone.
+
+- **`.okf.json` is the project-local registry's filename.** `okf registry init`
+  writes it, and it is what the docs now name. The older `.okf-registry.json` is
+  **still discovered**, so no committed registry breaks: both names are checked in
+  each directory on the way up — per directory, not one name swept to the root and
+  then the other, or a legacy file at a repo's root would beat a `.okf.json` two
+  levels down and "the nearest one wins" would mean something else. Within one
+  directory the short name wins, and a legacy file left beside it is named on
+  stderr rather than silently ignored.
+
+  The deprecation note is the `registry` umbrella's alone, and it is one stderr
+  line: that verb's subject *is* a registry file, and it is not the one people run
+  in loops or pipe into something else, which is exactly what `lint` and `search`
+  are. Renaming is `git mv .okf-registry.json .okf.json`, and the note says so. One
+  transitional cost worth naming: a checkout renamed to `.okf.json` is invisible to
+  an installed okf older than 2.2.0, which will fall back to the global registry
+  until that install is upgraded.
+
+- **`okf registry link <name> <file>` — the global registry points at another
+  registry file, and that file's bundles resolve here.** Nothing is copied: the
+  target keeps owning its rows, so an edit there shows on the next read. The case
+  it exists for is a repository that already curates its own bundles in a
+  committed `.okf-registry.json` — a link composes that curation instead of
+  duplicating it, and the target resolves its own relative paths exactly as it
+  would from inside that checkout. A linked bundle answers to its own slug, or to
+  `<name>-<slug>` when the name is already taken here; `@<name>` resolves as a
+  group over the set; `okf registry unlink <name>` drops it.
+
+  Links are the **global** registry's alone. A project-local one parses them and
+  never resolves them, which is what makes depth one structural — a linked file's
+  own links are never followed, so no chain forms and there is no cycle to guard.
+  A link is read-only: `rename`, `del`, `default`, `set --as` and `group` refuse a
+  slug it owns, naming the file that does, from the browser's ⚙ Bundles panel as
+  from the terminal. A target that has gone or cannot be parsed is listed
+  `(missing)`/`(unreadable)` and resolves to nothing, rather than taking down the
+  registry holding it.
+
+- `registry group` and `registry ungroup` refuse a group a link brought in —
+  the link's own set, or one the linked file curates. Naming one took the
+  update path, reported `grouped …`, and discarded the change on the next read,
+  because only the groups this registry owns are written. A write that reports
+  success and does not happen is worse than one that raises.
+
+- **`-g`/`--global` on every `registry` subcommand but `init`.** It forces the
+  `$OKF_HOME` registry for one command, so `okf registry list -g` reads the global
+  one from inside a repo carrying its own, and `okf registry set <dir> -g`
+  registers there without leaving. `OKF_NO_DISCOVERY=1` already did this for a
+  whole session and still does; the flag exists because a lever reachable only
+  through an env var is one most people never find. It stays on the `registry`
+  umbrella — the one verb whose subject *is* a registry file — and nowhere else.
+
+- The graph page's ⚙ Bundles panel marks a linked row `via @onm` and **offers no
+  actions menu** on it. Rename, Remove and Default are all refused for a linked
+  bundle, so the menu could only have produced three errors. The request is
+  refused whether or not the button exists — the guard is in `Registry`, not in
+  the page — which is the same split the read-only server already keeps: hiding
+  a control is a UI, refusing the request is the boundary.
+
+- **`okf help` shows one `registry` row instead of ten, and `okf registry --help`
+  prints the subcommands.** Ten rows for one verb made a third of the map about
+  registry management, and the map is there to name the verbs rather than to be
+  every verb's manual. The row names the help that replaces it, since nothing
+  else tells a reader an umbrella has subcommands. A bare `okf registry` still
+  lists the registry, and `okf registry <command> --help` still answers for that
+  command.
+
+### Changed
+
+- `okf registry list --json` groups now carry a `link` key — `null` for a group
+  this registry owns, the link's name for one that arrived through a link.
+  `Registry#groups_listing` returns both kinds in one list, own groups first,
+  because `#group?` resolves a linked group and a listing that named only the
+  local half would answer about a smaller set than the same object can resolve —
+  the drift every library consumer would inherit silently. A caller that wants
+  only the editable groups filters on `link`.
+
+- `okf registry list --json` gains a `links` array, and each bundle row gains
+  `link` (the link it arrived through, `null` when the registry owns it) and
+  `origin` (its slug in that file, differing only where a collision moved the
+  name). The on-disk registry gains a `"links"` key, written empty when there are
+  none; an older file with no such key reads unchanged.
+
 ## [2.1.1] - 2026-08-20
 
 ### Fixed

data/README.md

@@ -131,6 +131,8 @@ okf graph     <dir|@slug> [--hubs] [--traffic]   # the raw graph; --hubs ranks c
 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
+okf registry  link | unlink   <name> <file>      # fold another registry file's bundles in
+okf registry  import <@slug…> [--from FILE]      # copy bundles out of another registry into this one
 okf skill     <dest>                             # install the companion agent skill
 okf --version
 ```
@@ -173,17 +175,44 @@ 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
+`.okf.json` in the current directory (the older `.okf-registry.json` is still
+discovered, and `okf registry` says so once so you can `git mv` it); 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.
+bundles with no `$OKF_HOME` setup. The nearest registry wins; `-g` on any
+`registry` subcommand reaches the global one for a single command (`okf registry
+list -g`, `okf registry set ./docs -g`), and `OKF_NO_DISCOVERY=1` does it for a
+whole shell.
 
 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.)
 
+A repository that already curates its own bundles can lend that list rather than
+have it copied. `okf registry link onm ~/ONM/.okf.json` points the global
+registry at another registry file: its bundles resolve under their own slugs,
+`@onm` names the set, and nothing is duplicated — edit the other file and the
+change shows on the next read. They are read-only from here, since the file that
+owns them is elsewhere.
+
+```bash
+okf registry link okf ~/code/okf/.okf.json           # that repo's own curation, composed
+okf search @all rate limit                            # now spans both files
+```
+
+When you want one bundle rather than a whole file, `import` is the opposite
+trade — it copies the reference, and what lands is yours to rename, default and
+group. The source is `--from`, defaulting to the global registry, which inside a
+repo is the only other one you have. A group ask brings its members with it,
+slugs are preserved (a collision refuses rather than being renamed behind your
+back), and nothing is written unless every ask checks out.
+
+```bash
+okf registry list -g                 # what does the global registry hold?
+okf registry import handbook specs   # take those two, here, as mine
+```
+
 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

data/lib/okf/cli/command.rb

@@ -577,12 +577,17 @@ module OKF
 
       # The registry a verb resolves against — the single seam that opts the CLI
       # into discovery. `cwd: Dir.pwd` is what makes OKF::Registry.load walk up for
-      # a project-local .okf-registry.json; a library caller passing no cwd stays
+      # a project-local .okf.json; a library caller passing no cwd stays
       # global-only. The registry subcommands and `server` open through here too,
       # so a bare `okf server` inside a repo serves that repo's bundles.
-      def open_registry
+      # +global+ forces the $OKF_HOME registry by withholding the cwd discovery
+      # needs — the per-command form of OKF_NO_DISCOVERY, and the only thing
+      # `okf registry -g` does. It is an argument to the `registry` verb rather
+      # than a flag on all fourteen, because that verb's *subject* is a registry
+      # file; every other verb keeps inheriting the env var's one signal.
+      def open_registry(global: false)
         require "okf/registry"
-        OKF::Registry.load(cwd: Dir.pwd)
+        OKF::Registry.load(cwd: global ? nil : Dir.pwd)
       end
 
       # Resolve one @ref through the active registry — a discovered project-local