okf-tui 1.0.0 → 1.1.0

data/.okf/interaction/filter-escalates-to-search.md

@@ -3,7 +3,18 @@ type: Concept
 title: A Dead Filter Offers the Wider Search
 description: Filtering reads metadata in one bundle and searching reads bodies across all of them, so a filter that matches nothing offers the search rather than leaving a dead end.
 tags: [ux, search]
-timestamp: 2026-08-13
+generated:
+  by: human:maintainer
+  at: 2026-08-13
+sources:
+  - title: "`lib/okf/tui/views.rb` — `escalation_panel`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/views.rb
+  - title: "`lib/okf/tui/app.rb` — `filter_found_nothing?`, which is where the two views' conditions live side by side."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/app.rb
+  - title: "`test/integration/search_test.rb` — \"a filter that matches nothing offers the wider search\"."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/search_test.rb
+  - title: "`test/integration/groups_test.rb` — \"a filter matching a group but no bundle has found something\"."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/groups_test.rb
 ---
 
 # Overview
@@ -45,13 +56,3 @@ group and no bundle has found something, and the first cut of this read only the
 bundles pane — so `Enter` escalated on the keystroke that was accepting the
 filter, taking the filter, the view and the group the reader was pointing at with
 it. "The filter found nothing" is a claim about the whole view.
-
-# Citations
-
-[1] `lib/okf/tui/views.rb` — `escalation_panel`.
-[2] `lib/okf/tui/app.rb` — `filter_found_nothing?`, which is where the two views'
-    conditions live side by side.
-[3] `test/integration/search_test.rb` — "a filter that matches nothing offers
-    the wider search".
-[4] `test/integration/groups_test.rb` — "a filter matching a group but no bundle
-    has found something".

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

@@ -1,18 +1,33 @@
 ---
 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.
+description: okf resolves a project-local .okf.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
 
 "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`
+`OKF_NO_DISCOVERY` forces the global registry; otherwise a `.okf.json` — or the
+older `.okf-registry.json`, still discovered so no committed registry breaks —
 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.
+(default `~/.okf`). Both names are checked in each directory before climbing, so
+"nearest local file wins" keeps meaning what it says, 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
@@ -32,6 +47,25 @@ 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".
 
+# A third input arrived, and the answer stayed one method
+
+okf later gained `okf registry link`: the global registry can point at another
+registry file, and that file's bundles and groups resolve into the set. The TUI
+needed no change to show them — `registry_entries` reads `listing` and
+`registry_groups` reads `groups_listing`, and okf folds the linked half into
+both. That is the point. The rule this concept states is that one question has
+one answer per directory; a linked group listed by a *second* method would have
+put the TUI back where it started, showing a smaller set than its own `@ref`
+resolution could open, with nothing failing to say so.
+
+What the TUI had to add for itself is that a linked bundle is **read-only**. The
+config keys reached okf, which refused, and the message arrived on the status
+line — correct, and too late: the user had already typed a new name or confirmed
+a removal. `d`, `n`, `x` and `+` now refuse before the prompt, and the detail
+pane says where the bundle comes from. That is
+[registry-write-boundary](/decisions/registry-write-boundary.md)'s, not this
+file's — what belongs here is only that the *set* stayed one answer.
+
 # The library keeps okf's own line
 
 `cwd:` is a parameter, not a default of `Dir.pwd`, and that mirrors okf exactly:
@@ -69,17 +103,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,61 @@
 # Update Log
 
+## 2026-08-22
+
+* **The project-local registry is `.okf.json`, and the TUI inherits that for
+  free** — [which-registry](interaction/which-registry.md),
+  [registry-write-boundary](decisions/registry-write-boundary.md). okf renamed the
+  file and kept discovering the old `.okf-registry.json`, checking both names in
+  each directory on the way up. `Workspace` needed no change, which is the point
+  of asking okf rather than recomputing: the one method that answers "which
+  registry am I on" answered the new question the moment the kernel did. What the
+  two concepts owed was accuracy — one stated the discovery rule and would have
+  stated half of it, and the other named the file it writes.
+
+## 2026-08-21
+
+* **A linked bundle is read-only, and the four config keys say so before they
+  ask** — [registry-write-boundary](decisions/registry-write-boundary.md),
+  [which-registry](interaction/which-registry.md). okf's registry can now `link`
+  another registry file, whose bundles and groups resolve into the bundles view.
+  They list, load, scope and search like any other — but the file that owns them
+  is elsewhere, so okf refuses every write. `d`, `n`, `x` and `+` reached okf,
+  okf raised, and the message landed on the status line *after* the user had
+  typed a new name or confirmed a removal. They now refuse first, naming the
+  link; the bundle detail carries `read-only — linked from @onm` and the owning
+  file underneath. The registry pane is left alone, because 42 columns cannot
+  take another marker without clipping.
+
+* **Nothing was needed to *show* linked bundles at all.** The entries come from
+  okf's `listing` and the groups from its `groups_listing`, and okf folds the
+  linked half into both rather than into a second method — which is the whole
+  point of [which-registry](interaction/which-registry.md)'s rule, arriving from
+  the kernel's side this time. `Entry#link` and `Group#link` are read off those
+  rows, and an agreement test asserts the field against okf itself, since a
+  rename there would leave every refusal above quietly not firing.
+
+## 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.