freecodego 0.1.7-alpha.2.2 → 0.1.7-rc.2.2

package/dist/assets/design/skills/hyperframes-keyframes/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: hyperframes-keyframes
+description: >
+  Use when a HyperFrames composition needs a punch-in, punch-out, zoom, reframe,
+  Ken Burns treatment, camera move, visual match/whip handoff, or other seek-safe
+  2D/3D keyframes; also for GSAP, CSS keyframes, Anime.js, WAAPI, FLIP, paths,
+  masks, SVG morph/draw, text trails, 3D depth, or `freecodego_design_keyframes` diagnostics.
+  Don't use for broad scene strategy, brand design, media sourcing, captions, or
+  general video planning.
+---
+
+# HyperFrames Keyframes
+
+Keyframes are a pose contract: visible states, continuous subject identity, seek-safe runtime, verified pixels.
+
+Use `hyperframes-animation` for broad scene recipes. Use `hyperframes-cli` for full command docs. Use `references/keyframe-patterns.md` only when choosing implementation mechanisms, not visual style.
+
+## Creator editing boundary
+
+Keyframes own visual motion, not clip assembly. Source-range hard cuts, trim,
+splice, and reorder belong to `/hyperframes-core`: author one media element per
+kept range, place it with `data-start` and `data-duration`, and select its source
+offset with `data-media-start`. Adjacent ranges make a hard cut. A crossfade
+uses overlapping clips on different tracks plus visual opacity keyframes; sound
+fades use `/hyperframes-audio`.
+
+| Creator request                         | Truthful mechanism                                                                                                                                                                                                          |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Punch-in / punch-out                    | Keyframe `scale` with `x`/`y` or percentage translation on a non-timed visual/crop wrapper inside the clip. Use a set/short tween for a hard punch and a tween for a smooth move.                                           |
+| Smooth multi-state zoom or reframe      | Keep one subject wrapper alive and author multiple zoom/reframe states as a pose ladder with per-segment easing.                                                                                                            |
+| Pan, reframe, or Ken Burns camera move  | Animate wrapper translation plus scale. Geometry is authored; this is not face tracking or automatic semantic reframing.                                                                                                    |
+| Chained camera moves                    | Chain labeled transform beats on one registered seek-safe timeline.                                                                                                                                                         |
+| Match cut or whip pan                   | `/hyperframes-animation` owns the visual handoff; `/hyperframes-registry` supplies primitives; keyframes preserve authored geometry, direction, and velocity. There is no automatic matching-frame discovery.               |
+| Crop and mask reframe                   | Interpolate `clip-path` or a mask on an inner visual wrapper to crop/reframe without changing source time. Polygon keyframes can form a polygon/mask transition.                                                            |
+| Directional wipe cut or iris/reveal cut | Animate a mask/clip boundary across overlapping visual clips; `/hyperframes-animation` owns the handoff choreography.                                                                                                       |
+| Split-screen handoff                    | Keep both visual clips placed by core, then keyframe their inner crop/mask wrappers and divider geometry.                                                                                                                   |
+| Constant source retime                  | `/hyperframes-core` owns normalized `data-playback-rate` (`0.1..10`) for render-safe picture and pitch-preserved sound. It is constant for the whole media element.                                                         |
+| Source speed ramps                      | A `rate` lane in `data-automation` on the `<video>`/`<audio>` (`t` in clip seconds, `v` 0.1..10, log interpolation); it wins over the constant rate.                                                                        |
+| Freeze / hold                           | A visual pose, final source frame, or finished sub-composition can hold. Arbitrary mid-source freeze is not supported; preprocess a still/derived segment, place it as its own clip, then resume with another source range. |
+
+When editing picture and sound together, load `/hyperframes-core`, this skill for
+visual motion, and `/hyperframes-audio` for fades, crossfades, volume automation,
+ducking/carve, or effects on the placed tracks.
+
+A visual transition or cropping treatment is not a temporal source trim or
+splice. `/hyperframes-core` owns the timeline, clip timing, and source ranges;
+keyframes only animate the visible handoff or crop on wrappers inside those clips.
+For copyable combined picture/sound recipes, use `/hyperframes-core` → `references/creator-editing-recipes.md`.
+
+## Procedure
+
+1. Identify the animated subject, visible states, final state, and runtime.
+2. Choose the smallest mechanism that proves the prompt. Read `references/keyframe-patterns.md` only if the mechanism is unclear.
+3. Author seek-safe keyframes in the declared runtime. Build synchronously and register the runtime instance.
+4. Verify with `freecodego_design_lint`, `freecodego_design_lint`, `freecodego_design_keyframes`, one focused `--shot`, and snapshots at proof times.
+5. If proof fails, fix the source keyframes and rerun the smallest failing diagnostic before rendering.
+
+## Contract
+
+- Name the moving subject.
+- Name the poses needed to prove the intended motion, including the final state.
+- Keyframe visible channels, not hidden helper state.
+- Preserve object identity when continuity matters.
+- Crossfade only when the intended motion is replacement or dissolve.
+- Hold readable or semantic states long enough to see.
+- Final frame is part of the animation, not cleanup.
+- Do not reset to rest unless requested.
+- Do not end on black unless requested.
+- If editing a starter scene, preserve layout, copy, assets, colors, and final state unless asked to redesign.
+
+## Runtime Rules
+
+GSAP:
+
+- build synchronously at page load
+- use `gsap.timeline({ paused: true })`
+- register as `window.__timelines[compositionId]`
+- registry key must match `data-composition-id`
+- do not call `tl.play()` for render-critical motion
+- keep repeats finite
+
+CSS keyframes:
+
+- finite duration and iteration count
+- deterministic delay
+- `animation-fill-mode: both`
+- use `data-start` when timing belongs to a clip
+
+Anime.js:
+
+- create synchronously
+- `autoplay: false`
+- finite duration and loops
+- push every instance to `window.__hfAnime`
+
+WAAPI:
+
+- finite `duration`
+- `fill: "both"`
+- deterministic construction
+- the text surface does not list WAAPI; verify with `--shot` (it seeks WAAPI) and snapshots
+
+Never use for render-critical motion:
+
+- `Date.now()`
+- `performance.now()`
+- unseeded `Math.random()`
+- hover/scroll triggers
+- timers
+- async-created timelines
+- unregistered `requestAnimationFrame`
+- infinite loops
+
+## GSAP Skeleton
+
+```js
+const root = document.querySelector("[data-composition-id]");
+const compositionId = root.dataset.compositionId;
+const tl = gsap.timeline({ paused: true });
+
+tl.addLabel("state-a", 0);
+tl.to(".subject", {
+  keyframes: [
+    { x: 0, opacity: 1, duration: 0.2 },
+    { x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
+    { x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
+  ],
+  ease: "none",
+});
+
+window.__timelines = window.__timelines || {};
+window.__timelines[compositionId] = tl;
+```
+
+Use labels for semantic states. Use position parameters instead of chained delays. Use `immediateRender: false` for later `from()`/`fromTo()` tweens touching the same property.
+
+## Keyframe Forms
+
+- Array keyframes: pose ladder with per-step duration/ease.
+- Percentage keyframes: exact timing inside one tween.
+- Property arrays: compact multi-stop changes.
+- `ease: "none"` on the parent when each stop carries its own easing.
+- `easeEach` when every segment should share the same feel.
+
+Do not copy numeric distances or timing from examples. Derive them from the actual composition geometry and duration.
+
+For one subject moving between two boxes, prefer one continuous transform tween or FLIP. Split `x/y/scale` into multiple eased keyframes only when the viewer should feel distinct beats; every segment changes velocity and can read as a hitch.
+
+## Channels
+
+Prefer compositor/visual channels: `x/y/z`, `xPercent/yPercent`, `scale`, `rotationX/Y/Z`, `skew`, `transformOrigin`, `svgOrigin`, `opacity`, `autoAlpha`, `clip-path`, masks, CSS vars, SVG path/dash values, camera transforms, shader uniforms.
+
+Avoid layout/lifecycle channels: `top/left/right/bottom`, `width/height`, `margin/padding`, `display`, `visibility`, late DOM creation, helper overlays doing subject motion.
+
+For visibility changes, use `autoAlpha` on the registered seekable GSAP timeline, or a zero-duration `tl.set()` at an explicit boundary. Target only a non-clip element or a wrapper inside the clip; never target `.clip` itself. Never duration-tween raw `visibility`, and never tween `display`.
+
+## Mechanism Choice
+
+Choose the smallest mechanism that proves the prompt:
+
+| Need                                  | Mechanism                                          |
+| ------------------------------------- | -------------------------------------------------- |
+| Same subject changes box or hierarchy | shared element / FLIP                              |
+| Subject travels a visible route       | path travel                                        |
+| Stroke grows or traces                | stroke draw                                        |
+| Shape becomes another shape           | shape interpolation                                |
+| Reveal boundary is visible            | clip, mask, or shader uniform                      |
+| Many items move with order            | stagger / indexed delay                            |
+| Text itself moves                     | line, word, character, or band subdivision         |
+| Surface bends, stretches, or crops    | parent/child counter-transform                     |
+| UI has states                         | explicit state machine                             |
+| Scene has depth                       | DOM 3D, Three.js, or WebGL camera/object keyframes |
+
+Mechanisms can combine, but each one must clarify the idea. Decoration is not proof.
+
+## Timing
+
+- Anticipation only when it clarifies cause or direction.
+- Acceleration leaves rest.
+- Peak proof shows the mechanism unmistakably.
+- Follow-through sells energy and direction.
+- Overshoot only when the subject should feel elastic or tactile.
+- Constant-speed path travel usually needs `ease: "none"`.
+- Discrete UI states usually need a sharp ease-out.
+- Repeated elements need ordered offsets, not identical timing.
+- Final lockups need longer holds than transition poses.
+- Smoothness means continuous velocity on the same subject.
+- Do not overlap tweens that write the same transform property unless the overlap is intentional and verified.
+- Avoid animating large `clip-path`/mask changes while the same hero surface is also scaling or traveling; use nested reveals after the main move settles.
+
+## Text
+
+Preserve line boxes, word spacing, readability, and final fit. If text moves internally, move the glyphs or masked bands, not only decorations around the text. Snapshot readable frames.
+
+## SVG
+
+For stroke growth prefer `DrawSVGPlugin`, then `stroke-dasharray`/`stroke-dashoffset`. For shape interpolation prefer `MorphSVGPlugin`; convert primitives to paths when needed and split complex silhouettes into simpler parts.
+
+## 3D
+
+Scale alone is fake depth. Use perspective on a stable parent, `transform-style: preserve-3d`, z travel, rotation, camera/world motion, occlusion, and layer order when objects cross.
+
+Use one or two diagnostic angles that expose the depth relationship. If angled proof shows no depth crossing, improve z/camera/occlusion.
+
+## Canvas / WebGL
+
+Keyframe camera position, camera target, object transform, material opacity, shader uniforms, and postprocess intensity through deterministic state. Render from HyperFrames time. Use `--ghost` because marker boxes cannot see internal canvas motion.
+
+## CLI Proof
+
+```bash
+freecodego_design_lint
+freecodego_design_lint
+freecodego_design_keyframes .
+freecodego_design_keyframes . --json
+freecodego_design_keyframes . --runtime all
+freecodego_design_keyframes . --selector "<selector>" --shot "<file>" --samples <n>
+freecodego_design_keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
+freecodego_design_keyframes . --shot "<file>" --ghost --angle <angle>
+freecodego_design_snapshot . --at <times>
+```
+
+Choose `<selector>` for the real animated subject. Choose `<times>` for first frame, proof poses, final-minus-hold, and exact final. Choose `<angle>` only when depth must be proven.
+
+| Tool             | Proves                                                                                              |
+| ---------------- | --------------------------------------------------------------------------------------------------- |
+| `keyframes`      | targets, explicit stops, paths, traces, composed parent/child motion, CSS stops, Anime registration |
+| `--shot`         | ghosts, route shape, time spacing, DOM 3D projection, focused selector proof                        |
+| `--layout strip` | in-place motion, overlaps, contact, subtle scale/opacity, text waves                                |
+| `--ghost`        | canvas, WebGL, shader motion, rendered 3D                                                           |
+| `snapshot --at`  | masks, text readability, full state, final lockup, black/reset tails                                |
+
+If selector proof looks wrong:
+
+1. rerun `--json`
+2. find the actual animated target
+3. shoot that target
+4. snapshot full frames
+5. trust painted pixels over logs
+
+## Diagnostic Reading
+
+`flat` means no explicit middle poses. `keyframes` means explicit stops exist. `motionPath` means a route exists. `trace` means multi-stroke drawing. `composed with` means child motion inherits parent motion.
+
+Even ghost spacing means constant speed. Clustered ghosts mean slow-in or settle. Large gaps mean fast travel.
+
+A helper-selector shot is not proof. An onion shot over a broken full frame is not proof.
+
+## Error Handling
+
+| Failure            | Fix                                                                                |
+| ------------------ | ---------------------------------------------------------------------------------- |
+| endpoint-only      | add middle poses, hold peak proof, rerun `--shot`                                  |
+| identity break     | keep one element alive, use shared source/final boxes, remove substitute crossfade |
+| fake 3D            | add z/camera travel, occlusion, angled proof                                       |
+| wrong final        | add final hold, snapshot final-minus-hold and exact final                          |
+| unseekable runtime | pause autoplay, register instance, remove timers, build synchronously              |
+| unreadable text    | preserve line boxes, reduce displacement, add final hold, snapshot text frames     |
+
+## Done
+
+Run `freecodego_design_lint`, `freecodego_design_lint`, `freecodego_design_keyframes`, one focused `--shot`, and snapshots. Confirm first frame, proof poses, final-minus-hold, exact final, subject-owned motion, and no debug overlays.

package/dist/assets/design/skills/hyperframes-keyframes/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HyperFrames Keyframes"
+  short_description: "Author seek-safe video keyframes"
+  default_prompt: "Use $hyperframes-keyframes to author seek-safe 2D/3D keyframes and verify them with the CLI."

package/dist/assets/design/skills/hyperframes-keyframes/references/keyframe-patterns.md

@@ -0,0 +1,108 @@
+# Keyframe Mechanism Reference
+
+Use this after `SKILL.md` when choosing a concrete implementation mechanism. It is a parts shelf, not a style guide. Start with one primary mechanism; add supporting motion only when it clarifies the idea.
+
+## Runtime Skeletons
+
+GSAP:
+
+```js
+const root = document.querySelector("[data-composition-id]");
+const id = root.dataset.compositionId;
+const tl = gsap.timeline({ paused: true });
+tl.to("<selector>", {
+  keyframes: [
+    /* derive poses from the scene */
+  ],
+  ease: "none",
+});
+window.__timelines = window.__timelines || {};
+window.__timelines[id] = tl;
+```
+
+CSS:
+
+```css
+.<subject > {
+  animation: <name> <duration> <ease> both;
+  animation-iteration-count: 1;
+}
+@keyframes <name> {
+  0% {
+    transform: <pose-a>;
+    opacity: <a>;
+  }
+  100% {
+    transform: <pose-b>;
+    opacity: <b>;
+  }
+}
+```
+
+Anime.js:
+
+```js
+const animation = anime.createTimeline({ autoplay: false });
+animation.add("<selector>", {
+  /* derived channels */
+});
+window.__hfAnime = window.__hfAnime || [];
+window.__hfAnime.push(animation);
+```
+
+Three/WebGL:
+
+```js
+const state = { progress: 0 };
+tl.to(state, {
+  progress: 1,
+  duration: <duration>,
+  onUpdate: () => {
+    // derive camera/object/material values from state.progress
+    renderer.render(scene, camera);
+  },
+});
+```
+
+## Mechanisms
+
+| Mechanism           | Solves                                         | Keyframe                                                           | Runtime                                    | Verify                                         |
+| ------------------- | ---------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------ | ---------------------------------------------- |
+| Path travel         | Subject must visibly follow a route            | path progress, tangent rotation, follower offset, trail opacity    | GSAP MotionPath or sampled x/y/z           | strip shot at bends; final snapshot            |
+| Stroke draw         | A line, ring, or outline appears over time     | dash/draw range, stroke opacity, endpoint state                    | DrawSVG or SVG dash fallback               | partial mid snapshot; complete final           |
+| Shape interpolation | One silhouette becomes another                 | source path, middle path, target path, fill/stroke                 | MorphSVG or path tween                     | first/mid/final snapshots                      |
+| Shared element      | Same subject changes box or hierarchy          | source box, target box, x/y, scale, radius, context opacity        | GSAP Flip or manual FLIP                   | one identity moves; no substitute crossfade    |
+| Clip/mask reveal    | Animated boundary exposes content              | clip path, mask position/size, edge softness, inner counter-motion | CSS, SVG, GSAP, or shader                  | snapshot edge frames and final unclipped state |
+| Ordered repetition  | Many items enter, leave, or transform in order | indexed delay, x/y, scale, opacity, final alignment                | GSAP stagger, Anime stagger, CSS vars      | check first/middle/last item timing            |
+| Text subdivision    | Text motion needs readable internal timing     | line/word/char/band wrappers, y/x, opacity, final fit              | SplitText, authored spans, Anime splitText | strip shot plus final readability snapshot     |
+| Surface transform   | Image/card stretches, crops, or changes shape  | parent scale/skew/clip, child counter-scale, transform origin      | GSAP/CSS keyframes                         | no accidental warped final                     |
+| UI state machine    | Interface passes through semantic states       | closed, active, loading, success/error, final                      | GSAP/CSS/Anime                             | snapshots hit states in order                  |
+| DOM depth           | HTML elements need 3D separation               | perspective, z, rotationX/Y, opacity, crossing layer order         | CSS 3D + GSAP/CSS/Anime                    | angled `--shot`; overlap snapshot              |
+| Camera/object 3D    | Canvas/WebGL scene moves in depth              | camera, target, object transform, material opacity                 | Three.js/WebGL + GSAP proxy                | `--ghost`; snapshots at proof poses            |
+| Shader uniform      | Pixel effect is driven by scalar progress      | progress, edge width, noise, color mix, opacity                    | ShaderMaterial/WebGL uniforms              | `--ghost`; snapshot 0/edge/mid/final           |
+| Instanced system    | Many 3D objects move as one system             | instance transforms, scale, color/opacity, camera                  | Three InstancedMesh                        | snapshots, because DOM boxes miss internals    |
+| Imported model      | Model animation must scrub deterministically   | `AnimationMixer.setTime`, camera, material, lights                 | Three AnimationMixer                       | drive from HyperFrames time; `--ghost`         |
+
+## Source Links
+
+- GSAP keyframes: https://gsap.com/resources/keyframes/
+- GSAP timeline: https://gsap.com/docs/v3/GSAP/Timeline/
+- GSAP MotionPathPlugin: https://gsap.com/docs/v3/Plugins/MotionPathPlugin/
+- GSAP Flip: https://gsap.com/docs/v3/Plugins/Flip/
+- GSAP DrawSVGPlugin: https://gsap.com/docs/v3/Plugins/DrawSVGPlugin/
+- GSAP MorphSVGPlugin: https://gsap.com/docs/v3/Plugins/MorphSVGPlugin/
+- GSAP SplitText: https://gsap.com/docs/v3/Plugins/SplitText/
+- GSAP CSSPlugin: https://gsap.com/docs/v3/GSAP/CorePlugins/CSS/
+- Anime.js documentation: https://animejs.com/documentation/
+- Anime.js stagger grid: https://animejs.com/documentation/utilities/stagger/stagger-parameters/stagger-grid/
+- Anime.js timeline: https://animejs.com/documentation/timeline/
+- Anime.js SVG helpers: https://animejs.com/documentation/svg/createmotionpath/
+- MDN CSS animations: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_animations/Using_CSS_animations
+- MDN `@keyframes`: https://developer.mozilla.org/en-US/docs/Web/CSS/@keyframes
+- MDN `clip-path`: https://developer.mozilla.org/en-US/docs/Web/CSS/clip-path
+- MDN CSS masking: https://developer.mozilla.org/en-US/docs/Web/CSS/mask
+- MDN perspective: https://developer.mozilla.org/en-US/docs/Web/CSS/perspective
+- MDN transform-style: https://developer.mozilla.org/en-US/docs/Web/CSS/transform-style
+- Three.js AnimationMixer: https://threejs.org/docs/#api/en/animation/AnimationMixer
+- Three.js ShaderMaterial: https://threejs.org/docs/#api/en/materials/ShaderMaterial
+- Three.js InstancedMesh: https://threejs.org/docs/#api/en/objects/InstancedMesh

package/dist/assets/design/skills/hyperframes-studio/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: hyperframes-studio
+description: >
+  Use when building or editing a HyperFrames project that people open in
+  Studio: how the timeline should be laid out so it reads well (one caption
+  track, one element kind per track, every scene a sub-composition) and where
+  captions and key content may sit (safe zones). Don't use for how to perform an
+  individual edit (split, trim, retime, volume, copy, swap): that is
+  `creator-editing-recipes.md` in `/hyperframes-core`.
+---
+
+# HyperFrames Studio conventions
+
+Studio draws one timeline row per top-level element. A project that follows the
+rules below opens as a short, readable timeline; one that does not opens as a wall
+of unlabeled rows the user cannot edit. These are conventions for what to build.
+For how to change a clip, follow `/hyperframes-core` `references/creator-editing-recipes.md`
+and never invent a different form of the same edit.
+
+## 1. Every scene is a sub-composition
+
+The root composition holds only timed hosts, media and audio. Any scene with nested
+structure (a div containing children, a title with a subtitle, a chart) is its own
+file loaded with `data-composition-src`, wiring in
+`references/sub-compositions.md`.
+
+Nested markup left inside the root does not become a row of its own. It hides inside
+one opaque row that cannot be trimmed or moved part by part.
+
+Author as if a structure lint rejects any violation.
+
+## 2. One caption track
+
+- All captions live on one track: a single sub-composition host (one `data-track-index`)
+  marked `data-track-kind="captions"` that carries every caption group in order.
+- Never one row per caption group, and never captions mixed onto a track with
+  another kind.
+- Word-timing rules are unchanged: see `/embedded-captions` and the `caption_*` lint rules.
+
+## 3. One element kind per track
+
+Group by kind so each row is one thing the user can select, mute or drag as a set.
+
+| Kind                                    | `data-track-kind`      |
+| --------------------------------------- | ---------------------- |
+| Base video / A-roll                     | `video` (from the tag) |
+| Scenes, overlays, graphics              | `graphics`             |
+| Captions                                | `captions`             |
+| Audio (voiceover, music, sound effects) | `audio` (from the tag) |
+
+Put `data-track-kind` on sub-composition hosts. Video and audio kinds come from the tag, so
+`<video>` and `<audio>` need no attribute. Give each kind its own `data-track-index`; the number
+is display only; it never changes what renders on top. Use CSS for
+layering.
+
+## 4. Safe zones
+
+Any ruler or safe-box overlay lives in the preview pane, never inside the composition, so
+do not add guide elements to the HTML.
+Both framings (wide and vertical) use the same two safe boxes, Premiere's defaults. The preview
+toggle draws them with a tick at the midpoint of every edge. Source:
+`ACTION_SAFE_PERCENT` and `TITLE_SAFE_PERCENT` in `packages/studio/src/utils/previewSafeMargins.ts`.
+
+| Box         | Share of the frame | Inset on every edge |
+| ----------- | ------------------ | ------------------- |
+| Action-safe | 90%                | 5%                  |
+| Title-safe  | 80%                | 10%                 |
+
+- Safe margins: everything visible stays inside the action-safe box (90%), and captions and key content stay inside the title-safe box (80%).
+- Two-up and 50/50 layouts keep each half's content inside the title-safe box.
+
+## Checking your work
+
+Run `freecodego_design_lint` and fix every finding. Then open the project in Studio and
+check that the timeline shows a base row, one row per scene host, one caption row and the audio rows.

package/dist/assets/design/skills/motion-graphics/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: motion-graphics
+description: >
+  A short, design-led motion graphic where motion is the message — kinetic
+  typography, stat count-up, chart/data-viz hit, logo sting / brand lockup,
+  lower-third / callout / social overlay, animated map (highlight regions,
+  connect places, zoom to a location), animated tweet / news-article /
+  headline, webpage / UI animation (scroll, cursor, callouts), or fusing a
+  real image's geometry into a chart. Usually under 10s (up to ~30s), no
+  narration or live-action subject; renders to MP4 or transparent overlay.
+  Longer / narrated / multi-scene → /general-video. Unclear → /hyperframes.
+---
+
+> **First, keep this skill fresh — confirm with the user before running:** `this pack is bundled offline and is not updated at runtime motion-graphics`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
+
+> **figma source**: If the logo/asset/animation to build from comes from a figma.com URL, run `/figma` first — asset export, brand tokens, and Motion→GSAP translation if the graphic is a Figma Motion import — then build from its output. Don't drive Figma via raw MCP tools directly: that skips SVG sanitization, `.media/manifest.jsonl` provenance, and brand-token `var()` binding, so a later brand change can't propagate without a full re-import.
+
+# motion-graphics — dispatch entry
+
+> **The front door is `/hyperframes`.** This skill makes a **short, design-led, unnarrated motion graphic** (motion is the message; ~under 10s, no voice-over). Anything longer, narrated, or multi-scene — or any uncertainty → read `/hyperframes` first: the intent layer owns every route decision.
+
+This workflow is **autonomous by design** — at most one clarifying question (`agents/director.md`), then build through verification without intermediate review. The intent layer (`/hyperframes` → `references/intent-interview.md`) routes here directly without run-shape questions; a storyboard and companion session add little to a piece this short. Rendering is still user-gated: after checks and proof snapshots pass, ask the canonical “preview first, or render?” question from `../hyperframes/references/brief-contract.md`. When a `BRIEF.md` exists, read it before the director's question.
+
+A short design-led motion graphic. **Asset-first**: decide the asset strategy and source real material _before_ designing the shot, then design the shot around what you have, then compose by reusing catalog capabilities. All artifacts go to `PROJECT_DIR = videos/<project-name>/` (created in Step 0); all paths below are relative to it.
+
+| Phase    | Execution                                                             | Primary artifact                                                 | Detailed flow                 |
+| -------- | --------------------------------------------------------------------- | ---------------------------------------------------------------- | ----------------------------- |
+| init     | Bash                                                                  | `hyperframes.json`                                               | Step 0                        |
+| plan     | subagent — **decide search?** + classify + asset strategy             | `shot-plan.json` (draft: category, `asset_needs` queries, brief) | `agents/director.md` (Part 1) |
+| source ◇ | Bash — media-use resolve (**skip if `asset_needs` is empty**)         | `assets/` + `assets/index.md`                                    | `phases/source/guide.md`      |
+| design   | subagent — shot design around resolved assets                         | `shot-plan.json` (final: block(s) + layout + motion + positions) | `agents/director.md` (Part 2) |
+| build    | subagent — reuse-first composition                                    | `compositions/index.html`                                        | `agents/builder.md`           |
+| verify   | Bash — `lint`, `check`, proof snapshots; repair on failure            | `snapshots/contact-sheet.jpg`                                    | Step 5                        |
+| approve  | Ask preview or render; wait for the answer                            | explicit render approval                                         | Step 6                        |
+| render   | Bash — `freecodego_design_render` (MP4, or `--format webm/mov` for overlay) | `renders/video.mp4` or transparent overlay                       | Step 6                        |
+
+`◇ source` runs only when the chosen category declares assets. Pure code/text categories (e.g. `kinetic-type`, most `charts`/`stat`) have `asset_needs: []` and skip straight from plan to design.
+
+## Categories — split by the search decision
+
+`plan`'s **first decision is: does this need a search?** That fork splits the categories into two groups; then the specific category is picked — for search-driven, **by the type of content the search returns**. Each category is one `categories/<id>/module.md` (its planning + build rules); the shared motion vocabulary lives in `references/motion-vocabulary.md` (→ `hyperframes-animation` rules/blueprints + registry blocks).
+
+**Form categories — no search; the user supplies the content:**
+
+| Category       | Intent                                                                                                         | Leans on                                                                    |
+| -------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `kinetic-type` | punchy line / quote / title, motion-first text                                                                 | `caption-*` blocks + animation rules                                        |
+| `stat`         | single hero number / count-up + ring                                                                           | `apple-money-count` / `rules/{counting-dynamic-scale, stat-bars-and-fills}` |
+| `charts`       | bar / line / pie / race / % from data                                                                          | `data-chart` block                                                          |
+| `logo-reveal`  | logo sting / brand lockup (user logo)                                                                          | `logo-outro` / `rules/svg-path-draw`                                        |
+| `lower-thirds` | name / title bars, callouts, social overlays                                                                   | `caption-*` + registry overlay blocks                                       |
+| `maps`         | geographic motion — highlight regions, connect places, zoom to a location (vector lane, or baked basemap lane) | `us-map` / `world-map` family + `bake-basemap.mjs`                          |
+
+**Search-driven categories — search first, then animate by content type** (the RWA path):
+
+| Returned content | Category       | Animation                                                      |
+| ---------------- | -------------- | -------------------------------------------------------------- |
+| webpage / link   | `webpage`      | webpage / UI animation (scroll, reveal, cursor, callouts)      |
+| news article     | `news`         | headline reveal + source card + key-fact callouts              |
+| tweet            | `tweet`        | animated tweet card                                            |
+| image / entity   | `asset-fusion` | the asset's geometry _becomes_ the chart (RWA diegetic fusion) |
+
+Build order: one at a time, coverage-first (rough is fine). `kinetic-type` ported from the prototype; the rest follow.
+
+## Prerequisites
+
+macOS Apple Silicon or Linux x64. System tools: `brew install node ffmpeg`. `the design engine self-check in the Design settings page` once. macOS GPU render: `export PRODUCER_BROWSER_GPU_MODE=hardware`.
+
+Optional keys (local fallbacks if unset) — only needed by categories that source/generate assets via media-use:
+
+| Key                                 | Used for                                                    | Fallback                        |
+| ----------------------------------- | ----------------------------------------------------------- | ------------------------------- |
+| `GEMINI_API_KEY` / `GOOGLE_API_KEY` | image generation (media-use resolve)                        | skip generate / search-only     |
+| (asset_scout / search providers)    | `webpage`/`news`/`tweet` + `asset-fusion` real-asset search | category degrades to asset-free |
+
+## Flow
+
+### Step 0 — Initialize
+
+cwd is the agent workspace root; write all artifacts under `PROJECT_DIR = videos/<project-name>/`. `<project-name>`: use the dir the user gave, else a short kebab-case name from the intent (`<subject>-motion`). Not the workspace basename or a timestamp.
+
+Only when `$PROJECT_DIR/hyperframes.json` is absent:
+
+```bash
+PROJECT_DIR="${MOTION_GRAPHICS_DIR:-videos/<project-name>}"
+mkdir -p "$(dirname "$PROJECT_DIR")"
+```
+
+`init` checks the installed skills against the latest on GitHub and updates the global set if any are out of date.
+
+**Constraints:** never `hyperframes init` in the workspace root; never nest another `hyperframes/` inside `PROJECT_DIR`; every Bash command (master + subagents) is a `(cd "$PROJECT_DIR" && ...)` subshell — never bare `cd`.
+
+### Step 1 — Plan (subagent: Director Part 1)
+
+Dispatch one subagent. prompt = full `agents/director.md` + `## Dispatch context` (`SKILL_DIR` / `PROJECT_DIR` / the user's request / `Schema: <SKILL_DIR>/references/shot-plan-ir.md`). It must:
+
+1. **Decide: does this need a search?** (the first fork)
+   - **No** → pick a **form category** (kinetic-type / stat / charts / logo-reveal / lower-thirds); content is user-supplied; `asset_needs: []`.
+   - **Yes** → emit a **search plan** into `asset_needs[]` (news / web / tweet / image; two-pole queries). The specific **search-driven category** (webpage / news / tweet / asset-fusion) is confirmed by the content type returned in Step 2, and finalized in Step 3.
+2. Write a draft `shot-plan.json` (envelope + chosen form category _or_ search intent + `asset_needs` + a one-paragraph shot brief). Schema: `references/shot-plan-ir.md`.
+
+Validation: `[ -s "$PROJECT_DIR/shot-plan.json" ] && echo ok || echo missing`.
+
+### Step 2 — Source ◇ (Bash: media-use, conditional)
+
+If `shot-plan.json.asset_needs` is non-empty, resolve assets (search / generate / fetch → frozen project-local paths + ledger). See `phases/source/guide.md` (wraps `media-use resolve`; the search-driven categories use the news/web/tweet/image search). If `asset_needs` is empty, **skip to Step 3**.
+
+```bash
+# illustrative — see phases/source/guide.md
+(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/source/resolve.mjs --plan ./shot-plan.json --out ./assets)
+```
+
+Degrade gracefully: if a search/provider is unavailable, the category falls back to asset-free (note it in `context.log`).
+
+### Step 3 — Design (subagent: Director Part 2)
+
+Dispatch a subagent (prompt = `agents/director.md` Part 2 + dispatch context including the resolved `assets/index.md` if Step 2 ran + `catalog-map.md`). It designs the shot **around the available assets**: pick the catalog block(s) + the `hyperframes-animation` rules/blueprints, the layout, the motion, beats, and (for `asset-fusion`) the `element_positions` + eyedropper palette. Finalizes `shot-plan.json` (`content.block` + `content.customize` + per-category content).
+
+### Step 4 — Build (subagent: Builder, reuse-first)
+
+Dispatch a subagent. prompt = full `agents/builder.md` + dispatch context (`shot-plan.json`, `catalog-map.md`, the category's `module.md`, `references/motion-vocabulary.md`, `references/builder-contract.md`). This plugin ships no hosted block registry, so the effect is built from the local materials this skill carries.
+
+### Step 5 — Verify (Bash → repair subagent on failure)
+
+```bash
+(cd "$PROJECT_DIR" && freecodego_design_lint .)
+(cd "$PROJECT_DIR" && freecodego_design_lint .)
+(cd "$PROJECT_DIR" && freecodego_design_snapshot
+```
+
+Choose proof times that show the opening state, signature move, and final hold. Inspect the generated contact or snapshot sheet before continuing. On `lint`, `check`, or snapshot failure, dispatch the repair subagent (`agents/finalize.md`) for one in-place fix pass, then rerun the failed gate. Never change a fixed duration merely to hide a defect.
+
+### Step 6 — Approve and render (Bash)
+
+Ask one question: “preview first, or render?” If the user chooses preview, open Studio and return to the same approval gate after revisions:
+
+```bash
+(cd "$PROJECT_DIR" && freecodego_design_preview)
+```
+
+Render only after an explicit render answer:
+
+```bash
+(cd "$PROJECT_DIR" && freecodego_design_render . --skill=motion-graphics -q high -o ./renders/video.mp4)
+# transparent overlay variant: --format webm  (or mov)
+```
+
+Verify the output exists, is non-empty, and has the intended duration. The final handoff names the artifact, actual duration, composition or frame id, proof times, and the inspected contact or snapshot sheet. Flags live in `/hyperframes-cli` → `references/preview-render.md`.
+
+## Resume table
+
+| State                                                    | Continue from              |
+| -------------------------------------------------------- | -------------------------- |
+| no `shot-plan.json`                                      | Step 1 (plan)              |
+| `shot-plan.json` has `asset_needs`, no `assets/`         | Step 2 (source)            |
+| `shot-plan.json` final, no `compositions/index.html`     | Step 3/4 (design+build)    |
+| `compositions/index.html` exists, proof snapshots absent | Step 5 (verify)            |
+| checks and proof snapshots pass, no approved render      | Step 6 (approval)          |
+| approved render exists                                   | verify output, then report |
+
+## Design notes (maintainers — execution does not read this)
+
+- **Asset-first rationale:** sourcing is front-loaded and informs shot design (the RWA flow: analyze → search → review → compose). the search-driven categories (`webpage`/`news`/`tweet`) and `asset-fusion` both lean on media-use search (news/web/tweet/image), which is media-use's documented RWA lineage.
+- **Reuse-first:** the in-ecosystem analog of LLM-generated templates is "compose catalog blocks + `hyperframes-animation` rules". HF's paused GSAP timeline ≙ Remotion's `useCurrentFrame`.
+- **Category module contract:** one `categories/<id>/module.md` (planning + build), sharing `references/motion-vocabulary.md` (+ optional eval). Adding a category = drop the folder + register its classifier line in `agents/director.md` + its row in `catalog-map.md`; the phase pipeline is untouched.
+- **Directory shape:**
+  ```
+  videos/<project-name>/
+    hyperframes.json  context.log
+    shot-plan.json            # the IR (Director output)
+    assets/  assets/index.md  # media-use output (if sourced)
+    compositions/index.html   # Builder output
+    renders/video.mp4
+  ```
+- **Registration:** in `hyperframes` router — add the "design-led short motion graphic" intent + Workflow description; carve the motion-graphics triggers out of `/general-video`; add reverse Do-NOT-use edges. See `motion-graphics-genre.md` §5-7.