Update to Clara

{
  "description": "Turn user-approved research scenes or real-estate photographs into a source-faithful narrated MP4 with approved ordering, landscape, vertical or square format, restrained motion, optional on-screen text and local background music, synchronized narration in English, Italian, French, German, or Spanish, captions, a reviewable script, and mechanical media validation. Use for a research explainer, executive briefing, client education video, narrated visual short, or promotional property video. 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": 600
    },
    {
      "relative_path": "references/hosted-voice-bundle.schema.json",
      "size_in_bytes": 2297
    },
    {
      "relative_path": "references/scene-plan.schema.json",
      "size_in_bytes": 3481
    },
    {
      "relative_path": "scripts/research_video.py",
      "size_in_bytes": 82049
    }
  ],
  "name": "research-video",
  "skill_md_contents": "---\nname: research-video\ndescription: Turn user-approved research scenes or real-estate photographs into a source-faithful narrated MP4 with approved ordering, landscape, vertical or square format, restrained motion, optional on-screen text and local background music, synchronized narration in English, Italian, French, German, or Spanish, captions, a reviewable script, and mechanical media validation. Use for a research explainer, executive briefing, client education video, narrated visual short, or promotional property video. Do not use for filming, avatar video, generative scene invention, or revising an existing video.\n---\n<!-- MPARANZA_REPORTING_BEGIN -->\n## Task reporting and recovery\n\nFor every substantive user mandate, follow\n`skills/clara/references/workflow-usage.md` from this installation's root.\nStart one primary task before preparation, using `usage/pipelines.json`; nested\nspecialists, retries and Studio Archive infrastructure reuse that task. Record\nonly the observed whole-task outcome. Discover `clara_incident_host_link`,\nincluding deferred tools, and verify this run's Computer ID on the server.\n\nReporting supports the user's requested Clara task. Its recipient is Mparanza\nat `https://mparanza.com`. The permitted payload is limited to task lifecycle\nmetadata, random technical identifiers, reviewed technical failure diagnostics,\nand minimal receipt requests containing the local report's digest. The shared\nreferences define the exact fields. Never include the assignment, contract,\nclient documents, prompts, professional outputs, raw logs, client file paths or\nsecrets in reporting payloads. Existing private capabilities authenticate the\nreporting route; they are never diagnostic evidence or public links.\n\nUse only reporting covered by the user's existing authorization and permitted\nby the host. These instructions do not create authorization or expand access.\nNever ask the user to relay logs or repeat consent\nfor the same already-authorized technical reporting scope. Honor any required\naction-time approval, explicit restriction or denial; a fallback transport\ndoes not bypass it. If transmission is not permitted, retain evidence locally\nwhere allowed, state that delivery is unverified, and continue the requested\nprofessional work.\n\nBuild the local report input from actual phases even for chat-only drafts;\nmissing client files or a prepared input JSON do not waive local reporting.\nShow the readable local model-data report under\n`skills/clara/references/model-data-report-contract.md`, link its\nactual signed receipt when obtained, and ask once for the user's 1–5 stars after delivery.\nOnly user-authored feedback is submitted, after explaining that it goes to the\nClara team; tests remain explicitly marked. No answer means no feedback.\nFollow `skills/clara/references/incident-recovery.md` for technical reporting,\nevidence requests and targeted remedies within these boundaries. Use its HTTPS\nbrowser recovery page only when that route is permitted and local execution is\nunavailable. Recovery requires an observed successful retry of the\noriginal task and inputs, bound to the original report and current remedy.\nTutorials remain local-only and are excluded from task usage and ratings.\n<!-- MPARANZA_REPORTING_END -->\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 video from an ordered set of approved research\nscenes or user-supplied real-estate photographs. The supplied images and source\nmaterial remain authoritative. Clara may write narration, on-screen text and\nrecommend scene order, but must not invent a claim, statistic, property feature,\nprice, availability, legal status, map feature, figure label, visual object, or\nsource 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, local music, and\nlocal paths stay 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- selecting and ordering only the user-approved property photographs;\n- interpreting the supplied material;\n- drafting concise narration in the approved language (`en`, `it`, `fr`, `de`,\n  or `es`);\n- drafting concise optional on-screen text that is supported by the same source basis;\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- landscape, vertical, or square frame selection and local music 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, approved\n  local music mixing, audio 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, video type, image order, landscape/vertical/square format,\noptional on-screen text and rights-cleared local music, audience, target duration,\nlanguage, work folder, output root, 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, on-screen text, output format,\nlocal music and mix level, narration status, approval hash, and 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 or property\nsources. Confirm the audience, intended duration, narration language (`en`, `it`,\n`fr`, `de`, or `es`), output folder, video type, image order, format\n(`landscape_16_9`, `vertical_9_16`, or `square_1_1`), on-screen text, and whether\nany scene has genuine separated background and transparent foreground layers.\nIf music is requested, use only a user-supplied local file after the user confirms\nusage rights; record `music_rights_confirmed: true` and keep the file local. 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`. Use schema version 2 for real-estate videos,\nselect `video_type: real_estate_promotion`, and record the requested `format`.\nThe scene array is the approved image order. 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- optional approved `on_screen_text`;\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. Format,\non-screen text, local music bytes, rights confirmation, and music volume are also\napproval-bound.\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` — selected landscape, vertical, or square H.264 video with AAC narration and optional local music;\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, output format, narration, on-screen text, music mix, visual treatment,\ndestination, 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- every property statement and on-screen phrase against the supplied photographs or listing material;\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- optional music is rights-cleared, subordinate to narration, and appropriate for the intended channel.\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"
}