# v0.5 release plan

## Objective

Close the remaining vertical-slice gate without adding themes, search, MCP, or renderer adapters. The release must make the three agentic recipes easy to find, easy to copy, and safe to trust in a real browser. Astryx's setup suggests one additional release criterion: an agent should have an explicit setup prompt and a machine-readable catalog without needing a CLI or MCP server.

## Ranked slices

| Slice | Evidence | Impact | Confidence | Reach | Reversibility | Effort | Priority estimate |
|---|---|---:|---:|---:|---:|---:|---:|
| Three standalone recipes | The current flow is one combined page; J-F4 explicitly requires three recipes and complete state coverage. | 5 | 5 | 5 | 5 | 3 | 208 |
| Agentic component docs | The catalog currently exposes four foundation pages, while eight agentic components are discoverable mainly through the starter and raw contracts. | 5 | 5 | 5 | 5 | 4 | 156 |
| Browser release verification | Static checks pass, but browser-level focus, responsive, trust-state, and transition behavior need a repeatable proof. | 5 | 4 | 4 | 4 | 4 | 80 |
| Agent-ready setup and catalog | Astryx demonstrates that setup prompts, machine-readable discovery, and templates are part of the AI interface; `agent-ui` can ship the lightweight version without adding a CLI. | 5 | 5 | 5 | 5 | 2 | 156 |

Priority estimate uses the labeled 1–5 approximation: impact × confidence × reach × reversibility ÷ effort.

## Slice 1: standalone recipes

- [x] Add a patterns index with links to three focused recipes.
- [x] Add `chat-streaming.html` with streaming, success, error, and cancelled states.
- [x] Add `tool-approval.html` with exact arguments, immutable action ID, approval, rejection, and cancellation.
- [x] Add `question-resume.html` with native submission and waiting, answered, error, and cancelled states.
- [x] Keep all states in the HTML so the no-JS reading path remains honest.

**Done when:** each recipe works from a checked-out folder, has no external runtime request, remains usable at 390px, and is linked from the docs shell.

## Slice 2: agentic component docs

- [x] Generate pages for the eight agentic components from one documented metadata source.
- [x] Give every agentic page the same order: Specimen (Preview / HTML / CSS / Install tabs), contract, accessibility/security, and source links.
- [x] Link every page from the 12-component inventory.
- [x] Add a drift check so generated pages cannot silently diverge from the metadata source.

**Done when:** an agent can identify, install, copy, and validate any MVP agentic component without opening the source project.

## Slice 3: browser release verification

- [x] Add static recipe and generated-page contract checks to the existing quality gate.
- [x] Add a browser harness for required states, theme, reduced motion, keyboard focus, mobile overflow, external requests, and trust-state invariants.
- [x] Run the harness locally against all three recipes and all eight agentic docs pages.
- [x] Add the browser job to CI with a pinned browser CLI.
- [x] Run an adversarial browser pass against empty submits, repeated decisions, state switching, mobile layout, and refresh.

**Done when:** the release checks prove the three recipes and eight agentic docs pages in desktop, mobile, dark mode, reduced motion, and keyboard paths.

## Slice 4: agent-ready setup and catalog

- [x] Add repository-level `AGENTS.md` with a copyable setup prompt, component selection rules, trust boundary, and verification commands.
- [x] Add `docs/guides/ai-setup.html` for humans who want to hand the same prompt to an agent.
- [x] Generate `docs/catalog.json` with the 12 MVP components, states, required and optional dependencies, fixtures, raw paths, docs pages, variables, events, and host-owned responsibilities.
- [x] Include the starter and three focused recipes in the catalog so templates remain first-class discovery paths.
- [x] Fail `scripts/check-all.js` when the generated catalog is stale, incomplete, or points at a missing file.
- [ ] Run one catalog-first trial and compare component selection errors with the existing docs-only trial protocol.

**Done when:** a fresh agent can read `AGENTS.md` and `docs/catalog.json`, choose a recipe or component without guessing, and pass the existing quality checks without a package install.

## Deliberately deferred

- Command search
- A large CLI or package installer
- MCP server and renderer adapters
- Additional shapes and theme presets
- Markdown, terminal, and code-block surfaces

These remain downstream of the v0.5 proof rather than competing with it.

## Missing data to collect after release

- First external user reproduction time from the docs
- Screen-reader review on at least one recipe per state family
- Which agentic component users copy independently of the starter
- Any approval or cancellation wording that causes hesitation
- Whether catalog-first discovery reduces component-selection errors versus the current docs-only path