okf-tui 1.0.0 → 1.0.1

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

@@ -3,7 +3,12 @@ type: Runbook
 title: The One Test That Opens a Terminal
 description: A single pty test boots `okf tui` in a real process and walks every view, and the three timing traps that made it flake on the Ruby floor.
 tags: [testing, terminal, scar-tissue]
-timestamp: 2026-07-18
+generated:
+  by: human:maintainer
+  at: 2026-07-18
+sources:
+  - title: "`test/integration/terminal_test.rb` — `SCRIPT`, `settle`, `reap`."
+    resource: https://github.com/serradura/okf/blob/main/gems/okf-tui/test/integration/terminal_test.rb
 ---
 
 # Why it exists
@@ -67,7 +72,3 @@ the escape sequences before it do not.
 `"\t\r"` in a single write can reach the reader as a *single* keypress. Split
 control keys into separate steps — a race the test loses only sometimes is worse
 than one it loses always.
-
-# Citations
-
-[1] `test/integration/terminal_test.rb` — `SCRIPT`, `settle`, `reap`.

data/.okf/testing/the-suite.md

@@ -0,0 +1,120 @@
+---
+type: Component
+title: The Suite — Its Layers, and the Two Fixtures That Exist to Bite
+description: "What each test file proves, why `nested` and `provenance` were built when twelve fixtures already existed, and the two gaps between this suite and the okf a user actually resolves."
+tags: [testing, fixtures, structure]
+generated:
+  by: human:maintainer
+  at: 2026-08-19
+---
+
+# Integration first
+
+`test/integration/` is the critical layer: it drives the app the way a user does
+— real keys, real frames, real exit codes. A unit test proves a method behaves;
+an integration test proves the *product* behaves.
+
+```
+test/
+  test_helper.rb              OKF::TUI::TestCase: app_for, render, with_registry,
+                              with_local_registry
+  fixtures/                   bundles chosen for their standing, not their size
+    nested/                   the only one whose directories nest — see below
+    provenance/               the only v0.2 one, §5 declared and withheld — below
+  integration/
+    geometry_test.rb          every row is exactly the terminal width
+    browse_test.rb            reading order, rendering, find-in-body
+    search_test.rb            deferred search, focus, escalation, the held corpus
+    graph_test.rb             facets, and following a concept out
+    dirs_test.rb              okf's directory set, and the dir facet
+    structure_test.rb         hubs and dir traffic, against okf's own numbers,
+                              and health's two panes
+    groups_test.rb            registry groups, and scoping a search to one
+    refs_test.rb              @slug / @group, and which registry resolves them
+    provenance_test.rb        §5 on screen, and what a v0.1 bundle is spared
+    signals_test.rb           health colours, the tab flag, the filters
+    cli_test.rb               argv, streams, exit codes — CLI.run driven straight
+    plugin_test.rb            `okf tui` through okf's registry, and that the
+                              dispatcher adds nothing but the streams
+    terminal_test.rb          `okf tui` in a real process, through a real pty —
+                              the only test that walks process boot + discovery
+  unit/
+    gemspec_test.rb           the declared okf floor tracks the kernel next door
+    packaging_test.rb         LICENSE.txt and NOTICE ship, real files, unchanged
+    bundle_catalog_test.rb    this bundle against the code it describes
+```
+
+The three unit tests are there because their claims are about the *package* and
+the *documentation*, not the app — no integration test can reach them.
+
+# The two fixtures built to reach a branch nothing else could
+
+**`fixtures/nested` exists because every other fixture is one level deep**, and
+at one level `dir` and `top_dir` are the same string — so an assertion against
+them passes whichever field the code reads, which is exactly how the `area`
+break survived. It carries a real tree, an intermediate directory holding no
+concepts of its own (`platform/`), and a directory whose only file is a `log.md`
+(`history/`) — the two shapes okf 1.13.0 had to fix its own directory set for.
+Six directories against three top-level ones: reach for it for anything about
+`dir`, depth, or traffic.
+
+**`fixtures/provenance` is the only v0.2 bundle**, and it carries a concept that
+declares no §5 family (`untouched.md`) beside four that do — deliberately, so
+the suppression rule is a property of the *concept* rather than of the fixture,
+and one test can assert both halves against one bundle. Its numbers are chosen
+to bite: three of its four `unverified` concepts are claimable, so a trust facet
+counting the whole tally would say 4 and narrow to 3. Reach for it for anything
+about trust, status, `generated`, `stale_after` or `sources`; reach for a v0.1
+fixture to prove the same surface stays *absent*.
+
+Keep both conformant and lint-clean, so they stay usable by the health tests.
+Provenance's one `info` is the legacy `timestamp:` on `untouched.md`, which is
+the §13.1 lift under test.
+
+# Run with colour on, not just off
+
+Pastel disables colour when stdout is not a terminal, so a piped test exercises
+none of the ANSI-aware width, clipping and wrapping code — the paths most likely
+to be wrong are exactly the ones a naive capture cannot see. `geometry_test` runs
+both modes; `browse_test` forces colour for the render sweep.
+
+That is not thoroughness for its own sake: the `IndexError` in
+[markdown-rendering-trap](/rendering/markdown-rendering-trap.md) rendered
+perfectly in every uncoloured test.
+
+# No suite here runs the okf a user gets
+
+The `Gemfile` resolves okf from `../okf`, and in the monorepo that checkout is
+always there — so the local run, CI, and the 2.4 container all exercise
+*unreleased* okf. That is the right default: it lets a kernel change be driven
+from the UI without a release. It also leaves a checkout-versus-RubyGems gap.
+
+Two things stand in that gap, covering different halves.
+`test/unit/gemspec_test.rb` is the standing one: it fails the moment okf bumps
+and the gemspec floor does not follow. And a run against the *published* okf
+catches the rest — a released kernel resolves different analysis output, which
+is a difference no floor expresses.
+
+The disagreement it catches is silent: okf's lint findings on
+`fixtures/okf-docs` have changed between releases before, which is enough to
+change how many rows the health view has. **A test whose premise depends on
+okf's analysis output can pass here and fail there** — the health scroll tests
+did exactly that, proving a pane overflowed by leaning on a lint count. Prove a
+rendering property from geometry (a terminal too short to fit) and let the
+agreement tests be the place okf's numbers are asserted.
+
+# Two assertion traps this suite has already hit
+
+* **A check that crashes tells you less than one that fails.** When an
+  assertion's subject can be nil because the thing under test broke, report that
+  and skip the dependents rather than raising `NoMethodError` from the middle.
+* **Judge a rendered offset against the window the view actually used.** An
+  earlier version compared a scroll against a different window size and reported
+  a failure that was not one.
+
+And one naming rule: **name things, do not count them.** The browse list holds
+reserved files as well as concepts, so `<down><down><down>` is a guess about
+ordering. `open_concept("overview")` is a statement about which concept is open.
+
+For the 2.4 container, **read its output, not its exit status** — piping it
+through `tail` returns `tail`'s status, which is zero however the run went.

data/CHANGELOG.md

@@ -5,6 +5,61 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.0.1] - 2026-08-20
+
+### Fixed
+
+- **The package metadata follows the `gems/` move and the repository rename.**
+  Two URLs on the package page were about to be wrong at once. `changelog_uri`
+  named `blob/main/okf-tui/CHANGELOG.md`, a path that stopped existing when the
+  four gems moved under `gems/`; `homepage` named `serradura/okf-gem`, and the
+  repository is now **`serradura/okf`** — the name the command has had all
+  along. rubygems.org serves whatever the last release published, so neither
+  corrects itself: only a release republishes metadata, and this is that
+  release. Both land in one round rather than two, which is the whole reason
+  the rename waited for the paths to stop moving.
+
+  `homepage_uri`, `source_code_uri` and `changelog_uri` are all derived from
+  `homepage`, so one line moves four pieces of this gem's metadata. GitHub
+  redirects the old URLs permanently, so anything already published keeps
+  resolving.
+
+### Changed
+
+- **The gem's own bundle is now OKF v0.2.** It was the last one in the tree on
+  v0.1. Its 30 concepts moved `timestamp:` under `generated: { by, at }`, and
+  the 22 carrying a body `# Citations` list moved that provenance into
+  `sources:` — every entry keeping its text, with a GitHub URL where it named a
+  real file. The three concepts using positional `[1]` markers were rekeyed to
+  `[^1]` footnotes, which is what §5.1 asks for. `okf validate` and `okf lint`
+  are both clean on it.
+
+### Added
+
+- **The bundle carries the structure and the catalogue, and a test pins them.**
+  `.okf/structure/` names every file under `lib/`, grouped by the layer that
+  owns it; `.okf/capabilities/` is the catalogue of the six views and the kernel
+  surface behind them; `.okf/testing/the-suite.md` is what each test file proves
+  and why the two special fixtures exist; `.okf/testing/adding-a-view.md` is the
+  walk a new screen owes. `test/unit/bundle_catalog_test.rb` fails when a file
+  under `lib/` is named by no concept, when a concept names a file that is gone,
+  or when the view catalogue and `App::TABS` disagree. `AGENTS.md` kept the
+  contracts and the commands and now routes here for the rest — its
+  hand-maintained Map of `lib/**` was the thing nothing checked.
+
+### Fixed
+
+- **Three `AGENTS.md` paths pointed at directories that no longer exist** —
+  `cd /build/okf-tui`, `cd okf-tui`, and `working-directory: okf-tui`, all from
+  before the gems moved under `gems/`.
+
+### Changed
+
+- **The okf floor moves to `>= 2.1.1, < 3`** — the kernel this gem develops
+  against released 2.1.1, and the floor tracks what the suite proves against
+  (the gemspec drill enforces equality as the normal state). Nothing here calls
+  a 2.1-only surface; the ceiling is unchanged.
+
 ## [1.0.0] - 2026-08-15
 
 First release.
@@ -236,4 +291,5 @@ First release.
   turns the next one into a resolution failure a maintainer sees instead of a
   wrong number a reader believes.
 
-[1.0.0]: https://github.com/serradura/okf-gem/releases/tag/okf-tui/v1.0.0
+[1.0.1]: https://github.com/serradura/okf/compare/okf-tui/v1.0.0...okf-tui/v1.0.1
+[1.0.0]: https://github.com/serradura/okf/releases/tag/okf-tui/v1.0.0

data/README.md

@@ -1,6 +1,6 @@
 # okf-tui
 
-A full-screen terminal UI for [Open Knowledge Format](https://github.com/serradura/okf-gem)
+A full-screen terminal UI for [Open Knowledge Format](https://github.com/serradura/okf)
 bundles: read one, switch between many, configure the registry, and search
 across all of them at once. Built on the [TTY toolkit](https://ttytoolkit.org/components/).
 
@@ -21,7 +21,7 @@ This gem ships **no executable of its own** — deliberately. A second binary th
 only aliased `okf tui` would be one more name to install, document and keep
 working, and two front ends is two argument grammars waiting to drift. `okf`
 finds this gem because it ships `okf/plugin.rb`, the convention any gem can use
-to add a verb — see [extension points](https://github.com/serradura/okf-gem/blob/main/.okf/design/extension-points.md).
+to add a verb — see [extension points](https://github.com/serradura/okf/blob/main/.okf/design/extension-points.md).
 
 The argument shape mirrors `okf server` exactly, because it is the same grammar:
 `@slug` names a registered bundle, bare `@` the registry default, `@group` fans out
@@ -189,6 +189,11 @@ silently rather than loudly.
 the verb resolves the same way it does for a user. See [AGENTS.md](AGENTS.md)
 for the contracts a change has to keep.
 
+This gem ships its own knowledge bundle at `.okf/`, and it is the gem's own
+documentation rather than a sample: what every file under `lib/` does, what each
+of the six views answers, and why the interaction model is what it is. `okf tui
+.okf` reads it in this program, which is the shortest honest demo there is.
+
 ## License
 
 Apache-2.0.

data/lib/okf/tui/version.rb

@@ -2,6 +2,6 @@
 
 module OKF
   module TUI
-    VERSION = "1.0.0"
+    VERSION = "1.0.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf-tui
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -15,7 +15,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.1.1
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -25,7 +25,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 2.1.1
     - - "<"
       - !ruby/object:Gem::Version
         version: '3'
@@ -157,6 +157,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".okf/capabilities/index.md"
+- ".okf/capabilities/okf-surface.md"
+- ".okf/capabilities/views.md"
 - ".okf/decisions/index.md"
 - ".okf/decisions/invents-no-analysis.md"
 - ".okf/decisions/no-version-ceilings.md"
@@ -177,14 +180,22 @@ files:
 - ".okf/interaction/which-registry.md"
 - ".okf/log.md"
 - ".okf/rendering/ansi-aware-width.md"
+- ".okf/rendering/fit-or-say-so.md"
 - ".okf/rendering/index.md"
 - ".okf/rendering/markdown-rendering-trap.md"
 - ".okf/rendering/status-vocabulary.md"
 - ".okf/rendering/whole-frame-painting.md"
+- ".okf/structure/doors.md"
+- ".okf/structure/index.md"
+- ".okf/structure/rendering.md"
+- ".okf/structure/the-app.md"
+- ".okf/structure/the-workspace.md"
+- ".okf/testing/adding-a-view.md"
 - ".okf/testing/ci-matrix.md"
 - ".okf/testing/headless-frames.md"
 - ".okf/testing/index.md"
 - ".okf/testing/pty-test.md"
+- ".okf/testing/the-suite.md"
 - CHANGELOG.md
 - LICENSE.txt
 - NOTICE
@@ -199,14 +210,14 @@ files:
 - lib/okf/tui/version.rb
 - lib/okf/tui/views.rb
 - lib/okf/tui/workspace.rb
-homepage: https://github.com/serradura/okf-gem
+homepage: https://github.com/serradura/okf
 licenses:
 - Apache-2.0
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/serradura/okf-gem
-  source_code_uri: https://github.com/serradura/okf-gem
-  changelog_uri: https://github.com/serradura/okf-gem/blob/main/okf-tui/CHANGELOG.md
+  homepage_uri: https://github.com/serradura/okf
+  source_code_uri: https://github.com/serradura/okf
+  changelog_uri: https://github.com/serradura/okf/blob/main/gems/okf-tui/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: