# charm-tui

A portable agent skill for building and improving Go terminal interfaces using the Charm ecosystem. The entry point is [SKILL.md](SKILL.md); it contains activation metadata, a working procedure, decision rules, and links to deeper material.

Research snapshot: **23 September 2026**. This is an independent synthesis of official library documentation and selected source from Glow, Gum, Crush, and Soft Serve, plus Huh's documented form/accessibility design. It is not an official Charm skill or a claim that those applications were fully audited.

## Added: do-by-example teaching

The skill now includes [eight worked tasks](examples/WORKED-EXAMPLES.md) and [three complete Go example programs](examples/worked/README.md): a compact picker, debounced search, and a follow-tail event monitor. Each task shows the implementation, concrete interaction sequence, regression checks, and limits—not just a description of the desired property. The main skill also embeds three short worked fixes so examples are part of the default instructions.

The actual demo core source files have 26 executed tests, including cancellation and channel behavior. Charm integration and rendering tests are provided separately and remain unexecuted because toolchain/dependency downloads are unavailable here. See [verification](VERIFICATION.md).

## Use

Keep the entire `charm-tui` directory together and place it in the skills directory configured by your agent. The folder is provider-neutral; no network connector, model API, runtime plugin, or global configuration is required. An agent without a skill loader can read `SKILL.md` directly and open its references as needed.

Example requests:

> Review this Go picker for Charm-style interaction quality, focus correctness, and resize behavior. Preserve its existing appearance and keys.

> Build a small inline server selector. Use the charm-tui skill, keep stdout machine-readable, and avoid adding a full-screen application shell.

> Improve this Bubble Tea streaming view. Fix stale updates and scroll behavior before changing its theme.

Do not read every reference into context automatically. Start with the skill, then load the topic relevant to the work.

## Contents

| Path | Purpose |
| --- | --- |
| [SKILL.md](SKILL.md) | Main instructions, worked fixes, activation description |
| [Do by example](examples/WORKED-EXAMPLES.md) | Eight task-to-code walkthroughs with expected behavior and regression checks |
| [Complete Go demos](examples/worked/README.md) | Picker, cancellable search, follow-tail monitor, and their tests |
| [Design and interaction](references/design-and-interaction.md) | Screen hierarchy, feedback, focus, help, visual restraint, accessibility |
| [Architecture and effects](references/architecture-and-effects.md) | Ownership, composition, commands, generation guards, streams |
| [Layout and rendering](references/layout-and-rendering.md) | v2 box arithmetic, cells, resizing, style and cache correctness |
| [Versions and components](references/versions-and-components.md) | API-version traps and choosing the smallest useful component |
| [Testing and release](references/testing-and-release.md) | State, snapshot, integration, terminal, and performance checks |
| [Case studies](references/case-studies.md) | Observations, transferable lessons, and limits |
| [Source ledger](references/sources.md) | Primary references and exact inspection scope |
| [Evaluation scenarios](evals/scenarios.json) | Adversarial prompts and explicit pass/fail expectations |
| [Contract exercises](examples/contracts/README.md) | Small runnable Go tests for selected invariants |
| [Verification record](VERIFICATION.md) | What was and was not executed when packaging |

## Validate locally

From the skill directory:

```sh
python3 scripts/validate.py
python3 scripts/test_offline_examples.py
cd examples/contracts
go test -v ./...
```

The validator checks package structure, entry-point metadata, relative file/anchor links, fenced-code balance, and evaluation schema. It does not browse remote links, compile the Markdown integration sketches, evaluate an agent, or test terminal rendering.

## Evaluate an agent using the skill

The JSON scenarios are portable specifications, not tied to a particular eval service. Give the agent the scenario's setup and prompt with a suitable fixture repository. Run its proposed tests and inspect the resulting diff and interaction. Score each `must_pass` item and reject a result that exhibits a `must_not` failure. Do not award a behavioral pass merely because the agent mentions the right concept.

For a comparison, run the same fixture and task with and without the skill, then review blind for preserved behavior, correct implementation, useful tests, dependency restraint, and truthful verification. Record environment and failures. The supplied scenarios were authored and structurally checked, not executed as model evaluations during packaging.