git:20260820.246ce59 to git:20260820.3ce9341

- Maintainer guide for okf-tui — `okf-tui` on RubyGems. A full-screen terminal UI

- over [Open Knowledge Format](https://github.com/serradura/okf-gem) bundles: read

- one, switch between many, configure the registry, and search across all of them

- at once. This file documents how to change the code without breaking its

- contracts.

-

- This gem is a sibling in the okf-gem monorepo, one directory per gem under

- `gems/`, beside the baseline `gems/okf/` it depends on.

- [`../../AGENTS.md`](../../AGENTS.md) is the repo-level guide and owns everything

- above a single gem — the layout, the shared testing obligations, the PR shape,

- the release-title convention, the Git attribution rule and the working style.

- What is here is okf-tui's own: its floor, its dependency limits, its rendering

- and interaction contracts. Where the two overlap, the root is the general rule

- and this is the instance.

- ## Read the bundle first

- **`.okf/` is this gem's structural documentation and its catalogue, and this

- file no longer restates them.** What the code is, where each responsibility

- lives, what the six views answer, which kernel calls back them, and how to add

- one all live there — once, in the concept that owns them:

- | what a file under `lib/` does | [`.okf/structure/`](.okf/structure/) — one concept per layer, and it names every file |

- | whether a capability already exists | [`.okf/capabilities/`](.okf/capabilities/) — the six views and the okf surface, before you build a seventh |

-

- `okf server .okf` from this directory reads it as a graph; `okf search @okf-tui

- <term>` searches it from anywhere in the checkout.

-

- The split used to run the other way: this file carried a hand-written Map of

- `lib/**` and nothing checked it. `test/unit/bundle_catalog_test.rb` now 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 — so the

- structural layer is pinned where it lives, rather than trusted where nobody

- looks.

-

- ## One door

-

- This gem ships **no executable**. `lib/okf/plugin.rb` registers a `tui` command

- with okf's registry, and `okf tui` is how a user gets here. Adding a binary back

- needs an argument stronger than symmetry — the general case is the ecosystem

- bundle's `@okf-eco decisions/one-door-per-sibling`, and how this seam is put

- together is [`.okf/structure/doors.md`](.okf/structure/doors.md).

-

- Three consequences a reviewer checks, all of them pinned:

- * **The dispatcher adds nothing but argv and the streams.** `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.

- * **`plugin.rb` stays cheap.** okf reads it whenever a verb misses or `okf help`

- runs, so it registers a class and nothing else; the TTY toolkit is required

- inside `#call`, and a subprocess test asserts that loading the plugin leaves

- `TTY::Box` undefined.

- * **The advertisement and the behaviour stay in step.** `help_rows` read

- `tui [DIR|@slug…]` for a whole release while the CLI rejected every `@slug` as

- "not a directory"; the test now asserts the advertised form resolves.

- Nine rules. Where a concept carries the argument, this is the short form a

- reviewer checks against and the link is the rest.

-

- 1. **It invents no analysis.** okf owns the format, the model, and every

- question this renders. A question the TUI cannot answer by asking okf is a

- question it has no business answering, and reaching past the library to parse

- markdown, walk a directory or re-derive a count is the one change to refuse

- outright. [`.okf/decisions/invents-no-analysis.md`](.okf/decisions/invents-no-analysis.md).

- **The corollary that keeps biting: when okf renames something, this breaks

- silently** — `area` → `top_dir`, then the catalog's `timestamp` →

- `generated_at`, each shipping a wrong number that looked like a right one

- with a green suite either side. So a derived okf field read here wants a test

- that would notice, and the strongest form is an *agreement* test: ask okf the

- same question and compare. Every drift found so far, and the two agreement

- tests that now stand where they were, are

-

- **It targets OKF v0.2, and reads v0.1 as well as okf does** — v0.2 only added

- optional keys, so a bundle that adopted none must not read as deficient. A

- *derived* value is never a declared one, and a version is a thing the bundle

- *says* (`Bundle#okf_version`, never a literal).

-

- 2. **Ruby >= 2.4**, the same floor as okf, which takes it from rack. RuboCop

- parses at 2.4 and catches syntax, but **not APIs**: the forbidden list,

- broken out by the version that introduced each name, is `@okf

- design/ruby-floor`, and what taking okf's floor rather than its own costs

- this gem is [`.okf/decisions/ruby-floor.md`](.okf/decisions/ruby-floor.md).

- It binds `test/` too. The container that proves it is under

- [Commands](#commands), and it is **run from the repo root**: the Gemfile

- resolves okf from `../okf`, so a container holding only this directory fails

- at `bundle install` before a test runs.

-

- 3. **No version ceilings for the floor's sake.** `kramdown` and `rouge` declare

- their own floors, so resolution already picks the newest each Ruby accepts;

- pinning the old lines for everyone was tried first and broke on modern Ruby.

- A ceiling has to be justified by an incompatibility resolution cannot see.

-

- 4. **The runtime dependencies are okf plus the TTY toolkit** — one gem per job

- (`pastel`, `tty-box`, `tty-cursor`, `tty-markdown`, `tty-reader`,

- `tty-screen`) and no more. A seventh is a design decision, not a convenience;

- challenge it. Nothing in `lib/` may require a gem the gemspec does not name —

- the one accepted exception, and the test that fails loudly if it stops

- arriving, is

-

- 5. **Width is measured on the ANSI-stripped text, always.** A composed frame

- breaks the moment a row's display width disagrees with `String#length`, which

- is exactly what colour causes. New rendering goes through `Ui`, never around

- it. [`.okf/rendering/ansi-aware-width.md`](.okf/rendering/ansi-aware-width.md).

-

- 6. **tty-markdown is never asked to wrap.** Its wrapper miscounts ANSI escapes

- and raises `IndexError` on coloured input, so `PARSE_WIDTH` is a width it can

- never reach and `Ui.reflow` wraps instead. The colour mode is passed

- explicitly rather than sniffed, which is what lets a test turn colour on.

-

- 7. **A layout that cannot fit says so rather than clipping.** Health is two

- panes above 112 columns and one pane at a time below it, reached by the same

- `Tab` either way — the key keeps its meaning and the narrow case stops

- pretending both halves fit. Judge a new split by what its *narrowest* column

- does to the longest row it must carry: health's right pane holds a fixed

- width because every row in it is short by construction, and the rows that

- carry paths are all on the left.

-

- 8. **A view returns rows; it never writes to the terminal.** `Views` is pure, so

- a frame is a value a test can assert on, and only `App#paint` prints. That is

- what makes the suite renderable without a terminal at all —

- 9. **The registry is the user's configuration, and that is the line.** The

- boundary the side effects sit on is not read-versus-write, it is the registry

- versus the knowledge: the TUI edits the former and never the latter. A write

- that can lose configuration asks first and names the consequence; an edit acts

- on a row rather than on a set the reader has to compute. All of it, including

- `registry init` sitting on the far side, is

- [`.okf/decisions/registry-write-boundary.md`](.okf/decisions/registry-write-boundary.md),

- and the interaction rules the panes obey are

- [`.okf/interaction/`](.okf/interaction/).

-

- **Which registry a session is on is a question with one answer.** okf

- resolves a project-local `.okf-registry.json` before the global `$OKF_HOME`

- one; the TUI did not, and being the single verb that disagreed was a silent

- wrong answer rather than an error.

- [`.okf/interaction/which-registry.md`](.okf/interaction/which-registry.md).

-

- ## Testing

-

- **Integration first.** `test/integration/` is the critical layer: it drives the

- app the way a user does — real keys, real frames, real exit codes. The

- test-first obligations are the root guide's and apply unchanged. What each file

- proves, the two fixtures built to reach a branch nothing else could, why the

- render sweep runs with colour *on*, and the two assertion traps this suite has

- already hit are [`.okf/testing/the-suite.md`](.okf/testing/the-suite.md); the

- walk a new view, key or panel owes is

- [`.okf/testing/adding-a-view.md`](.okf/testing/adding-a-view.md).

- One obligation is this gem's alone, because no other gem in the repo reads

- okf's *analysis output*:

- > **Run the suite against the *published* okf** before pushing anything that

- > reads it, and before a release. No suite here does by default — the Gemfile

- > resolves the checkout next door — and a released kernel resolves different

- > analysis output, which is a difference no floor expresses.

- # there is no exe/ here — `okf tui` is the entry point, and the bundle resolves

- # okf from ../okf, so `bundle exec okf` is the checkout's own CLI

- bundle exec okf tui # the TUI from the checkout, on your registry

- # the suite against the *published* okf, which is what a user resolves — see Testing

- The 2.4 floor, run from the repo root so the checkout of okf comes with it:

- CI runs this gem's default task on every supported Ruby as its own `okf-tui`

- job. A change is not done until that matrix is green.

-

- A release is cut **from this directory** — `cd gems/okf-tui` first. Bundler

- reads the gemspec in its working directory and derives the tag from it, so the

- root `rake release` refuses rather than doing something plausible. The PR that

- carries a version bump is a release PR and takes the repo-level shape — the

- `release` label, the title `Release okf-tui X.Y.Z — <summary>`, the body

- skeleton — all three owned by [`../../AGENTS.md`](../../AGENTS.md).

-

- 1. Bump `lib/okf/tui/version.rb` and move the `Unreleased` notes in

- `CHANGELOG.md` under the new version.

- 2. Move the gemspec's `okf` floor if the kernel bumped in the same cycle —

- `test/unit/gemspec_test.rb` fails until it does.

- 3. `bundle exec rake release` — tags **`okf-tui/vX.Y.Z`**, pushes commits + tag,

- pushes the gem to RubyGems (MFA required).

- **The tag prefix is load-bearing, not cosmetic**, which is why `Rakefile` sets

- `helper.tag_prefix = "okf-tui/"` before `#install`: a bare tag pushed from here

- would rebuild and republish the *okf* image, `:latest` included, from a release

- that ships something else. The argument is the ecosystem bundle's `@okf-eco

- decisions/release-and-tags`.

- `release:guard_clean` is repo-wide: Bundler runs `git diff` with no pathspec, so

- an edited file in a sibling gem blocks a release of this one, and all it says is

- "There are files that need to be committed first."

- Gem packaging detail: `spec.files` comes from `git ls-files` run with `chdir:`

- into this directory, minus `test/`, `bin/`, the Gemfile, the Rakefile,

- `.rubocop.yml`, `.gitignore`, `AGENTS.md` and `CLAUDE.md`. A new top-level file

- **here** ships unless the gemspec rejects it, so check `gem build` output when

- adding one. `.okf/` is not rejected on purpose. `LICENSE.txt` and `NOTICE` are

- real duplicates of the repo root's, never symlinks — `gem build` packages a

- symlink as a symlink, RubyGems >= 3.2 refuses to extract one, and older RubyGems

- (which the 2.4 end of this matrix runs) installs it dangling, so the gem ships

- with no licence and exits 0. `test/unit/packaging_test.rb` pins all of those

- claims.

- `.okf/` ships inside the gem, and `rake okf` at the repo root validates and

- lints it. Maintain it in the same commit as the code it documents. A new file

- under `lib/` without a line in the concept that owns its layer is a red suite,

- not a stale document — and so is a view added to `App::TABS` without its row in

- the catalogue.