thurbox: Skill for Claude Code

Thurbox plugin kernel and plugin authoring

Working reference indexed by AGENTS.md. The rationale behind these decisions is owned by the docs under docs/; a change that invalidates what this says updates it in the same PR.

Architecture (plugin kernel)

The interface is Lua running on a Rust kernel. thurbox boots the kernel, which reads ui/ and renders whatever plugins it finds; there is no built-in pane. v1's src/app (TEA model/update/view) and src/ui (35 render modules) were deleted when the kernel took the binary name — v1 lives on the v1.x branch.

The five rules

1. Four node kinds, forever — text, box, input, surface. Everything else composes in ui/lib/widgets.lua. tests/kernel_mvp.rs asserts the count. A new appearance arrives as a prop on one of the four: text takes a style the kernel paints across its whole rect before the spans go on top, which is what a selection bar or hover band is — no pane pads a row with a spacer span, and a span naming its own colour keeps it (a search hit stays visible under the bar). widgets.list exposes it as selected_style / hover_style. A frame takes title_align, border_type (rounded/square) and an overlay — runs painted onto its own border cells (top_left/top_right/bottom_left/bottom_right/right_column) after the block, which is where the session list's ▲ N/▼ N counts and the terminal pane's scrollbar live, at the cost of no content cell. And a run takes id/role, so a chip inside a line is a click target over its own columns without becoming a node; adjacent runs sharing an identity coalesce into one hitbox, which is what makes ◀ F9 — an accent chevron and a muted hint — a single button.
2. Layout resolves before render — rects are computed first, then each plugin is called with its own. Plugins declare size statically, in their declaration table, which is what breaks the circularity.
3. Snapshot-read, command-write — reads come from an in-memory snapshot and return instantly; writes are commands accepted now and surfaced later. Lua never blocks, so no plugin can stall the loop on SQLite, git or an unreachable host.
4. Capabilities by absence — an ungranted capability is not in the environment. io, os, debug, package and the loaders are withheld, and thurbox.yml makes selene enforce that statically. One capability cannot be expressed that way: a program pane is asked for through command, which every plugin has, so thurbox.granted reports the grant instead — a boolean about a decision already made, which withholds nothing.
5. Anything touching the world runs on a worker — terminal attach, commands, the interface's database reads and writes (kernel::snapshot_db), diffs, metrics, git stats, repository reads, update checks, and programs a plugin asked for.