okf-tui 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: def7a9aa9c4d6fd614896848e6e6712491f062f830d487e260142bfdd8698374
+  data.tar.gz: 96e3fb4d8bdbb6c78aef7cf00392372667d89066793bd81feacb6e486e13967a
+SHA512:
+  metadata.gz: 9520521f0c1ca38385d2ab974b81d1f574923be0ae9f4612c4dd590d66d11a92dbc0e88ac57d81793944134b349df664e802d102609d24d899bb7bf577aeb383
+  data.tar.gz: f8f24b77abed3ef919c40ff34d322ff81d006be77f27c2daf1bb1377bc1634d8834eaa80cd4d93ad987f57a13bd08bce499166a01ebb04578cc6874ed05d5223

data/.okf/decisions/index.md

@@ -0,0 +1,12 @@
+# Decisions
+
+The choices that shape okf-tui, each with the tradeoff it accepted.
+
+* [It Invents No Analysis](invents-no-analysis.md) - Every judgement comes from okf; the negative rule this imposes on any feature request, and what it costs.
+* [The Search Facade Coupling](search-facade-coupling.md) - Why search rides Bundle::Search.across, and why that needs a check at boot rather than a rescue.
+* [Ruby 2.4 Floor, Inherited](ruby-floor.md) - The floor taken from okf, the 2.5 API that slipped past RuboCop, and why the linter loads conditionally.
+* [No Version Ceilings on the Markdown Stack](no-version-ceilings.md) - Pinning kramdown and rouge down to protect the floor broke every Ruby above it.
+* [One Door — the Plugin Seam Is the Entry Point](one-door-the-plugin-seam.md) - okf-tui ships no executable and registers as an `okf` command; why one front end rather than two, and why registration must not build anything.
+* [The Undeclared Width Dependency](undeclared-width-dependency.md) - Column measurement rests on a gem that arrives through tty-box; why that is accepted, and what fails loudly if it stops.
+* [okf Moves, and This Breaks Quietly](okf-capability-drift.md) - Inventing no analysis means okf's evolution is this program's; every drift found so far failed silently, and agreement tests are the only defence that works.
+* [It Writes the Registry, Never a Bundle](registry-write-boundary.md) - The line under the TUI's side effects is the registry versus the knowledge — what that admits, and why `registry init` falls outside it.

data/.okf/decisions/invents-no-analysis.md

@@ -0,0 +1,53 @@
+---
+type: Decision
+title: It Invents No Analysis
+description: Every judgement on screen is a pure call into okf; the TUI adds no check, score, or verdict of its own, which bounds what a feature request may be answered with.
+tags: [okf-coupling, dependencies]
+timestamp: 2026-07-19
+---
+
+# Overview
+
+`OKF::Bundle::Reader` and `OKF::Registry` are the only parts that touch disk, and
+everything drawn is a pure call on the resulting in-memory bundles — `catalog`,
+`graph`, `validate`, `lint`, `Bundle::Search`. The TUI is one more shell over the
+same core the `okf` CLI and the graph server already use.
+
+The rule this actually imposes is a *negative* one, and it is the reason to write
+it down: **a question the TUI cannot answer by asking okf is a question it does
+not answer.** No extra lint check, no derived score, no "helpful" verdict
+computed locally. If a screen wants an analysis okf does not expose, the change
+belongs in okf.
+
+# What that keeps intact
+
+okf's own contracts survive the port to a screen, rather than being softened for
+presentation:
+
+| okf contract | How the screen keeps it |
+|--------------|------------------------|
+| `validate` and `lint` answer different questions | separate sections in the health view, never merged into one score |
+| reads are best-effort | an unreadable file reports as `⊘ n unreadable`, not fatal |
+| exit codes mean something | a bad directory exits `2`, the usage-error code |
+
+The one place the TUI *does* add vocabulary is presentational: the clean /
+warnings / not-conformant verdict that colours the bundle name everywhere it
+appears. That is a rendering of `validate` + `lint` output, not a fourth
+judgement — see [status-vocabulary](/rendering/status-vocabulary.md).
+
+# The cost
+
+It makes okf-tui's release calendar depend on okf's. The search view demonstrated
+the sharp edge: [search-facade-coupling](/decisions/search-facade-coupling.md)
+was blocked entirely on an okf release, with no local workaround *by
+construction* — implementing a fallback search here would have broken this rule.
+
+That one has since resolved (okf 1.9.0 shipped the facade), which is the point
+rather than a footnote: the cost of this rule is paid in **waiting**, not in
+capability. The wait ended, and nothing had to be built twice.
+
+# Citations
+
+[1] `lib/okf/tui.rb` — the module comment stating the split.
+[2] `lib/okf/tui/model.rb`, `lib/okf/tui/workspace.rb` — every analysis is a
+    memoized call into okf.

data/.okf/decisions/no-version-ceilings.md

@@ -0,0 +1,69 @@
+---
+type: Decision
+title: No Version Ceilings on the Markdown Stack
+description: Pinning kramdown and rouge to their old lines to protect the Ruby 2.4 floor broke modern Ruby instead; the gems declare their own floors, so resolution handles it per-Ruby.
+tags: [ruby-floor, dependencies]
+timestamp: 2026-07-18
+---
+
+# Overview
+
+`tty-markdown` pulls in `kramdown` and `rouge`. Both have dropped Ruby 2.4 in
+their current lines, so the first instinct was to pin everyone to the last
+versions that still ran on the floor:
+
+```ruby
+spec.add_dependency "kramdown", ">= 2.3", "< 2.5"   # wrong
+spec.add_dependency "rouge",    ">= 3.14", "< 4.0"  # wrong
+```
+
+That is backwards, and it broke the *modern* end of the matrix: kramdown 2.4
+calls a `CGI` method that no longer exists on Ruby 4.0, so every job above the
+floor died with `NoMethodError: undefined method 'parse' for class CGI`.
+
+# The rule
+
+**Do not pin a dependency down to protect an old Ruby.** A ceiling is a claim
+about every Ruby, made to serve one of them.
+
+The gems already carry `required_ruby_version`, and Bundler honours it: on 2.4 it
+resolves kramdown 2.4.0 and rouge 3.30.0 by itself, on 4.0 it resolves the
+current lines. Declaring only floors lets each Ruby get the newest version that
+actually runs there — which is more than the ceiling would have allowed, and
+correct on every Ruby rather than one.
+
+```ruby
+spec.add_dependency "kramdown", ">= 2.3"
+spec.add_dependency "rouge", ">= 3.14"
+```
+
+This is the same reasoning that gates the *development* tooling instead of
+pinning it — see [ruby-floor](/decisions/ruby-floor.md), where RuboCop and irb
+load only on 2.7+ because they cannot install on the floor at all.
+
+# The one ceiling, and what earns it
+
+`okf` carries `< 3`, and it is not a hedge against a Ruby — it is the exception
+that shows what the rule is actually about. The rule refuses a ceiling *made to
+serve one Ruby*, because `required_ruby_version` already expresses that and
+better. It does not refuse a ceiling that expresses a real incompatibility
+resolution cannot see.
+
+This one does, and the evidence is this gem's own scar tissue: an okf *major* is
+where the renames come from, and those renames break screens
+[silently](/decisions/okf-capability-drift.md) — `area` became `top_dir` and
+every bundle reported one directory; `timestamp` became `generated_at` and the
+"updated" row stopped rendering. Neither raised. Neither turned a suite red.
+
+So `< 3` buys the one thing a floor cannot: it turns the *next* one into a
+resolution failure a maintainer reads, instead of a wrong number a reader
+believes. `test/unit/gemspec_test.rb` pins both bounds — the floor may never lag
+the kernel this gem develops against, and the ceiling may not quietly go away.
+
+# Citations
+
+[1] `okf-tui.gemspec` — the two floors, with the comment recording the failed
+    ceiling attempt.
+[2] Verified in `ruby:2.4` (Docker): resolved kramdown 2.4.0 + rouge 3.30.0,
+    34 runs / 6622 assertions green, and green across
+    [the whole matrix](/testing/ci-matrix.md) up to 4.0.

data/.okf/decisions/okf-capability-drift.md

@@ -0,0 +1,120 @@
+---
+type: Decision
+title: okf Moves, and This Breaks Quietly
+description: Inventing no analysis means every answer on screen is okf's — so okf renaming a field or adding a faster path is a change to this program, and every such drift found so far failed silently rather than loudly.
+tags: [okf-coupling, dependencies, testing, maintenance]
+timestamp: 2026-08-13
+---
+
+# Overview
+
+[invents-no-analysis](/decisions/invents-no-analysis.md) says every judgement on
+screen comes from okf. The cost of that rule is not the one it looks like. It is
+not that features are hard to add; it is that **okf's evolution is this program's
+evolution**, and the failures arrive without a stack trace.
+
+This file records the shape of that drift, found by catching up four okf minor
+versions at once (1.9 → 1.13) and discovering that the TUI had been wrong in
+production for a release without anything going red.
+
+# Every drift found so far was silent
+
+Four, and not one of them raised:
+
+| What okf did | How it presented here |
+|---|---|
+| renamed the catalog's `area` to `top_dir` (1.12.0) | `rows.map { row[:area] }` returned `[nil]`, so **every** bundle reported `1 areas` — a wrong number that looks like a right one |
+| added `Search.prepare`/`with` (1.11.0) | nothing broke; the TUI simply kept rebuilding a full-text index per query, 392 ms where 12 ms was available |
+| added registry groups (1.12.0) | `registry.listing` returns bundles only, so groups were absent from the one view whose job is the registry |
+| added local-registry discovery (1.12.0) | `Registry.load` without `cwd:` still worked — it just answered about a *different registry* than every other okf verb in the same directory |
+
+Two patterns, and the second is the dangerous one:
+
+- **A renamed field reads as nil.** Ruby hands back `nil` for a missing hash key,
+  so a derived-field rename cannot fail loudly. It becomes a plausible number.
+- **A new capability is invisible by construction.** Nothing is broken when okf
+  adds a faster path or a new concept; the TUI is merely *less* than it was
+  written to be. No test can fail for a feature nobody has written yet, which
+  means the only defence is reading okf's changelog on purpose.
+
+The renames are why the floor is now stated per capability in the gemspec, one
+line each, naming the version and what fails without it. The additions are why
+catching up is a periodic *task*, not an event that gets triggered.
+
+# The defence that works: agreement, not assertion
+
+The instinct after the `area` break is to assert the number: "this fixture has six
+directories". That catches a regression in this code and nothing about drift — okf
+could change what counts as a directory tomorrow and the test would keep passing
+while the screen went wrong.
+
+What works is asking okf the same question and comparing:
+
+```ruby
+# dirs_test.rb — the dir facet, against okf's own subtree column
+OKF::CLI.start([ "dirs", fixture(name), "--json" ], out: out, err: StringIO.new)
+```
+
+`structure_test.rb` does the same against `okf graph --traffic`, parsing its
+**human** table and matching the rendered frame row for row. Both run in-process,
+so they cost milliseconds, and both fail the moment okf and this disagree about a
+number — which is the actual contract, and the one an asserted constant does not
+express.
+
+Where a formula had to be reproduced (cohesion is `internal / (internal + out +
+in)`, okf's arithmetic over `Bundle::Skeleton`), the agreement test is what makes
+the copy safe. A comment saying "same as okf's" is a claim; the test is the check.
+
+# Prefer inheriting a rule to copying it
+
+Two couplings arrived in this pass, and they were resolved differently on purpose:
+
+**The ref grammar is inherited.** `OKF::TUI::Refs` subclasses `OKF::CLI::Command`
+to reach `resolve_ref_expanding`, okf's own resolver — so `@slug`, bare `@`,
+`@group` fan-out, the vanished-member note and the `@all` refusal all behave
+identically to `okf server`, messages and exit codes included. That is a coupling
+to a **private** method, accepted because the alternative is a second copy of a
+grammar with five branches and its own error strings, which is precisely the
+"second argument grammar" [one-door-the-plugin-seam](/decisions/one-door-the-plugin-seam.md)
+exists to prevent. `refs_test.rb` pins the seam by name, so okf moving it fails
+loudly rather than quietly restoring `not a directory`.
+
+**The `--dir` matching rule is reimplemented**, in one line
+(`Model.under_dir?`), and that is not inconsistent. okf's flag handling is mostly
+about *arguments a human typed* — the `root` alias, a trailing slash, case folding
+— and none of it applies to a facet whose value the TUI got out of
+`Bundle#directories` and whose rows carry `OKF.dir_of`. Both sides are already
+okf's canonical spellings, so what is left is the set relation between two values
+okf handed over. The agreement test is what holds it to okf's answer.
+
+The rule of thumb: **inherit a grammar, reimplement a predicate, and test
+agreement either way.**
+
+# What this costs, and why it is still right
+
+The bill is real: a periodic read of okf's changelog, a floor that has to be
+raised deliberately, and a test suite that runs okf's CLI in-process to check its
+own arithmetic. None of that would exist if the TUI parsed markdown itself.
+
+It is still right, and the four drifts above are the argument. Every one of them
+was a *number this program did not have to compute*, and three of the four were
+okf getting better at answering it. A TUI with its own catalog would not have had
+the `area` break — it would have had its own, permanently, with no upstream to
+inherit the fix from.
+
+# Citations
+
+[1] `okf-tui.gemspec` — the seven capabilities and the version each shipped in.
+[2] `test/integration/dirs_test.rb` — `okf_subtree_counts`, the `okf dirs --json`
+    oracle; and the `nested` fixture, which exists because at one directory level
+    `dir` and `top_dir` are the same string and an assertion cannot tell them apart.
+[3] `test/integration/structure_test.rb` — `okf_traffic_rows`, parsing okf's human
+    traffic table; the row count is asserted first so the comparison loop cannot
+    pass vacuously.
+[4] `lib/okf/tui/refs.rb` — the inherited grammar, and why it subclasses Command
+    without ever being registered.
+[5] okf `CHANGELOG.md`, 1.12.0 "Changed": "The derived `area` field is renamed
+    `top_dir`" — "`area` was never the OKF spec's word (`grep -ci area SPEC.md` → 0)".
+[6] Measured 2026-08-13 over five registered bundles / 129 concepts: first query
+    391.8 ms, then 16.2 / 13.0 / 12.0 / 14.4 ms. Before, every query paid the first
+    figure.

data/.okf/decisions/one-door-the-plugin-seam.md

@@ -0,0 +1,131 @@
+---
+type: Decision
+title: One door — the plugin seam is the entry point
+description: okf-tui ships no executable; `okf tui` is the only way in, and the registration stays cheap enough that a run wanting `okf lint` pays nothing for it.
+tags: [okf-coupling, dependencies, cli]
+timestamp: 2026-07-19T18:00:00Z
+---
+
+# Overview
+
+okf's CLI dispatches through a registry and finds extensions by convention: any
+gem with `okf/plugin.rb` on its load path can add a verb. This gem ships one, and
+that file is its **only** entry point: there is no `exe/`, and `okf help` lists
+`tui` under `installed extensions:`. It is the second registry this gem plugs
+into, after
+[the search facade](search-facade-coupling.md) — and unlike that one it carries
+no unreleased-API risk, because a plugin file an old okf never discovers is
+simply inert.
+
+Installing the gem is the whole installation. There is no config file, no
+`okf plugin add`, and nothing to edit in okf — which is the point of a convention
+over a list. See okf's
+[extension points](https://github.com/serradura/okf-gem/blob/main/.okf/design/extension-points.md).
+
+# One front end, because two would drift
+
+There was an `exe/okf-tui`. It did nothing but call the same `CLI.run` the
+plugin's `#call` calls, and it went before the first release, while removing a
+name still cost nobody anything. okf-mcp had already made the same call for the
+same reason, and its gemspec records it in one line: a second binary that only
+aliases a verb is one more name to install, document and keep working.
+
+The cost of keeping it was not the file. It was that **two front ends are two
+argument grammars, and the drift between them is invisible** — each one passes
+its own tests while they disagree, because nothing compares them. That is not
+hypothetical here: `--home` had to be dropped precisely because the same tool
+answered differently depending on which door you came through (see below). The
+door that survives is the one a user is told about in `okf help`.
+
+What the seam buys instead is discoverability. Somebody who installed okf-tui
+finds it in okf's own map without having to learn that a second command exists.
+
+The obligation that replaces the two-door test: **the adapter must carry argv
+and the streams and add nothing else.** `plugin_test.rb` drives the same run
+through `OKF::CLI.start` and straight into `OKF::TUI::CLI.run`, and compares the
+exit code and the message — driven in the same
+[headless, stream-injected](../testing/headless-frames.md) style every other
+surface here is proven in. `terminal_test.rb` covers what neither of those can,
+being in-process: it spawns okf's executable on a real pty, so process boot and
+plugin *discovery* are on the path too.
+
+# Registration must not build anything
+
+okf reads `okf/plugin.rb` whenever a verb misses or `okf help` runs. That file
+therefore cannot be expensive, and this gem's library is: six TTY gems plus
+kramdown and rouge. Somebody typing `okf lint` should not pay for a terminal
+toolkit they are not going to see.
+
+So the plugin file registers a class and nothing else; `require "okf/tui/cli"`
+happens inside `#call`. A subprocess test asserts that loading the plugin leaves
+`TTY::Box` undefined — in-process it would assert nothing, since the suite has
+long since loaded it.
+
+This is the same shape as okf's own laziness one level up: discovery itself only
+runs for an unknown verb or for `help`, so a built-in verb never even reads this
+file.
+
+# `input:` is why the base command carries a terminal
+
+Every verb okf ships is a one-shot read that never looks at stdin. This one
+cannot work without it — a full-screen UI with no terminal has nothing to drive —
+so `Command` carries an `input:` alongside `out:`/`err:`, and the TUI takes it
+from there rather than reaching for `$stdin`.
+
+That is not ceremony. Reaching past the injected streams would put the command
+outside the stream discipline
+[the whole suite depends on](../testing/headless-frames.md), and it would make
+"it refuses to run without a terminal" unassertable through `okf tui` — the
+refusal only works because the stream okf handed down is the one the TUI checks.
+
+# It could not ship before okf did, and that debt is paid
+
+The seam was once newer than any okf release, so `okf tui` did not work against
+the published gem and this suite would have been asserting against a CLI with no
+`register` at all — the same shape as
+[the search facade](search-facade-coupling.md). It was handled the way that one
+taught rather than discovered again: the plugin tests **skipped, named**, on an
+okf without the registry, and the floor stayed honest rather than guessing at a
+version that did not exist yet — guessing one is how the last dependency fix
+[became the next bug](../testing/ci-matrix.md).
+
+Both debts are settled. `OKF::CLI.register` shipped in okf 1.10.0, the floor now
+names `okf >= 2.0, < 3`, and the skip is gone — deleted on its own instruction,
+because a skip left in place after the reason for it is gone is a suite that
+quietly tests nothing.
+
+One piece of that arrangement stays, and it should: `lib/okf/plugin.rb` raises a
+named `LoadError` rather than a bare `NameError` if it is ever required against
+an okf without the registry. The floor makes that unreachable through
+resolution, and unreachable is not the same as impossible — a second okf ahead
+of the intended one on the load path is exactly how it would happen.
+
+# What it cost: the `--home` flag
+
+`okf-tui --home DIR` is gone. okf had dropped its own `--home` before 1.8 for a
+reason it wrote down — a flag whose whole job is to name a location `$OKF_HOME`
+already names has to be remembered on the verbs that offer it and forgotten on
+the ones that do not — and this gem kept it anyway.
+
+That was survivable while `okf-tui` was its own binary. It stopped being
+survivable the moment `okf tui` existed, because then the same tool had two
+grammars depending on which door you came through. The flag went first and the
+binary followed, which is the order the lesson actually arrived in: the drift was
+visible before its cause was.
+
+The library keyword is untouched: `App` and `Workspace` still take `home:`, which
+is how an embedding app and the suite name a registry without mutating a
+process-global. That is exactly the split okf itself draws — the env var is the
+CLI's only lever, the keyword is the library's.
+
+# Citations
+
+[1] `lib/okf/plugin.rb` — the whole seam, including why the heavy require is in `#call`.
+[2] `okf-tui.gemspec` — the comment recording why there is no `spec.executables`.
+[3] `test/integration/plugin_test.rb` — the dispatcher adding nothing but the
+    streams, and the subprocess check that registering does not load tty-box.
+[4] `test/integration/terminal_test.rb` — okf's own executable on a real pty, the
+    one test that walks process boot and plugin discovery rather than the
+    in-process dispatcher.
+[5] Verified 2026-07-19: `okf --help` lists `tui` under `installed extensions:`;
+    `okf validate` still runs without triggering discovery at all.

data/.okf/decisions/registry-write-boundary.md

@@ -0,0 +1,175 @@
+---
+type: Decision
+title: It Writes the Registry, Never a Bundle
+description: The line the TUI's side effects sit on is not read-versus-write — it is the registry versus the knowledge; what that admits, what it excludes, and why `registry init` is on the far side of it.
+tags: [registry, boundary, side-effects]
+timestamp: 2026-08-13
+---
+
+# Overview
+
+The TUI has side effects, and more of them than a reader expects from something
+described as a viewer. It registers bundles, removes them, renames slugs, moves
+the default. The question that keeps coming up — *should it also create groups?
+rename them? do everything the CLI does?* — cannot be answered by asking whether
+a feature writes to disk, because the answer is already yes.
+
+The line is **the registry, not read-versus-write**: this program edits the user's
+*configuration* freely and never touches the *knowledge*.
+
+# What that admits
+
+Seven of okf's eight `registry` verbs have a place here, and it is the same place —
+the bundles view, where `Workspace` owns every write and each is followed by a
+reload, per `AGENTS.md` constraint 8:
+
+| Key | `Workspace` | okf CLI |
+|-----|-------------|---------|
+| `a` | `add` | `okf registry set <dir>` |
+| `x` | `remove` | `okf registry del <@slug>` — spans a group |
+| `d` | `make_default` | `okf registry default <@slug>` |
+| `n` | `rename` | `okf registry rename <@slug> <new>` — spans a group |
+| `c` | `create_group` | `okf registry group <slug> <@member…>` |
+| `+` | `add_to_group` | `okf registry group <slug> <@member…>` |
+| `-` | `remove_from_group` | `okf registry ungroup <slug> <@member…>` |
+| — | the view itself | `okf registry list` |
+
+Group create/edit was the question that forced this file to be written, and it
+falls on the admitted side: a group is registry configuration in exactly the sense
+a slug rename is. Stopping at read-only would have put a `@mkt` row on a screen
+where `x` already deletes a bundle, and refused to let you add a member to it —
+not restraint, just an arbitrary stopping point.
+
+**The members come from the scope, not from a typed list.** `◉` already means
+"these bundles" in this view, so the gesture is toggle what you want and then name
+it (`c`), or put the cursor on a group and push the scope into it (`+`) or out of
+it (`-`). That is a gesture the CLI cannot offer, and it is why these keys are
+worth having rather than being a second spelling of `okf registry group`.
+
+okf owns every cascade. `set_group` creates-or-adds and refuses a cycle,
+`unset_group_members` deletes a group it empties, and `rename`/`del` span a group
+slug and cascade through every member list that names it. None of that is
+reimplemented; `groups_test.rb` asserts the *effects* — that renaming `@docs`
+leaves `@everything` naming `@papers` — precisely so the cascades stay okf's.
+
+# What it excludes
+
+Nothing in `lib/` writes a bundle. There is no `OKF::Bundle::Writer` reference in
+this gem, and that is the invariant worth grepping for: no concept editing, no
+"fix this lint warning for me", no touching a `log.md`. Authoring is okf's CLI and
+its companion skill, which have the vocabulary and the review path for it.
+
+The reason is not timidity. A registry is small, local, reversible and *about the
+session* — a list of references, which is why removing a bundle famously does not
+delete it. A bundle is the knowledge itself, and a full-screen keyboard UI is a
+poor place to make an irreversible edit to it by muscle memory.
+
+# `registry init` is excluded, for a different reason
+
+okf 1.12.0 added `okf registry init`, which creates a project-local
+`.okf-registry.json`. It is registry configuration, so the line above admits it —
+and it is still not offered, on mechanics rather than principle.
+
+The registry is resolved **once, at boot**: `Workspace#load_entries` opens it, and
+every reload after that goes through `Registry#reopen` on the same file. Creating
+a *new* registry mid-session is not an edit to the thing the session is on, it is
+a **re-anchoring** — after it, the file every other okf verb in that directory
+would now resolve is one this session has never read. Either the key appears to do
+nothing, or the entire workspace silently swaps out from under every open view,
+including the active bundle the other five views are about.
+
+Both outcomes are worse than not having the key. The CLI is the right door, and
+once the file exists the TUI discovers it on the next launch — which is
+`Workspace.new(cwd:)`, and the fix recorded in
+[which-registry](/interaction/which-registry.md).
+
+# The removal key, got wrong twice
+
+The first cut put removal on `-` at the group row, acting on the bundles the scope
+and the member list had in common. It shipped, and the report came back at once:
+someone looking for how to *turn the scope off* pressed `-`, and it deleted a group.
+
+Three things lined up, and the missing confirmation was only one of them:
+
+- **`-` reads as "remove", and the nearest removable thing was the scope.** Where
+  `◉` means "a search covers this", a key marked `-` is a scope key until proven
+  otherwise.
+- **The footer had dropped the scope keys on a group row** and labelled the member
+  keys `+/- add/remove scoped` — so the one screen someone stands on while wanting
+  to stop searching everything offered no `A`/`N`, and did offer a `-` described
+  with the word *scoped*. Close to an instruction.
+- **okf deletes a group whose last member leaves.** Right for a CLI where the
+  command names its members explicitly; here it meant one keystroke could destroy
+  the group rather than trim it.
+
+Adding a confirmation fixed the damage and left the real fault in place, which the
+next round of feedback named: `-` acted on **`scope ∩ members`, a set with no row
+on screen**. To predict the key you had to intersect two lists in your head, and
+the review comment was simply "it took me some time to understand how this works".
+
+The fix that stuck was structural, and it came from the maintainer rather than from
+me: **give the groups a pane of their own.** The bundles view is three panes now —
+bundles, groups, and the detail of whichever has focus — with `Tab` cycling.
+
+That does more than tidy the layout. Two panes hold *two selections at once*, and
+suddenly every editing key has visible rows to name: `+` is the bundle under the
+bundles cursor joining the group selected below, `-` is the member under the members
+cursor. Nothing reads the search scope any more except `c`, where naming the bundles
+you have been searching together is precisely the gesture. The key I had got wrong
+twice stopped being hard the moment the layout gave it something to point at.
+
+It also fixed a fault nobody had reported yet: the groups were a heading inside the
+bundle list, and a heading scrolls away. Thirteen registered bundles put them below
+the fold on a short terminal — no way to show a thing you are meant to select. A
+pane is always on screen, and `Tab` is the jump to it.
+
+Three rules came out of it, in increasing order of how far they carry:
+
+1. A write that can lose configuration confirms, and the question names the
+   outcome — `remove @nested — its last, so @docs goes too`, not a bare "remove?".
+2. **Act on a row, not on a set the reader has to compute.** A key whose effect is
+   an intersection of two lists cannot be predicted from the screen, and every
+   misreading of it is reasonable.
+3. **A hint must not borrow the vocabulary of a different mechanism.** Two
+   independent axes live in this view — the active bundle and the scope
+   ([cross-bundle-scope](/interaction/cross-bundle-scope.md)) — so a registry write
+   described in the scope's words will be read as the scope's key.
+
+Reuse also mattered: `Tab` already meant "switch pane" in browse and graph, so three
+panes cost a reader nothing new, and `Esc` peels them one at a time before the
+filter, exactly as
+[esc-peels-one-layer](/interaction/esc-peels-one-layer.md) requires. A key that
+belongs to a different pane *says where it lives* rather than going silent — a key
+that quietly stopped working is indistinguishable from a broken one.
+
+The last thing, and the smallest, was the one the report actually opened with:
+"it is not clear how to control the scope." It was not. Neither `A` nor `N` appeared
+in the footer on a bundle row, and the footer truncates, so at 80 columns everything
+past `d` was already off screen. The scope is one of this view's two axes
+([cross-bundle-scope](/interaction/cross-bundle-scope.md)); it belongs in the
+visible prefix, ahead of the config keys, and that is where it is now.
+
+# The test that keeps it honest
+
+Every write test builds its own registry: `with_registry` under a temporary
+`$OKF_HOME`, and `with_local_registry` for the project-local file. Nothing in the
+suite may touch the real `~/.okf` — it is the maintainer's own configuration, and
+this is a suite that exercises `remove`.
+
+Two states in `groups_test.rb` are reached by writing the registry JSON directly,
+because okf's own API refuses to produce them: a member naming nothing registered,
+and a cycle (`group cycle: @g would contain itself`). Both are legitimate things
+to survive, since okf invites you to *commit* a local registry — so a hand-edited
+file is a normal input, not an abuse.
+
+# Citations
+
+[1] `lib/okf/tui/workspace.rb` — the seven writes, each returning a status message
+    and reloading; `not_registry_backed` for the ad-hoc case, which has no registry
+    to change.
+[2] `AGENTS.md` constraint 8 — the same boundary, stated where a change is judged.
+[3] `grep -rn "Bundle::Writer" lib/` → no matches, 2026-08-13.
+[4] okf `CHANGELOG.md` 1.12.0 — `okf registry init`, and the discovery rule that
+    makes the nearest `.okf-registry.json` win.
+[5] `test/test_helper.rb` — `with_registry`, `with_local_registry`, and the
+    `$OKF_HOME` save/restore around both.

data/.okf/decisions/ruby-floor.md

@@ -0,0 +1,59 @@
+---
+type: Decision
+title: Ruby 2.4 Floor, Inherited
+description: okf-tui takes okf's floor rather than its own, which costs the ergonomic syntax and forces the development tooling to load conditionally.
+tags: [ruby-floor, dependencies]
+timestamp: 2026-07-18
+---
+
+# Overview
+
+`required_ruby_version = ">= 2.4.0"`, taken from [okf](@okf), which takes it from
+rack. A UI over a library that runs on the Ruby an OS already ships would be a
+strange thing to require a newer Ruby for.
+
+The cost lands in two places that are not obvious until you hit them.
+
+# The port had to give up keyword_init
+
+The prototype built its one-off structs the modern way:
+
+```ruby
+Prompt = Struct.new(:kind, :label, :buffer, :subject, :free_text, keyword_init: true)
+```
+
+`keyword_init:` is Ruby **2.5**. RuboCop at `TargetRubyVersion: 2.4` parses this
+happily — it catches *syntax*, not *APIs* — so nothing local complained; it would
+have failed on the floor at runtime. It is now a plain class with an
+`attr_reader` and a `free_text?` predicate.
+
+This is the general trap: the floor is a library-API constraint that only two
+things actually prove — reading the version each method arrived in, and running
+the suite on 2.4.
+
+# The tooling cannot install on the floor it guards
+
+RuboCop needs Ruby ≥ 2.5, so requiring it unconditionally makes `bundle install`
+fail on 2.4 — the tooling that enforces the floor blocks the floor. Both dev gems
+load conditionally, and the Rakefile degrades to test-only when RuboCop is
+absent:
+
+```ruby
+if RUBY_VERSION >= "2.7"
+  gem "irb"
+  gem "rubocop", "~> 1.21"
+end
+```
+
+So on 2.4 the *suite* is the proof and lint is skipped; on 2.7+ the default task
+runs both. Same split okf uses, and it is why
+[the CI matrix](/testing/ci-matrix.md) — not RuboCop — is what actually holds
+the floor.
+
+Nothing is pinned *down* to make this work — see
+[no-version-ceilings](/decisions/no-version-ceilings.md).
+
+# Citations
+
+[1] `okf-tui.gemspec`, `Gemfile`, `Rakefile`.
+[2] Verified in `ruby:2.4` (Docker) and on CI, which runs 2.4 through 4.0.