okf-tui 1.0.0 → 1.0.1

data/.okf/interaction/following-links.md

@@ -3,7 +3,16 @@ type: Decision
 title: Following a Link Out of the Page
 description: The picker is a mode rather than inline hints, the directory link okf declines to resolve, and the count it deliberately disagrees with.
 tags: [ux, keys, okf-coupling]
-timestamp: 2026-07-19
+generated:
+  by: human:maintainer
+  at: 2026-07-19
+sources:
+  - title: "`lib/okf/tui/model.rb` — `links_for`, `resolve_target`, `describe_link`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/model.rb
+  - title: "`lib/okf/tui/app.rb` — `handle_follow`, `follow_selected`, `push_trail`, `back`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/app.rb
+  - title: "`test/integration/links_test.rb` — the area-link case is the one that would otherwise have been silently empty."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/links_test.rb
 ---
 
 # Overview
@@ -73,10 +82,3 @@ label rather than being reconciled to the header.
 two functions every jump already went through. Opening a search hit and following
 a concept out of the graph became reversible without either being touched, which
 is why the stack lives there rather than in the picker.
-
-# Citations
-
-[1] `lib/okf/tui/model.rb` — `links_for`, `resolve_target`, `describe_link`.
-[2] `lib/okf/tui/app.rb` — `handle_follow`, `follow_selected`, `push_trail`, `back`.
-[3] `test/integration/links_test.rb` — the area-link case is the one that would
-    otherwise have been silently empty.

data/.okf/interaction/key-routing.md

@@ -3,7 +3,12 @@ type: Reference
 title: Key Routing and Its Modes
 description: handle dispatches through modes before the global keys, which is what keeps digits navigating everywhere, and the guard-fallback trap that a Ruby case statement sets for shared letters.
 tags: [ux, keys]
-timestamp: 2026-07-18
+generated:
+  by: human:maintainer
+  at: 2026-07-18
+sources:
+  - title: "`lib/okf/tui/app.rb` — `handle`, `fallback`, `KEY_VIEWS`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/app.rb
 ---
 
 # The order
@@ -78,7 +83,3 @@ later. That is the check worth keeping: an arming that never lets go renders
 identically to the fixed behaviour until the pair is pressed apart.
 
 `Ctrl-c` stays single. An escape hatch that needs confirming is not one.
-
-# Citations
-
-[1] `lib/okf/tui/app.rb` — `handle`, `fallback`, `KEY_VIEWS`.

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

@@ -3,7 +3,20 @@ 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
+generated:
+  by: human:maintainer
+  at: 2026-08-13
+sources:
+  - title: "`lib/okf/tui/workspace.rb` — `open_registry`, and `registry_path` asking the registry rather than recomputing from `home`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/workspace.rb
+  - title: "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."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/registry.rb
+  - title: "okf `CHANGELOG.md` 1.12.0 — `okf registry init`, relative path storage, and the hub bug that `#reopen` fixed."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/CHANGELOG.md
+  - title: "`test/integration/refs_test.rb` — the local/global pair, `OKF_NO_DISCOVERY`, and the embedding-app case that must stay global-only."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/refs_test.rb
+  - title: "Reproduced 2026-08-13 in a scratch project: `Registry.load(cwd: pwd).path` → `<project>/.okf-registry.json`, `Registry.load.path` → `<home>/registry.json`."
+    resource: "Reproduced 2026-08-13 in a scratch project: `Registry.load(cwd: pwd).path` → `<project>/.okf-registry.json`, `Registry.load.path` → `<home>/registry.json`"
 ---
 
 # Overview
@@ -69,17 +82,3 @@ too. That is not decoration — it is the only way a user can tell which of the
 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

@@ -1,5 +1,27 @@
 # Update Log
 
+## 2026-08-19
+
+* **This bundle moved to OKF v0.2.** `timestamp:` became
+  `generated: { by, at }` on all 30 concepts, and the 22 body `# Citations`
+  lists became `sources:` — the text preserved, a GitHub URL where the entry
+  named a real file, a scope descriptor where it recorded a measurement or a
+  repro. Three concepts carried positional `[1]` markers in their bodies; those
+  are now `[^1]` footnotes keyed to `sources[].id`, and the sources nothing
+  cites lost the id rather than keeping a join half-made.
+
+* **The structure and the catalogue moved into this bundle, and a test holds
+  them to the code.** `AGENTS.md` carried a hand-maintained Map of `lib/**` that
+  nothing checked, so a file could arrive, move or leave and the Map would keep
+  reading plausibly. [Structure](/structure/) now owns it — four concepts over
+  ten files — and [Capabilities](/capabilities/) owns the catalogue of the six
+  views and the kernel surface behind them, which is the list to read before
+  building a seventh. `test/unit/bundle_catalog_test.rb` is the pin, and it
+  bites in both directions: a file no concept names, a concept naming a file
+  that is gone, or a view catalogue that disagrees with `App::TABS`. The test
+  suite's own map moved too, to [the-suite](/testing/the-suite.md), and
+  [adding-a-view](/testing/adding-a-view.md) is the walk a new screen owes.
+
 ## 2026-08-15
 
 * **Release**: **1.0.0**, the first. Six views over one bundle or many —

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

@@ -3,7 +3,14 @@ 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
+generated:
+  by: human:maintainer
+  at: 2026-07-19
+sources:
+  - title: "`lib/okf/tui/ui.rb` — the primitives."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/ui.rb
+  - title: "`test/integration/geometry_test.rb` — the two-colour matrix and `with_colour`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/geometry_test.rb
 ---
 
 # Overview
@@ -66,9 +73,3 @@ 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/fit-or-say-so.md

@@ -0,0 +1,34 @@
+---
+type: Constraint
+title: A layout that cannot fit says so
+description: Health is two panes above 112 columns and one at a time below it, reached by the same key either way — a narrow terminal changes what is shown rather than silently clipping it, and a new split is judged by its narrowest column.
+tags: [rendering, layout, terminal, width]
+generated:
+  by: human:maintainer
+  at: 2026-08-19T12:00:00Z
+---
+
+# The rule
+
+A pane that cannot fit its content does not clip it. It stops claiming to show
+both halves.
+
+The health view is the instance: two panes above 112 columns, one pane at a time
+below it, and the **same `Tab`** reaches the other one in both modes. The key
+keeps its meaning across the breakpoint, so nothing a reader has learned stops
+working when they narrow the window — the mode changes, the vocabulary does not.
+
+# How to judge a new split
+
+By what its *narrowest* column does to the longest row it must carry, not by how
+it looks at the width you happen to be developing at.
+
+Health passes that test by construction rather than by tuning: its right pane
+holds a fixed width because every row in it is short by design, and every row
+that carries a path — the ones with no bound on their length — is on the left.
+A split that puts an unbounded row in a fixed column has already failed, and
+will fail invisibly, because at a comfortable width it looks correct.
+
+This is the layout-level form of the same discipline
+[width measurement](ansi-aware-width.md) applies at the character level: a frame
+is only correct if it is correct at the width it was not designed for.

data/.okf/rendering/index.md

@@ -6,3 +6,4 @@ How a frame is composed, and the arithmetic that breaks when colour is involved.
 * [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.
+* [A layout that cannot fit says so](fit-or-say-so.md) - Two panes or one, the same key either way, and a new split judged by its narrowest column rather than by how it looks now.

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

@@ -3,7 +3,14 @@ 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
+generated:
+  by: human:maintainer
+  at: 2026-07-18
+sources:
+  - title: "`lib/okf/tui/app.rb` — `PARSE_WIDTH` and the render."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/app.rb
+  - title: "Reproduced by sweeping every concept × width with colour forced on: 50/192 raised `IndexError`; 0/192 with the fix."
+    resource: "Reproduced by sweeping every concept × width with colour forced on: 50/192 raised `IndexError`; 0/192 with the fix"
 ---
 
 # The symptom
@@ -55,9 +62,3 @@ 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

@@ -3,7 +3,12 @@ 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
+generated:
+  by: human:maintainer
+  at: 2026-07-18
+sources:
+  - title: "`lib/okf/tui/views.rb` — `health_status`, `STATUS`, `status_style`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/views.rb
 ---
 
 # Overview
@@ -39,7 +44,3 @@ 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

@@ -3,7 +3,14 @@ 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
+generated:
+  by: human:maintainer
+  at: 2026-07-18
+sources:
+  - title: "`lib/okf/tui/app.rb` — `paint`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/app.rb
+  - title: "`test/test_helper.rb` — `FixedScreen`, `frame_for`, `render`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/test_helper.rb
 ---
 
 # Overview
@@ -45,8 +52,3 @@ differently on the machine running the suite.
   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/structure/doors.md

@@ -0,0 +1,61 @@
+---
+type: Component
+title: The Doors, and What Loads When
+description: One entry point through okf's plugin seam, an argv shell that loads on demand, and a ref grammar subclassed from okf rather than rewritten.
+tags: [structure, cli, plugin, loading]
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The files
+
+| file | what it owns |
+|---|---|
+| `lib/okf/tui.rb` | `OKF::TUI`, `OKF::TUI::Error`, and the two capability probes |
+| `lib/okf/plugin.rb` | `OKF::CLI::Tui` — registers `okf tui`, the gem's only entry point |
+| `lib/okf/tui/cli.rb` | `OKF::TUI::CLI` — the only layer that parses argv, prints, and exits |
+| `lib/okf/tui/refs.rb` | `OKF::TUI::Refs` — argv to bundle dirs, through okf's own ref grammar |
+| `lib/okf/tui/version.rb` | `OKF::TUI::VERSION` |
+
+# One door, and what that costs the dispatcher
+
+There is **no executable**. `okf tui` is the whole surface, and the reasoning is
+[one-door-the-plugin-seam](/decisions/one-door-the-plugin-seam.md).
+
+The consequence to hold on to: **the dispatcher must add nothing but argv and
+the streams.** `plugin_test.rb` pins it by driving the same run both through
+`OKF::CLI.start` and straight into `CLI.run`, comparing the exit code and the
+message.
+
+`help_rows` is a promise as much as a help line. It read `tui [DIR|@slug…]` for
+a whole release while the CLI rejected every `@slug` as "not a directory", so
+the test now asserts the advertised form actually resolves.
+
+# The ref grammar is okf's
+
+`Refs` subclasses `OKF::CLI::Command`, so `@slug`, a bare `@`, an `@group` and
+the refusal of `@all` mean exactly what they mean to `okf server` — same
+messages, same exit codes. It reaches a *private* helper
+(`resolve_ref_expanding`), which is a deliberate trade: one copy of the grammar,
+at the cost of a coupling that `refs_test.rb` pins **by name**, so okf moving it
+fails loudly rather than quietly restoring "not a directory".
+
+The same call is what opts this gem into registry discovery, since okf's
+`open_registry` is `Registry.load(cwd: Dir.pwd)` — which is why the TUI resolves
+the same registry every other `okf` verb run from that directory resolves. See
+[which-registry](/interaction/which-registry.md).
+
+# What loads when
+
+`require "okf/tui"` loads the library only. `cli.rb` arrives on demand — the
+plugin's `#call` requires it, and so must any test that drives it.
+
+That is not tidiness. okf reads `plugin.rb` whenever a verb misses or `okf help`
+runs, so it must stay cheap: it registers a class and nothing else, and the TTY
+toolkit is required inside `#call`. A subprocess test asserts that loading the
+plugin leaves `TTY::Box` undefined.
+
+`OKF::TUI.search_capable?` and `.spec_capable?` are the other half of that
+caution — they ask the installed okf what it can do rather than assuming a
+version, which is [okf-capability-drift](/decisions/okf-capability-drift.md).

data/.okf/structure/index.md

@@ -0,0 +1,16 @@
+# Structure
+
+Every file under `lib/`, grouped by the layer that owns it. One concept owns
+each file, and `test/unit/bundle_catalog_test.rb` fails if that stops being true
+in either direction — a file no concept names, or a concept naming a file that
+is gone.
+
+Ten files, four layers, and the dependency runs one way: the doors build a
+workspace, the workspace answers questions about bundles, the app holds the
+state and the key loop, and the rendering layer turns that state into rows.
+Nothing below reaches back up.
+
+* [The Doors](doors.md) - `lib/okf/tui.rb`, `lib/okf/plugin.rb`, `lib/okf/tui/cli.rb`, `lib/okf/tui/refs.rb`, `lib/okf/tui/version.rb` — the one entry point, the argv shell, and the ref grammar borrowed rather than rewritten.
+* [The Workspace and the Model](the-workspace.md) - `lib/okf/tui/workspace.rb`, `lib/okf/tui/model.rb` — which bundles a session can see, and every answer about one of them.
+* [The App](the-app.md) - `lib/okf/tui/app.rb` — state, the key loop, and the frame.
+* [The Rendering Layer](rendering.md) - `lib/okf/tui/views.rb`, `lib/okf/tui/ui.rb` — the six screens as row builders, and the primitives that make a row fit.

data/.okf/structure/rendering.md

@@ -0,0 +1,58 @@
+---
+type: Component
+title: The Rendering Layer
+description: Six screens built as rows of text with no terminal I/O, over primitives that measure and cut strings by display width rather than by character count.
+tags: [structure, rendering, ansi, layout]
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The files
+
+| file | pure? | what it owns |
+|---|---|---|
+| `lib/okf/tui/views.rb` | pure | the six screens — row builders, no terminal I/O |
+| `lib/okf/tui/ui.rb` | pure | layout primitives: width, clipping, wrapping, boxes |
+
+Both are pure, and that is the property the test suite is built on: a view
+returns an array of strings, so a test can assert a frame without a pty.
+
+# Views: one builder per screen, plus the chrome
+
+`Views` is a module of builders taking `(app, width, height)` and returning rows.
+Beyond the six screens it owns the chrome every screen wears — `header`,
+`workspace_header`, `tabs`, `footer`, `active_badge` — and the two vocabularies
+that must be identical everywhere: `TYPE_COLOURS` / `type_colour`, and `STATUS` /
+`health_status` / `status_style`.
+
+That second one is the point of [status-vocabulary](/rendering/status-vocabulary.md):
+`validate` and `lint` collapse into **one** verdict so a problem is visible from
+any view, rather than only from the one that ran the check.
+
+`pair` is the label/value row every detail panel is made of, and it is worth
+reusing rather than re-aligning by hand.
+
+# Ui: nothing here counts characters
+
+`String#length` is the wrong answer twice over — a wide CJK glyph occupies two
+columns, and an ANSI escape occupies none — so every primitive here measures
+display width instead. `ANSI` is the escape pattern, `width` the measure, and
+`clip` / `clip_ansi` / `wrap_ansi` / `reflow` the cuts that respect it.
+[ansi-aware-width](/rendering/ansi-aware-width.md) is the arithmetic and why the
+geometry suite runs twice.
+
+`TABULAR` exists because a box-drawing run must not be reflowed as prose, and
+`LIST_START` because a bullet's continuation lines have to hang under its text.
+`reset_if_styled` closes a style at the end of a row so a colour cannot bleed
+into the next one — a frame is printed whole, so one unterminated sequence
+stains everything below it.
+
+`Line` is the builder for a single row under a width budget; `blank_line`,
+`fit_block`, `hjoin`, `box` and `title_label` compose them. `PASTEL` is
+constructed once, with `FORCE_COLOR` honoured, because colour detection is a
+terminal question and the tests need to answer it themselves.
+
+The trap that only appears with colour on is
+[markdown-rendering-trap](/rendering/markdown-rendering-trap.md); read it before
+touching anything that hands a width to tty-markdown.

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

@@ -0,0 +1,55 @@
+---
+type: Component
+title: The App — State, the Key Loop, and the Frame
+description: "One class holding the whole session: which view, which selection, which prompt is open, and the loop that reads a key, changes that state, and repaints every row."
+tags: [structure, keyboard, state, terminal]
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The file
+
+| file | pure? | what it owns |
+|---|---|---|
+| `lib/okf/tui/app.rb` | shell | state, the key loop, frame painting |
+
+It is the largest file in the gem and the only one that reads a keystroke, and
+those two facts are the same fact: everything that is *not* state or input has
+been pushed down into `Views` and `Ui`, or out into `Workspace` and `Model`.
+
+# The tables that define the surface
+
+| constant | what it fixes |
+|---|---|
+| `TABS` | the six views, in the order the tab bar shows them, `help` last |
+| `KEY_VIEWS` | `1`–`6`, the direct jump to each |
+| `SINGLE_BUNDLE_VIEWS` | `browse`, `health`, `graph` — the ones with nothing to show when no bundle can be read |
+| `CONTENT_VIEWS` | `health`, `help` — a scrolling page rather than a selectable list |
+| `FILTERABLE_VIEWS` | `bundles`, `browse`, `graph` — the ones `/` narrows |
+| `PANES` | `bundles`, `groups`, `members` — what Tab cycles inside the bundles view |
+
+There were seven views once. The `index` map went because browse answers the
+same question with a key the reader already has, and what the map could show and
+browse cannot is real but narrow. A seventh tab is a real cost on a six-tab bar.
+
+`Prompt` is a pending question on the status line: `kind` decides what the answer
+does, and `free_text?` says whether it collects a line or a single confirming
+key. Every destructive registry action goes through one.
+
+# The loop, and why the frame is a pure function
+
+`run` reads a key, routes it, and calls `paint`. `paint` moves the cursor home
+and prints exactly `height` rows — no damage tracking, no dirty regions. That is
+what makes a frame a pure function of state, which is in turn what lets the whole
+test suite render without a terminal
+([headless-frames](/testing/headless-frames.md)).
+
+Key routing has modes, and Esc peels one layer at a time rather than quitting
+outright — both arrived at by getting them wrong first:
+[key-routing](/interaction/key-routing.md),
+[esc-peels-one-layer](/interaction/esc-peels-one-layer.md).
+`/` starts a filter, and the filter belongs to the *view*, so switching away
+drops it rather than carrying a bundle filter into the concept list; where the
+filter runs out, [filter-escalates-to-search](/interaction/filter-escalates-to-search.md)
+is what happens next.

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

@@ -0,0 +1,69 @@
+---
+type: Component
+title: The Workspace and the Model
+description: Two files answering two different questions — which bundles this session can see, and everything there is to know about one of them — with the memoization that makes a repaint free.
+tags: [structure, registry, model, memoization]
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The files
+
+| file | pure? | what it owns |
+|---|---|---|
+| `lib/okf/tui/workspace.rb` | shell | the bundles a session can see; the **only** registry writes in the gem |
+| `lib/okf/tui/model.rb` | pure | one bundle, and every answer about it, memoized |
+
+# Workspace: which bundles, and which of them count
+
+`Workspace` holds `Entry` (a bundle: slug, dir, default?, registered?, loaded?)
+and `Group` (a registry group, with `cyclic?` for the one it cannot resolve).
+Its two axes are independent and it is worth stating plainly, because conflating
+them is the mistake the code is shaped to prevent:
+
+* **active** — `switch`, `active`, `model`: the one bundle the single-bundle
+  views are about;
+* **scope** — `scope`, `scoped?`, `toggle_scope`, `scope_all`, `scope_none`,
+  `scope_only`, `scope_group`: the set search runs across.
+
+[cross-bundle-scope](/interaction/cross-bundle-scope.md) is why they are two
+things and not one.
+
+`add`, `remove` and the rest of the mutators are the **only** writes to the
+registry anywhere in this gem, deliberately — the boundary and what it refuses
+are [registry-write-boundary](/decisions/registry-write-boundary.md).
+`registry_backed?` and `registry_path` are how a view says which registry it is
+looking at without guessing.
+
+`search` is the cross-bundle one, and it goes through okf's search facade rather
+than reimplementing ranking — with the sharp edge recorded in
+[search-facade-coupling](/decisions/search-facade-coupling.md).
+
+# Model: every answer about one bundle, computed once
+
+`Model` is pure and **memoized**, and both properties are load-bearing. Pure,
+because the app repaints the entire frame on every keystroke
+([whole-frame-painting](/rendering/whole-frame-painting.md)) and a view that
+recomputed a lint on each one would be unusable. Memoized, for the same reason.
+
+What it already answers — read this before computing anything in a view:
+
+| question | reader |
+|---|---|
+| the bundle's concepts, as rows | `rows`, `row_by_id`, `concept_by_id` |
+| the catalog and the graph | `catalog`, `graph` |
+| conformance and curation | `validation`, `lint`, `skipped_checks` |
+| the two v0.2 postures | `trust_posture`, `status_posture`, `shows_trust?` |
+| size and shape | `concept_count`, `edge_count`, `orphan_ids`, `hubs` |
+| the directory tree | `dirs`, `dir_traffic`, `dir_arcs`, `under_dir?` |
+| the facets | `types`, `tags`, `types_of`, `tags_of`, `statuses_of`, `tiers_of` |
+| what the bundle declares itself to be | `okf_version` |
+
+Every one of those is okf's judgement, not this gem's. `Model` is a reader over
+the kernel's analysers, and the rule that keeps it that way is
+[invents-no-analysis](/decisions/invents-no-analysis.md): a number on screen
+that okf did not compute is a number that will disagree with `okf lint`.
+
+`UNTYPED` and `type_label` are the one exception, and they are labelling rather
+than analysis — a concept with no `type` still needs a row.

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.