@autoaiai/aicut 0.1.7 → 0.1.11

package/skills/html2video/references/storyboard.md

@@ -0,0 +1,323 @@
+# 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

@@ -0,0 +1,202 @@
+---
+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

@@ -0,0 +1,160 @@
+# 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 |