creating-explainer-videos-skill 2.0.0__py3-none-any.whl

creating_explainer_videos_skill/__init__.py

@@ -0,0 +1,3 @@
+"""Python distribution for the Creating Explainer Videos Skill."""
+
+__version__ = "2.0.0"

creating_explainer_videos_skill/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+
+raise SystemExit(main())

creating_explainer_videos_skill/assets/creating-explainer-videos/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: creating-explainer-videos
+description: Use when researching, planning, scripting, animating, rendering, auditing, or packaging a mechanism, process, system, or scientific explainer video with executable project state, narration-identical captions, cue-synchronized motion, dedicated covers, and release evidence.
+---
+
+# Creating Explainer Videos
+
+Create a traceable teaching product, not just an MP4. The Agent must drive the executable state machine, call the required tools, inspect their evidence, and stop at unresolved gates.
+
+## Start with the executable project
+
+Use the installed CLI `explainer-video-skill`. From a copied Skill directory use `node <skill-dir>/scripts/explainer-video.mjs` instead. Run `doctor --json` before promising a render.
+
+Create a project only after the exact question, audience, language, platform, and aspect ratio are known:
+
+```powershell
+explainer-video-skill new <project-dir> --title "标题" --topic "要解释的精确问题" --template spatial-chamber --preset general-mechanism --json
+explainer-video-skill status --json <project-dir>
+explainer-video-skill next --json <project-dir>
+```
+
+For every stage, repeat this loop:
+
+1. Run `status --json` and `next --json`.
+2. Read the listed required inputs and gate.
+3. Perform the real research, writing, generation, render, or review action.
+4. Write the requested evidence file; do not invent success.
+5. Run `validate <current-stage> <project-dir> --json`.
+6. Continue only when validation moves the project forward.
+
+The stages are `discovery -> brief -> evidence -> mechanism_map -> narration_and_cues -> real_audio_timing -> scene_spec -> runnable_renderer -> render -> automated_qc -> human_listen -> publishing_package -> human_release_decision`.
+
+## Content contract
+
+Read [content-and-script-contract.md](references/content-and-script-contract.md) when defining the promise, evidence, mechanism, narration, or cue map.
+
+- Explain `input -> internal state changes -> output`, including why each step follows.
+- Include one worked example and one relevant boundary, cost, control, or failure chain.
+- Treat duration, scene count, and word count as depth alarms, never padding targets.
+- Keep the public topic no broader than the mechanism actually taught.
+- For a series, the opening sentence connects the previous output to this exact topic; the final sentence previews the next exact question. For a standalone video, open with the exact question and close with the reusable conclusion.
+- Store one canonical spoken string. Captions and TTS must be character-identical after normalization.
+- Remove `\_`, snake_case underscores, Markdown syntax, and other characters a TTS engine may pronounce literally. Keep technical spelling in a separate on-screen label.
+- Bind every cue's narration, visible title, mechanism label, focus, action, and handoff to the same local claim.
+
+Use primary evidence for mechanism facts. Keep source, source type, verification date, simplification, and planned visual expression in the evidence table. Community sources may expose confusion or edge cases but do not establish the mechanism by themselves.
+
+## Select from the visual template collection
+
+Read [visual-template-collection.md](references/visual-template-collection.md) before choosing or modifying a template. Inspect the executable manifests with:
+
+```powershell
+explainer-video-skill templates list --json
+explainer-video-skill templates inspect paper-theatre --json
+explainer-video-skill templates inspect spatial-chamber --json
+explainer-video-skill templates inspect ink-explainer --json
+```
+
+- `paper-theatre`: object identity, physical processing, evidence, sorting, comparison, and editorial transformation.
+- `spatial-chamber`: systems, routes, layers, pipelines, queues, transfer, and high-impact spatial state changes.
+- `ink-explainer`: derivation, formulas, causal relations, dense annotations, comparisons, and correction.
+
+Select by knowledge structure, not decoration. A project may combine primitives, but one grammar must remain dominant. Do not copy an old scene and swap text. Do not use full-frame scanning lines, narration-length sweeps, meaningless particles, or repeated cards as substitute motion.
+
+Use DingTalk JinBuTi/DingTalk Sans for display roles when locally licensed and installed, and Noto Sans SC or a tested CJK fallback for captions. Never package font binaries or commercial GSAP plugins without redistribution rights. Every premium plugin needs the fallback declared by its template.
+
+## Narration, timing, and render
+
+Read [engineering-pipeline.md](references/engineering-pipeline.md) before implementation.
+
+```powershell
+explainer-video-skill narration prepare <project-dir> --json
+# Produce narration with the selected provider only after any required cost/credential authorization.
+explainer-video-skill narration import-timing <project-dir> --timing <measured-timing.json> --json
+explainer-video-skill build <project-dir> --json
+explainer-video-skill render <project-dir> --json
+explainer-video-skill cover <project-dir> --json
+explainer-video-skill mux <project-dir> --audio <narration.wav> --json
+```
+
+Real measured narration timing is the only final animation clock. Use deterministic paused timelines, local assets, fixed viewBoxes, and explicit cue anchors. Never use runtime randomness, remote assets, wall-clock timers, or estimated timings in a release render.
+
+Generate a dedicated cover, not a random frame. The cover must state the exact topic and remain readable in a phone-size preview. Series/season/episode labels are preset rules, not core-package branding.
+
+## QC and release boundary
+
+Read [release-qc-and-publishing.md](references/release-qc-and-publishing.md) before calling a candidate complete.
+
+```powershell
+explainer-video-skill audit <project-dir> --json
+explainer-video-skill package <project-dir> --json
+```
+
+Automated checks must include full decode, media specifications, black/freeze/silence diagnostics, representative frames, warning frames, overflow/layout inspection, cover preview, and artifact hashes. Automation may only write `release_candidate_pending_human_listen`.
+
+Complete three human passes on the exact hashed candidate: muted visual, audio-only, and normal watch. Record title/narration/caption/focus mismatches, clipping, unreadable text, accidental symbol speech, timing drift, dead motion, repeated composition, dirty transitions, and mixing defects with timestamps.
+
+Only after a named reviewer listened to the whole hashed candidate may the Agent run:
+
+```powershell
+explainer-video-skill release record-human-decision <project-dir> --decision passed --actor "<reviewer>" --complete-listen --listened-sha256 "<sha256>" --json
+```
+
+Never infer `passed` from a render, a provider success, green tests, or file presence.
+
+## Extensions, presets, and portability
+
+Read [extension-api.md](references/extension-api.md) before adding a visual, voice, research, QC, or publishing profile. Extensions are declarative, permission-listed, hash-locked, and cannot run arbitrary hooks. `general-mechanism` is domain-neutral; topic-specific behavior belongs in an explicit preset such as the included `ai-principle-series` example.
+
+Read [install-and-portability.md](references/install-and-portability.md) for npm, Codex, other Agent hosts, migration, update, rollback, and asset-license rules.
+
+## Stop conditions
+
+Stop and report the exact blocker when facts are unverified, the topic promise is broader than the explanation, canonical narration is not fixed, real audio timing is missing, title/card/narration/focus diverge, text clips or overflows, the selected template does not express the mechanism, media decode fails, licensed assets are unresolved, or human review is incomplete.

creating_explainer_videos_skill/assets/creating-explainer-videos/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "解释型视频制作脚手架"
+  short_description: "调研、脚本、三套视觉模板、确定性渲染、音画同步和发布质检的一体化工作流"
+  default_prompt: "使用 $creating-explainer-videos 创建并执行一个机制解释视频工程；按状态机推进，依据知识结构选择模板，使用真实旁白时间，并停在未完成的人工发布门禁。"

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/douyin-release/extension.json

@@ -0,0 +1,15 @@
+{
+  "apiVersion": 1,
+  "id": "douyin-release",
+  "type": "publishing",
+  "version": "1.0.0",
+  "displayName": "抖音发布包",
+  "description": "Douyin title, independent cover hierarchy, copy, topics, and pinned-comment profile.",
+  "entrypoints": {
+    "reference": "reference.md",
+    "profile": "profile.json",
+    "assets": []
+  },
+  "capabilities": ["publishing.title", "publishing.cover", "publishing.copy", "publishing.pinned-comment"],
+  "permissions": ["filesystem:project-read", "filesystem:project-write"]
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/douyin-release/profile.json

@@ -0,0 +1,12 @@
+{
+  "platform": "douyin",
+  "titlePattern": "主题：具体问题或核心结论",
+  "coverRules": [
+    "series-at-top-left",
+    "season-episode-immediately-after-series",
+    "exact-topic-visible",
+    "top-right-clean",
+    "phone-preview-required"
+  ],
+  "deliverables": ["title", "description", "topics", "pinned-comment", "video-path", "cover-path", "phone-cover-preview"]
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/douyin-release/reference.md

@@ -0,0 +1,6 @@
+# 抖音发布包
+
+Use `主题：具体问题或核心结论` for the title. The independent cover shows the series label at top left, season/episode immediately after it, the exact topic, one concrete question, and one mechanism graphic; the top right remains clean.
+
+Deliver the video path, cover path, phone preview, title, concise description, relevant topics, pinned comment, and next-episode teaser. Publishing copy cannot make claims or quote performance numbers absent from the reviewed episode.
+

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/ink-explainer/assets/style-tokens.css

@@ -0,0 +1,11 @@
+:root {
+  --sheet: #f8f3e8;
+  --paper-2: #fffaf0;
+  --ink: #201e1b;
+  --blue: #264ac7;
+  --red: #dc3f36;
+  --yellow: #f0c331;
+  --green: #24845c;
+  --caption-bg: rgba(255, 250, 240, .96);
+}
+

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/ink-explainer/extension.json

@@ -0,0 +1,15 @@
+{
+  "apiVersion": 1,
+  "id": "ink-explainer",
+  "type": "visual",
+  "version": "1.0.0",
+  "displayName": "Ink Explainer 手绘动态图解",
+  "description": "Ruled-paper, hand-drawn mechanism explanation for dense mechanisms and derivations.",
+  "entrypoints": {
+    "reference": "reference.md",
+    "profile": "profile.json",
+    "assets": ["assets/style-tokens.css"]
+  },
+  "capabilities": ["visual.tokens", "visual.semantic-motion", "visual.cover-grammar"],
+  "permissions": []
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/ink-explainer/profile.json

@@ -0,0 +1,12 @@
+{
+  "style": "ink",
+  "styleName": "Ink Explainer 手绘动态图解",
+  "tokenAsset": "assets/style-tokens.css",
+  "motionPlugins": ["DrawSVGPlugin", "SplitText", "CustomEase"],
+  "coverGrammar": "top-left-series-cluster-clean-top-right",
+  "fontRoles": {
+    "displayZh": "钉钉进步体 Regular",
+    "latinAndNumbers": "DingTalk Sans",
+    "caption": "Noto Sans SC"
+  }
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/ink-explainer/reference.md

@@ -0,0 +1,5 @@
+# Ink Explainer
+
+Use for derivation, encoding, formulas, comparisons, relationships, and high-density mechanism teaching. Build on ruled paper with thick rounded SVG paths, blue structure, red action/error, yellow annotation, and green verified conclusions.
+
+Each cue must visibly write, connect, split, calculate, compare, reject, or circle the current knowledge state. Redesign the scene DOM and core SVG for every episode. Never use a narration-length full-area scanning edge.

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/neutral-technical-zh/extension.json

@@ -0,0 +1,15 @@
+{
+  "apiVersion": 1,
+  "id": "neutral-technical-zh",
+  "type": "voice",
+  "version": "1.0.0",
+  "displayName": "中文中性技术讲师",
+  "description": "Natural, clear Mandarin teaching voice profile for technical mechanisms.",
+  "entrypoints": {
+    "reference": "reference.md",
+    "profile": "profile.json",
+    "assets": []
+  },
+  "capabilities": ["voice.tts-profile", "voice.pronunciation", "voice.caption-identity"],
+  "permissions": ["provider:tts"]
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/neutral-technical-zh/profile.json

@@ -0,0 +1,14 @@
+{
+  "providerClass": "configurable-tts",
+  "language": "zh-CN",
+  "voiceId": "configure-on-host",
+  "role": "neutral-technical-teacher",
+  "rate": "+10%",
+  "pitch": "+0Hz",
+  "captionSource": "same-as-tts",
+  "pronunciationPolicy": {
+    "codeIdentifiers": "keep-on-screen-speak-naturally",
+    "underscore": "forbidden-in-spoken-text",
+    "abbreviations": "record-and-listen-before-timing-lock"
+  }
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/neutral-technical-zh/reference.md

@@ -0,0 +1,6 @@
+# 中文中性技术讲师
+
+Use a natural Mandarin teaching delivery: clear logic, restrained emotion, short single-action sentences, and stable pace. The voice ID remains host-configurable so the package does not assume a paid provider or account entitlement.
+
+Caption and TTS come from one string. Keep code spelling on screen but replace `_` and other symbol names with natural spoken wording. Listen to English terms, abbreviations, formulas, numbers, the first sentence, and the final preview before timing is locked.
+

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/paper-theatre/assets/style-tokens.css

@@ -0,0 +1,11 @@
+:root {
+  --cream: #efe1c1;
+  --sheet: #fff8e8;
+  --ink: #211e19;
+  --red: #df4637;
+  --blue: #2766bd;
+  --yellow: #efbd38;
+  --green: #2f8d63;
+  --caption-bg: rgba(255, 248, 232, .96);
+}
+

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/paper-theatre/extension.json

@@ -0,0 +1,15 @@
+{
+  "apiVersion": 1,
+  "id": "paper-theatre",
+  "type": "visual",
+  "version": "1.0.0",
+  "displayName": "Paper Theatre 纸艺编辑剧场",
+  "description": "Physical paper-object transformation for process, evidence, identity, and rules.",
+  "entrypoints": {
+    "reference": "reference.md",
+    "profile": "profile.json",
+    "assets": ["assets/style-tokens.css"]
+  },
+  "capabilities": ["visual.tokens", "visual.semantic-motion", "visual.cover-grammar"],
+  "permissions": []
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/paper-theatre/profile.json

@@ -0,0 +1,12 @@
+{
+  "style": "paper",
+  "styleName": "Paper Theatre 纸艺编辑剧场",
+  "tokenAsset": "assets/style-tokens.css",
+  "motionPlugins": ["DrawSVGPlugin", "MorphSVGPlugin", "Flip", "CustomEase"],
+  "coverGrammar": "top-left-series-cluster-clean-top-right",
+  "fontRoles": {
+    "displayZh": "钉钉进步体 Regular",
+    "latinAndNumbers": "DingTalk Sans",
+    "caption": "Noto Sans SC"
+  }
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/paper-theatre/reference.md

@@ -0,0 +1,5 @@
+# Paper Theatre
+
+Use when the mechanism is best understood as objects being cut, stamped, sorted, folded, compressed, or handed forward. Preserve identity while the object changes state.
+
+Different mechanism roles require different silhouettes and operations. Do not turn every idea into the same paper card. Keep shadows, torn edges, tape, and rotation subordinate to readable knowledge actions.

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/primary-source-research/extension.json

@@ -0,0 +1,15 @@
+{
+  "apiVersion": 1,
+  "id": "primary-source-research",
+  "type": "research",
+  "version": "1.0.0",
+  "displayName": "一手资料研究",
+  "description": "Primary-source evidence profile for explaining mechanisms, systems, and scientific processes.",
+  "entrypoints": {
+    "reference": "reference.md",
+    "profile": "profile.json",
+    "assets": []
+  },
+  "capabilities": ["research.primary-sources", "research.fact-table", "research.current-verification"],
+  "permissions": ["network:read"]
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/primary-source-research/profile.json

@@ -0,0 +1,11 @@
+{
+  "sourcePriority": [
+    "original-research-or-primary-record",
+    "official-documentation-or-standard",
+    "official-repository-or-dataset"
+  ],
+  "communityRole": "discovery-or-counterexample-only",
+  "evidenceFields": ["claim", "source", "sourceType", "verifiedAt", "teachingSimplification", "visualExpression"],
+  "currentVerification": "required-for-versioned-products-APIs-standards-benchmarks-and-prices",
+  "illustrativeNumbers": "label-as-teaching-example-not-measurement"
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/primary-source-research/reference.md

@@ -0,0 +1,5 @@
+# Primary-source research
+
+Use primary records, original research, official documentation, standards, repositories, and authoritative datasets for mechanism facts. Community material may reveal confusing cases or failure symptoms, but does not establish a mechanism by itself.
+
+For every key claim record the source, source type, verification date, teaching simplification, and planned visual expression. Label invented numbers as teaching examples rather than measurements. Recheck time-sensitive APIs, products, standards, prices, and performance claims immediately before scripting.

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/spatial-chamber/assets/style-tokens.css

@@ -0,0 +1,10 @@
+:root {
+  --void: #080b12;
+  --panel: #121a29;
+  --ink: #eef4ff;
+  --cyan: #56d8ff;
+  --violet: #9b7cff;
+  --amber: #ffc457;
+  --alert: #ff5f70;
+  --caption-bg: rgba(8, 11, 18, .92);
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/spatial-chamber/extension.json

@@ -0,0 +1,15 @@
+{
+  "apiVersion": 1,
+  "id": "spatial-chamber",
+  "type": "visual",
+  "version": "1.0.0",
+  "displayName": "Spatial Chamber 空间叙事舱",
+  "description": "Perspective, path, depth, and occlusion grammar for systems, routing, and multi-stage flows.",
+  "entrypoints": {
+    "reference": "reference.md",
+    "profile": "profile.json",
+    "assets": ["assets/style-tokens.css"]
+  },
+  "capabilities": ["visual.tokens", "visual.semantic-motion", "visual.spatial-depth", "visual.cover-grammar"],
+  "permissions": []
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/spatial-chamber/profile.json

@@ -0,0 +1,16 @@
+{
+  "style": "spatial",
+  "styleName": "Spatial Chamber 空间叙事舱",
+  "tokenAsset": "assets/style-tokens.css",
+  "motionPlugins": ["MotionPathPlugin", "DrawSVGPlugin", "Flip", "CustomEase"],
+  "fallbacks": {
+    "MotionPathPlugin": "svg-path-sampling",
+    "DrawSVGPlugin": "stroke-dashoffset"
+  },
+  "coverGrammar": "top-left-identity-central-spatial-mechanism-clean-edge",
+  "fontRoles": {
+    "displayZh": "钉钉进步体 Regular",
+    "latinAndNumbers": "DingTalk Sans",
+    "caption": "Noto Sans SC"
+  }
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/spatial-chamber/reference.md

@@ -0,0 +1,5 @@
+# Spatial Chamber
+
+Use when the explanation depends on location, route, layers, transfer, queues, or several components acting in sequence. Put one state-changing object on an intentional path through a spatial system instead of stacking interchangeable cards.
+
+Depth and camera movement must encode knowledge: foreground establishes the current state, the mid-ground shows transformation, and the background previews destination or consequence. Keep labels facing the viewer, protect caption and title safe areas, and use static SVG path sampling when premium motion plugins are unavailable.

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/strict-release-qc/extension.json

@@ -0,0 +1,15 @@
+{
+  "apiVersion": 1,
+  "id": "strict-release-qc",
+  "type": "qc",
+  "version": "1.0.0",
+  "displayName": "严格发布质检",
+  "description": "Automated media evidence plus muted, audio-only, and normal-watch human gates.",
+  "entrypoints": {
+    "reference": "reference.md",
+    "profile": "profile.json",
+    "assets": []
+  },
+  "capabilities": ["qc.media", "qc.visual", "qc.audio", "qc.release-decision"],
+  "permissions": ["filesystem:project-read", "filesystem:project-write", "process:ffmpeg", "process:ffprobe"]
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/strict-release-qc/profile.json

@@ -0,0 +1,9 @@
+{
+  "blackDetectSeconds": 0.2,
+  "freezeDetectSeconds": 6.5,
+  "silenceDetectSeconds": 0.6,
+  "durationToleranceSeconds": 0.35,
+  "requiredHumanPasses": ["muted-visual", "audio-only", "normal-watch"],
+  "candidateState": "release_candidate_pending_human_listen",
+  "publishState": "passed"
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/extensions/strict-release-qc/reference.md

@@ -0,0 +1,6 @@
+# 严格发布质检
+
+Run content/source checks, page/runtime/layout checks, full MP4 decode, media specification probing, black/freeze/silence detection, representative frames, warning-time frames, and a contact sheet.
+
+Then complete muted visual, audio-only, and normal-watch reviews. Automation can only produce a release candidate. A named human must complete all passes before `release_decision: passed`.
+

creating_explainer_videos_skill/assets/creating-explainer-videos/presets/ai-principle-series/preset.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "id": "ai-principle-series",
+  "version": "1.0.0",
+  "displayName": "AI 底层原理图解系列示例",
+  "description": "Example preset preserving the production rules learned from the AI principle explainer series without branding the core package.",
+  "template": null,
+  "extensions": {
+    "voice": "neutral-technical-zh",
+    "research": "primary-source-research",
+    "qc": "strict-release-qc",
+    "publishing": "douyin-release"
+  },
+  "seriesRules": {
+    "opening": "one-sentence-recap-and-exact-topic",
+    "closing": "one-sentence-next-episode-preview",
+    "cover": "series-season-episode-topic-in-top-left-cluster",
+    "depth": "teach-input-state-change-output-boundary-and-failure",
+    "captionSource": "canonical-narration"
+  }
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/presets/general-mechanism/preset.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": 1,
+  "id": "general-mechanism",
+  "version": "1.0.0",
+  "displayName": "通用机制解释",
+  "description": "Domain-neutral starting point for explaining inputs, internal state changes, outputs, boundaries, and failures.",
+  "template": null,
+  "extensions": {
+    "voice": "neutral-technical-zh",
+    "research": "primary-source-research",
+    "qc": "strict-release-qc",
+    "publishing": "douyin-release"
+  },
+  "contentRules": {
+    "requiredMechanismFields": ["input", "internalChanges", "output", "boundaries", "failures"],
+    "opening": "state-the-exact-question",
+    "closing": "summarize-the-mechanism-and-preview-the-next-question"
+  }
+}

creating_explainer_videos_skill/assets/creating-explainer-videos/references/agent-forward-validation.md

@@ -0,0 +1,17 @@
+# Agent forward validation
+
+Use fresh Agent sessions with one process topic, one science topic, and one domain-specific preset topic. The test passes only when the Agent performs the workflow, not when it merely repeats the documentation.
+
+Record whether each run:
+
+- calls `doctor`, `status`, `next`, and `validate`;
+- chooses a template from the knowledge structure and explains the choice;
+- completes the mechanism/evidence contract before implementing scenes;
+- produces a runnable renderer and dedicated cover;
+- normalizes canonical narration and imports measured timing;
+- keeps captions identical to narration;
+- runs media/visual evidence checks;
+- reports missing tools and paid-provider boundaries honestly;
+- stops at `human_listen` until a named reviewer assesses the exact artifact hash.
+
+A generated file, successful provider response, or passing automated test is not forward-validation success if the Agent bypassed state, evidence, or human gates.

creating_explainer_videos_skill/assets/creating-explainer-videos/references/content-and-script-contract.md

@@ -0,0 +1,75 @@
+# Content and script contract
+
+## 1. Exact promise
+
+Complete `brief.json` before scripting:
+
+- one exact viewer question;
+- one answer the viewer can repeat;
+- audience and prior knowledge;
+- evidence and uncertainty requirements;
+- scope and exclusions;
+- platform, aspect ratio, language, and depth profile;
+- previous/next connection only when the project is part of a series.
+
+The public topic must cover exactly what the video teaches. If the mechanism explains only one stage of a broader concept, name that stage in the title and cover.
+
+## 2. Mechanism completeness
+
+`mechanism-map.json` must include:
+
+1. input objects and representations;
+2. internal state changes in causal order;
+3. output and why it follows;
+4. one worked numerical, symbolic, sample, or system-state example;
+5. one relevant failure, boundary, cost, or control;
+6. a reconstruction that lets the viewer restate the chain.
+
+Use `1700–2200` Chinese characters, `30–45` cues, `10–11` scenes, and `300–420` seconds as a deep-video baseline when the brief calls for a full lesson. They are depth alarms rather than mandatory padding. A shorter result needs a written completeness rationale; a longer result needs a pacing and platform rationale.
+
+## 3. Evidence table
+
+For every important claim record `claim`, `source`, `sourceType`, `verifiedAt`, `teachingSimplification`, and `visualExpression`. Prefer primary records, original research, standards, official documentation, repositories, or datasets. Mark invented numbers as teaching examples. Recheck anything versioned, priced, regulated, scheduled, benchmarked, or otherwise time-sensitive immediately before the script is frozen.
+
+## 4. Scene and cue contracts
+
+Every scene in `scene-spec.json` needs:
+
+```text
+id, title, knowledgePoint, input, transformation, output, compositionTask
+```
+
+Every row in `script/narration.json` and `script/cues.json` needs:
+
+```text
+id, sceneId, text, focus, from, action, to, handoff
+```
+
+`text` is the canonical TTS and caption string. Cue start and duration are added only from measured audio. The visible scene title, active mechanism label, narration, caption, and animation focus must answer the same local question.
+
+## 5. Writing rules
+
+- One cue explains one action or judgment.
+- Introduce the effect before its formal term.
+- Split long thoughts in canonical narration; never shorten only the caption.
+- Keep code/formula spelling in an on-screen field separate from spoken text.
+- Normalize escaped underscores, snake_case, Markdown markers, raw URLs, and punctuation that TTS may pronounce literally.
+- Record pronunciation decisions for English terms, abbreviations, formulas, numbers, and names.
+- Generate speech at a natural rate. Never slow it to meet an arbitrary duration.
+
+For a series, the first sentence joins the previous result to this exact question and the final sentence states the next exact topic plus its value. For standalone work, the first sentence states the exact question and the final sentence reconstructs the reusable answer.
+
+## 6. Authoring order
+
+1. Verify the question and facts.
+2. Complete the mechanism and failure chain.
+3. Write understanding beats.
+4. Choose the dominant visual grammar.
+5. Map beats to varied composition tasks.
+6. Write single-action canonical cues.
+7. Validate semantic alignment and depth.
+8. Generate/listen to real narration.
+9. Import measured timing.
+10. Implement final animation anchors.
+
+Never infer knowledge completeness from scene count and never begin final motion from estimated narration time.