@waits/cadence 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Waits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MOTION.md

@@ -0,0 +1,70 @@
+# Motion vocabulary
+
+The controlled lexicon every changelog beat speaks. Each name is implemented in
+`src/motion/presets.ts`, frozen in `src/motion/names.ts`, and resolved by the
+`useMotion` hook (`src/motion/useMotion.ts`). Beats reference these names as
+strings — they never inline animation code.
+
+## Principles (from the product DESIGN.md)
+
+- **Ease-out only. No bounce, no elastic, never animate layout.** Entrances move
+  opacity + `transform`/`filter`, not width/height/top/left.
+- **Two easings, two jobs.**
+  - `smooth` — `cubic-bezier(0.19, 1, 0.22, 1)`. Pure ease-out. **Every entrance.**
+  - `snappy` — `cubic-bezier(0.175, 0.885, 0.32, 1.1)`. Has a deliberate slight
+    settle/overshoot. **State-feedback pops only** (the NEW badge, a toggle) —
+    never a big entrance.
+- **Respect reduced-motion.** Every preset has a `reduced` variant that drops to
+  opacity-only.
+- **Signal Blue ≤10%, one Marker-Pink gesture per scene** (the `draw`n NEW badge).
+
+## Enter presets
+
+| Name | Motion | Use for |
+|------|--------|---------|
+| `rise` | translateY ↑ + fade | headlines, single cards |
+| `settle` | scale 1.03→1 + fade | windows, data panels arriving |
+| `bloom` | fade + blur 8px→0 | painting backgrounds |
+| `type` | character-by-character typewriter | code, terminal lines |
+| `stagger` | sequential `rise` of children | list / table rows |
+| `draw` | SVG stroke reveal | diagrams, the NEW badge circle (Marker Pink) |
+| `count` | numeric tween 0→value | metrics, counters |
+
+`type` / `draw` / `count` carry their value internally — the preset gates
+visibility, the helpers (`typewriterChars`, `drawDashoffset`, `countValue`,
+`staggerDelay`) drive the value.
+
+## Exit presets
+
+| Name | Motion | Use for |
+|------|--------|---------|
+| `sink` | translateY ↑ + fade out | headlines leaving |
+| `dissolve` | fade out | most panels / code |
+| `lift` | scale 1→1.02 + fade out | a window departing forward |
+| `cut` | instant | hard scene change |
+
+## Style taxonomy — what each content type speaks
+
+The default grammar a beat follows unless overridden. This is the "language":
+pick the row, get the motion.
+
+| Content | Enter | Exit | Easing | Notes |
+|---------|-------|------|--------|-------|
+| Headline | `rise` | `sink` | smooth | eyebrow = Caveat marker-pink, `draw`n in after |
+| Eyebrow / NEW badge | `draw` | `dissolve` | smooth | the one human flourish; Marker Pink |
+| Code window | `settle` + `type` | `dissolve` | smooth | caret blinks; typing is internal |
+| Terminal line | `type` | `dissolve` | smooth | mono, single line |
+| Data panel | `settle`, rows `stagger` | `dissolve` | smooth | "streaming…" pulse is ambient, not an entrance |
+| Diagram | `draw` (edges) + `settle` (nodes) | `dissolve` | smooth | one filled accent node |
+| Metric | `count` | `dissolve` | smooth | Fira Code, tabular-nums |
+| Background | `bloom` + Ken Burns | `dissolve` | smooth | slow push-in over the whole beat |
+
+## MotionSpec
+
+```ts
+{ enter?, exit?, easing?: "smooth" | "snappy", delay?, durationInFrames?, distance? }
+```
+
+`delay` and `durationInFrames` are in frames; `distance` is px travel for `rise`.
+`easing` defaults to `smooth`. See the live `MotionReel` composition for each
+preset playing.

package/README.md

@@ -0,0 +1,109 @@
+# Cadence
+
+**A changelog video engine that refuses to fabricate your product.**
+
+Point it at a repo or a release and get an on-brand launch / changelog / announcement
+video — real code from your project, your colors, rendered locally. No invented APIs,
+no generic AI-video look, no hosted service. Free and open source.
+
+> **Ask your agent for a launch video.** With the skill installed, say *"make a
+> changelog video for this release"* — it reads your repo, writes the beats, and
+> renders an MP4.
+
+![changelog](docs/preview.png)
+![announcement](docs/preview-announcement.png)
+
+→ See the [gallery](docs/gallery.md) for the same engine across themes, formats, and arcs.
+
+## Install
+
+```bash
+npx skills add ryanwaits/cadence   # adds the skill to Claude Code / Cursor / Codex
+```
+
+Then just ask your agent. Or drive the CLI directly:
+
+```bash
+npx cadence create --release owner/name --install "npm i your-pkg"   # a repo → a video
+npx cadence create my.beats.json --format 9x16                       # a beats file → a video
+npx cadence themes                                                   # list built-in themes
+```
+
+A render runs entirely on your machine (or your own GitHub Actions) — free, no API key.
+
+## Why it doesn't look AI-generated
+
+Most AI video either fabricates a fake product or reaches for the same neon-on-black
+template. Cadence refuses both:
+
+- **Refuses to invent API.** The agent climbs an honesty ladder — types → examples →
+  README → install-only — and never shows a snippet it can't verify in your repo.
+- **Refuses a baked-in brand.** Colors and fonts come from *your* theme — derive one
+  from your URL (`cadence study --from-url`), a screenshot, or pick from 18 built-ins.
+- **Refuses generic backdrops.** The default is a procedural, theme-colored field of
+  soft gradient arcs (no asset, no key); an optional pack offers 19th-century landscape
+  paintings instead of stock gradients.
+- **Refuses freehand animation.** A controlled motion lexicon — ease-out only, no
+  bounce — so every video moves the same, considered way.
+
+The whole surface is small and countable: **7 enter + 4 exit transitions, 9 panel
+kinds, 3 formats, 18 themes — and one honesty rule: zero invented code.**
+
+## How it works
+
+A video is a list of **beats** — a small JSON file (`*.beats.json`). Each beat is a
+generic unit: an optional background + headline + optional code window + optional
+panel. The engine owns motion, fonts, layout, the typewriter, and code highlighting,
+so the same engine makes changelogs, feature drops, launch announcements, and
+milestones. The agent (via the skill) writes the beats; you tweak and render.
+
+Panels visualize what a change *produces* — pick by result:
+`feed · data-table · status · stat · proof · stream-resume · fork · upload-progress · diagram`.
+
+- **[docs/recipes.md](docs/recipes.md)** — worked examples (changelog, announcement, showcase, brand-from-URL, CI).
+- **[docs/gallery.md](docs/gallery.md)** — the same engine, visibly different videos.
+- **[WALKTHROUGH.md](WALKTHROUGH.md)** — architecture + how to adjust each part.
+- **[MOTION.md](MOTION.md)** — the motion lexicon + taxonomy.
+
+## CLI
+
+```
+cadence create <repo|beats.json>   build a video (repo flow, or a beats file)
+cadence study  --from-url <url>    a brand URL / color → a theme JSON
+cadence audit  <beats.json>        heuristic checks on a beats file (no auto-fix)
+cadence redesign <beats.json>      re-skin a beats file (new theme / background)
+cadence themes | templates         list built-ins
+cadence guide                      interactive walkthrough
+```
+
+Shared flags: `--format 16x9|1x1|9x16`, `--theme <name>`, `--theme-file <path>`,
+`--frame <n>` (still preview).
+
+## Ship on release (CI)
+
+The included GitHub Action renders a video on every release, free, on your own
+runner — no hosted service. See **[docs/github-action.md](docs/github-action.md)**.
+
+## Develop the engine
+
+```bash
+bun install
+bun run dev          # Remotion Studio
+bun run check        # tsc
+bun run check:motion # MOTION.md ↔ presets parity
+```
+
+Layout: `src/schema` (the beats contract), `src/components` (scene + panels),
+`src/motion` (the lexicon), `src/theme` (themes + derivation), `src/templates`
+(the no-LLM repo→beats path), `prompts/art` (the optional painterly pack).
+
+## Optional: painterly backgrounds
+
+The default backdrop is procedural and needs no key. For the optional
+"Hill Country Sublime" landscape pack (see **[ART-DIRECTION.md](ART-DIRECTION.md)**):
+
+```bash
+cadence art --landmark pennybacker --level heightened   # needs OPENAI_API_KEY
+```
+
+This is the only part of the toolchain that calls an external API.

package/bin/cli.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * npm bin launcher. node can't execute TypeScript directly, so this resolves
+ * the `tsx` runner (package-local `.bin`, then the hoisted top-level `.bin`
+ * when we're installed under `node_modules/<pkg>`, else PATH) and runs the
+ * TS CLI. Mirrors `scripts/_pkg.ts#binPath` — kept in JS so the bin needs no
+ * transpile step.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const tsx =
+  [join(root, "node_modules/.bin/tsx"), resolve(root, "../.bin/tsx")].find(existsSync) ?? "tsx";
+
+const res = spawnSync(tsx, [join(root, "scripts/cli.ts"), ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+process.exit(res.status ?? 0);

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@waits/cadence",
+  "version": "0.2.0",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "cadence": "bin/cli.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryanwaits/cadence.git"
+  },
+  "files": [
+    "bin",
+    "scripts",
+    "src",
+    "prompts/art",
+    "public/backgrounds/*.png",
+    "MOTION.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "cli": "tsx scripts/cli.ts",
+    "guide": "tsx scripts/guide.ts",
+    "dev": "remotion studio",
+    "render": "tsx scripts/render.ts",
+    "art": "tsx scripts/generate-art.ts",
+    "changes": "tsx scripts/changes.ts",
+    "create": "tsx scripts/make.ts",
+    "study": "tsx scripts/theme.ts",
+    "audit": "tsx scripts/audit.ts",
+    "redesign": "tsx scripts/redesign.ts",
+    "sync-skill": "tsx scripts/sync-skill.ts",
+    "still": "remotion still",
+    "check": "tsc --noEmit",
+    "check:motion": "tsx scripts/check-motion.ts",
+    "check:render": "tsx scripts/smoke.ts",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish"
+  },
+  "dependencies": {
+    "@remotion/cli": "4.0.471",
+    "@remotion/google-fonts": "4.0.471",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
+    "remotion": "4.0.471",
+    "shiki": "4.2.0",
+    "tsx": "4.22.4",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@changesets/changelog-git": "^0.2.1",
+    "@changesets/cli": "^2.31.0",
+    "@types/react": "19.2.16",
+    "typescript": "5.7.3"
+  }
+}

package/prompts/art/compose.ts

@@ -0,0 +1,18 @@
+import type { Format } from "../../src/schema/beats";
+import { COMPOSITION, NEGATIVES, STYLE } from "./style";
+import { LANDMARKS, type LandmarkKey } from "./landmarks";
+import { FANTASY, type FantasyLevel } from "./fantasy";
+
+/** Build the full image-gen prompt for a landmark × fantasy level × format. */
+export function composePrompt(landmark: LandmarkKey, level: FantasyLevel, format: Format): string {
+  return [
+    STYLE,
+    `Subject: ${LANDMARKS[landmark].subject}.`,
+    FANTASY[level],
+    COMPOSITION[format],
+    NEGATIVES,
+  ].join(" ");
+}
+
+export { LANDMARKS, FANTASY };
+export type { LandmarkKey, FantasyLevel };

package/prompts/art/fantasy.ts

@@ -0,0 +1,15 @@
+/**
+ * The fantasy dial. Grounded keeps it plausibly Texan; Heightened is the default
+ * launch register (recognizable but sublime); Mythic goes full Bierstadt fever-
+ * dream. Same landmark, escalating wilderness around it.
+ */
+export const FANTASY = {
+  grounded:
+    "Keep the landmark and Texas Hill Country terrain recognizable and naturalistic — only the light is idealized: a glowing, atmospheric golden hour.",
+  heightened:
+    "Heighten the drama: exaggerate the scale of the cliffs and sky, widen the river into a grand basin, add distant snow-dusted Southwest peaks and deeper atmospheric haze — recognizable but sublime.",
+  mythic:
+    "Full sublime fantasy: impossible towering mesas and spires, a vast alpine-scale lake, layered floating mist, cathedral shafts of light — a dreamlike, mythic grandeur while the landmark remains just identifiable.",
+} as const;
+
+export type FantasyLevel = keyof typeof FANTASY;

package/prompts/art/landmarks.ts

@@ -0,0 +1,49 @@
+/**
+ * Austin / Texas Hill Country / Southwest landmarks, each described as a subject
+ * clause to drop into the luminist style. The recognizable landmark grounds the
+ * fantasy; the `fantasy` dial then exaggerates the wilderness around it.
+ */
+export const LANDMARKS = {
+  pennybacker: {
+    name: "Pennybacker (360) Bridge",
+    subject:
+      "the graceful rust-red Pennybacker 360 steel arch bridge spanning a deep Hill Country river gorge, cedar-covered limestone cliffs rising on either side above a wide still river",
+  },
+  utTower: {
+    name: "UT Tower",
+    subject:
+      "a tall pale limestone bell tower in the manner of the University of Texas tower crowning a forested hill, glowing in golden light above a valley",
+  },
+  capitol: {
+    name: "Texas Capitol",
+    subject:
+      "a great domed sandstone capitol building in the manner of the Texas State Capitol, its pink-granite dome catching the light atop a broad rise of live oaks",
+  },
+  congress: {
+    name: "Congress Ave Bridge",
+    subject:
+      "a long low arched stone bridge over a wide calm urban lake at dusk in the manner of the Congress Avenue bridge, a faint cloud of bats rising in the distance",
+  },
+  mountBonnell: {
+    name: "Mount Bonnell",
+    subject:
+      "a high limestone overlook in the manner of Mount Bonnell above a winding emerald river far below, cedar and prickly-pear clinging to the rocky bluff",
+  },
+  enchantedRock: {
+    name: "Enchanted Rock",
+    subject:
+      "an enormous rounded pink-granite dome in the manner of Enchanted Rock swelling from the Hill Country scrub, monumental and weathered",
+  },
+  hamiltonPool: {
+    name: "Hamilton Pool",
+    subject:
+      "a collapsed-grotto jade-green grotto pool in the manner of Hamilton Pool, a thin waterfall spilling from a moss-hung limestone overhang into still water",
+  },
+  bartonSprings: {
+    name: "Barton Springs",
+    subject:
+      "a long spring-fed natural pool of clear turquoise water in the manner of Barton Springs, lined with bald cypress and pecan, fed by limestone springs",
+  },
+} as const;
+
+export type LandmarkKey = keyof typeof LANDMARKS;

package/prompts/art/style.ts

@@ -0,0 +1,20 @@
+/**
+ * The luminist DNA preamble — constant across every "Hill Country Sublime"
+ * painting. Encodes the Hudson River School lineage, the light, and the palette,
+ * reconciled with the Field Notebook brand so paper/ink/Signal-Blue UI reads
+ * cleanly on top. See ART-DIRECTION.md for the full rationale.
+ */
+export const STYLE = `A grand 19th-century Luminist landscape oil painting in the Hudson River School tradition of Albert Bierstadt, Thomas Moran, and Frederic Edwin Church. Soft painterly brushwork, deep atmospheric perspective, glowing diffuse light with a single cool source low in a clear sky, drifting haze and god-rays breaking through luminous towering clouds. Museum-quality, serene, monumental, contemplative. Palette of slate blue, steel and cerulean, cool limestone grey-white, sage and cedar green, pale periwinkle, and a luminous cobalt-to-cream sky echoing a signal blue (#2563eb) — cool, airy, and atmospheric, never garish.`;
+
+/** Composition guidance so the painting works as a backdrop for the UI layer. */
+export const COMPOSITION = {
+  "16x9":
+    "Compose for a wide 16:9 frame: keep the upper third a calm, uncluttered luminous sky and the lower third a still, mirror-like water plane — these are intentional areas of negative space for overlaid text and UI. The focal landform sits in the middle distance, slightly off-center.",
+  "1x1":
+    "Compose for a square 1:1 frame: generous calm sky filling the top half, a still water plane across the bottom, the focal landform centered in the middle distance. Leave the upper-center quiet for overlaid text.",
+  "9x16":
+    "Compose for a tall vertical 9:16 frame: a soaring luminous sky in the upper half, the focal landform in the middle band, and a still reflective water plane in the lower third. Keep the vertical center column calm for stacked UI overlays.",
+} as const;
+
+/** Always appended — keeps the frame clean for compositing. */
+export const NEGATIVES = "No text, no lettering, no watermark, no people in the foreground, no modern vehicles, no signage, no harsh saturated colors.";

package/scripts/_pkg.ts

@@ -0,0 +1,28 @@
+/**
+ * Path resolution that works both in-repo (dev) and from an installed npm
+ * package. The engine's own files (the Remotion entry, sibling scripts, dep
+ * bins) must resolve relative to *this package*, not the user's CWD — only
+ * user-supplied paths (a beats file, the `out/` dir) are CWD-relative.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Absolute path to the engine package root (one level above `scripts/`). */
+export const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+/** Absolute path to one of the engine's own files (e.g. `src/index.ts`). */
+export const pkgFile = (rel: string) => join(PKG_ROOT, rel);
+
+/**
+ * Resolve a dependency's CLI bin, robust to install layout: package-local
+ * `.bin` first (dev + nested installs), then the hoisted top-level `.bin`
+ * (our package living under `node_modules/<pkg>`), else assume it's on PATH.
+ */
+export function binPath(name: string): string {
+  const local = join(PKG_ROOT, "node_modules", ".bin", name);
+  if (existsSync(local)) return local;
+  const hoisted = resolve(PKG_ROOT, "..", ".bin", name);
+  if (existsSync(hoisted)) return hoisted;
+  return name;
+}

package/scripts/audit.ts

@@ -0,0 +1,69 @@
+/**
+ * `cadence audit <beats>` — static, heuristic checks on a beats file. Advisory
+ * only: ranked findings, no auto-fix (edit content by hand; use `redesign` to
+ * re-skin). Mirrors the authoring guidance in the cadence skill.
+ *
+ *   cadence audit src/content/streams-launch.beats.ts
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { changelogSchema } from "../src/schema/beats";
+
+const file = process.argv.slice(2).find((a) => !a.startsWith("-"));
+if (!file) {
+  console.error("usage: cadence audit <beats.ts|.json>");
+  process.exit(1);
+}
+
+const raw = file.endsWith(".json")
+  ? JSON.parse(readFileSync(resolve(file), "utf8"))
+  : (await import(pathToFileURL(resolve(file)).href)).default;
+const parsed = changelogSchema.parse(raw);
+const beats = parsed.beats;
+const FPS = 30;
+
+type Level = "error" | "warn" | "info";
+const findings: { level: Level; msg: string }[] = [];
+const add = (level: Level, msg: string) => findings.push({ level, msg });
+
+// 1. Beat count — skill guidance is to keep it tight (3-6).
+if (beats.length < 2) add("warn", `only ${beats.length} beat — most videos want 3-6`);
+if (beats.length > 7) add("warn", `${beats.length} beats — tighten toward 3-6; long videos lose attention`);
+
+// 2. Per-beat duration (≈2-10s at 30fps).
+beats.forEach((b, i) => {
+  const s = (b.durationInFrames / FPS).toFixed(1);
+  if (b.durationInFrames < 45) add("warn", `beat ${i + 1} "${b.headline}" is ${s}s — too short to read`);
+  else if (b.durationInFrames > 360) add("warn", `beat ${i + 1} "${b.headline}" is ${s}s — likely too long`);
+});
+
+// 3. Headline length — short + declarative.
+beats.forEach((b, i) => {
+  if (b.headline.length > 48)
+    add("warn", `beat ${i + 1} headline is ${b.headline.length} chars — shorten ("${b.headline.slice(0, 40)}…")`);
+});
+
+// 4. Motion monotony — every beat with an explicit enter uses the same one.
+const enters = beats.map((b) => b.headlineMotion?.enter).filter(Boolean);
+if (enters.length >= 3 && new Set(enters).size === 1)
+  add("info", `every headline uses the "${enters[0]}" enter — vary it for rhythm`);
+
+// 5. Install/CTA closer — heuristic: last beat centered with a bash command or a badge/caption.
+const last = beats[beats.length - 1];
+const isCloser = last.layout === "center" && (last.code?.lang === "bash" || !!last.badge || !!last.caption);
+if (!isCloser) add("info", "last beat doesn't look like an install/CTA closer (centered + install command)");
+
+// Report, ranked: error → warn → info. "Issues" = error+warn; info are notes.
+const order: Record<Level, number> = { error: 0, warn: 1, info: 2 };
+findings.sort((a, b) => order[a.level] - order[b.level]);
+const icon: Record<Level, string> = { error: "✗", warn: "▲", info: "·" };
+const issues = findings.filter((f) => f.level !== "info").length;
+
+if (issues === 0) {
+  const notes = findings.length ? ` (${findings.length} note${findings.length > 1 ? "s" : ""} below)` : "";
+  console.log(`✓ ${file}: no issues across ${beats.length} beats${notes}`);
+} else {
+  console.log(`${file}: ${issues} issue${issues > 1 ? "s" : ""} across ${beats.length} beats`);
+}
+for (const f of findings) console.log(`  ${icon[f.level]} ${f.msg}`);

package/scripts/changes.ts

@@ -0,0 +1,70 @@
+/**
+ * Read what changed in a repo → a normalized UpdateManifest (JSON on stdout).
+ * The deterministic "reads your repo" half of the pipeline; the brain/template
+ * turns the manifest into beats.
+ *
+ *   tsx scripts/changes.ts --release stx-labs/clarinet [--tag v3.18.0] [--install "brew install clarinet"]
+ *   tsx scripts/changes.ts --changelog ./CHANGELOG.md --product my-pkg --install "npm i my-pkg"
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { manifestFromChangelogText, manifestFromReleaseBody } from "../src/adapters";
+
+/** Warn (don't fail) if a sibling package.json version disagrees with the changelog's. */
+function warnIfStale(changelogPath: string, changelogVersion: string) {
+  if (!changelogVersion) return;
+  try {
+    const pkgPath = join(dirname(changelogPath), "package.json");
+    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+    const pkgVersion = String(pkg.version ?? "").replace(/^v/i, "").trim();
+    if (pkgVersion && pkgVersion !== changelogVersion) {
+      console.error(
+        `warning: ${pkgPath} is at ${pkgVersion} but the changelog's top entry is ${changelogVersion} — the changelog may be stale.`
+      );
+    }
+  } catch {
+    // no sibling package.json / unreadable — nothing to compare against
+  }
+}
+
+const args = process.argv.slice(2);
+const flag = (n: string) => {
+  const eq = args.find((a) => a.startsWith(`${n}=`));
+  if (eq) return eq.split("=")[1];
+  const i = args.indexOf(n);
+  return i >= 0 && !args[i + 1]?.startsWith("--") ? args[i + 1] : undefined;
+};
+
+const release = flag("--release"); // owner/name
+const changelog = flag("--changelog");
+const install = flag("--install");
+
+let manifest;
+if (release) {
+  const tag = flag("--tag");
+  const gh = ["release", "view", ...(tag ? [tag] : []), "--repo", release, "--json", "tagName,name,publishedAt,body"];
+  const res = spawnSync("gh", gh, { encoding: "utf8" });
+  if (res.status !== 0) {
+    console.error(`gh release view failed for ${release}:\n${res.stderr}`);
+    process.exit(1);
+  }
+  const r = JSON.parse(res.stdout);
+  manifest = manifestFromReleaseBody({
+    product: flag("--product") ?? basename(release),
+    version: r.tagName ?? r.name ?? "",
+    body: r.body ?? "",
+    date: r.publishedAt?.slice(0, 10),
+    install,
+    repoUrl: `https://github.com/${release}`,
+  });
+} else if (changelog) {
+  const text = readFileSync(changelog, "utf8");
+  manifest = manifestFromChangelogText(text, { product: flag("--product") ?? "package", install });
+  warnIfStale(changelog, manifest.version);
+} else {
+  console.error("usage: changes.ts --release <owner/name> [--tag vX] | --changelog <path> [--product X] [--install '...']");
+  process.exit(1);
+}
+
+console.log(JSON.stringify(manifest, null, 2));

package/scripts/check-motion.ts

@@ -0,0 +1,37 @@
+/**
+ * Parity guard: every preset in names.ts must be documented in MOTION.md, and
+ * every preset named in MOTION.md's Enter/Exit tables must exist in names.ts.
+ * Run: `bun run check:motion` (or `tsx scripts/check-motion.ts`).
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { ENTER_PRESETS, EXIT_PRESETS } from "../src/motion/names";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const doc = readFileSync(join(root, "MOTION.md"), "utf8");
+const all = [...ENTER_PRESETS, ...EXIT_PRESETS];
+const errors: string[] = [];
+
+// forward: each name appears as `name` in the doc
+for (const name of all) {
+  if (!doc.includes(`\`${name}\``)) errors.push(`MOTION.md is missing preset \`${name}\``);
+}
+
+// backward: first-column backticked names in the two preset tables exist in names.ts
+const tableNames = new Set<string>();
+for (const section of ["## Enter presets", "## Exit presets"]) {
+  const start = doc.indexOf(section);
+  if (start === -1) { errors.push(`MOTION.md missing section "${section}"`); continue; }
+  const body = doc.slice(start, doc.indexOf("\n## ", start + 1) === -1 ? undefined : doc.indexOf("\n## ", start + 1));
+  for (const m of body.matchAll(/^\|\s*`([a-z]+)`\s*\|/gm)) tableNames.add(m[1]);
+}
+for (const name of tableNames) {
+  if (!(all as string[]).includes(name)) errors.push(`MOTION.md documents unknown preset \`${name}\``);
+}
+
+if (errors.length) {
+  console.error("✗ motion parity failed:\n" + errors.map((e) => "  - " + e).join("\n"));
+  process.exit(1);
+}
+console.log(`✓ motion parity: ${all.length} presets documented (${tableNames.size} in tables)`);