flomotion 0.2.0 → 0.4.0

package/docs/gate2-manual-checklist.md

@@ -1,6 +1,6 @@
 # Gate 2: manual checklist (a real Claude Code session)
 
-**Status: unverified.** Nothing in this repository has been run in a real Claude Code session with the `motion-studio` skill. The automated flow test (`tests/e2e/gate2-flow.test.ts`) plays the skill's steps through the MCP SDK client against test doubles. It proves the tools compose in the skill's order and enforce its gates. It does not prove that Claude follows the skill, writes good scenes, or that the live services behave like the doubles. Run this checklist to find out, and tell me what breaks.
+**Status: unverified.** Nothing in this repository has been run in a real Claude Code session with the `flomotion-studio` skill. The automated flow test (`tests/e2e/gate2-flow.test.ts`) plays the skill's steps through the MCP SDK client against test doubles. It proves the tools compose in the skill's order and enforce its gates. It does not prove that Claude follows the skill, writes good scenes, or that the live services behave like the doubles. Run this checklist to find out, and tell me what breaks.
 
 Allow about an hour and a cheap amount of money: the only paid step is the optional ElevenLabs voice.
 
@@ -20,7 +20,7 @@ Without a Freesound key the server falls back to `sounds/catalog.json` (your own
 
 Optional environment for ElevenLabs quotes: `ELEVENLABS_USD_PER_1K_CREDITS` (your plan's price per 1000 credits, so the quote can show money), `ELEVENLABS_CREDITS_PER_CHAR` (default 1; about 0.5 for flash models), `ELEVENLABS_COMMERCIAL_OK=1` (only if your plan allows commercial use, so the ledger records the voice as cleared).
 
-## 1. Install CodeCut and the skill
+## 1. Install flomotion and the skill
 
 From a checkout of this repo:
 
@@ -28,22 +28,22 @@ From a checkout of this repo:
 pnpm i && pnpm build
 ```
 
-After it is published to npm you can use `npx -y flomotion …` (the npm package is `flomotion`; the command is `codecut`) instead of the path below.
+After it is published to npm you can use `npx -y flomotion …` instead of the path below.
 
 Make an empty folder for the video and register the server **in that folder's scope**:
 
 ```bash
 mkdir ~/videos/pulse && cd ~/videos/pulse
-claude mcp add codecut \
+claude mcp add flomotion \
   -e FREESOUND_API_KEY=$FREESOUND_API_KEY \
   -e ELEVENLABS_API_KEY=$ELEVENLABS_API_KEY \
-  -- node /ABSOLUTE/PATH/TO/codeCut/packages/cli/dist/bin.mjs mcp --dir .
-node /ABSOLUTE/PATH/TO/codeCut/packages/cli/dist/bin.mjs skill install      # copies the skill to ./.claude/skills/motion-studio
+  -- node /ABSOLUTE/PATH/TO/flomotion/packages/cli/dist/bin.mjs mcp --dir . --ui
+node /ABSOLUTE/PATH/TO/flomotion/packages/cli/dist/bin.mjs install skill      # copies the skill to ~/.claude/skills/flomotion-studio (add --project for ./.claude/skills)
 ```
 
-Leave out the `-e` lines for keys you do not have. Then start `claude` in that folder and run `/mcp`: the `codecut` server must be connected and list 30 tools. Run `/skills` (or ask "what skills do you have?"): `motion-studio` must be there.
+Leave out the `-e` lines for keys you do not have. Then start `claude` in that folder and run `/mcp`: the `flomotion` server must be connected and list 39 tools. Run `/skills` (or ask "what skills do you have?"): `flomotion-studio` must be there. The server was started with `--ui`: its stderr line `live view: http://127.0.0.1:4317` (also in the `ui` field of `project_read`) is the live view address; open it before you start and keep it beside the terminal.
 
-Pass: server connected, 30 tools, skill listed. If the server is not connected, run the command after `mcp` by hand in a terminal and read its stderr.
+Pass: server connected, 39 tools, skill listed. If the server is not connected, run the command after `mcp` by hand in a terminal and read its stderr.
 
 ## 2. The session
 
@@ -73,6 +73,7 @@ Watch for each item. Write "pass", "fail" or "n/a" and a note.
 4. **Check `renders/<id>-final.licenses.json`** for `problems`. A generated ElevenLabs voice shows "not cleared for commercial use" unless you set `ELEVENLABS_COMMERCIAL_OK=1`; confirm your plan before publishing.
 5. **Open `project.tsx`.** Is it readable? Would it diff cleanly in git? Run `git init && git add . && git commit` and make a one-line change by hand; render again.
 6. **Undo works:** ask Claude to undo its last change (it uses `history_restore`), check the file went back.
+7. **The live view tells the truth.** While Claude works, the activity list should show each tool call within about a second, with the same description Claude reports; the progress list should follow the gate files Claude writes (`brief.md`, `script.md`, `storyboard.md`); the preview scrubber should render the current file; the Restore button on the History tab should put an earlier version back. Note anything that lags, shows stale data, or disagrees with what Claude says it did.
 
 ## 4. Live services: what each test double hides
 
@@ -86,4 +87,4 @@ Watch for each item. Write "pass", "fail" or "n/a" and a note.
 
 ## 5. Report back
 
-Send me: which table rows failed and the tool error text (every error has a `code` and a `fix`), the `.codecut/history/index.json`, and the final MP4's duration. I will fix what broke and re-run the gate.
+Send me: which table rows failed and the tool error text (every error has a `code` and a `fix`), the `.flomotion/history/index.json`, and the final MP4's duration. I will fix what broke and re-run the gate.

package/docs/hyperframes-notes.md

@@ -5,7 +5,7 @@ FFmpeg 7.1.1). Sources: `npx hyperframes --help`, `docs <topic>`, scaffold from
 skills in `node_modules/hyperframes/dist/skills/` (`hyperframes`, `hyperframes-cli`, `media-use`),
 and real test renders. **Installed version wins over the prompt.** Differences are listed at the end.
 
-## CLI used by CodeCut
+## CLI used by flomotion
 
 | Need                     | Command                                                                                  |
 | ------------------------ | ---------------------------------------------------------------------------------------- |
@@ -17,7 +17,7 @@ and real test renders. **Installed version wins over the prompt.** Differences a
 | Env health               | `hyperframes doctor` (reports FFmpeg, Chrome, whisper-cpp, memory)                       |
 
 Render writes `renders/<name>.mp4` by default; `-o` overrides. Telemetry: set
-`HYPERFRAMES_NO_TELEMETRY=1` and `DO_NOT_TRACK=1` for child processes (CodeCut does).
+`HYPERFRAMES_NO_TELEMETRY=1` and `DO_NOT_TRACK=1` for child processes (flomotion does).
 
 ## Project / composition contract
 
@@ -38,7 +38,7 @@ Render writes `renders/<name>.mp4` by default; `-o` overrides. Telemetry: set
   element (`gsap_css_transform_conflict`), tween of the `.clip` element itself
   (`gsap_animates_clip_element`: animate a child or its `opacity`).
 - Nested timed clips: a clip inside another timed element takes `data-start` from the
-  _composition_, not the parent, and shows only while the parent shows. CodeCut avoids this:
+  _composition_, not the parent, and shows only while the parent shows. flomotion avoids this:
   timed wrappers (scenes) have _untimed_ children, or all layers are flat siblings.
 - Seek protocol for non-GSAP drawing: `window.addEventListener("hf-seek", e => draw(e.detail.time))`
   (`e.detail.waitUntil(promise)` for async). No rAF clock. Heavy setup:
@@ -48,17 +48,17 @@ Render writes `renders/<name>.mp4` by default; `-o` overrides. Telemetry: set
   `data-volume` 1 = 0 dB, up to 3.98. Edge fades `data-fade-in/out`.
 - Asset paths root-relative (`assets/...`). Images without `data-duration` last 3 s.
 - Variables: `data-composition-variables` on `<html>`, `--variables '{}'` on render.
-  (CodeCut does not use these in phase 1/2.)
+  (flomotion does not use these in phase 1/2.)
 - Sub-compositions: files in `compositions/` wrapped in `<template>`, mounted with
   `data-composition-src`. Host id == scene root id == timeline key, else 45 s wait per scene.
-  CodeCut phase 1 emits one flat `index.html` and does not use sub-compositions.
+  flomotion phase 1 emits one flat `index.html` and does not use sub-compositions.
 
 ## GSAP loading
 
-The scaffold loads GSAP from jsDelivr CDN. **CodeCut instead vendors the file**:
+The scaffold loads GSAP from jsDelivr CDN. **flomotion instead vendors the file**:
 `<script src="vendor/gsap.min.js">` with a copy of `gsap@3.14.2/dist/gsap.min.js` written into the
 project at compile time (render verified with a local script, no CDN). The `gsap` npm package is
-a `@codecut/render` dependency.
+a `@flomotion/render` dependency.
 
 ## Fonts (important for determinism)
 
@@ -67,17 +67,17 @@ a `@codecut/render` dependency.
   Source Code Pro, Noto Sans JP, Roboto, Open Sans, Lato, Poppins.
 - **For bundled names HyperFrames fetches from Google Fonts at render and caches in
   `~/.cache/hyperframes/fonts/<family>/`** (observed log: `Fetched 11 font face(s) for "Inter"
-from Google Fonts`). This is network use at render, so CodeCut always emits its own
+from Google Fonts`). This is network use at render, so flomotion always emits its own
   `@font-face` for every used family and refuses bare-name use of bundled families.
 - A local `@font-face` with `src:url('assets/fonts/x.woff2')` is embedded as a data URI
   (`Embedded local font file ... → data URI`) and makes no network request. Verified.
 - **A missing font file does NOT fail HyperFrames**: the render succeeds (exit 0) with a
   fallback face and only logs `[FileServer] 404 Not Found: /assets/fonts/x.woff2`. Therefore
-  CodeCut must do its own pre-render font gate (file exists, hash matches lock, `document.fonts.load`
-  succeeds in headless Chrome). Implemented in `@codecut/render` (`fontGate`).
+  flomotion must do its own pre-render font gate (file exists, hash matches lock, `document.fonts.load`
+  succeeds in headless Chrome). Implemented in `@flomotion/render` (`fontGate`).
 - `hyperframes lint` rule `font_family_without_font_face` fires for unbundled families without
   `@font-face`.
-- `window.__hyperframes.fitTextFontSize(...)` and `.pretext` exist; CodeCut uses its own
+- `window.__hyperframes.fitTextFontSize(...)` and `.pretext` exist; flomotion uses its own
   Chrome measurement instead so results are cached/hashed.
 
 ## Rendering behaviours observed
@@ -90,20 +90,20 @@ from Google Fonts`). This is network use at render, so CodeCut always emits its
   First render downloads/caches fonts and takes ~1.5 min; warm render of 2 s took ~5 s.
 - Static-frame dedup reuses identical frames (speeds up holds).
 - `check` runs lint + runtime + layout + contrast; warns `first_frame_empty`, `line_unread`,
-  `sweep_static` etc. (useful input for CodeCut `review`.)
+  `sweep_static` etc. (useful input for flomotion `review`.)
 - Chrome: uses system Chrome if found, GPU probe `hardware` (Metal) on this machine.
   `--no-browser-gpu` forces SwiftShader (more deterministic across machines).
 
 ## Differences from the prompt
 
-| Prompt                                     | Installed reality                              | CodeCut decision                                                               |
+| Prompt                                     | Installed reality                              | flomotion decision                                                             |
 | ------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------ |
 | `data-track-index` positions layers        | Studio lane only; z-index paints               | Compiler emits both; z-index from track order                                  |
 | Fonts from `document.fonts.load` fail-hard | HF itself silently falls back                  | Own `fontGate` pre-render step                                                 |
 | GSAP "loaded the way HF expects" (CDN)     | CDN in scaffold; local script works            | Vendor GSAP locally                                                            |
 | No network at render                       | HF auto-fetches Google fonts for bundled names | Always emit own `@font-face`, lint bare bundled names                          |
 | Byte-identical double render               | True on same machine (no timestamps)           | Compare bytes; fall back to frame hashes if a future version embeds timestamps |
-| Audio mix by HF                            | HF mixes `<audio>` tags itself                 | CodeCut mixes offline with FFmpeg and emits one `<audio id="mix">`             |
+| Audio mix by HF                            | HF mixes `<audio>` tags itself                 | flomotion mixes offline with FFmpeg and emits one `<audio id="mix">`           |
 | Transcribe                                 | `hyperframes transcribe` (whisper-cpp) exists  | Prefer `whisper-cpp` via HF; error if missing                                  |
 
 ## Verified later while building
@@ -113,7 +113,7 @@ from Google Fonts`). This is network use at render, so CodeCut always emits its
   tuples sorted numerically, ranges `300..700`. A modern Chrome User-Agent returns woff2 split into `/* subset */`
   `@font-face` blocks with `unicode-range`. Developer API: `https://www.googleapis.com/webfonts/v1/webfonts?key=…`
   (`capability=VF` adds `axes`). No quotas are documented.
-- Google serves woff2 with the licence text **stripped** (only a copyright string remains), so CodeCut reads the
+- Google serves woff2 with the licence text **stripped** (only a copyright string remains), so flomotion reads the
   family's real licence from `github.com/google/fonts/<ofl|apache|ufl>/<family>/METADATA.pb`.
 - **CSS `mask: url(#svgMask)` is not applied to HTML elements in headless Chrome 152** (the golden frames showed no
   masking). Masks are implemented as a data-URI SVG `mask-image` instead.
@@ -127,10 +127,10 @@ from Google Fonts`). This is network use at render, so CodeCut always emits its
 - `hyperframes check <dir> --json` prints a banner line, then one JSON object with `lint`, `runtime`, `layout`,
   `motion` and `contrast`, each `{ ok, errorCount, warningCount, findings[] }`. `layout.samples` lists the times
   it measured (about nine for 30 s); contrast findings carry `text`, `fg`, `bg`, `ratio`, `time`. A 30 s check takes
-  about a minute on this machine. The `lint` block warns `nested_structure_needs_subcomposition` for CodeCut's
-  track wrappers; CodeCut ignores it (renders are correct).
+  about a minute on this machine. The `lint` block warns `nested_structure_needs_subcomposition` for flomotion's
+  track wrappers; flomotion ignores it (renders are correct).
 - `hyperframes transcribe <audio|transcript> -d <dir> --json [--no-runtime-install] [-l lang] [-m model]` writes
-  `transcript.json` in `<dir>`; with `--json` it prints `{ ok, engine, wordCount, transcriptPath, … }` or
+  `transcript.md` in `<dir>`; with `--json` it prints `{ ok, engine, wordCount, transcriptPath, … }` or
   `{ ok:false, error }` (`--optional` returns `{ skipped, reason:"whisper_unavailable", install }`). Engines: Parakeet
   if installed, else whisper.cpp. Not run here (no whisper-cpp installed); the word shape is read tolerantly
   (`text|word|w`, `start`, `end`).
@@ -145,5 +145,5 @@ from Google Fonts`). This is network use at render, so CodeCut always emits its
 character_end_times_seconds } }`. The docs fetched did not state the auth header or per-character credit cost:
   `xi-api-key` is used and the credit estimate is an assumption. **No live call has been made.**
 - `tsx` applies a tsconfig only to files under the tsconfig's directory and reads it at registration, so a
-  published CodeCut cannot rely on it. The bundled CLI compiles project TSX itself (esbuild, automatic JSX runtime
-  from `@codecut/core`) and maps `@codecut/*` imports with a Node resolve hook.
+  published flomotion cannot rely on it. The bundled CLI compiles project TSX itself (esbuild, automatic JSX runtime
+  from `@flomotion/core`) and maps `@flomotion/*` imports with a Node resolve hook.

package/docs/later.md

@@ -2,19 +2,26 @@
 
 Nothing here is implemented. Each item has a typed field or component so projects can already carry it.
 
-| Item                                                      | Where                            | Behaviour now                                    | Issue note                                    |
-| --------------------------------------------------------- | -------------------------------- | ------------------------------------------------ | --------------------------------------------- |
-| `Precomp`, `Adjustment`                                   | structure                        | Schema only; compile reports `stub-not-rendered` | issue: nested timelines and adjustment layers |
-| `shader(name)` transition                                 | `Scene.transition.type="shader"` | Falls back to dissolve with a warning            | issue: WebGL shader transitions               |
-| `.cube` LUTs                                              | `ColorGrade.lut`                 | Ignored with a warning                           | issue: WebGL grading pass + LUT loader        |
-| Text `extrude` (3D)                                       | text style                       | Ignored with a warning                           | issue: 3D text (phase 4)                      |
-| Dashed text stroke, `stroke.align="inside"`               | text style                       | Dash ignored; inside = centre                    | issue: SVG text rendering                     |
-| Video fill clipped to letters                             | text `fill`                      | Falls back to white with a warning               | issue: SVG clipPath + video                   |
-| `Video.reverse`                                           | media                            | Plays forward with a warning                     | issue: pre-rendered reversed copies           |
-| Sidecar `*.keys.json`                                     | keyframes `keys=`                | Field accepted, file not read                    | issue: sidecar keyframe files                 |
-| Phases 3–5                                                | UI, 3D, pro layer                | Not started                                      | see brief §12                                 |
-| `render` `variants` (9:16, 16:9, 1:1, 4:5)                | MCP `render`                     | Rejected with `invalid_edit`                     | issue: format variants (phase 5)              |
-| Editor type hints for `@codecut/*` in a published install | `codecut` package                | Not shipped: projects run, editors show no types | issue: emit `.d.ts` for core and components   |
-| Local TTS off macOS                                       | `voice_quote local-tts`          | `missing_dependency` with install steps          | issue: piper / espeak-ng provider             |
-| Original-quality Freesound files                          | `sound_get`                      | HQ MP3 preview (needs only an API key)           | issue: OAuth2 download flow                   |
-| Voice cost in money                                       | `voice_quote elevenlabs`         | Credits estimate; USD only if you set a rate     | issue: read the account's plan from the API   |
+| Item                                                        | Where                            | Behaviour now                                                  | Issue note                                                               |
+| ----------------------------------------------------------- | -------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `Precomp`, `Adjustment`                                     | structure                        | Schema only; compile reports `stub-not-rendered`               | issue: nested timelines and adjustment layers                            |
+| `shader(name)` transition                                   | `Scene.transition.type="shader"` | Falls back to dissolve with a warning                          | issue: WebGL shader transitions                                          |
+| `.cube` LUTs                                                | `ColorGrade.lut`                 | Ignored with a warning                                         | issue: WebGL grading pass + LUT loader                                   |
+| Text `extrude` (3D)                                         | text style                       | Ignored with a warning                                         | issue: 3D text (phase 4)                                                 |
+| Dashed text stroke, `stroke.align="inside"`                 | text style                       | Dash ignored; inside = centre                                  | issue: SVG text rendering                                                |
+| Video fill clipped to letters                               | text `fill`                      | Falls back to white with a warning                             | issue: SVG clipPath + video                                              |
+| `Video.reverse`                                             | media                            | Plays forward with a warning                                   | issue: pre-rendered reversed copies                                      |
+| Sidecar `*.keys.json`                                       | keyframes `keys=`                | Field accepted, file not read                                  | issue: sidecar keyframe files                                            |
+| Phases 3–5                                                  | UI, 3D, pro layer                | Not started                                                    | see brief §12                                                            |
+| `render` `variants` (9:16, 16:9, 1:1, 4:5)                  | MCP `render`                     | Rejected with `invalid_edit`                                   | issue: format variants (phase 5)                                         |
+| Editor type hints for `@flomotion/*` in a published install | `flomotion` package              | Not shipped: projects run, editors show no types               | issue: emit `.d.ts` for core and components                              |
+| Local TTS off macOS                                         | `voice_quote local-tts`          | `missing_dependency` with install steps                        | issue: piper / espeak-ng provider                                        |
+| Original-quality Freesound files                            | `sound_get`                      | HQ MP3 preview (needs only an API key)                         | issue: OAuth2 download flow                                              |
+| Voice cost in money                                         | `voice_quote elevenlabs`         | Credits estimate; USD only if you set a rate                   | issue: read the account's plan from the API                              |
+| Editing in the live view                                    | `flomotion ui`                   | Viewer with undo (Restore); no property editing                | issue: phase 3 editor (inspector from schemas, patches via the same ops) |
+| Skill checks not measured                                   | `references/checks.md`           | `palette-adherence` and `determinism` are reported as not run  | issue: frame colour sampling; double render of sample frames in `review` |
+| Pattern blocks (B)                                          | `references/blocks.md`           | Described, no recipes; build as custom scenes                  | issue: recipes for the 13 pattern blocks                                 |
+| AI image generation                                         | `asset_*`                        | Not built                                                      | issue: a generation provider with quote then confirm, like voice         |
+| Unsplash and Pixabay photos                                 | `asset_search`                   | Openverse and Pexels only                                      | issue: more stock sources                                                |
+| Capturing pages behind a login                              | `asset_capture`                  | Public pages only; use `asset_import` for your own screenshots | issue: cookies or a recorded session                                     |
+| Freesound original files                                    | `sound_get`                      | HQ MP3 preview with only an API key                            | issue: OAuth2 download flow                                              |

package/docs/spec.md

@@ -1,4 +1,4 @@
-# CodeCut spec (condensed, as implemented)
+# flomotion spec (condensed, as implemented)
 
 Sections 5–9 of the project brief, with the decisions made while building. Reference pages for every
 component are generated from the schemas into `docs/components/` (`pnpm run gen:docs`).
@@ -34,7 +34,7 @@ internals. Constants become static styles.
 
 ## 3. Syntax and timing rules (§5.3)
 
-- Every element has an `id`. A missing id is a lint warning and gets a stable `cc_` id (hash of its path).
+- Every element has an `id`. A missing id is a lint warning and gets a stable `fm_` id (hash of its path).
 - Effects are children of the layer they affect and apply in source order.
 - **Child timing is relative to the parent Scene/Group/Sequence start.** `start="@12s"` is absolute.
   Keyframe times are relative to the parent (the spec's "parent's local time"); expression `t` is relative to
@@ -93,7 +93,7 @@ rippleDelete snap lockTrack muteTrack soloTrack addMarker removeMarker`, as `edi
 
 ## 8. MCP server (§10.1)
 
-`codecut mcp --dir <project>` (or `npx -y flomotion mcp`) serves 30 tools over stdio for one project folder. All
+`flomotion mcp --dir <project>` (or `npx -y flomotion mcp`) serves 39 tools over stdio for one project folder. All
 paths are checked to stay inside it (`path_outside_project`). Every write returns `{ description, patches,
 undoToken }`; the undo token is the id of the history snapshot taken before the write (`history_restore`).
 Errors are `{ error: { code, message, fix, details } }` with `isError: true`. Codes: `schema_violation`,
@@ -101,23 +101,26 @@ Errors are `{ error: { code, message, fix, details } }` with `isError: true`. Co
 `unknown_element`, `duplicate_keyframe`, `invalid_time`, `impure_expression`, `missing_dependency`,
 `path_outside_project`, `font_error`, `render_failed`, `invalid_edit`.
 
-| Tool                                                                     | Does                                                                                                             |
-| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| `project_create` `project_read`                                          | scaffold (blank, saas-promo) and outline (`path` = element id, `depth`); first read writes stable `cc_` ids      |
-| `element_add` `element_set` `element_remove` `element_move` `effect_add` | structured edits, props validated by the component schema                                                        |
-| `keyframe_set`                                                           | replaces all keys of an animatable prop; times snap to the frame grid                                            |
-| `edit`                                                                   | any timeline op (§7) or keyframe op (§6)                                                                         |
-| `scene_write`                                                            | replace an element with TSX you write: parsed, impurity-scanned, imports added, linted; restored if it fails     |
-| `lint`                                                                   | schema, determinism, fonts, ledger, text rules; `scope` limits to a subtree                                      |
-| `frame_render` `contact_sheet`                                           | exact-time PNG, tiled JPG (images are returned to the model)                                                     |
-| `sound_search` `sound_get` `sound_auto`                                  | Freesound (key) or `sounds/catalog.json`; CC0/CC-BY by default; peak measured; ledger                            |
-| `font_search` `font_get` `font_list` `font_preview` `font_check`         | Google Fonts metadata (key), download + lock + ledger, usage, PNG sample, glyph coverage                         |
-| `transcribe` `voice_quote` `voice_generate` `align_to_voice`             | whisper.cpp via hyperframes, quote then `confirm:true`, retime to spoken words                                   |
-| `mix_preview` `render` `review`                                          | offline mix with measured loudness; presets draft/social/final with credits + licence report; 17-point checklist |
-| `history_list` `history_restore`                                         | snapshots of the TSX file                                                                                        |
-
-Resources: `codecut://schema/{component}` (JSON schema + docs), `codecut://project/outline`, `codecut://ledger`,
-`codecut://looks`.
+| Tool                                                                     | Does                                                                                                                                         |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `project_create` `project_read`                                          | scaffold (blank, saas-promo) and outline (`path` = element id, `depth`); first read writes stable `fm_` ids                                  |
+| `element_add` `element_set` `element_remove` `element_move` `effect_add` | structured edits, props validated by the component schema                                                                                    |
+| `keyframe_set`                                                           | replaces all keys of an animatable prop; times snap to the frame grid                                                                        |
+| `edit`                                                                   | any timeline op (§7) or keyframe op (§6)                                                                                                     |
+| `scene_write`                                                            | replace an element with TSX you write: parsed, impurity-scanned, imports added, linted; restored if it fails                                 |
+| `lint`                                                                   | schema, determinism, fonts, ledger, text rules; `scope` limits to a subtree                                                                  |
+| `frame_render` `contact_sheet`                                           | exact-time PNG, tiled JPG (images are returned to the model)                                                                                 |
+| `sound_search` `sound_get` `sound_auto`                                  | Freesound (key) or `sounds/catalog.json`; CC0/CC-BY by default; peak measured; ledger                                                        |
+| `font_search` `font_get` `font_list` `font_preview` `font_check`         | Google Fonts metadata (key), download + lock + ledger, usage, PNG sample, glyph coverage                                                     |
+| `transcribe` `voice_quote` `voice_generate` `align_to_voice`             | whisper.cpp via hyperframes, quote then `confirm:true`, retime to spoken words                                                               |
+| `mix_preview` `render` `review`                                          | offline mix with measured loudness; presets draft/social/final with credits + licence report; 17-point checklist                             |
+| `history_list` `history_restore`                                         | snapshots of the TSX file                                                                                                                    |
+| `setup_status`                                                           | what is set up and what is missing, by job; never returns a key                                                                              |
+| `voice_import` `transcript_import` `sound_import` `asset_import`         | the person's own recording, transcript or captions, sound files, images and video, from anywhere on their computer, with their stated rights |
+| `asset_search` `asset_get` `asset_capture` `brand_extract`               | icons, emoji, logos, photos, illustrations from open sources; screenshots and brand from the person's own site                               |
+
+Resources: `flomotion://schema/{component}` (JSON schema + docs), `flomotion://project/outline`, `flomotion://ledger`,
+`flomotion://looks`.
 
 ### Editing TSX (codemods)
 
@@ -134,9 +137,9 @@ than writing something different.
 
 Sound tags: `ui/pop ui/tap ui/tick move/whip move/whoosh-deep hit/land hit/punch hit/boom tech/click tech/data
 tech/glass tech/success tech/glitch`. `sound_get` records `{source,id,author,license,url,attributionRequired,
-commercialOk,peak}` in `.codecut/ledger.json` (peak names merge when one sound serves several tags).
+commercialOk,peak}` in `.flomotion/ledger.json` (peak names merge when one sound serves several tags).
 `<Sound at peak>` starts early by the peak so it lands on `at`. Ledger licence strings are SPDX-like (`CC0-1.0`,
-`CC-BY-4.0`); `codecut.json` `soundLicenses` lists the allowed families (`["CC0"]` restricts). Voice providers:
+`CC-BY-4.0`); `flomotion.json` `soundLicenses` lists the allowed families (`["CC0"]` restricts). Voice providers:
 `recording` (default), `local-tts` (macOS `say`), `elevenlabs` (quote, then `confirm:true`). Mix presets set the
 master LUFS (-14).
 
@@ -145,3 +148,61 @@ master LUFS (-14).
 17 checks decided from the compiled project (baked channels give motion and static gaps), the lint, the ledger,
 the measured mix, and `hyperframes check` for layout and contrast. Statuses: pass, fail, warn, manual, skipped.
 Manual items are for the agent's second pass over the contact sheet; the tool never marks them as passed.
+
+## 9. Live view (`flomotion ui`, `flomotion mcp --ui`)
+
+A small local web page that shows what the agent is doing while it makes the video. `flomotion ui` serves it for a
+folder; `flomotion mcp --ui` serves it from the MCP process (the address goes to stderr and into the `ui` field of
+`project_read` and `project_create`). It binds `127.0.0.1` only and answers only requests whose `Host` is
+localhost (no DNS rebinding); the page loads nothing from the network.
+
+- **Activity:** every tool call is appended to `.flomotion/activity.jsonl` by the MCP server (tool, shortened
+  arguments, ok, duration, one-line summary, undo token). The page lists them newest first.
+- **State:** `GET /api/state` gives the outline and timeline (from evaluating the TSX; a file that fails to load
+  keeps the last good picture and shows the error), history, activity, the ledger, the last `review` result
+  (`.flomotion/review/last.json`), gate files (`interview.md brief.md script.md storyboard.md LOG.md`), renders
+  and frames. Changes reach the page over Server-Sent Events (`/events`), which polls the files twice a second.
+- **Preview:** `GET /api/frame?t=` builds the project in its own folder (`.flomotion/ui-build`, never the agent's)
+  and snapshots one frame, one build at a time, cached while the files are unchanged.
+- **Files:** `/files/...` serves only frames, sheets, previews, renders and assets (with range requests for video).
+  Source, ledger internals, history and the activity log are never served.
+- **Restore:** `POST /api/restore {id}` (requires a custom header so other sites cannot call it) restores a snapshot
+  and is logged and undoable like any write.
+
+A link can open a tab and a time: `http://127.0.0.1:4317/#tab=review&t=2.4` (tabs: outline, code, review, assets, renders, history). It is a viewer with undo, not an editor: edits are made by the agent (or by hand in the file).
+
+## 10. Setup, the person's own material, and assets
+
+**`flomotion setup`** asks how the person wants to supply voice, word timings, sound effects and graphics, and saves
+the keys that go with their choices to `~/.config/flomotion/config.json` (or `$FLOMOTION_CONFIG`; mode 0600; never
+in the project, never sent to the model). Every key is optional and checked against its service with one read-only
+request (Freesound search, ElevenLabs `GET /v1/user/subscription`, Google Fonts, Pexels). Real environment
+variables win over saved keys. `setup show | check | set <name> [key] | unset <name> | sounds <folder> --rights`,
+and `setup --yes` to save keys that are already in the environment. A folder of the person's own sounds is indexed by
+name (tags from file and folder names) into `sound-library.json` next to the config; lengths are measured when a
+sound is found, not when indexed.
+
+**Voice and timings.** `voice_import` copies a recording in (assets/voice) and records it as the person's;
+`transcript_import` turns SRT, VTT, word-level JSON (Whisper, ElevenLabs alignment, hyperframes), segment JSON,
+lines starting with a time, or plain text into `<audio>.words.json` and reports the **precision**: `word` (exact),
+`cue` (a time per line; words spread by length), `estimated` (plain text spread over the audio length). The
+quote for a paid voice shows the real remaining allowance of the account.
+
+**Sounds.** Your own files (project `sounds/catalog.json`, the library index, `sound_import`) are searched first,
+then Freesound. They are used as `local:ID`. A row with a stated `rights` is always allowed; the person's statement
+is recorded in the ledger as `rights asserted by the person`, never verified.
+
+**Assets.** Sources: Iconify (icons, emoji, brand logos; per-set SPDX licence from its API; no key), Openverse
+(photos and illustrations, filtered to CC0, PDM and CC-BY; no key), Pexels (key). Allowed licence classes by default:
+CC0, permissive (MIT, Apache, ISC, BSD, OFL), CC-BY; share-alike, non-commercial and unknown are refused
+(`flomotion.json` `assetLicenses` narrows it). Brand logos are trademarks and need `permission:true`. Files go to
+`assets/third-party/<source>/` (pulled), `assets/captures/` (screenshots), `assets/brand/` (from the person's site),
+`assets/imported/` (the person's own), each with a ledger entry (`assetKind`, licence, author, hash, source URL).
+SVG that contains scripts, event handlers, `foreignObject` or external references is refused. `lint` requires a
+ledger entry for any Image, Svg or Video under those folders and refuses one that is not cleared for commercial use;
+the render's credits file lists CC-BY assets and, separately, credits a source asks for but the licence does not
+require. `asset_capture` and `brand_extract` need `permission:true` (the person owns the page or may show it) and
+use headless Chrome and the network once; `asset_capture` dismisses `alert()` dialogs and can hide elements.
+
+Reading the person's files: only audio, image, video, caption and transcript types; never `.env`, `.ssh`, `.aws`,
+`.gnupg`, keychains, `id_rsa`, `.npmrc` and the like.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flomotion",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "A code-first video editor: a video is one TSX file, edited by Claude through MCP and rendered with HyperFrames.",
   "type": "module",
   "license": "MIT",
@@ -17,7 +17,6 @@
     "node": ">=22"
   },
   "bin": {
-    "codecut": "dist/bin.mjs",
     "flomotion": "dist/bin.mjs"
   },
   "exports": {

package/skills/flomotion-studio/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+Format: date, what changed, why (evidence), effect on the 10-brief eval.
+
+## 2026-10-25: v0.4.0 (flomotion 0.4.0)
+- Setup and the person's own material: `setup_status` first; Round 0 of the interview asks how voice, word timings, sound effects and graphics will be supplied (own files first, services optional). New tools in `mcp-tools.md`: `voice_import`, `transcript_import` (with precision: word, cue, estimated), `sound_import`, `asset_import`.
+- `references/assets.md`: where each SaaS graphic comes from (icons, logos with permission, screenshots, brand from the person's site, photos), the asset plan in the storyboard, permission rules. New tools: `asset_search`, `asset_get`, `asset_capture`, `brand_extract`.
+- `workflow.md`: materials check at G0, asset plan at G4, asset pulling before the draft build. `sound.md`: own sound files and own transcripts.
+- Evidence: package tests (every tool, live Iconify and Openverse, the setup wizard, skill structure). Eval on the 10 briefs: not run.
+
+## 2026-10-24: v0.3.0 (shipped in the flomotion package)
+- Reconciled with the real MCP: `references/mcp-tools.md` rewritten with the 30 real tools, call order, error codes; `references/checks.md` says which checks `review` computes (17) and which the agent computes or cannot run; `sound.md` uses the real sound tags and `sound_auto`.
+- Added `references/block-recipes.md` (13 core blocks as TSX, linted by the package tests) and `references/components.md` (generated).
+- The three looks now exist in the engine (`theme="$look.clean-light" | "dark-product" | "bold-kinetic"`), derived from `looks/*.md`; a test keeps palette, fonts and easing in sync.
+- Live view: SKILL.md tells the person about `flomotion ui` and what it shows; the agent keeps the gate files current.
+- Evidence: package tests (skill files, recipes lint, looks sync, installer). Eval on the 10 briefs: not run.
+
+## 2026-10-23: v0.2.2
+- Product name flomotion renamed to flowmotion in all files.
+
+## 2026-10-23: v0.2.1
+- Renamed skill to flomotion-studio.
+
+## 2026-10-23: v0.2.0
+- Added `references/interview.md` (9 adaptive rounds, 28 must-have fields, clarity score >= 90%, mandatory read-back) and `dataset/brief-template.md`.
+- SKILL.md rule 0 and G0 now require the interview. Reason: user asked for an extensive, adaptive interview before any design work.
+- Eval: not run yet.
+
+## 2026-10-23: v0.1.0
+- Initial package: SKILL.md, 16 references, 3 starter looks, 9 reference annotations, thresholds, eval briefs.
+- Evidence: 8 reference ads annotated from still frames (user-collected from one compilation). No ratings or durations yet.
+- Eval: not run yet.
+
+## 0.4.0: Markdown only, the storyboard board, clean styles
+
+- **No JSON in the skill.** Looks, thresholds, the reference annotations and the schemas are Markdown tables a model reads directly; the gate files are `brief.md`, `script.md`, `storyboard.md` (a project that still has the `.json` versions is read too).
+- **The Storyboard tab:** `ideas.md` (brainstorm) and `storyboard.md` (the plan) show in the live view as a board and a timeline that turns green as scenes are built. New `references/storyboard.md`.
+- **New references:** `clean-styles.md` (from three reference pieces: character story, glowing thread, build-as-story), `script-craft.md` (the engineered script), `transitions.md` (signature transitions with TSX: the two-dots turn, the vault door, the mascot).
+- **Example:** `examples/flomotion-ad/`: the 30 s ad for flomotion itself, with its script, storyboard and an honest log.

package/skills/flomotion-studio/README.md

@@ -0,0 +1,81 @@
+# flomotion-studio skill package
+
+A constraint layer for Claude driving the flomotion MCP (a video is one TSX file, rendered by HyperFrames). It makes output consistently professional by forcing a gated workflow, data-driven looks, reusable scene blocks, and automatic checks.
+
+## Structure
+
+```
+flomotion-studio/
+  SKILL.md                      entry point (short, procedural)
+  README.md                     this file
+  CHANGELOG.md                  record every change with its evidence
+  config/
+    thresholds.md             all numeric defaults (tunable, proposals)
+  references/
+    interview.md                extensive adaptive interview (G0), clarity score
+    workflow.md                 gates, unattended rules
+    catalogue.md                analysis of the 8 reference ads
+    patterns.md                 21 distilled rules
+    styles.md                   7 style-family recipes
+    looks.md                    look token spec + 3 starter looks
+    blocks.md                   scene block library and parameters
+    story-templates.md          15 s / 30 s / 45 s beat sheets
+    decision-tables.md          brief -> style, look, template
+    copywriting.md              hooks, word limits, proof, CTA
+    motion.md                   easing, timing, impacts, transitions
+    typography.md               type scale and emphasis
+    sound.md                    sound palettes and mix
+    checks.md                   23 automatic checks
+    review.md                   review protocol and rubric
+    anti-patterns.md            mistakes with before/after
+    mcp-tools.md                the real tool list and call order
+    assets.md                   where graphics come from, the asset plan, permission rules
+    block-recipes.md            TSX recipes for the 13 core blocks (linted by tests)
+    transitions.md              signature transitions with TSX: slab, iris, stripes, the two-dots turn, the vault door, the mascot
+    script-craft.md             the engineered script: hook, pain, turn, promise, proof, reveal, CTA
+    clean-styles.md             what clean, catchy motion looks like, from three reference pieces
+    storyboard.md               the Storyboard tab: ideas.md, storyboard.md, what the board shows
+    components.md               generated from the schemas
+  looks/
+    clean-light.md  dark-product.md  bold-kinetic.md
+  dataset/
+    schema.md                   reference-ad annotation schema
+    brief-template.md           interview output (brief) template
+    rating-sheet.md             human rating template
+    annotations/*.md          one file per reference ad
+  evals/
+    briefs/briefs.md            10 invented test briefs
+    README.md                   how to run and compare
+  examples/
+    saas-promo/                 a finished 30 s project (engine look)
+    flomotion-ad/               the 30 s ad for flomotion itself: project, script, storyboard, log
+    engine-looks/               reference scenes for the engine's kinetic, minimal, sketch looks
+```
+
+## Install
+
+```bash
+npx -y flomotion install skill              # for all your projects: ~/.claude/skills/flomotion-studio
+npx -y flomotion install skill --project    # only this folder: ./.claude/skills/flomotion-studio
+```
+
+(`flomotion install skill` is the same command if the package is installed.) Then add the MCP server in your video folder:
+`claude mcp add flomotion -- npx -y flomotion mcp --dir . --ui`, and open the printed address to watch progress.
+
+Claude loads `SKILL.md` on a video request and reads references only when a step needs them.
+
+## What is verified and what is not
+
+- Verified: the file structure is complete and every file named in SKILL.md exists.
+- Reconciled with the real tool list (v0.3.0): `references/mcp-tools.md` named the 30 tools the server had then (39 from v0.4.0), and `references/checks.md` says which checks `review` computes and which you compute. The three looks exist in the engine as `theme="$look.clean-light"` etc. The recipes in `references/block-recipes.md` are linted by the package's tests.
+- Not verified: nothing here has been run in a real Claude Code session yet (see `docs/gate2-manual-checklist.md` in the package).
+- The reference annotations come from **still frames only**. Timings, sound and exact motion are inferred or marked `null`. Fill them from your own viewing.
+- All thresholds are starting guesses. Tune them from your ratings (see `evals/README.md`).
+- The 3 looks are starters with original palettes. Replace after giving direction notes.
+
+## Extending the dataset
+
+1. Copy an annotation file, change `id`, fill the fields.
+2. Add duration, platform and your 1 to 5 rating (`dataset/rating-sheet.md`).
+3. Re-derive patterns: if 3 or more rated-4+ ads share a trait, add or tighten a rule in `references/patterns.md` and a check in `references/checks.md`.
+4. Log the change in `CHANGELOG.md` with the evidence.