okf-tui 1.0.0

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

@@ -0,0 +1,146 @@
+---
+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
+---
+
+# Overview
+
+The search view calls `OKF::Bundle::Search.across`, okf's engine facade, which
+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
+that shaped this file is resolved.
+
+The coupling is deliberate, because per-bundle indexes would be a different and
+worse product: BM25 weighs a term by how rare it is *in the corpus*, so indexing
+each bundle separately scores the same match differently depending on which
+bundle it came from. One index makes one corpus, and cross-bundle scores that
+can be compared are the whole point of the view. See
+[cross-bundle-scope](/interaction/cross-bundle-scope.md).
+
+# `fuzzy: true` is what selects the engine
+
+okf has since made the facade route between engines, and the **BM25 index is no
+longer the default** — a plain search runs the regexp scan, because a one-shot
+CLI cannot amortize an index build. okf-tui still gets the index, but only as a
+consequence of asking for a capability the scan does not have:
+
+```ruby
+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
+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.
+
+Unlike the CLI, the TUI is long-lived and searches repeatedly, so paying for the
+index is the right trade here even though it is the wrong default there.
+
+# Long-lived means the corpus is held, not rebuilt
+
+Which was the point, and for a release the code did not act on it. `Search.across`
+rebuilds **everything** per call — the documents and the index over them — and the
+TUI called it on every submitted query. okf 1.11.0 had already added the pair for
+this exact case, and uses them in its own server:
+
+```ruby
+corpus = OKF::Bundle::Search.prepare(pairs)          # once, per scope
+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
+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.
+
+Two details that are not obvious from the API:
+
+- **No `engine:` is passed to `prepare`.** That argument only moves the index build
+  *earlier*; there is no boot here to move it into, and a session that never
+  searches should not pay to index bundles nobody opened. The index is built lazily
+  on the first query and memoized inside the corpus, which is okf's behaviour, not
+  something arranged here.
+- **A held corpus is a snapshot, and staleness is the failure mode.** It is keyed
+  on the scoped slugs and dropped outright by `load_entries`, so a scope change or
+  a reload cannot be answered from an index built over a different set. okf takes
+  the same care in its hub and gives the reason: a held index outliving the set it
+  was built from is a *wrong* answer rather than a slow one.
+
+`search_test.rb` asserts the mechanism — built once, reused across queries, dropped
+on scope change and on reload — and separately that the held corpus returns the
+identical ranking to `across`, since this is meant to be a performance change and
+nothing else.
+
+# The floor records it
+
+`okf >= 1.9` was the first honest floor — the version `across` shipped in, and
+what made the gem publishable at all: the `okf >= 0.1` placeholder it replaced
+was provably false, since no okf of that line could answer the search view.
+
+It has moved with the kernel since, one line per capability, because each
+absence fails silently rather than loudly — see
+[okf-capability-drift](/decisions/okf-capability-drift.md), which records what
+each one is; `prepare`/`with` above is among them. It stands at `okf >= 2.0`
+today, with the `< 3` ceiling that is
+[no-version-ceilings](/decisions/no-version-ceilings.md)' one earned exception.
+
+The proof of a floor is the resolution itself, never the local suite: resolve
+the *published* okf — drop the `path:` source, drop the lockfile — and run the
+suite on the floor and on a modern Ruby.
+
+# Why it still needs a boot check
+
+The check has not become redundant — its meaning has changed. It used to guard
+against an okf that had not shipped the method yet; it now guards against an
+installed okf **older than the floor**, which is a thing users will actually have.
+
+The failure mode is what makes this worth recording. `Workspace#search` rescues
+a failed search into an empty result — correct for a query okf cannot parse,
+badly wrong for a method that is not there, because then **every** search
+answers "no matches" and the screen reads as an empty bundle rather than a
+broken install.
+
+It now checks all three methods search actually calls — `across`, `prepare`,
+`with` — because a `prepare` that is not there fails the same silent way, rescued
+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
+`$LOAD_PATH` directly, so it always had the unreleased method.
+
+So the check moved out of the rescue and up to boot:
+
+```ruby
+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

@@ -0,0 +1,73 @@
+---
+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
+---
+
+# Overview
+
+[Column measurement](/rendering/ansi-aware-width.md) is the invariant the whole
+layout rests on, and it is computed by a gem the gemspec does not name:
+
+```ruby
+begin
+  require "unicode/display_width"
+rescue LoadError
+end
+...
+if defined?(Unicode::DisplayWidth)
+  Unicode::DisplayWidth.of(plain)
+else
+  plain.length          # the fallback
+end
+```
+
+It loads today because `tty-box` depends on it transitively. So the most
+load-bearing measurement in the program is held up by another gem's dependency
+graph.
+
+# Why it stays that way
+
+Declaring it was the obvious fix and was deliberately declined: the gem is
+already installed for every user, nothing changes for anyone today, and the
+guarded `require` means the program degrades rather than crashes.
+
+The accepted risk is narrow and worth naming precisely. If `tty-box` ever drops
+`unicode-display_width`:
+
+- nothing crashes — the `rescue LoadError` swallows it;
+- ASCII keeps rendering correctly — the fallback counts characters, which is the
+  right answer for ASCII;
+- **CJK, emoji and combining marks start shearing the frame**, and only there.
+
+So the failure is silent, partial, and shows up in a user's terminal rather than
+in CI. That combination is why it needed a guard even though it needed no
+gemspec line.
+
+# What guards it
+
+Two checks, and the split between them is the point:
+
+| Check | Catches |
+|-------|---------|
+| the `wide` fixture rendered at four sizes | the shear itself, end to end |
+| `Ui.width("日本語") == 6` plus `assert defined?(Unicode::DisplayWidth)` | the gem going missing |
+
+The second is deliberately **not** a rendering assertion. Were the gem to vanish,
+the layout and any test measuring through `Ui.width` would both fall back to
+counting characters and would agree with each other — passing while the real
+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.

data/.okf/index.md

@@ -0,0 +1,28 @@
+---
+okf_version: "0.1"
+---
+
+# 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.
+
+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
+first), the terminal-composition arithmetic that breaks the moment colour is
+involved, the coupling to an okf API and the scaffolding that outlived it, and
+what each layer of the test suite can and cannot catch.
+
+The through-line, if there is one: **this program invents no analysis.** okf owns
+every judgement on screen, so the knowledge worth recording here is not what the
+bundles say — it is how a screen shows them without lying, and where doing that
+turned out to be harder than it looked.
+
+# Areas
+
+* [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.
+* [Testing](testing/) - Frames proven without a terminal, the single pty walk that proves the binary boots, and the CI matrix that catches what a local run structurally cannot.

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

@@ -0,0 +1,61 @@
+---
+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
+---
+
+# Overview
+
+"Which bundle" is two questions, and collapsing them into one would be the
+obvious mistake:
+
+- the **active bundle** (`●`) — what browse, graph and health are about. `Enter`
+  on a bundle changes it.
+- the **scope** (`◉`) — which bundles a search covers. `space` toggles one, `A`
+  all, `N` none.
+
+So you can read one bundle while searching all of them. Opening a hit that lives
+in a *different* bundle switches the active bundle to it, which is the one place
+the axes meet.
+
+Scope is not a filter applied after the fact: the scoped bundles are indexed
+**together**, as one corpus, so BM25 scores compare across them rather than only
+within one. That is the same thing `okf search @all --fuzzy` does, and the reason
+for [the facade coupling](/decisions/search-facade-coupling.md) — which is also
+where the `fuzzy: true` that selects the BM25 engine at all is explained.
+
+# Reconciliation keys on the directory
+
+Every registry write reloads from disk, so the screen shows what the file now
+says rather than what the in-memory list was talked into believing. That reload
+has to carry the scope forward, and *how* it matches bundles is where three real
+bugs lived:
+
+| Bug | Cause | Fix |
+|-----|-------|-----|
+| a renamed bundle silently dropped out of scope | scope matched on slug, which a rename changes | reconcile on the **directory**, which survives a rename |
+| setting a default moved the row under the cursor | the list reorders; the cursor held a position | the cursor follows the *bundle*, not the index |
+| a newly added bundle was outside scope | the prior scope cannot mention a slug that did not exist | add it explicitly on add |
+
+The through-line: **a slug is a label, the directory is the identity.** Anything
+that has to survive a registry edit keys on the path.
+
+# The registry is the user's config
+
+Registry writes are real writes to the user's file. Removing a bundle never
+touches the bundle on disk — the registry is a list of references — and a
+workspace of directories named on the command line has no registry at all and
+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

@@ -0,0 +1,49 @@
+---
+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
+---
+
+# Overview
+
+Typing in the search field changes nothing. `Enter` runs the search.
+
+Live search was the first design, then a debounce, and both were wrong for the
+same reason: a search here builds **one index across every scoped bundle** (see
+[cross-bundle-scope](/interaction/cross-bundle-scope.md)), so a search per
+keystroke rebuilds that index per keystroke. A debounce only makes the waste
+intermittent — it is still doing the expensive thing on a query nobody asked for.
+
+Submitting is also the better interaction: the results stay still while you type,
+and the moment of asking is yours rather than a timer's.
+
+# Why it needs a counting test
+
+This is the regression worth guarding, and it is **invisible on a screenshot**.
+Pointing the results back at `@query` instead of `@searched` still renders
+correctly — the right hits appear, the screen is indistinguishable — it just
+rebuilds a full cross-bundle index for every letter. Only a count catches it:
+
+```ruby
+searches = 0
+app.workspace.define_singleton_method(:search) { |_q| searches += 1; [] }
+WORD.each_char { |char| app.handle(char); app.search_hits }
+# typing runs 0; Enter runs exactly 1
+```
+
+# The cache-key bug underneath
+
+The memoized hits were keyed on the query string itself — which the field
+*mutates in place* as you type. The key was the same object as the value's input,
+so it always compared equal and the cache never invalidated. The filter had the
+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

@@ -0,0 +1,70 @@
+---
+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
+---
+
+# The rule
+
+`Esc` ends the **innermost** thing currently active, and only that. Press it
+again for the next layer out. It is the mirror of
+[the mode dispatch](/interaction/key-routing.md): the same layers, unwound one at
+a time.
+
+```
+link picker → find → filter / facet → (nothing; it never leaves the view)
+```
+
+It never switches views. That was an explicit correction during design: pressing
+Esc twice in the search view used to jump back to tab 1, which threw away the
+results just as the reader was deciding what to do with them. Stopping the search
+and moving on are two different intentions, and only one of them was being
+offered.
+
+# The bug that made the rule explicit
+
+A find is a layer even after `Enter`. Submitting a find only releases the *field*
+— the term stays lit and `n`/`N` still step through the matches — so the find is
+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]
+
+```ruby
+if findable? && !@find.empty?
+  clear_find
+  return
+end
+```
+
+The file being read is the one thing a find must never cost.
+
+# What stayed the same
+
+The fix is narrow on purpose — a second Esc still clears the filter and resets
+the cursor, and these were each verified unchanged:
+
+| Esc pressed | Behaviour |
+|---|---|
+| after a submitted find | clears the find, cursor untouched |
+| again, find gone | clears the filter, resets cursor |
+| with no find at all | clears the filter, resets cursor |
+| on a graph facet | clears the facet |
+| on the help page find | clears the find, stays on help |
+| in the link picker | closes it, body and find both untouched |
+
+The picker row is the rule's newest test, and the one that would have repeated
+the bug above: it is handled *inside* the picker's own key handler rather than in
+`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

@@ -0,0 +1,57 @@
+---
+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
+---
+
+# Overview
+
+`/` filters the list you are in — bundles by slug or path, browse by title, id,
+type or tag, graph by type, tag or concept id. When it matches nothing, the empty
+result is not a dead end: `Enter` takes the term to the search view and runs it
+across every scoped bundle.
+
+# Why the escalation is honest
+
+The two are not the same search narrowed differently — they read different things
+in different places:
+
+| | reads | covers |
+|---|---|---|
+| filter | metadata (title, id, type, tag) | the current bundle |
+| search | bodies, ranked | every bundle in scope |
+
+So "no concept here is *called* that" and "nothing anywhere *says* that" are
+genuinely different answers, and a reader who got the first one almost always
+wants the second. Making them ask again in another view — retyping the term — is
+the whole friction the escalation removes.
+
+It is offered rather than automatic. The jump changes what you are looking at and
+runs work, so it stays an accepted suggestion, consistent with
+[search submitting rather than following typing](/interaction/deferred-search.md).
+
+# The registry filter escalates too
+
+A filter in the bundles view looks through a dozen slugs and the group names
+beside them, which is a narrower thing than it looks: a term matching none of
+them is usually a question about what the bundles *say*, not about what one is
+called. `Enter` there takes the term to the search view over every bundle, the
+same key doing the same thing.
+
+**Both panes have to be empty, not just the focused one.** A filter matching a
+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

@@ -0,0 +1,82 @@
+---
+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
+---
+
+# Overview
+
+`f` lists the markdown links leaving the open document; `1`–`9` or `Enter`
+follows one. The list comes from `OKF::Markdown::Links` — the same extraction
+`Bundle::Graph` builds its edges with and the validator warns on — so this walks
+the graph okf already computed rather than reading the body for link syntax. It
+stays inside [invents-no-analysis](/decisions/invents-no-analysis.md) by asking,
+not parsing.
+
+# A picker, not inline hints
+
+The obvious design is the browser one: light up each link in the body and label
+it. It was not built, and the reason is
+[markdown-rendering-trap](/rendering/markdown-rendering-trap.md) — the body on
+screen is tty-markdown's output, which has already rewritten and coloured the
+link text. Anchoring a hint to it means pattern-matching a *render artifact*, and
+the render is the least stable thing here.
+
+The link list is a value instead: a plain array of resolved targets, which a view
+turns into rows and a check asserts on without a terminal. It replaces the body
+in the detail pane rather than overlaying it, so the header above stays put and
+nothing touches `@detail_scroll` — Esc puts the page back exactly where it was.
+
+# The picker owns the digits
+
+It is a mode, dispatched before the view-switch keys, which is the whole reason
+it is a mode and not a pane: while it is open `1` picks a link, and everywhere
+else `1` is view one. That ordering is the rule in
+[key-routing](/interaction/key-routing.md), and the picker sits innermost — Esc
+closes it and leaves a running find still lit, which is
+[esc-peels-one-layer](/interaction/esc-peels-one-layer.md) applied to one more
+layer.
+
+# The directory link okf will not resolve
+
+`Links.resolve` returns nil for a target ending in `/`, and is right to: a
+directory is not a graph edge and the validator has nothing to check about it.
+But `[Decisions](decisions/)` is how *every* index.md points at its area, so
+reading okf's answer literally left the bundle's front door — the root index,
+which §6 makes the way in — as the one page with nothing to follow. Measured, not
+guessed: 0 of 5 links resolved there, against 5 of 5 in `interaction/index.md`.
+
+So a nil resolution whose raw target ends in `/` is retried as
+`<target>index.md`, and kept only if that path is in `bundle.reserved`. That is a
+lookup in a list okf handed over — no directory is walked, no markdown is read,
+and a directory with no index stays unfollowable. The judgement: this is
+*navigation*, which the TUI owns, not *analysis*, which it must not invent. The
+stricter reading is that resolution belongs upstream in okf, and if it lands
+there this should collapse into calling it.
+
+# The count it disagrees with
+
+The detail header shows `links →N` from the catalog, and the picker shows its own
+count, and **they do not always match**. The header counts graph edges:
+concept→concept, deduped, self-links dropped. The picker counts what a reader can
+follow, which also includes reserved files and targets nothing has been written
+at yet. In the `okf-docs` fixture, `overview` reads 16 against the picker's 17 —
+the extra one is a link to `design/index.md`, which the graph has no node for.
+Both numbers are right about different questions, so the picker carries its own
+label rather than being reconciled to the header.
+
+# The trail came free
+
+`Backspace` pops a stack pushed inside `open_concept` and `open_reserved` — the
+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/index.md

@@ -0,0 +1,12 @@
+# Interaction
+
+The keyboard model, and the UX decisions that were arrived at by getting them
+wrong first.
+
+* [Key Routing and Its Modes](key-routing.md) - The dispatch order, why `/` starts every text field, and the `case`-guard trap for letters that mean two things.
+* [Esc Peels One Layer](esc-peels-one-layer.md) - Esc ends the innermost thing only — the rule that stops a find from costing you the file you were reading.
+* [Search Submits, It Does Not Follow Typing](deferred-search.md) - Why Enter runs the search, and the regression that renders identically to the correct behaviour.
+* [Which Registry a Session Is On](which-registry.md) - okf resolves a project-local registry before the global one; being the single verb that disagreed was a silent wrong answer rather than an error.
+* [Active Bundle and Scope Are Two Axes](cross-bundle-scope.md) - Reading one bundle while searching many, and why reconciliation keys on the directory.
+* [A Dead Filter Offers the Wider Search](filter-escalates-to-search.md) - Filter reads metadata in one bundle, search reads bodies across all of them.
+* [Following a Link Out of the Page](following-links.md) - A picker rather than inline hints, the directory link okf declines to resolve, and the count it deliberately disagrees with.

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

@@ -0,0 +1,84 @@
+---
+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
+---
+
+# The order
+
+`handle` tries modes in order, innermost first, and only then the global keys:
+
+```
+prompt → link picker → find → filter → query field → view switch (1-6) → global keys
+```
+
+Each mode returns early, so while one owns the keyboard the layers under it never
+see the key.
+
+The link picker is the clearest case of why the order is what it is: it sits
+above the view switch so that `1` picks a link while it is open, and means view
+one everywhere else — see [following-links](/interaction/following-links.md).
+
+# Nothing grabs the field on arrival
+
+The rule that shapes the whole scheme: **arriving at a view never gives its text
+field focus.** Typing starts on `/`, everywhere, in every view that has anything
+to look through.
+
+The alternative was tried and is worse. A search view that takes focus on arrival
+swallows every printable key, so pressing `3` then `4` types "4" into the query
+instead of switching views — the number keys stop being navigation the moment you
+land somewhere that can type. Requiring `/` costs one keystroke and buys `1`–`6`
+meaning the same thing from everywhere.
+
+In the search view specifically, `Enter` submits and `Esc` releases the field
+*without leaving the view*, so the results stay reachable — see
+[esc-peels-one-layer](/interaction/esc-peels-one-layer.md) and
+[deferred-search](/interaction/deferred-search.md).
+
+What `/` looks through depends on what has focus: a list is filtered, a document
+is searched within. When a list filter comes back empty it
+[offers the wider search](/interaction/filter-escalates-to-search.md) rather than
+stopping there.
+
+# The guard trap
+
+Two letters do different things in different views: `n` is "next match" while
+reading and "rename" in the bundles view; `N` is "previous match" and "scope
+none".
+
+A Ruby `case` branch matches **whether or not its guard holds** — a `when "n"`
+with a failing guard does not fall through to the next branch, it matches and
+does nothing. So the shared letters must hand the key back explicitly:
+
+```ruby
+when "n" then findable? ? step_match(1) : fallback(key)
+when "N" then findable? ? step_match(-1) : fallback(key)
+```
+
+Without `fallback`, `n` and `N` were simply swallowed in the bundles view and
+rename was unreachable. Any new letter that means two things in two views needs
+the same treatment.
+
+Worth knowing that a find now survives until `Esc` rather than until `Enter`, so
+the window in which `n` means "next match" is longer than it used to be.
+
+# One key that spans two presses
+
+`q` quits, but only as `q q`. A single press ended the session on one stray
+keystroke with nothing to undo it, so the first press arms and says so on the
+status line, and the *next key* either confirms or cancels.
+
+The disarm is what makes it correct, and it is placed above the mode handlers on
+purpose — typing `q` into a filter or a query has to cancel the arming, or the
+chord leaks across a text field and `q` still quits on its own two keystrokes
+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`.