@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/beat-sync-edit/SKILL.md

@@ -1,148 +0,0 @@
----
-name: beat-sync-edit
-description: "Turn a song + raw footage into a beat-synced edit. Runs the four-stage pipeline (beat analysis, scene tagging, EDL planning, render) and applies user-described ffmpeg effects — white flashes, stretch punches, hue shifts, speed ramps — at beat-accurate timestamps. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "ZiadAbdelkarim/beat-synced-edit"
----
-
-# Beat-Sync Edit
-
-## 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.
-
-
-Drive the deterministic pipeline conversationally. The user describes the edit
-they want ("cut my footage to the chorus, white flash on every drop, make it
-9:16"); you run the stages, apply effects, and deliver the file.
-
-## The pipeline (run in order)
-
-```
-python3 beat_map.py <song>                       # beats, energy, peaks/valleys → <song>_beatmap.json
-python3 clip_tag.py <footage> --html --thumbs    # scenes + motion/energy tags → <footage>_clips.json
-python3 plan_edit.py <beatmap> <clips> --html    # energy-matched EDL → <name>_edl.json
-python3 render_edit.py <edl> -a <song> -v <footage>   # final MP4
-python3 vertical_style.py <mp4>                  # optional 9:16 squeeze + grade
-```
-```
-- Read the beatmap's `peaks`/`valleys` and the EDL before adding effects —
-  effects belong ON beat timestamps, not at arbitrary times.
-- `plan_edit.py` overrides: `--exclude '1,6,0-30'`, `--lead '2:18,5'`,
-  `--pin '8=138,peak2=22'` — use them when the user dislikes a cut.
-- `plan_edit.py --beat-stride N` — cut density. 1 = a cut on every beat
-  (default); N>1 keeps every Nth beat: fewer, longer cuts that breathe, for
-  slow/contemplative footage. Naming convention for variants:
-  `<name>_beat-full` (stride 1) vs `<name>_beat-thinned` (stride 2+).
-- `plan_edit.py --full` uses the whole song instead of the best segment;
-  `--segment 2|3` picks the second/third-best highlight segment.
-- `render_edit.py --overunder` emits the stacked 960x1080 "3D" variant.
-```
-
-## The white-flash montage template (separate edit style)
-
-When the user asks for a MONTAGE — a 1:1 sequence of held shots/stills with
-white-flash transitions ("white flash between each clip", "photo narrative",
-"meme montage") — use `flash_montage.py` instead of the beat pipeline:
-
-```
-python3 flash_montage.py --seq seq.json --audio <song> --out out.mp4 --flash 1.0
-```
-```
-Author the seq.json yourself from the user's description: one item per shot,
-`{"video": path, "start": t, "dur": d}` or `{"image": path, "dur": d}`, with
-`zoom`/`cx`/`cy` to punch in on each subject (LOOK at a frame first to place
-cx/cy), `stretch` for width hits, `motion: "sway"` for handheld feel (default
-on stills, off for videos). Set `dur` to a beat-multiple of the song's tempo
-(from beat_map.py) so flashes land musically — e.g. 4 beats per slot. Iterate
-by editing the seq.json, not by rebuilding commands.
-```
-
-## What the user can ask for (translate words → workflow)
-
-- "punchier / more cuts" → `--beat-stride 1` (default), or lower clip_tag
-  `--threshold` for finer scenes
-- "calmer / spaced out / longer scenes / let shots breathe" →
-  `--beat-stride 2` (or 4 for very slow footage); when comparing, render both
-  and suffix the outputs `_beat-full` / `_beat-thinned`
-- "start on the best moment" → `--lead` with the highest-energy clip
-- "make it vertical / TikTok-ready / 9:16" → vertical_style.py after render;
-  "square / 1:1" → center-crop with ffmpeg (`crop=ih:ih,setsar=1` + scale);
-  "stacked / over-under" → `render_edit.py --overunder`
-- **Reference videos — take ONLY what the user asks for.** A reference is not
-  a request to clone the whole look. Extract 3-5 frames
-  (`ffmpeg -ss <t> -frames:v 1`), LOOK at them, then match just the named
-  aspect(s): "this tint" → hue/cast only (`hue`, `colorbalance`); "this
-  contrast" → `curves`/`eq` only; "how washed out it is" → saturation only;
-  "the way it cuts" → cut rhythm/density, not color at all; "that flash
-  effect" → just that effect from the cookbook. If they say "make it look
-  like this" without naming an aspect, ASK which parts they mean (color?
-  contrast? pacing? effects?) before matching more than one. Show a
-  confirmation frame before final render. If the reference is on the web and
-  Chrome tools are available, study it there the same way.
-
-## Effects cookbook (apply with ffmpeg per segment, then re-concat)
-
-Apply to individual extracted segments between the extract and concat steps
-(re-encode the segment with `-vf "<filter>"`), or to the final file. Time
-effects to beat timestamps from the beatmap.
-
-| User says | ffmpeg filter |
-|---|---|
-| white flash (on the beat/drop) | `fade=t=in:st=0:d=0.07:color=white` on the segment starting at that beat |
-| black dip | `fade=t=in:st=0:d=0.07:color=black` |
-| stretch / punch-in | `scale=iw*1.15:ih*1.15,crop=iw/1.15:ih/1.15,setsar=1` (hold ~2 frames, then normal) |
-| horizontal stretch hit | `scale=iw*1.25:ih,crop=iw/1.25:ih,setsar=1` |
-| hue shift / psychedelic | static: `hue=h=60` · animated: `hue=h='mod(t*180,360)'` |
-| RGB split / glitch | `rgbashift=rh=6:bh=-6` |
-| speed ramp | `setpts=0.5*PTS` (2x) · `setpts=2*PTS` (half speed; add `minterpolate` for smoothness) |
-| shake | `crop=iw-20:ih-20:'10+8*sin(t*40)':'10+8*cos(t*37)'` |
-| strobe invert | `negate=enable='lt(mod(t,0.25),0.04)'` |
-| dreamy glow | `gblur=sigma=8,blend=all_mode=screen,all_opacity=0.35` (via split) |
-| grade: warm | `colorbalance=rm=.12:bm=-.08` · cool: `colorbalance=bm=.12:rm=-.06` |
-
-Rules of thumb: flashes/punches on energy PEAKS only (over-flashing reads
-amateur); one signature effect per edit + one grade; always `-pix_fmt yuv420p`
-and `setsar=1` when re-encoding segments so concat stays valid.
-
-## Workflow when the user asks for an edit
-
-1. Run beat_map + clip_tag (with `--thumbs`; view the contact sheet to know
-   the footage).
-2. plan_edit → review the EDL against their description; apply overrides.
-3. render_edit → if effects were requested, re-extract the affected segments
-   with filters at the right beats, re-concat, re-mux audio.
-4. Optional vertical_style for 9:16. Deliver the file path + one-line summary
-   of cut count, duration, and effects used.
-
-## Source
-
-Rewritten for AICUT from [`ZiadAbdelkarim/beat-synced-edit`](https://github.com/ZiadAbdelkarim/beat-synced-edit)
-(MIT), .claude/skills/beat-sync-edit/SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/book-video-factory/SKILL.md

@@ -1,139 +0,0 @@
----
-name: book-video-factory
-description: "Create or operate a portable, auditable Chinese book-review short-video workflow from a clean local workspace. Use when starting a book-video factory, choosing between the original 3:4 bilingual editorial style and the new 9:16 VOX-style book-video workflow, importing dbs-content-system source documents and QST/CON/OPI/CAS/SOL content units, linking script claims to evidence and scenes, using approved Gemini API or Google Flow assets, collecting rights-aware media, recording run cost, or preparing a local master for optional ChatCut fine editing. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "jaxxchen003/book-video-factory"
----
-
-# 图书视频工厂
-
-## 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.
-
-
-## First use
-
-1. Resolve `SKILL_ROOT` as the directory containing this `SKILL.md`; do not assume a particular user home directory, operating system, brand, voice, font, or credential.
-2. In an empty or new workspace, run:
-
-   ```bash
-python3 <SKILL_ROOT>/scripts/bootstrap_workspace.py --workspace .
-   python3 <SKILL_ROOT>/scripts/doctor.py --profile planning
-```
-```
-Bootstrap copies the bundled deterministic runtime into `book_video_factory/`; it does not download hidden media or depend on the maintainer's machine.
-
-3. Create a project only after the user approves the book/topic:
-```
-```bash
-python3 <SKILL_ROOT>/scripts/bootstrap_workspace.py \
-     --workspace . --slug <slug> --book-title '<title>' --author '<author>'
-```
-```
-If the topic comes from a structured content asset system, add `--mode content-system-backed`. This mode requires a validated content package and traceability map before assets can pass their gate.
-
-4. Read `references/first-run.md` before generating the first production package. Read `references/quality-gates.md` before declaring a release ready.
-```
-
-## Working model
-
-- Keep reusable workflow/configuration in `book_video_factory/` and project-specific evidence/media in `book_video_warehouse/`.
-- Treat all book covers, quotations, BGM, voice references, reference videos, generated assets, and credentials as user-owned/project-local inputs. Never ship, download, clone, or reuse a hidden default asset.
-- Create a new release directory for every revision. Preserve the local master as the source of truth; ChatCut is an optional editable polish layer.
-- Keep human gates for topic approval, script approval, source/rights approval, native-language review, and publish approval.
-
-## Style profiles
-
-Select one style profile before making assets; never silently mix their frame, typography, or review contracts.
-
-- **双语编辑模板图书视频（原风格）** — machine ID `book-editorial-bilingual-v2`. Deterministic 3:4 bilingual template with a real cover, 12 approved stills, local narration, rendered captions, and an optional 9:16 derivative.
-- **VOX风格图书视频（新增风格）** — machine ID `paper-collage-explainer-v1`. A 9:16, voice-led editorial paper-collage explainer made from 4–8-second visual beats. It is a descriptive public label, not an affiliation claim or permission to imitate a named publisher/program. Read [references/paper-collage-explainer.md](references/paper-collage-explainer.md) before selecting it.
-
-The original style is the backward-compatible default. For VOX style, create the project with `--style-profile paper-collage-explainer-v1` and explicitly choose one generation lane:
-
-- **`gemini-api`** — programmatic lane. Requires a user-authorized `GEMINI_API_KEY`, the current Google Gen AI SDK, provider cost/quota approval, and an immutable operation/output record. Use `gemini-omni-flash-preview` through the Interactions API by default; use `veo-3.1-generate-preview` through `generate_videos` when first/last-frame control or video extension is required.
-- **`google-flow`** — manual creative lane. Requires current account/region eligibility, an eligible Google AI plan, available credits, and a user-operated browser session. Do not assume Flow exposes a programmable API; import only user-authorized exports and record prompts, visible credits, hashes, and manual-run provenance.
-
-The VOX-style path is currently an orchestration-and-import workflow. Do not claim this repository bundles a one-click Google video generator.
-The current `dbs-content-system` scene-traceability contract is V4-specific, so `content-system-backed` is supported by the original style only; VOX style is fail-closed to `single-book` until a manifest-based traceability contract is implemented and tested.
-
-## Production sequence
-
-1. **Topic and evidence** — collect public, attributable book metadata. If a WeRead credential or another data source is unavailable, record the limitation and use user-supplied/publicly attributable evidence; do not bypass logins or platform restrictions.
-2. **Script, voice, and timing** — create and approve a concise Chinese script plus any English production draft. Generate/record narration only with authorization; derive timestamps from actual audio via permitted ASR or an editor transcript. Never invent timing. VOX style locks this timing before full clip generation.
-3. **Style-specific assets** — the original style obtains a real cover plus 12 approved text-free stills. VOX style approves one metaphor, then a first/last frame or contact sheet, then each generated visual beat; prompts use non-branded editorial descriptors.
-4. **Picture lock** — map approved assets to the locked narration. Normalize VOX clips to silent 720×1280 H.264 at the local 30 fps timeline without speed changes; inspect cadence and keep optical flow off by default.
-5. **Audio and render** — add project-owned narration, local captions, permitted BGM and SFX. BGM rights approval and creative `bgm_review` are separate decisions. Never copy a reference video's audio.
-6. **QC and delivery** — run technical and human gates, bind approvals to hashes, write manifests and cost events, then optionally import the passed local master into ChatCut for fine editing.
-
-## Workflow contracts
-
-- `project.json.workflow.style_profile_id` selects the visual workflow; its mapped `release_profile_id` selects the renderer/output contract. Existing projects without a style ID fall back to the original style only for compatibility.
-- Use `config/release_profiles/book-v4-bilingual-3x4.json` for the original style and `config/release_profiles/book-vox-vertical-9x16-v1.json` for VOX style; never treat either style's dimensions or assets as universal constants.
-- Use `scripts/workflow.py evaluate --project <project> --release-id <release-id>` to resolve the project profile and derive a release-scoped state. `project.json.status` is not an approval mechanism, and approvals from different releases are never combined.
-- Record human decisions with `scripts/workflow.py approve`; approvals bind to the reviewed file hash and become stale after edits.
-- Use `scripts/workflow.py manifest-stage` for immutable stage manifests with input/output hashes.
-- Long titles are pixel-measured, semantically wrapped to at most two lines, and fail closed if they cannot fit the configured safe area.
-- Keep `dbs-content-system` upstream: it owns source audits, `QST / CON / OPI / CAS / SOL`, theme maps, relationships, deduplication, canonical versions, and assembly. Do not reproduce those algorithms in this Skill.
-- For `content-system-backed`, use `scripts/content_bridge.py export-dbs`, `validate-package`, `import-package`, `attach-traceability`, and `status`. `export-dbs` is serialization only; it does not perform upstream semantic work. Imports and active-version changes are append-only and hash-bound.
-- A valid bridge package contains `source_document / content_unit / claim / assembly_brief`; the traceability map connects every script line to reviewed Claim evidence or an explicit editorial exemption, and to the renderer's actual scene contract. A human `traceability` approval bound to that map is required before `assets_ready`.
-
-## Required release gates
-
-- Do not use a generated imitation as a book cover. Record the actual cover source and rights/usage status.
-- Do not reuse copyrighted music, sound effects, reference-video audio, a person's voice, public-figure likeness, or account branding without explicit rights.
-- Require 12 non-duplicate numbered stills (`S01`–`S12`) only for the original V4-style delivery. VOX style uses its approved clip manifest and does not impose a universal scene count.
-- For VOX style, keep `source_audit`, `gate_1_metaphor`, `gate_2_still`, `gate_3_clip_qa`, `bgm_review`, `audio_qc`, `local_master_review`, and `publish` as distinct hash-bound gates. Apply `cover_rights` and `english_native` only when those elements are delivered.
-- Accept invisible provider provenance such as SynthID; do not remove or tamper with it. Reject visible third-party watermarks.
-- Never invent token counts. Record only usage values exposed by the relevant provider.
-
-## Cost ledger
-
-Use the bundled append-only ledger for known usage and operational facts:
-
-```bash
-python3 <SKILL_ROOT>/scripts/run_cost.py record \
-  --warehouse book_video_warehouse --project <slug> --stage assets.generate \
-  --images 12 --note 'Approved scene images'
-python3 <SKILL_ROOT>/scripts/run_cost.py report --warehouse book_video_warehouse
-```
-```
-`—` in a report means the usage was not available; it is not zero cost.
-```
-
-## ChatCut handoff
-
-Use ChatCut only after local QC passes. Import the local master and subtitle file, make scoped editorial changes, and export `v4-chatcut-<revision>` without overwriting the local master. Record the project ID, edits, reviewer decision, and export path in the project delivery manifest.
-
-## Source
-
-Rewritten for AICUT from [`jaxxchen003/book-video-factory`](https://github.com/jaxxchen003/book-video-factory)
-(MIT), skills/book-video-factory/SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/book-video-factory/references/first-run.md

@@ -1,50 +0,0 @@
-# First production run
-
-## What installation gives you
-
-This skill gives Codex a portable operating contract plus the deterministic factory runtime: renderer scripts, release profiles, schemas, dependency diagnostics, title safe-area logic, immutable manifests, hash-bound approvals, and the cost ledger. It does not contain a voice, cover, BGM, SFX, reference video, book text, external credentials, or a publishing account.
-
-## Choose a style before rendering
-
-- **双语编辑模板图书视频（原风格）** — `book-editorial-bilingual-v2`. Requires the V4 3:4 contract, a real cover with provenance, a 15-line Chinese/English script, and 12 approved distinct text-free stills (`S01`–`S12`).
-- **VOX风格图书视频（新增风格）** — `paper-collage-explainer-v1`. Requires a `single-book` project, an explicit `gemini-api` or `google-flow` lane, approved narration timing, and a manifest-defined set of 4–8-second visual beats. It does not require exactly 12 clips.
-
-Both styles require an approved topic/book match, attributable evidence, authorized narration, real timing data, permitted BGM/SFX with provenance, technical QC, local-master review, and a separate publish decision. Cover rights and native-English review apply when those elements are delivered.
-
-## Supported paths
-
-- **Local renderer path:** install Python 3.11+, Pillow, FFmpeg/FFprobe, and a permitted ASR/TTS implementation. Keep tool paths/configuration in the workspace, not in the Skill.
-- **VOX / Gemini API path:** select `--style-profile paper-collage-explainer-v1 --generation-lane gemini-api`, keep `GEMINI_API_KEY` in the environment only, and run `doctor.py --profile production --project <project>` before generation.
-- **VOX / Google Flow path:** select `--generation-lane google-flow`, work in the user's eligible Google account, and import only legitimate exports with prompt, credits, and hash provenance. Flow is not treated as a programmable API.
-- **Editor-first path:** use ChatCut only if the user has installed/authenticated it. Keep the local master and subtitle file before importing. If ChatCut is unavailable, continue with local files and explain the missing polish step.
-- **Research fallback:** if WeRead or another credentialed source is unavailable, use attributable public metadata or user-provided sources and record the source limitation. Never circumvent access controls.
-- **Content-system-backed path:** use the original style with `--mode content-system-backed`, import a validated `dbs-content-system` JSON snapshot, and attach traceability after the script and V4 scene manifest exist. The current VOX profile rejects this mode until its manifest-based traceability contract is implemented.
-
-## Content-system bridge sequence
-
-```bash
-python3 book_video_factory/scripts/content_bridge.py export-dbs \
-  --content-root /path/to/content-system \
-  --assembly /path/to/content-system/06-选题装配/topic.md \
-  --output /path/to/package.json
-python3 book_video_factory/scripts/content_bridge.py validate-package --package /path/to/package.json
-python3 book_video_factory/scripts/content_bridge.py import-package \
-  --project book_video_warehouse/projects/<slug> --package /path/to/package.json
-python3 book_video_factory/scripts/content_bridge.py attach-traceability \
-  --project book_video_warehouse/projects/<slug> --map /path/to/traceability.json
-python3 book_video_factory/scripts/workflow.py approve \
-  --project book_video_warehouse/projects/<slug> --release-id <release-id> \
-  --gate traceability --decision approved --reviewer '<reviewer>' \
-  --subject 02_story_script_故事脚本/traceability/<release-id>/<attached-map>.json
-python3 book_video_factory/scripts/content_bridge.py status \
-  --project book_video_warehouse/projects/<slug> --require traceability
-```
-
-See `book_video_factory/docs/CONTENT_SYSTEM_BRIDGE.md` in the bootstrapped runtime for the package contract and fail-closed rules.
-
-## First-run review questions
-
-- Is the user entitled to use the cover, quotations, BGM, sound effect, voice reference, and reference style?
-- Are medical, mental-health, financial, or legal claims framed as non-diagnostic editorial commentary rather than advice?
-- Has a native reviewer approved the English copy if this will be published internationally?
-- Are all provider usage/cost figures sourced from real provider telemetry rather than inferred from output files?

package/skills/book-video-factory/references/paper-collage-explainer.md

@@ -1,127 +0,0 @@
-# VOX风格图书视频
-
-Machine ID: `paper-collage-explainer-v1`
-
-这是图书视频工厂新增的第二种风格，不替代原有的 `book-editorial-bilingual-v2`。它用 9:16 原创编辑型纸拼贴、证据导向图解和克制动画解释高信息密度概念；“VOX风格”只是便于用户识别的公开描述，不代表与 Vox Media 存在合作、授权或隶属关系。提示词不得要求复制任何具体节目、logo、片头、字体系统或专有品牌包装。
-
-## 两种风格如何选择
-
-| 公开名称 | Machine ID | 适合场景 | 核心交付 |
-| --- | --- | --- | --- |
-| 双语编辑模板图书视频（原风格） | `book-editorial-bilingual-v2` | 真实书封驱动、3:4、双语包装、确定性批量渲染 | 12 张批准静帧 + 本地旁白/字幕 + FFmpeg 母版 |
-| VOX风格图书视频（新增风格） | `paper-collage-explainer-v1` | 9:16、高信息密度、视觉隐喻和解释型动画 | 每个信息变化一条 4–8 秒 visual beat + 本地旁白/字幕/音频母版 |
-
-创建项目时必须显式选择 VOX 风格的生成渠道：
-
-```bash
-# Gemini API 程序化渠道
-python3 <SKILL_ROOT>/scripts/bootstrap_workspace.py \
-  --workspace . --slug <slug> --book-title '<title>' --author '<author>' \
-  --style-profile paper-collage-explainer-v1 \
-  --generation-lane gemini-api
-
-# Google Flow 手工导演渠道
-python3 <SKILL_ROOT>/scripts/bootstrap_workspace.py \
-  --workspace . --slug <slug> --book-title '<title>' --author '<author>' \
-  --style-profile paper-collage-explainer-v1 \
-  --generation-lane google-flow
-```
-
-项目会绑定 `book-vox-vertical-9x16-v1` 发布配置。Skill 提供提示词、审批、导入、本地时间线、音频、QC 与交付编排；仓库当前不宣称内置“一键调用 Google 生成完整成片”的执行器。
-
-当前 VOX 风格只支持 `single-book`。现有 `content-system-backed` 追溯仍绑定原风格的 V4 scene-line contract；在 manifest-based 追溯实现并通过测试前，初始化器会拒绝把 VOX 风格与该模式组合，避免生成伪追溯记录。
-
-## 生成渠道
-
-### Gemini API：程序化生成
-
-仅在用户授权付费生成并提供 `GEMINI_API_KEY` 后使用；密钥只从环境读取，不写入项目、日志、manifest 或提示词。
-
-- 默认模型：Gemini Omni Flash，API ID 为 `gemini-omni-flash-preview`，通过 Interactions API 调用。它是 preview 能力。
-- Gemini Omni 不支持视频延长或首尾帧插值；需要首尾帧控制或视频延长时，改用 Veo 3.1，API ID 为 `veo-3.1-generate-preview`，通过 `generate_videos` 调用。
-- Gemini Omni 没有独立 negative-prompt 参数；把限制写成普通提示词中的 `Do not ...` 约束。
-- 英文提示词是最稳妥的生产默认；其他语言可用性需逐次验证。
-- 超过内联响应限制的大文件使用供应商 URI 交付，并记录 URI/operation 与下载后哈希。
-- 每次请求记录模型/API surface、提交时间、operation/job ID、完整提示词、输入资产哈希、输出哈希、供应商暴露的用量/费用和失败原因。不可获得的数据记为 `—`，不能猜零。
-
-运行生成前：
-
-```bash
-python3 book_video_factory/scripts/doctor.py \
-  --profile production \
-  --project book_video_warehouse/projects/<slug>
-```
-
-官方依据：<https://ai.google.dev/gemini-api/docs/omni>、<https://ai.google.dev/gemini-api/docs/veo> 与 <https://ai.google.dev/gemini-api/docs/video>。
-
-### Google Flow：手工导演与导出
-
-Flow 是用户操作的创作工作台，本 Skill 不假设存在可编程 Flow API。
-
-- 前提取决于当前地区、年龄、账号类型、合格 Google AI 方案和可用 credits；运行前在官方帮助页复核。
-- 桌面 Chromium 是推荐环境，不表述为唯一支持方式。
-- 只导入用户合法导出的文件；不读取或绕过登录、credits、区域或下载限制，也不把 UI 预览当成可发布资产。
-- 每条片段保存 Flow prompt、输出日期、界面可见 credits、导出文件、SHA-256、`scene_id` 和人工审核结论。
-
-官方依据：<https://support.google.com/flow/answer/16353333> 与 <https://support.google.com/labs/answer/16935308>。
-
-## 风格圣经
-
-### 画面语言
-
-- 9:16 竖屏；主体在中央安全区，前景纸屑/中景主隐喻/背景档案纹理分层。
-- 纸张撕边、丝网印刷颗粒、剪报、有限配色、清晰留白；每个项目先锁定 4–6 个主色和 1 个强调色。
-- 用证据关系、尺度、路径、对比和因果变化组织画面，不用无信息的“漂亮拼贴”。
-- 生成片段不放可读文字、字幕、logo 或仿制书封；标题、数据、引文和字幕在本地时间线统一排版。
-
-### 动画语法
-
-每个 4–8 秒 visual beat 只有一个主要信息变化、一个主隐喻和一个主动作：
-
-- `reveal`：撕开纸层，露出隐藏路径或证据。
-- `trace`：纸线/箭头沿路径生长，表达过程或因果。
-- `compare`：两个剪纸对象缩放、对齐或错位，表达差异。
-- `accumulate`：图表、台阶或容器逐层增长，表达积累。
-- `transform`：同一对象在受控范围内改变状态，表达前后变化。
-- `parallax`：前中后景轻微视差，增强层次，不抢叙事。
-
-镜头只选轻推近、轻平移或固定机位之一。避免快速旋转、强闪烁、无控制 morph、复杂对白、多动作竞争和与口播无关的装饰运动。
-
-## 核心工作流
-
-1. **资料审计**：锁定书籍元数据、可归因资料、Claim 边界和风险说明；读者评论不能当事实证据。
-2. **脚本与旁白锁定**：先批准中文脚本，再生成/录制授权旁白并取得真实 ASR 时间。把旁白拆为每 4–8 秒一次信息变化；不要先生成视频再强行拉伸口播。
-3. **Gate 1 — 隐喻**：每段填写 `概念 → 可见关系 → 主动作 → 禁止项`，审批后再生图。
-4. **Gate 2 — 首/尾帧或联系表**：检查焦点、安全区、材质、配色、隐喻重复、文字污染、解剖错误、logo 和可见水印。未通过不得生成完整片段。
-5. **Gate 3 — 片段 QA**：通过选定渠道生成；检查时长、画幅、可解码性、动作连续性、尾帧漂移、嵌字、可见水印和 provenance。每条片段单独通过。
-6. **规范化**：把批准素材转换为静音 720×1280 H.264 MP4，再以不变速方式规范化到 30 fps 本地时间线；默认不做光流补帧。
-7. **Picture lock**：按旁白/ASR 时间组装 visual beats，加入本地标题、字幕、真实书封或品牌层。图片锁定后再进入最终音频混合。
-8. **声音设计**：旁白优先；BGM 先过权利审查，再单独过 `bgm_review` 人耳审听；SFX 只强调关键转折。生成片段的原生音频默认移除。
-9. **技术与人工 QC**：验证完整解码、720×1280、30 fps、H.264/AAC、A/V 时长、字幕安全区、约 −16 LUFS、真峰值上限、黑帧和输出哈希。
-10. **交付与发布**：`local_master_review`、`publish` 分开审批。若做公开仓库案例，另建 `showcase_publish`，绑定压缩/遮盖后的预览哈希和权利范围。
-
-完整 gate 定义以 [quality-gates.md](quality-gates.md) 为准。
-
-## 单镜头提示词模板
-
-提示词使用非品牌化描述，并把每条视频限制为一个可见动作：
-
-```text
-Purpose: <the single relationship the viewer must understand in this beat>.
-Visual metaphor: <visible relationship among paper cutouts, objects, paths, or evidence shapes>.
-Composition: vertical 9:16, main subject inside the central safe area, layered foreground / midground / background.
-Material: original editorial paper-collage, torn paper edges, archival grain, restrained 4–6 color palette, deliberate negative space.
-Primary action: <one reveal / trace / compare / accumulate / transform action>.
-Camera: <locked / gentle push-in / gentle lateral move>, subtle layered parallax only.
-Continuity: preserve subject identity, palette, lighting direction, paper texture, and spatial layout from the approved frame.
-Do not include logos, readable text, subtitles, book-cover replicas, visible third-party watermarks, brand/program imitation, rapid rotation, flashing, uncontrolled morphing, multiple competing actions, or talking characters.
-Audio: silent visual asset; narration, captions, BGM, and SFX are added in the local master.
-```
-
-若使用 Gemini Omni，不要把 `Avoid/Do not` 区域误当成不存在的独立 negative-prompt 参数；它属于普通提示词正文。
-
-## 最低资产 manifest
-
-每个生成片段至少记录：`release_id`、`scene_id`、`script_line_id`、`provider_lane`、`model_or_flow`、`api_surface`、`prompt`、`input_hashes`、`output_path`、`output_sha256`、`duration_seconds`、`width`、`height`、`fps`、`audio_policy`、`gate_1`、`gate_2`、`gate_3`、`reviewer`、`operation_or_export_evidence`、`cost_evidence`、`synthid_policy`。
-
-字段或审批缺失时，片段不得视为可复用、可交付或可发布资产。

package/skills/book-video-factory/references/quality-gates.md

@@ -1,87 +0,0 @@
-# Release quality gates
-
-## Project contract
-
-- `project.json` must identify the book/topic, workflow mode, `style_profile_id`, `release_profile_id`, and generation lane. A missing `style_profile_id` is treated as the original `book-editorial-bilingual-v2` only for backward compatibility.
-- The two built-in styles are independent contracts: the original **双语编辑模板图书视频** and the new **VOX风格图书视频**. Never combine their frame, asset, renderer, or approval assumptions silently.
-- Each stage writes an immutable manifest or append-only cost event. Each revision uses a new `release_id` and delivery directory; an approved master is never overwritten.
-- `workflow.py evaluate --project <project> --release-id <release-id>` resolves the release profile from the project, then derives state from files, hashes, QC, and approval events. Direct edits to `project.json.status` cannot advance a gate, and approvals from different releases are never combined.
-
-## Common editorial and rights gates
-
-- `topic` — a human approves the topic and intended audience.
-- `source` or `source_audit` — every factual claim and quotation has attributable evidence; reader comments remain opinions, not book facts.
-- `script` — approval binds to the current script hash. Any script edit invalidates the decision.
-- `voice_rights` — narration or voice-clone authorization is recorded. Never clone a public figure, another creator, or an unconsenting person.
-- `bgm_rights` / `sfx_rights` — provenance records creator/provider, licence or user authorization, source URL or file hash, attribution requirements, and account-terms caveats.
-- `cover_rights` — required when a real book cover or cover-derived frame is used. A generated imitation is never accepted as a substitute for the real cover.
-- `english_native` — required only when English copy or subtitles are delivered; keep English marked `needs_native_review` before approval.
-- `publish` — a human approval bound to the exact delivery output hash. Technical QC or local-master approval is not publication approval.
-
-## Content-system-backed gates
-
-- The package preserves source registry rows, source-copy hashes, complete content-unit fields/body, materialized Claims, and a structured assembly brief.
-- Only `回应 / 解释 / 证明 / 冲突` relationships are accepted. Unknown types are rejected rather than silently normalized.
-- All five main unit types are present for a production-eligible assembly, selected units are canonical, and used Claims are reviewed or approved.
-- The source approval binds the active package snapshot; traceability covers every script line exactly once and uses the active renderer scene contract.
-- A human `traceability` approval binds the attached map hash. Automated structural validation cannot approve semantic Claim-to-script links.
-- `single-book` projects remain compatible and do not inherit these additional content-system gates.
-
-## Style A — 双语编辑模板图书视频（原风格）
-
-Machine ID: `book-editorial-bilingual-v2`  
-Release profile: `book-v4-bilingual-3x4`
-
-- Exactly 12 distinct approved stills exist as `S01.png` through `S12.png`.
-- Every still is topic-specific, text-free, and free of a copied cover design or visible watermark.
-- The real cover has provenance and a passed `cover_rights` decision.
-- The local master is 720×960, 3:4, 30 fps, H.264/AAC, includes readable bilingual captions, and respects the configured title/subtitle safe areas.
-- The V4 QC report carries the same `release_id` as its approvals and reports `local_master_status: pass`.
-- Required publish approvals are `script`, `cover_rights`, `bgm_rights`, `sfx_rights`, `voice_rights`, `english_native`, and `publish`, in addition to the state-sequence approvals for topic, source, and timing.
-
-## Style B — VOX风格图书视频（新增风格）
-
-Machine ID: `paper-collage-explainer-v1`  
-Release profile: `book-vox-vertical-9x16-v1`
-
-“VOX风格” is a user-facing descriptive label for an original editorial explainer treatment. It does not claim affiliation with Vox Media and must not be used as an instruction to copy a named program, logo, brand package, or proprietary graphic system. Generation prompts use non-branded visual descriptors.
-
-The built-in VOX profile currently supports `single-book` only. The existing `content-system-backed` traceability implementation is tied to the original V4 scene-line contract and fails closed for VOX projects.
-
-### Editorial and visual gates
-
-1. `source_audit` — the evidence pack and claim boundaries are reviewed.
-2. `script` — narration is concise, voice-led, and split into one information change per 4–8-second visual beat.
-3. `timing` — narration and ASR timing are locked before full clip generation. Do not stretch narration to fit generated footage after the fact.
-4. `gate_1_metaphor` — each beat states `concept → visible metaphor → main action → prohibited elements`. One primary metaphor and one primary motion per beat.
-5. `gate_2_still` — approve the first frame, optional last frame, or contact sheet. Check focal hierarchy, 9:16 safe area, paper texture, palette continuity, repeated metaphors, anatomy, embedded text, logos, and visible watermarks.
-6. `gate_3_clip_qa` — approve every generated clip and its manifest. Verify scene ID, prompt, provider/model or Flow label, input/output hashes, duration, dimensions, decodability, continuity, QA decision, and cost/credits evidence.
-
-### Clip and motion contract
-
-- Generated clips are 9:16 H.264 MP4 visual beats. The asset manifest, rather than a universal scene count, defines how many clips the release uses.
-- Clip IDs and hashes are unique; every referenced file exists and its recorded SHA-256 matches.
-- Generated clips contain no embedded captions and are absent of audio or stripped before local assembly. Generated native audio is not treated as the final mix source.
-- Acceptable motion grammar includes paper-layer reveal, cutout slide, path trace, chart growth, object comparison, restrained parallax, and gentle push-in. Avoid rapid orbiting, uncontrolled morphing, flash cuts, decorative motion unrelated to narration, and multiple competing actions.
-- Invisible provider provenance such as SynthID is allowed and must not be removed or tampered with. Reject visible third-party watermarks or ownership marks.
-
-### Local timeline, picture lock, and audio gates
-
-- Normalize provider clips to the 720×1280, 30 fps local timeline without changing playback speed. Inspect cadence; optical-flow interpolation is off by default.
-- Keep titles within 48 px horizontal margins. Keep subtitles inside the 48 px horizontal and 120 px bottom safe areas defined by the release profile; fail closed on overflow.
-- `timing` binds the narration/ASR map. `local_master_review` binds the exact H.264/AAC master after picture lock.
-- `bgm_rights` validates provenance; `bgm_review` is a separate human listening decision for mood, repetition, speech masking, transitions, and ending. A rights-valid track can still fail creative review.
-- `audio_qc` targets approximately −16 LUFS integrated, accepts the project-approved delivery range, and keeps true peak at or below the configured −1.2 dBFS ceiling. Confirm no clipping, missing channel, abrupt cut, or inaudible narration.
-- Technical QC checks full decode, 720×1280, constant 30 fps delivery, H.264/AAC, A/V duration agreement, black frames, caption safe area, and output hash.
-
-### Publish and showcase gates
-
-- Required production approvals are `source_audit`, `script`, `gate_1_metaphor`, `gate_2_still`, `gate_3_clip_qa`, `timing`, `voice_rights`, `bgm_rights`, `bgm_review`, `sfx_rights`, `audio_qc`, `local_master_review`, and `publish`.
-- `cover_rights` is added when a real cover or cover-derived frame is present. `english_native` is added when English is delivered.
-- A public repository demo is a separate derivative. Require `showcase_publish` bound to the preview hash, plus a sanitized gate summary that records source-manifest/event hashes, redactions, transcoding, rights scope, unresolved production gates, and the distinction between source local-master approval and public-showcase approval. State provider-account rights as operator attestations unless independently verified.
-
-## ChatCut handoff gate
-
-- Import only a locally QC-passed master and its subtitle file.
-- Record the editor project ID, edit summary, export path, reviewer, revision label, and any generated BGM asset/provenance.
-- Keep the local master immutable and publish the ChatCut export as a distinct derivative version.