natureco-cli 5.18.3 → 5.20.0

package/skills/model-deployment/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: model-deployment
+description: Deploy ML models with serving infrastructure, A/B testing, and monitoring
+category: Intelligence & General
+---
+
+# Model Deployment
+
+## Overview
+Deploy ML models with serving infrastructure, A/B testing, and monitoring. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply model deployment best practices
+- When establishing processes or standards for your workflow
+- When training team members on model deployment
+- When automating or optimizing model deployment tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply model deployment for my current project
+Assistant: I'll help you apply model deployment step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

package/skills/model-evaluation/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: model-evaluation
+description: Evaluate LLM outputs with metrics, human feedback, and automated test suites
+category: AI Agents
+---
+
+# Model Evaluation
+
+## Overview
+Evaluate LLM outputs with metrics, human feedback, and automated test suites. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply model evaluation best practices
+- When establishing processes or standards for your workflow
+- When training team members on model evaluation
+- When automating or optimizing model evaluation tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply model evaluation for my current project
+Assistant: I'll help you apply model evaluation step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

package/skills/monitoring-setup/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: monitoring-setup
+description: Set up monitoring with metrics, alerts, dashboards, and distributed tracing
+category: Software Development
+---
+
+# Monitoring Setup
+
+## Overview
+Set up monitoring with metrics, alerts, dashboards, and distributed tracing. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply monitoring setup best practices
+- When establishing processes or standards for your workflow
+- When training team members on monitoring setup
+- When automating or optimizing monitoring setup tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply monitoring setup for my current project
+Assistant: I'll help you apply monitoring setup step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

package/skills/monorepo-setup/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: monorepo-setup
+description: Set up monorepo with workspace tools, shared configs, and dependency graph awareness
+category: Software Development
+---
+
+# Monorepo Setup
+
+## Overview
+Set up monorepo with workspace tools, shared configs, and dependency graph awareness. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply monorepo setup best practices
+- When establishing processes or standards for your workflow
+- When training team members on monorepo setup
+- When automating or optimizing monorepo setup tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply monorepo setup for my current project
+Assistant: I'll help you apply monorepo setup step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

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/multi-agent-systems/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: multi-agent-systems
+description: Design multi-agent systems with specialized roles, communication, and coordination
+category: AI Agents
+---
+
+# Multi Agent Systems
+
+## Overview
+Design multi-agent systems with specialized roles, communication, and coordination. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply multi agent systems best practices
+- When establishing processes or standards for your workflow
+- When training team members on multi agent systems
+- When automating or optimizing multi agent systems tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply multi agent systems for my current project
+Assistant: I'll help you apply multi agent systems step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration

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/network-troubleshooting/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: network-troubleshooting
+description: Troubleshoot network issues with ping, traceroute, DNS checks, and packet analysis
+category: Intelligence & General
+---
+
+# Network Troubleshooting
+
+## Overview
+Troubleshoot network issues with ping, traceroute, DNS checks, and packet analysis. This skill helps you apply structured, repeatable methods for consistent results.
+
+## When to Use
+- When you need to apply network troubleshooting best practices
+- When establishing processes or standards for your workflow
+- When training team members on network troubleshooting
+- When automating or optimizing network troubleshooting tasks
+
+## Instructions
+1. **Assess**: Evaluate the current state, requirements, and constraints
+2. **Plan**: Define the approach, steps, and success criteria
+3. **Execute**: Follow the established patterns and best practices
+4. **Verify**: Check results against expected outcomes and quality standards
+5. **Iterate**: Refine based on feedback and lessons learned
+
+## Examples
+```
+User: Help me apply network troubleshooting for my current project
+Assistant: I'll help you apply network troubleshooting step by step...
+```
+
+## Related Skills
+- Use with `workflow` tool for orchestrated execution
+- Combine with `task` tool for delegated processing
+- Reference `system-prompt` for system-level integration