prep-major-release

name	prep-major-release
description	Prepare Domotion for a major release — refresh the README so it stays compelling and advertises the best features, review + update the docs site (Astro/Starlight content, showcase, usage pages) and its demos, refresh the AI-agent usage guide, and hand the maintainer a screenshot/recording capture checklist.
allowed-tools	Read, Grep, Glob, Bash, Edit, Write, Agent

Prepare the project for a major release. Domotion moves fast, so the public-facing surface — the README, the docs site (site/), the demo visuals, and the AI-agent usage guide — drifts behind the feature set. This skill brings them back in sync: it updates README.md to stay compelling and advertise the most important and interesting features, reviews and updates the site content (the hosted Starlight docs: showcase, usage, start, developer pages), reviews the demo modes / screenshots and hands the maintainer a concrete capture checklist, and refreshes llms.txt (the guide agents use to drive Domotion as a tool).

This skill does NOT capture screenshots/recordings or push a release. It updates prose, site content, and wiring, and produces a capture checklist; the maintainer captures the new visuals. It also does not edit the sync-docs-generated reference pages (those regenerate from the schema — see Step 4).

Step 1 — Survey what actually changed

Figure out what's new and compelling since the README last reflected reality. Don't guess from memory — read the sources of truth:

• git log --oneline since the last README-touching commit (git log -1 --format=%H -- README.md, then git log --oneline <that>..HEAD). Group commits into feature areas.
• The numbered docs/ set, newest first (ls docs/*.md | sort -V | tail -25) — each "Shipped" doc is a candidate headline feature. docs/ai/requirements-summary.md is the synthesized status view.
• FEATURES.md and docs/ai/code-summary.md for the current capability + bin inventory.
• package.json bin (the published CLIs) and examples/ (what's demoable).

Output a short internal list: "headline features now shippable that the README under-sells or omits." Templates, terminal capture, animation transitions, device mockups, scroll, svg-to-video, the review/debug tooling are the usual suspects — verify which are actually shipped before advertising them.

Step 2 — Review + update README.md

The README is the single most important advertisement. Keep it compelling, tight, and honest.

• Lead with the hook. The hero image + the one-sentence "what it is" + the "Why" (the pain it removes) must land in the first screen. Sharpen these if the value prop has grown.
• Advertise the best features prominently — but curate, don't enumerate. Pull the genuinely interesting/differentiating capabilities up where a skimming reader will see them (e.g. the template library that turns a few flags into an animated SVG; faithful capture of real Chromium paint; terminal-session capture; one-command SVG→MP4). A capability buried in docs/ that nobody knows about is wasted — surface it. A laundry list nobody reads is also wasted — cut it.
• Keep the structure scannable: hook → why → status/platform honesty → install → usage (the headline CLIs with copy-pasteable one-liners) → a "what else it does" highlights pass → links into the hosted docs/gallery for depth. Don't let any section bloat; the README is a launchpad, not the manual.
• Preserve the honesty that's already there (the ## Status early-stage note and the ## Platform support macOS-calibrated caveat). Update them if reality changed, but don't quietly drop the caveats.
• Verify every claim and command you keep or add against the current code — run the CLI --help, check the bin names, confirm the example paths exist. American-English spelling throughout (per CLAUDE.md).
• Make surgical edits to the existing README where it's still good; only rewrite sections whose framing no longer fits. End with a quick read-through for flow.

Step 3 — Review the demo modes + screenshots

The visuals that sell the project: the README hero (examples/output/domotion-word-demo.svg), the runnable demo scripts under examples/ (regenerated by npm run demos:examples), and the demos embedded on the site's Showcase + template gallery (site/src/content/docs/showcase.mdx and the usage/ pages — Astro/Starlight, post-DM-1308 rebuild). The committed example SVGs (examples/output/, examples/output/templates/, examples/animate/<name>/, site/demo-assets/apps/) are surfaced to the site by site/scripts/build-demos.mjs (npm --prefix site run build-demos → site/public/demos/); the site embeds them with plain <img src="/domotion/demos/…svg">. (The old kerfjs manual — site/pages/guides/*, npm run manual:images — was removed in DM-1308; don't look for it.)

Assess whether the current demos still represent the project well:

• Coverage — do the demos showcase the current headline features? If a major capability shipped with no demo (e.g. a new template family, terminal capture, a transition), that's a gap. If a demo shows a deprecated/less-interesting path, flag it for replacement.
• Quality / freshness — are any committed example SVGs stale (regenerate locally with npm run demos:examples and diff)? Is the hero still the strongest first impression?
• Fewer / different — more demos isn't better. Recommend cutting weak ones and sharpening the few that best tell the story. Prefer animated SVGs (they sell the "it moves" point) over static where it helps.

Because the maintainer captures the actual screenshots/recordings, your deliverable here is a concrete checklist, e.g.:

Screenshots / demos to (re)capture for the release:
- [ ] <name> — <what it should show> — <how to produce it: command / example script / fixture> — [new | replace <old> | regenerate]
...

Make each item self-contained (the maintainer should be able to run it without re-deriving context). If a demo needs a new example script or fixture, write that script/fixture so the maintainer only has to run it. Don't capture or commit binary screenshots yourself unless they're a deterministic demos:examples output you can regenerate.

Step 4 — Review + update the docs site (site/)

The hosted docs (Astro + Starlight, rebuilt in DM-1308) are the other public face of the project, and they drift just like the README. Actually update the site prose here — this step produces edits, not just a checklist. Content lives in site/src/content/docs/:

• index.mdx (landing) + why-domotion.md — the hook / value prop. Keep in step with the README's lead.
• start/ — what-is-domotion.md, quickstart.md (install + first commands; verify the commands run).
• usage/ — capture.md, animate.md, templates.md, terminal.md, export.md, composite.md, web-app-demos.md. These are the per-feature how-tos; bring each in sync with the Step 1 survey (new verbs/flags/templates/transitions, renamed/removed ones).
• developer/ — api.md, using-ai.md, custom-templates.md, animate-config.md. (The developer/reference/* pages are generated by site/scripts/sync-docs.mjs from schemas/ on every build — do NOT hand-edit them; if a contract changed, update the schema/source, not the generated page.)
• showcase.mdx — the demo gallery. Every demo is one self-contained .svg embedded via <img src="/domotion/demos/<name>.svg">. Surface the current headline features here; add a card for a major capability that shipped without one, and cut/replace stale ones.

Do this:

1. Sync the content to reality from the Step 1 survey + the updated README. Verify every command, flag, template name, and CLI snippet against the current build (same rigor as the README). American-English throughout.
2. Check the demo wiring. The SVGs the site embeds are copied from the repo by npm --prefix site run build-demos (sources: examples/output/, examples/output/templates/, examples/animate/<name>/, site/demo-assets/apps/ → site/public/demos/). Make sure every <img src="/domotion/demos/…svg"> in the content resolves to a real file after that copy, and that new demos you want shown are committed in those source locations. Fold any new demo wiring into the Step 3 capture checklist where the maintainer must supply the actual asset.
3. Build it to catch breakage: npm --prefix site install (if needed) then npm --prefix site run build (runs build-demos + build-icons + sync-docs + astro build); at minimum run npm --prefix site run build-demos + npm --prefix site run sync-docs. There's a layout guard: npm --prefix site test (check-hero-layout.mjs).
4. Keep the public-site boundary: never leak local-only DM-XXX ticket references or .hotsheet/ mentions into site content (per CLAUDE.md; the sync-docs script header documents this). Pair any necessary reference with a self-contained summary or omit it.

If a site change is genuinely the maintainer's call (drop a page, restructure nav), surface it as an open question rather than deciding silently.

Step 5 — Refresh the AI-agent usage doc (llms.txt)

llms.txt at the repo root is the concise, self-contained guide an AI agent uses Domotion as a tool (distinct from CLAUDE.md/docs/ai/*, which are about editing this repo). It ships in the npm package (package.json files) and is the thing other agents are pointed at, so it must not drift.

Bring it back in sync with the survey from Step 1:

• New capabilities — if a verb, flag, template, transition, overlay, or API export shipped, add it (concise — one line, with a copy-pasteable example only where it earns its place). If something was removed/renamed, fix it.
• Verify every command, flag, template name, and export against the current build — run domotion <verb> --help, domotion template list, and import-check the named exports from dist/index.js (it's ESM). A wrong flag in this doc misleads every agent that reads it. American-English.
• Keep it tight. It's "thorough but concise" — the launchpad for an agent, not the manual. Prune anything stale or low-value; link to domotion --help and the hosted docs for depth rather than duplicating them.
• Keep the package.json files entry and the README pointer to llms.txt intact.

Output

Report:

• README — the sections updated and why (the features now surfaced; anything cut).
• Site — the site/ pages updated and why (showcase cards added/replaced, usage pages synced, any demo <img> wiring fixed); whether npm --prefix site run build succeeded.
• Demos — the capture checklist (Step 3), plus any new example scripts/fixtures you added to support it.
• llms.txt — what changed.
• Open questions — anything where the right call is the maintainer's (e.g. "drop the X demo?", "restructure the site nav?"), surfaced as a question, not a silent decision.

Keep FEATURES.md and the docs/ai/* summaries in sync if your survey turned up drift (or note it for the check-requirements-against-code skill).