okf-tui 1.0.0 → 1.1.0

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

@@ -0,0 +1,58 @@
+---
+type: Playbook
+title: Adding a View, a Key, or a Panel
+description: The steps a new screen owes, in order — where the builder goes, which tables it joins, what the frame test must assert, and the catalogue entry the pin will demand.
+tags: [testing, playbook, views]
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# Before you add a view, try not to
+
+Six is the whole tab bar, and a seventh is a real cost on every screen. One view
+has already been withdrawn for not earning its tab: the `index` map, because
+browse answered the same question with a key the reader already had. Check
+[the catalogue](/capabilities/views.md) first.
+
+The same instinct applies one level down: a new *number* on an existing screen
+usually belongs in okf, not here — [invents-no-analysis](/decisions/invents-no-analysis.md).
+
+# The walk
+
+1. **Write the failing test first**, in `test/integration/`, headless. It renders
+   a frame and asserts what is in it. Run it: it must fail for the reason you
+   predicted. And prove the assertion can fail at all — a frame test that passes
+   against the *old* code is asserting nothing. See
+   [headless-frames](/testing/headless-frames.md).
+2. **Build rows, not output.** The builder goes in `views.rb` and returns an
+   array of strings; it may not touch the terminal. Anything that measures or
+   cuts a string goes through `ui.rb`, never `String#length` —
+   [ansi-aware-width](/rendering/ansi-aware-width.md).
+3. **Join the tables in `app.rb`.** `TABS` (order matters — `help` stays last)
+   and `KEY_VIEWS`. Then decide the two behaviours: is it a
+   `SINGLE_BUNDLE_VIEW` (follows the active bundle) or scope-wide? Is it a
+   `CONTENT_VIEW` (a scrolling page) or a list? Is it a `FILTERABLE_VIEW`?
+4. **Ask the reader, don't compute.** `Model` is memoized and already answers
+   most of it — [the-workspace](/structure/the-workspace.md) has the table. If
+   the answer isn't there, the question is probably okf's.
+5. **A destructive action gets a `Prompt`.** Every registry write asks first,
+   and the write itself goes through `Workspace` and nowhere else —
+   [registry-write-boundary](/decisions/registry-write-boundary.md).
+6. **Esc must peel exactly one layer.** A new mode adds a layer to that stack;
+   [esc-peels-one-layer](/interaction/esc-peels-one-layer.md) is the rule it has
+   to obey.
+7. **Update the catalogue** — [capabilities/views](/capabilities/views.md). This
+   is not etiquette: `test/unit/bundle_catalog_test.rb` compares that table
+   against `App::TABS`, so the suite is red until you do. A new file under
+   `lib/` needs its line in [structure/](/structure/) for the same reason.
+8. **Run the same test unedited**, then the geometry suite — it runs twice, at
+   two widths, and that is where a row that fits in ASCII and overflows in colour
+   shows up.
+
+# What the suite structurally cannot catch
+
+One pty test proves the binary boots and nothing else ([pty-test](/testing/pty-test.md)),
+and a local run cannot see the dependency resolution that only the matrix
+exercises ([ci-matrix](/testing/ci-matrix.md)). Neither is a gap to fill with
+more headless tests; they are different questions.

data/.okf/testing/ci-matrix.md

@@ -3,7 +3,14 @@ type: Runbook
 title: The CI Matrix and What Only It Catches
 description: Ten Rubies on every push, what only the 2.4 container proves, and the resolution gap the matrix cannot see because every run resolves the sibling checkout.
 tags: [testing, ruby-floor, dependencies]
-timestamp: 2026-07-19
+generated:
+  by: human:maintainer
+  at: 2026-07-19
+sources:
+  - title: "The repository's `.github/workflows/main.yml`, `okf-tui` job."
+    resource: https://github.com/serradura/okf/blob/main/.github/workflows/main.yml
+  - title: "`AGENTS.md` — the scripted `Gemfile.ci-check` run against the published okf."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/AGENTS.md
 ---
 
 # The matrix
@@ -73,8 +80,3 @@ Two details keep that reproduction honest:
   something no user has. Drop the lockfile in the copy, exactly as the Docker
   command above drops it for its own reason (a lockfile written by a modern
   Bundler is one 2.4's cannot read).
-
-# Citations
-
-[1] The repository's `.github/workflows/main.yml`, `okf-tui` job.
-[2] `AGENTS.md` — the scripted `Gemfile.ci-check` run against the published okf.

data/.okf/testing/headless-frames.md

@@ -3,7 +3,12 @@ type: Playbook
 title: Testing Frames Without a Terminal
 description: How the suite drives real interactions and asserts on real frames with no pty — and the discipline of proving each check can actually fail.
 tags: [testing, rendering]
-timestamp: 2026-07-19
+generated:
+  by: human:maintainer
+  at: 2026-07-19
+sources:
+  - title: "`test/test_helper.rb` — `FixedScreen`, `with_registry`, `app_for`, `frame_for`, `keystrokes`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/test_helper.rb
 ---
 
 # The shape
@@ -67,8 +72,3 @@ Two things, each covered elsewhere because no headless frame can reach them:
   [the pty test](/testing/pty-test.md);
 - anything that depends on which okf actually resolves, since the Gemfile prefers
   the sibling checkout locally — that is [the CI matrix](/testing/ci-matrix.md).
-
-# Citations
-
-[1] `test/test_helper.rb` — `FixedScreen`, `with_registry`, `app_for`,
-    `frame_for`, `keystrokes`.

data/.okf/testing/index.md

@@ -3,6 +3,8 @@
 How a full-screen terminal app is proven, and what each layer can and cannot
 catch.
 
+* [The Suite — Its Layers, and the Two Fixtures That Exist to Bite](the-suite.md) - What each test file proves, and the two fixtures built to reach a branch nothing else could.
 * [Testing Frames Without a Terminal](headless-frames.md) - Driving real interactions headlessly, and the discipline of proving a check can fail.
 * [The One Test That Opens a Terminal](pty-test.md) - The single pty walk, and the three timing traps that made it flake on the floor.
 * [The CI Matrix and What Only It Catches](ci-matrix.md) - Ten Rubies, the Docker floor check, and the dependency bug a local run cannot see.
+* [Adding a View, a Key, or a Panel](adding-a-view.md) - The steps a new screen owes, and the catalogue entry the pin will demand.

data/.okf/testing/pty-test.md

@@ -3,7 +3,12 @@ type: Runbook
 title: The One Test That Opens a Terminal
 description: A single pty test boots `okf tui` in a real process and walks every view, and the three timing traps that made it flake on the Ruby floor.
 tags: [testing, terminal, scar-tissue]
-timestamp: 2026-07-18
+generated:
+  by: human:maintainer
+  at: 2026-07-18
+sources:
+  - title: "`test/integration/terminal_test.rb` — `SCRIPT`, `settle`, `reap`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/terminal_test.rb
 ---
 
 # Why it exists
@@ -67,7 +72,3 @@ the escape sequences before it do not.
 `"\t\r"` in a single write can reach the reader as a *single* keypress. Split
 control keys into separate steps — a race the test loses only sometimes is worse
 than one it loses always.
-
-# Citations
-
-[1] `test/integration/terminal_test.rb` — `SCRIPT`, `settle`, `reap`.

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

@@ -0,0 +1,120 @@
+---
+type: Component
+title: The Suite — Its Layers, and the Two Fixtures That Exist to Bite
+description: "What each test file proves, why `nested` and `provenance` were built when twelve fixtures already existed, and the two gaps between this suite and the okf a user actually resolves."
+tags: [testing, fixtures, structure]
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# Integration first
+
+`test/integration/` is the critical layer: it drives the app the way a user does
+— real keys, real frames, real exit codes. A unit test proves a method behaves;
+an integration test proves the *product* behaves.
+
+```
+test/
+  test_helper.rb              OKF::TUI::TestCase: app_for, render, with_registry,
+                              with_local_registry
+  fixtures/                   bundles chosen for their standing, not their size
+    nested/                   the only one whose directories nest — see below
+    provenance/               the only v0.2 one, §5 declared and withheld — below
+  integration/
+    geometry_test.rb          every row is exactly the terminal width
+    browse_test.rb            reading order, rendering, find-in-body
+    search_test.rb            deferred search, focus, escalation, the held corpus
+    graph_test.rb             facets, and following a concept out
+    dirs_test.rb              okf's directory set, and the dir facet
+    structure_test.rb         hubs and dir traffic, against okf's own numbers,
+                              and health's two panes
+    groups_test.rb            registry groups, and scoping a search to one
+    refs_test.rb              @slug / @group, and which registry resolves them
+    provenance_test.rb        §5 on screen, and what a v0.1 bundle is spared
+    signals_test.rb           health colours, the tab flag, the filters
+    cli_test.rb               argv, streams, exit codes — CLI.run driven straight
+    plugin_test.rb            `okf tui` through okf's registry, and that the
+                              dispatcher adds nothing but the streams
+    terminal_test.rb          `okf tui` in a real process, through a real pty —
+                              the only test that walks process boot + discovery
+  unit/
+    gemspec_test.rb           the declared okf floor tracks the kernel next door
+    packaging_test.rb         LICENSE.txt and NOTICE ship, real files, unchanged
+    bundle_catalog_test.rb    this bundle against the code it describes
+```
+
+The three unit tests are there because their claims are about the *package* and
+the *documentation*, not the app — no integration test can reach them.
+
+# The two fixtures built to reach a branch nothing else could
+
+**`fixtures/nested` exists because every other fixture is one level deep**, and
+at one level `dir` and `top_dir` are the same string — so an assertion against
+them passes whichever field the code reads, which is exactly how the `area`
+break survived. It carries a real tree, an intermediate directory holding no
+concepts of its own (`platform/`), and a directory whose only file is a `log.md`
+(`history/`) — the two shapes okf 1.13.0 had to fix its own directory set for.
+Six directories against three top-level ones: reach for it for anything about
+`dir`, depth, or traffic.
+
+**`fixtures/provenance` is the only v0.2 bundle**, and it carries a concept that
+declares no §5 family (`untouched.md`) beside four that do — deliberately, so
+the suppression rule is a property of the *concept* rather than of the fixture,
+and one test can assert both halves against one bundle. Its numbers are chosen
+to bite: three of its four `unverified` concepts are claimable, so a trust facet
+counting the whole tally would say 4 and narrow to 3. Reach for it for anything
+about trust, status, `generated`, `stale_after` or `sources`; reach for a v0.1
+fixture to prove the same surface stays *absent*.
+
+Keep both conformant and lint-clean, so they stay usable by the health tests.
+Provenance's one `info` is the legacy `timestamp:` on `untouched.md`, which is
+the §13.1 lift under test.
+
+# Run with colour on, not just off
+
+Pastel disables colour when stdout is not a terminal, so a piped test exercises
+none of the ANSI-aware width, clipping and wrapping code — the paths most likely
+to be wrong are exactly the ones a naive capture cannot see. `geometry_test` runs
+both modes; `browse_test` forces colour for the render sweep.
+
+That is not thoroughness for its own sake: the `IndexError` in
+[markdown-rendering-trap](/rendering/markdown-rendering-trap.md) rendered
+perfectly in every uncoloured test.
+
+# No suite here runs the okf a user gets
+
+The `Gemfile` resolves okf from `../okf`, and in the monorepo that checkout is
+always there — so the local run, CI, and the 2.4 container all exercise
+*unreleased* okf. That is the right default: it lets a kernel change be driven
+from the UI without a release. It also leaves a checkout-versus-RubyGems gap.
+
+Two things stand in that gap, covering different halves.
+`test/unit/gemspec_test.rb` is the standing one: it fails the moment okf bumps
+and the gemspec floor does not follow. And a run against the *published* okf
+catches the rest — a released kernel resolves different analysis output, which
+is a difference no floor expresses.
+
+The disagreement it catches is silent: okf's lint findings on
+`fixtures/okf-docs` have changed between releases before, which is enough to
+change how many rows the health view has. **A test whose premise depends on
+okf's analysis output can pass here and fail there** — the health scroll tests
+did exactly that, proving a pane overflowed by leaning on a lint count. Prove a
+rendering property from geometry (a terminal too short to fit) and let the
+agreement tests be the place okf's numbers are asserted.
+
+# Two assertion traps this suite has already hit
+
+* **A check that crashes tells you less than one that fails.** When an
+  assertion's subject can be nil because the thing under test broke, report that
+  and skip the dependents rather than raising `NoMethodError` from the middle.
+* **Judge a rendered offset against the window the view actually used.** An
+  earlier version compared a scroll against a different window size and reported
+  a failure that was not one.
+
+And one naming rule: **name things, do not count them.** The browse list holds
+reserved files as well as concepts, so `<down><down><down>` is a guess about
+ordering. `open_concept("overview")` is a statement about which concept is open.
+
+For the 2.4 container, **read its output, not its exit status** — piping it
+through `tail` returns `tail`'s status, which is zero however the run went.

data/CHANGELOG.md

@@ -5,6 +5,99 @@ 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.1.0] - 2026-08-22
+
+### Added
+
+- **Linked bundles are marked read-only, and the config keys refuse before the
+  prompt.** okf's global registry can now `link` another registry file, and that
+  file's bundles and groups resolve into the bundles view. Browsing one is
+  browsing a bundle, so they list, load, scope and search like any other — but
+  the file that owns them is elsewhere and okf refuses every write against one.
+
+  `d`, `n`, `x` and `+` now say so *before* asking. Without this the ask went
+  through, okf raised, and the message reached the status line only after the
+  user had typed a new name or confirmed a removal. The bundle detail carries
+  `read-only — linked from @onm` and the owning file underneath; the registry
+  pane is left alone, because 42 columns cannot take another marker without
+  clipping.
+
+  Nothing else changed to show linked bundles at all: the entries come from
+  okf's `listing` and the groups from its `groups_listing`, both of which fold
+  the linked half in. `Entry#link` and `Group#link` are read straight off those
+  rows, and the suite asserts that agreement against okf rather than a fixture.
+
+### Changed
+
+- **The project-local registry is now `.okf.json`.** The TUI reads whichever file
+  okf resolves, so this needed no code change — but it is what the header prints
+  and what the "nothing to show" message names, so the file you see identified
+  there has a new name. The older `.okf-registry.json` is still discovered, both
+  names checked in each directory on the way up, so a repository carrying one
+  keeps working untouched. `okf registry init` writes the short name.
+
+- **The `okf` floor moves to 2.2.0**, the kernel that ships `registry link`
+  (`Registry#links_listing`, and the `link` key on listing and group rows).
+  Against 2.1.1 those read as *nil* rather than raising, so a linked bundle would
+  simply never be marked read-only and the four config keys would stop refusing —
+  silent, which is the drift this gem's floor exists to turn into a resolution
+  failure.
+
+## [1.0.1] - 2026-08-20
+
+### Fixed
+
+- **The package metadata follows the `gems/` move and the repository rename.**
+  Two URLs on the package page were about to be wrong at once. `changelog_uri`
+  named `blob/main/okf-tui/CHANGELOG.md`, a path that stopped existing when the
+  four gems moved under `gems/`; `homepage` named `serradura/okf-gem`, and the
+  repository is now **`serradura/okf`** — the name the command has had all
+  along. rubygems.org serves whatever the last release published, so neither
+  corrects itself: only a release republishes metadata, and this is that
+  release. Both land in one round rather than two, which is the whole reason
+  the rename waited for the paths to stop moving.
+
+  `homepage_uri`, `source_code_uri` and `changelog_uri` are all derived from
+  `homepage`, so one line moves four pieces of this gem's metadata. GitHub
+  redirects the old URLs permanently, so anything already published keeps
+  resolving.
+
+### Changed
+
+- **The gem's own bundle is now OKF v0.2.** It was the last one in the tree on
+  v0.1. Its 30 concepts moved `timestamp:` under `generated: { by, at }`, and
+  the 22 carrying a body `# Citations` list moved that provenance into
+  `sources:` — every entry keeping its text, with a GitHub URL where it named a
+  real file. The three concepts using positional `[1]` markers were rekeyed to
+  `[^1]` footnotes, which is what §5.1 asks for. `okf validate` and `okf lint`
+  are both clean on it.
+
+### Added
+
+- **The bundle carries the structure and the catalogue, and a test pins them.**
+  `.okf/structure/` names every file under `lib/`, grouped by the layer that
+  owns it; `.okf/capabilities/` is the catalogue of the six views and the kernel
+  surface behind them; `.okf/testing/the-suite.md` is what each test file proves
+  and why the two special fixtures exist; `.okf/testing/adding-a-view.md` is the
+  walk a new screen owes. `test/unit/bundle_catalog_test.rb` fails when a file
+  under `lib/` is named by no concept, when a concept names a file that is gone,
+  or when the view catalogue and `App::TABS` disagree. `AGENTS.md` kept the
+  contracts and the commands and now routes here for the rest — its
+  hand-maintained Map of `lib/**` was the thing nothing checked.
+
+### Fixed
+
+- **Three `AGENTS.md` paths pointed at directories that no longer exist** —
+  `cd /build/okf-tui`, `cd okf-tui`, and `working-directory: okf-tui`, all from
+  before the gems moved under `gems/`.
+
+### Changed
+
+- **The okf floor moves to `>= 2.1.1, < 3`** — the kernel this gem develops
+  against released 2.1.1, and the floor tracks what the suite proves against
+  (the gemspec drill enforces equality as the normal state). Nothing here calls
+  a 2.1-only surface; the ceiling is unchanged.
+
 ## [1.0.0] - 2026-08-15
 
 First release.
@@ -236,4 +329,5 @@ First release.
   turns the next one into a resolution failure a maintainer sees instead of a
   wrong number a reader believes.
 
-[1.0.0]: https://github.com/serradura/okf-gem/releases/tag/okf-tui/v1.0.0
+[1.0.1]: https://github.com/serradura/okf/compare/okf-tui/v1.0.0...okf-tui/v1.0.1
+[1.0.0]: https://github.com/serradura/okf/releases/tag/okf-tui/v1.0.0

data/README.md

@@ -1,6 +1,6 @@
 # okf-tui
 
-A full-screen terminal UI for [Open Knowledge Format](https://github.com/serradura/okf-gem)
+A full-screen terminal UI for [Open Knowledge Format](https://github.com/serradura/okf)
 bundles: read one, switch between many, configure the registry, and search
 across all of them at once. Built on the [TTY toolkit](https://ttytoolkit.org/components/).
 
@@ -21,7 +21,7 @@ This gem ships **no executable of its own** — deliberately. A second binary th
 only aliased `okf tui` would be one more name to install, document and keep
 working, and two front ends is two argument grammars waiting to drift. `okf`
 finds this gem because it ships `okf/plugin.rb`, the convention any gem can use
-to add a verb — see [extension points](https://github.com/serradura/okf-gem/blob/main/.okf/design/extension-points.md).
+to add a verb — see [extension points](https://github.com/serradura/okf/blob/main/.okf/design/extension-points.md).
 
 The argument shape mirrors `okf server` exactly, because it is the same grammar:
 `@slug` names a registered bundle, bare `@` the registry default, `@group` fans out
@@ -124,6 +124,10 @@ In the bundles view: `d` default, `a` add, `n` rename, `x` remove (asks first),
 shows what the file now says. Removing a bundle never touches the bundle on
 disk — the registry is a list of references.
 
+A bundle that arrived through an `okf registry link` is read-only — the registry
+that owns it is another file — so those keys say so instead of asking, and the
+detail pane names the link and the file to edit.
+
 It edits your *configuration*, never your knowledge: there is no bundle writing
 anywhere in this gem. Authoring belongs to `okf` and its companion skill.
 
@@ -151,7 +155,7 @@ Anything that can lose configuration asks first and names what it is about to do
 group goes with it. `+`, `c` and `d` add or reorder, and do not ask.
 
 **Which registry.** The same one every other `okf` verb run from the same
-directory resolves: a project-local `.okf-registry.json` when one is on the path
+directory resolves: a project-local `.okf.json` when one is on the path
 up from here, and `$OKF_HOME` (default `~/.okf`) otherwise. `OKF_NO_DISCOVERY=1`
 forces the global one. The header names the file it read, so there is never a
 question which is in force. A workspace of directories named on the command line
@@ -189,6 +193,11 @@ silently rather than loudly.
 the verb resolves the same way it does for a user. See [AGENTS.md](AGENTS.md)
 for the contracts a change has to keep.
 
+This gem ships its own knowledge bundle at `.okf/`, and it is the gem's own
+documentation rather than a sample: what every file under `lib/` does, what each
+of the six views answers, and why the interaction model is what it is. `okf tui
+.okf` reads it in this program, which is the shortest honest demo there is.
+
 ## License
 
 Apache-2.0.

data/lib/okf/tui/app.rb

@@ -996,6 +996,10 @@ module OKF::TUI
       return (@message = "no bundle here to add") if entry.nil?
       return (@message = "no group to add it to — c names the bundles in scope as one") if group.nil?
       return (@message = "@#{group.slug} already names @#{entry.slug}") if group.members.include?(entry.slug)
+      # Both halves: a linked bundle cannot be stored as a member (its name lives
+      # only while its link resolves), and a linked group cannot be written to.
+      return if refused_linked?(entry, "grouping")
+      return if refused_linked?(group, "adding to")
 
       apply_group_edit_keeping_focus do
         keeping_group_scoped(group.slug) { workspace.add_to_group(group.slug, [ entry.slug ]) }
@@ -1434,19 +1438,35 @@ module OKF::TUI
     # cascades across every member list, and one `del` cascade-drops the slug and
     # deletes any group it empties. Nothing here has to know that — it just has to
     # pass the slug the cursor is on rather than assuming it is a bundle's.
+    # A bundle or group an okf registry *link* brought in is read-only: the file
+    # that owns it is another registry, and okf refuses every config write against
+    # one. The refusal belongs here, before the prompt — letting the ask through
+    # makes a user type a new name and confirm it before learning it could never
+    # land, and this view's own rule is that a key which stops working says so.
+    # True when it refused, so a caller reads as `return if refused_linked?(…)`.
+    def refused_linked?(subject, action)
+      return false if subject.nil? || !subject.linked?
+
+      @message = "#{action} @#{subject.slug} is read-only — it comes from the linked registry " \
+                 "@#{subject.link}, so edit it there"
+      true
+    end
+
     def ask_rename
-      slug = selected_slug
-      return if slug.nil?
+      subject = detailing_group? ? selected_group : selected_entry
+      return if subject.nil?
+      return if refused_linked?(subject, "renaming")
 
-      ask(:rename, "rename @#{slug} to:", free_text: true, subject: slug)
+      ask(:rename, "rename @#{subject.slug} to:", free_text: true, subject: subject.slug)
     end
 
     def ask_remove
-      slug = selected_slug
-      return if slug.nil?
+      subject = detailing_group? ? selected_group : selected_entry
+      return if subject.nil?
+      return if refused_linked?(subject, "removing")
 
-      what = detailing_group? ? "group @#{slug}" : "@#{slug}"
-      ask(:remove, "remove #{what} from the registry? (y/n)", free_text: false, subject: slug)
+      what = detailing_group? ? "group @#{subject.slug}" : "@#{subject.slug}"
+      ask(:remove, "remove #{what} from the registry? (y/n)", free_text: false, subject: subject.slug)
     end
 
     # The slug the focused pane has selected — a group's when the groups or member
@@ -1458,6 +1478,7 @@ module OKF::TUI
     def set_default
       entry = selected_entry
       return if entry.nil?
+      return if refused_linked?(entry, "defaulting to")
 
       @message = workspace.make_default(entry.slug)
       # Making a bundle the default moves it to the front, so the list reorders

data/lib/okf/tui/cli.rb

@@ -32,7 +32,7 @@ module OKF
             -v, --version      print the version
             -h, --help         print this message
 
-        The registry is the project-local .okf-registry.json when one is on the
+        The registry is the project-local .okf.json when one is on the
         path up from here, and $OKF_HOME (default ~/.okf) otherwise — whichever
         one every other `okf` verb run from here resolves to. OKF_NO_DISCOVERY=1
         forces the global one.
@@ -87,7 +87,7 @@ module OKF
       # `cwd: Dir.pwd` is the other half of that: it is what opts this run into
       # registry discovery, mirroring okf's own rule that only its CLI passes a
       # cwd while a library caller stays global-only. Without it the TUI would be
-      # the one okf verb that ignores a project-local `.okf-registry.json` sitting
+      # the one okf verb that ignores a project-local `.okf.json` sitting
       # right beside the bundles it is being asked about.
       def start(refs)
         return incompatible_okf("cannot answer a search — OKF::Bundle::Search is missing across/prepare/with") unless

data/lib/okf/tui/refs.rb

@@ -28,7 +28,7 @@ module OKF
     # Resolution is also what opts the TUI into registry discovery: Command's
     # `open_registry` is `OKF::Registry.load(cwd: Dir.pwd)`, so a `@slug` here
     # means the same bundle it means to every other okf verb run from the same
-    # directory — the project-local `.okf-registry.json` when there is one on the
+    # directory — the project-local `.okf.json` when there is one on the
     # path up, the global `$OKF_HOME` registry otherwise.
     class Refs < OKF::CLI::Command
       def self.id

data/lib/okf/tui/version.rb

@@ -2,6 +2,6 @@
 
 module OKF
   module TUI
-    VERSION = "1.0.0"
+    VERSION = "1.1.0"
   end
 end

data/lib/okf/tui/views.rb

@@ -439,6 +439,7 @@ module OKF::TUI
         r.add("  default", :magenta) if entry.default?
       end
       rows << Ui.line(width) { |r| r.add(entry.dir.to_s, :bright_black) }
+      rows.concat(linked_rows(app, entry, width))
       rows.concat(membership_rows(app, entry, width))
       rows << Ui.blank_line(width)
 
@@ -500,6 +501,20 @@ module OKF::TUI
     # can show one membership, and a bundle can have several. This is the line that
     # answers "did that + land" when the group being edited is scrolled out of the
     # groups pane.
+    # Where a linked bundle comes from, and that the config keys will not touch
+    # it. On the detail rather than the registry row: that pane is 42 columns and
+    # already carries slug, count and `default`, so a marker there would clip on a
+    # narrow terminal — and this is the pane where the other "what can I do with
+    # this one" lines already live.
+    def linked_rows(app, entry, width)
+      return [] unless entry.linked?
+
+      target = app.workspace.link_target(entry.link)
+      rows = [ Ui.line(width) { |r| r.add("read-only — linked from @#{entry.link}", :yellow) } ]
+      rows << Ui.line(width) { |r| r.add(target.to_s, :bright_black) } if target
+      rows
+    end
+
     def membership_rows(app, entry, width)
       groups = app.workspace.groups.select { |group| group.members.include?(entry.slug) }
       return [] if groups.empty?

data/lib/okf/tui/workspace.rb

@@ -16,14 +16,22 @@ module OKF::TUI
     # or unreadable, and `error` says which — so a row explains itself instead of
     # silently vanishing from the list.
     class Entry
-      attr_reader :slug, :dir
+      attr_reader :slug, :dir, :link
       attr_accessor :model, :error
 
-      def initialize(slug:, dir:, default:, registered:)
+      def initialize(slug:, dir:, default:, registered:, link: nil)
         @slug = slug
         @dir = dir
         @default = default
         @registered = registered
+        @link = link
+      end
+
+      # Did this bundle arrive through an okf registry link? Browsing one is
+      # browsing a bundle, so it reads like any other — but the registry that
+      # owns it is another file, and okf refuses every config write against it.
+      def linked?
+        !@link.nil?
       end
 
       def default?
@@ -52,13 +60,21 @@ module OKF::TUI
     # the members are what an edit would change, the leaves are what a search
     # would cover, and for a nested group those are not the same list.
     class Group
-      attr_reader :slug, :members, :bundles
+      attr_reader :slug, :members, :bundles, :link
 
-      def initialize(slug:, members:, bundles:, cyclic:)
+      def initialize(slug:, members:, bundles:, cyclic:, link: nil)
         @slug = slug
         @members = members
         @bundles = bundles
         @cyclic = cyclic
+        @link = link
+      end
+
+      # A group an okf registry link brought in — the link's own set, or one the
+      # linked file curates. Scopable and searchable like any other; writable by
+      # nobody here, since okf persists only the groups this registry owns.
+      def linked?
+        !@link.nil?
       end
 
       # A hand-edited registry can name a cycle, which okf reports by declining to
@@ -81,7 +97,7 @@ module OKF::TUI
     # its CLI passes a cwd and a library caller stays on the global registry. A
     # default here would make the registry an embedding app reads depend on the
     # directory its process happens to be in, and would let the suite discover a
-    # `.okf-registry.json` from wherever `rake` was run.
+    # `.okf.json` from wherever `rake` was run.
     #
     # +ref_slugs+ maps a resolved directory to the slug the @ref named it by, so a
     # session built from refs keeps the names the user typed. See Refs#slugs.
@@ -108,6 +124,15 @@ module OKF::TUI
       (registry || open_registry).path
     end
 
+    # The registry file a link points at — what a refusal has to name, since
+    # "edit it there" is useless without saying where there is. nil when nothing
+    # is linked under that name.
+    def link_target(name)
+      return nil unless registry_backed?
+
+      registry.links_listing.find { |row| row[:slug] == name }&.fetch(:registry)
+    end
+
     def empty?
       entries.empty?
     end
@@ -465,7 +490,7 @@ module OKF::TUI
     def registry_entries
       registry.listing.map do |row|
         build_entry(slug: row[:slug], dir: row[:dir], default: row[:default],
-          registered: true, missing: row[:missing])
+          registered: true, missing: row[:missing], link: row[:link])
       end
     end
 
@@ -482,7 +507,7 @@ module OKF::TUI
         end
 
         Group.new(slug: row[:slug], members: row[:members], bundles: bundles || [],
-          cyclic: bundles.nil?)
+          cyclic: bundles.nil?, link: row[:link])
       end
     end
 
@@ -508,8 +533,8 @@ module OKF::TUI
       end
     end
 
-    def build_entry(slug:, dir:, default:, registered:, missing:)
-      entry = Entry.new(slug: slug, dir: dir, default: default, registered: registered)
+    def build_entry(slug:, dir:, default:, registered:, missing:, link: nil)
+      entry = Entry.new(slug: slug, dir: dir, default: default, registered: registered, link: link)
 
       if missing
         entry.error = "directory is gone"