okf-tui 1.0.0 → 1.0.1

checksums.yaml

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

data/.okf/capabilities/index.md

@@ -0,0 +1,13 @@
+# Capabilities
+
+What this program can already answer, and where the answer comes from. Read it
+before building a view, a panel or a computation — the point of a catalogue is
+that the seventh screen is not the third screen under a new name, and that a
+number on it is one okf computed.
+
+`test/unit/bundle_catalog_test.rb` compares the view catalogue against
+`App::TABS`, so a view added to the code and not to the catalogue is a red suite
+rather than a stale document.
+
+* [The Six Views](views.md) - What each screen answers, which keys reach it, and which reader backs it.
+* [The okf Surface](okf-surface.md) - Every kernel call this gem makes, and the rule that keeps the list short.

data/.okf/capabilities/okf-surface.md

@@ -0,0 +1,48 @@
+---
+type: Capability
+title: The okf Surface This Gem Uses
+description: Every kernel call the TUI makes, in one list — because the rule is that okf owns every judgement on screen, and a number this gem computed is a number that will disagree with `okf lint`.
+tags: [okf, boundary, capabilities]
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The rule first
+
+**This program invents no analysis.** Everything on screen is a pure call on an
+in-memory bundle the kernel built. The argument, and what it costs, is
+[invents-no-analysis](/decisions/invents-no-analysis.md).
+
+So this list is short on purpose, and the right instinct on finding it does not
+cover your case is to ask whether the kernel should answer it — not to compute it
+here.
+
+# What is actually called
+
+| kernel surface | reached through | shows up as |
+|---|---|---|
+| `Bundle` / reader | `Model#catalog` | every row in browse |
+| `Bundle::Graph` | `Model#graph` | the graph view, `hubs`, `orphan_ids`, `edge_count` |
+| `Bundle::Validator` | `Model#validation` | health's conformance findings |
+| `Bundle::Linter` | `Model#lint`, `#skipped_checks` | health's curation findings, and the confession of what did not run |
+| `Bundle::Search` | `Workspace#search` | the search view, across the whole scope |
+| `Registry` | `Workspace` | the bundles view, and the only writes this gem makes |
+| `CLI::Command` ref grammar | `Refs` | `@slug`, bare `@`, `@group`, and the refusal of `@all` |
+| `Concept` trust/status | `Model#trust_posture`, `#status_posture` | the v0.2 chips and the one verdict |
+
+Two of those are pinned against the CLI rather than trusted: the directory tree
+is asserted against `okf dirs --json`, and the cohesion table against
+`okf graph --traffic`, so the screen and the command cannot drift apart.
+
+# The two probes
+
+`OKF::TUI.search_capable?` and `.spec_capable?` ask the *installed* okf what it
+can do, rather than inferring it from a version number. That is
+[okf-capability-drift](/decisions/okf-capability-drift.md), and it is why this
+gem carries [no version ceilings](/decisions/no-version-ceilings.md): a probe
+degrades a feature, a ceiling refuses to install.
+
+The one place the coupling is sharper than a probe can cover is the search
+facade — [search-facade-coupling](/decisions/search-facade-coupling.md) is the
+edge, and it is a private-surface dependency pinned by name in the suite.

data/.okf/capabilities/views.md

@@ -0,0 +1,48 @@
+---
+type: Capability
+title: The Six Views
+description: What each screen answers, whether it is about one bundle or the whole scope, which keys reach it, and which reader supplies its numbers.
+tags: [views, keyboard, capabilities]
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# The catalogue
+
+`App::TABS` is the source of truth for this table, and a test holds the two
+together.
+
+| view | key | answers | reads |
+|---|---|---|---|
+| `bundles` | `1` | what can I open, which is active, which is the default — the registry's groups, and all registry config | `Workspace` |
+| `browse` | `2` | what is in the bundle, in reading order — `index.md`, `log.md`, then each directory | `Model#rows`, `#dirs` |
+| `search` | `3` | which concept covers X, across *every bundle in scope*, ranked together | `Workspace#search` |
+| `graph` | `4` | what shape is its knowledge — narrowed by type, tag or dir | `Model#graph`, `#types`, `#tags` |
+| `health` | `5` | is it legal, well curated, well structured — findings left, standing right | `Model#validation`, `#lint`, `#hubs`, `#dir_traffic`, `#dir_arcs` |
+| `help` | `6` | the keys | — |
+
+# Which of them are about *one* bundle
+
+`browse`, `graph` and `health` are `SINGLE_BUNDLE_VIEWS`: they follow the
+**active** bundle, and they have nothing to show when none can be read. `search`
+follows the **scope** instead — a different, independent axis, so you can read
+one bundle while searching all of them. `bundles` is where both are set.
+
+That two-axis model is the thing most likely to be got wrong by a new view, and
+[cross-bundle-scope](/interaction/cross-bundle-scope.md) is the argument for it.
+
+# The two behaviours every view inherits
+
+`health` and `help` are `CONTENT_VIEWS` — a single scrolling page rather than a
+selectable list, which changes what the arrow keys mean.
+
+`bundles`, `browse` and `graph` are `FILTERABLE_VIEWS` — `/` starts typing, and
+the filter belongs to the view, so switching away drops it. When a browse filter
+matches nothing, `Enter` carries the term to search, because that is the query
+the reader was already making:
+[filter-escalates-to-search](/interaction/filter-escalates-to-search.md).
+
+A seventh view is a real cost on a six-tab bar, and one has already been
+withdrawn for not earning its tab. Before adding one, check that an existing
+view with a key the reader already has does not answer the same question.

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

@@ -3,7 +3,14 @@ type: Decision
 title: It Invents No Analysis
 description: Every judgement on screen is a pure call into okf; the TUI adds no check, score, or verdict of its own, which bounds what a feature request may be answered with.
 tags: [okf-coupling, dependencies]
-timestamp: 2026-07-19
+generated:
+  by: human:maintainer
+  at: 2026-07-19
+sources:
+  - title: "`lib/okf/tui.rb` — the module comment stating the split."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui.rb
+  - title: "`lib/okf/tui/model.rb`, `lib/okf/tui/workspace.rb` — every analysis is a memoized call into okf."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/model.rb
 ---
 
 # Overview
@@ -45,9 +52,3 @@ construction* — implementing a fallback search here would have broken this rul
 That one has since resolved (okf 1.9.0 shipped the facade), which is the point
 rather than a footnote: the cost of this rule is paid in **waiting**, not in
 capability. The wait ended, and nothing had to be built twice.
-
-# Citations
-
-[1] `lib/okf/tui.rb` — the module comment stating the split.
-[2] `lib/okf/tui/model.rb`, `lib/okf/tui/workspace.rb` — every analysis is a
-    memoized call into okf.

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

@@ -3,7 +3,14 @@ type: Decision
 title: No Version Ceilings on the Markdown Stack
 description: Pinning kramdown and rouge to their old lines to protect the Ruby 2.4 floor broke modern Ruby instead; the gems declare their own floors, so resolution handles it per-Ruby.
 tags: [ruby-floor, dependencies]
-timestamp: 2026-07-18
+generated:
+  by: human:maintainer
+  at: 2026-07-18
+sources:
+  - title: "`okf-tui.gemspec` — the two floors, with the comment recording the failed ceiling attempt."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/okf-tui.gemspec
+  - title: "Verified in `ruby:2.4` (Docker): resolved kramdown 2.4.0 + rouge 3.30.0, 34 runs / 6622 assertions green, and green across the whole matrix up to 4.0."
+    resource: "Verified in `ruby:2.4` (Docker): resolved kramdown 2.4.0 + rouge 3.30.0, 34 runs / 6622 assertions green, and green across the whole matrix up to 4.0"
 ---
 
 # Overview
@@ -59,11 +66,3 @@ So `< 3` buys the one thing a floor cannot: it turns the *next* one into a
 resolution failure a maintainer reads, instead of a wrong number a reader
 believes. `test/unit/gemspec_test.rb` pins both bounds — the floor may never lag
 the kernel this gem develops against, and the ceiling may not quietly go away.
-
-# Citations
-
-[1] `okf-tui.gemspec` — the two floors, with the comment recording the failed
-    ceiling attempt.
-[2] Verified in `ruby:2.4` (Docker): resolved kramdown 2.4.0 + rouge 3.30.0,
-    34 runs / 6622 assertions green, and green across
-    [the whole matrix](/testing/ci-matrix.md) up to 4.0.

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

@@ -3,7 +3,22 @@ type: Decision
 title: okf Moves, and This Breaks Quietly
 description: Inventing no analysis means every answer on screen is okf's — so okf renaming a field or adding a faster path is a change to this program, and every such drift found so far failed silently rather than loudly.
 tags: [okf-coupling, dependencies, testing, maintenance]
-timestamp: 2026-08-13
+generated:
+  by: human:maintainer
+  at: 2026-08-13
+sources:
+  - title: "`okf-tui.gemspec` — the seven capabilities and the version each shipped in."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/okf-tui.gemspec
+  - title: "`test/integration/dirs_test.rb` — `okf_subtree_counts`, the `okf dirs --json` oracle; and the `nested` fixture, which exists because at one directory level `dir` and `top_dir` are the same string and an assertion cannot tell them apart."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/dirs_test.rb
+  - title: "`test/integration/structure_test.rb` — `okf_traffic_rows`, parsing okf's human traffic table; the row count is asserted first so the comparison loop cannot pass vacuously."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/structure_test.rb
+  - title: "`lib/okf/tui/refs.rb` — the inherited grammar, and why it subclasses Command without ever being registered."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/refs.rb
+  - title: "okf `CHANGELOG.md`, 1.12.0 \"Changed\": \"The derived `area` field is renamed `top_dir`\" — \"`area` was never the OKF spec's word (`grep -ci area SPEC.md` → 0)\"."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/CHANGELOG.md
+  - title: "Measured 2026-08-13 over five registered bundles / 129 concepts: first query 391.8 ms, then 16.2 / 13.0 / 12.0 / 14.4 ms. Before, every query paid the first figure."
+    resource: "Measured 2026-08-13 over five registered bundles / 129 concepts: first query 391.8 ms, then 16.2 / 13.0 / 12.0 / 14.4 ms. Before, every query paid the first figure"
 ---
 
 # Overview
@@ -101,20 +116,3 @@ was a *number this program did not have to compute*, and three of the four were
 okf getting better at answering it. A TUI with its own catalog would not have had
 the `area` break — it would have had its own, permanently, with no upstream to
 inherit the fix from.
-
-# Citations
-
-[1] `okf-tui.gemspec` — the seven capabilities and the version each shipped in.
-[2] `test/integration/dirs_test.rb` — `okf_subtree_counts`, the `okf dirs --json`
-    oracle; and the `nested` fixture, which exists because at one directory level
-    `dir` and `top_dir` are the same string and an assertion cannot tell them apart.
-[3] `test/integration/structure_test.rb` — `okf_traffic_rows`, parsing okf's human
-    traffic table; the row count is asserted first so the comparison loop cannot
-    pass vacuously.
-[4] `lib/okf/tui/refs.rb` — the inherited grammar, and why it subclasses Command
-    without ever being registered.
-[5] okf `CHANGELOG.md`, 1.12.0 "Changed": "The derived `area` field is renamed
-    `top_dir`" — "`area` was never the OKF spec's word (`grep -ci area SPEC.md` → 0)".
-[6] Measured 2026-08-13 over five registered bundles / 129 concepts: first query
-    391.8 ms, then 16.2 / 13.0 / 12.0 / 14.4 ms. Before, every query paid the first
-    figure.

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

@@ -3,7 +3,20 @@ type: Decision
 title: One door — the plugin seam is the entry point
 description: okf-tui ships no executable; `okf tui` is the only way in, and the registration stays cheap enough that a run wanting `okf lint` pays nothing for it.
 tags: [okf-coupling, dependencies, cli]
-timestamp: 2026-07-19T18:00:00Z
+generated:
+  by: human:maintainer
+  at: 2026-07-19T18:00:00Z
+sources:
+  - title: "`lib/okf/plugin.rb` — the whole seam, including why the heavy require is in `#call`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/plugin.rb
+  - title: "`okf-tui.gemspec` — the comment recording why there is no `spec.executables`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/okf-tui.gemspec
+  - title: "`test/integration/plugin_test.rb` — the dispatcher adding nothing but the streams, and the subprocess check that registering does not load tty-box."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/plugin_test.rb
+  - title: "`test/integration/terminal_test.rb` — okf's own executable on a real pty, the one test that walks process boot and plugin discovery rather than the in-process dispatcher."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/terminal_test.rb
+  - title: "Verified 2026-07-19: `okf --help` lists `tui` under `installed extensions:`; `okf validate` still runs without triggering discovery at all."
+    resource: "Verified 2026-07-19: `okf --help` lists `tui` under `installed extensions:`; `okf validate` still runs without triggering discovery at all"
 ---
 
 # Overview
@@ -20,7 +33,7 @@ simply inert.
 Installing the gem is the whole installation. There is no config file, no
 `okf plugin add`, and nothing to edit in okf — which is the point of a convention
 over a list. See okf's
-[extension points](https://github.com/serradura/okf-gem/blob/main/.okf/design/extension-points.md).
+[extension points](https://github.com/serradura/okf/blob/main/.okf/design/extension-points.md).
 
 # One front end, because two would drift
 
@@ -117,15 +130,3 @@ The library keyword is untouched: `App` and `Workspace` still take `home:`, whic
 is how an embedding app and the suite name a registry without mutating a
 process-global. That is exactly the split okf itself draws — the env var is the
 CLI's only lever, the keyword is the library's.
-
-# Citations
-
-[1] `lib/okf/plugin.rb` — the whole seam, including why the heavy require is in `#call`.
-[2] `okf-tui.gemspec` — the comment recording why there is no `spec.executables`.
-[3] `test/integration/plugin_test.rb` — the dispatcher adding nothing but the
-    streams, and the subprocess check that registering does not load tty-box.
-[4] `test/integration/terminal_test.rb` — okf's own executable on a real pty, the
-    one test that walks process boot and plugin discovery rather than the
-    in-process dispatcher.
-[5] Verified 2026-07-19: `okf --help` lists `tui` under `installed extensions:`;
-    `okf validate` still runs without triggering discovery at all.

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

@@ -3,7 +3,20 @@ type: Decision
 title: It Writes the Registry, Never a Bundle
 description: The line the TUI's side effects sit on is not read-versus-write — it is the registry versus the knowledge; what that admits, what it excludes, and why `registry init` is on the far side of it.
 tags: [registry, boundary, side-effects]
-timestamp: 2026-08-13
+generated:
+  by: human:maintainer
+  at: 2026-08-13
+sources:
+  - title: "`lib/okf/tui/workspace.rb` — the seven writes, each returning a status message and reloading; `not_registry_backed` for the ad-hoc case, which has no registry to change."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/workspace.rb
+  - title: "`AGENTS.md` — \"The registry is the user's configuration\", the same boundary where a change is judged."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/AGENTS.md
+  - title: "`grep -rn \"Bundle::Writer\" lib/` → no matches, 2026-08-13."
+    resource: "`grep -rn \"Bundle::Writer\" lib/` → no matches, 2026-08-13"
+  - title: "okf `CHANGELOG.md` 1.12.0 — `okf registry init`, and the discovery rule that makes the nearest `.okf-registry.json` win."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/CHANGELOG.md
+  - title: "`test/test_helper.rb` — `with_registry`, `with_local_registry`, and the `$OKF_HOME` save/restore around both."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/test_helper.rb
 ---
 
 # Overview
@@ -21,7 +34,7 @@ The line is **the registry, not read-versus-write**: this program edits the user
 
 Seven of okf's eight `registry` verbs have a place here, and it is the same place —
 the bundles view, where `Workspace` owns every write and each is followed by a
-reload, per `AGENTS.md` constraint 8:
+reload, per `AGENTS.md`'s rule that the registry is the user's configuration:
 
 | Key | `Workspace` | okf CLI |
 |-----|-------------|---------|
@@ -161,15 +174,3 @@ because okf's own API refuses to produce them: a member naming nothing registere
 and a cycle (`group cycle: @g would contain itself`). Both are legitimate things
 to survive, since okf invites you to *commit* a local registry — so a hand-edited
 file is a normal input, not an abuse.
-
-# Citations
-
-[1] `lib/okf/tui/workspace.rb` — the seven writes, each returning a status message
-    and reloading; `not_registry_backed` for the ad-hoc case, which has no registry
-    to change.
-[2] `AGENTS.md` constraint 8 — the same boundary, stated where a change is judged.
-[3] `grep -rn "Bundle::Writer" lib/` → no matches, 2026-08-13.
-[4] okf `CHANGELOG.md` 1.12.0 — `okf registry init`, and the discovery rule that
-    makes the nearest `.okf-registry.json` win.
-[5] `test/test_helper.rb` — `with_registry`, `with_local_registry`, and the
-    `$OKF_HOME` save/restore around both.

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

@@ -3,14 +3,21 @@ type: Decision
 title: Ruby 2.4 Floor, Inherited
 description: okf-tui takes okf's floor rather than its own, which costs the ergonomic syntax and forces the development tooling to load conditionally.
 tags: [ruby-floor, dependencies]
-timestamp: 2026-07-18
+generated:
+  by: human:maintainer
+  at: 2026-07-18
+sources:
+  - title: "`okf-tui.gemspec`, `Gemfile`, `Rakefile`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/okf-tui.gemspec
+  - title: "Verified in `ruby:2.4` (Docker) and on CI, which runs 2.4 through 4.0."
+    resource: "Verified in `ruby:2.4` (Docker) and on CI, which runs 2.4 through 4.0"
 ---
 
 # Overview
 
-`required_ruby_version = ">= 2.4.0"`, taken from [okf](@okf), which takes it from
-rack. A UI over a library that runs on the Ruby an OS already ships would be a
-strange thing to require a newer Ruby for.
+`required_ruby_version = ">= 2.4.0"`, taken from okf (`@okf design/ruby-floor`),
+which takes it from rack. A UI over a library that runs on the Ruby an OS
+already ships would be a strange thing to require a newer Ruby for.
 
 The cost lands in two places that are not obvious until you hit them.
 
@@ -52,8 +59,3 @@ the floor.
 
 Nothing is pinned *down* to make this work — see
 [no-version-ceilings](/decisions/no-version-ceilings.md).
-
-# Citations
-
-[1] `okf-tui.gemspec`, `Gemfile`, `Rakefile`.
-[2] Verified in `ruby:2.4` (Docker) and on CI, which runs 2.4 through 4.0.

data/.okf/decisions/search-facade-coupling.md

@@ -3,7 +3,24 @@ type: Decision
 title: The Search Facade Coupling
 description: The search view rides okf's engine facade — `across` for the routing, and since okf 1.11.0 a corpus prepared once and queried many times; the `fuzzy` flag is what selects the engine, and it is load-bearing in a way it does not look.
 tags: [okf-coupling, search, dependencies]
-timestamp: 2026-08-13
+generated:
+  by: human:maintainer
+  at: 2026-08-13
+sources:
+  - id: "1"
+    title: "Verified 2026-07-19 in a clean `ruby:3.2-slim` container — no checkout, no bundler: `gem install okf` resolved 1.9.0, `Bundle::Search.respond_to?(:across)` → `true`, `engine_for([:fuzzy])` → `OKF::Bundle::Search::Index`. RubyGems lists okf 1.9.0 as the current release."
+    resource: "Verified 2026-07-19 in a clean `ruby:3.2-slim` container — no checkout, no bundler: `gem install okf` resolved 1.9.0, `Bundle::Search.respond_to?(:across)` → `true`, `engine_for([:fuzzy])` → `OKF::Bundle::Search::Index`. RubyGems lists okf 1.9.0 as the current release"
+  - id: "2"
+    title: "Verified 2026-07-19 against the okf checkout: `engine_for([:fuzzy])` → `index`, `engine_for([])` → `scan`; `DEFAULT_ENGINE = :scan` in `lib/okf/bundle/search.rb`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf/lib/okf/bundle/search.rb
+  - id: "3"
+    title: "Measured 2026-08-13 against the registry's own five bundles (129 concepts): `across` per query 391.8 ms; with a held corpus 16.2 / 13.0 / 12.0 / 14.4 ms after the first. On the six test fixtures (36 concepts): 62–80 ms against 2.7–3.0 ms."
+    resource: "Measured 2026-08-13 against the registry's own five bundles (129 concepts): `across` per query 391.8 ms; with a held corpus 16.2 / 13.0 / 12.0 / 14.4 ms after the first. On the six test fixtures (36 concepts): 62–80 ms against 2.7–3.0 ms"
+  - id: "4"
+    title: "Reproduced 2026-07-18: `ruby -Ilib` outside bundler loaded okf 1.8.0 from the mise gem path, `Bundle::Search.respond_to?(:across)` → `false`, search returned 0 hits for a term the checkout finds. Under `bundle exec` the same query returned 1 hit (\"orphan\") and 11 (\"registry\")."
+    resource: "Reproduced 2026-07-18: `ruby -Ilib` outside bundler loaded okf 1.8.0 from the mise gem path, `Bundle::Search.respond_to?(:across)` → `false`, search returned 0 hits for a term the checkout finds. Under `bundle exec` the same query returned 1 hit (\"orphan\") and 11 (\"registry\")"
+  - title: "`lib/okf/tui.rb` — `OKF::TUI.search_capable?`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui.rb
 ---
 
 # Overview
@@ -13,7 +30,7 @@ merges several bundles into **one** ranked corpus.
 
 **This has shipped.** `across` was unreleased when the view was built — `okf`
 1.8.0 on RubyGems had no such method — but okf **1.9.0 carries it**, verified
-from a clean install with no checkout and no bundler in sight.[1] The coupling
+from a clean install with no checkout and no bundler in sight.[^1] The coupling
 that shaped this file is resolved.
 
 The coupling is deliberate, because per-bundle indexes would be a different and
@@ -35,7 +52,7 @@ OKF::Bundle::Search.across(pairs, terms, fuzzy: true)
 ```
 
 The registry picks the default engine first and falls through to one that can
-answer, so `fuzzy` is what routes this to minifts.[2] That makes the flag
+answer, so `fuzzy` is what routes this to minifts.[^2] That makes the flag
 load-bearing in a way it does not look: **dropping `fuzzy: true` would silently
 change the engine**, and with it the ranking — no error, no missing method, just
 different results and no BM25 scores. The screen would still work.
@@ -56,7 +73,7 @@ OKF::Bundle::Search.with(corpus, terms, fuzzy: true) # per query
 ```
 
 Measured over five registered bundles, 129 concepts: **392 ms** for the first
-query, then **12–16 ms**. Before, every query paid the 392 ms.[3] It is the same
+query, then **12–16 ms**. Before, every query paid the 392 ms.[^3] It is the same
 arithmetic okf used to justify the opposite default — an index build amortized over
 one query is a bad trade, and over many it is the whole point.
 
@@ -113,7 +130,7 @@ into "no matches".
 
 That is exactly how it presented: running the CLI via `ruby -Ilib` outside
 bundler let RubyGems activate the installed `okf` 1.8.0, and search silently
-found nothing.[4] The prototype could never hit it — it put the okf checkout on
+found nothing.[^4] The prototype could never hit it — it put the okf checkout on
 `$LOAD_PATH` directly, so it always had the unreleased method.
 
 So the check moved out of the rescue and up to boot:
@@ -125,22 +142,3 @@ OKF::TUI.search_capable?   # across, prepare and with — all three
 The CLI refuses to start and exits `1`, naming **the okf file that answered** —
 not the version, the file — because the usual cause is a second okf ahead of the
 intended one on the load path, and a version number does not tell you that.
-
-# Citations
-
-[1] Verified 2026-07-19 in a clean `ruby:3.2-slim` container — no checkout, no
-    bundler: `gem install okf` resolved 1.9.0, `Bundle::Search.respond_to?(:across)`
-    → `true`, `engine_for([:fuzzy])` → `OKF::Bundle::Search::Index`. RubyGems lists
-    okf 1.9.0 as the current release.
-[2] Verified 2026-07-19 against the okf checkout: `engine_for([:fuzzy])` → `index`,
-    `engine_for([])` → `scan`; `DEFAULT_ENGINE = :scan` in
-    `lib/okf/bundle/search.rb`.
-[3] Measured 2026-08-13 against the registry's own five bundles (129 concepts):
-    `across` per query 391.8 ms; with a held corpus 16.2 / 13.0 / 12.0 / 14.4 ms
-    after the first. On the six test fixtures (36 concepts): 62–80 ms against
-    2.7–3.0 ms.
-[4] Reproduced 2026-07-18: `ruby -Ilib` outside bundler loaded okf 1.8.0 from the
-    mise gem path, `Bundle::Search.respond_to?(:across)` → `false`, search
-    returned 0 hits for a term the checkout finds. Under `bundle exec` the same
-    query returned 1 hit ("orphan") and 11 ("registry").
-[5] `lib/okf/tui.rb` — `OKF::TUI.search_capable?`.

data/.okf/decisions/undeclared-width-dependency.md

@@ -3,7 +3,17 @@ type: Decision
 title: The Undeclared Width Dependency
 description: Ui.width rests on unicode-display_width, which arrives through tty-box rather than the gemspec — accepted deliberately, and guarded by a test that fails loudly if it stops arriving.
 tags: [dependencies, rendering, terminal]
-timestamp: 2026-07-19
+generated:
+  by: human:maintainer
+  at: 2026-07-19
+sources:
+  - id: "1"
+    title: "Sabotage run 2026-07-19: `Ui.width` reduced to `plain.length`, both checks failed as predicted, then restored — 38 runs green."
+    resource: "Sabotage run 2026-07-19: `Ui.width` reduced to `plain.length`, both checks failed as predicted, then restored — 38 runs green"
+  - title: "`lib/okf/tui/ui.rb` — the guarded require and the fallback."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/ui.rb
+  - title: "`test/integration/geometry_test.rb` — `WIDE_STATES` and the display-columns check."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/geometry_test.rb
 ---
 
 # Overview
@@ -62,12 +72,4 @@ terminal sheared. A test that degrades alongside the code it checks is not a
 guard.
 
 Both were verified by forcing the fallback: a row measured 87 columns in an
-80-column terminal, and CJK measured 3 instead of 6.[1]
-
-# Citations
-
-[1] Sabotage run 2026-07-19: `Ui.width` reduced to `plain.length`, both checks
-    failed as predicted, then restored — 38 runs green.
-[2] `lib/okf/tui/ui.rb` — the guarded require and the fallback.
-[3] `test/integration/geometry_test.rb` — `WIDE_STATES` and the
-    display-columns check.
+80-column terminal, and CJK measured 3 instead of 6.[^1]

data/.okf/index.md

@@ -1,13 +1,19 @@
 ---
-okf_version: "0.1"
+okf_version: "0.2"
 ---
 
 # okf-tui knowledge bundle
 
-The non-obvious knowledge behind **okf-tui** — the full-screen terminal UI over
-[okf](@okf) bundles. The `README` documents what the six views answer and which
-keys drive them, and `AGENTS.md` carries the contracts a change has to keep; this
-bundle deliberately restates neither.
+The knowledge behind **okf-tui** — the full-screen terminal UI over
+okf (`@okf`) bundles. It is written to be read *before* opening `lib/`, so an
+agent about to add a view, a key or a panel does not re-derive the layering and
+does not rebuild something the kernel or this program already answers.
+
+`AGENTS.md` beside it carries the contracts a change has to keep and routes here
+for everything else; the `README` is the user's. What used to be a
+hand-maintained Map of `lib/**` in `AGENTS.md` now lives in
+[Structure](structure/), pinned by `test/unit/bundle_catalog_test.rb` — the code
+is the truth and this bundle is the claim, so the two cannot drift quietly.
 
 What it captures is what the code cannot tell you on its own: *why* the
 interaction model is what it is (each piece of it arrived at by getting it wrong
@@ -22,6 +28,8 @@ turned out to be harder than it looked.
 
 # Areas
 
+* [Structure](structure/) - Every file under `lib/`, grouped by the layer that owns it: the doors, the workspace and the model, the app, and the rendering layer.
+* [Capabilities](capabilities/) - The catalogue: the six views and the kernel surface behind them, before you build a seventh.
 * [Decisions](decisions/) - The choices and their tradeoffs: the analysis boundary with okf, the search facade and the branch it outlived, the inherited Ruby floor, and why no dependency carries a ceiling.
 * [Interaction](interaction/) - The keyboard model — key routing and its modes, Esc as a stack, submitted rather than live search, following a link out of the page, and the two independent axes of "which bundle".
 * [Rendering](rendering/) - Composing a frame: ANSI-aware width, whole-frame painting, the tty-markdown trap that only appears in colour, and the one verdict a bundle wears everywhere.

data/.okf/interaction/cross-bundle-scope.md

@@ -3,7 +3,14 @@ type: Concept
 title: Active Bundle and Scope Are Two Axes
 description: What you are reading and what you are searching move independently, and the registry writes that reconcile them key on the directory rather than the slug.
 tags: [ux, search, registry]
-timestamp: 2026-07-19
+generated:
+  by: human:maintainer
+  at: 2026-07-19
+sources:
+  - title: "`lib/okf/tui/workspace.rb` — `reload`, `add`, `remove`, `make_default`, `rename`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/workspace.rb
+  - title: "`test/test_helper.rb` — `with_registry`; `test/integration/terminal_test.rb` — the unchanged-registry assertion."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/test_helper.rb
 ---
 
 # Overview
@@ -52,10 +59,3 @@ says so rather than pretending to configure one.
 The suite never touches the real `~/.okf`: every test runs against a temporary
 `$OKF_HOME`, and the pty test asserts the registry file is byte-identical
 afterwards.
-
-# Citations
-
-[1] `lib/okf/tui/workspace.rb` — `reload`, `add`, `remove`, `make_default`,
-    `rename`.
-[2] `test/test_helper.rb` — `with_registry`; `test/integration/terminal_test.rb`
-    — the unchanged-registry assertion.

data/.okf/interaction/deferred-search.md

@@ -3,7 +3,14 @@ type: Decision
 title: Search Submits, It Does Not Follow Typing
 description: Enter runs the search rather than every keystroke, because a cross-bundle index is rebuilt per query — and the regression that hides is invisible on screen.
 tags: [ux, search, keys]
-timestamp: 2026-07-18
+generated:
+  by: human:maintainer
+  at: 2026-07-18
+sources:
+  - title: "`lib/okf/tui/app.rb` — `@searched`, `@search_hits_key`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/app.rb
+  - title: "`test/integration/search_test.rb` — the counting test."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/search_test.rb
 ---
 
 # Overview
@@ -42,8 +49,3 @@ identical bug. Both keys are now `.dup`ed.
 
 A cache keyed on a mutable string it does not own is not a cache; it is a
 one-shot.
-
-# Citations
-
-[1] `lib/okf/tui/app.rb` — `@searched`, `@search_hits_key`.
-[2] `test/integration/search_test.rb` — the counting test.

data/.okf/interaction/esc-peels-one-layer.md

@@ -3,7 +3,15 @@ type: Decision
 title: Esc Peels One Layer
 description: Esc ends the innermost active thing and nothing else — the rule that stops it from resetting a list cursor and losing the file the reader had open.
 tags: [ux, keys, scar-tissue]
-timestamp: 2026-07-18
+generated:
+  by: human:maintainer
+  at: 2026-07-18
+sources:
+  - id: "1"
+    title: "Reproduced 2026-07-18 in `test/integration/browse_test.rb`: with `overview` open the cursor moved 4 → 1 on Esc. The test was written red first and passed unedited after the fix."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/browse_test.rb
+  - title: "`lib/okf/tui/app.rb` — `handle_escape`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/lib/okf/tui/app.rb
 ---
 
 # The rule
@@ -31,7 +39,7 @@ still active while `@finding` is false.
 
 Esc from that state fell through to the list's own Esc, which clears the filter
 and calls `reset_cursor`. The reader was reading a concept and landed back on the
-**first file in the bundle**, having lost the one they had open.[1]
+**first file in the bundle**, having lost the one they had open.[^1]
 
 ```ruby
 if findable? && !@find.empty?
@@ -61,10 +69,3 @@ the bug above: it is handled *inside* the picker's own key handler rather than i
 `handle_escape`, so closing it can never fall through to the layers beneath —
 which is exactly what the find failed to do. See
 [following-links](/interaction/following-links.md).
-
-# Citations
-
-[1] Reproduced 2026-07-18 in `test/integration/browse_test.rb`: with `overview`
-    open the cursor moved 4 → 1 on Esc. The test was written red first and
-    passed unedited after the fix.
-[2] `lib/okf/tui/app.rb` — `handle_escape`.

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".