@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/make-blender-education-video/SKILL.md

@@ -1,247 +0,0 @@
----
-name: make-blender-education-video
-description: "Create high-detail, fact-checked English cinematic educational animations in Blender for science, engineering, architecture, construction, manufacturing, machines, infrastructure, energy, medicine, biology, computing, and other complex systems. Use for Blender-based explainer videos that require authoritative research or supplied sources, reusable topic-specific GitHub workflows and assets, a user-provided visual reference or defined style, a realistic or stylized 3D scene, burned-in subtitles, one representative approval frame before full rendering, and verified 4K delivery. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "sunxiayi/make-blender-education-video-skill"
----
-
-# Make Blender Education Video
-
-## 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.
-
-
-Create an English cinematic explainer that teaches a correct mental model and meets an explicit visual-quality reference.
-
-## Prerequisite: Blender must be installed
-
-Blender is a hard prerequisite for this skill. Before creating scenes, running Blender Python, or rendering any frame, verify that Blender is installed, launches successfully, and exposes a usable executable path. If it is missing, stop production and ask the user to download and install Blender from the official download page: <https://www.blender.org/download/>. Downloading the application alone is not sufficient; resume only after Blender is installed and runnable. Report the detected Blender version before proceeding.
-
-## Non-negotiable output
-
-- Produce English narration and burned-in English subtitles. Preserve official names, formulas, symbols, and necessary technical terms. Labels, legends, chapter cards, and teaching overlays are universally optional: never make them an intake, approval, production, QA, or delivery requirement. Omit them by default and add them only when the user explicitly requests them.
-- Generate all narration with **Kokoro-82M** (`hexgrad/Kokoro-82M`). Do not substitute a system voice, another local TTS model, a cloud TTS service, or a differently sized Kokoro model. If Kokoro-82M cannot be loaded, stop and report the dependency problem instead of silently falling back.
-- Voice selection is not a user-approval gate. Unless the user explicitly asks to audition or choose voices, select a suitable English Kokoro-82M voice autonomously, generate the production narration, and continue without presenting a voice sample or pausing for voice approval. Default to `af_heart` when the brief provides no contrary voice direction.
-- Interpret requests such as “no text in the picture,” “no on-screen text,” or “remove the labels/legend” as removing scene text, labels, legends, chapter cards, and teaching overlays only. These requests do **not** remove subtitles. Omit subtitles only when the user explicitly says “no subtitles,” “no captions,” or otherwise names subtitles/captions directly.
-- Produce a cinematic explainer only. Do not create a Blender UI tutorial, cursor recording, or hybrid tutorial.
-- Treat the single approval frame as approval of the **visual system only**: materials, lighting, composition, detail, depth of field, and subtitle treatment. It does not approve motion design, animation quality, pacing, process coverage, or explanatory completeness.
-- Animate the subject and the process for real in Blender. Every narrated process shot must show a meaningful frame-to-frame change in the relevant material, object, mechanism, flow, or system state, including the cause and visible effect. Camera movement alone does not count as process animation.
-- Never substitute a still image, slideshow, repeated frame, Ken Burns pan/zoom, 2.5D drift, or crossfade montage for an animation that is supposed to explain manufacturing, operation, construction, transformation, biological change, transport, or another dynamic process. Brief still holds are allowed only for establishing context, transitions, or emphasis; they must not carry the process explanation.
-- Burn English subtitles into the final picture using the required subtitle style below unless the user explicitly opts out of subtitles or captions.
-- Default to 16:9, 4K, and 30 fps unless the user requests different delivery specifications.
-- Never speed up, slow down, time-stretch, or time-compress generated narration, including micro-adjustments made only to fit shot boundaries. Treat native-speed narration as timing authority: regenerate it at the intended original speed when needed, then rearrange, extend, or retime the picture edit and rebuild subtitle timings around the resulting waveform.
-- Treat physical plausibility as a hard approval requirement. Every salient object, material, interface, and motion shown in a literal scene must have a real-world counterpart or authoritative reference at the depicted scale. Reject decorative or conceptual stand-ins that could be mistaken for literal equipment, material, or process behavior.
-- Never represent microscopic fibers, molecules, forces, field lines, flow, or other invisible phenomena as macroscopic solid rods, tubes, wires, or particles inside an otherwise literal scene. When such teaching imagery is necessary, isolate it in a clearly disclosed conceptual inset or scale-transition shot.
-- Preserve the real material of equipment in cutaways. Reveal an opaque vessel, housing, body, wall, or shell with a section cut, transparency treatment, or removable surface; do not replace it with a glass object unless the real object is made of glass.
-- Before showing an approval frame, inspect it at 100% and reject it for flat materials, alpha-dither noise, plastic-looking metal, unsupported visible objects, implausible scale, floating parts, missing contacts, or geometry that leaves its intended enclosure because of an incorrect transform origin.
-
-## Run the required intake first
-
-Before researching, planning, opening Blender, or creating an artifact, ask the user to confirm all of the following in one concise intake message. Prefill details already supplied, but always request explicit confirmation.
-
-1. **Duration:** How long should the finished video be?
-2. **Audience:** Who are the target viewers, and what can they already be expected to know?
-3. **Learning outcome:** What should viewers be able to explain after watching?
-4. **Visual reference:** Ask the user to upload or link an example video for quality, detailing, camera, lighting, and pacing reference, or describe the desired style in concrete terms. Require one of these before continuing.
-5. **Research approach:** Ask whether the agent should research the subject, the user will supply reference articles, URLs, or files, or both. Ask the user to attach or link every source they want used.
-
-Also confirm any choice that changes factual content, such as jurisdiction, construction system, species, machine variant, historical period, or required level of abstraction. Wait for the user's answers before continuing.
-
-## Read the supporting references
-
-- Read [evidence-and-explanation.md](references/evidence-and-explanation.md) before research, outlining, labeling, or narration.
-- Read [github-workflow-discovery.md](references/github-workflow-discovery.md) before searching for, downloading, importing, or executing a GitHub resource.
-- Read [story-patterns.md](references/story-patterns.md) before storyboarding. Select one primary pattern and at most two supporting patterns.
-- Read [visual-quality.md](references/visual-quality.md) before modeling, shading, lighting, camera work, or rendering.
-- Read [production-workflow.md](references/production-workflow.md) before narration, editing, or delivery.
-
-## Resolve tools and paths
-
-Resolve this skill's installed directory as an absolute path before invoking bundled scripts. Do not assume the current working directory is the skill directory.
-
-After the intake and before production, verify the installed Blender version and executable path again, then verify that Python 3.9 or newer, FFmpeg, and FFprobe are available. Confirm that FFmpeg provides the required H.264 or H.265 encoder and ASS/libass subtitle filter. Verify that the Kokoro-82M runtime can load `hexgrad/Kokoro-82M` and synthesize the selected English voice at native speed. Record the exact Kokoro-82M model revision and voice used. If a dependency is missing, report it before creating scenes or renders; do not substitute another TTS engine. Never attempt Blender production through a web substitute when the local Blender prerequisite is unmet. Confirm that the selected subtitle font is installed; if Arial is unavailable, use a metrically suitable sans-serif substitute and visually recheck wrapping and safe margins.
-
-## Follow the workflow
-
-### 1. Establish the evidence boundary
-
-Use the research approach chosen by the user. When the agent researches, use authoritative primary sources for every factual detail. Treat user-provided sources as required inputs, but do not assume they are correct; cross-check them when the user permits outside research. If the user restricts research to supplied material, omit or clearly flag anything those materials cannot verify.
-
-Create a claim ledger covering narration, any optional on-screen text, geometry, materials, proportions, sequence, motion, causal relationships, numbers, and symbolic visual encodings. Each entry must include its source and one of these statuses:
-
-- `verified`: directly supported by authoritative evidence;
-- `inferred`: a necessary conclusion supported by evidence and explicitly qualified;
-- `conceptual`: a teaching abstraction disclosed as conceptual, schematic, compressed, or not to scale through narration/subtitles and distinct visual treatment.
-
-Fact-check the outline, storyboard, narration, any optional labels, and final visuals against this ledger. Never guess, fill gaps with plausible details, or present decorative choices as facts. If a detail cannot be verified, remove it or disclose its uncertainty.
-
-### 2. Search GitHub for reusable Blender resources
-
-After the required intake, always search GitHub for existing workflows, application templates, add-ons, scripts, Geometry Nodes setups, `.blend` files, and appropriately licensed 3D assets related to the exact topic. Follow [github-workflow-discovery.md](references/github-workflow-discovery.md).
-
-Create `brief/github_resource_review.json` from [github_resource_review.template.json`github_resource_review.template.json`. Record the search queries, repository URL, exact commit or release, intended use, Blender compatibility, license, upstream asset provenance, dependencies, security review, and accept/reject decision for every serious candidate.
-
-Treat GitHub resources as production accelerators, not factual authorities. Verify all scientific, medical, engineering, and historical claims independently through the evidence workflow. Never execute repository code or import active-content files before inspecting them. Do not reuse a repository without a clear compatible license and required attribution terms.
-
-For human anatomy projects, evaluate [Z-Anatomy/Models-of-human-anatomy](https://github.com/Z-Anatomy/Models-of-human-anatomy) as one candidate. Review the license and provenance of each specific model before use because the repository includes material derived from multiple upstream sources.
-
-### 3. Design the explanation
-
-Define the exact learning outcome, audience assumptions, duration, technical scope, and truth level of the visuals. Select an explanatory pattern from [story-patterns.md](references/story-patterns.md), then create a shot table with one teaching objective, one narration idea, one subject-state change, and one causal visual action per shot. Record the start state, motion driver, intermediate state, and end state. Prefer 6–12 second shots and a clear causal order.
-
-### 4. Translate the visual reference into a style brief
-
-Inspect the supplied example video or style description. Record the intended level of detail, realism, material treatment, lighting, palette, camera language, motion pace, depth of field, subtitle treatment, and overall density. Record typography or label behavior only when the user explicitly requests optional scene text. Use the reference as a quality and style target without copying distinctive frames or protected creative elements literally. Track optional scene text and subtitles as separate decisions; omitting the former does not disable the latter.
-
-### 5. Create a safe project
-
-Work in a dedicated directory and preserve source files and unrelated `.blend` files. Initialize the project with:
-
-```bash
-python3 /ABS/PATH/TO/SKILL/scripts/init_blender_education_project.py /ABS/PATH/project-name
-```
-```
-Keep the brief, sources, scene files, renders, audio, overlays, reviews, QA, and deliverables separate.
-```
-
-### 6. Build the visual system
-
-Use Blender Python, Geometry Nodes, or instancing for repeated or dense structures. Preserve plausible scale relationships. Add geometry where silhouette, parallax, contact, deformation, or close-up readability requires it. Use textures, decals, and shaders for sub-pixel information. Build reusable highlight, cutaway, exploded-view, and flow systems before animating individual shots. Do not build label, legend, chapter-card, or teaching-overlay systems unless the user explicitly requested them.
-
-### 7. Render exactly one approval frame and stop
-
-Apply [visual-quality.md](references/visual-quality.md). Render exactly one representative 4K frame containing the hardest material, finest readable detail, darkest region, brightest highlight, and intended depth of field. Do not require a label, legend, chapter card, or teaching overlay in the approval frame. Include optional scene text only when the user explicitly requested it. Include one sample burned-in subtitle unless the user explicitly opted out of subtitles/captions.
-
-Show the frame to the user and ask: **"Would you like to modify the style, level of detail, composition, lighting, or subtitle treatment before I create the full video?"** If the user explicitly requested optional scene text, also ask about its treatment. Wait for an explicit response.
-
-If the user requests changes, revise the scene and render one replacement frame for the next approval round. Do not render a motion sample, frame sequence, chapter, or full video until the user explicitly approves the current frame. This is a hard production gate.
-
-Approval of this frame authorizes use of its visual language only. Never infer that the user has approved static storytelling, limited animation, motion quality, process choreography, camera pacing, or the finished explanation. After frame approval, build the real motion plan and animate the process; do not turn the approved image itself into the video.
-
-### 8. Animate the approved visual system
-
-After explicit frame approval, animate the full cinematic explainer as genuine continuous Blender motion. Use one dominant visual action per sentence, reveal structure in causal order, and preserve orientation between wide views and close-ups. Use keyframed mechanisms, rigs, shape keys, simulations, particles, Geometry Nodes, material-state animation, deforming geometry, or other appropriate techniques so the subject visibly changes across frames.
-
-For every narrated process shot:
-
-1. establish the relevant start state;
-2. animate the physical, biological, chemical, informational, or conceptual driver;
-3. show the resulting motion or transformation;
-4. end on a visibly different state that prepares the next shot.
-
-The subject-space change must remain meaningful even if the camera transform is ignored. A dolly, orbit, zoom, parallax pass, rack focus, light sweep, or crossfade may support the action but cannot be the action. Do not build a process sequence from animated crops of still renders.
-
-Use transparency, isolation, section cuts, exploded views, color highlights, particles, arrows, or field lines only when each has a defined meaning.
-
-Distinguish literal motion from teaching motion. Disclose impossible camera travel, compressed time, symbolic color, and conceptual flow wherever viewers could mistake them for reality. By default, make the disclosure through narration, subtitles, and distinct visual treatment. Never require a label, legend, or teaching overlay for this disclosure.
-
-### 9. Write English narration and burned-in subtitles
-
-Explain each object, stage, or mechanism through four questions: what it is, what changes or moves, what causes the change, and why it matters to the whole system.
-
-Maintain separate `display` and `tts` strings in English. `display` is the subtitle text; `tts` is the pronunciation-friendly input sent to Kokoro-82M. Create a pronunciation map for acronyms, units, formulas, and product names.
-
-Generate the narration exclusively with `hexgrad/Kokoro-82M`. Select an English Kokoro voice that matches the supplied visual/voice reference or stated tone; when neither supplies voice direction, use `af_heart`. Voice selection is an internal production decision unless the user explicitly requests an audition. Do not ask for voice approval or pause production after synthesis. Keep the model at native speaking speed, and record the model revision, voice identifier, and synthesis settings in the project notes. Do not use an operating-system voice or another TTS engine as a preview or production fallback. Target approximately -16 LUFS integrated, no true peak above -1.5 dBTP, 48 kHz audio, and exact timeline duration.
-
-Generate narration at the intended native TTS speed and lock its waveform before final picture timing. Do not use `atempo`, `asetrate`, Rubber Band, phase-vocoder stretching, sample interpolation, NLE rate controls, or any other duration-changing process on narration. If the spoken material does not fit the requested duration, revise the script and regenerate it at native speed; otherwise let the finished duration change. To restore synchronization, rebuild shot boundaries, holds, transitions, subtitle cues, and any explicitly requested optional overlays from the regenerated audio. Sample-rate conversion such as 24 kHz to 48 kHz is allowed only when it preserves the narration's duration and pitch.
-
-Unless the user explicitly opted out of subtitles/captions, author captions as ASS using [subtitle.template.ass`subtitle.template.ass` and burn them into every narrated scene. A request for no text, labels, legends, chapter cards, or teaching overlays is not a subtitle opt-out. Match the supplied reference image:
-
-- large white or very light gray sans-serif text;
-- centered near the bottom of the frame;
-- dark outline plus a subtle shadow for readability on any background;
-- no opaque caption box;
-- generous left and right safe margins;
-- one line when readable and no more than two lines;
-- natural sentence case, synchronized to the spoken phrase.
-
-At 3840x2160, start with 92 px Arial, a 5 px dark outline, a 2 px shadow, 120 px horizontal margins, and a 90 px bottom margin. Adjust only when required for legibility while preserving the same visual treatment.
-
-### 10. Assemble and verify
-
-Copy [timeline_manifest.template.json`timeline_manifest.template.json`, list only approved source ranges, and preflight before encoding:
-
-```bash
-python3 /ABS/PATH/TO/SKILL/scripts/assemble_picture.py \
-  --manifest /ABS/PATH/timeline_manifest.json --preflight-only
-```
-```
-Lock timing, then burn the required ASS subtitles. Labels, legends, chapter cards, and teaching overlays are not required; add the optional `--overlay` argument only when the user explicitly requested scene text:
-```
-```bash
-python3 /ABS/PATH/TO/SKILL/scripts/compose_tutorial.py \
-  --video /ABS/PATH/picture-master.mp4 \
-  --narration /ABS/PATH/narration.wav \
-  --captions /ABS/PATH/captions.ass \
-  --output /ABS/PATH/final-4k.mp4 \
-  --audio-language eng \
-  --codec h264 --preset slow --crf 14 --fps 30
-```
-```
-If the user explicitly opted out of subtitles/captions, replace `--captions ...` with `--no-captions`. This explicit flag prevents a vague “no text” request from accidentally producing an uncaptioned video.
-
-Run structural and full-decode QA:
-```
-```bash
-python3 /ABS/PATH/TO/SKILL/scripts/verify_output.py /ABS/PATH/final-4k.mp4 \
-  --expected-codec h264 --expected-fps 30 \
-  --expected-duration EXPECTED_SECONDS \
-  --report /ABS/PATH/final-4k.qa.json
-```
-```
-Extract entry, intermediate, and exit frames from every process shot and inspect them as a temporal sequence; a single representative contact sheet is insufficient for motion QA. Verify that the subject or process state changes independently of camera motion, that the stated cause precedes its effect, and that the end state prepares the next shot. Reject any process shot that is only a still, repeated frame, pan, zoom, orbit, crossfade, or lighting change.
-
-Create `qa/motion_qa.json` from [motion_qa.template.json`motion_qa.template.json`. Complete one entry for every narrated process shot with the teaching action, animation driver, start-state time/frame, intermediate-state time/frame, end-state time/frame, observed subject change, and explicit static-substitute checks. Every process shot must pass `subject_change_visible_without_camera_motion` and `cause_precedes_effect`, with `static_substitute_detected` set to false. Verify every visible factual detail against the claim ledger. Check subtitle readability, timing, safe margins, line wrapping, collisions, and consistency. Structural QA does not replace evidence, temporal, or visual review.
-```
-
-## Delivery requirements
-
-Deliver the final MP4 with burned-in English subtitles, a safe `.blend` file, the ASS subtitle file, source and claim notes, the GitHub resource review with licenses and attributions, and QA JSON. The subtitle file may be omitted only after an explicit subtitle/caption opt-out. Report the real resolution, frame rate, duration, codec, loudness, synchronization, Kokoro-82M model revision and voice, third-party resources, and every conceptual or symbolic visualization.
-
-Do not call the film complete while any narrated process is represented only by camera movement over a static image, repeated frames, a slideshow, a crossfade montage, or another substitute for real process animation. Also reject any unsupported claim, invented detail, misleading scale, unreadable or clipped subtitle, unexplained abstraction, black frame, color-tag error, audio drift, or decode failure.
-
-## Bundled resources
-
-- `scripts/init_blender_education_project.py`: create a non-destructive project and copy templates.
-- `scripts/assemble_picture.py`: create a frame-exact BT.709 picture master.
-- `scripts/compose_tutorial.py`: combine picture, narration, burned-in subtitles, and optional user-requested overlays.
-- `scripts/verify_output.py`: verify 4K geometry, codec, tags, timing, audio, frames, and full decode.
-- `assets/timeline_manifest.template.json`: starting point for edit decisions.
-- `assets/narration_plan.template.json`: starting point for English narration and claim status.
-- `assets/github_resource_review.template.json`: record GitHub candidates, compatibility, provenance, license, and safety decisions.
-- `assets/motion_qa.template.json`: required per-shot evidence that the subject or process genuinely changes across frames.
-- `assets/subtitle.template.ass`: required burned-in subtitle treatment.
-- `assets/teaching_overlay.template.ass`: optional starting point when the user explicitly requests English chapter cards or teaching labels.
-
-## Source
-
-Rewritten for AICUT from [`sunxiayi/make-blender-education-video-skill`](https://github.com/sunxiayi/make-blender-education-video-skill)
-(MIT), skills/make-blender-education-video/SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/make-blender-education-video/references/evidence-and-explanation.md

@@ -1,62 +0,0 @@
-# Evidence and Explanation
-
-## Define the truth level
-
-Record every factual detail in a claim ledger, including narration, any optional labels, geometry, materials, proportions, sequence, motion, numbers, and causal relationships:
-
-| Status | Meaning | Treatment |
-|---|---|---|
-| `verified` | Supported by authoritative evidence | State directly and retain the source |
-| `inferred` | Reasonable conclusion from evidence | Qualify the language |
-| `conceptual` | Teaching abstraction | Disclose in narration/subtitles and distinguish visually as conceptual, schematic, compressed, or not to scale |
-
-Prefer primary sources: official documentation, standards, codes, papers, museum or institutional records, manufacturer diagrams, engineering drawings, or direct observation. Use secondary sources to locate evidence or establish context.
-
-Fact-check the outline, storyboard, narration, any optional on-screen text, and final imagery against the ledger. Never add a plausible detail simply because it looks or sounds right. Remove any detail that cannot be verified, or disclose it clearly as inferred or conceptual through narration/subtitles and visual treatment. User-provided references are required inputs when supplied, but they do not override contradictory primary evidence.
-
-## Separate four kinds of accuracy
-
-- **Factual accuracy:** names, numbers, sequence, material, function, and causal claims.
-- **Geometric accuracy:** shape, scale, position, construction, and spatial relationships.
-- **Temporal accuracy:** real-time motion versus slowed, accelerated, reordered, or compressed events.
-- **Visual encoding accuracy:** what colors, arrows, transparency, particles, or highlights mean.
-
-Declare limitations in the visual language rather than hiding them in a final disclaimer.
-
-## Build explanations around causality
-
-For each object, stage, or mechanism, answer:
-
-1. What is it?
-2. What changes, moves, enters, or leaves?
-3. What causes that change?
-4. Why does it matter to the whole system?
-
-Prefer “because” and “therefore” over lists of parts. Show the cause before the result whenever possible.
-
-## Handle domain-specific risk
-
-- For construction and architecture, specify location, structural system, code context, and whether the sequence is typical or required.
-- For medicine and biology, distinguish normal variation, simplified anatomy, cellular scale, and clinical advice.
-- For machines and manufacturing, specify variant, operating state, omitted guards, and whether motion is slowed or sectioned.
-- For physics and energy, define what field lines, particles, colors, and vector arrows represent.
-- For historical reconstruction, distinguish surviving evidence, scholarly interpretation, and artistic completion.
-
-Do not turn a visualization into actionable professional guidance unless the user explicitly requests that scope and appropriate authoritative sources support it.
-
-## Write narration that matches the image
-
-Narrate only what the viewer can see or what the visual clearly prepares them to infer. Remove claims whose corresponding object, step, or causal link is absent.
-
-Keep separate English `display` and `tts` strings. Use consistent terminology. Preserve official names, formulas, and symbols. Expand ambiguous acronyms and units in TTS text.
-
-## Final evidence review
-
-Verify that:
-
-- every factual detail and every numerical or safety-relevant claim has a source;
-- every optional concept label matches its visual target;
-- symbolic colors and flows are clearly introduced through narration/subtitles or visual context; a legend is optional and used only when explicitly requested;
-- compressed time and nonliteral motion are disclosed;
-- no decorative detail is presented as evidence;
-- the final summary preserves the original qualifications.

package/skills/make-blender-education-video/references/github-workflow-discovery.md

@@ -1,55 +0,0 @@
-# GitHub workflow discovery
-
-## Search before building
-
-Search GitHub for reusable Blender work related to the exact topic before designing geometry from scratch. Use several narrow queries rather than one broad search. Combine the subject with terms such as:
-
-- `Blender`, `.blend`, `Geometry Nodes`, `Blender Python`, or `add-on`;
-- `animation`, `simulation`, `rig`, `procedural`, `exploded view`, or `visualization`;
-- the relevant domain term, standard, species, machine variant, structure, or process.
-
-Look for four kinds of resources:
-
-1. production workflows or procedural techniques;
-2. Blender add-ons and scripts;
-3. application templates and reusable scene systems;
-4. licensed models, data, textures, rigs, or reference assets.
-
-Do not select a repository by stars alone. Inspect its README, license, recent commits or releases, issues, supported Blender versions, dependencies, example output, file structure, and upstream attributions.
-
-## Evaluate every serious candidate
-
-Record each candidate in `brief/github_resource_review.json` with:
-
-- repository name, URL, and exact commit or release;
-- intended use in this project;
-- resource type and relevant files;
-- supported Blender version and required add-ons;
-- license, attribution text, share-alike or noncommercial restrictions;
-- provenance and license of bundled or derived assets;
-- maintenance signals and known limitations;
-- dependencies, install steps, and security findings;
-- import or compatibility test results;
-- decision: `use`, `adapt`, `reference_only`, or `reject`;
-- reason for the decision.
-
-Reject reuse when the repository has no clear license, conflicts with the intended distribution, obscures asset provenance, requires unsafe execution, or cannot be tested in a scene copy. A repository-level license may not cover every bundled asset; trace each model, texture, dataset, and audio file to its own source.
-
-## Inspect safely
-
-- Download or clone into a dedicated review directory, not the production scene directory.
-- Pin the exact commit or release used.
-- Inspect Python, shell scripts, installers, and dependencies before execution.
-- Do not enable an add-on, run a startup file, or open active content blindly.
-- Import into a disposable Blender scene first. Check units, origin, transforms, topology, normals, naming, materials, rigs, external links, drivers, scripts, and performance.
-- Preserve the original files and document every transformation applied during adaptation.
-
-## Separate reuse from truth
-
-GitHub can provide geometry, workflows, and implementation ideas. It is not automatically an authoritative source for factual claims. Verify anatomy, engineering, construction, medicine, and other domain details through authoritative evidence and record them in the claim ledger.
-
-For anatomy, [Z-Anatomy/Models-of-human-anatomy](https://github.com/Z-Anatomy/Models-of-human-anatomy) is a useful candidate because it provides a Blender anatomy application template and models. Its README lists CC BY-SA licensing and several upstream sources with their own conditions. Review the provenance and license of each specific structure before importing or distributing it.
-
-## Report the result
-
-Before modeling, summarize the strongest candidates and state what each could save: research time, modeling time, rigging, simulation setup, labeling, or animation logic. Identify the recommended resource and its constraints. Ask for user confirmation before adopting anything with material attribution, share-alike, noncommercial, compatibility, or visual-direction consequences.

package/skills/make-blender-education-video/references/production-workflow.md

@@ -1,62 +0,0 @@
-# Production Workflow
-
-## Project layout
-
-Use `brief/`, `sources/`, `scene/`, `renders/`, `audio/`, `overlays/`, `review/`, `qa/`, and `deliverables/`. Keep raw sources immutable and save descriptive Blender milestones.
-
-## Approval gates
-
-1. Confirm duration, audience, learning outcome, visual reference or style description, and research approach.
-2. Review topic-specific GitHub candidates, licenses, provenance, compatibility, and proposed use.
-3. Approve the English learning outcome, scope, claim ledger, storyboard, and visual grammar.
-4. Approve exactly one 4K style frame containing a representative subtitle unless the user explicitly opted out of subtitles/captions. Labels, legends, chapter cards, and teaching overlays are never required in this frame; include them only when the user explicitly requested them. This approves visual treatment only, never motion design or animation quality.
-5. Pass final evidence, visual, subtitle, audio, metadata, sync, and decode QA.
-
-Do not render a motion sample or any full-video frames before the user explicitly approves the single style frame. If the user requests style changes, render one replacement frame and ask again. After approval, do not use the approved still as a video source or infer that static storytelling is approved; create genuine subject and process animation.
-
-Voice selection is not an approval gate. Do not present a voice sample, ask for voice approval, or pause production after narration synthesis unless the user explicitly requested a voice audition or comparison.
-
-## Blender strategy
-
-Search GitHub for topic-specific Blender workflows and assets before modeling. Record candidates in `brief/github_resource_review.json`; review licenses, provenance, compatibility, dependencies, and code safety before use. Use scripts, Geometry Nodes, instancing, keyframes, rigs, shape keys, simulations, particles, deformers, or material animation as appropriate. Preserve real scale and coordinate conventions. Build reusable systems for exploded views, section cuts, highlights, and flows. Do not build label, legend, chapter-card, or teaching-overlay systems unless the user explicitly requested them. Produce a cinematic explainer rather than recording Blender UI operations.
-
-For every narrated process shot, document the subject’s start state, animation driver, intermediate state, and end state. Camera animation is a separate layer and cannot satisfy the subject-animation requirement. Still images with pan, zoom, orbit, parallax, light sweeps, or crossfades are not acceptable substitutes for process motion.
-
-## Narration
-
-Copy `assets/narration_plan.template.json` after the required intake is complete. Keep cue boundaries on exact frames when practical. Maintain separate English display and TTS text plus a pronunciation dictionary.
-
-Use `hexgrad/Kokoro-82M` exclusively for narration. Verify the model can load before production, select a suitable English voice autonomously, record its exact revision and voice identifier, and synthesize at native speed. Default to `af_heart` when the brief provides no contrary voice direction. Continue directly into production without seeking voice approval unless the user explicitly requested an audition. Do not substitute an operating-system voice, cloud service, another local TTS model, or a differently sized Kokoro model if Kokoro-82M is unavailable.
-
-Generate a 48 kHz WAV master. Measure the encoded final audio, not only the source. Target approximately −16 LUFS integrated and no true peak above −1.5 dBTP unless the destination requires a different standard.
-
-Treat native-speed narration as the timing master. Never change narration duration to force it into pre-existing shot windows, even by a small amount. Prohibit tempo or rate filters, pitch-preserving time stretching, sample interpolation, and NLE speed controls on generated speech. When timing does not fit:
-
-1. Revise the script if the requested total duration is strict, then regenerate the narration at the intended original TTS speed.
-2. Lock the regenerated waveform without duration-changing processing.
-3. Measure the real cue and section durations.
-4. Rearrange, extend, hold, or visually retime the shots to those measurements.
-5. Regenerate subtitle timings and any explicitly requested optional scene-text timings from the same audio timeline.
-6. Verify each source cue duration equals its placed duration and record that no post-generation time stretch was used.
-
-Allow sample-rate conversion only when it preserves duration and pitch. Loudness normalization, EQ, compression, and limiting may be applied if they do not alter speech timing.
-
-## Picture, subtitles, and optional scene text
-
-Copy `assets/timeline_manifest.template.json`. Select only clean, genuinely animated source ranges. Exclude errors, wrong values, stalls, unintended repeated frames, static-image motion substitutes, black frames, blocking dialogs, and unstable renders.
-
-Create captions from `assets/subtitle.template.ass` and burn them into the picture unless the user explicitly opted out of subtitles/captions. “No text in the picture,” “no on-screen text,” and requests to remove labels or legends affect optional scene text only; subtitles remain required. Labels, legends, chapter cards, and teaching overlays are universally optional and omitted by default. Use ASS overlays only when the user explicitly requests them. Use large white sans-serif subtitles centered near the bottom, with a dark outline, subtle shadow, no opaque box, generous side margins, and no more than two lines. Inspect exact subtitle frames and any requested overlay frames visually.
-
-Run `assemble_picture.py` in preflight mode, then assemble the final-quality picture. Use motivated cuts and transitions for scale, section, or process changes.
-
-## Composition
-
-Use `compose_tutorial.py` to combine picture, narration, burned-in subtitles, and optional overlays. Always set the audio language to `eng`. The script requires either `--captions` or the explicit `--no-captions` opt-out flag. Prefer H.264/`avc1` for compatibility and H.265/`hvc1` Main10 for supported high-quality archives.
-
-## QA
-
-Use `verify_output.py` to require one video and one audio stream, 3840×2160, requested constant frame rate, correct codec tag and pixel format, BT.709 metadata, AAC 48 kHz stereo, expected duration, correct frame count, synchronized streams, and clean full decode.
-
-Create entry/middle/exit frame triplets for every narrated process shot, plus a contact sheet at chapter boundaries. Confirm that the subject state changes across the triplet even when camera motion is ignored, and that cause precedes effect. Reject still-image pans, zooms, orbits, parallax passes, crossfade montages, repeated frames, and light-only changes when they carry a process explanation.
-
-Copy `assets/motion_qa.template.json` to `qa/motion_qa.json` and complete it for every narrated process shot. Each entry must pass `subject_change_visible_without_camera_motion` and `cause_precedes_effect`, and must set `static_substitute_detected` to false. Inspect section cuts, transparency, black regions, subtitle readability and collisions, aliasing, render noise, and temporal artifacts. Inspect labels, legends, chapter cards, or teaching overlays only when the user explicitly requested and included them. Recheck every visible detail against the claim ledger. Structural QA never replaces evidence, temporal, or visual QA.

package/skills/make-blender-education-video/references/story-patterns.md

@@ -1,65 +0,0 @@
-# Story Patterns
-
-Choose one primary pattern. Add at most two supporting patterns so the film retains a clear mental model.
-
-## How it is built
-
-Use for buildings, machines, infrastructure, products, organisms developing over time, and manufacturing.
-
-Sequence: final result → prerequisites → ordered stages → hidden layers → completed system. Show each new stage attaching to an established spatial reference. Use time compression deliberately.
-
-## How it works
-
-Use for engines, devices, biological mechanisms, software-hardware systems, and energy conversion.
-
-Sequence: input → transformation → output → control → failure or constraint. Animate cause before effect. Use repeated cycles only after explaining one complete cycle slowly.
-
-## Inside the system
-
-Use for anatomy, architecture, geology, machines, electronics, and infrastructure.
-
-Sequence: exterior context → section cut → subsystem isolation → relationship between subsystems → reconstructed whole. Preserve camera orientation across scale changes.
-
-## Invisible flows
-
-Use for electricity, heat, air, water, forces, stress, information, chemistry, and biological transport.
-
-Define the visual grammar before using it. Assign consistent meanings to color, direction, speed, density, thickness, and particle behavior. Do not let decorative particles imply quantitative accuracy.
-
-## Scale journey
-
-Use for cells, materials, planets, semiconductor structures, ecosystems, and nested systems.
-
-Anchor every scale transition with a known object, a dimension stated in narration/subtitles, or a retained geometric landmark. Optional dimension labels may be used only when the user explicitly requests them. Avoid an endless zoom that destroys orientation.
-
-## Cause and effect
-
-Use for failures, natural phenomena, engineering tradeoffs, medical mechanisms, and historical processes.
-
-Sequence: initial conditions → trigger → propagation → visible outcome → intervention or alternative. Distinguish correlation from mechanism.
-
-## Comparison or evolution
-
-Use for old versus new technology, species, design alternatives, construction systems, or competing mechanisms.
-
-Keep camera, scale, lighting, and metrics consistent. Change one variable at a time. Use side-by-side views only when both remain legible.
-
-## Shot design template
-
-For each shot, record:
-
-- learning objective;
-- claim status;
-- starting orientation and scale;
-- start state of the subject or process;
-- physical, biological, chemical, informational, or conceptual motion driver;
-- intermediate state that proves the process is occurring;
-- visibly different end state;
-- one dominant subject-space visual action, excluding camera movement;
-- supporting camera action, if any;
-- narration cue;
-- optional scene-text request, defaulting to none;
-- literal versus conceptual motion;
-- exit state that prepares the next shot.
-
-Use a clean overview at the beginning and reassemble the system at the end. A viewer should be able to retell the explanation without remembering every label.

package/skills/make-blender-education-video/references/visual-quality.md

@@ -1,82 +0,0 @@
-# Visual Quality
-
-## Build readable hierarchy
-
-Establish primary forms, secondary mechanisms or layers, and tertiary details. Make primary forms legible at thumbnail size. Reveal tertiary detail only when the camera and narration require it.
-
-Preserve plausible scale, thickness, edge radius, spacing, joint, and contact relationships. Use real geometry for silhouette, parallax, contact shadow, deformation, and close-up features. Use textures, decals, and shaders for sub-pixel information.
-
-## Avoid the toy look
-
-- Vary edge radii according to material and manufacturing or biological role.
-- Vary thickness, height, spacing, and surface response instead of scaling all details uniformly.
-- Add contact, fastening, layering, seams, or transition detail where parts meet.
-- Break perfect uniformity through roughness and normal variation before color noise.
-- Preserve detail in dark materials; avoid featureless black.
-- Use joints, fasteners, grain, pores, strata, or other domain-appropriate scale cues. Labels are never required and should be omitted unless the user explicitly requests them.
-- Avoid excessive saturation, bloom, glow, and miniature-like depth of field.
-
-High detail does not require photorealism. A stylized film can remain precise when shape, hierarchy, motion, and visual encoding are consistent.
-
-## Match materials to the subject
-
-Create a restrained material family with clearly different response for metal, glass, wood, concrete, soil, polymer, fluid, tissue, stone, ceramic, paint, or composite materials as needed.
-
-Use microtexture to shape highlights rather than display obvious procedural noise. Keep printed or engraved labels sharp at delivery resolution. Add dirt, wear, moisture, scratches, or biological irregularity only when they support the explanation.
-
-## Run a physical-plausibility gate
-
-Before rendering the approval frame, review every salient visible element:
-
-1. Name what the element represents.
-2. Identify its real-world counterpart or evidence source.
-3. Confirm that its scale, material, thickness, attachment, and location are plausible.
-4. Classify it as literal, inferred, or conceptual.
-5. Remove it if an ordinary viewer could mistake an unsupported abstraction for a real object.
-
-Reject the frame when:
-
-- a visible hose, tube, strand, particle, arrow, or decorative mechanism has no real-world counterpart;
-- microscopic structures appear at macroscopic scale without a separate, disclosed scale transition;
-- an opaque real object has been changed into glass merely to expose its interior;
-- transparent materials use visible screen-door or alpha-dither noise;
-- metal has uniform color and roughness with no believable highlight response;
-- repeated objects have perfectly identical color, edge shape, or surface response;
-- an animated curve, instance, or mesh scales around the wrong origin and moves outside its intended vessel or mechanism;
-- parts float, intersect, or lack believable joints, seals, fasteners, contact shadows, or supporting structure.
-
-Prefer a section cut through the real material over a glass substitute. For invisible or microscopic processes, use a dedicated conceptual inset, scale-matched cut, or isolated teaching view instead of inserting literal-looking rods, wires, particles, or tubes into a real-scale scene.
-
-## Light for explanation
-
-Use broad controlled lights to reveal form and material. Keep the background separate from the subject. Preserve readable shadows and highlight rolloff. Add localized accents only to clarify an object or stage.
-
-Do not copy light coordinates across unrelated subjects. Place lights by observing reflections, silhouette, volume, and the current learning objective.
-
-## Use the camera as a teaching tool
-
-Establish orientation before close-ups. Use focal length and camera distance to control perspective rather than relying on extreme depth of field. Keep the explanatory subject sharp.
-
-Use deliberate moves: overview orbit, dolly, top-down reveal, section transition, track through a flow, or scale-matched cut. Avoid constant drifting and unexplained rotation.
-
-Camera movement supports subject animation; it never replaces it. A moving crop of a still frame, including a Ken Burns pan/zoom or 2.5D parallax pass, does not demonstrate a process.
-
-## Animate readable change
-
-Use one dominant visual action per sentence. Every narrated dynamic shot must contain a meaningful subject-space change: material moves, a mechanism operates, geometry deforms, a flow propagates, components assemble, a biological state develops, or another relevant transformation occurs. Establish the start state, animate its driver, show an intermediate state, and land on a visibly different end state.
-
-Use consistent easing and highlight colors. Reserve dramatic motion for meaningful transitions. If the user explicitly requested optional labels, keep them attached to their targets without covering them.
-
-When motion is conceptual, make it visually distinct from literal mechanical or biological motion.
-
-Do not count camera transforms, focus pulls, light changes, crossfades, or shader-only glints as the dominant process action. Brief still holds may establish context or create emphasis, but they cannot occupy the explanatory core of a process shot.
-
-## Approve before scaling
-
-Render exactly one 4K style frame containing the hardest material, finest readable detail, darkest region, brightest highlight, and intended depth of field. Labels, legends, chapter cards, and teaching overlays are never required; omit them unless the user explicitly requested them. Include one sample burned-in subtitle unless the user explicitly opted out of subtitles/captions. A request for “no text in the picture,” no labels, or no legend does not remove the subtitle. Inspect at 100% and thumbnail size.
-
-Show that frame to the user and ask whether to modify the style, detail, composition, lighting, or subtitle treatment. Ask about scene-text treatment only when the user explicitly requested it. If revisions are requested, render one replacement frame. Do not render any motion sample, frame sequence, chapter, or full video until the user explicitly approves the current frame.
-
-The approval frame confirms appearance only. It provides no evidence of animation quality and must never be repurposed into a static or Ken Burns-style final sequence.
-
-Use Eevee for rapid style iteration or approved real-time results. Use Cycles when reflections, transmission, volume, close-up shadows, or global illumination materially improve the learning result and render budget permits.