@ignix-social/editor 0.1.0

package/vendor/hyperframes/dist/skills/media-use/references/media-treatments.md

@@ -0,0 +1,202 @@
+# Media treatments
+
+A media treatment is a source-aware plan that composes existing HyperFrames
+color, effect, timeline, and Registry primitives. It is not a second runtime
+schema. Use this file to choose a primary direction. A matching recipe is an
+optional tested seed; bespoke requests may assemble a validated treatment from
+the canonical capability catalog.
+
+## Permission and scope
+
+- An explicit request such as "polish this", "make it look better", or "make it
+  fit the topic" delegates a conservative treatment. Apply it, verify it, and
+  report what changed.
+- During an unsolicited opportunity scan, show or suggest the treatment first.
+- Target meaningful photographic media. Skip text, SVG, logos, icons, UI
+  chrome, and intentionally stylized footage unless the user asks.
+- Realtime grading and effects apply to the entire selected real `<img>` or
+  `<video>`. They do not isolate or track a face, plate, address, or other
+  region. For region-only work, first create a separate cropped/masked media
+  layer or use an external segmentation/tracking tool; never imply that a
+  whole-media Blur or Pixelate performed region isolation.
+- The realtime treatment path is Rec.709/SDR. Do not silently process HDR, HLG,
+  PQ, or camera LOG sources through it.
+
+## Classify the request
+
+Choose the smallest lane that satisfies the request before choosing a recipe
+or assembling a custom treatment:
+
+| User intent                                         | Lane                                       |
+| --------------------------------------------------- | ------------------------------------------ |
+| too dark, flat, too warm, too many shadows          | correction                                 |
+| shape shadows/highlights or selected colors         | wheels, curves, or HSL secondary           |
+| polished, premium, warm, cinematic, fit the topic   | preset or custom treatment                 |
+| retro, print, ASCII, glitch, camcorder              | shader effect or effect-bearing preset     |
+| obscure the whole selected media                    | privacy Blur or Pixelate                   |
+| hide one face, plate, address, or screen region     | separate crop/mask/asset or external tool  |
+| draw attention to media without changing its pixels | framing, motion, or optional overlay       |
+| reveal, focus, depixelate, fade the treatment       | finite seek-safe treatment keyframes       |
+| REC HUD, light leak, flash, freeze-frame cutout     | Registry overlay plus any justified pixels |
+
+The lane identifies the primary reason for the change; it is not a one-feature
+limit. A final treatment may combine correction, a preset, finishing, multiple
+compatible shader effects, finite keyframed values, and optional overlays when
+the inspected media and user intent justify the complete combination. Keep one
+primary intent as the creative anchor so the result remains coherent and
+deterministic.
+
+Do not add a stylized Effect when correction solves the complaint. Do not
+change color when the request is only temporal, and do not install an overlay
+when the selected media alone communicates the result.
+
+Match strength to intent. When the user explicitly names a bold look such as
+VHS, glitch, ASCII, halftone, camcorder, print, or engraving, apply its
+signature effects strongly enough to read unmistakably. The guard against
+unrequested additions does not mean under-delivering an effect the user asked
+for. Correction and polish stay restrained; named stylization must be obvious
+in the after-frame.
+
+### Translate vague feedback conservatively
+
+| User feedback                         | First action                                                                                    | Add only when the frames justify it                             | Never infer                                     |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------- |
+| too many shadows and a bit boring     | lift shadows/protect highlights, then compare one restrained source-appropriate preset          | mild contrast or vibrance                                       | retro texture, HUD, or palette effect           |
+| make the product footage feel premium | protect product color and labels, compare Product Polish                                        | restrained vignette on lifestyle footage                        | a cinematic LUT or crushed blacks               |
+| make this reveal cooler               | preserve color and animate one supported effect or treatment value                              | a short owned overlay block                                     | unrelated whole-clip styling                    |
+| make it feel like an old home video   | compare 8mm and VHS language against the source                                                 | finite weave/flicker or justified HUD                           | that every old-video request means VHS          |
+| hide this face                        | explain that realtime effects are whole-media; isolate the region first or use an external tool | whole-media Blur/Pixelate only when the user accepts that scope | face tracking or masking that was not performed |
+| keep the brand colors exact           | leave UI/logo pixels unchanged; use framing and motion                                          | demonstrated exposure-only correction                           | stylized preset, palette, or LUT                |
+
+When more than one lane could fit, generate at most two candidates and choose
+from inspected before/after evidence. Ordinary correction or polish starts with
+one candidate; a second candidate is an escalation, not the default. Do not
+stack effects merely to make the answer look more sophisticated.
+
+## Seed or assemble
+
+Use the table when a tested recipe directly fits. Read only that recipe
+section. Recipes are optional macros, not a closed list of allowed results.
+
+| Intent or source                                         | Recipe heading to read                            |
+| -------------------------------------------------------- | ------------------------------------------------- |
+| Talking head, interview, presenter, people-focused photo | `Natural Portrait`                                |
+| Product footage, lifestyle footage, clean social polish  | `Product Polish`                                  |
+| Screen capture, dashboard, website, app UI               | `UI Fidelity`                                     |
+| Warm memory, restrained nostalgia                        | `Film Memory`                                     |
+| Creator/UGC handheld camera character                    | `Creator Camcorder`                               |
+| Analog tape playback                                     | `VHS Playback`                                    |
+| Small-gauge home-movie character                         | `8mm Home Movie`                                  |
+| Editorial dots or ink print                              | `Editorial Halftone` or `Two-Ink Editorial Print` |
+| Monochrome dot/line screen print                         | `Monochrome Screen Print`                         |
+| Engraved or hand-hatched illustration                    | `Engraved Illustration` or `Crosshatched Sketch`  |
+| Curved scanlined display                                 | `CRT Display`                                     |
+| Glyph-based art                                          | `Procedural ASCII`                                |
+| Realtime palette quantization                            | `Ordered Palette Dither`                          |
+| Exact historical error diffusion                         | `Cached Error Diffusion`                          |
+| Finite warm flare layer                                  | `Organic Light Leak`                              |
+| Held-frame graphic interruption                          | `Freeze-Frame Cutout`                             |
+| Short exposure-flash transition                          | `Social Flash / Editorial Reveal`                 |
+
+Use `rg -n '^## <heading>$' <SKILL_DIR>/references/media-treatment-recipes.md`,
+then read only from that heading to the next `##`. Do not load the entire
+cookbook for one request.
+
+When source intent is unclear, inspect the concise capability overview:
+
+```bash
+hyperframes media-treatment --capabilities --json
+```
+
+It lists the complete surface by family with one-line descriptions. Then load
+only the family, effect, preset, or palette relevant to the inspected source:
+
+```bash
+hyperframes media-treatment --capability <id> --json
+```
+
+The focused result provides legal controls, recommended apply values, render
+cost, palette support, and the exact animation contract when supported. Use
+`--all` only for tooling/tests or a genuinely exhaustive audit. Compose one
+nested payload from these existing parts. Recipes and catalog-built payloads
+use the same renderer and persistence contract.
+
+Treat `renderLane: "multipass"` as a cost signal. Blur, Bloom, and Kuwahara are
+bounded but more expensive than single-pass effects; avoid stacking several of
+them across many simultaneous media elements unless the composition needs it,
+then verify playback and a draft render.
+Cost follows treated pixel area as well as element count. More than two
+simultaneously visible full-frame multipass media layers requires a continuous
+playback check on the target machine; simplify or pre-render the stack if it
+drops frames. Do not impose or claim a universal hard cap from one machine.
+
+## Common workflow
+
+1. Confirm the target is a real `<img>` or `<video>` and inspect source color
+   metadata.
+2. For an image, read it once. For video, capture early/middle/late output as
+   one labeled sheet and read that one image:
+
+   ```bash
+   hyperframes snapshot <project> --frames 3 --no-end --describe false \
+     --output snapshots/treatment-before
+   ```
+
+   Read `snapshots/treatment-before/contact-sheet.jpg`; do not spend separate
+   model turns reading each frame unless the sheet exposes a specific problem.
+   Do not infer semantics from signal statistics alone.
+
+3. Choose one primary lane. Use one matching recipe as a tested seed, or read
+   the overview and one focused capability detail when the request is bespoke.
+   A seed may be changed or combined with compatible catalog controls when the
+   contact sheet justifies it. Do not invent keys, exceed reported ranges, or
+   stack effects without a visual reason. Do not run the generic grade/LUT
+   resolver first; it adds irrelevant candidates and may download an unused
+   LUT. Use `media-treatment --selector "#hero" --analyze --json` only when
+   correction needs measured signal evidence.
+4. Persist pixel settings with `hyperframes media-treatment`; it validates and
+   merges a patch into the existing nested `data-color-grading` contract. Use registered
+   GSAP only for supported animated values and Registry overlay blocks only
+   for authored dressing.
+   ```bash
+   hyperframes media-treatment --selector "<unique selector>" \
+     --grading '<nested JSON patch>' --apply --json
+   ```
+   For a temporal reveal, use the focused capability result's `animation`
+   contract. If it is `null`, the capability is static. Author the starting CSS
+   property inline on the real media element and return temporary treatment
+   values to neutral so the finished shot preserves its existing pixels.
+   Prefer that bounded media animation first; if an overlay is justified,
+   install the owned Registry block instead of recreating it with bespoke
+   overlay markup.
+   For correction and ordinary polish, keep those values as editable
+   preset/adjustment JSON; do not generate a LUT for controls the realtime shader
+   already owns.
+   Use the canonical `details`/`effects` fields for vignette, grain, blur,
+   pixelate, and related primitives. Do not duplicate them with CSS filters,
+   SVG turbulence, opacity, or decorative DOM overlays.
+5. When the treatment calls for an overlay, install that named block with
+   `hyperframes add <name> --dir <project> --no-clipboard --json`, inspect its
+   returned `data-composition-src` host, and place it once using the block's
+   timing contract. Check for the installed file and host element
+   ID before insertion; never duplicate an existing overlay block. This is one
+   treatment workflow: do not make the user discover Catalog or separately ask
+   for the recipe's justified overlay.
+6. For ordinary correction/polish, capture one after-sheet with the same three
+   timestamps under `snapshots/treatment-after`, compare it to the before-sheet,
+   and stop when the result is clearly better. Run the normal project check;
+   do not encode a draft solely to prove a static correction.
+7. Escalate only when evidence requires it. Read individual frames to diagnose a
+   specific visual problem. Preview and render moving evidence when judging
+   treatment keyframes, glitch/tape motion, overlays, playback smoothness, LUT
+   timing, or any other temporal behavior. HDR/LOG, privacy, and brand-sensitive
+   work also require the existing explicit caveats and stronger verification.
+   If the treatment is not clearly better, keep the source unchanged.
+8. Report the selected media, primary intent, recipe seed if used, final
+   composed controls, optional overlays, and the frames/render that were
+   actually checked. Do not report visual quality from command success alone.
+
+`media-treatment --analyze` provides deterministic clipping and signal
+evidence for local composition media, not subject recognition or automatic
+taste. It reports HDR/metadata caveats and a bounded primary-correction patch;
+it does not invent wheels, curves, or HSL selections from statistics.

package/vendor/hyperframes/dist/skills/media-use/references/memory.md

@@ -0,0 +1,37 @@
+# User memory — preferences and recipes
+
+## Preferences — remembered defaults
+
+The lightweight tier of user memory: confirmed brief answers (destination, aspect, language, flow, storyboard, voice, style preset) persisted on the same two-tier split as assets — project `.media/preferences.json` (committed, the team inherits it) and personal `~/.media/preferences.json`. A value earns the personal tier by being confirmed in **two different projects**, so a one-off choice never pollutes the global defaults.
+
+```bash
+node <SKILL_DIR>/scripts/prefs.mjs get --hyperframes . --json      # merged view (project overrides user)
+node <SKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key destination --value x-feed
+node <SKILL_DIR>/scripts/prefs.mjs record --hyperframes . --key style_preset --value pin-and-paper --workflow faceless-explainer
+```
+
+Only what the user actually confirmed gets recorded — never an inferred or defaulted value. How workflows consume these (a remembered value becomes the recommended default with a receipt, and never skips a question) is the brief contract's rule: `hyperframes/references/brief-contract.md` § 2, Remembered defaults.
+
+## Recipes — frozen video bundles
+
+The heavyweight tier of user memory: one approved run frozen as a named, versioned bundle — `frame.md`, the storyboard skeleton (structure kept, content blanked to per-frame fill-ins), the brief skeleton (from `BRIEF.md` when the project has one — reusable frontmatter kept, run-shape and prose blanked), and the confirmed brief values. Same two tiers: project `.media/recipes/<name>/` (committed) and `~/.media/recipes/<name>/` (a freeze is already a confirmed bundle, so it promotes immediately — no two-project rule). Re-freezing a name bumps `version` and archives the old folder as `<name>@v<N>`.
+
+```bash
+node <SKILL_DIR>/scripts/recipe.mjs freeze --hyperframes . --name weekly-promo   # workflow read from BRIEF.md (--workflow only for briefless projects)
+node <SKILL_DIR>/scripts/recipe.mjs list --hyperframes . --workflow product-launch-video
+node <SKILL_DIR>/scripts/recipe.mjs use --hyperframes . --name weekly-promo   # also: resolve.mjs --type recipe --entity weekly-promo
+```
+
+The freeze is offered once after the final approval (`hyperframes/references/review-loop.md` § 4), and the intent layer (`/hyperframes` → `references/intent-interview.md`, step 1) checks for a match before its first question. Adopting a recipe fills the brief, the design spec, and the storyboard skeleton — and unlike preferences it may skip the questions it answers: the bundle was approved as a whole, and adoption itself is the question.
+
+## Files
+
+- `.media/manifest.jsonl`: machine SSOT, one JSON record per line. Records are keyed by path and only appended, so
+  the last record for a path is the file's record; a file moved or replaced by hand keeps (or loses) its record by path.
+- `.media/index.md`: agent-readable table (id, type, dur, dims, path, description)
+- `.media/preferences.json`: the project's remembered defaults (committed)
+- `~/.media/`: global cross-project reuse cache (content-addressed, SHA-256)
+- `~/.media/preferences.json`: personal remembered defaults (promoted after two projects)
+- `.media/recipes/<name>/`: frozen video bundles — recipe.json + frame.md + storyboard skeleton (committed)
+- `~/.media/recipes/<name>/`: personal recipe tier (promoted on freeze)
+- `~/.media/misses.jsonl`: local-only resolve misses, including intent text for `--stats`

package/vendor/hyperframes/dist/skills/media-use/references/meta.md

@@ -0,0 +1,61 @@
+# Ownership matrix, usage stats, telemetry, privacy
+
+Maintainer-facing reference. Nothing here changes how you resolve or operate on media.
+
+## What it owns (the gaps HyperFrames leaves)
+
+HyperFrames owns media _playback_; media-use owns everything else. Each row is enforced by `scripts/lib/coverage.test.mjs` so the claim can't rot.
+
+| HyperFrames gap                            | media-use owns it via                                                                                                                                                                                                                                                               |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Audio-only, no image/icon                  | `resolve --type image\|icon` (heygen asset search)                                                                                                                                                                                                                                  |
+| No third-party brand logos                 | `resolve --type logo` (theSVG → GitHub org avatar → domain favicon)                                                                                                                                                                                                                 |
+| No voice / audio generation                | `resolve --type voice` (HeyGen TTS free-usage path; optional local Kokoro) + the audio engine (`audio/scripts/audio.mjs`)                                                                                                                                                           |
+| Scattered/duplicated audio engine          | one consolidated engine under `audio/` (hyperframes-media retired)                                                                                                                                                                                                                  |
+| No agent media-ops (cut/reframe/transform) | `references/operations.md` + `resolve --from` to register outputs                                                                                                                                                                                                                   |
+| No transcript-driven cutting               | `scripts/transcript-cut.mjs` compiles word-timestamp edits into cut lists                                                                                                                                                                                                           |
+| No auto-duck / publish loudness            | `scripts/audio-duck.mjs` + `references/operations.md` loudnorm/sidechain recipes                                                                                                                                                                                                    |
+| No cross-project memory                    | global content-addressed cache + auto-promote (`~/.media`)                                                                                                                                                                                                                          |
+| Grade recipes and LUT freezing             | `resolve --type grade` emits a paste-ready recipe and `resolve --type lut` freezes validated `.cube` files; direct element analysis/authoring lives in `hyperframes media-treatment`                                                                                                |
+| No image generation                        | RAM-graded local mflux (FLUX) via `scripts/lib/mflux-provider.mjs`, codex `image_gen` upsell (`scripts/lib/codex-provider.mjs`)                                                                                                                                                     |
+| No video generation                        | `resolve --type video` — HeyGen avatar video first (free-usage path, sign-in nudge on auth failure), local LTX fallback (`videogen` in `scripts/lib/local-models.mjs`); image-to-video, photo-avatar, dub/translate remain manual `heygen` CLI recipes (`references/operations.md`) |
+| Weak local-model defaults                  | HeyGen free-usage path via the `heygen` CLI; local open-source tools only as opt-in alternatives (`scripts/lib/local-run.mjs`)                                                                                                                                                      |
+
+## Usage stats
+
+Use `resolve --stats` for a local, shareable report over the current project's `.media/` manifest, the global `~/.media/` cache, and local resolve misses. Human output is compact; add `--json` for a single machine-readable object, and `--days N` to window timestamped records.
+
+```bash
+npx hyperframes media-use resolve --stats --project . --days 7
+# media-use stats
+# total resolves: 12
+# misses: 2
+# hit rate: 86%
+```
+
+## Telemetry
+
+`resolve` and the edit tools (transcribe / transcript-cut / audio-duck) send an
+anonymous usage event to PostHog (`scripts/lib/telemetry.mjs`), so we can see
+which capabilities are actually used. It records only the media TYPE, the
+resolution SOURCE, and the winning PROVIDER: never the intent text, file names,
+or paths, and `$ip:null` so no IP is stored. Best-effort and non-blocking (a
+resolve never waits on or fails from telemetry).
+
+Opt out with `DO_NOT_TRACK=1` or `HYPERFRAMES_NO_TELEMETRY=1` (also off in CI and
+dev). Same public PostHog project key and opt-outs as the `hyperframes` CLI.
+
+HeyGen request tagging: every generating `heygen` call (TTS, avatar video, catalog
+search) carries the allowlisted `X-HeyGen-Client-Source: media-use` header, sourced
+from one shared constant (`HEYGEN_CLIENT_SOURCE_ARGV` in `scripts/lib/heygen-cli.mjs`)
+so a future call site can't silently ship untagged. Read-only discovery calls
+(`voice list`, `avatar list`) are intentionally left untagged.
+
+## Privacy
+
+media-use uses the same shared install id as the `hyperframes` CLI/studio
+(`~/.hyperframes/config.json`). When you are signed in to HeyGen, usage is
+linked to your account email, or username when email is unavailable, matching
+the CLI behavior. The events stay coarse: media type, source, provider, and
+small counts only; intent text and paths stay local. Disable telemetry with
+`HYPERFRAMES_NO_TELEMETRY=1` or `DO_NOT_TRACK=1`.

package/vendor/hyperframes/dist/skills/media-use/references/operations.md

@@ -0,0 +1,327 @@
+# Media operations: agent guidance
+
+media-use resolves and remembers assets. For **operating** on them: cutting,
+reframing, stitching, transforming, it does not wrap every action as a bespoke
+command. Instead it points you at the right local tool (decision OP1). Run the
+tool, then register the output with `resolve --from <output> --type <type>` so the
+result lands in the ledger and the global cache like any other asset.
+
+All tools below are local and free. ffmpeg is assumed present (it backs the
+engine already).
+
+## Cut / trim: keep a slice
+
+```bash
+ffmpeg -i in.mp4 -ss 00:00:12 -to 00:00:20 -c copy out.mp4   # 0:12–0:20, no re-encode
+```
+
+In-composition trimming usually needs **no new file**: a clip plays a sub-window
+via `data-media-start` + `data-duration` (see hyperframes-core). Only cut a
+physical file when exporting/assembling outside the composition.
+
+## Reframe / crop: change aspect ratio
+
+```bash
+# 16:9 -> 9:16, crop centered
+ffmpeg -i in.mp4 -vf "crop=ih*9/16:ih,scale=1080:1920" out.mp4
+```
+
+For a non-destructive crop, set a `clip-path` on the element in the composition
+itself (render-time, source file untouched) instead of re-encoding with ffmpeg.
+
+## Montage / stitch: join clips
+
+```bash
+printf "file '%s'\n" a.mp4 b.mp4 c.mp4 > list.txt
+ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4
+```
+
+## Silence-cut / highlight: trim dead air, grab the best moment
+
+```bash
+auto-editor in.mp4 --edit audio:threshold=4% -o tight.mp4   # pip install auto-editor
+scenedetect -i in.mp4 detect-adaptive list-scenes           # pip install scenedetect
+```
+
+## Transforms with a quality choice (process)
+
+These have a local option AND a higher-quality HeyGen-CLI option. Run the local
+one for free/offline; use the HeyGen CLI when quality matters. Showing the user
+a **side-by-side** (local vs HeyGen) is the honest way to let them choose.
+
+| Op                 | Local (free)                                       | HeyGen CLI (quality)        |
+| ------------------ | -------------------------------------------------- | --------------------------- |
+| Background removal | `hyperframes remove-background in.png` (u2net)     | `heygen background-removal` |
+| Upscale            | `realesrgan-ncnn-vulkan -i in.png -o out.png -s 4` | n/a                         |
+| Lipsync (dub)      | n/a                                                | `heygen lipsync`            |
+| Translate          | n/a                                                | `heygen video-translate`    |
+
+After any op: `resolve --from out.ext --type <type>` to register the derived
+asset (it records provenance and auto-promotes to the global cache).
+
+> ponytail: media-use doesn't re-wrap ffmpeg/heygen here, that's deliberate
+> (OP1). The value it adds is the ledger + global reuse on the _output_, via
+> `--from`. Add a thin `process` verb only if agents repeatedly fumble these
+> recipes.
+
+## Exact error-diffusion dither
+
+Use the local processor when the requested look specifically calls for
+Floyd-Steinberg, Atkinson/Macintosh, Jarvis-Judice-Ninke, Stucki, Burkes, or a
+Sierra variant. These are sequential error-diffusion algorithms, not the
+realtime Bayer `effects.dither` shader.
+
+```bash
+node <SKILL_DIR>/scripts/dither.mjs \
+  --input source.mp4 \
+  --out source.atkinson.mp4 \
+  --algorithm atkinson \
+  --palette '#0f380f,#306230,#8bac0f,#9bbc0f' \
+  --point-size 3
+
+npx hyperframes media-use resolve \
+  --from source.atkinson.mp4 --type video --project .
+```
+
+Available algorithms: `floyd-steinberg`, `atkinson`,
+`jarvis-judice-ninke`, `stucki`, `burkes`, `sierra`, `sierra-lite`, and
+`two-row-sierra`. The default is balanced Floyd-Steinberg with a black/white
+palette. Palettes contain 2-6 `#rrggbb` colors in authored dark-to-light order;
+reversing the order intentionally inverts the mapping. `--point-size` controls
+1-20px blocks; `--brightness` and `--contrast` accept 0.5-2; `--detail` accepts
+0.1-1.
+
+The processor supports ordinary SDR images and MP4 video, preserves video
+audio, and emits BT.709 MP4. It rejects tagged PQ/HLG input rather than silently
+tone-mapping it. To animate the transformation, keep the original and processed
+files as two real media layers and use the seek-safe GSAP timeline to reveal or
+crossfade between them. Use the realtime Bayer shader instead when the dither
+amount itself must animate continuously.
+
+## Transcription (default: Parakeet, better than whisper.cpp)
+
+`transcribe.mjs` is the default local transcription path. It runs **NVIDIA
+Parakeet-TDT via parakeet-mlx**, which beats whisper.cpp on the Open ASR
+Leaderboard (avg WER ~6.05% vs 7.44%; on NOISY audio 4.73% vs 5.96%, where
+whisper-large-v3 hallucinated to 308% WER on meetings) and is 5-10x faster.
+It emits `{ text, words:[{text,start,end}] }` with word timestamps (merged from
+Parakeet's sub-word tokens), feeding transcript-cut, captions, and the audio
+engine directly.
+
+```bash
+# install once: uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx
+node <SKILL_DIR>/scripts/transcribe.mjs --input talk.mp4 --out talk.transcribe.json
+
+# the hyperframes CLI runs Parakeet on macOS, Linux and Windows once it is installed:
+npx hyperframes models install parakeet                 # once, ~640 MB, ask the user first
+npx hyperframes transcribe talk.mp4 --engine parakeet   # or --engine auto (default)
+```
+
+VERIFIED on 24GB: accurate, ~3s (cached) for 8s audio. Parakeet covers 25
+European languages, English included. For other languages, or when parakeet-mlx is not
+installed, transcribe.mjs falls back to `hyperframes transcribe`, which uses the
+CLI's Parakeet when `models install parakeet` has run and whisper.cpp (99
+languages) otherwise. `--engine parakeet|whisper` forces one. (Cohere
+Transcribe tops the leaderboard on paper but its mlx-audio quants produced
+garbage and ran 40-70x slower on a Mac in testing, so it is not wired in.)
+
+## Text-based editing (transcript cut)
+
+`transcript-cut.mjs` is a compiler, not a wrapper: it turns word timestamps and
+agent cut decisions into exact kept segments. It is provided even though the rest
+of this file is guidance-only.
+
+```bash
+node <SKILL_DIR>/scripts/transcript-cut.mjs \
+  --input talk.mp4 \
+  --transcript talk.transcribe.json \
+  --remove "12.41-15.02,88.3-91.7" \
+  --remove-fillers "um,uh,like" \
+  --cut-silence 0.8 \
+  --out talk.cut.mp4
+
+resolve --from talk.cut.mp4 --type video
+```
+
+Use `--plan` first when you want to inspect the kept segment JSON before encoding.
+
+## Ducking (declare in-composition / bake for export)
+
+B1, declare ducking in the composition. `audio-duck.mjs` emits a volume lane
+as a `data-automation` attribute. Add it to the background `<audio>` element;
+the source file stays untouched. Lane times are clip-local, so pass
+`--composition` to let the script subtract the element's `data-start`.
+
+```bash
+node <SKILL_DIR>/scripts/audio-duck.mjs \
+  --meta audio_meta.json \
+  --target "#bgm" \
+  --composition index.html
+```
+
+```html
+<!-- auto-duck: #bgm under narration; add to its <audio> element -->
+data-automation='{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":0.6},{"t":3.42,"v":0.6},{"t":3.57,"v":0.15},{"t":9.87,"v":0.15},{"t":10.27,"v":0.6}]}]}'
+```
+
+B2, bake ducking only for exported or standalone files.
+
+```bash
+ffmpeg -i bgm.mp3 -i voice.wav \
+  -filter_complex "[0][1]sidechaincompress=threshold=0.03:ratio=8:attack=200:release=400[ducked]" \
+  -map "[ducked]" bgm.ducked.wav
+```
+
+Declare inside compositions. Bake only for assets leaving the hyperframes
+pipeline.
+
+## Publish loudness
+
+Two-pass `loudnorm` measures first, then applies the measured values with the
+target LUFS baked in.
+
+Socials target, -14 LUFS:
+
+```bash
+ffmpeg -i mix.wav \
+  -af loudnorm=I=-14:TP=-1.5:LRA=11:print_format=json \
+  -f null -
+
+ffmpeg -i mix.wav \
+  -af loudnorm=I=-14:TP=-1.5:LRA=11:measured_I=<input_i>:measured_TP=<input_tp>:measured_LRA=<input_lra>:measured_thresh=<input_thresh>:offset=<target_offset>:linear=true:print_format=summary \
+  mix.social.wav
+```
+
+Podcast target, -16 LUFS:
+
+```bash
+ffmpeg -i mix.wav \
+  -af loudnorm=I=-16:TP=-1.5:LRA=11:print_format=json \
+  -f null -
+
+ffmpeg -i mix.wav \
+  -af loudnorm=I=-16:TP=-1.5:LRA=11:measured_I=<input_i>:measured_TP=<input_tp>:measured_LRA=<input_lra>:measured_thresh=<input_thresh>:offset=<target_offset>:linear=true:print_format=summary \
+  mix.podcast.wav
+```
+
+## Generate: images (local first, cloud upsell)
+
+`resolve --type image` retrieves from the HeyGen catalog first; on a miss it
+GENERATES. Two paths, best-for-the-machine picked automatically:
+
+1. **Local (default, free, private): mflux** (FLUX-on-MLX). `resolve` spec-checks
+   AVAILABLE RAM and runs the best FLUX-class model that fits, via
+   `scripts/lib/local-models.mjs` (`imagegen` ladder) + `mflux-provider.mjs`.
+   The RAM ladder (agent sees it via `describeModelLadder("imagegen", specs)`):
+
+   | Tier   | Model                | Needs (available RAM) | Notes                               |
+   | ------ | -------------------- | --------------------- | ----------------------------------- |
+   | medium | FLUX.1 schnell int4  | ~8GB (`--low-ram`)    | ~20s/512px on 24GB. VERIFIED. Fast. |
+   | large  | FLUX.2 Klein 4B int4 | ~32GB                 | higher quality, full-resident       |
+   | xlarge | Qwen-Image           | ~64GB                 | top quality, 64GB+ Macs only        |
+
+   Gotchas baked into the table: the official FLUX repos are HF-gated, so it
+   points at non-gated community 4-bit re-uploads; and `--low-ram` is MANDATORY
+   at the medium tier (without it a 768x512 run swap-thrashed to 90 minutes on
+   24GB; with it, 20 seconds).
+
+2. **Cloud upsell (better quality): the `codex` CLI** `image_gen` tool, on the
+   user's ChatGPT subscription (codex owns auth, no key here, no per-call
+   charge). It is the automatic fallback when no local model fits AND the
+   explicit "make it better" choice on any machine. Users who just want codex
+   can ask for it directly. Verified: prompt -> raster -> frozen + ledgered.
+
+`--local-only` keeps mflux (once cached) and skips codex (network).
+
+## Generate: video (`resolve --type video`, HeyGen avatar first)
+
+`resolve --type video "<intent>"` is the default path. It generates a
+script-driven HeyGen avatar video first (the free-usage allowance — OAuth
+sessions ride the web-plan free avatar-video quota where eligible, API keys
+follow normal API billing), falling back to local generative LTX only when
+HeyGen is unavailable, uncredentialed, or `--local-only` is passed. The two
+are non-substitutable outputs (a real presenter vs. a generic generative
+clip), so treat the fallback as "HeyGen wasn't reachable," not "upgrade the
+quality":
+
+- **HeyGen avatar video (default, free for new API users):**
+  `heygenVideoGenerate` (`scripts/lib/heygen-video-provider.mjs`) shells the
+  `heygen` CLI — never the raw API — auto-picking a public avatar and a
+  starfish voice (override with `--avatar-id`/`--voice-id`, threaded through
+  as `ctx.avatarId`/`ctx.voiceId`). If the CLI reports `not_authenticated`,
+  the provider prints an onboarding recommendation (avatar video is free for
+  new API users — sign in) to stderr and falls through to LTX instead of
+  hard-failing.
+- **Local fallback: LTX 2.3 on MLX** via `dgrauet/ltx-2-mlx`, the `videogen`
+  ladder in `local-models.mjs` (`ltx-video-provider.mjs`). Generative clips
+  (t2v), spec-gated to RAM. Verified on 24GB: 512x320 x 33f with audio.
+
+Every generating `heygen` call from media-use — TTS, avatar video, and
+catalog search — sends the allowlisted `X-HeyGen-Client-Source: media-use`
+header (persistent flag, works on every subcommand) via the shared
+`HEYGEN_CLIENT_SOURCE_ARGV` constant (`scripts/lib/heygen-cli.mjs`), so usage
+tags correctly in billing/resource meta and shows up in the API dashboards.
+Read-only discovery (`avatar list`, `voice list`) doesn't need it.
+
+For structured bodies `resolve --type video` doesn't expose yet (a specific
+`avatar_id`/`voice_id` combination beyond the ctx overrides, or a
+pre-recorded `audio_url` instead of a script), the raw `heygen video create`
+recipe below remains the escape hatch:
+
+```bash
+# discover an avatar + a starfish voice, then create + wait
+heygen avatar list --ownership public --limit 5
+heygen voice list --engine starfish --limit 5
+heygen video create --headers "X-HeyGen-Client-Source: media-use" --wait -d '{
+  "type": "avatar",
+  "avatar_id": "<avatar-id>",
+  "script": "Your narration here.",
+  "voice_id": "<voice-id>"
+}'
+```
+
+Avatar videos are deterministic + script-driven (lip-sync from a script or a
+pre-recorded `audio_url`), distinct from the generative LTX clips. After a
+manual recipe renders, `resolve --from <downloaded.mp4> --type video` to
+ledger it (not needed when generating via `resolve --type video` directly —
+that already ledgers the result).
+
+### Image-to-video (animate any still into a talking clip)
+
+Not wired into `resolve --type video` (deferred — the `avatar` type covers
+the default script-driven case). `heygen video create` takes the raw
+`POST /v3/videos` body, so switching `type`
+from `avatar` to `image` animates **any image of a person** into a lip-synced
+talking video, with no avatar/photo-avatar creation step first. Point `image` at a
+public URL or an uploaded `asset_id`, and drive speech with a `script`+`voice_id`
+or a pre-recorded `audio_url`:
+
+```bash
+heygen video create --headers "X-HeyGen-Client-Source: media-use" --wait -d '{
+  "type": "image",
+  "image": { "type": "url", "url": "https://example.com/person.jpg" },
+  "script": "Your narration here.",
+  "voice_id": "<voice-id>"
+}'
+```
+
+Common optional fields: `title`, `resolution` (`4k`/`1080p`/`720p`),
+`aspect_ratio`, `remove_background`, `background`, `voice_settings`,
+`motion_prompt` + `expressiveness` (photo-avatar animation), and
+`callback_url`/`callback_id` for webhooks. Don't hardcode these from memory: the
+CLI self-documents the full, current body with
+`heygen video create --request-schema` (a discriminated union keyed on `type`),
+so read the schema rather than trusting a stale field list. For a still you'll
+reuse across many scripts, create a reusable **Photo Avatar** once instead
+(`heygen avatar create`). Ledger the result with
+`resolve --from <downloaded.mp4> --type video`. Docs:
+<https://developers.heygen.com/image-to-video>.
+
+## HEVC / H.265 sources
+
+HEVC/H.265 sources need no conversion for **render** (FFmpeg pre-decodes all
+input video) or for **preview** (auto-proxy transcodes and caches an H.264
+copy on first use, disable with `--no-proxy` or `media.autoProxy: false` in
+hyperframes.json). A manual H.264 proxy via `ffmpeg -i in.mp4 -c:v libx264
+-crf 18 proxy.mp4`, registered with `resolve --from`, remains available for
+edge cases (e.g. auto-proxy disabled, or ffmpeg unavailable at preview time).