@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/package-talking-head-video/references/motion-and-illustration.md

@@ -1,25 +0,0 @@
-# Motion and integrated line illustrations
-
-## Seek-safe motion primitives
-
-`hit`, `slide`, `lift`, `stamp`, `route`, `trace`, `count`, `reveal`, `relay`, and `focus` are deterministic functions of frame, fps, start frame, and duration. The same frame must always render the same state.
-
-- Use `hit` for a short hook or conclusion, not every heading.
-- Use `route` and `trace` for actual paths, loops, and staged progress.
-- Use `count` only for attributed metrics.
-- Use `focus` for a selected command, source, or proof detail.
-- Never use timers, random values, runtime state, or CSS transitions that depend on playback history.
-
-## Semantic doodle contract
-
-An integrated doodle has three explicit layers:
-
-1. `line`: the subject and stable environment;
-2. `action`: the force, route, movement, or transformation;
-3. `outcome`: the resulting state.
-
-The `semantic-doodle` structure keeps the drawing inside the composition hierarchy instead of placing it in a detached generic card. It receives `subject`, `action`, `outcome`, and one accent color from the storyboard.
-
-Use programmatic SVG with explicit `fill="none"`, explicit stroke attributes, rounded caps/joins, and frame-derived drawing progress. Avoid logos, brand imitation, decorative text inside the drawing, and unsupported product claims.
-
-Existing reusable drawing scenarios include information overload, climbing a difficult path, balancing tradeoffs, following a fast route, activating connected nodes, and showing a before/after transformation. The semantic content decides which scenario is valid.

package/skills/paper-cut/SKILL.md

@@ -1,164 +0,0 @@
----
-name: paper-cut
-description: "Create, resume, revise, and render editable image-led paper-cut collage explainer videos with approved AI-generated hero-frame stills, original-frame layer extraction, AICUT HTML/CSS/GSAP motion, narration, paper SFX, optional collage typography, and deterministic QA. Use for Paper Cut, Vox-style paper collage, code-animated collage B-roll without a video model, layered cutout animation, or turning a topic, script, article, or reference video into an editable horizontal or vertical collage explainer. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "aijiduonadegou/Paper-Cut"
----
-
-# Paper Cut
-
-## 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.
-
-
-Make the image model responsible for art direction and hero-frame composition. Make HyperFrames responsible for motion, camera, timing, transitions, audio, and reproducibility. Do not substitute code-drawn vector art for a requested paper-collage still, and do not substitute a video model unless the user explicitly changes the method.
-
-## Start or resume
-
-1. Find `paper-cut-project.json`. If present, read it and `assets-manifest.json`, resume from `stage`, and preserve approvals.
-2. For a new project, collect only the topic/source, target duration, aspect ratio, language, narration/caption/music requirements, and visual direction.
-3. Run `scripts/check_environment.py`; report only and do not install anything silently.
-4. Read [references/workflow.md](references/workflow.md) and obey all three gates.
-5. Before asset production, read [references/image-led-production.md](references/image-led-production.md) and [references/asset-spec.md](references/asset-spec.md).
-6. Before authoring or rendering, read the installed HyperFrames entry, core, animation, keyframes, creative, and CLI skills.
-
-## Non-negotiable method
-
-- Storyboard before generation. Every scene needs a precise hero-frame composition, not a generic asset list.
-- Show real image-model hero frames at Gate 1/2 when the user needs to judge the look; a code vector diagram is not a substitute.
-- Generate or approve the complete scene still first. Treat it as the visual source of truth.
-- Extract the few layers that truly need motion from that approved still. Preserve the original background, texture, silhouettes, print registration, torn edges, and native shadows.
-- Prefer local masking/matting from the original still. Generate a clean plate only when extraction leaves an unavoidable hole. Never regenerate every subject on green solely to simplify animation.
-- Move only narrative focal elements. Use generated typographic cutouts and slow camera motion to add energy while the rest of the scene preserves the approved still.
-- Keep the layered composition visible through the whole shot. Never swap to the untouched master still for the final second.
-- Use overlapping scene transitions. Never leave an uncovered gap that can produce a white, black, or stale frame.
-- Keep image-generation attempts, originals, derivatives, hashes, and approvals in `assets-manifest.json`.
-- Do not call paid or quota-consuming image, voice, sound, or video providers before Gate 2 explicitly approves the provider and maximum attempts.
-- Distinguish subtitles from designed keywords. “No subtitles” removes sentence-by-sentence captions; it does not remove a few editorial wordmarks unless the user also says “no on-screen text.”
-
-## Project records
-
-Maintain:
-
-- `video-script.md`: approved narration and factual/rights notes;
-- `storyboard.md`: timestamps, hero frames, layers, text, motion, and transitions;
-- `paper-cut-project.json`: stage, approvals, providers, attempt caps/usage, timings, and delivery paths;
-- `assets-manifest.json`: every original, processed derivative, generated type asset, audio asset, attempt ID, and SHA-256;
-- `DESIGN.md`: shared paper stock, print process, palette, typography, shadow, and motion rules.
-
-Read [references/storyboard-schema.md](references/storyboard-schema.md) before writing machine-readable state.
-
-## Gate 1 — narration and storyboard
-
-Provide:
-
-- one-sentence thesis and factual-risk notes;
-- final narration with estimated spoken duration;
-- a scene table with timestamps, purpose, visual metaphor, exact hero-frame composition, fixed background, candidate moving layers, on-screen text, and transition;
-- aspect ratio and visual direction;
-- map, identity, copyright, financial, medical, legal, or scientific claims needing verification.
-
-Ask for explicit approval. Record it in `approvals.storyboard`. Revision feedback does not pass the gate.
-
-## Gate 2 — visual proof and budget
-
-Provide:
-
-- one representative image-model hero frame or the complete scene still set needed for visual judgment;
-- the exact fixed-background versus moving-layer plan for every scene;
-- which layers will be extracted from the approved still and which holes require a clean plate;
-- all proposed generated typographic cutouts with exact approved text;
-- image, voice, and sound providers, maximum attempts, current usage, and known cost/credit implications;
-- a clear statement that no video model will be used unless approved.
-
-Ask for explicit approval before generation. Preserve provider originals and make derivatives separately.
-
-## Asset production
-
-Follow [references/image-led-production.md](references/image-led-production.md).
-
-1. Generate/approve scene hero frames in storyboard order.
-2. Inspect every still at full resolution for text errors, sensitive borders, anatomy, edge debris, inconsistent paper, and unintended symbols.
-3. Select only the focal motion layers. Typical choices are a sun plus heat waves, one pressure lid, one route pair, or one wordmark.
-4. Extract those pixels from the approved frame with their paper edge and shadow when possible.
-5. Build a clean plate by local inpainting/compositing only where the extracted subject exposes a hole.
-6. Generate transparent typographic collage assets only after the exact text list is approved. Keep secondary labels code-native for legibility and editability.
-7. Crop transparent margins without flattening alpha or replacing the original shadow.
-
-Use `scripts/normalize_asset.py` only for standalone cutouts that benefit from a normalized square canvas. Do not normalize wide wordmarks or full-frame scene layers.
-
-## Assemble in HyperFrames
-
-Read [references/hyperframes-assembly.md](references/hyperframes-assembly.md).
-
-- Build each approved hero frame statically before motion.
-- Create a synchronous paused GSAP timeline and register it in `window.__timelines`.
-- Use deterministic transforms, opacity, clip paths, and finite cycles only. No randomness, infinite repeats, async timeline construction, CSS transitions, or CSS keyframes.
-- Animate the main subject first, one explanatory element second, and use a 3–6% slow push/pull/pan as background energy.
-- Use generated wordmarks as transparent PNG layers with restrained slap/slide/stamp entrances. Keep text safely inside camera-scaled bounds.
-- Treat the outgoing scene transition as its exit. Keep both scenes overlapped until the handoff is fully covered.
-
-## Audio revisions
-
-Read [references/audio-and-chatcut.md](references/audio-and-chatcut.md) when narration or sound is present.
-
-- Treat narration timestamps as timing truth.
-- For a script deletion, locate the spoken words by transcription, make a non-destructive audio cut with a short crossfade, audition the join, then shift every downstream scene, SFX, text, camera, assertion, and composition duration by the exact removed interval.
-- Do not regenerate an approved voice when a clean edit is sufficient.
-
-## Gate 3 and deterministic QA
-
-Run:
-
-```powershell
-python scripts/validate_project.py <project-dir>
-npx -y @autoaiai/aicut@latest open .
-```
-```
-For substantive work, also run the HyperFrames animation map and focused `keyframes --shot` diagnostics. Inspect:
-
-- first visible frame and every hero frame;
-- 0.1 seconds before/after every transition;
-- all generated wordmarks under maximum camera scale;
-- the narration edit join;
-- final frame and final hold.
-
-Render only a draft preview before Gate 3. After explicit approval, render delivery quality and inspect the final encoded MP4 itself. Verify resolution, duration, fps, video/audio streams, first/last frames, transition contact sheet, and run FFmpeg black-frame detection. Record the final file and QA evidence in project state.
-```
-
-## Completion
-
-Deliver the editable HyperFrames project, state files, approved MP4, QA evidence, provider/attempt summary, generated originals, local derivatives, and known limitations. External upload or publication requires explicit authorization.
-
-## Source
-
-Rewritten for AICUT from [`aijiduonadegou/Paper-Cut`](https://github.com/aijiduonadegou/Paper-Cut)
-(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/paper-cut/references/asset-spec.md

@@ -1,47 +0,0 @@
-# Asset specification
-
-## Manifest record
-
-```json
-{
-  "id": "scene-02-hero-title",
-  "sceneIds": ["scene-02"],
-  "role": "type",
-  "sourcePath": "assets/originals/scene-02-hero-title.png",
-  "processedPath": "assets/processed/scene-02-hero-title.png",
-  "alphaRequired": true,
-  "status": "approved",
-  "provider": "approved-image-provider+local-alpha-crop",
-  "attemptId": "provider-attempt-id",
-  "sha256": "...",
-  "notes": "Exact approved text; image call 4 of 12."
-}
-```
-
-Roles: `background`, `subject`, `prop`, `texture`, `type`, `audio`, `reference`. Statuses: `planned`, `generated`, `processed`, `approved`, `rejected`, `superseded`.
-
-## Scene-first separation
-
-- Generate/approve the complete hero frame before separating layers.
-- Keep all fixed environment, texture, and nonessential decoration in the background.
-- Extract each independently moving focal subject or prop from the approved still.
-- Keep native silhouette, torn edge, print texture, and shadow.
-- Create a clean plate only for pixels exposed by extraction.
-- Avoid green-screen regeneration when the original pixels can be masked.
-- Preserve provider originals under `assets/originals/`; write every derivative separately.
-
-## Text
-
-- Keep subtitles, paragraphs, scientific labels, numbers, and revisable data as HTML/SVG.
-- Generate only short, approved hero wordmarks when collage typography materially improves the scene.
-- Reject any wordmark with a wrong character, punctuation, baked checkerboard, clipped paper edge, or inconsistent shadow.
-
-## Visual consistency
-
-Lock paper stock, edge treatment, print process, grain, shadow direction/depth, palette, and illustration register across prompts. Do not normalize a full-frame scene into a square canvas. Normalize only standalone cutouts where consistent occupancy is useful.
-
-## Local derivatives
-
-Cropping transparent margins, alpha cleanup, masking, local inpainting, compositing, mirroring, resizing, color correction, shadow repair, paper outlines, and texture overlays are local derivatives and do not consume provider attempts.
-
-Reject disconnected edge debris, clipped silhouettes, inconsistent paper, obvious watermark residue, unintended geographic symbols, or unreadable generated text.

package/skills/paper-cut/references/audio-and-chatcut.md

@@ -1,26 +0,0 @@
-# Audio and ChatCut handoff
-
-## Narration is timing truth
-
-Generate or import one approved clean master track, then obtain word-level timestamps before locking scenes, captions, SFX, and camera cues. Audition a short voice sample before a paid full take.
-
-## Shortening approved narration
-
-When the user deletes a passage:
-
-1. locate the first and last deleted spoken words from transcription;
-2. cut only that interval from a derivative audio file;
-3. add a short crossfade at the join and audition it;
-4. preserve the approved voice instead of regenerating it;
-5. subtract the exact removed duration from every downstream scene, SFX, text cue, camera move, assertion, and total duration;
-6. recheck transitions and the final hold.
-
-## Captions and key text
-
-Keep captions as structured timestamp data, never baked into scene images. Hero wordmarks are not subtitles: use them selectively and keep normal labels editable.
-
-## ChatCut optional path
-
-Use ChatCut when the user wants a specific Chinese voice, transcription, subtitle correction, generated SFX/music, an editable finishing timeline, or ChatCut export. Load the relevant ChatCut skills and keep the HyperFrames project as the animation master.
-
-Do not rebuild the collage as ChatCut AI video generation. A hybrid requires explicit approval and separate labeling of generated video inserts.

package/skills/paper-cut/references/hyperframes-assembly.md

@@ -1,47 +0,0 @@
-# HyperFrames paper-cut assembly
-
-## Reconstruct the approved hero frame
-
-Place the fixed clean plate first, then extracted layers at the exact scale and coordinates of the approved still. Add generated wordmarks and code-native labels last. Compare a static snapshot with the approved hero frame before adding motion.
-
-Use depth roles: fixed paper environment, narrative focal layers, then foreground type/accents. Avoid centered web-card layouts and flat code-drawn infographic substitutes.
-
-## Motion hierarchy
-
-Use physical paper verbs:
-
-- `slap`: scale 1.12–1.20 to 1 with slight rotation correction;
-- `slide`: enter from an edge with a small skew/rotation;
-- `drop`: enter from above and settle;
-- `peel`: clip-path reveal;
-- `stamp`: fast type impact;
-- `drift`: finite 6–18px motion;
-- `camera`: slow 3–6% push/pull/pan on a wrapper;
-- `page-push`: overlapping scene handoff.
-
-Animate the hero first and one explanatory element second. Keep decoration fixed. Camera motion and wordmarks may provide energy when only one subject moves.
-
-## Transform ownership
-
-Use separate wrappers when the same visual needs entrance motion and camera motion. Do not write competing transforms to one node. Keep camera movement on the scene-camera wrapper and object motion on child layers.
-
-## HyperFrames contract
-
-- Put the standalone `data-composition-id` element directly in `body`.
-- Declare start, duration, track index, width, and height.
-- Create a synchronous `gsap.timeline({paused:true})` and register it in `window.__timelines`.
-- Animate transforms, opacity, and clip paths; avoid layout properties.
-- Never animate display/visibility, use randomness, infinite repeats, asynchronous timeline construction, CSS transitions, or CSS keyframes.
-- Use deterministic media paths and framework-owned audio playback.
-
-## Transitions
-
-Overlap outgoing and incoming scene bodies. Keep the outgoing frame assembled until the incoming scene or transition cover is opaque. Do not set the outgoing scene to zero opacity before the handoff. Do not reintroduce the untouched master still as a final settle.
-
-## Text safety
-
-Place generated wordmarks inside bounds that remain safe under the maximum camera scale and their entrance overshoot. Use motion assertions such as `staysInFrame`. Give secondary labels high-contrast paper strips or ink chips; avoid plain black text over dark collage textures.
-
-## QA
-
-Inspect first frame, every hero, text overshoots, 0.1 seconds before/after transitions, audio edit joins, and final hold. Run lint, check with transition samples, animation map, and focused keyframe onion shots. After final rendering, inspect the encoded MP4 with FFprobe, extract a contact sheet from the MP4, and run FFmpeg `blackdetect`.

package/skills/paper-cut/references/image-led-production.md

@@ -1,65 +0,0 @@
-# Image-led production
-
-## Source-of-truth rule
-
-Treat each approved complete scene still as the visual source of truth. The still locks composition, paper stock, halftone density, torn edges, palette, lighting, shadow direction, and relative scale. Animation must preserve that lock.
-
-## Generate whole scenes before parts
-
-Prompt from the storyboard's exact composition: subject positions, negative space, visual hierarchy, paper materials, print process, and intended text-safe zones. Do not generate a bag of generic suns, globes, maps, and people and then improvise a composition in code.
-
-When the user asks to see a storyboard, show real raster hero frames from the image model. A flat vector schematic may accompany them as an annotation, but cannot replace them.
-
-## Choose motion layers
-
-For each scene, rank elements:
-
-1. narrative hero — normally animate;
-2. explanatory mechanism — animate only if it clarifies causality;
-3. atmosphere and decoration — normally keep fixed;
-4. text — animate selectively;
-5. camera — add a slow 3–6% push, pull, or pan.
-
-Two to four active channels are usually enough. If everything moves, the scene loses the approved composition and increases masking failures.
-
-## Extraction order
-
-1. Extract the selected element from the approved still with structure-aware masking/matting.
-2. Preserve native paper edge, halftone texture, contact shadow, and irregular outline.
-3. If the shadow cannot be separated cleanly, either keep it with the layer or rebuild a restrained directional CSS shadow that matches the still.
-4. Repair only the exposed hole in the fixed background. Prefer local inpainting or selective compositing.
-5. Generate a replacement clean plate only when local repair cannot preserve the scene.
-
-Do not regenerate selected elements on green solely because chroma removal is easy. Regeneration changes shape, texture, lighting, and shadow and often breaks continuity with the approved still.
-
-## Transparent typography
-
-Use an image model for a few hero wordmarks when typography itself is part of the collage art. Before generation:
-
-- approve the exact characters and punctuation;
-- limit each asset to one short phrase;
-- request direct alpha transparency, real torn paper, print texture, and an integrated physical shadow;
-- inspect every character at full resolution;
-- preserve the original and make a separate alpha-cropped derivative.
-
-Keep secondary labels code-native for factual accuracy, contrast, and easy revision. Never rely on generated type for paragraphs or subtitles.
-
-Treat subtitles and editorial type as separate switches. A request for no subtitles still permits a restrained keyword/wordmark plan unless the user explicitly requests no text anywhere on screen.
-
-## Clean-plate and settle behavior
-
-The clean plate plus extracted layers is the scene for its entire duration. Do not place the untouched master still on top at the end as a settle frame: that creates a visible one-frame or one-second jump and hides the motion layers.
-
-## Sensitive maps and boundaries
-
-Determine whether directional language refers to a country, a region, or a global pattern. If geographic boundaries are not necessary, use borderless environmental contrasts, abstract ocean/land textures, pressure diagrams, or circulation paths. Do not introduce country borders, administrative lines, flags, disputed outlines, or labels merely as decoration.
-
-## Reuse test
-
-Before another image call, ask:
-
-- Can the approved still be cropped, masked, mirrored, recolored, or locally repaired?
-- Can a secondary label remain HTML text?
-- Is the difference visible at delivery resolution?
-
-If yes, use a local derivative and record it without consuming another provider attempt.

package/skills/paper-cut/references/storyboard-schema.md

@@ -1,48 +0,0 @@
-# Storyboard and project schema
-
-## Project state
-
-```json
-{
-  "schemaVersion": 1,
-  "slug": "example",
-  "stage": "storyboard-review",
-  "video": {"width": 1920, "height": 1080, "fps": 30, "durationSeconds": 50, "language": "zh-CN"},
-  "style": {"mood": "editorial, tactile", "palette": [], "paperTreatment": ""},
-  "approvals": {
-    "storyboard": {"approved": false, "note": "", "at": null},
-    "assets": {
-      "approved": false,
-      "note": "",
-      "at": null,
-      "providers": {},
-      "attemptCaps": {"image": 0, "voice": 0, "video": 0, "sound": 0},
-      "attemptUsage": {"image": 0, "voice": 0, "video": 0, "sound": 0}
-    },
-    "preview": {"approved": false, "note": "", "at": null}
-  },
-  "scenes": []
-}
-```
-
-## Scene record
-
-```json
-{
-  "id": "scene-01",
-  "start": 0,
-  "duration": 4.8,
-  "purpose": "state the mechanism",
-  "voiceover": "旁白原文",
-  "heroFrame": "可直接用于生图的完整构图说明",
-  "background": "scene-01-cleanplate",
-  "fixedElements": ["environment", "decorative-clouds"],
-  "movingLayers": ["sun", "heat-waves"],
-  "onScreenText": ["为什么这么热？"],
-  "motion": {"hero": "sun drops", "secondary": "heat waves reveal", "camera": "slow push 4%"},
-  "transition": {"type": "overlapping-paper-push", "duration": 0.35},
-  "safety": "no sensitive geographic boundary"
-}
-```
-
-Scene starts must be monotonic, durations positive, and the full composition long enough to contain every scene. Keep 0.1–0.3 seconds before the first entrance. Plan build, breathe, resolve, and transition phases. Earlier scenes exit through their transition; only the final scene may use a deliberate final exit.

package/skills/paper-cut/references/workflow.md

@@ -1,39 +0,0 @@
-# Paper Cut workflow
-
-## Stages
-
-Use `intake`, `storyboard-review`, `asset-review`, `asset-production`, `assembly`, `qa`, `preview-review`, then `delivery`. Write the current stage after each completed batch. Never infer approval from file existence.
-
-## Gate 1 — narration and storyboard
-
-Show the final narration and compact scene plan. Every scene needs a purpose, visual metaphor, exact hero-frame composition, fixed background, candidate moving layers, text plan, duration, transition, and relevant factual/safety notes.
-
-Passing response: explicit approval of narration and storyboard. Revision requests do not pass.
-
-## Gate 2 — visual proof, method, and budget
-
-Show at least one real image-model hero frame when the user needs to judge collage quality. Show every planned full-frame still, extraction, clean plate, type asset, provider, attempt cap, current usage, and first-use download. State explicitly whether a video model will be used.
-
-The cap counts provider calls, including rejected results. Local crop, alpha extraction, masking, compositing, color correction, shadow repair, and resizing do not count as new calls.
-
-Passing response: explicit approval of the image-led direction, provider choices, layer plan, and caps.
-
-## Gate 3 — encoded preview
-
-Validate the composition, inspect hero frames and transitions, then render a draft. Present the actual encoded preview with known limitations.
-
-Passing response: explicit approval of that preview. Only then render final quality.
-
-## Resume and revision rules
-
-- Read state and manifests before media folders.
-- Reuse approved assets whose hash and intended role are unchanged.
-- Do not regenerate an asset because the chat restarted.
-- Invalidate only changed scenes and dependent assets.
-- If timing changes but art does not, resume from assembly.
-- If narration deletes a passage, edit audio and shift downstream timing; do not regenerate approved visuals or voice unnecessarily.
-- If only text styling changes, preserve scene stills and generate only the approved wordmarks.
-
-## Provider boundary
-
-Environment checks are free and read-only. Installation, model downloads, cloud generation, voice cloning, and paid calls require approval. Never use a video-generation model as a silent fallback.