@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/html2video/references/storyboard.md

@@ -1,323 +0,0 @@
-# storyboard.json
-
-The reviewable contract between understanding and rendering. Authoritative schema:
-`assets/template/src/schema/storyboard.ts`.
-
-Two rules shape the whole thing:
-
-1. **Everything time-like inside a scene is normalised `0..1`, never a frame.**
-   Scene durations get re-solved to hit the runtime target, so any authored frame
-   number would silently desync emphasis, callouts and captions.
-2. **Assets are local, always.** The schema rejects anything matching `^https?:`,
-   because nothing in the render may wait on the network.
-
-## Top level
-
-```jsonc
-{
-  "version": 1,                      // literal 1
-  "meta": {
-    "sourceUrl":   "https://…",      // required, must parse as a URL
-    "sourceTitle": "…",              // required, non-empty
-    "lang":        "zh-Hans",        // required, LITERAL "zh-Hans"
-    "coreMessage": "…",              // required, <= 40 chars
-    "arc":         "claim-evidence-implication",   // required, one of five below
-    "author":      "",               // optional
-    "publishedAt": ""                // optional
-  },
-  "target": { "fps": 30, "width": 1920, "height": 1080,
-              "seconds": 95, "toleranceFrames": 30 },
-  "art":    { … },   // harvested design tokens — the "骨"
-  "motion": { … },   // seeded motion signature — the "魂"
-  "audio":  { "mode": "music", "bedGain": 0.32, "duckTo": 0.12 },
-  "assets": [ … ],
-  "scenes": [ … ]    // 4 to 14
-}
-```
-
-Every field in `meta` marked required will fail validation if absent, and `lang`
-must be exactly `"zh-Hans"` — the schema uses a literal, not a free string.
-
-`fps`, `width` and `height` are also literals: `30`, `1920`, `1080`. Other formats
-are P1, so the schema refuses them rather than rendering something mis-sized.
-
-`meta.coreMessage` is capped at 40 characters — the Chinese equivalent of "15 words
-or fewer". `meta.arc` is one of the five narrative arcs in
-[editorial.md](editorial.md).
-
-`target.seconds` is a goal, not a guarantee. The solver hits it when it can and
-reports when it cannot; see [Timing](#timing).
-
-## art
-
-Harvested by `harvest.py` into `harvest.json`'s `tokens`, then hand-mapped. From
-the reference article's real computed styles:
-
-```jsonc
-{
-  "ground": "paper",            // paper | ink | tint
-  "groundColor": "#faf9f5",     // tokens.bodyBg
-  "ink": "#141413",             // tokens.bodyColor
-  "inkMuted": "#5e5d59",        // from tokens.textColorsByUse
-  "accent": "#d97757",          // tokens.cssVars["--color-clay"]
-  "accentAlt": "#bcd1ca",       // tokens.cssVars["--color-cactus"]
-  "radius": 16,                 // tokens.radii, most frequent
-  "ruleWidth": 1,               // scaled up for video; see pitfalls.md
-  "texture": "paper",           // none | grain | grid | paper
-  "displayFace": "sans",        // tokens.h1Font
-  "bodyFace": "serif",          // tokens.bodyFont (see note)
-  "sourceLabel": "anthropic.com"
-}
-```
-
-`displayFace` and `bodyFace` are independent on purpose — this site sets headings
-in a sans and body in a serif, and collapsing that to one toggle loses the contrast
-that makes its typography recognisable.
-
-Pick `inkMuted` for readability rather than fidelity: the most-used muted colour on
-the page may be far too light for a caption at video viewing distance.
-
-## motion
-
-```jsonc
-{
-  "seed": "anthropic.com/research/natural-language-autoencoders",
-  "pace": "measured",           // staccato | measured | languid
-  "easeFamily": "editorial",    // crisp | editorial | overshoot
-  "panBias": "ltr",
-  "revealStyle": "mask-up",
-  "transitionVocab": ["cut", "fade", "wipe"],
-  "gridEnergy": 0.22
-}
-```
-
-`motionFromUrl()` in `src/lib/art.ts` derives a full signature deterministically
-from a URL if you want one chosen for you. Write the result into the JSON rather
-than recomputing at render time, so the value is stable and reviewable.
-
-## assets
-
-```jsonc
-{
-  "id": "fig-arch",
-  "src": "media/fig-02.png",        // harvest.json calls this key `file`, not `src`
-  "intrinsic": { "w": 4620, "h": 1410 },   // copy from harvest.json — must be accurate
-  "role": "diagram",                // REQUIRED, no default:
-                                    //   figure | diagram | screenshot | hero | logo
-  "alt": "",                        // optional
-  "sourceCaption": "In a natural language autoencoder, the activation verbalizer …"
-}
-```
-
-Note the key rename: `harvest.json` exposes the path as `figures[].file`; the
-storyboard field is `src`. `render.mjs` resolves it relative to the harvest
-directory and stages the file, so `media/fig-02.png` is the right form to write.
-
-`intrinsic` drives the resolution guard, so copy it rather than guessing. `role` is
-required and has no default. `sourceCaption` keeps the untranslated original for
-provenance and is never rendered.
-
-**Check `harvest.json`'s `captionSource` before trusting a caption.** It is one of:
-
-| value | meaning |
-|---|---|
-| `figcaption` | taken from the page's own `<figure>/<figcaption>` — authoritative |
-| `proximity` | the paragraph that happened to follow the image — **verify it** |
-| `none` | the page gave no caption |
-
-`proximity` is a guess and it can be wrong in the worst way: on one real page all
-three such captions were ordinary body prose, and one described the *next* chart.
-When it says `proximity` or `none`, open the image and read the finding off the
-chart itself — its own embedded title is usually the best source, and re-authoring
-that as a Chinese headline is the intended move.
-
-## scenes
-
-```jsonc
-{
-  "id": "s4",
-  "shot": "diagram",
-  "weight": 2.8,                    // dimensionless — never frames
-  "text": {
-    "eyebrow": "机制",
-    "headline": "一个负责说，一个负责猜"
-  },
-  "assets": [{ "ref": "fig-arch", "slot": "band",
-               "move": { "kind": "hold", "target": {"x":0,"y":0,"w":1,"h":1} } }],
-  "callouts": [
-    { "at": 0.16, "text": "AV：把激活翻成一段人话", "anchor": {"x":0.13,"y":0.80} },
-    { "at": 0.48, "text": "AR：只读这段话，反推原始激活", "anchor": {"x":0.46,"y":0.80} },
-    { "at": 0.78, "text": "对得上，才算这句人话是真的", "anchor": {"x":0.82,"y":0.80} }
-  ],
-  "emphasis": [{ "at": 0.62, "kind": "punch", "target": "line:2" }],
-  "transitionOut": { "kind": "fade", "frames": 14, "timing": "linear" }
-}
-```
-
-`text` fields: `eyebrow` (24), `headline` (100), `sub` (160), `caption` (200),
-`credit` (120), `items[]` (max 4, label 12 + text 60), `stat` (value 10, unit 8,
-of 40). Those are schema caps; the real limits are the per-box character budgets in
-[cjk-type.md](cjk-type.md), which are tighter.
-
-**The `quote` shot carries its quotation in `headline`, and the attribution in
-`credit`** — there is no dedicated field. Practical limit is about 36 CJK
-characters or ~100 Latin, because it sets at statement size on `cols(9)` over three
-lines. A long quotation therefore has to be **excerpted**: pick the clause that
-carries the point and move the rest into narration or a following `statement` scene.
-Trying to fit a whole paragraph will fail validation, and would be unreadable if it
-did not.
-
-**A `\n` in any text field is an authored line break, and it is honoured.** The
-fitter splits on it, treats each part as its own paragraph, and disables line
-balancing for multi-paragraph text. This is the tool for fixing a bad automatic
-break: when the balancer splits 来不及 or 声明 across two lines, put the break where
-it belongs yourself. Balancing only runs on single-paragraph text precisely so that
-an authored break is never second-guessed.
-
-Per-shot required fields, enforced by the schema:
-
-| shot | also requires |
-|---|---|
-| `stat` | `text.stat` |
-| `compare` | at least 2 `text.items` |
-| `ladder` | at least 2 `text.items` |
-| `diagram` | at least 2 `callouts` |
-
-`stat` also renders `text.headline` at sub size beneath the number, which is a
-useful place for the contrasting figure. `outro` renders `text.headline`, not
-`meta.coreMessage` — usually you want the same sentence in both.
-
-`emphasis.target` accepts `"headline"`, `"sub"`, `"line:N"` (1-based),
-`"item:N"` and `"callout:N"`.
-
-`anchor` and `focus` are in **source-image space**, normalised. `at` is normalised
-within the scene. Callouts must be strictly ordered by `at`.
-
-## fit: cover or contain
-
-Every slot is 1.78:1 or wider, so an image taller than that loses height. Under
-`"cover"` (the default) that lost height is cropped — and for a chart the height
-that goes is the title and the axis labels, i.e. the content.
-
-```jsonc
-{ "ref": "fig-04", "slot": "inset", "fit": "contain",
-  "move": { "kind": "hold", "target": {"x":0,"y":0,"w":1,"h":1} } }
-```
-
-| fit | Behaviour | Use for |
-|---|---|---|
-| `cover` | fills the slot, crops the overflow, Ken Burns applies | photographs, a figure used as a backdrop, anything wider than its slot |
-| `contain` | whole image scaled to fit, letterboxed by the ground, **`move` ignored** | charts, schematics, screenshots, tables — anything whose edges carry meaning |
-
-A 1.36:1 map in a 1.78:1 slot loses about 43% of its height under `cover`. If the
-figure has a title, a legend, or axis labels, use `contain`. The resolution guard
-adjusts automatically: a contained figure only needs its fitted size, so headroom
-is much easier to satisfy.
-
-The trade-off is that `contain` is static — there is nothing to pan within. A board
-where every figure is contained will read as slides, so give at least one `cover`
-figure a gentle `push-in` **where the material allows it**.
-
-Sometimes it does not, and that is a legitimate outcome rather than a failure to
-work around. An article whose figures are all charts, schematics and screenshots
-sends all of them to `contain`, and none can take a crop: a chart loses its axis
-labels, a screenshot loses the text that is the point of showing it. Two things to
-know before fighting it:
-
-- **A push-in whose target is the full width silently becomes a hold.**
-  `expandRect` clamps at `w = 1`, so `{kind:"push-in", target:{...w:1...}}` has
-  nothing to expand from. It will not error; it simply will not move.
-- If every figure must be static, get the variation from elsewhere: alternate
-  figure-led and text-led scenes, use `stat` and `quote` between figures, and let
-  the `caveat` inversion carry the structural break. A static middle third is a
-  real weakness — say so when handing the video over rather than hiding it.
-
-## Moves
-
-```jsonc
-{ "kind": "hold",     "target": rect }
-{ "kind": "push-in",  "target": rect, "amount": 1.18 }   // starts wide, settles on target
-{ "kind": "pull-out", "target": rect, "amount": 1.18 }   // starts on target, opens out
-{ "kind": "pan",      "from": rect, "to": rect }
-{ "kind": "rects",    "from": rect, "to": rect }         // explicit both ends
-```
-
-Rects are normalised in source-image space and must lie inside the unit square.
-The library then **snaps them to the destination box's aspect**, growing the
-deficient axis so nothing you asked for is lost. Because `lerp` preserves the
-width/height ratio and a convex combination of two contained rects stays contained,
-every interpolated frame is both aspect-exact and inside the image — which is why
-"the pan must not expose the frame edge" is a schema precondition rather than a
-runtime hope.
-
-Two guards fire before frame 0:
-
-- **Resolution**: `dest.w / tightest.w` must not exceed `intrinsic.w`. A 1590px
-  chart cannot fill a 1920 slot at any crop.
-- **Shimmer**: zoom range is capped at 1.25x for moves of 4s or more (Chrome
-  re-rasterises across large scale ranges and it crawls).
-
-## Timing
-
-Three tiers, and the floor is inviolable.
-
-**1. Reading floor**, computed by the library from your text — never authored:
-
-```
-READ_CPS = { display: 5.5, headline: 5.0, statement: 4.6, sub: 4.4, caption: 4.0, quote: 3.4 }
-floor = max(SHOT_FLOOR[shot], ceil(fps * (0.5 + Σ chars/READ_CPS + holdOut)))
-```
-
-CJK counts one unit per character; Latin runs count a **third** of their length,
-because reading effort for Latin is per-word not per-glyph. `credit` is excluded
-entirely — nobody reads a URL character by character, and counting it once inflated
-an outro to 10 seconds of dead air.
-
-`SHOT_FLOOR` exists because some shots need time to read as a *move*: `figure` 2.6s,
-`diagram` 3.2s **per callout**, `compare` 3.0s.
-
-**2. Weights.** The solver bisects for a `unit` such that
-`Σ clamp(floor, weight·unit, cap) − Σ transitions = target`. Clamped scenes push
-their slack onto unclamped ones.
-
-**3. Voice mode inverts authority.** With `audio.mode: "voice"`, speech sets the
-length: each scene runs as long as its `narration` takes to say, and
-`target.seconds` becomes an assertion about the result rather than something to
-solve for. The READING floor is dropped — the viewer is listening, not reading, and
-keeping it would stretch scenes past their narration into dead air. Only the
-per-shot "reads as a move" minimum survives.
-
-With no measured audio, the spoken length is estimated from the narration text by
-`lib/speech.ts`. That estimate is a pure function of the text, so it needs no side
-channel and stays deterministic. See [narration.md](narration.md) for the model and
-the `--sps` rate flag.
-
-Expect a voice board to run considerably longer than the same content in music
-mode — narration is slower than reading. The reference article is 95s read and 148s
-narrated.
-
-**The solver may only distribute slack above the floor.** If the floors alone
-overflow, the pipeline **fails with an editorial instruction** naming the scenes
-with the most slack to give back:
-
-```
-storyboard is 29.6s over target (floors 77.3s + transitions 2.7s vs target 45s).
-  - scene "s4" (diagram) has a 12.4s floor from 12 chars — cut text or drop the scene
-```
-
-Squeezing text below its reading floor is the one failure a viewer notices every
-single time, so it is not available.
-
-If the caps cannot reach the target the video is simply shorter, and it says so —
-add a scene or lower `target.seconds` rather than letting shots drag.
-
-## Authoring loop
-
-```bash
-node scripts/render.mjs --storyboard ./work/myrun --still 0    # validate + one frame
-```
-
-The report gives resolved durations, each scene's `from` frame, pixel headroom per
-asset and character budgets. Fix everything before rendering. What it cannot check
-is text fitting — that needs a browser, so line-count overflow surfaces at render
-time as a named failure (`scene "s6" field "headline" does not fit …`).

package/skills/hyperdirector/SKILL.md

@@ -1,202 +0,0 @@
----
-name: hyperdirector
-description: "HyperDirector: the method the original skill taught, run as an AICUT film — pages that draw any moment t, cut on tracks. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: Apache-2.0
-source: "gloweaseco-leo/hyperdirector"
----
-
-# HyperDirector
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-Hermes video director enhancement pack. HyperFrames is the render engine. HyperDirector is the director workflow layer above it.
-
-**Reference files:**
-- Capability rules → `CAPABILITY_BOUNDARY.md`
-- Upstream principles → `upstream/hyperframes-principles.md`
-- Anti-patterns → `upstream/hyperframes-anti-patterns.md`
-- Command patterns → `upstream/hyperframes-command-patterns.md`
-- Agent-native rules → `upstream/hyperframes-agent-native-rules.md`
-- Headless / offline rendering stability → `rules/headless-rendering-stability.md`
-- Image asset rules → `rules/image-assets-basics.md`
-- Audio Director rules → `rules/audio-director-rules.md`
-
----
-
-## Default Workflow
-
-Execute these steps in order. Do not skip steps. Do not jump to HTML generation without brief and storyboard.
-
-```
-Step 1 — Capability Judge
-  Read CAPABILITY_BOUNDARY.md.
-  Classify request: suitable / degraded / reject.
-  If degraded: propose downgrade version and wait for user confirmation.
-  If reject: output reason and alternatives. Stop.
-
-Step 2 — Brief Generation  (→ brief.json)
-  Populate brief.json per schemas/brief.schema.json.
-  Infer brief.language from user input if not specified.
-  Chinese users default to zh-CN.
-
-Step 3 — Storyboard Generation  (→ storyboard.json + script.md)
-  Generate scene structure per schemas/storyboard.schema.json.
-  Duration sum must equal brief.duration_seconds.
-  Every scene needs: id, duration, purpose, headline, visual, caption, transition.
-
-Step 4 — Visual Design  (→ DESIGN.md)
-  Select template from: tiktok-vertical-kit | saas-demo-kit | ai-knowledge-explainer-kit.
-  Load brand-kit.json. Apply colors, fonts, motion_language, cta.
-  Write DESIGN.md: canvas size, color palette, font stack, per-scene animation intent.
-
-Step 5 — HTML Composition  (→ index.html)
-  Generate plain HTML + CSS + GSAP composition.
-  Follow rules/hyperframes-core-rules.md, rules/gsap-deterministic-rules.md, rules/headless-rendering-stability.md.
-  Every timed element needs class="clip", data-start, data-duration, data-track-index.
-  Timeline must be paused. Key must match data-composition-id.
-
-Step 6 — QA Fix Loop  (→ lint output)
-  Run: npx hyperframes lint
-  Run: npx hyperframes validate  (if lint passes)
-  On failure: apply fix from rules/common-errors-fix.md. Retry max 3 times.
-  On 3rd failure: halt, output unresolved error to user.
-
-Step 7 — Render (if HyperFrames CLI available)
-  Draft: npx hyperframes render --quality draft --output output/<slug>/draft.mp4
-  Final (after user confirms draft): npx hyperframes render --quality high --output output/<slug>/final.mp4
-  If CLI not available: skip render, note in render-report.md.
-
-Step 8 — Render Report  (→ render-report.md)
-  Always output render-report.md even if render was skipped.
-  Include: task type, template, lint result, fixes applied, render status.
-  Never write "render completed" unless CLI returned exit code 0 and output file exists.
-```
-```
----
-```
-
-## Prohibited Behaviors
-
-- Do not promise or attempt photorealistic video generation (Sora / Runway territory).
-- Do not promise or attempt digital human lip-sync (HeyGen Studio / Synthesia territory).
-- Do not promise cinema-grade 3D effects or character animation.
-- Do not replicate copyrighted brand identities, film styles, or specific influencer templates.
-- Do not skip the Capability Judge step before generating anything.
-- Do not skip brief.json or storyboard.json and jump directly to HTML.
-- Do not skip lint/validate before render.
-- Do not write "video generated" or "render completed" without CLI evidence.
-- Do not rewrite the entire index.html during warm iteration — patch only affected scenes.
-- Do not use Math.random() or infinite repeat in GSAP timelines.
-- Do not call video.play() / audio.currentTime in composition scripts.
-- Do not animate width/height/top/left directly on <video> elements.
-
----
-
-## Standard Output
-
-Every completed run produces these files in `output/<project-slug>/`:
-
-```
-brief.json              required — structured requirements
-storyboard.json         required — scene structure
-DESIGN.md               required — visual design spec
-index.html              required — HyperFrames composition source
-render-report.md        required — QA + render status
-script.md               recommended — narration script
-brand-used.json         recommended — applied brand values snapshot
-edit-instructions.md    on iteration — change log
-final.mp4               when render executed
-```
-
-# Media Asset Pipeline (optional — activate when project needs visual or audio assets)
-asset-manifest.json     optional — image asset declarations (Source Image Pipeline)
-audio-manifest.json     optional — audio segment declarations (Audio Director)
-caption-timeline.json   optional — subtitle/caption alignment (Audio Director)
-```
----
-```
-
-## Language Policy
-
-- Engineering files (this file, prompts/, rules/, schemas/) use English.
-- User-facing content in generated videos follows `brief.language`.
-- If `brief.language` is absent, infer from user input language.
-- Chinese users default to `zh-CN`: scripts, captions, CTA, on-screen copy all in Chinese.
-- Technical terms (API, GSAP, HyperFrames, CLI) may stay English in Chinese video copy.
-- Chinese user docs are in `docs/*.zh-CN.md` and `README.zh-CN.md`.
-
----
-
-## Warm Iteration Rules
-
-When user requests changes to an existing project:
-
-1. Locate affected scene(s) in storyboard.json by scene id.
-2. Locate corresponding HTML elements by id attribute.
-3. Apply surgical edits — do not regenerate the entire file.
-4. Re-run lint on modified file.
-5. Update storyboard.json in sync with any structural HTML changes.
-6. Output edit-instructions.md describing what changed and why.
-
----
-
-## Optional Media Asset Pipeline
-
-Media Asset Pipeline is **optional**. Activate when the project needs visual or audio assets beyond pure HTML/CSS composition.
-
-**Source Image Pipeline** — activate when the project needs:
-- Source images, screenshots, logos, product photos
-- PPT / PDF visuals, README diagrams, UI screenshots
-- Local visual assets bound to specific scenes or slots
-
-→ Produces `asset-manifest.json`. See `rules/image-assets-basics.md`, `docs/source-image-workflow.zh-CN.md`.
-
-**Audio Director** — activate when the project needs:
-- Voiceover planning and provider-neutral TTS contracts
-- Caption timeline aligned to audio segments
-- Audio/video sync QA and authorisation tracking
-- Audio manifest for render planning
-
-→ Produces `audio-manifest.json` + `caption-timeline.json`. See `rules/audio-director-rules.md`, `docs/audio-workflow.zh-CN.md`.
-
-Both pipelines are insertable **after Step 3 (Storyboard)** and **before Step 5 (HTML Composition)**. They are not required for every project.
-
-Advisory hazard scan (non-blocking, covers images and audio):
-```bash
-node hyperdirector/scripts/check-composition-hazards.js output/index.html
-```
-
-## Source
-
-Rewritten for AICUT from [`gloweaseco-leo/hyperdirector`](https://github.com/gloweaseco-leo/hyperdirector)
-(Apache-2.0), hyperdirector/SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/hyperdirector/docs/audio-workflow.md

@@ -1,160 +0,0 @@
-# Audio Director Workflow
-
-> Version: v0.1.3-preview  
-> Applies to: HyperDirector + Hermes (Cursor Agent)  
-> Rules: `rules/audio-director-rules.md`  
-> Schemas: `schemas/audio-manifest.schema.json` / `schemas/caption-timeline.schema.json`  
-> QA: `qa/audio-qa-checklist.md`
-
----
-
-## What Audio Director Is
-
-Audio Director is the **audio planning layer** in HyperDirector. It is not a TTS tool.
-
-Its responsibility is to organise scripts, voice segments, voice profiles, provider-neutral TTS plans, audio manifests, caption timelines, and audio/video sync relationships into a reviewable pipeline.
-
-Audio Director does **not**:
-- Directly call TTS providers to generate audio
-- Clone voices (without explicit authorisation)
-- Perform audio waveform analysis or compression
-- Search the internet for narration content (when web research is needed, use Hermes official built-in `web_search` / `web_extract` capabilities)
-- Replace the HyperFrames render engine
-
----
-
-## Relationship to Other Pipelines
-
-```
-Storyboard (scene_id / shot_id canonical index)
-       │
-       ├─→ Source Image Pipeline → asset-manifest.json
-       │
-       ├─→ Audio Director Pipeline
-       │       │
-       │       ├─→ audio-manifest.json    (audio segment declarations)
-       │       └─→ caption-timeline.json  (subtitle/caption alignment)
-       │
-       └─→ Render Planning (reads image + audio + caption together)
-```
-
-- Image assets → `asset-manifest.json` (bound by scene_id / slot)
-- Audio segments → `audio-manifest.json` (bound by scene_id / shot_id)
-- Captions → `caption-timeline.json` (linked by scene_id / segment_id)
-
-`storyboard.json` remains the single authoritative index for `scene_id` and `shot_id`.
-
----
-
-## Pipeline Stages
-
-### Stage 1 — Extract Audio Intent
-
-From each scene in `storyboard.json`, determine:
-- Whether narration is needed (or pure text captions / silence)
-- Approximate narration content and tone
-- Suggested pace relative to scene `duration`
-
-For web research content, use Hermes official `web_search` / `web_extract` — Audio Director does not implement its own search capability.
-
-### Stage 2 — Split Voice Segments
-
-Divide full narration into scene-level (or shot-level) segments:
-- One `segment_id` per scene or per shot
-- Chinese: 30–80 characters per segment
-- English: 20–60 words per segment
-- Target: segment duration ≤ scene duration × 1.0
-
-### Stage 3 — Define Voice Profile
-
-For simple projects: record `speaker_id`, `provider`, and `voice_name` directly in each `audio-manifest.json` segment.  
-For complex projects (Pro): define a `voice-profile.schema.json` entry and reference it via `voice_profile_id`.
-
-### Stage 4 — Provider-Neutral TTS Planning
-
-Select a TTS provider and record it in the `provider` field. Follow R-AUD-09 provider-neutral design:
-- `text` and `language` fields must be self-contained
-- A fallback provider must be plannable from the same fields
-
-Optional provider directions (none are default dependencies):
-
-| Provider | Type | Use case |
-|----------|------|----------|
-| `edge-tts` | System-level TTS, no API key | Fallback, rapid prototyping |
-| `cosyvoice` | Local high-quality Chinese TTS | Chinese narration, local install |
-| `chattts` | Local dialogue TTS | Dialogue scenes, experimental |
-| `fish_audio` | Commercial API | High-quality multi-language |
-| `minimax` | Commercial API | High-quality Chinese |
-
-Do not commit API keys. Do not add these as default dependencies.
-
-### Stage 5 — Generate audio-manifest.json
-
-Initial state: all segments have `render_safe: false`, `local_path` contains the planned path (files not yet generated).
-
-### Stage 6 — Generate caption-timeline.json
-
-Captions can exist independently of audio. A caption entry without a `segment_id` is a text-only caption.
-
-Alignment: `start_ms` / `end_ms` in captions should match the corresponding audio segment timing within ±500ms.
-
-### Stage 7 — Audio File Production
-
-User generates audio files with the chosen TTS provider (or records manually) and places them in `output/assets/audio/`.
-
-Update `audio-manifest.json`:
-- `duration_ms` — from file metadata
-- `start_ms` / `end_ms` — from timeline plan
-- `transcript` — actual TTS output text or manual record
-
-### Stage 8 — Audio / Video Sync QA
-
-```bash
-node hyperdirector/scripts/check-composition-hazards.js output/index.html
-```
-
-Complete `qa/audio-qa-checklist.md`. Set `render_safe: true` for each cleared segment.
-
-### Stage 9 — Render Planning
-
-Reference audio by local path in `index.html`:
-
-```html
-<!-- Correct: local path -->
-<audio id="narration_s01" src="assets/audio/seg_scene01_hook.mp3" preload="auto"></audio>
-
-<!-- Forbidden in production -->
-<!-- <audio src="https://..."></audio> -->
-```
-
-### Stage 10 — Render and Delivery
-
-```bash
-npx hyperframes render --input output/index.html --output output/final.mp4
-```
-
----
-
-## Safety and Authorisation Boundaries
-
-| Allowed | Forbidden |
-|---------|-----------|
-| Standard TTS synthesis (`tts_only`) | Unauthorised voice cloning |
-| Voice cloning with written consent (`consent_obtained`) | API keys in manifest |
-| Provider metadata (no credentials) | Real audio samples committed to git |
-| `edge-tts` as fallback | Model weights committed to git |
-| Planning audio pipeline (no API calls) | Silently calling commercial TTS API |
-
----
-
-## Related Files
-
-| File | Purpose |
-|------|---------|
-| `rules/audio-director-rules.md` | R-AUD-01 – R-AUD-11 rule definitions |
-| `schemas/audio-manifest.schema.json` | Audio Manifest JSON Schema |
-| `schemas/caption-timeline.schema.json` | Caption Timeline JSON Schema |
-| `qa/audio-qa-checklist.md` | Pre-render audio QA checklist |
-| `scripts/check-composition-hazards.js` | Advisory hazard scan (includes audio) |
-| `docs/audio-workflow.zh-CN.md` | Chinese version of this document |
-| `docs/source-image-workflow.md` | Source Image Pipeline workflow |