takomi 2.1.45 → 2.5.4

package/assets/.agent/skills/hyperframes-registry/references/wiring-blocks.md

@@ -1,61 +1,61 @@
-# Wiring Blocks
-
-Blocks are standalone compositions with their own `data-composition-id`, dimensions, duration, and GSAP timeline. Include them in a host composition using `data-composition-src` on a `<div>`.
-
-## Basic wiring
-
-After `hyperframes add data-chart`, wire it into your `index.html`:
-
-```html
-<div id="stage" data-composition-id="main" data-width="1920" data-height="1080" data-duration="20">
-  <video id="a-roll" src="video.mp4" data-start="0" data-duration="20" data-track-index="0"></video>
-
-  <!-- Block: appears at 2s, plays for 15s, on layer 1 -->
-  <div
-    data-composition-id="data-chart"
-    data-composition-src="compositions/data-chart.html"
-    data-start="2"
-    data-duration="15"
-    data-track-index="1"
-    data-width="1920"
-    data-height="1080"
-  ></div>
-</div>
-```
-
-## Required attributes
-
-| Attribute              | Description                                                          |
-| ---------------------- | -------------------------------------------------------------------- |
-| `data-composition-src` | Path to the block HTML file (relative to index.html)                 |
-| `data-composition-id`  | Unique ID matching the block's internal composition ID               |
-| `data-start`           | When the block appears in the host timeline (seconds)                |
-| `data-duration`        | How long the block plays (seconds, at most the block's own duration) |
-| `data-track-index`     | Layer ordering — higher numbers render in front                      |
-| `data-width`           | Block canvas width (match the block's dimensions)                    |
-| `data-height`          | Block canvas height (match the block's dimensions)                   |
-
-## Timeline coordination
-
-The block's internal GSAP timeline runs independently from the host timeline. The HyperFrames runtime loads the sub-composition, finds its `window.__timelines` registration, and seeks the block in sync with the host, offset by `data-start`. You do NOT need to reference the block's timeline in your host's GSAP code.
-
-## Positioning blocks
-
-To position a block in a specific area of the screen, add CSS:
-
-```html
-<div
-  data-composition-id="data-chart"
-  data-composition-src="compositions/data-chart.html"
-  data-start="2"
-  data-duration="15"
-  data-track-index="1"
-  data-width="1920"
-  data-height="1080"
-  style="position: absolute; right: 0; top: 0; width: 40%; height: 100%;"
-></div>
-```
-
-## Multiple blocks
-
-Add additional `<div data-composition-src="...">` siblings with non-overlapping or overlapping `data-start` values — each block's timeline is independent and seeked in sync by the runtime.
+# Wiring Blocks
+
+Blocks are standalone compositions with their own `data-composition-id`, dimensions, duration, and GSAP timeline. Include them in a host composition using `data-composition-src` on a `<div>`.
+
+## Basic wiring
+
+After `hyperframes add data-chart`, wire it into your `index.html`:
+
+```html
+<div id="stage" data-composition-id="main" data-width="1920" data-height="1080" data-duration="20">
+  <video id="a-roll" src="video.mp4" data-start="0" data-duration="20" data-track-index="0"></video>
+
+  <!-- Block: appears at 2s, plays for 15s, on layer 1 -->
+  <div
+    data-composition-id="data-chart"
+    data-composition-src="compositions/data-chart.html"
+    data-start="2"
+    data-duration="15"
+    data-track-index="1"
+    data-width="1920"
+    data-height="1080"
+  ></div>
+</div>
+```
+
+## Required attributes
+
+| Attribute              | Description                                                          |
+| ---------------------- | -------------------------------------------------------------------- |
+| `data-composition-src` | Path to the block HTML file (relative to index.html)                 |
+| `data-composition-id`  | Unique ID matching the block's internal composition ID               |
+| `data-start`           | When the block appears in the host timeline (seconds)                |
+| `data-duration`        | How long the block plays (seconds, at most the block's own duration) |
+| `data-track-index`     | Layer ordering — higher numbers render in front                      |
+| `data-width`           | Block canvas width (match the block's dimensions)                    |
+| `data-height`          | Block canvas height (match the block's dimensions)                   |
+
+## Timeline coordination
+
+The block's internal GSAP timeline runs independently from the host timeline. The HyperFrames runtime loads the sub-composition, finds its `window.__timelines` registration, and seeks the block in sync with the host, offset by `data-start`. You do NOT need to reference the block's timeline in your host's GSAP code.
+
+## Positioning blocks
+
+To position a block in a specific area of the screen, add CSS:
+
+```html
+<div
+  data-composition-id="data-chart"
+  data-composition-src="compositions/data-chart.html"
+  data-start="2"
+  data-duration="15"
+  data-track-index="1"
+  data-width="1920"
+  data-height="1080"
+  style="position: absolute; right: 0; top: 0; width: 40%; height: 100%;"
+></div>
+```
+
+## Multiple blocks
+
+Add additional `<div data-composition-src="...">` siblings with non-overlapping or overlapping `data-start` values — each block's timeline is independent and seeked in sync by the runtime.

package/assets/.agent/skills/hyperframes-registry/references/wiring-components.md

@@ -1,39 +1,39 @@
-# Wiring Components
-
-Components are effect snippets — HTML, CSS, and optionally JS that you merge directly into an existing composition. Unlike blocks, components have no standalone timeline; they participate in the host composition's timeline.
-
-## General process
-
-1. Run `hyperframes add <component-name>`
-2. Open the installed file (e.g., `compositions/components/grain-overlay.html`)
-3. Read the comment header for usage instructions
-4. Copy the parts into your host composition:
-   - **HTML elements** — inside your `<div data-composition-id="...">`
-   - **CSS styles** — into your composition's `<style>` block
-   - **JS setup** — into your composition's `<script>`, before your timeline code
-   - **Timeline calls** — into your GSAP timeline (if the component exposes them)
-
-## Example: grain-overlay (CSS-only, no timeline integration)
-
-```html
-<!-- Paste the overlay div into your composition -->
-<div
-  id="grain-overlay"
-  style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none; z-index: 100;"
->
-  <div class="grain-texture"></div>
-</div>
-```
-
-Then paste the CSS keyframes and `.grain-texture` rule into your styles. No GSAP timeline calls needed — the grain animates via CSS `@keyframes`.
-
-## Example: shimmer-sweep (needs timeline integration)
-
-See `examples/add-component.md` for the full shimmer-sweep walkthrough (HTML wrapping, CSS, JS setup, and timeline call).
-
-## Key principles
-
-- Components inherit the host composition's dimensions and duration
-- Place component HTML at the appropriate z-index relative to your content
-- Read the comment header in each snippet for customizable values
-- Run `hyperframes lint` after wiring to catch structural issues
+# Wiring Components
+
+Components are effect snippets — HTML, CSS, and optionally JS that you merge directly into an existing composition. Unlike blocks, components have no standalone timeline; they participate in the host composition's timeline.
+
+## General process
+
+1. Run `hyperframes add <component-name>`
+2. Open the installed file (e.g., `compositions/components/grain-overlay.html`)
+3. Read the comment header for usage instructions
+4. Copy the parts into your host composition:
+   - **HTML elements** — inside your `<div data-composition-id="...">`
+   - **CSS styles** — into your composition's `<style>` block
+   - **JS setup** — into your composition's `<script>`, before your timeline code
+   - **Timeline calls** — into your GSAP timeline (if the component exposes them)
+
+## Example: grain-overlay (CSS-only, no timeline integration)
+
+```html
+<!-- Paste the overlay div into your composition -->
+<div
+  id="grain-overlay"
+  style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; pointer-events: none; z-index: 100;"
+>
+  <div class="grain-texture"></div>
+</div>
+```
+
+Then paste the CSS keyframes and `.grain-texture` rule into your styles. No GSAP timeline calls needed — the grain animates via CSS `@keyframes`.
+
+## Example: shimmer-sweep (needs timeline integration)
+
+See `examples/add-component.md` for the full shimmer-sweep walkthrough (HTML wrapping, CSS, JS setup, and timeline call).
+
+## Key principles
+
+- Components inherit the host composition's dimensions and duration
+- Place component HTML at the appropriate z-index relative to your content
+- Read the comment header in each snippet for customizable values
+- Run `hyperframes lint` after wiring to catch structural issues

package/assets/.agent/skills/media-use/SKILL.md

@@ -1,124 +1,124 @@
----
-name: media-use
-description: Agent Media OS — resolve any media need (BGM, SFX, image, icon) into a frozen local file + ledger record. One verb (`resolve`) handles the full cascade — project cache, global cache, HeyGen catalog search, freeze, register. Keeps search noise on disk, hands the agent a path. Use when a composition needs background music, sound effects, images, or icons.
----
-
-# media-use
-
-Resolve media needs into frozen local files. One verb, four types, zero context noise.
-
-## When to use
-
-Call `resolve` whenever a composition needs media — background music, sound effects, images, or icons. media-use searches the HeyGen catalog, downloads the best match, freezes it locally, and registers it in a manifest. The agent gets back one line; all search noise stays on disk.
-
-## Resolve
-
-```bash
-node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
-```
-
-Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
-
-### Types
-
-| Type    | What it finds       | Provider                                 |
-| ------- | ------------------- | ---------------------------------------- |
-| `bgm`   | Background music    | HeyGen audio catalog (10k+ tracks)       |
-| `sfx`   | Sound effects       | Bundled 19-file library + HeyGen catalog |
-| `image` | Photos, backgrounds | HeyGen asset search (75k+ vectors)       |
-| `icon`  | Icons, logos        | HeyGen asset search (type=icon)          |
-
-### Examples
-
-```bash
-# Background music
-node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
-# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
-
-# Sound effect
-node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
-# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
-
-# Image
-node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
-# → resolved image_001 → .media/images/image_001.jpg (image)
-
-# Icon
-node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
-# → resolved icon_001 → .media/images/icon_001.png (icon, transparent)
-```
-
-### Flags
-
-| Flag            | Description                                |
-| --------------- | ------------------------------------------ |
-| `--type, -t`    | Media type: bgm, sfx, image, icon          |
-| `--intent, -i`  | What you need (natural language)           |
-| `--entity, -e`  | Entity name for cache matching (optional)  |
-| `--project, -p` | Project directory (default: .)             |
-| `--adopt`       | Bulk-import existing assets/ into manifest |
-| `--json`        | Output JSON instead of one-line result     |
-
-## How it works
-
-1. Check project `.media/manifest.jsonl` for exact-prompt match
-2. Scan existing `assets/` directory for unregistered files matching the need
-3. Check global cache `~/.media/` for reusable asset
-4. Search via provider (HeyGen audio catalog, HeyGen asset search)
-5. Freeze file to `.media/<type>/`, register in manifest, regenerate `index.md`
-
-The agent gets back **one line**. Candidates, scores, provenance stay on disk.
-
-## Adopt existing projects
-
-Most HyperFrames projects already have assets in `assets/`. media-use adopts them:
-
-```bash
-node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
-# → adopted 9 assets from assets/
-#   bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
-#   image_001 → assets/images/avatar.jpg (image, 400×400)
-```
-
-`ffprobe` extracts real duration and dimensions. During resolve, unregistered files in `assets/` matching the intent are adopted on the fly.
-
-## Reading the inventory
-
-After resolve or adopt, read `.media/index.md` for the full inventory:
-
-```
-# .media · 4 assets
-
-id         type   dur   dims       path                          description
-bgm_001    bgm    25s   —          .media/audio/bgm/bgm_001.mp3  upbeat tech launch
-sfx_001    sfx    0.6s  —          .media/audio/sfx/sfx_001.mp3  whoosh
-image_001  image  —     1920×1080  .media/images/image_001.jpg   gradient tech background
-icon_001   icon   —     200×200    .media/images/icon_001.png    rocket
-```
-
-## Cross-project reuse
-
-Assets are cached automatically on resolve. Subsequent resolves for the same prompt hit the global cache at `~/.media/` — no re-download, no provider call. Promote an asset explicitly with `organize --promote <id>` to make it reusable across all projects.
-
-## Files
-
-- `.media/manifest.jsonl` — machine SSOT, one JSON record per line
-- `.media/index.md` — agent-readable table (id, type, dur, dims, path, description)
-- `~/.media/` — global cross-project reuse cache (content-addressed, SHA-256)
-
-## CLI tools used
-
-| Tool      | Purpose                                    | Required?     |
-| --------- | ------------------------------------------ | ------------- |
-| `ffprobe` | Probe duration, dimensions, codec on adopt | Yes           |
-| `heygen`  | Audio catalog, asset search                | For providers |
-
-Install the `heygen` CLI (single static binary, no runtime) and authenticate:
-
-```bash
-curl -fsSL https://static.heygen.ai/cli/install.sh | bash   # installs latest to ~/.local/bin
-heygen update                                               # if already installed: needs >= v0.1.6
-export HEYGEN_API_KEY=<your-key>                            # or: heygen auth login --key <key>
-```
-
-Requires **heygen >= v0.1.6** — the providers tag requests with the allowlisted `--headers 'X-HeyGen-Client-Source: media-use'` flag, added in v0.1.6. `asset search` is a pre-launch command hidden from `heygen --help`, but it runs. Without a `heygen` on PATH (or a valid key) the providers print a one-line diagnostic to stderr and resolve falls through to "no provider could resolve".
+---
+name: media-use
+description: Agent Media OS — resolve any media need (BGM, SFX, image, icon) into a frozen local file + ledger record. One verb (`resolve`) handles the full cascade — project cache, global cache, HeyGen catalog search, freeze, register. Keeps search noise on disk, hands the agent a path. Use when a composition needs background music, sound effects, images, or icons.
+---
+
+# media-use
+
+Resolve media needs into frozen local files. One verb, four types, zero context noise.
+
+## When to use
+
+Call `resolve` whenever a composition needs media — background music, sound effects, images, or icons. media-use searches the HeyGen catalog, downloads the best match, freezes it locally, and registers it in a manifest. The agent gets back one line; all search noise stays on disk.
+
+## Resolve
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --type <type> --intent "<description>" --project <dir>
+```
+
+Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
+
+### Types
+
+| Type    | What it finds       | Provider                                 |
+| ------- | ------------------- | ---------------------------------------- |
+| `bgm`   | Background music    | HeyGen audio catalog (10k+ tracks)       |
+| `sfx`   | Sound effects       | Bundled 19-file library + HeyGen catalog |
+| `image` | Photos, backgrounds | HeyGen asset search (75k+ vectors)       |
+| `icon`  | Icons, logos        | HeyGen asset search (type=icon)          |
+
+### Examples
+
+```bash
+# Background music
+node <SKILL_DIR>/scripts/resolve.mjs --type bgm --intent "upbeat tech launch" --project .
+# → resolved bgm_001 → .media/audio/bgm/bgm_001.mp3 (bgm, 25s)
+
+# Sound effect
+node <SKILL_DIR>/scripts/resolve.mjs --type sfx --intent "whoosh" --project .
+# → resolved sfx_001 → .media/audio/sfx/sfx_001.mp3 (sfx, 0.57s)
+
+# Image
+node <SKILL_DIR>/scripts/resolve.mjs --type image --intent "gradient tech background" --project .
+# → resolved image_001 → .media/images/image_001.jpg (image)
+
+# Icon
+node <SKILL_DIR>/scripts/resolve.mjs --type icon --intent "rocket" --project .
+# → resolved icon_001 → .media/images/icon_001.png (icon, transparent)
+```
+
+### Flags
+
+| Flag            | Description                                |
+| --------------- | ------------------------------------------ |
+| `--type, -t`    | Media type: bgm, sfx, image, icon          |
+| `--intent, -i`  | What you need (natural language)           |
+| `--entity, -e`  | Entity name for cache matching (optional)  |
+| `--project, -p` | Project directory (default: .)             |
+| `--adopt`       | Bulk-import existing assets/ into manifest |
+| `--json`        | Output JSON instead of one-line result     |
+
+## How it works
+
+1. Check project `.media/manifest.jsonl` for exact-prompt match
+2. Scan existing `assets/` directory for unregistered files matching the need
+3. Check global cache `~/.media/` for reusable asset
+4. Search via provider (HeyGen audio catalog, HeyGen asset search)
+5. Freeze file to `.media/<type>/`, register in manifest, regenerate `index.md`
+
+The agent gets back **one line**. Candidates, scores, provenance stay on disk.
+
+## Adopt existing projects
+
+Most HyperFrames projects already have assets in `assets/`. media-use adopts them:
+
+```bash
+node <SKILL_DIR>/scripts/resolve.mjs --adopt --project .
+# → adopted 9 assets from assets/
+#   bgm_001 → assets/bgm/mango-fizz.mp3 (bgm, 146.6s)
+#   image_001 → assets/images/avatar.jpg (image, 400×400)
+```
+
+`ffprobe` extracts real duration and dimensions. During resolve, unregistered files in `assets/` matching the intent are adopted on the fly.
+
+## Reading the inventory
+
+After resolve or adopt, read `.media/index.md` for the full inventory:
+
+```
+# .media · 4 assets
+
+id         type   dur   dims       path                          description
+bgm_001    bgm    25s   —          .media/audio/bgm/bgm_001.mp3  upbeat tech launch
+sfx_001    sfx    0.6s  —          .media/audio/sfx/sfx_001.mp3  whoosh
+image_001  image  —     1920×1080  .media/images/image_001.jpg   gradient tech background
+icon_001   icon   —     200×200    .media/images/icon_001.png    rocket
+```
+
+## Cross-project reuse
+
+Assets are cached automatically on resolve. Subsequent resolves for the same prompt hit the global cache at `~/.media/` — no re-download, no provider call. Promote an asset explicitly with `organize --promote <id>` to make it reusable across all projects.
+
+## Files
+
+- `.media/manifest.jsonl` — machine SSOT, one JSON record per line
+- `.media/index.md` — agent-readable table (id, type, dur, dims, path, description)
+- `~/.media/` — global cross-project reuse cache (content-addressed, SHA-256)
+
+## CLI tools used
+
+| Tool      | Purpose                                    | Required?     |
+| --------- | ------------------------------------------ | ------------- |
+| `ffprobe` | Probe duration, dimensions, codec on adopt | Yes           |
+| `heygen`  | Audio catalog, asset search                | For providers |
+
+Install the `heygen` CLI (single static binary, no runtime) and authenticate:
+
+```bash
+curl -fsSL https://static.heygen.ai/cli/install.sh | bash   # installs latest to ~/.local/bin
+heygen update                                               # if already installed: needs >= v0.1.6
+export HEYGEN_API_KEY=<your-key>                            # or: heygen auth login --key <key>
+```
+
+Requires **heygen >= v0.1.6** — the providers tag requests with the allowlisted `--headers 'X-HeyGen-Client-Source: media-use'` flag, added in v0.1.6. `asset search` is a pre-launch command hidden from `heygen --help`, but it runs. Without a `heygen` on PATH (or a valid key) the providers print a one-line diagnostic to stderr and resolve falls through to "no provider could resolve".