natureco-cli 5.18.3 → 5.19.0

package/skills/minimalist-skill/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: minimalist-ui
+description: Clean editorial-style interfaces. Warm monochrome palette, typographic contrast, flat bento grids, muted pastels. No gradients, no heavy shadows.
+---
+
+# Protocol: Premium Utilitarian Minimalism UI Architect
+
+## 1. Protocol Overview
+Name: Premium Utilitarian Minimalism & Editorial UI
+Description: An advanced frontend engineering directive for generating highly refined, ultra-minimalist, "document-style" web interfaces analogous to top-tier workspace platforms. This protocol strictly enforces a high-contrast warm monochrome palette, bespoke typographic hierarchies, meticulous structural macro-whitespace, bento-grid layouts, and an ultra-flat component architecture with deliberate muted pastel accents. It actively rejects standard generic SaaS design trends.
+
+## 2. Absolute Negative Constraints (Banned Elements)
+The AI must strictly avoid the following generic web development defaults:
+- DO NOT use the "Inter", "Roboto", or "Open Sans" typefaces.
+- DO NOT use generic, thin-line icon libraries like "Lucide", "Feather", or standard "Heroicons".
+- DO NOT use Tailwind's default heavy drop shadows (e.g., `shadow-md`, `shadow-lg`, `shadow-xl`). Shadows must be practically non-existent or heavily customized to be ultra-diffuse and low opacity (< 0.05).
+- DO NOT use primary colored backgrounds for large elements or sections (e.g., no bright blue, green, or red hero sections).
+- DO NOT use gradients, neon colors, or 3D glassmorphism (beyond subtle navbar blurs).
+- DO NOT use `rounded-full` (pill shapes) for large containers, cards, or primary buttons.
+- DO NOT use emojis anywhere in code, markup, text content, headings, or alt text. Replace with proper icons or clean SVG primitives.
+- DO NOT use generic placeholder names like "John Doe", "Acme Corp", or "Lorem Ipsum". Use realistic, contextual content.
+- DO NOT use AI copywriting clichés: "Elevate", "Seamless", "Unleash", "Next-Gen", "Game-changer", "Delve". Write plain, specific language.
+
+## 3. Typographic Architecture
+The interface must rely on extreme typographic contrast and premium font selection to establish an editorial feel.
+- Primary Sans-Serif (Body, UI, Buttons): Use clean, geometric, or system-native fonts with character. Target: `font-family: 'SF Pro Display', 'Geist Sans', 'Helvetica Neue', 'Switzer', sans-serif`.
+- Editorial Serif (Hero Headings & Quotes): Target: `font-family: 'Lyon Text', 'Newsreader', 'Playfair Display', 'Instrument Serif', serif`. Apply tight tracking (`letter-spacing: -0.02em` to `-0.04em`) and tight line-height (`1.1`).
+- Monospace (Code, Keystrokes, Meta-data): Target: `font-family: 'Geist Mono', 'SF Mono', 'JetBrains Mono', monospace`.
+- Text Colors: Body text must never be absolute black (`#000000`). Use off-black/charcoal (`#111111` or `#2F3437`) with a generous `line-height` of `1.6` for legibility. Secondary text should be muted gray (`#787774`).
+
+## 4. Color Palette (Warm Monochrome + Spot Pastels)
+Color is a scarce resource, utilized only for semantic meaning or subtle accents.
+- Canvas / Background: Pure White `#FFFFFF` or Warm Bone/Off-White `#F7F6F3` / `#FBFBFA`.
+- Primary Surface (Cards): `#FFFFFF` or `#F9F9F8`.
+- Structural Borders / Dividers: Ultra-light gray `#EAEAEA` or `rgba(0,0,0,0.06)`.
+- Accent Colors: Exclusively use highly desaturated, washed-out pastels for tags, inline code backgrounds, or subtle icon backgrounds.
+  - Pale Red: `#FDEBEC` (Text: `#9F2F2D`)
+  - Pale Blue: `#E1F3FE` (Text: `#1F6C9F`)
+  - Pale Green: `#EDF3EC` (Text: `#346538`)
+  - Pale Yellow: `#FBF3DB` (Text: `#956400`)
+
+## 5. Component Specifications
+- Bento Box Feature Grids:
+  - Utilize asymmetrical CSS Grid layouts.
+  - Cards must have exactly `border: 1px solid #EAEAEA`.
+  - Border-radius must be crisp: `8px` or `12px` maximum.
+  - Internal padding must be generous (e.g., `24px` to `40px`).
+- Primary Call-To-Action (Buttons):
+  - Solid background `#111111`, text `#FFFFFF`. 
+  - Slight border-radius (`4px` to `6px`). No box-shadow. 
+  - Hover state should be a subtle color shift to `#333333` or a micro-scale `transform: scale(0.98)`.
+- Tags & Status Badges:
+  - Pill-shaped (`border-radius: 9999px`), very small typography (`text-xs`), uppercase with wide tracking (`letter-spacing: 0.05em`).
+  - Background must use the defined Muted Pastels.
+- Accordions (FAQ):
+  - Strip all container boxes. Separate items only with a `border-bottom: 1px solid #EAEAEA`.
+  - Use a clean, sharp `+` and `-` icon for the toggle state.
+- Keystroke Micro-UIs:
+  - Render shortcuts as physical keys using `<kbd>` tags: `border: 1px solid #EAEAEA`, `border-radius: 4px`, `background: #F7F6F3`, using the Monospace font.
+- Faux-OS Window Chrome:
+  - When mocking up software, wrap it in a minimalist container with a white top bar containing three small, light gray circles (replicating macOS window controls).
+
+## 6. Iconography & Imagery Directives
+- System Icons: Use "Phosphor Icons (Bold or Fill weights)" or "Radix UI Icons" for a technical, slightly thicker-stroke aesthetic. Standardize stroke width across all icons.
+- Illustrations: Monochromatic, rough continuous-line ink sketches on a white background, featuring a single offset geometric shape filled with a muted pastel color.
+- Photography: Use high-quality, desaturated images with a warm tone. Apply subtle overlays (`opacity: 0.04` warm grain) to blend photos into the monochrome palette. Never use oversaturated stock photos. Use reliable placeholders like `https://picsum.photos/seed/{context}/1200/800` when real assets are unavailable.
+- Hero & Section Backgrounds: Sections should not feel empty and flat. Use subtle full-width background imagery at very low opacity, soft radial light spots (`radial-gradient` with warm tones at `opacity: 0.03`), or minimal geometric line patterns to add depth without breaking the clean aesthetic.
+
+## 7. Subtle Motion & Micro-Animations
+Motion should feel invisible — present but never distracting. The goal is quiet sophistication, not spectacle.
+- Scroll Entry: Elements fade in gently as they enter the viewport. Use `translateY(12px)` + `opacity: 0` resolving over `600ms` with `cubic-bezier(0.16, 1, 0.3, 1)`. Use `IntersectionObserver`, never `window.addEventListener('scroll')`.
+- Hover States: Cards lift with an ultra-subtle shadow shift (`box-shadow` transitioning from `0 0 0` to `0 2px 8px rgba(0,0,0,0.04)` over `200ms`). Buttons respond with `scale(0.98)` on `:active`.
+- Staggered Reveals: Lists and grid items enter with a cascade delay (`animation-delay: calc(var(--index) * 80ms)`). Never mount everything at once.
+- Background Ambient Motion: Optional. A single, very slow-moving radial gradient blob (`animation-duration: 20s+`, `opacity: 0.02-0.04`) drifting behind hero sections. Must be applied to a `position: fixed; pointer-events: none` layer. Never on scrolling containers.
+- Performance: Animate exclusively via `transform` and `opacity`. No layout-triggering properties (`top`, `left`, `width`, `height`). Use `will-change: transform` sparingly and only on actively animating elements.
+
+## 8. Execution Protocol
+When tasked with writing frontend code (HTML, React, Tailwind, Vue) or designing a layout:
+1. Establish the macro-whitespace first. Use massive vertical padding between sections (e.g., `py-24` or `py-32` in Tailwind).
+2. Constrain the main typography content width to `max-w-4xl` or `max-w-5xl`.
+3. Apply the custom typographic hierarchy and monochromatic color variables immediately.
+4. Ensure every card, divider, and border adheres strictly to the `1px solid #EAEAEA` rule.
+5. Add scroll-entry animations to all major content blocks.
+6. Ensure sections have visual depth through imagery, ambient gradients, or subtle textures — no empty flat backgrounds.
+7. Provide code that reflects this high-end, uncluttered, editorial aesthetic natively without requiring manual adjustments.

package/skills/motion-graphics/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: motion-graphics
+description: >
+  Use when the user wants a short, design-led motion graphic where motion is the
+  message: kinetic typography, stat or number count-up, chart/data-viz hit,
+  logo sting, brand lockup, lower-third, callout, social overlay, animated
+  headline/tweet/news item, motion poster, or quick captured-page highlight.
+  Usually under 10s and up to ~30s, with no narration arc, voice-over, or
+  live-action subject. Can render to MP4 or transparent overlay. Not for longer,
+  multi-scene, narrated, or brand-reel pieces (use general-video), narrated
+  website videos (website-to-video), topic explainers
+  (faceless-explainer), product promos (product-launch-video), PR videos
+  (pr-to-video), or captions on existing footage (embedded-captions). When unsure whether it's a
+  quick motion-first piece or a longer / narrated treatment, see /hyperframes.
+metadata:
+  {
+    "tags": "orchestrator, motion-graphics, kinetic-type, data-viz, logo-reveal, lower-thirds, news, tweet, webpage, asset-fusion, short-form, overlay, no-narration",
+  }
+---
+
+# motion-graphics — dispatch entry
+
+> **Confirm the route before Step 0.** This skill makes a **short, design-led, unnarrated motion graphic** (motion is the message; ~under 10s, no voice-over). A **longer, multi-scene, or narrated** treatment → `/general-video`; a **narrated video of a website** → `/website-to-video`; a **topic explainer** → `/faceless-explainer`; a **product promo** → `/product-launch-video`; **captions on existing footage** → `/embedded-captions`. **Out of scope**: live / at-render-time data, or footage it can't capture. Unsure motion-first-vs-narrated? **Read `/hyperframes` first.**
+
+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`           |
+| render   | Bash — `hyperframes render` (MP4, or `--format webm/mov` for overlay) | `renders/video.mp4`                                              | Step 5                        |
+| verify   | Bash — `lint` / `inspect` -> repair subagent on failure               | (fixes in place)                                                 | `agents/finalize.md`          |
+
+`◇ 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                                       |
+
+**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`. `npx hyperframes doctor` 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")"
+npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank
+```
+
+**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`). **Reuse-first**: `npx hyperframes add <block>` + customize in place; hand-author only gaps + the asset-fusion affordance. Output `compositions/index.html` honoring the HF contract (paused GSAP timeline on `window.__timelines`, `class="clip"` + stable ids, `tl.seek(0)`, deterministic).
+
+### Step 5 — Render (Bash)
+
+```bash
+(cd "$PROJECT_DIR" && npx hyperframes render . --skill=motion-graphics -q draft -o ./renders/video.mp4)
+# transparent overlay variant: --format webm  (or mov)
+```
+
+### Step 6 — Verify (Bash → repair subagent on failure)
+
+```bash
+(cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes inspect .)
+```
+
+exit 0 → done. On lint/inspect errors, dispatch the repair subagent (`agents/finalize.md`: snapshot QA + one in-place fix pass + re-render). Never change a fixed duration in repair.
+
+### Report + optional preview
+
+Report the final output (`renders/video.mp4`, or the `.webm` / `.mov` overlay variant) + duration. **Don't open a preview during the run.** Offer one only on request, started **after** render so it serves the final file:
+
+```bash
+(cd "$PROJECT_DIR" && npx hyperframes preview)   # Studio UI; or `npx hyperframes play` for a shareable link
+```
+
+Flags live in the `hyperframes-cli` skill (`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, no `renders/video.mp4` | Step 5 (render) + Step 6 |
+| `renders/video.mp4` exists                               | Report + stop            |
+
+## 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.

package/skills/music-to-video/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: music-to-video
+description: "Use when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting. The music drives everything: one analyzer reads it once, the orchestrator lays out the frames and fills a per-frame plan, and one sub-agent builds each frame. Typography and templates are the floor — a complete video needs zero assets — but any images or videos the user supplies are cut into the frames on the same beat grid (beat-cut / ken-burns). The genre (lyric video, slideshow, kinetic promo) falls out of the per-frame choices; the pipeline never branches on it."
+---
+
+# music-to-video — one music-grounded, beat-synced video workflow
+
+Use this skill to turn a **music track** into a beat-synced HyperFrames video. You analyze the track once, lay out the frames, fill in a per-frame plan, and build each frame as a composition. The input is a music track plus optional user images or videos — there is **no narration and no website capture**. Typography and templates are the floor (a complete video needs zero assets); any media the user supplies is cut in on the same beat grid.
+
+You are the **orchestrator**. Work in `videos/<project>/`. Run the steps in order and pass each **Gate** before moving on. Two steps need the user: **Step 3** (plan approval) and **Step 6** (render approval). Do every step yourself except **Step 4**, where you dispatch **one sub-agent per frame**. Keep design and motion rules out of this file — they live in `references/` and the `frame-worker` sub-agent.
+
+`SKILL_DIR` = this skill directory. `PROJECT_DIR` = `videos/<project-name>/`.
+
+Workflow: Step 0 setup → `hyperframes.json` + `assets/bgm.mp3`; Step 1 analyze → `audiomap.json`; Step 2 skeleton → `STORYBOARD.md` (frames, groups `TBD`); Step 3 plan → complete `STORYBOARD.md` + `frame.md`; Step 4 build → `compositions/frames/NN-*.html`; Step 5 assemble → `index.html`; Step 6 render → `renders/video.mp4`.
+
+## Two ideas that shape everything
+
+- **One analyzer, and you trust it.** `analyze-beatgrid.py` is the only beat analyzer — never re-measure beats with another tool or by ear. Its energy / density / rolls / onsets / silences are always reliable. Its `bpm` and `beats_sec` are reliable **only when the music is genuinely rhythmic**; on calm music the grid is a metronome the tracker imposed, so pace by phrases and energy instead and never hard-cut to it. Deciding which case you're in is each frame's `pacing` (Step 2).
+- **One frame = one file; groups live inside.** Step 2 cuts the track into **frames**, and each frame becomes one composition file `compositions/frames/NN-<frame_id>.html`, built by one frame-worker. A frame can subdivide into **groups** (each a template or a motion-primitives combo). Extra density goes _inside_ a group, so **frame count tracks distinct treatments, not beats** — a fast track does not blow up the number of sub-agents.
+
+---
+
+## Step 0: Setup, BGM, and inputs
+
+Goal: Establish the music source, create the HyperFrames project, and note any user-supplied media.
+
+The **music is the spine** — establish one track before anything else. This skill is tuned for **fast, high-energy BGM**: a strong beat grid drives the cuts (calm tracks work, but pace by phrase rather than beat). If the user gave you audio — a music file, or a video to pull the audio from — use it. If not, generate one: choose the mood from the user's description (e.g. "driving synthwave", "trap beat", "upbeat corporate") and produce a track via `/hyperframes-media` (`references/bgm.md` — HeyGen retrieval when credentialed, else local Lyria / MusicGen; ElevenLabs or another generator also works). Before generating, run `npx hyperframes auth status` and **relay its output verbatim (don't paraphrase or rewrite it)** — it shows whether BGM comes from HeyGen or local MusicGen and, if not signed in, how to sign in. **If not signed in, STOP and wait for the user to choose — sign in, or continue offline with local MusicGen — before generating the track**; don't write keys into a per-repo `.env`. (In autonomous mode, note the status and continue offline.) See `/hyperframes-media` → Preflight for the canonical guidance. Either way the track lands at `assets/bgm.mp3`. Stage any user-supplied images or videos so frames can weave them in on the beat grid; otherwise typography carries the whole video.
+
+Initialize only if `hyperframes.json` is missing. Name `<project>` from the brief in kebab-case, such as `midnight-drive-loop` — never a timestamp.
+
+```bash
+npx hyperframes init "videos/<project>" --non-interactive --skip-skills --example=blank
+mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
+cp "<user-music>" "$PROJECT_DIR/assets/bgm.mp3"   # extract from a video first if needed
+# only if the user gave you images/videos:
+node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --hyperframes "$PROJECT_DIR" --into public
+```
+
+The **brand** (font + palette) is chosen at Step 3, not here. Don't pick a genre or a track type up front — assets are just an optional ingredient, and the genre emerges from the per-frame choices.
+
+**Gate:** `hyperframes.json` + `assets/bgm.mp3` exist; aspect / length / fps and (if any) the asset inventory are noted.
+
+---
+
+## Step 1: Analyze the music
+
+Goal: Produce the one canonical timing analysis the whole video is built on.
+
+`analyze-beatgrid.py` is the **only** beat analyzer — never re-measure beats with another tool or by ear. It reads the track once and writes `audiomap.json`: energy phases (level / density / feel), onsets + `onset_rate`, rolls, silences, `hard_stops`, `key_moments`, phrases, tempo / grid, and `audio.duration_sec`. It's deterministic — the same file always gives the same map. Most fields are reliable on any music; `bpm` and `beats_sec` are reliable only when the music is genuinely rhythmic, and judging that is the call you make at Step 2.
+
+Prerequisites: Python 3 with `librosa`, `numpy`, and `soundfile` available. If import fails, install them into the active Python environment before running the analyzer:
+
+```bash
+python3 -m pip install librosa numpy soundfile
+```
+
+```bash
+python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" \
+  -o "$PROJECT_DIR/audiomap.json" --print
+```
+
+**Gate:** `audiomap.json` exists; `audio.duration_sec` is known.
+
+---
+
+## Step 2: Frame skeleton (structure only)
+
+Goal: Read the music and lay out the frames — the skeleton of `STORYBOARD.md`.
+
+Read [`references/frame-skeleton.md`](references/frame-skeleton.md). Turn `audiomap.json` into the **skeleton** of `STORYBOARD.md` yourself — there is no intermediate JSON. Cut the track into **frames** at real musical changes (`hard_stops`, SURGE / DROP `key_moments`, the edges of a roll, a stretch with no onsets, a big energy jump), snapping every boundary to an audiomap anchor. For each frame set `span_sec`, `pacing` (the verdict from Step 1's trust call — `beat_cut` when the grid is real, `phrase_flow` when it's a metronome imposed on calm music), `mood`, and a one-line `feel` (the plain music situation Step 3 matches a template against). Only classify and lay out here: leave every frame's `### Groups` as `TBD (Step 3)` and the frontmatter `style` blank — no templates, copy, color, or fonts. Expect ~1–6 frames.
+
+**Gate:** frames tile the track (first at 0, last at `duration_s`); each carries `span_sec` + `pacing` + `mood` + `feel`; every `### Groups` is `TBD`; no content anywhere.
+
+---
+
+## Step 3: Fill the plan (user-gated)
+
+Goal: Turn the skeleton into an approved, complete `STORYBOARD.md`.
+
+Read [`references/planning.md`](references/planning.md), [`storyboard-format.md`](references/storyboard-format.md), [`template-catalog.md`](references/template-catalog.md), [`motion-primitive-catalog.md`](references/motion-primitive-catalog.md), and [`montage.md`](references/montage.md) (only if the user supplied assets). Editing the same file in place, do two things:
+
+1. **Pick the brand.** Choose one preset from `../hyperframes-creative/frame-presets/` using the table in `../hyperframes-creative/references/design-spec.md` (match the track's mood; **only its fonts and colors matter** — templates own composition). Copy it into `frame.md` **unmodified** and fill the frontmatter `style` (font + a ≤4–6 swatch palette) from it.
+2. **Fill every frame.** Decide its groups and give each a treatment: a matched template from the catalog (with bound params and real audiomap anchors), a free-compose from the primitive catalog, or an asset treatment that **obeys `pacing`**. Write the copy. You own WHAT (template / primitives + content + anchors); the frame-worker owns HOW — **never write millisecond tweens into the storyboard**.
+
+```bash
+node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
+  --audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
+```
+
+Fix every `✗` (hard errors: duration mismatch, frames not tiling the track, a missing `src`); warnings are best-effort. Then show the user a frame-by-frame summary and iterate until they approve.
+
+**Gate:** `frame.md` is a verbatim preset copy; `validate-plan.mjs` exits 0; the user approved the plan.
+
+---
+
+## Step 4: Build frames from the plan
+
+Goal: Build every frame as a self-contained composition file.
+
+Create `compositions/frames/`. Read [`sub-agents/frame-worker.md`](sub-agents/frame-worker.md) and `../hyperframes-core/references/subagent-dispatch.md`. Dispatch **one frame-worker per frame**, in parallel where possible (otherwise in waves). Each worker gets exactly one frame and this context:
+
+```text
+PROJECT_DIR: <abs path>
+frame_id: <NN-frame_id>              # = the frame file stem, e.g. 02-f2; the composition id
+Your block: the `## Frame N — <frame_id>` block in PROJECT_DIR/STORYBOARD.md
+audiomap: PROJECT_DIR/audiomap.json
+frame.md: PROJECT_DIR/frame.md
+Materials: for each group, <SKILL_DIR>/references/templates/<id>/index.html (templates) and
+           <SKILL_DIR>/references/motion-primitives/<id>/ (free); staged assets/ (asset groups)
+Contracts: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
+Canvas: <w>×<h>   Pacing: <beat_cut|phrase_flow>
+Write to: PROJECT_DIR/compositions/frames/<frame_id>.html
+```
+
+The worker forks the cited materials, converts every anchor to frame-local seconds (`local_t = track_t − span_sec[0]`), gates its groups with 0ms cuts, and writes one seek-safe frame file. **The worker never runs the `hyperframes` CLI** — those commands operate on the assembled project, which doesn't exist yet, so they'd report on the wrong files. The worker just writes to the contract and stops; you verify after assembly (Step 6). As each worker returns, you can confirm its file landed on disk.
+
+**Gate:** every frame has its `compositions/frames/NN-*.html` on disk.
+
+---
+
+## Step 5: Assemble
+
+Goal: Wire the built frames + BGM into the playable `index.html`.
+
+`assemble-index.mjs` is deterministic — no subagent, no judgment. It references each frame file at its cumulative `data-start`, mounts `assets/bgm.mp3` on track 11, and hard-cuts frame → frame (frames tile the track with no gaps, so there is **no transition injector**).
+
+```bash
+node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
+  --hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
+```
+
+Fix any `✗` it reports — a missing or blank frame file means that worker wrote a partial file; re-dispatch it (Step 4) and re-assemble.
+
+**Gate:** `index.html` exists; total duration == `audiomap.audio.duration_sec`.
+
+---
+
+## Step 6: Verify and render
+
+Goal: Verify the assembled video, get user approval, and render the final MP4.
+
+Run the CLI on the **assembled project** — that's the correct unit (the per-frame workers couldn't run it). `lint` checks structure, `validate` runs headless Chrome (catching JS errors and missing assets), `inspect` snapshots frames.
+
+```bash
+( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )
+```
+
+Inspect at `t=0`, each frame start, the strongest DROP / SURGE, every `hard_stops[].t`, and the final frame. On failure, make the **cheapest safe fix** yourself: edit the offending `compositions/frames/NN-*.html`. Never change duration or audio timing to hide a sync issue. Once the gates pass, pause for user review, then render only on approval:
+
+```bash
+( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
+```
+
+**Gate:** `lint` / `validate` / `inspect` passed; the user approved; `renders/video.mp4` exists with audio, duration == `audiomap.audio.duration_sec`. The final reply states the MP4 path and duration.
+
+---
+
+## Resume table
+
+| You have                   | Continue from |
+| -------------------------- | ------------- |
+| `assets/bgm.mp3` only      | Step 1        |
+| `audiomap.json`            | Step 2        |
+| `STORYBOARD.md` (skeleton) | Step 3        |
+| `STORYBOARD.md` (complete) | Step 4        |
+| all frame files            | Step 5        |
+| `index.html`               | Step 6        |
+
+## Quick Reference
+
+**Formats:** landscape `1920x1080` by default; portrait `1080x1920`; square `1080x1080`. Set the canvas once in the storyboard frontmatter (`canvas: { w, h, fps }`).
+
+**Scripts** under `scripts/`: `analyze-beatgrid.py` (the one analyzer), `validate-plan.mjs` (plan check), `assemble-index.mjs` (index assembly), `stage-assets.mjs` (stage user media), `lib/storyboard.mjs` (vendored parser). Everything else is the `hyperframes` CLI.
+
+| Read                                                                                                           | When                                                    |
+| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
+| [`references/frame-skeleton.md`](references/frame-skeleton.md)                                                 | Step 2: read the music, lay out the frames, set pacing  |
+| [`references/planning.md`](references/planning.md) · [`storyboard-format.md`](references/storyboard-format.md) | Step 3: pick the brand, fill each frame, write the plan |
+| [`references/template-catalog.md`](references/template-catalog.md)                                             | Step 3: pick a template per group                       |
+| [`references/motion-primitive-catalog.md`](references/motion-primitive-catalog.md)                             | Step 3/4: L0 recipes for free-compose                   |
+| [`references/montage.md`](references/montage.md)                                                               | Step 3/4: asset treatments (beat-cut / ken-burns)       |
+| [`sub-agents/frame-worker.md`](sub-agents/frame-worker.md)                                                     | Step 4: dispatch + build one frame                      |
+| `../hyperframes-core/references/subagent-dispatch.md`                                                          | Step 4: dispatch sub-agents safely                      |
+| `../hyperframes-creative/references/design-spec.md`                                                            | Step 3: pick the preset (the brand)                     |
+
+## Directory layout
+
+```
+music-to-video/
+  SKILL.md
+  references/   frame-skeleton.md · planning.md · storyboard-format.md
+                template-catalog.md · motion-primitive-catalog.md · montage.md
+                templates/<id>/          { index.html (+ assets/ · program.json) }  ← L1 catalog impls
+                motion-primitives/<id>/  { index.html } (+ ../assets/gsap.min.js shared by recipes) ← L0 catalog impls
+  scripts/      analyze-beatgrid.py · assemble-index.mjs · validate-plan.mjs · stage-assets.mjs · lib/storyboard.mjs
+  sub-agents/   frame-worker.md   ← the one subagent (one per frame)
+```

package/skills/node/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: node
+description: Provides domain-specific best practices for Node.js development with TypeScript, covering type stripping, async patterns, error handling, streams, modules, testing, performance, caching, logging, and more. Use when setting up Node.js projects with native TypeScript support, configuring type stripping (--experimental-strip-types), writing Node 22+ TypeScript without a build step, or when the user mentions 'native TypeScript in Node', 'strip types', 'Node 22 TypeScript', '.ts files without compilation', 'ts-node alternative', or needs guidance on error handling, graceful shutdown, flaky tests, profiling, or environment configuration in Node.js. Helps configure tsconfig.json for type stripping, set up package.json scripts, handle module resolution and import extensions, and apply robust patterns across the full Node.js stack.
+metadata:
+  tags: node, nodejs, javascript, typescript, type-stripping, backend, server
+---
+
+## When to use
+
+Use this skill whenever you are dealing with Node.js code to obtain domain-specific knowledge for building robust, performant, and maintainable Node.js applications.
+
+## TypeScript with Type Stripping
+
+When writing TypeScript for Node.js, use **type stripping** (Node.js 22.6+) instead of build tools like ts-node or tsx. Type stripping runs TypeScript directly by removing type annotations at runtime without transpilation.
+
+Key requirements for type stripping compatibility:
+- Use `import type` for type-only imports
+- Use const objects instead of enums
+- Avoid namespaces and parameter properties
+- Use `.ts` extensions in imports
+
+**Minimal example** — a valid type-stripped TypeScript file:
+
+```ts
+// greet.ts
+import type { IncomingMessage } from 'node:http';
+
+const greet = (name: string): string => `Hello, ${name}!`;
+console.log(greet('world'));
+```
+
+Run directly with:
+```bash
+node greet.ts
+```
+
+See [rules/typescript.md](rules/typescript.md) for complete configuration and examples.
+
+## Common Workflows
+
+For multi-step processes, follow these high-level sequences before consulting the relevant rule file:
+
+**Graceful shutdown**: Register signal handlers (SIGTERM/SIGINT) → stop accepting new work → drain in-flight requests → close external connections (DB, cache) → exit with appropriate code. See [rules/graceful-shutdown.md](rules/graceful-shutdown.md).
+
+**Error handling**: Define a shared error base class → classify errors (operational vs programmer) → add async boundary handlers (`process.on('unhandledRejection')`) → propagate typed errors through the call stack → log with context before responding or crashing. See [rules/error-handling.md](rules/error-handling.md).
+
+**Diagnosing flaky tests**: Isolate the test with `--test-only` → check for shared state or timer dependencies → inspect async teardown order → add retry logic as a temporary diagnostic step → fix root cause. See [rules/flaky-tests.md](rules/flaky-tests.md).
+
+**Diagnosing stuck processes/tests** (`node --test` hangs, "process did not exit", CI timeout, open handles): isolate file/test → run with explicit timeout/reporter → inspect handles via `why-is-node-running` (`SIGUSR1`) → patch deterministic teardown in resource-creation scope → rerun isolated + full suite until stable. See [rules/stuck-processes-and-tests.md](rules/stuck-processes-and-tests.md).
+
+**Profiling a slow path**: Reproduce under realistic load → capture a CPU profile with `--cpu-prof` → identify hot functions → check for stream backpressure or unnecessary serialisation → validate improvement with a benchmark. See [rules/profiling.md](rules/profiling.md) and [rules/performance.md](rules/performance.md).
+
+## High-priority activation checklist (streams + caching)
+
+When the task mentions **CSV**, **ETL**, **ingestion pipelines**, **large file processing**, **backpressure**, **repeated lookups**, or **deduplicating concurrent async calls**, explicitly apply this checklist:
+
+1. Use `await pipeline(...)` from `node:stream/promises` (prefer this over chained `.pipe()` in guidance/code).
+2. Include at least one explicit `async function*` transform when data is being transformed in-stream.
+3. Choose a cache strategy when repeated work appears:
+   - `lru-cache` for bounded in-memory reuse in a single process.
+   - `async-cache-dedupe` for async request deduplication / stale-while-revalidate behavior.
+4. Show where backpressure is handled (implicitly via `pipeline()` or explicitly via `drain`).
+
+### Integrated example pattern (CSV/ETL)
+
+For CSV/ETL-style prompts, prefer an answer structure like:
+- `createReadStream(input)`
+- `async function*` parser/transform
+- optional cached enrichment lookup (`async-cache-dedupe` or `lru-cache`)
+- `await pipeline(...)` to a writable destination
+
+Link relevant rules directly in explanations so models can retrieve details:
+- [rules/streams.md](rules/streams.md)
+- [rules/caching.md](rules/caching.md)
+
+## How to use
+
+Read individual rule files for detailed explanations and code examples:
+
+- [rules/error-handling.md](rules/error-handling.md) - Error handling patterns in Node.js
+- [rules/async-patterns.md](rules/async-patterns.md) - Async/await and Promise patterns
+- [rules/streams.md](rules/streams.md) - Working with Node.js streams
+- [rules/modules.md](rules/modules.md) - ES Modules and CommonJS patterns
+- [rules/testing.md](rules/testing.md) - Testing strategies for Node.js applications
+- [rules/flaky-tests.md](rules/flaky-tests.md) - Identifying and diagnosing flaky tests with node:test
+- [rules/stuck-processes-and-tests.md](rules/stuck-processes-and-tests.md) - Diagnosing processes that do not exit and tests that get stuck
+- [rules/node-modules-exploration.md](rules/node-modules-exploration.md) - Navigating and analyzing node_modules directories
+- [rules/performance.md](rules/performance.md) - Performance optimization techniques
+- [rules/caching.md](rules/caching.md) - Caching patterns and libraries
+- [rules/profiling.md](rules/profiling.md) - Profiling and benchmarking tools
+- [rules/logging.md](rules/logging.md) - Logging and debugging patterns
+- [rules/environment.md](rules/environment.md) - Environment configuration and secrets management
+- [rules/graceful-shutdown.md](rules/graceful-shutdown.md) - Graceful shutdown and signal handling
+- [rules/typescript.md](rules/typescript.md) - TypeScript configuration and type stripping in Node.js