okf-tui 1.0.0

data/.okf/interaction/which-registry.md

@@ -0,0 +1,85 @@
+---
+type: Constraint
+title: Which Registry a Session Is On
+description: 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.
+tags: [registry, okf-coupling, discovery]
+timestamp: 2026-08-13
+---
+
+# Overview
+
+"Which bundles can I see?" has one right answer per directory, and okf decides it:
+`OKF_NO_DISCOVERY` forces the global registry; otherwise a `.okf-registry.json`
+found by walking up from the working directory wins; otherwise `$OKF_HOME`
+(default `~/.okf`). Nearest local file wins, and a local registry stores paths
+*relative* to itself so it can be committed and travel with the repo.
+
+The TUI ignored all of that for a release. `Workspace` called
+`OKF::Registry.load(home: home)` with no `cwd:`, and okf only discovers when it is
+handed one — so inside a repo carrying a local registry, `okf registry list` and
+`okf server` read the local file while `okf tui`, one keystroke away, read the
+global one.
+
+# Why it was worse than an error
+
+Nothing failed. The TUI opened, listed bundles, and searched them. It was simply
+answering about a *different set* than every other verb in that directory —
+including the `okf registry list` a user would run to check what the TUI should be
+showing. The two disagreeing is the whole failure, and neither could report it,
+because each was internally consistent.
+
+This is the shape [okf-capability-drift](/decisions/okf-capability-drift.md)
+describes: okf added a resolution rule, the old call kept working, and "kept
+working" meant "kept answering the wrong question".
+
+# The library keeps okf's own line
+
+`cwd:` is a parameter, not a default of `Dir.pwd`, and that mirrors okf exactly:
+only its CLI opts in, while a library caller stays global-only. okf's reason is
+that a discovered registry depends on where a *process happens to be*, which is
+right for a command someone typed in a directory and wrong for an embedding app.
+
+So `OKF::TUI::CLI` passes `cwd: Dir.pwd` and `Workspace.new` defaults to nil. The
+suite depends on this too: with a default, `rake` would discover whatever registry
+sat above the checkout.
+
+Ref resolution gets discovery for free rather than separately —
+`OKF::CLI::Command#open_registry` *is* `Registry.load(cwd: Dir.pwd)`, so a `@slug`
+inherits the rule along with the grammar.
+
+# Reload must reopen, not reconstruct
+
+Every registry write is followed by a re-read, and the re-read has to be
+`Registry#reopen`. `Registry.new(path)` drops the `relative_base` a discovered
+local registry carries — okf hit this in its own server and wrote down the two
+symptoms: every in-tree bundle reads as "folder is gone", and a bundle added
+through the UI gets flattened to an absolute path, undoing the portability the
+relative form exists for.
+
+So `load_entries` discovers on the first load and reopens on every one after:
+
+```ruby
+@registry = (registry ? registry.reopen : open_registry) if registry_backed?
+```
+
+# The screen names the file
+
+The header prints the registry path, and the "nothing to show" message names it
+too. That is not decoration — it is the only way a user can tell which of the two
+registries is in force, and it is what `refs_test.rb` asserts on to prove the CLI
+opts into discovery at all: an empty *local* registry reports the local path,
+where a run that ignored discovery would name the global one.
+
+# Citations
+
+[1] `lib/okf/tui/workspace.rb` — `open_registry`, and `registry_path` asking the
+    registry rather than recomputing from `home`.
+[2] okf `lib/okf/registry.rb` — `Registry.load(home:, cwd:)`, `LOCAL_FILE`,
+    `NO_DISCOVERY_ENV`, and `#reopen` with the comment recording what a bare `new`
+    costs.
+[3] okf `CHANGELOG.md` 1.12.0 — `okf registry init`, relative path storage, and the
+    hub bug that `#reopen` fixed.
+[4] `test/integration/refs_test.rb` — the local/global pair, `OKF_NO_DISCOVERY`, and
+    the embedding-app case that must stay global-only.
+[5] Reproduced 2026-08-13 in a scratch project: `Registry.load(cwd: pwd).path` →
+    `<project>/.okf-registry.json`, `Registry.load.path` → `<home>/registry.json`.

data/.okf/log.md

@@ -0,0 +1,38 @@
+# Update Log
+
+## 2026-08-15
+
+* **Release**: **1.0.0**, the first. Six views over one bundle or many —
+  bundles, browse, search, graph, health, help — with the registry and its
+  groups as editable configuration, and search across every bundle in scope
+  through one shared corpus, so the scores compare between them. It
+  [invents no analysis](decisions/invents-no-analysis.md): okf owns the format,
+  the model, and every question on screen. The floor is `okf >= 2.0, < 3`, and
+  the ceiling is the one exception to
+  [no version ceilings](decisions/no-version-ceilings.md) — earned rather than
+  conventional, because an okf major is where
+  [the silent drift](decisions/okf-capability-drift.md) comes from, and a
+  renamed field read as nil is a wrong number with a green suite either side
+  of it.
+* **Note**: **the gem ships no executable.** `okf tui` is the entry point,
+  registered through [the plugin seam](decisions/one-door-the-plugin-seam.md),
+  so installing the gem is the whole installation. A second binary that only
+  aliased the verb would be one more name to install, document and keep
+  working, and two front ends are two argument grammars that drift while each
+  passes its own tests. What ships instead is one adapter carrying argv and the
+  streams and nothing else, which `plugin_test.rb` pins by running the same
+  invocation both ways and comparing the message.
+* **Note**: **the Rakefile sets its tag prefix behind a guard.**
+  `Bundler::GemHelper#tag_prefix=` arrived in Bundler 2.2, and the Bundler that
+  Ruby 2.4 ships is 1.17.3 — so setting it unconditionally raises
+  `NoMethodError` at Rakefile load on the floor, taking `rake test` down before
+  a single test runs. The [2.4 container](decisions/ruby-floor.md) is what sees
+  that and CI is not: `ruby/setup-ruby` installs a newer Bundler than the Ruby
+  ships. The negative branch *refuses to release* rather than installing the
+  tasks unprefixed — an old Ruby is one to test on, never one to release from,
+  and a bare `vX.Y.Z` tag here fires the Docker build for the okf image.
+* **Creation**: the bundle seeded with 22 concepts across four areas —
+  [decisions](decisions/), [interaction](interaction/),
+  [rendering](rendering/) and [testing](testing/) — deliberately restating
+  neither the `README` (what the views answer, which keys drive them) nor
+  `AGENTS.md` (the contracts a change must keep).

data/.okf/rendering/ansi-aware-width.md

@@ -0,0 +1,74 @@
+---
+type: Component
+title: ANSI-aware Width
+description: Every layout primitive measures display width on colour-stripped text, because String#length counts escape bytes and a composed frame breaks the moment those two disagree.
+tags: [rendering, terminal, ansi]
+timestamp: 2026-07-19
+---
+
+# Overview
+
+The whole composition rests on one invariant: **every painted row measures
+exactly the terminal width.** A row that measures wide pushes the frame's right
+edge into the next line and the layout shears; a row that measures narrow leaves
+the box unclosed.
+
+Colour is what makes this hard. `"\e[31mred\e[0m"` is 3 characters on screen and
+14 in `String#length`, so any primitive that pads, clips, or wraps using
+`#length` is wrong the moment styling is applied — and wrong *invisibly*, because
+the arithmetic is self-consistent.
+
+Every primitive in `Ui` therefore measures on the ANSI-stripped text and operates
+on the styled one:
+
+| Primitive | Does |
+|-----------|------|
+| `Line` | builds a row, tracking `@spent` in display columns |
+| `clip_ansi` | truncates to N columns without cutting an escape in half |
+| `wrap_ansi` | wraps at display width, carrying style across the break |
+| `reflow` | rejoins paragraphs, then wraps them |
+| `fit_block` | pads **and truncates** a block to exact height and width |
+
+# The test has to run twice
+
+Pastel disables colour when stdout is not a terminal. So a captured frame in a
+test is **uncoloured**, which exercises none of the code above — the geometry
+suite would pass while every coloured path was broken.
+
+`GeometryTest` therefore runs the whole matrix twice, swapping the `PASTEL`
+constant for a `Pastel.new(enabled: true)` instance on the second pass: 20
+interaction states × 4 terminal sizes × 2 colour modes. That doubling is not
+thoroughness for its own sake; it is the only pass that tests the ANSI
+arithmetic at all.
+
+`fit_block` originally padded but never truncated, which is precisely the bug
+this catches: markdown longer than the pane overflowed and wrapped the frame.
+
+The invariant exists because nothing
+[repairs a bad row later](/rendering/whole-frame-painting.md) — the frame is
+printed whole and then not touched until the next keypress. And the doubling is
+not paranoia: a bug that lives *only* in the coloured path is exactly what
+[the tty-markdown trap](/rendering/markdown-rendering-trap.md) turned out to be.
+
+# And a third time, on text where a character is not a column
+
+The matrix above asserts each row's *stripped length* equals the width — which
+is only a width assertion on ASCII, where characters and columns are the same
+number. Every fixture was ASCII, so all 6,240 of those assertions passed
+identically whether the layout measured columns or characters. They could not
+tell the two apart.
+
+The `wide` fixture is the case that can: CJK is two columns per character, emoji
+two, a combining mark zero. Six states render it at the same four sizes in both
+colour modes, measured with `Unicode::DisplayWidth` **directly** rather than
+through `Ui.width`, so a regression in `Ui` cannot be validated by a test using
+the same broken measure.
+
+Which matters because `Ui.width` depends on a gem nobody declared — see
+[the undeclared width dependency](/decisions/undeclared-width-dependency.md).
+
+# Citations
+
+[1] `lib/okf/tui/ui.rb` — the primitives.
+[2] `test/integration/geometry_test.rb` — the two-colour matrix and
+    `with_colour`.

data/.okf/rendering/index.md

@@ -0,0 +1,8 @@
+# Rendering
+
+How a frame is composed, and the arithmetic that breaks when colour is involved.
+
+* [ANSI-aware Width](ansi-aware-width.md) - Display width versus `String#length`, the primitives that respect it, and why the geometry suite runs twice.
+* [Whole-frame Painting](whole-frame-painting.md) - Repaint everything each keystroke; the purity that buys, and the constraints it imposes.
+* [The tty-markdown Wrapping Trap](markdown-rendering-trap.md) - An `IndexError` that only appears with colour on, and the parse width that avoids it.
+* [One Verdict, Worn Everywhere](status-vocabulary.md) - Collapsing `validate` and `lint` into one colour so a problem is visible from any view.

data/.okf/rendering/markdown-rendering-trap.md

@@ -0,0 +1,63 @@
+---
+type: Reference
+title: The tty-markdown Wrapping Trap
+description: tty-markdown raises IndexError on some documents when colour is on, so the renderer asks it never to wrap and does its own wrapping instead.
+tags: [rendering, terminal, ansi, scar-tissue]
+timestamp: 2026-07-18
+---
+
+# The symptom
+
+Some concepts rendered as a red error instead of a body. Not all of them, and not
+reproducibly from a test or a screenshot — 50 of 192 concept/width pairs failed.
+
+```
+IndexError: index N out of string
+```
+
+# The cause
+
+`tty-markdown` wraps text through the `strings` gem, which miscounts ANSI escape
+sequences and can compute an insert position past the end of the string. It only
+happens **with colour on**, which is why nothing caught it: Pastel disables
+colour when stdout is not a terminal, so every piped test run and every captured
+screenshot rendered the same documents fine. The bug lived exclusively in the
+interactive path.
+
+# The fix
+
+Take the wrapping away from tty-markdown entirely. It is asked to parse at a
+width no document reaches, and the layout's own
+[ANSI-aware wrapping](/rendering/ansi-aware-width.md) does the real work
+afterwards:
+
+```ruby
+PARSE_WIDTH = 10_000
+
+mode = Ui.pastel.enabled? ? :always : :never
+Ui.reflow(TTY::Markdown.parse(source, width: PARSE_WIDTH, color: mode).lines, limit)
+```
+
+Two details matter and neither is decoration:
+
+- **`PARSE_WIDTH = 10_000`** — large enough that tty-markdown never reaches a
+  wrap decision, so the miscounting code never runs.
+- **explicit `color:`** — tty-markdown otherwise makes its own colour decision,
+  which can disagree with Pastel's and produce escapes the layout did not expect.
+
+The rescue around the render now includes the exception *message*, not just the
+class. The original error surfaced as a bare class name, which said nothing about
+where to look.
+
+# The lesson worth keeping
+
+A rendering bug that only appears with colour on cannot be caught by any test
+that captures output through a pipe. When a screen misbehaves in the terminal but
+not in a test, **suspect the colour path first** — it is the one the harness
+never walks.
+
+# Citations
+
+[1] `lib/okf/tui/app.rb` — `PARSE_WIDTH` and the render.
+[2] Reproduced by sweeping every concept × width with colour forced on: 50/192
+    raised `IndexError`; 0/192 with the fix.

data/.okf/rendering/status-vocabulary.md

@@ -0,0 +1,45 @@
+---
+type: Concept
+title: One Verdict, Worn Everywhere
+description: A bundle is clean, warned, or not conformant, and that single judgement drives its colour in every place it is named — so a problem is visible without opening the health view.
+tags: [rendering, ux]
+timestamp: 2026-07-18
+---
+
+# Overview
+
+`validate` and `lint` answer different questions and the health view keeps them
+in separate sections, as [okf requires](/decisions/invents-no-analysis.md). But a
+*reader* needs one thing at a glance: is this bundle all right?
+
+So the two outputs collapse into one presentational verdict:
+
+| Verdict | Source | Colour |
+|---------|--------|--------|
+| not conformant | `validate` has §9 errors | red |
+| warnings | `validate` is clean, `lint` has findings | orange |
+| clean | both clean | default |
+
+This is a *rendering* of okf's analysis, not a fourth judgement — no check is
+computed here.
+
+# Why it appears everywhere
+
+The verdict follows the bundle's name into every place the name appears: the
+header, the footer badge, its row in the registry list, its detail pane, and the
+health tab's own label.
+
+The health tab carrying it is the point of the design. Without it a reader has to
+*visit* the health view to learn there is anything to see, which means the
+common case — nothing wrong — costs a trip, and the uncommon case is invisible
+until you happen to look. Colouring the tab makes the bundle's state ambient:
+you find out from wherever you already are.
+
+Because the colour is attached to the name rather than to a view, switching the
+active bundle changes it everywhere at once, which is what makes it readable
+while moving between bundles — see
+[cross-bundle-scope](/interaction/cross-bundle-scope.md).
+
+# Citations
+
+[1] `lib/okf/tui/views.rb` — `health_status`, `STATUS`, `status_style`.

data/.okf/rendering/whole-frame-painting.md

@@ -0,0 +1,52 @@
+---
+type: Component
+title: Whole-frame Painting
+description: Each keystroke repaints every row from cursor-home rather than diffing, which makes a frame a pure function of state and is what lets the tests render without a terminal.
+tags: [rendering, terminal, testing]
+timestamp: 2026-07-18
+---
+
+# Overview
+
+There is no damage tracking, no dirty-region diffing, and no partial redraw.
+`paint` moves the cursor home and prints exactly `height` rows, every time.
+
+For a screen of this size the redraw is imperceptible, and buying simplicity with
+it is a good trade — but the real payoff is not performance, it is testability.
+
+# Why it makes the UI testable
+
+Because painting reads state and writes a string, a frame is a **pure function of
+(workspace, keys, size)**. Nothing about it needs a terminal:
+
+```ruby
+app = App.new(dirs: [...], output: StringIO.new)
+FixedScreen.with(width, height) { keys.each { |key| app.handle(key) } }
+```
+
+`handle` mutates state exactly as the key loop does, and `paint` renders it into
+a `StringIO`. So the tests drive real interactions and assert on real frames
+without a pty — see [headless-frames](/testing/headless-frames.md). A diffing
+renderer would have made the output depend on what was on screen *before*, and
+that property would be gone.
+
+The terminal size is the only ambient input, so `FixedScreen` pins it by
+prepending an override onto `TTY::Screen` — otherwise a frame would render
+differently on the machine running the suite.
+
+# The consequences to respect
+
+- **Every row must be exactly the width** — nothing repairs a short row on the
+  next pass, because there is no next pass until a key arrives. See
+  [ansi-aware-width](/rendering/ansi-aware-width.md).
+- **The frame must fit the height** — a view that builds more rows than the
+  terminal has scrolls its own content; it never lets the frame overflow. Health,
+  graph and help each build the full page and scroll it, which replaced an
+  earlier per-pane budget that could go negative on a short terminal and crash.
+- **Views stay pure row builders.** No view writes to the terminal; they return
+  arrays of rows. The app is the only thing that prints.
+
+# Citations
+
+[1] `lib/okf/tui/app.rb` — `paint`.
+[2] `test/test_helper.rb` — `FixedScreen`, `frame_for`, `render`.

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

@@ -0,0 +1,80 @@
+---
+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
+---
+
+# The matrix
+
+The repository's `.github/workflows/main.yml` runs this gem's default task on
+Ruby 2.4 through 4.0 as its own `okf-tui` job — 2.4/2.5/2.6 on `ubuntu-22.04`,
+the rest on `ubuntu-latest`, since the older Rubies predate the current image's
+toolchain. `fail-fast: false`, so one failure does not hide the others. It is one
+job per gem rather than a gem axis on one matrix, because the gems in the
+repository do not share a Ruby floor. A change is not done until the matrix is
+green.
+
+The floor can also be proven locally, which is faster than pushing. Run it from
+the repository root and let it step in here — the Gemfile resolves okf from
+`../okf`, so a container holding only this directory fails at `bundle install`
+before a test runs:
+
+```bash
+docker run --rm -v "$PWD":/src:ro ruby:2.4 bash -c \
+  "cp -a /src /build && cd /build/okf-tui && rm -f Gemfile.lock && bundle install --quiet && bundle exec rake test"
+```
+
+The copy and the dropped lockfile are both load-bearing: a lockfile written by a
+modern Bundler is one 2.4's own cannot read, and mounting read-only stops the run
+writing one back.
+
+**This container runs an older Bundler than CI does, and that is a feature.**
+`ruby/setup-ruby` installs the newest Bundler each Ruby accepts; the image ships
+the one the Ruby came with — 1.17.3 on 2.4. The gap is a real support claim, and
+it caught a Rakefile that could not *load* there: `GemHelper#tag_prefix=` arrived
+in Bundler 2.2, so the line that keeps this gem's release tags prefixed raised
+`NoMethodError` before `rake test` reached a test. The matrix would have been
+green over it.
+
+# What the matrix cannot catch
+
+A green run proves the code against the okf on this disk, not the okf a user
+gets: the Gemfile resolves the kernel from the checkout next door, so every run
+— local, CI, the floor container — exercises the *unreleased* kernel, and
+nothing crosses to RubyGems by default. When two runs of identical code
+disagree, suspect dependency resolution before suspecting the runner.
+
+Two things stand in that gap, and they cover different halves:
+
+- `test/unit/gemspec_test.rb` fails the moment okf bumps and the gemspec's
+  declared floor does not follow, so the floor can never quietly come to admit a
+  kernel this code has outgrown.
+- A scripted run against the *published* okf catches what a floor cannot
+  express, which is that a released kernel returns different analysis output:
+
+  ```bash
+  sed '/gem "okf", path:/d' Gemfile > Gemfile.ci-check
+  BUNDLE_GEMFILE=Gemfile.ci-check bundle install && BUNDLE_GEMFILE=Gemfile.ci-check bundle exec rake
+  ```
+
+Run it before pushing anything that reads okf's analysis, and before a release.
+Nothing enforces it, which is the honest state: it is a maintainer obligation,
+and saying so is better than believing the matrix covers it.
+
+Two details keep that reproduction honest:
+
+- **`Gemfile.lock` is gitignored**, so there is no committed resolution to mask
+  a broken one — every run re-resolves.
+- **A plain `cp` of the tree keeps the untracked lockfile**, and that lockfile
+  can carry a `PATH` remote naming an absolute directory on this machine — so a
+  copy made to test the published resolution can quietly resolve against
+  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

@@ -0,0 +1,74 @@
+---
+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
+---
+
+# The shape
+
+Because [painting is a pure function of state](/rendering/whole-frame-painting.md),
+a test needs no terminal — only a key script and a size:
+
+```ruby
+render(home: home, keys: "4<enter><tab>", size: [ 100, 30 ])
+```
+
+`keystrokes` maps `<enter>`, `<tab>`, `<esc>`, `<down>` to the real bytes, so a
+script reads as what a user actually pressed. `app_for` drives `handle`;
+`frame_for` renders through a `StringIO`; `FixedScreen` pins the size.
+
+Bundles come from `with_registry`, which builds a temporary `$OKF_HOME`. Nothing
+in the suite ever touches the real `~/.okf` — that is the user's configuration,
+not the suite's.
+
+# Prefer naming over counting
+
+`app.open_concept("overview")` rather than three `<down>` presses. The list holds
+reserved files as well as concepts, so cursor arithmetic is a guess about
+ordering rather than a statement about which concept is open — and it breaks
+whenever a fixture gains a file, in a way that looks like a real failure.
+
+# Prove the check can fail
+
+The discipline that mattered most here, because it repeatedly caught checks that
+could not have failed:
+
+- a geometry check reported "ok" on a frame that had **crashed** and rendered
+  empty — zero rows trivially satisfied "every row is the right width";
+- a check looped over the very constant it was testing, so it agreed with itself;
+- a scroll check judged an offset against a different window than the view used,
+  and reported a failure that was not real.
+
+So: **sabotage the code, watch the check fail for the reason you predicted, then
+restore it.** A green check that has never been seen red is an assumption wearing
+a test's clothes.
+
+The sharpest case was a whole suite that could not fail: 6,240 geometry
+assertions that passed identically whether the layout measured columns or
+characters, because every fixture was ASCII and the two numbers agree there.
+Reducing `Ui.width` to `plain.length` was the sabotage that proved it — the
+suite stayed green, and only a fixture of
+[wide characters](/decisions/undeclared-width-dependency.md) turned it red. The same rule as the repo's test-first discipline, applied to
+the harness itself — a bug report earns a red test before it earns a patch, and
+the red has to be for the predicted reason, not a missing fixture or a typo'd
+regex.
+
+Assertions must also be read off real output: run it, read what it actually
+prints, then assert *that*. Asserting what you assume the code does is how a
+green suite certifies a bug.
+
+# What this layer cannot catch
+
+Two things, each covered elsewhere because no headless frame can reach them:
+
+- a broken key loop, a raw-mode failure, or a binary that will not boot — that is
+  [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

@@ -0,0 +1,8 @@
+# Testing
+
+How a full-screen terminal app is proven, and what each layer can and cannot
+catch.
+
+* [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.

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

@@ -0,0 +1,73 @@
+---
+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
+---
+
+# Why it exists
+
+Every other test calls `App#handle` directly and never opens a terminal, so none
+of them can catch a broken key loop, a raw-mode failure, or a verb that will not
+boot. This one spawns a real process through a real pty, sends real keypresses,
+walks all six views, quits on `q`, and asserts the exit status — plus that the
+registry file is byte-identical afterwards.
+
+**It spawns okf's executable, not one of this gem's, because this gem has none**
+— the [plugin seam](/decisions/one-door-the-plugin-seam.md) is the only entry
+point. That is not a workaround; it is what makes this test cover more than it
+used to. It is now the only place the *whole* path a user walks is exercised:
+okf boots, misses `tui` among its built-ins, discovers `okf/plugin.rb` on the
+load path, registers the verb, and hands it a real terminal. Every other plugin
+test drives the dispatcher in-process, which skips process boot and discovery
+both.
+
+The executable is asked of RubyGems (`Gem.bin_path("okf", "okf")`) rather than
+guessed from a relative path: okf is a path source inside the monorepo and an
+ordinary gem outside it, and this has to keep working either way.
+
+It is deliberately *one* test. A pty is slow and timing-dependent; the cheap
+[headless frames](/testing/headless-frames.md) carry the coverage, and this
+carries the proof that the thing boots and runs at all.
+
+# The three traps
+
+Each of these was a real failure on the Ruby 2.4 floor, and each looks like a
+different bug than it is:
+
+**No `$TERM`.** `tty-cursor` shells out to `tput`. A container or CI runner
+without `TERM` set paints *nothing at all* — which reads as a hung app, not a
+missing environment variable. The spawn passes `"TERM" => "xterm"`.
+
+**An unsized pty.** `TTY::Screen` asks the pty itself before it reads `LINES`
+and `COLUMNS`, and an unsized pty reports nothing, so the app paints an empty
+frame. `reader.winsize = [ 40, 120 ]` after spawn, not just the env vars.
+
+# The spawn's environment is the isolation
+
+The child gets `OKF_HOME` named explicitly, alongside `TERM`/`LINES`/`COLUMNS`.
+That is not tidiness: since [`--home` was dropped](/decisions/one-door-the-plugin-seam.md)
+it is the **only** lever on which registry the binary reads, and this is the one
+test that runs a real process against a real registry file. Naming it rather
+than trusting inheritance is what keeps the run off the user's own `~/.okf` —
+the thing the byte-identical assertion above would otherwise be checking on
+*their* file.
+
+**Settling on the first byte.** The app hides the cursor *before* it does any
+work, so the first bytes arrive immediately while the real boot — Bundler setup,
+gem loads, reading every bundle — happens after them. A settle that starts its
+short idle timer on the first byte therefore declares an app "settled" before it
+has painted, which is exactly what happened on 2.4. The wait is generous until
+the buffer contains a `\n`, and short after: a painted frame always has newlines,
+the escape sequences before it do not.
+
+# Send one control key per step
+
+`"\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`.