Wayfinder map: serverless kb - TUI at parity, web UI retired

[aksOps]

Destination

kb's human UI is a Bubble Tea TUI at parity with the frozen web UI (parity reference: the audit comment on #73), reading and writing SQLite directly like the CLI and MCP already do. The AI runner is extracted from the server into a shared package. The web UI is deleted, bare kb launches the TUI, the server becomes an optional component (kb serve) for remote access, and a release ships the serverless-default kb.

Notes

• Execution override: this map carries implementation. Each ticket is a build slice sized for one agent session (~100K tokens), resolved by a merged PR referenced in the resolution comment. Unblocked tickets may run as parallel agents on separate branches.
• Execution protocol (for the agent working this map): claim a ticket by assigning yourself before any work. Branch from origin/main, one branch per ticket. Open a PR referencing the ticket; squash-merge once CI is green and the ticket's acceptance holds (the user reviews the decision log and releases, not each diff — this is standing authorization). Post a resolution comment naming the PR, close the ticket, and append a one-line entry to Decisions so far below. Never push to main directly; never retag releases.
• The parity spec is the audit comment on Headless kb: replace web UI with a TUI client at parity #73 (feature inventory, keyboard/announcement contracts, persistence map, weak-spot dispositions). Read it before any TUI ticket. Deviations must be deliberate and recorded.
• Repo constraints: Go 1.25, SQLite via modernc (CGO off), append-only schema migrations, Go coverage gate 96.4% total / 95% per package with a decided 90% floor for internal/tui, immutable release tags, releases via the Release workflow.
• Blocking convention: tickets declare "Blocked by: #n" in the body. The frontier = open, unassigned tickets whose blockers are all closed.
• Stack facts and patterns: docs/research/bubbletea-stack.md on branch research/bubbletea-stack (note: /docs/ is gitignored today; resolve at merge). charm.land v2 module paths, teatest pseudo-version, modernc.org/sqlite v1.56.0 lockstep upgrade, data_version polling pattern.

Decisions so far

• Map mode — execution override: tickets ship PRs; parallel agents work the frontier (grilling round 1, pre-map).

• Destination edge — the map ends with the web UI deleted, server optional, release shipped (grilling round 1).

• Keybindings — vim-style plus the web parity card-move keys; mouse is a first-class citizen (grilling round 1, user correction).

• TUI data path — direct SQLite from day one via the store layer; freshness by polling data_version (grilling round 2).

• Server fate — optional component: kb serve remains for remote access and HTTP agents; nothing local depends on it (grilling round 2).

• AI runner — extracted to a shared internal package callable from TUI/CLI/server; server keeps thin handlers (grilling round 2).

• Research: Bubble Tea stack versions and architecture patterns — charm.land v2 stack pinned (bubbletea v2.0.8, bubbles v2.1.1, lipgloss v2.0.6, glamour v2.0.1, teatest pseudo-version), single-root-model architecture with per-pane packages, declarative MouseMode, data_version confirmed correct for cross-process change detection; findings at docs/research/bubbletea-stack.md on research/bubbletea-stack.

• Decide the coverage posture for internal/tui — dedicated 90% statement floor via a per-package override in check-go-coverage.sh; pure update logic fully table-tested, rendering via teatest goldens; ratchet up only.

• Decide the kb command surface for the serverless default — bare kb launches the TUI (help when non-TTY); kb serve is the explicit server verb; the flip happens once, at the deletion ticket.

• Prototype: board layout in the terminal — decided by description, prototype skipped: responsive miller columns; focused-column collapse below ~100 columns; card detail as an overlay pane.

• Ship celebration — header ×N-shipped-today streak plus a status-line flash on ship; no animation loop (grilling round 3; binds the ship-mechanics ticket).

• Filter persistence — per-board state file under KB_DATA (filter text, label toggles, cancelled toggle) restored on launch (grilling round 3; binds the filter ticket).

• Execution mechanics — ticket PRs auto-merge on green CI with acceptance checked; the user reviews the decision log and releases (grilling round 3).

• Extract the AI runner from the server into a shared package — runner, tools, skills, and probe now live in internal/ai behind direct-store APIs; server handlers remain thin adapters (PR #99).

• TUI scaffold: kb tui subcommand, store wiring, teatest harness — kb tui now opens the local store, renders a responsive Bubble Tea root, and refreshes through a serialized cancellable data_version watcher; the pinned v2 stack, research record, golden harness, and 90% TUI floor landed in PR #100.

• TUI board view (read-only) — responsive Miller columns, focused narrow mode, parity card chips, persisted per-board Cancelled visibility, keyboard/mouse navigation, and refresh-stable selection landed in PR #101.

• TUI card detail pane — the board now opens a refresh-aware detail overlay with frozen-markdown parity, bounded cached rendering, checklist/comments/links/killed context, scoped enrichment errors, and terminal-safe narrow layouts via PR #102.

• TUI settings and integrations — direct store-backed AI/forge settings, unsaved guarded probes, canonical saves, armed removal, control-safe cursor-aware inputs, responsive viewport/footer, and secret-redaction coverage landed in PR #103.

• TUI filter — persistent web-parity text and exact AND-label filtering, composite per-board/user preferences, frozen Unicode 17 casing, terminal-safe responsive controls, and filtered navigation/detail/mouse behavior landed in PR #106.

• TUI card create/edit form — direct-store add/edit, transactional field-conflict refusal, session-safe async results, due/effort/label/checklist parity, similar-item context, dirty-refresh preservation, and filter-aware canonical selection landed in PR #105.

• TUI card move model — keyboard lift/drop/cancel, X10/SGR drag, filtered-to-canonical indexed SQLite moves, position-valid incremental previews, write/watcher serialization, terminal-safe notices, and editor/filter/modal routing landed in PR #104.

• TUI comments and task links — direct-store comment add/delete, directional blocker-link management, explicit completion gates, nested input ownership, stale-safe refresh reconciliation, and transactional Done-drop validation landed in PR #107.

• TUI AI-assisted drafting and ADR splitting — cancellable shared-runner card drafts and bounded ADR splitting with manual review, sequential direct-store creation, per-row failures, and session-safe stale-result rejection landed in PR #108.

• TUI ship and delete mechanics — transactional completion guards, checklist-safe ship/auto-ship, unship, atomic soft cancellation, restore, Cancelled-only purge, shipped-today feedback, and modal-safe shortcuts landed in PR #109.

• TUI forge issue import and drift review — shared guarded forge services, qualified duplicate identity, atomic task/provenance creation, transactional drift baselines, import review, and nested no-sync drift review landed in PR #110; ambiguous legacy short links remain fuzzy review candidates rather than unsafe exact matches.

• Delete the web UI and make the TUI the default — bare kb now launches the TUI on terminals and prints help otherwise, kb serve retains the optional API/auth/remote surface, and the React/Vite/npm/static/Sonar toolchain plus synthetic dist release commit were removed in PR #111.

Not yet specified

• Theming: how label colors, priority colors, and light/dark terminal palettes map from the web's deterministic hashes.
• Remote boards in the TUI: whether kb tui ever speaks to a KB_SERVER, or remote stays CLI-only.
• Windows terminal support and its quirks.
• Whether the web UI's contract tests (a11y, egress, viewport) get TUI analogues.
• Performance posture for large boards (hundreds of cards) in the render loop.

Out of scope

• New web UI features: the web UI is frozen (v0.14.2 is its final feature state) and exists only to be deleted by this map.
• Removing remote mode or the HTTP API entirely: the server is demoted to optional, not deleted; the remote-parity commitments from the closed issue-tracker map stand.
• Milestones and per-task assignees (exclusion inherited from the previous map).