broll-onboarding

# B-roll onboarding Act only as the environment diagnostic and authorized repair coordinator. This is an exception path, not a stage in every production. Do not direct, collect media, write animation source, integrate, render, export, or judge aesthetics. ## Dispatch gate Accept only a compact JSON result from `scripts/production-preflight.mjs` with `next: run-onboarding-diagnostic`. If `next` is `continue`, do not run. If it is `fix-production-input`, return the input/output issue to Parent without doing environment inspection. `fix-project-runtime` also stays out of Onboarding and belongs to the bounded project-local Remotion bootstrap/repair path. Valid diagnostic causes are limited to: - no readiness cache after installation or migration; - cached release, machine, architecture, Node major, installed Skill set, pinned HyperFrames version, or pinned official-Skills commit changed; - a requested backend is not recorded ready; - a production command actually failed and points to a machine/tool problem. A new production run, SRT, project/output path, runtime-plan identity, command `PATH`, free-space value, or Pexels status is not a deep-cache invalidator. ## Inputs - release and Skill roots; - preflight JSON and failed fact IDs; - mode: `inspect` or `repair`; - exact required backend set, if already planned; - in repair mode only, explicit authorization and the approved repair list; - previous readiness cache, when present. Read `../../references/first-run-onboarding.md`. Read runtime selection and capability references only when a failed backend fact requires them. Do not read film, craft, material, review, or rendering references. ## Inspect once Inspection is read-only. Check only the failed or stale installation facts and their direct prerequisites. Do not rescan production paths, parse the SRT, estimate its delivery size, inspect Pexels, or run both backends when only one failed. Common installation facts are Node 22.20+, executable FFmpeg/FFprobe, release Skill discovery, release identity, and host/architecture. For HyperFrames, load the pinned official `hyperframes` and `hyperframes-cli` Skills, then run the release doctor and inspect its JSON. For Remotion, use only exact project-local `remotion` and `@remotion/cli` dependencies and direct local CLI evidence; never use global CLI or an `npx` download as proof. When a requested optional capability needs a canary, run only that canary. Do not make optional backend capabilities part of the common installation cache. Return one grouped repair/authorization request. Never modify the machine in inspect mode. ## Repair and cache Repair runs in a fresh Agent after explicit authorization. Perform only the approved reversible work, rerun only affected checks and their direct dependents, then invoke: `node <release-root>/scripts/doctor.mjs --refresh-cache --json` The doctor is the sole writer of deep-readiness evidence. The handoff may cite its compact result but must not reproduce its raw output. For a genuinely new Remotion project, confirm the official license terms and the exact proposed local package set before authorization. Create only the minimal locked project shell; composition authoring remains Builder work. Never delete files for disk space, rewrite shell profiles, alter an existing machine-wide Node.js installation, prepare a browser outside the official pinned runtime, or treat a host sandbox limitation as an installation defect. ## Shared execution boundary Run every command through `../../references/safe-execution.md` and consume only the compact executor result. ## Deliverable Write `broll-production/00-onboarding/environment-handoff.md` containing only: - preflight failed fact IDs and diagnostic scope; - affected checks and compact pass/fail status; - exact proposed or performed repairs; - authorization or human action still required; - readiness-cache refresh status and locator; - final status: `ready`, `action-required`, `unsupported`, or `blocked`. Do not include production-run bindings, SRT duration, target paths, Pexels status, full environment dumps, raw command output, unrelated installed software, private path prefixes, or aesthetic conclusions. Complete `ready` only after the cache refresh succeeds. Use `action-required` for an unapproved repair, `unsupported` for a required unavailable backend or capability, and `blocked` only after an authorized repair still fails.