# E2E validation checklist (alpha.27)

Manual end‑to‑end acceptance before the first real alpha publish. Run through this top‑to‑bottom; each step has a ✅ / ❌ answer. Any ❌ is a blocker.

Prereqs:
- Node 20+
- A DeepSeek (or OpenAI‑compatible) API key
- For steps marked **[figma]**: Figma Desktop, a PAT, the Desktop Bridge plugin running (see `docs/figma-setup.md`)

---

## Stage A — Install and first run

- [ ] `npm i -g @wz927/codedesign@alpha` succeeds (or `npm link` from the repo).
- [ ] `codedesign --version` prints `codedesign 1.0.0-alpha.27`.
- [ ] `codedesign --help` lists `ds <sub>` and `auth <sub>` subcommands.
- [ ] First run prompts for an API key; afterwards `codedesign auth show` shows `deepseek_api_key` masked.
- [ ] Second launch goes straight into the REPL with no re‑prompt.

## Stage B — CLI subcommands

- [ ] `codedesign auth set tavily_api_key tvly-xxx` writes to `auth.toml` (verify with `auth show`, secret masked).
- [ ] `codedesign auth remove tavily_api_key` deletes it cleanly.
- [ ] `codedesign ds list` prints the 5 directions with palette previews.
- [ ] `codedesign ds init editorial-monocle --brand Acme` writes `~/.codedesign/ds.json` + `design-systems/editorial-monocle/DESIGN.md`.
- [ ] `codedesign ds show` prints the bound DS, brand `Acme`, `9/9` sections on DESIGN.md.
- [ ] `codedesign ds pull stripe` vendors `DESIGN.md` from `nexu-io/open-design` under `design-systems/stripe/`.

## Stage C — REPL basics

- [ ] `/tools` lists at minimum: `ds_query`, `list_directions`, `pick_direction`, `craft_lint`, `figma_distill_ds`, `image_understand`, `list_cases`, `read_file`, `list_dir`. Conditionally: `figma_execute` (if token set), `web_search` (if tavily key set).
- [ ] `/ds` confirms the same DS path as `codedesign ds show`.
- [ ] `/skills` lists all 8 skills (pitch‑deck, mobile‑screens, dashboard, landing‑page, email‑template, docs‑site, form‑system, onboarding‑flow).
- [ ] `/skill dashboard-figma` activates it; the next reply should mention density / data hierarchy conventions.
- [ ] `/skill none` clears it.

## Stage D — PRD loop (no Figma needed)

1. Create a short PRD file `./test-prd.md` with a 2‑paragraph brief (e.g. "a note‑taking app landing page, target indie hackers").
2. In the REPL: `read this PRD and produce a visual plan: ./test-prd.md`

- [ ] Agent calls `read_file` and surfaces PRD contents.
- [ ] Agent calls `ds_query` or references the bound DS palette in its proposal.
- [ ] Produced plan cites specific hex from the DS (not invented colours).
- [ ] Running `/critique` on the reply returns 5 panelist scores and converges within ≤ 3 rounds.

## Stage E — Web search (optional, needs `tavily_api_key`)

- [ ] Prompt: `search for current onboarding UX patterns in 2026`
- [ ] Agent calls `web_search`, cites sources `[1]`, `[2]`, …
- [ ] A refresh of the same prompt does NOT re‑cite stale results (context respects turn freshness).

## Stage F — Figma DS distill **[figma, read path]**

- [ ] `codedesign auth set figma_token figd_…` set.
- [ ] `codedesign ds import https://www.figma.com/design/<FILE_KEY>/Any-Title` on a file you have read access to.
- [ ] Preview prints `bg / surface / fg / muted / border / accent` each with a provenance tag (`variable` / `style` / `sample`).
- [ ] Confirm `y` → `ds.json` + `DESIGN.md` written. `codedesign ds show` reflects the new palette.
- [ ] Rerun with `--force --yes` — overwrites without prompting.

## Stage G — Figma write path **[figma, write path]**

Prereq: Figma Desktop open, a scratch file open, Desktop Bridge plugin window visible with green "MCP ready" dot.

1. In the REPL: `in my current Figma file, create a single 1440x900 frame called "hero", with a heading "Hello from codedesign" using the bound display font and brand colours`
2. Agent should call `figma_execute` with a small block of Plugin API JS.

- [ ] Frame appears in the Figma file within a few seconds.
- [ ] Text node uses the display font from the bound DS.
- [ ] Fill colour matches `palette.fg` or the explicit colour requested.
- [ ] Closing the bridge plugin window and retrying shows a clean `bridge not running` error, not a silent hang.

## Stage H — Session persistence

- [ ] After several turns, `~/.codedesign/sessions/<timestamp>-*.json` exists.
- [ ] `codedesign --resume` lists it (newest first, ≤ 20 rows).
- [ ] `codedesign --resume <id>` reopens with history intact; next turn appends to the same file.

## Stage I — Compaction

- [ ] After >40 messages, `/compact` reduces history; the next reply remains coherent with earlier context.
- [ ] `/compact --auto` then triggers silently at the threshold on subsequent turns.

---

## Sign‑off

- Date tested: `_______________`
- Operator: `_______________`
- Environment: macOS / Linux / Windows (Node version `_____`)
- Any ❌ above: `_______________`

If every box above is ✅, the alpha is ready to publish.
