Ratatui Docs Demo Loop

---
name: ratatui-docs-demo-loop
description: Use this skill whenever the user wants to turn a ratatui-kit example into a story-driven docs/tutorial page, create a real VHS terminal recording, automate example recording, build a docs homepage vertical slice, or run one complete docs/example loop for ratatui-kit. This skill should trigger even if the user says "just do one example", "record the demo", "make a tutorial from this example", "homepage needs runtime visuals", or "run the loop".
---

# ratatui Docs Demo Loop

Use this skill to produce one complete vertical slice for ratatui-kit documentation:

`example -> real VHS recording -> docs asset -> story-first tutorial -> optional homepage hook -> validation`

The goal is a repeatable loop, not a batch rewrite. A good run leaves behind one polished example that proves the pipeline works and can become the template for the rest.

## First Moves

1. Inspect the repository before making choices:
   - read `AGENTS.md` or provided repository instructions
   - inspect `Cargo.toml`, `examples/`, and the docs app (`docs/package.json`, `docs/astro.config.*`, existing docs pages)
   - check existing assets under `docs/public/` and example docs under `docs/src/content/docs/`
2. Pick exactly one example unless the user explicitly asks for more.
   - Prefer `counter` for the first loop because it is small, dynamic, and already tells a hooks/state story.
3. Use VHS as the only recording path.
   - default docs inline asset: `docs/public/recordings/<example>.gif`
   - homepage or richer video asset: `docs/public/recordings/<example>.mp4` or `.webm`
   - reproducible recipe: `docs/tapes/<example>.tape`
4. Keep generated assets real. Do not fake runtime output with hand-written terminal art or decorative mockups unless the user explicitly asks for concept art.
5. Keep edits scoped to the selected example, related docs page/component, and recording artifacts.

Read only the references needed for the current run:

- `references/recording-tools.md` when installing tools or recording terminal output.
- `references/artifact-contract.md` before writing generated assets or test outputs.
- `references/story-tutorial.md` before drafting or rewriting a tutorial page.
- `references/quality-gates.md` before final validation.

## Loop Workflow

### 1. Scope the slice

Capture these values in your working notes or test output:

- selected example name
- command used to run it
- VHS output format to produce (`gif`, `mp4`, or `webm`)
- docs page to update or create
- validation commands to run

If the user is exploring and has asked not to execute, stop after the plan. If the user asks to implement, proceed.

### 2. Prepare recording

Use deterministic terminal conditions:

- fixed terminal size, usually 80x24 or 100x30
- stable theme and font assumptions
- predictable waits
- no local secrets, hostnames, usernames, or shell prompts in the capture

Use a VHS tape for scripted input and waits so the asset can be regenerated.

### 3. Generate the artifact

Write assets to the docs public tree following `references/artifact-contract.md`.

For a first slice, produce one VHS-rendered asset:

- `docs/public/recordings/<example>.gif`
- `docs/public/recordings/<example>.mp4`
- `docs/public/recordings/<example>.webm`

Keep the VHS recipe under:

- `docs/tapes/<example>.tape`

### 4. Write the docs page

Use the story-first shape from `references/story-tutorial.md`:

- lead with the running example and its output
- show the smallest runnable code path
- explain the concept after the reader has seen the behavior
- connect the example to ratatui-kit architecture
- end with the next natural example

Avoid writing a marketing landing page as a tutorial. The tutorial should feel like a guided build, not a feature list.

### 5. Wire homepage only when useful

If the user asks for a homepage slice, reference the real runtime artifact from the selected example. Keep actual product behavior prominent. For a user-requested brand hero, place real runtime examples immediately after the hero instead of substituting decorative mockups for them.

Read `references/homepage-brand.md` when changing the bilingual homepage, its playback controls, or brand assets.

### 6. Validate and report

Run the smallest meaningful validation for the slice, then broaden if risk justifies it:

- generated VHS artifact exists and is non-empty
- VHS tape exists and can reproduce the recording
- visual quality is checked with VHS `Screenshot` PNGs following `references/quality-gates.md`
- selected example still builds or runs
- docs build still passes
- full Cargo checks only when code changed or public Rust API behavior is touched

Summarize what changed, which commands ran, where the artifacts are, and what remains.

## Output Shape

When finishing a run, report:

- selected example
- generated artifact paths
- docs paths changed or created
- validation commands and results
- any tool limitations or fallback used

Keep the final response concise and concrete.