xonecas.io
64875
Mc

mini-coder / commit 5fa7102

feat: reduce complexity around tool output

Also addresses some agent config pain points that encouraged agents to
over engineer solutions

xonecas2026-07-10 5fa7102157d41c53c580bab2b23508c2776cabe2 parent 4cabfb5

22 files changed

This diff is too big to show in full. The first 1000 lines are below, and every file is listed with its counts.

.agents/skills/cel-tui/SKILL.md+0−291
@@ -1,291 +0,0 @@
1----
2-name: cel-tui
3-description: Build terminal user interfaces with cel-tui, a TypeScript TUI framework. Use when the user wants to create a TUI app, build a terminal UI, render text in the terminal, create a CLI with interactive elements, build a chat interface, text editor, or any interactive terminal application. Triggers include "build a TUI", "terminal UI", "interactive CLI", "text-based interface", "render to terminal", or any task requiring a programmatic terminal user interface.
4-license: MIT
5-compatibility: Requires Bun runtime. Best experience on Kitty-compatible terminals and in tmux with `set -s extended-keys on`; uses SGR mouse mode and accepts recoverable legacy key encodings when hosts do not preserve a pure Kitty stream.
6-metadata:
7- author: sacenox
8- version: "0.8.1"
9----
10-
11-# Building TUIs with cel-tui
12-
13-cel-tui is a TypeScript TUI framework with a declarative functional API, flexbox layout, cell-buffer rendering, style inheritance, and Kitty-first keyboard input. It has 4 primitives and external state management.
14-
15-## Terminal compatibility
16-
17-- **First-class:** Kitty-compatible terminals
18-- **First-class:** `tmux` with `set -s extended-keys on`
19-- **Best effort:** legacy terminals or multiplexers that collapse some modifier distinctions
20-
21-cel-tui enables Kitty level 1 for full modifier fidelity, but it also accepts recoverable legacy control bytes and ESC-prefixed Alt combinations so common keyboard flows keep working in tmux and mixed environments.
22-
23-## Install
24-
25-```bash
26-bun add @cel-tui/core
27-# Optional pre-made components
28-bun add @cel-tui/components
29-# Optional stream-first syntax tokenization
30-bun add @cel-tui/clew
31-```
32-
33-## Core Pattern
34-
35-Every cel-tui app follows this structure:
36-
37-```ts
38-import {
39- cel,
40- VStack,
41- HStack,
42- Text,
43- TextInput,
44- ProcessTerminal,
45-} from "@cel-tui/core";
46-
47-let value = "";
48-
49-cel.init(new ProcessTerminal());
50-cel.viewport(() =>
51- VStack(
52- {
53- height: "100%",
54- onKeyPress: (key) => {
55- if (key === "ctrl+q") {
56- cel.stop();
57- process.exit();
58- }
59- },
60- },
61- [
62- Text("My App", { bold: true, fgColor: "color06" }),
63- Text("─", { repeat: "fill" }),
64- TextInput({
65- flex: 1,
66- value,
67- onChange: (v) => {
68- value = v;
69- cel.render();
70- },
71- }),
72- ],
73- ),
74-);
75-```
76-
77-The steps: `cel.init(terminal)` → `cel.viewport(() => tree)` → mutate state + `cel.render()`.
78-
79-Use `cel.setTitle("My App")` when you want to update the terminal window or tab title. It is imperative terminal state, not part of the render tree, and the previous title is not restored automatically on `cel.stop()`.
80-
81-## 4 Primitives
82-
83-| Primitive | Type | Description |
84-| ------------------------- | ----------------------- | ----------------------------------------- |
85-| `VStack(props, children)` | Container | Vertical stack — children top to bottom |
86-| `HStack(props, children)` | Container | Horizontal stack — children left to right |
87-| `Text(content, props?)` | Leaf | Styled text, no children |
88-| `TextInput(props)` | Container (no children) | Multi-line editable text |
89-
90-Containers accept sizing (`width`, `height`, `flex`, `"50%"`, `minWidth`/`maxWidth`), layout (`padding`, `gap`, `justifyContent`, `alignItems`, `flexWrap`), scroll (`overflow: "scroll"`, `scrollbar`, `scrollStep`, `scrollOffset`, `onScroll`), styling (`fgColor`, `bgColor`, `bold`, `focusStyle`), and interaction (`onClick`, `focusable`, `focused`, `onKeyPress`). Colors are numbered palette slots (`"color00"`–`"color15"`), mapped to ANSI 16 by default. Custom themes can remap slots to different …
91-
92-Read [references/api.md](references/api.md) for the full props listing, sizing strategies, text props, and component reference.
93-
94-## Common Patterns
95-
96-### Spacer, divider, button
97-
98-```ts
99-HStack({ height: 1 }, [Text("left"), VStack({ flex: 1 }, []), Text("right")]);
100-Text("─", { repeat: "fill", fgColor: "color08" });
101-HStack(
102- {
103- onClick: handleClick,
104- focusStyle: { bgColor: "color06", fgColor: "color00" },
105- },
106- [Text(" Send ", { bold: true })],
107-);
108-```
109-
110-### Scrollable list
111-
112-Scroll is **uncontrolled by default** — the framework manages scroll position internally. Mouse wheel just works:
113-
114-```ts
115-VStack({ overflow: "scroll", scrollbar: true }, [...items]);
116-```
117-
118-Mouse wheel scrolling uses an **adaptive step** by default based on the scroll target's visible main-axis viewport size:
119-
120-- `floor(viewportMainAxis / 3)`
121-- clamped to `3..8`
122-
123-Override it with `scrollStep` when a view should scroll faster or slower:
124-
125-```ts
126-VStack({ overflow: "scroll", scrollbar: true, scrollStep: 6 }, [...items]);
127-```
128-
129-Provide `scrollOffset` + `onScroll` to opt into **controlled mode** — you own the state:
130-
131-```ts
132-let offset = 0;
133-
134-VStack(
135- {
136- overflow: "scroll",
137- scrollbar: true,
138- scrollOffset: offset,
139- onScroll: (newOffset, maxOffset) => {
140- offset = newOffset;
141- cel.render();
142- },
143- },
144- [...items],
145-);
146-```
147-
148-Controlled mode enables patterns like auto-scroll to bottom on new content. `scrollStep` affects mouse wheel input only — not programmatic `scrollOffset` updates.
149-
150-### Measuring content height
151-
152-Use `measureContentHeight(node, { width })` when your app knows the wrapping width but needs to know how tall a content subtree will be.
153-
154-```ts
155-import { measureContentHeight, VStack } from "@cel-tui/core";
156-
157-const addedHeight = measureContentHeight(
158- VStack({}, olderMessages.map(renderMessage)),
159- { width: historyContentWidth },
160-);
161-
162-scrollOffset += addedHeight;
163-```
164-
165-This is for **intrinsic content measurement**, not viewport/clipping measurement. The provided `width` is authoritative. Measure the content subtree you are adding or anchoring around — not a wrapper whose visible height is controlled by `height`, `flex`, or percentage sizing. If you measure a padded container, pass its outer width; if you measure the children inside a padded container directly, pass the inner content width.
166-
167-### Layers (modals)
168-
169-Return an array from the render function — layers composite bottom-to-top:
170-
171-```ts
172-cel.viewport(() => [
173- VStack({ height: "100%" }, [...mainUI]),
174- ...(showModal
175- ? [
176- VStack(
177- { height: "100%", justifyContent: "center", alignItems: "center" },
178- [
179- VStack(
180- { width: 40, height: 10, bgColor: "color08", fgColor: "color07" },
181- [...modalContent],
182- ),
183- ],
184- ),
185- ]
186- : []),
187-]);
188-```
189-
190-### Focus
191-
192-Focus is **uncontrolled by default** — Tab/Shift+Tab/Escape/click just work. Provide `focused` prop to opt into controlled mode:
193-
194-```ts
195-// Uncontrolled — framework manages focus
196-HStack({ onClick: handleAction }, [Text("[ OK ]")]);
197-
198-// Controlled — app owns focus state
199-TextInput({
200- value,
201- onChange,
202- focused: isFocused,
203- onFocus: ({ reason }) => {
204- addLog(`focused via ${reason}`);
205- isFocused = true;
206- cel.render();
207- },
208-});
209-```
210-
211-### Style inheritance
212-
213-Containers propagate styles to descendants. Explicit props always win:
214-
215-```ts
216-VStack({ fgColor: "color07", bgColor: "color04" }, [
217- Text("inherits color07 on color04"),
218- Text("explicit color02", { fgColor: "color02" }),
219-]);
220-```
221-
222-### Select component
223-
224-```ts
225-import { Select } from "@cel-tui/components";
226-
227-const mySelect = Select({
228- items: ["apple", "banana", "cherry"],
229- onSelect: (value) => {
230- chosen = value;
231- cel.render();
232- },
233-});
234-
235-// ctrl+q lives on the root — Select returns false for unrecognized
236-// keys, so they bubble up automatically.
237-cel.viewport(() =>
238- VStack(
239- {
240- height: "100%",
241- onKeyPress: (key) => {
242- if (key === "ctrl+q") {
243- cel.stop();
244- process.exit();
245- }
246- },
247- },
248- [mySelect()],
249- ),
250-);
251-mySelect.reset(); // clear filter/highlight programmatically
252-```
253-
254-### SyntaxHighlight component
255-
256-```ts
257-import { SyntaxHighlight } from "@cel-tui/components";
258-
259-VStack({ flex: 1, overflow: "scroll", padding: { x: 1 } }, [
260- SyntaxHighlight(source, "typescript"),
261-]);
262-
263-SyntaxHighlight(source, "javascript", { theme: "dark-plus" });
264-```
265-
266-`SyntaxHighlight(content, language, props?)` renders registered `clew` languages into cel-tui primitives. Current ids include the TypeScript / JavaScript families plus `python` / `py`, `bash`, `json`, and `markdown`. The component stays synchronous to call, but append-only updates reuse a cached `clew` stream while non-append edits replay the full snippet, so final output stays stable across streamed chunk boundaries. Unknown language ids render plain text. The optional `theme` accepts the small …
267-
268-## Gotchas
269-
270-- **State is external** — the framework has no state. Mutate variables then call `cel.render()`.
271-- **Text is a pure leaf** — no sizing props, no children. Parent controls the box.
272-- **TextInput consumes insertable text and editing/navigation keys** when focused (printable text, arrows, backspace, Enter, Tab), plus readline-style shortcuts: `ctrl+a` / `ctrl+e`, `alt+b` / `alt+f`, `ctrl+left` / `ctrl+right`, `ctrl+w`, and `alt+d`. Word movement and deletion are whitespace-delimited, and `up` / `down` follow visual wrapped lines. Enter inserts a newline by default. Use `onKeyPress` on TextInput to intercept keys before editing — return `false` to prevent the default action …
273-- **Escape unfocuses** the current element. Tab/Shift+Tab traverses focusable elements (wraps around). After Escape, traversal continues from where focus was lost.
274-- **Enter activates** a focused container's `onClick`. If no `onClick`, Enter reaches `onKeyPress`.
275-- **`focusable: true`** without `onClick` makes a container keyboard-focusable (receives `onKeyPress` events via Tab). Used by stateful components like `Select`.
276-- **Innermost handler wins** — for `onClick` and `onScroll`. For `onKeyPress`, keys **bubble up** through ancestors: return `false` from a handler to let the key continue to the next ancestor. Returning `void`/`undefined` consumes the key (stops bubbling). This is backward-compatible.
277-- **Mouse wheel step is adaptive by default** — scrollable containers and `TextInput` use `floor(viewportMainAxis / 3)`, clamped to `3..8`. Set `scrollStep` to override it for a specific view.
278-- **Container `bgColor`** fills the rect with opaque background before painting children. Always pair `bgColor` with `fgColor` for contrast — terminal default fg is designed for the terminal default bg, not for arbitrary palette backgrounds.
279-- **Colors are numbered slots** (`"color00"`–`"color15"`), not names. The default theme maps to ANSI 16. Omit `fgColor`/`bgColor` for terminal defaults (guaranteed readable across themes).
280-- **Crash cleanup** — terminal state is restored on SIGINT, SIGTERM, uncaughtException.
281-- **Always call `cel.stop()` before `process.exit()`** — restores raw mode, mouse tracking, and alternate screen.
282-- **Kitty-first keyboard input** — the framework enables Kitty level 1 and gets full modifier fidelity when the host preserves it (`alt+x`, `ctrl+plus`, `shift+enter`, etc.). It also normalizes recoverable legacy encodings so common shortcuts keep working in tmux. For best results, use a Kitty-compatible terminal or `tmux` with `set -s extended-keys on`. On older legacy hosts, historically ambiguous collisions such as `ctrl+i` vs `tab` or `ctrl+m` vs `enter` cannot be recovered once the host c …
283-- **tmux is good for keyboard-driven manual checks** — common `tmux send-keys` paths work for printable chars, `Tab`/`BTab`, `Enter`, `Escape`, arrows, and many `Ctrl+letter` shortcuts. Use exact raw-sequence injection only when you need to target a protocol-specific encoding. Mouse input remains unreliable in tmux and should be verified in a real terminal.
284-- **Button limitations** — `Button` from `@cel-tui/components` does not forward container sizing props (`width`, `height`, `flex`, `minWidth`, etc.). It supports styling (`fgColor`, `bgColor`, `bold`, etc.), `focusStyle`, `focused`, `onFocus`, `onBlur`, `onKeyPress`, and `padding`. For full layout control, use `HStack` + `Text` directly.
285-- **SyntaxHighlight only keeps parser state for append-only growth** — appended content reuses a cached `clew` stream, but non-append edits still reset and replay the full snippet so final output stays deterministic across chunk boundaries. Unknown language ids render plain text.
286-
287-## Composing Components
288-
289-Stateless components are plain functions returning `Node` trees — prefer this pattern. When a component needs internal state across renders, use a factory function that returns a callable instance. Read [references/composing-components.md](references/composing-components.md) for full patterns and examples.
290-
291-For the full framework specification, see the [cel-tui spec](https://raw.githubusercontent.com/sacenox/cel-tui/main/spec.md).
.agents/skills/cel-tui/references/api.md+0−346
@@ -1,346 +0,0 @@
1-# cel-tui API Reference
2-
3-## Framework lifecycle
4-
5-```ts
6-cel.init(new ProcessTerminal(), { theme?: Theme });
7-cel.viewport(() => tree); // or () => [layer1, layer2]
8-cel.render();
9-cel.setTitle("My App");
10-cel.stop();
11-```
12-
13-- `cel.viewport` sets the render function and triggers the first render.
14-- `cel.render()` requests a batched re-render after external state changes.
15-- `cel.setTitle(title)` writes a best-effort terminal title request. Control characters are stripped from `title`, and `cel.stop()` does not restore the previous title automatically.
16-- `cel.stop()` restores terminal state (raw mode, keyboard protocol, mouse tracking, alternate screen).
17-
18-## Container Props
19-
20-All props accepted by `VStack` and `HStack`:
21-
22-```ts
23-{
24- // Sizing
25- width, height, // SizeValue (number | "50%")
26- flex, // number
27- minWidth, maxWidth, // number
28- minHeight, maxHeight, // number
29- padding, // { x?: number, y?: number }
30- gap, // number (cells between children)
31- justifyContent, // "start" | "end" | "center" | "space-between"
32- alignItems, // "start" | "end" | "center" | "stretch"
33- overflow, // "hidden" (default) | "scroll"
34- scrollbar, // boolean
35- scrollStep, // number (mouse wheel step in cells; default adaptive)
36- scrollOffset, // number (controlled scroll)
37- onScroll, // (offset: number, maxOffset: number) => void
38- flexWrap, // "nowrap" (default) | "wrap" (HStack only)
39-
40- // Styling (inherited by descendants)
41- bold, italic, underline,// boolean
42- fgColor, bgColor, // Color ("color00"–"color15")
43- focusStyle, // StyleProps — overrides when focused
44-
45- // Interaction
46- onClick, // () => void
47- focusable, // boolean (default true if onClick set, or set true explicitly)
48- focused, // boolean (controlled — omit for uncontrolled)
49- onFocus, // ({ reason }) => void — reason is "tab" | "shift+tab" | "click" | "escape"
50- onBlur, // ({ reason }) => void — reason is "tab" | "shift+tab" | "click" | "escape"
51- onKeyPress, // (key: string) => boolean | void — normalized semantic key string; return false to keep bubbling
52-}
53-```
54-
55-## Measurement Helpers
56-
57-```ts
58-measureContentHeight(node, { width }); // number
59-```
60-
61-- Measures a node tree's **intrinsic content height** at the provided wrapping width.
62-- This is a content-measurement helper, not a viewport/clipping helper.
63-- The provided `width` is authoritative — use the actual width the subtree wraps at.
64-- Main use case: prepend-style scrollback, where older content is inserted above the current viewport and the app needs to preserve the viewport anchor.
65-
66-```ts
67-const addedHeight = measureContentHeight(
68- VStack({}, olderMessages.map(renderMessage)),
69- { width: historyContentWidth },
70-);
71-
72-scrollOffset += addedHeight;
73-```
74-
75-Measure the content subtree you are adding. If a wrapper's visible height is controlled by `height`, `flex`, or percentage sizing, measure the content inside that wrapper instead. For padded content, pass the outer width when measuring the padded container itself, or the inner content width when measuring its children directly.
76-
77-## Scroll
78-
79-Scroll supports **uncontrolled** (default) and **controlled** modes, mirroring the focus model:
80-
81-```ts
82-// Uncontrolled — framework manages scroll position. Mouse wheel just works.
83-VStack({ overflow: "scroll", scrollbar: true }, [...items]);
84-
85-// Controlled — app owns scroll state.
86-VStack(
87- {
88- overflow: "scroll",
89- scrollbar: true,
90- scrollOffset: offset,
91- onScroll: (newOffset, maxOffset) => {
92- offset = newOffset;
93- cel.render();
94- },
95- },
96- [...items],
97-);
98-```
99-
100-- Scroll direction follows the container’s main axis: VStack → vertical, HStack → horizontal.
101-- Scroll is pointer-driven (mouse wheel), not focus-driven. A user can type in a focused widget while scrolling a different container.
102-- Mouse wheel scrolling uses an adaptive default step based on the scroll target's visible main-axis viewport size: `floor(viewportMainAxis / 3)`, clamped to `3..8`.
103-- Set `scrollStep` to override the mouse wheel step for a specific scrollable or `TextInput`.
104-- In controlled mode, the UI only moves when the app passes the updated `scrollOffset` back. `onScroll` fires with the clamped new offset and the maximum offset (content size minus viewport size). Pass `Infinity` as `scrollOffset` to mean "scroll to end" (clamped during rendering and hit testing). `scrollStep` affects mouse wheel input only.
105-
106-## Text Props
107-
108-```ts
109-Text("content", {
110- repeat: "fill" | number, // Repeat to fill width or N times
111- wrap: "none" | "word", // Default "none", hard-clips at edge
112- bold,
113- italic,
114- underline, // boolean
115- fgColor,
116- bgColor, // Color ("color00"–"color15")
117-});
118-```
119-
120-Colors: 16 numbered palette slots — `"color00"` through `"color15"`. Mapped to ANSI 16 by default; custom themes can remap to different ANSI indices or 24-bit true color. Omit a color prop for the terminal default.
121-
122-## TextInput Props
123-
124-```ts
125-TextInput({
126- value, // string (controlled)
127- onChange, // (value: string) => void
128- onKeyPress, // (key: string) => boolean | void — normalized semantic key string; return false to prevent default editing action
129- placeholder, // Text() node shown when empty
130- // + all container props (sizing, styling, focus, scrollStep, etc.)
131-});
132-```
133-
134-Enter inserts a newline by default. Use `onKeyPress` to intercept keys before editing:
135-
136-```ts
137-// Enter submits instead of inserting newline
138-TextInput({
139- value: input,
140- onChange: handleChange,
141- onKeyPress: (key) => {
142- if (key === "enter") {
143- handleSend();
144- return false;
145- }
146- },
147-});
148-```
149-
150-When focused, TextInput consumes insertable text plus editing/navigation keys, including readline-style shortcuts: `ctrl+a` / `ctrl+e`, `alt+b` / `alt+f`, `ctrl+left` / `ctrl+right`, `ctrl+w`, and `alt+d`. Word movement and deletion are whitespace-delimited, and `up` / `down` navigate visual wrapped lines. The stored scroll offset is clamped every render; when focused, the viewport adjusts further only as needed to keep the cursor visible after edits, cursor movement, mouse wheel scrolling, or r …
151-
152-## Sizing Strategies
153-
154-Containers accept 4 sizing strategies:
155-
156-```ts
157-VStack({}, []); // Intrinsic — size to fit content (default)
158-VStack({ width: 30, height: 10 }, []); // Fixed — exact cell count
159-VStack({ flex: 1 }, []); // Flex — proportional to siblings
160-VStack({ width: "50%", height: "100%" }, []); // Percentage — relative to parent
161-```
162-
163-Constraints: `minWidth`, `maxWidth`, `minHeight`, `maxHeight`.
164-
165-Text has no sizing props — parent controls the box, height is intrinsic (content + wrapping).
166-
167-TextInput accepts container sizing props (`flex`, `width`, `height`, `padding`, `maxHeight`, etc.) plus container scroll props like `scrollStep` for mouse wheel behavior.
168-
169-## Key Format
170-
171-All lowercase, modifiers joined by `+`: `"ctrl+s"`, `"ctrl+shift+n"`, `"escape"`, `"enter"`, `"alt+up"`, `"f1"`. Framework normalizes modifier order.
172-
173-cel-tui is **Kitty-first** and works well in `tmux` with `set -s extended-keys on`. Recoverable legacy forms normalize to the same key strings, but historically collapsed collisions (`ctrl+i` vs `tab`, `ctrl+m` vs `enter`, `ctrl+[` vs `escape`) remain limited by what the host terminal or multiplexer reports.
174-
175-## Pre-made Components
176-
177-```ts
178-import {
179- Spacer,
180- Divider,
181- Button,
182- Select,
183- VDivider,
184- Markdown,
185- SyntaxHighlight,
186-} from "@cel-tui/components";
187-
188-Spacer(); // VStack({ flex: 1 }, [])
189-Divider(); // Text("─", { repeat: "fill" })
190-Divider({ char: "═", fgColor: "color08" });
191-Button("[OK]", { onClick: handleOk });
192-Button("✕", { onClick: handleClose, focusable: false });
193-// Button accepts: onClick, focusable, focused, onFocus, onBlur, focusStyle,
194-// onKeyPress, padding, bold, fgColor, bgColor, italic, underline.
195-// Note: Button does not forward container sizing props (width, height, flex).
196-// For full layout control, use HStack + Text directly.
197-```
198-
199-### Select (filterable list)
200-
201-Select props: `items`, `onSelect`, `placeholder` (default `"type to filter..."`), `maxVisible` (default `10`), `indicator` (default `"›"`), `highlightColor` (default `"color06"`), `onKeyPress` (composed with internal handler), plus container/style props: `width`, `height`, `flex`, `fgColor`, `bgColor`, `focused`, `focusable`, `onFocus`, `onBlur`, `focusStyle`.
202-
203-```ts
204-const mySelect = Select({
205- items: ["apple", "banana", "cherry"],
206- onSelect: (value) => {
207- chosen = value;
208- cel.render();
209- },
210- placeholder: "search fruits...",
211- maxVisible: 8,
212-});
213-
214-// Select returns false for unrecognized keys, so they bubble to root.
215-cel.viewport(() =>
216- VStack(
217- {
218- height: "100%",
219- onKeyPress: (key) => {
220- if (key === "ctrl+q") {
221- cel.stop();
222- process.exit();
223- }
224- },
225- },
226- [Text("Pick a fruit:"), mySelect()],
227- ),
228-);
229-
230-// Reset state programmatically
231-mySelect.reset();
232-```
233-
234-Rich items with separate display label, return value, and filter text:
235-
236-```ts
237-const modelSelect = Select({
238- items: [
239- {
240- label: "claude-sonnet-4 (free)",
241- value: "anthropic/claude-sonnet-4",
242- filterText: "claude-sonnet-4",
243- },
244- { label: "gpt-4o", value: "openai/gpt-4o", filterText: "gpt-4o" },
245- ],
246- onSelect: (value) => {
247- model = value;
248- cel.render();
249- },
250-});
251-```
252-
253-### VDivider (vertical divider)
254-
255-```ts
256-import { VDivider } from "@cel-tui/components";
257-
258-// Separate columns in an HStack
259-HStack({ height: "100%" }, [
260- VStack({ flex: 1 }, [Text("left pane")]),
261- VDivider({ fgColor: "color08" }),
262- VStack({ flex: 1 }, [Text("right pane")]),
263-]);
264-
265-// Custom character
266-VDivider({ char: "║", fgColor: "color08" });
267-```
268-
269-### Markdown (rendered markdown)
270-
271-Returns an array of nodes — spread into a container's children:
272-
273-````ts
274-import { Markdown } from "@cel-tui/components";
275-
276-VStack(
277- { flex: 1, overflow: "scroll", padding: { x: 1 } },
278- Markdown("# Hello\n\nSome **bold** text.\n\n```js\nconst x = 1;\n```"),
279-);
280-````
281-
282-Custom theme for markdown styling:
283-
284-```ts
285-Markdown(content, {
286- theme: {
287- heading1: { bold: true, fgColor: "color05" },
288- codeBlock: { bgColor: "color08" },
289- bold: { bold: true, fgColor: "color03" },
290- },
291-});
292-```
293-
294-Streaming works naturally — append chunks and call `cel.render()`. Unclosed blocks are handled gracefully.
295-
296-### SyntaxHighlight (rendered code)
297-
298-Returns a `VStack` — place it directly in a container's children:
299-
300-```ts
301-import { SyntaxHighlight } from "@cel-tui/components";
302-
303-VStack({ flex: 1, overflow: "scroll", padding: { x: 1 } }, [
304- SyntaxHighlight(code, "typescript"),
305-]);
306-
307-SyntaxHighlight(code, "javascript", { theme: "dark-plus" });
308-```
309-
310-- Signature: `SyntaxHighlight(content, language, props?)`
311-- `language` accepts registered `clew` language ids (`typescript` / `javascript` families plus `python` / `py`, `bash`, `json`, and `markdown` right now)
312-- `props.theme` accepts the built-in presets (`"default"`, `"dark-plus"`) or a best-effort token theme registration object targeting canonical `clew` scopes
313-- Uses a terminal-friendly ANSI 16 fallback theme by default
314-- Highlighting is synchronous at the component boundary; unsupported languages render plain text
315-- Append-only updates reuse a cached `clew` stream, while non-append edits replay the full snippet so final output stays stable across streamed chunk boundaries
316-
317-## Theme
318-
319-The default theme maps 16 color slots to ANSI palette indices. Custom themes remap to different ANSI indices or 24-bit hex:
320-
321-```ts
322-import { cel, ProcessTerminal, type Theme } from "@cel-tui/core";
323-
324-const mocha: Theme = {
325- color00: "#1e1e2e",
326- color01: "#f38ba8",
327- color02: "#a6e3a1",
328- color03: "#f9e2af",
329- color04: "#89b4fa",
330- color05: "#cba6f7",
331- color06: "#94e2d5",
332- color07: "#cdd6f4",
333- color08: "#45475a",
334- color09: "#f38ba8",
335- color10: "#a6e3a1",
336- color11: "#f9e2af",
337- color12: "#89b4fa",
338- color13: "#cba6f7",
339- color14: "#94e2d5",
340- color15: "#bac2de",
341-};
342-
343-cel.init(new ProcessTerminal(), { theme: mocha });
344-```
345-
346-App code uses `"color00"`–`"color15"` regardless of theme. The mapping is a rendering concern.
.agents/skills/cel-tui/references/composing-components.md+0−109
@@ -1,109 +0,0 @@
1-# Composing Components
2-
3-cel-tui components are plain functions that return `Node` trees. There are two patterns depending on whether the component needs internal state.
4-
5-## Stateless components
6-
7-Simple functions that take props and return a `Node`. Called every render cycle inside `cel.viewport()`. All state is external — passed in as props.
8-
9-```ts
10-import type { ContainerNode } from "@cel-tui/types";
11-import { HStack, VStack, Text } from "@cel-tui/core";
12-
13-function StatusBar(left: string, right: string): ContainerNode {
14- return HStack({ fgColor: "color00", bgColor: "color07" }, [
15- Text(` ${left}`),
16- VStack({ flex: 1 }, []), // spacer
17- Text(`${right} `),
18- ]);
19-}
20-
21-// Usage — called fresh each render
22-cel.viewport(() =>
23- VStack({ height: "100%" }, [
24- mainContent(),
25- StatusBar(filename, `${lines} lines`),
26- ]),
27-);
28-```
29-
30-This is the pattern used by `Button`, `Divider`, `Spacer`, `VDivider`, `Markdown`, and `SyntaxHighlight` — stateless functions that derive output from current inputs. Prefer it whenever possible — it's simple, testable, and composable.
31-
32-## Stateful components (factory pattern)
33-
34-When a component needs internal state that persists across renders (e.g., a search query, cursor position, scroll offset), use a **factory function** that returns a callable instance. State lives in the closure. The user calls the instance each render to get a fresh `Node` tree.
35-
36-```ts
37-import type { ContainerNode, Color } from "@cel-tui/types";
38-import { cel, VStack, HStack, Text } from "@cel-tui/core";
39-
40-interface ToggleGroupProps {
41- options: string[];
42- onSelect: (value: string) => void;
43- activeColor?: Color;
44-}
45-
46-interface ToggleGroupInstance {
47- (): ContainerNode;
48- reset(): void;
49-}
50-
51-function ToggleGroup(props: ToggleGroupProps): ToggleGroupInstance {
52- const { options, onSelect, activeColor = "color06" } = props;
53- let activeIndex = 0;
54-
55- function handleKey(key: string): boolean | void {
56- if (key === "left" && activeIndex > 0) {
57- activeIndex--;
58- cel.render();
59- } else if (key === "right" && activeIndex < options.length - 1) {
60- activeIndex++;
61- cel.render();
62- } else if (key === "enter") {
63- onSelect(options[activeIndex]!);
64- } else {
65- return false; // unrecognized key — let it bubble to ancestors
66- }
67- }
68-
69- function render(): ContainerNode {
70- return HStack(
71- { focusable: true, onKeyPress: handleKey, gap: 1 },
72- options.map((opt, i) =>
73- Text(` ${opt} `, {
74- fgColor: i === activeIndex ? "color00" : undefined,
75- bgColor: i === activeIndex ? activeColor : undefined,
76- }),
77- ),
78- );
79- }
80-
81- render.reset = () => {
82- activeIndex = 0;
83- };
84- return render as ToggleGroupInstance;
85-}
86-
87-// Usage — create once, call each render
88-const formatToggle = ToggleGroup({
89- options: ["JSON", "YAML", "TOML"],
90- onSelect: (fmt) => {
91- format = fmt;
92- cel.render();
93- },
94-});
95-
96-cel.viewport(() =>
97- VStack({ height: "100%" }, [Text("Output format:"), formatToggle()]),
98-);
99-```
100-
101-## Key points
102-
103-- **Create once** outside `cel.viewport()`. The closure captures mutable state.
104-- **Call each render** inside `cel.viewport()` — the function builds a fresh node tree from current state.
105-- **`cel.render()`** is importable from `@cel-tui/core` — stateful components call it after internal state changes to trigger re-renders.
106-- **Key bubbling** — `onKeyPress` handlers bubble from innermost to root. Return `false` from a handler to signal the key was not consumed and let it continue to the next ancestor. Return `void`/`undefined` to consume (backward-compatible). Components like `Select` return `false` for unrecognized keys, so app-level shortcuts on parent containers work automatically.
107-- **`.reset()`** or other methods — attach to the render function (functions are objects in JS) to expose imperative control.
108-
109-This is the pattern used by `Select` from `@cel-tui/components`.
.agents/skills/rr/SKILL.md+0−20
@@ -1,20 +0,0 @@
1----
2-name: rr
3-description: Use this skill when explicitly requested by the user.
4----
5-
6-# Code Review Request
7-
8-Use this skill only when explicitly asked by the user.
9-
10-## How to review
11-
12-1. Understand the codebase, read the changes in full, and determine whether you understand the direction of the changes.
13-2. Ask the user any clarifying questions if needed.
14-3. Review the code changes for alignment with the direction, code quality, and common agent-induced anti-patterns.
15-4. Present your findings in a human-readable way. Do not suggest fixes; simply expose the issues. Do not give priorities or severities.
16-
17-## Review style
18-
19-1. Do not report the same issue multiple times.
20-2. Don't be a style zealot or nitpicker. Focus on code correctness, quality, and alignment with the codebase and the user's goal for the changes.
.agents/skills/systematic-debugging/CREATION-LOG.md+0−119
@@ -1,119 +0,0 @@
1-# Creation Log: Systematic Debugging Skill
2-
3-Reference example of extracting, structuring, and bulletproofing a critical skill.
4-
5-## Source Material
6-
7-Extracted debugging framework from `/Users/jesse/.claude/CLAUDE.md`:
8-- 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation)
9-- Core mandate: ALWAYS find root cause, NEVER fix symptoms
10-- Rules designed to resist time pressure and rationalization
11-
12-## Extraction Decisions
13-
14-**What to include:**
15-- Complete 4-phase framework with all rules
16-- Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze")
17-- Pressure-resistant language ("even if faster", "even if I seem in a hurry")
18-- Concrete steps for each phase
19-
20-**What to leave out:**
21-- Project-specific context
22-- Repetitive variations of same rule
23-- Narrative explanations (condensed to principles)
24-
25-## Structure Following skill-creation/SKILL.md
26-
27-1. **Rich when_to_use** - Included symptoms and anti-patterns
28-2. **Type: technique** - Concrete process with steps
29-3. **Keywords** - "root cause", "symptom", "workaround", "debugging", "investigation"
30-4. **Flowchart** - Decision point for "fix failed" → re-analyze vs add more fixes
31-5. **Phase-by-phase breakdown** - Scannable checklist format
32-6. **Anti-patterns section** - What NOT to do (critical for this skill)
33-
34-## Bulletproofing Elements
35-
36-Framework designed to resist rationalization under pressure:
37-
38-### Language Choices
39-- "ALWAYS" / "NEVER" (not "should" / "try to")
40-- "even if faster" / "even if I seem in a hurry"
41-- "STOP and re-analyze" (explicit pause)
42-- "Don't skip past" (catches the actual behavior)
43-
44-### Structural Defenses
45-- **Phase 1 required** - Can't skip to implementation
46-- **Single hypothesis rule** - Forces thinking, prevents shotgun fixes
47-- **Explicit failure mode** - "IF your first fix doesn't work" with mandatory action
48-- **Anti-patterns section** - Shows exactly what shortcuts look like
49-
50-### Redundancy
51-- Root cause mandate in overview + when_to_use + Phase 1 + implementation rules
52-- "NEVER fix symptom" appears 4 times in different contexts
53-- Each phase has explicit "don't skip" guidance
54-
55-## Testing Approach
56-
57-Created 4 validation tests following skills/meta/testing-skills-with-subagents:
58-
59-### Test 1: Academic Context (No Pressure)
60-- Simple bug, no time pressure
61-- **Result:** Perfect compliance, complete investigation
62-
63-### Test 2: Time Pressure + Obvious Quick Fix
64-- User "in a hurry", symptom fix looks easy
65-- **Result:** Resisted shortcut, followed full process, found real root cause
66-
67-### Test 3: Complex System + Uncertainty
68-- Multi-layer failure, unclear if can find root cause
69-- **Result:** Systematic investigation, traced through all layers, found source
70-
71-### Test 4: Failed First Fix
72-- Hypothesis doesn't work, temptation to add more fixes
73-- **Result:** Stopped, re-analyzed, formed new hypothesis (no shotgun)
74-
75-**All tests passed.** No rationalizations found.
76-
77-## Iterations
78-
79-### Initial Version
80-- Complete 4-phase framework
81-- Anti-patterns section
82-- Flowchart for "fix failed" decision
83-
84-### Enhancement 1: TDD Reference
85-- Added link to skills/testing/test-driven-development
86-- Note explaining TDD's "simplest code" ≠ debugging's "root cause"
87-- Prevents confusion between methodologies
88-
89-## Final Outcome
90-
91-Bulletproof skill that:
92-- ✅ Clearly mandates root cause investigation
93-- ✅ Resists time pressure rationalization
94-- ✅ Provides concrete steps for each phase
95-- ✅ Shows anti-patterns explicitly
96-- ✅ Tested under multiple pressure scenarios
97-- ✅ Clarifies relationship to TDD
98-- ✅ Ready for use
99-
100-## Key Insight
101-
102-**Most important bulletproofing:** Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction.
103-
104-## Usage Example
105-
106-When encountering a bug:
107-1. Load skill: skills/debugging/systematic-debugging
108-2. Read overview (10 sec) - reminded of mandate
109-3. Follow Phase 1 checklist - forced investigation
110-4. If tempted to skip - see anti-pattern, stop
111-5. Complete all phases - root cause found
112-
113-**Time investment:** 5-10 minutes
114-**Time saved:** Hours of symptom-whack-a-mole
115-
116----
117-
118-*Created: 2025-10-03*
119-*Purpose: Reference example for skill extraction and bulletproofing*
.agents/skills/systematic-debugging/SKILL.md+0−296
@@ -1,296 +0,0 @@
1----
2-name: systematic-debugging
3-description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
4----
5-
6-# Systematic Debugging
7-
8-## Overview
9-
10-Random fixes waste time and create new bugs. Quick patches mask underlying issues.
11-
12-**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
13-
14-**Violating the letter of this process is violating the spirit of debugging.**
15-
16-## The Iron Law
17-
18-```
19-NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
20-```
21-
22-If you haven't completed Phase 1, you cannot propose fixes.
23-
24-## When to Use
25-
26-Use for ANY technical issue:
27-- Test failures
28-- Bugs in production
29-- Unexpected behavior
30-- Performance problems
31-- Build failures
32-- Integration issues
33-
34-**Use this ESPECIALLY when:**
35-- Under time pressure (emergencies make guessing tempting)
36-- "Just one quick fix" seems obvious
37-- You've already tried multiple fixes
38-- Previous fix didn't work
39-- You don't fully understand the issue
40-
41-**Don't skip when:**
42-- Issue seems simple (simple bugs have root causes too)
43-- You're in a hurry (rushing guarantees rework)
44-- Manager wants it fixed NOW (systematic is faster than thrashing)
45-
46-## The Four Phases
47-
48-You MUST complete each phase before proceeding to the next.
49-
50-### Phase 1: Root Cause Investigation
51-
52-**BEFORE attempting ANY fix:**
53-
54-1. **Read Error Messages Carefully**
55- - Don't skip past errors or warnings
56- - They often contain the exact solution
57- - Read stack traces completely
58- - Note line numbers, file paths, error codes
59-
60-2. **Reproduce Consistently**
61- - Can you trigger it reliably?
62- - What are the exact steps?
63- - Does it happen every time?
64- - If not reproducible → gather more data, don't guess
65-
66-3. **Check Recent Changes**
67- - What changed that could cause this?
68- - Git diff, recent commits
69- - New dependencies, config changes
70- - Environmental differences
71-
72-4. **Gather Evidence in Multi-Component Systems**
73-
74- **WHEN system has multiple components (CI → build → signing, API → service → database):**
75-
76- **BEFORE proposing fixes, add diagnostic instrumentation:**
77- ```
78- For EACH component boundary:
79- - Log what data enters component
80- - Log what data exits component
81- - Verify environment/config propagation
82- - Check state at each layer
83-
84- Run once to gather evidence showing WHERE it breaks
85- THEN analyze evidence to identify failing component
86- THEN investigate that specific component
87- ```
88-
89- **Example (multi-layer system):**
90- ```bash
91- # Layer 1: Workflow
92- echo "=== Secrets available in workflow: ==="
93- echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
94-
95- # Layer 2: Build script
96- echo "=== Env vars in build script: ==="
97- env | grep IDENTITY || echo "IDENTITY not in environment"
98-
99- # Layer 3: Signing script
100- echo "=== Keychain state: ==="
101- security list-keychains
102- security find-identity -v
103-
104- # Layer 4: Actual signing
105- codesign --sign "$IDENTITY" --verbose=4 "$APP"
106- ```
107-
108- **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
109-
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/condition-based-waiting-example.ts+0−164
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/condition-based-waiting.md+0−115
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/defense-in-depth.md+0−122
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/find-polluter.sh+0−63
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/root-cause-tracing.md+0−169
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/test-academic.md+0−14
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/test-pressure-1.md+0−58
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/test-pressure-2.md+0−68
Cut short: this commit's diff is over 1000 lines.
.agents/skills/systematic-debugging/test-pressure-3.md+0−69
Cut short: this commit's diff is over 1000 lines.
.agents/skills/typescript-advanced-types/SKILL.md+0−717
Cut short: this commit's diff is over 1000 lines.
AGENTS.md+48−8
Cut short: this commit's diff is over 1000 lines.
README.md+1−18
Cut short: this commit's diff is over 1000 lines.
skills-lock.json+0−10
Cut short: this commit's diff is over 1000 lines.
src/agent.ts+13−3
Cut short: this commit's diff is over 1000 lines.
src/tool-bash.ts+6−15
Cut short: this commit's diff is over 1000 lines.
src/tool-output.ts+0−99
Cut short: this commit's diff is over 1000 lines.