Update to Clara

{
  "description": "Turn a user-approved ordered set of research scene images into a source-faithful 16:9 narrated MP4 with restrained motion, synchronized narration in English, Italian, French, German, or Spanish, captions, a reviewable narration script, and mechanical media validation. Use for a research explainer, executive briefing video, client education video, or narrated visual short. Do not use for filming, avatar video, generative scene invention, or revising an existing video.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 326
    },
    {
      "relative_path": "references/hosted-voice-bundle.schema.json",
      "size_in_bytes": 2297
    },
    {
      "relative_path": "references/scene-plan.schema.json",
      "size_in_bytes": 2483
    },
    {
      "relative_path": "scripts/research_video.py",
      "size_in_bytes": 70541
    }
  ],
  "name": "research-video",
  "skill_md_contents": "---\nname: research-video\ndescription: Turn a user-approved ordered set of research scene images into a source-faithful 16:9 narrated MP4 with restrained motion, synchronized narration in English, Italian, French, German, or Spanish, captions, a reviewable narration script, and mechanical media validation. Use for a research explainer, executive briefing video, client education video, or narrated visual short. Do not use for filming, avatar video, generative scene invention, or revising an existing video.\n---\n\n<!-- CLARA_OPENAI_ONBOARDING_BEGIN -->\nOnboarding is optional. Continue ordinary professional work immediately,\nincluding direct specialist invocation, without checking or completing a local\nonboarding profile. Missing, unfinished, inaccessible or corrupt onboarding state,\nor unavailable voice/window controls, must never block ordinary work. Do not\nautomatically start, resume or repeatedly offer onboarding.\nOnly for a user-requested tutorial or a native teaching handoff, read\n`../clara/references/local-onboarding.md`. A verified paired lesson worker\nexecutes only its bound lesson and token; never bypass tutorial validation.\nTutorial profiles, progress, examples and feedback remain local; never send a\nchange request, stamp a tutorial receipt or call hosted interviews for a tutorial.\nCurrent user requests take precedence over saved preferences.\n<!-- CLARA_OPENAI_ONBOARDING_END -->\n\n# Research Video\n\nAfter substantive use of this workflow, read and follow the `Plugin Improvement Feedback` section in `../clara/SKILL.md`.\n\nCreate one short, source-faithful research video from an ordered set of approved\nscene images. The supplied images and source material remain authoritative.\nClara may write narration and recommend scene order, but must not invent a\nclaim, statistic, map feature, figure label, visual object, or source basis.\n\n## Runtime and output boundary\n\nThe complete workflow uses the authenticated Mparanza Research Video voice\npage to generate one audio artifact per approved scene, plus a local Clara\nruntime with Python and FFmpeg to build the MP4. No user API key is required.\nMparanza holds the provider credential; the packaged renderer contains no\nprovider credential and makes no direct speech-provider call.\n\nThe hosted service is currently open to every authenticated Mparanza account;\nthere is no Research Video email allowlist. Only the exact approved narration,\nlanguage, scene identifiers, and approval/plan hashes cross the hosted boundary.\nImages, research sources, source-basis notes, Vera artifacts, and local paths\nstay in the local workspace. Mparanza builds the response ZIP in memory and does\nnot write the request or generated audio to application storage. OpenAI receives\nthe narration under Mparanza's provider arrangement; do not infer or promise an\nOpenAI retention period from this workflow.\n\nKeep all run inputs and outputs outside plugin source and static/public folders.\nUse an output folder beside the user's project material unless the user names a\ndifferent destination. Never put an API key in chat, a scene plan, a command\nargument, a log, or an artifact.\n\n## Decision boundary\n\nClara owns semantic work through model-led review:\n\n- selecting and ordering only the user-approved research scenes;\n- interpreting the supplied material;\n- drafting concise narration in the approved language (`en`, `it`, `fr`, `de`,\n  or `es`);\n- deciding what each scene contributes to the argument;\n- checking that narration says no more than its recorded source basis;\n- identifying qualifications, uncertainty, and claims that should be removed.\n\nDeterministic code owns work whose correctness is mechanically verifiable:\n\n- scene-plan schema, path, file-type, dimension, and size validation;\n- SHA-256 fingerprints for the plan and every visual layer;\n- approval binding to the exact narration and visual plan;\n- hosted voice request and bundle-manifest shape, scene-audio conversion and\n  hashes, scene timing, caption timing, motion rendering, cross-fades, audio\n  normalization, MP4 assembly, decoding, and artifact hashes.\n\nMparanza sends the exact approved narration to OpenAI using the centrally\nselected model and language-specific voice, then returns an in-memory ZIP. The\nlocal attachment code validates the source marker, request and approval hashes,\naudio bytes, WAV metadata, duration, and scene order. These checks prove bundle\nintegrity; they do not prove pronunciation or semantic delivery.\n\nThe renderer requires source-basis entries but cannot judge whether they truly\nsupport the narration. Clara must perform that semantic review before asking\nfor approval, and the user remains the final reviewer.\n\n## Vera handoff boundary\n\nKeep Research Video Clara-owned. When the input comes from Vera, use only the\nexact accepted visuals and their current review artifacts from the relevant\nVera workflow. For a legal, tax, regulatory, accounting, social-security, or\nprofessional communication, Vera continues to own source authority, governing\nframework, applicability, claim assurance, professional acceptance, and any\nsend or publication decision. Clara may turn those accepted materials into the\nreviewable video, but the presence of `source_basis` does not repeat or replace\nVera's professional review.\n\nDo not route an unsupported Vera question to Research Video merely because a\nvideo was requested. Finish the applicable Vera workflow first; if no Vera\nworkflow covers the professional task, stop rather than using the video plan as\nan assurance substitute.\n\n## Hosted-Voice Run UX\n\nBefore write-heavy work, show a compact Run Intake table with source files,\napproved scene images, audience, target duration, language, work folder, output\nroot, privacy boundary, and review status. Keep a short checklist for source\ninspection, scene plan, narration review, approval, render, mechanical checks,\nsemantic review, and delivery.\n\nUse a Decision Table for resolved facts and evidence: scene order, source basis,\nvisual-layer availability, selected motion, narration status, approval hash,\nand render status. These are facts to verify, not choices to propose after the\nuser has already requested a complete narrated video.\n\nBefore voice generation, show one execution checkpoint naming the run folder,\nexact approved plan, scene count, Mparanza/OpenAI voice policy, and expected\nartifacts. State that no user API key is involved. Default output policy: keep\nthe canonical plan, intake, narration, Mparanza voice request,\nvoice manifest and audio, review packet, approval, MP4, poster, captions,\nreports, and artifact manifest outside plugin source. The generated ZIPs belong\nin the repository only during an explicit plugin package or release task; never\nedit them by hand.\n\nAt delivery, return an Artifact Card linking the MP4, poster, captions,\nnarration script, Mparanza voice request, attached voice manifest and scene audio,\nrender report, final artifact manifest, and editable run folder. Include source\ncount, scene count, duration, narration language, voice, the localized on-screen\nAI-voice disclosure, motion boundary, validation status, and any residual issue.\nWrite `codex_run_review.md` when the run is blocked, a fallback is accepted, or a\nrepeated failure needs a durable handoff note.\n\n## Workflow\n\n### 1. Establish the run intake\n\nRun Clara's dependency check from the Clara plugin root:\n\n```bash\npython scripts/check_dependencies.py\n```\n\nInspect every proposed scene image and the controlling research sources. Confirm\nthe audience, intended duration, narration language (`en`, `it`, `fr`, `de`, or\n`es`), output folder, and whether any scene has genuine separated background and\ntransparent foreground layers. Ask only about unresolved choices that\nmaterially change the story or output.\n\nUse chat and Markdown for review. A separate HTML application is unnecessary\nfor this bounded ordered-scene workflow.\n\n### 2. Author the scene plan\n\nCreate `scene-plan.json` outside plugin source using\n`references/scene-plan.schema.json`. Each scene requires:\n\n- a stable `id`;\n- one approved local `image`;\n- the exact narration text to synthesize in the declared language;\n- at least one `source_basis` item naming a reference and what it supports;\n- optional restrained `motion`.\n\nSupported flat-image motion is `zoom_in`, `zoom_out`, `pan_left`, `pan_right`,\nor `static`. Flat images do not become true parallax. Use\n`layered_parallax` only when the user supplies both a clean background image and\nan aligned transparent PNG `foreground_image`; never manufacture depth layers\nfrom the research image.\n\nPrepare the run:\n\n```bash\npython scripts/managed_python_runtime.py run \\\n  skills/research-video/scripts/research_video.py prepare \\\n  --scene-plan <scene-plan.json> \\\n  --output-dir <project-output-folder>/research-video\n```\n\nPreparation writes `run_intake.json`, a canonical `scene_plan.json`, a clean\n`narration_script.md`, and `review_packet.md`. It does not create the hosted\nrequest, invoke voice, or render media.\n\n### 3. Review and bind approval\n\nRead `review_packet.md` completely. Re-open the source when a claim, number,\nlabel, qualification, or visual meaning is material. Compare each narration\nscene with its source basis and image. Remove unsupported language rather than\nsoftening it into an untraceable claim.\n\nShow the narration script and explain that Mparanza will send the exact approved\nnarration to OpenAI. Images, source-basis notes, Vera artifacts, and local paths\nare not part of the hosted request. No user API key is used. The exact narration\nstill requires approval because it becomes a professional-facing spoken\nartifact. The review packet also shows the localized AI-voice disclosure that\nremains visible on every scene.\n\nAfter the user approves the exact script and visual plan, bind that approval:\n\n```bash\npython scripts/managed_python_runtime.py run \\\n  skills/research-video/scripts/research_video.py approve \\\n  --run-dir <project-output-folder>/research-video \\\n  --approved-by <reviewer> \\\n  --confirmed-by-user\n```\n\nAny later change to narration, scene order, motion, source basis, or image bytes\ninvalidates the approval and requires preparation and approval again.\nApproval writes `narration_approval.json` and the minimal,\nhash-bound `mparanza_voice_request.json`.\n\n### 4. Generate and attach hosted voice\n\nOpen `https://mparanza.com/case-notes/research-video/voice`, sign in to\nMparanza, upload `mparanza_voice_request.json`, and download the returned ZIP.\nThe service uses the server-held provider credential and the fixed policy in\n`scripts/video_voice_policy.py`; never request or accept a user API key. The ZIP\nmanifest follows `references/hosted-voice-bundle.schema.json`.\n\nAttach and normalize the downloaded bundle locally:\n\n```bash\npython scripts/managed_python_runtime.py run \\\n  skills/research-video/scripts/research_video.py attach-voice \\\n  --run-dir <project-output-folder>/research-video \\\n  --voice-bundle <research-video-voice.zip>\n```\n\nThe attachment step rejects path traversal, symlinks, duplicate or undeclared\nZIP entries, unexpected fields, changed request/approval hashes, wrong provider\npolicy, incomplete scene order, stale WAV metadata, and changed audio bytes. If\nthe hosted service cannot return the bundle, leave the run\n`approved_for_hosted_voice`; do not request an API key or substitute another\nvoice.\n\n### 5. Render and validate\n\nRender only after approval and hosted voice attachment:\n\n```bash\npython scripts/managed_python_runtime.py run \\\n  skills/research-video/scripts/research_video.py render \\\n  --run-dir <project-output-folder>/research-video\n```\n\nRendering is local and requires no network access. The renderer consumes the\nattached hosted voice artifacts, applies calm professional delivery already\ncaptured in those files, and displays the localized disclosure that the voice\nis AI-generated. It produces:\n\n- `research_video.mp4` — 16:9 H.264 video with AAC voice-over;\n- `poster.jpg` — first-scene poster;\n- `captions.vtt` — scene-aligned captions in the narration language;\n- `narration_script.md` — the approved narration;\n- `mparanza_voice_request.json` — exact minimal hosted request per scene;\n- `hosted_voice_manifest.json` — attached audio provenance, hashes, and duration;\n- `hosted_voice/*.wav` — normalized scene-level narration artifacts;\n- `render_report.json` — input hashes, timing, voice, media and validation data;\n- `final_artifacts.json` — final handoff and readiness state.\n\n## Codex-Native Run UX\n\nUse a compact checklist covering dependency readiness, source and visual\ninventory, exact narration review, bound approval, hosted voice attachment,\nlocal rendering, and final media validation. Before preparation, show a Run\nIntake table with the audience, language, intended duration, ordered scene\nimages, source basis, output directory, and missing inputs.\n\nShow a Decision Table only when a missing choice materially changes the scene\norder, narration, visual treatment, destination, or professional-review scope.\nThe Default output policy is to prepare the review packet, wait for exact\napproval, attach the authenticated hosted bundle, render locally, and validate\nthe final artifacts; these are not choices to propose when the user has already\nrequested a complete Research Video run.\n\nEnd with an Artifact Card linking the MP4, poster, captions, narration script,\nhosted voice manifest, render report, and final artifact manifest. Create\n`codex_run_review.md` only when blocked evidence or a repeated manual correction\nneeds a durable developer note. Never edit generated ZIPs or packaged plugin\ncopies directly; rebuild them from plugin source.\n\n### 6. Final semantic review\n\nThe render report records measured video and decoded audio duration, frame rate,\ndimensions, codec checks, tool versions, and caption timing against both streams.\nCues are also checked against the approved scene speech durations before output\npublication. These checks establish timing and media integrity; they do not\nreview the meaning of captions or narration.\n\nWatch the complete MP4 and inspect the poster, captions, narration script,\nrender report, and final artifact manifest. Mechanical validation proves media\nshape and byte integrity, not scientific fidelity or editorial quality. Check:\n\n- every spoken claim against its supplied source basis;\n- figures, maps, text, labels, and statistics remain legible and uncropped;\n- scene order supports the intended research argument;\n- motion clarifies rather than distracts;\n- transitions do not interrupt speech;\n- pronunciation, pacing, captions, AI-voice disclosure, and qualifications are\n  acceptable.\n\nIf any issue is material, revise the scene plan, prepare again, obtain a new\napproval, and rerender. Deliver only when the final review is complete. State\nplainly when a flat-image run has no true parallax.\n\nRender attempts are serialized per run directory. Inspect `render_attempt.json`\nbefore relying on a saved render report: only `completed` describes a completed\ncurrent invocation; `running` is unfinished and `failed_or_interrupted` is a\nfailed attempt. Retained `.render-attempts/<attempt-id>/` directories contain\nstage media, streamed process logs, the attempt record, and previous report /\nmanifest evidence. A retry preserves these diagnostics. On failure, top-level\nrender and artifact reports explicitly lose their successful status. Recheck\napproved input bytes and final output hashes before delivery; an old report or\nan existing MP4 alone is insufficient evidence of current success.\n\nAfter rendering, verify the publication before reviewing or handing it off:\n\n```bash\npython scripts/managed_python_runtime.py run \\\n  skills/research-video/scripts/research_video.py verify \\\n  <project-output-folder>/research-video\n```\n\n`current_render.json` is the authoritative publication pointer. A successful\npointer references the complete `published/` snapshot inside its retained\nattempt directory. Use the verified `generation_directory` and its manifest for\nhandoff. Top-level media files are convenient working copies and may be replaced\nduring a retry. The pointer commits only after every snapshot artifact matches\nits declared hash. Verification rechecks snapshot bytes and current approved\nvisual/narration/voice inputs; semantic, voice-content and visual review are still\nrequired. A failed or unfinished current pointer must not be replaced by an old\nsuccessful report when describing the current run.\n"
}