tillerhand 3.53.0 → 3.54.0

package/.claude/commands/release.md

@@ -47,4 +47,6 @@ Source lists: `docs/operations/release-checklist.md`, `docs/architecture/stack.m
 1. Preview: `npx -y vercel@63.1.1 deploy` (version pinned; `docs/workflow/mcp-catalog.md`). Produce evidence on the preview URL: the main flow with Playwright CLI, `console` (no errors), desktop and mobile screenshots.
 2. Ask the user: "The preview is ready, promote it to prod?" If approved, `npx -y vercel@63.1.1 promote <preview-url>` or `deploy --prod` (the shield asks again). Rollback path: `vercel rollback`.
 
+**Launch clip (an offer, only when there are no ❌ items):** Ask the user with AskUserQuestion whether they want a 20-second launch clip of the release with the `motion-video` skill. Do nothing if they decline.
+
 Do not start a prod deploy without approval. Ask with **multi-select** which of the ❌ items to fix now. Update `docs/workflow/progress.md` and write the status block.

package/.claude/skills/motion-video/SKILL.md

@@ -1,16 +1,20 @@
 ---
 name: motion-video
-description: Produces the product's promo video (SaaS demo loop, landing page video, social media clip) with code. A single HTML file and renderAt(t), a real cursor, closed-form springs, a 120 BPM rhythm; frames are captured one by one with Playwright and converted to MP4 with ffmpeg. Use when a "promo video", "demo video", "product animation" or "landing page loop" is requested. Not for in-app animation (use ui-motion for that).
+description: Produces the product's promo video with code, in two modes. Demo loop: a landing page or SaaS demo with a real cursor, closed-form springs and a 120 BPM rhythm. Launch clip: a 20-second video of a finished project with generated music and share text. Frames are captured one by one with Playwright and converted to MP4 with ffmpeg. Use when a "promo video", "demo video", "launch video", "product animation" or "landing page loop" is requested. Not for in-app animation (use ui-motion for that).
 ---
 
 # Promo video (with code)
 
-> This skill is adapted from N01ennn's "UI motion design for Opus 5.5" prompt (October 2026).
+> This skill is adapted from N01ennn's "UI motion design for Opus 5.5" prompt (October 2026). The launch clip ideas are adapted from `latent-spaces/brag` (MIT).
 
 **Core problem:** Claude cannot watch its own frames while they move. So every frame is computed from time `t`; a real cursor drives the story; still frames are checked before you say the work is done.
 
 Ask decisions per `docs/workflow/decision-protocol.md`. Visual decisions (direction, frame choice) are asked with a preview.
 
+**Ask first which mode, demo loop or launch clip:**
+- **Demo loop:** a seamless loop of the product in use, for a landing page. Sections 1-6 below.
+- **Launch clip:** a 20-second video that tells a stranger what a finished project is, for sharing. The "Launch clip" section; it uses cuts.
+
 ## 0. Prerequisites
 
 Check them; if one is missing, give the user the install command (install happens with the user's approval):
@@ -31,12 +35,12 @@ Ask in one round (4 questions at most, with recommendations):
 
 1. **States:** 8-12 interface states of the product. Source: routes of the running app (recommended), screenshots or components. List what each state shows in one sentence and get it confirmed.
 2. **Color and typography:** Black, white and a single accent color (default: the main color in `DESIGN.md`), typefaces, logo (`public/brand/` or `assets/brand/`).
-3. **Sound:** A 120 BPM music track (the user provides it; the license is the user's responsibility), or just a click track (generated automatically), or silent.
+3. **Sound:** Generated music (see "Generated sound"), a 120 BPM track the user gives (the license is the user's responsibility), just a click track (generated automatically), or silent.
 4. **Format and closing:** 1440×1440 (default, social media and landing page) or 1920×1080; the one-line text shown on the last frame (run it through `humanizer:humanizer`).
 
 ## 2. Direction
 
-- **One continuous transformation (morph):** No cuts or fades between states. An element turns into an element of the next state.
+- **One continuous transformation (morph):** The demo loop has no cuts or fades between states. An element turns into an element of the next state.
 - **Real cursor:** The cursor triggers every change (hover, click, drag, typing). The cursor never leaves the frame.
 - **Camera:** In each state, it zooms in so that state fills the frame, then pulls back.
 - **Springs:** Use springs with mass and a very small overshoot.
@@ -89,8 +93,8 @@ With no audio, remove `-i track.wav` and `-shortest`. If a click track is needed
 
 - **Loop seam:** Last frame = first frame, cursor included.
 - **Blur:** No `will-change` on scaling elements; it blurs text. After every zoom, check the text at 1x.
-- **Determinism:** Calling `seek(7.25)` twice must give a pixel-for-pixel identical result. Compare the screenshot buffers.
-- **Fonts:** Load fonts from a local file and wait for `document.fonts.ready` before rendering starts.
+- **Determinism:** Calling `seek(7.25)`, seeking elsewhere, then `seek(7.25)` again must give a pixel-for-pixel identical result. Compare the screenshot buffers. A leftover `transform` on a settled element is a common cause of a difference: set it to `none`.
+- **Fonts:** Load fonts from a local file and wait for `document.fonts.ready` before rendering starts. If the project loads them from a CDN, ask before downloading a local copy.
 
 ## 6. Start order
 
@@ -99,3 +103,46 @@ With no audio, remove `-i track.wav` and `-shortest`. If a click track is needed
 3. Show the frames under `.previews/NN-motion/` and ask for approval with AskUserQuestion: Start / Change this. **Do not do a full render until the user says "Start".**
 4. Render, run the determinism and loop seam tests, and show screenshots of 3 frames of the video.
 5. Write the decisions to `docs/decisions/log.md`. Write the video's path and how to reproduce it to `marketing/motion/<ad>/README.md`.
+
+## Launch clip
+
+About 20 seconds (15-25). After one viewing, a stranger knows what the project does, who it is for and how to get it. Scenes may use cuts. A plain crossfade between two busy layouts looks muddy, so take the old content out first, then bring the new content in.
+
+**1. Read the project first.** Do not ask for a list of states. Read the main page, the styles (exact colors and fonts), the README, the routes and the key components, and find the real flow: entry, key action, result.
+
+Do not read `.env` files, keys, credentials, build output or lock files.
+
+**2. Ask** the tone (playful, polished, deadpan or the user's own), the format and the sound. Formats: landscape 1920×1080, vertical 1080×1920, square 1080×1080. If the user points at one feature or version, it becomes the focus.
+
+**3. Plan** as hook (2-3 s), reveal (2-4 s), 2-3 highlights, punchline (2-4 s). Show the plan as a table with durations and every cut on a beat, and keep it in `beats.json`: the sound reads the same file. Then:
+
+- **Reuse the real interface:** render the project's own components, styles, fonts and images instead of redrawing them. Prefer the working app over a page that describes it.
+- **Nothing invented:** no made-up claims, numbers or testimonials. Small sample text inside a screen is fine (a file name, a toast).
+- **Readable:** text the viewer must read stays settled on screen for about 0.3 seconds per word.
+- **Specific:** use the project's own words. If a line could describe any product, rewrite it.
+- **The first 2 seconds decide:** plan the hook first.
+
+**4. Keep private data out.** The video and the share text are public. Secrets, tokens, internal URLs, real customer names, email addresses and other personal data never reach them. If such data shows on a real screen, replace it with made-up sample values before capture. Ask before showing something public but personal, such as a user name in a repository URL.
+
+**5. Build and check** with the same files as the demo loop: `index.html` with `renderAt(t)` and `seek(t)`, `render.mjs`, and the determinism and font checks of §5. The cursor, the one-action-per-beat rule and the Remotion question are for the demo loop only.
+
+Blending sub-frames with `fps` smears a cut into a grey frame. Capture each frame's sub-frames inside that frame, at `(n + (j + 0.5) / 4) / fps` for `j` from 0 to 3, then keep every fourth blended frame. At 30 fps:
+
+```bash
+ffmpeg -y -framerate 120 -i frames/%06d.png -i track.wav \
+  -vf "tmix=frames=4,select='eq(mod(n,4),3)',setpts=N/(30*TB)" -r 30 -shortest \
+  -c:v libx264 -crf 14 -pix_fmt yuv420p out/clip.mp4
+```
+
+Before the full render, look at stills from every scene, from mid-transition and from the frames on both sides of a cut, and fix overflow, collisions and low contrast. Show them under `.previews/NN-motion/` and ask with AskUserQuestion: Start / Change this. Do not do a full render until the user approves the stills.
+
+**6. Deliver** to `marketing/motion/<name>/out/`: the video, a poster frame and `share-copy.txt` (1-3 sentences ready to post, run through `humanizer:humanizer`). The poster is the strongest settled frame. It replaces frame 0 only, so the thumbnail shows it and the hook still starts at once. Write the decisions and how to reproduce the video as in §6.
+
+## Generated sound
+
+No music or audio file ships with the kit. The model writes the sound itself with tools on the machine, for example a short Node script that writes a WAV file, or ffmpeg's `aevalsrc`:
+
+- **One beat grid:** drums, bass, melody and effects play on the same grid as the video, counted from the first frame.
+- **Effects under the music:** sound effects share the music's key and sit softly under it. Repeated small sounds stay in the background.
+- **No clipping:** overlapping hits add up, so pass the mix through a soft limiter (`tanh`), keep peaks near -1 dB and check with ffmpeg's `volumedetect` filter. Write 44.1 kHz stereo.
+- Listening is the user's job: you cannot hear it. Say so when you show the result, and offer another try.

package/README.md

@@ -6,7 +6,7 @@
 </p>
 
 <p align="center">
-  <a href="kit/CHANGELOG.md"><img alt="Version" src="https://img.shields.io/badge/version-3.53.0-2a78d6?style=flat-square"></a>
+  <a href="kit/CHANGELOG.md"><img alt="Version" src="https://img.shields.io/badge/version-3.54.0-2a78d6?style=flat-square"></a>
   <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-2a78d6?style=flat-square"></a>
   <img alt="Claude Code" src="https://img.shields.io/badge/Claude%20Code-ready-d97757?style=flat-square">
   <img alt="Also Codex and Antigravity" src="https://img.shields.io/badge/also-Codex%20%C2%B7%20Antigravity-5b6577?style=flat-square">

package/README.tr.md

@@ -6,7 +6,7 @@
 </p>
 
 <p align="center">
-  <a href="kit/CHANGELOG.md"><img alt="Sürüm" src="https://img.shields.io/badge/s%C3%BCr%C3%BCm-3.53.0-2a78d6?style=flat-square"></a>
+  <a href="kit/CHANGELOG.md"><img alt="Sürüm" src="https://img.shields.io/badge/s%C3%BCr%C3%BCm-3.54.0-2a78d6?style=flat-square"></a>
   <a href="LICENSE"><img alt="Lisans: MIT" src="https://img.shields.io/badge/lisans-MIT-2a78d6?style=flat-square"></a>
   <img alt="Claude Code" src="https://img.shields.io/badge/Claude%20Code-haz%C4%B1r-d97757?style=flat-square">
   <img alt="Codex ve Antigravity" src="https://img.shields.io/badge/ayr%C4%B1ca-Codex%20%C2%B7%20Antigravity-5b6577?style=flat-square">

package/docs/workflow/skills.md

@@ -35,7 +35,7 @@
 | `document-to-markdown` | A PDF or Office file: convert with MarkItDown first, read only the part you need |
 | `logo-design` | Logo, icon, favicon, brand pack (SVG, needs no API) |
 | `ui-motion` | In-app animation and transitions |
-| `motion-video` | Promo video, landing page loop (renderAt(t) + Playwright + ffmpeg) |
+| `motion-video` | Promo video: landing page demo loop, or a 20-second launch clip of a finished project with generated music (renderAt(t) + Playwright + ffmpeg) |
 
 ## Tools (MCP)
 

package/kit/CHANGELOG.md

@@ -3,6 +3,14 @@
 The kit version is in `kit/VERSION`. To update a project, run `/kit-update` in it.
 Items with an "Adapt by hand" note concern files owned by the project; the update does not touch them.
 
+## [3.54.0] - 2026-11-01
+
+### Added
+- **`motion-video` makes a launch clip.** The skill now asks which video you want: the demo loop as before, or a 20-second clip of a finished project. The clip reads the project, reuses its real interface, generates its own music and delivers a poster and share text. Private data is kept out. `/release` offers a clip when nothing blocks the release. Ideas adapted from `latent-spaces/brag` (MIT).
+
+### Fixed
+- The determinism check now seeks away and back, which catches differences a repeated call misses.
+
 ## [3.53.0] - 2026-11-01
 
 ### Added

package/kit/VERSION

@@ -1 +1 @@
-3.53.0
+3.54.0

package/kit/guide.html

@@ -361,7 +361,7 @@ footer .container { display: flex; flex-wrap: wrap; gap: 16px; justify-content:
 <section class="hero">
   <div class="container">
     <div>
-      <span class="pill"><b>v3.53.0</b> Starter kit for Claude Code · MIT</span>
+      <span class="pill"><b>v3.54.0</b> Starter kit for Claude Code · MIT</span>
       <h1>The AI builds.<br><em>You steer.</em></h1>
       <p class="sub">TillerHand takes a product from idea to production and maintenance with Claude Code. At every important decision the AI gives you the options, its recommendation and the cost of each option. An expert board reviews the work, and guardrails stop mistakes before they happen.</p>
       <div class="setup">
@@ -1094,7 +1094,7 @@ Pending decision: email service</pre>
     <article class="tile"><h3>QA and preview in the browser</h3><p class="stack">/qa · preview.mjs · Playwright CLI</p><ul><li>Interface criteria run as tests in a real browser</li><li>The report is written from the test result, a card on the dashboard</li><li>On an interface task /build takes desktop and mobile screenshots</li></ul></article>
     <article class="tile"><h3>Spec and drift check</h3><p class="stack">docs/product/specs/ · gate.mjs</p><ul><li>Current, expected and must-not-change behavior</li><li>The tests of the "must not change" lines are checked at the gate</li><li>/plan-task for work of 3+ files, /fix-bug writes it for every bug</li></ul></article>
     <article class="tile"><h3>Logo</h3><p class="stack">logo-design · SVG</p><ul><li>Brand questions, 4-6 concepts with a visual preview</li><li>Readable at 16 px, a one-color version, a dark background</li><li>Favicon, app icons, PNG sizes</li></ul></article>
-    <article class="tile"><h3>Promo video</h3><p class="stack">motion-video · renderAt(t) · Playwright · ffmpeg</p><ul><li>One continuous conversion, a real cursor, 120 BPM</li><li>Closed-form springs (verified with a test)</li><li>A beat map and 4 frames approved first, then MP4</li></ul></article>
+    <article class="tile"><h3>Promo video</h3><p class="stack">motion-video · renderAt(t) · Playwright · ffmpeg</p><ul><li>One continuous conversion, a real cursor, 120 BPM</li><li>Closed-form springs (verified with a test)</li><li>A beat map and 4 frames approved first, then MP4</li><li>Or a 20-second launch clip with generated music and share text</li></ul></article>
     <article class="tile"><h3>Interface motion and 3D</h3><p class="stack">ui-motion · Motion · Reanimated · GSAP · three.js</p><ul><li>Duration tokens, springs, transform/opacity only</li><li>The reduced-motion preference is mandatory</li><li>3D: lazy loading, a static fallback, mobile GPU</li></ul></article>
     <article class="tile"><h3>Review and discovery</h3><p class="stack">rea · Understand-Anything · awesome-design-md</p><ul><li>How a competitor's feature works: only in software you are authorized to examine, with approval first</li><li>A code map for people: suggested by /adopt, /handoff, /release first</li></ul></article>
     <article class="tile"><h3>Security</h3><p class="stack">security-guidance · claude-security · Trail of Bits</p><ul><li>While writing: a risky-pattern warning</li><li>At the commit: a review by a separate model</li><li>/findings-security: a multi-agent, verified scan</li></ul></article>
@@ -1255,7 +1255,7 @@ Pending decision: email service</pre>
 <footer>
   <div class="container">
     <a class="brand" href="#top" style="font-size:16px"><svg class="mark" style="width:22px;height:22px"><use href="#mark"/></svg>TillerHand</a>
-    <span>Version 3.53.0 · <a href="https://github.com/burakdogrul/TillerHand">GitHub</a> · <a href="https://github.com/burakdogrul/TillerHand/blob/main/LICENSE">MIT license</a> · The KVKK section is a checklist, not legal advice.</span>
+    <span>Version 3.54.0 · <a href="https://github.com/burakdogrul/TillerHand">GitHub</a> · <a href="https://github.com/burakdogrul/TillerHand/blob/main/LICENSE">MIT license</a> · The KVKK section is a checklist, not legal advice.</span>
   </div>
 </footer>
 

package/kit/guide.tr.html

@@ -361,7 +361,7 @@ footer .container { display: flex; flex-wrap: wrap; gap: 16px; justify-content:
 <section class="hero">
   <div class="container">
     <div>
-      <span class="pill"><b>v3.53.0</b> Claude Code için başlangıç kiti · MIT</span>
+      <span class="pill"><b>v3.54.0</b> Claude Code için başlangıç kiti · MIT</span>
       <h1>Kodu AI yazar.<br><em>Dümen sende.</em></h1>
       <p class="sub">TillerHand, Claude Code ile bir ürünü fikirden canlıya ve bakıma kadar götürür. Her önemli kararda AI sana seçenekleri, önerisini ve her seçeneğin bedelini sunar. Bir uzman kurulu işi denetler, korumalar hatayı daha olmadan durdurur.</p>
       <div class="setup">
@@ -1094,7 +1094,7 @@ Bekleyen karar: e-posta servisi</pre>
     <article class="tile"><h3>Tarayıcıda QA ve önizleme</h3><p class="stack">/qa · preview.mjs · Playwright CLI</p><ul><li>Arayüz kriterleri gerçek tarayıcıda test olarak koşar</li><li>Rapor test sonucundan yazılır, panoda kart</li><li>/build arayüz görevinde masaüstü ve mobil ekran görüntüsü</li></ul></article>
     <article class="tile"><h3>Spec ve sapma kontrolü</h3><p class="stack">docs/product/specs/ · gate.mjs</p><ul><li>Mevcut, beklenen ve değişmemesi gereken davranış</li><li>"Değişmemesi gereken" satırların testi kapıda denetlenir</li><li>3+ dosyalık işte /plan-task, her hatada /fix-bug yazar</li></ul></article>
     <article class="tile"><h3>Logo</h3><p class="stack">logo-design · SVG</p><ul><li>Marka soruları, 4-6 konsept görsel önizlemeyle</li><li>16 px okunurluk, tek renk hal, koyu zemin</li><li>Favicon, uygulama ikonları, PNG boyutları</li></ul></article>
-    <article class="tile"><h3>Tanıtım videosu</h3><p class="stack">motion-video · renderAt(t) · Playwright · ffmpeg</p><ul><li>Tek kesintisiz dönüşüm, gerçek imleç, 120 BPM</li><li>Kapalı formlu yaylar (testle doğrulandı)</li><li>Önce vuruş haritası ve 4 kare onayı, sonra MP4</li></ul></article>
+    <article class="tile"><h3>Tanıtım videosu</h3><p class="stack">motion-video · renderAt(t) · Playwright · ffmpeg</p><ul><li>Tek kesintisiz dönüşüm, gerçek imleç, 120 BPM</li><li>Kapalı formlu yaylar (testle doğrulandı)</li><li>Önce vuruş haritası ve 4 kare onayı, sonra MP4</li><li>Ya da üretilmiş müzik ve paylaşım metniyle 20 saniyelik tanıtım klibi</li></ul></article>
     <article class="tile"><h3>Arayüz hareketi ve 3D</h3><p class="stack">ui-motion · Motion · Reanimated · GSAP · three.js</p><ul><li>Süre belirteçleri, yaylar, sadece transform/opacity</li><li>Hareket azaltma tercihi zorunlu</li><li>3D: tembel yükleme, statik yedek, mobil GPU</li></ul></article>
     <article class="tile"><h3>İnceleme ve keşif</h3><p class="stack">rea · Understand-Anything · awesome-design-md</p><ul><li>Rakip özelliği nasıl çalışıyor: sadece yetkili olduğun yazılımda, önce onay</li><li>İnsan için kod haritası: /adopt, /handoff, /release first önerir</li></ul></article>
     <article class="tile"><h3>Güvenlik</h3><p class="stack">security-guidance · claude-security · Trail of Bits</p><ul><li>Yazarken: riskli kalıp uyarısı</li><li>Commit'te: ayrı modelle inceleme</li><li>/findings-security: çok ajanlı, doğrulanmış tarama</li></ul></article>
@@ -1255,7 +1255,7 @@ Bekleyen karar: e-posta servisi</pre>
 <footer>
   <div class="container">
     <a class="brand" href="#top" style="font-size:16px"><svg class="mark" style="width:22px;height:22px"><use href="#mark"/></svg>TillerHand</a>
-    <span>Sürüm 3.53.0 · <a href="https://github.com/burakdogrul/TillerHand">GitHub</a> · <a href="https://github.com/burakdogrul/TillerHand/blob/main/LICENSE">MIT lisansı</a> · KVKK bölümü kontrol listesidir, hukuki görüş değildir.</span>
+    <span>Sürüm 3.54.0 · <a href="https://github.com/burakdogrul/TillerHand">GitHub</a> · <a href="https://github.com/burakdogrul/TillerHand/blob/main/LICENSE">MIT lisansı</a> · KVKK bölümü kontrol listesidir, hukuki görüş değildir.</span>
   </div>
 </footer>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tillerhand",
-  "version": "3.53.0",
+  "version": "3.54.0",
   "description": "Vibe coding kit for Claude Code, Codex and Antigravity: rules, commands, guards and project templates.",
   "license": "MIT",
   "type": "module",