ClearFrame agent instructions

ClearFrame renders with the scene engine (packages/engine/src/scene/, Skia on Metal, driven by a compiled scene plan), its only renderer: it draws the 31 blocks, native stages, film compositing and footage itself; see docs/scene-engine.md. fframes (MIT, pinned in archive/fframes/upstream.json) is the film runtime for renders: it schedules frames, encodes GOP-aligned segments in parallel and concatenates them, while each of its workers draws with the scene engine (packages/engine/src/scene/native/src/runtime.rs, docs/fframes-return.md). CLEARFRAME_RUNTIME=scene keeps the engine's old FFmpeg pipe for comparison only; there is no fallback renderer. Begin with skills/clearframe/SKILL.md, then skills/clearframe-library/SKILL.md. Use skills/clearframe-engine/SKILL.md for project commands, skills/clearframe-scene/SKILL.md for native stages and engine changes, and skills/clearframe-blocks/SKILL.md plus packages/engine/src/film/AGENTS.md for block internals. Runtime integration and upgrades are documented in docs/fframes-return.md.

• Workplace and financial-services films (benefits, retirement, open enrollment, pay, policy, training, onboarding, client updates) start with skills/clearframe-workplace/SKILL.md: the workplace treatment, a fill-in-the-blank sketch per kind of fact (match, vesting, deadline, expire, limit, was-now, share, portal, inspect, choose, split), a document for the policy's own words, a receipt drawn from its lines, an app (through its pages) or crumbs with a pointer for the step in the app, and the motion verdict from draft.
• Podcasts, interviews and other recordings start with ingest DIR --audio FILE [--script turns.txt] [--vertical]: the film plays the recording itself, with its words measured. Never scaffold a playbook for a recording or re-voice it. Then give the ideas pictures: the paper edit (paper DIR) suggests one per beat; examples/podcast-pictures is a worked clip.
• Author one storyboard, using block and validated props. Run playbooks, blocks, treatments and sketch before inventing a scene.
• Adapt structure to the story. Playbooks and treatments are reusable starting points, not limits on possible films. Source material (reports, recordings) goes through ingest; references through reference; see skills/clearframe-direction/SKILL.md.
• New palettes, treatments, type voices, sketches and playbooks are files in packages/engine/src/library/ (see packages/engine/src/library/README.md); engine code is for new capabilities. A project's library/ or --library DIR overrides built-ins, JSON only.
• Native GPU stages (stage block, beat stage, film stages) carry actors with stable identities, links, packets, callouts, commit-grounded code, footage textures, SkSL materials, particles, a 2.5D camera and motion blur. They use the canvas element dialect; canvas-only features are refused on stages by name, never dropped.
• Films are not slide decks, and not trailers either (read skills/clearframe-motion/SKILL.md; critique prints a film score from the eight tells of a slideshow): keep a subject on screen that changes with the voice (canvas, a cast, one world), point at words with marks, cut by default and carry something across each cut (a shared id, a world; into an element of the last scene at a turn), move the camera for a reason, and run critique before rendering. There are no film looks (letterbox, grades, flash cuts, swells) in the library.
• To explain how or why something works, on any subject, read skills/clearframe-explain/SKILL.md: canvas graph, accumulate, estimate and field draw a picture that changes, from a stated formula or a seeded, labelled simulation. They show behaviour, never data.
• Choose palette, type voice (type, usually from the treatment; types lists them), motion preset/intensity and entrances explicitly. Follow docs/style.md; use looks to compare one scene across palettes. Keep slide counters out of film output.
• New GitHub code/assets must be MIT-licensed at the exact imported revision, with bundled notices/provenance; bundled fonts are SIL OFL 1.1 from google/fonts at a pinned revision with hashes in packages/engine/src/film/assets/fonts/provenance.json. Prefer independently implemented ideas over adding another renderer; see docs/research/2026-github-video-patterns.md.
• For speech-following text read docs/speech.md. Never call interpolated timestamps measured. Final kinetic/captioned scenes require word timings tied to the current audio hash; align --whisper measures them locally for free.
• Keep factual text, charts and labels native. Every displayed number needs visible attribution and a sources entry. Never present sample figures or fictional quotes as evidence.
• For brand-sensitive art, use imagegen to explore materials and geometry, then rebuild selected ideas with palette tokens and native fonts; see docs/image-direction.md. Generated stills are a regular tool for places: depth plates (layers: true assets, plates on a canvas) put the camera inside painted scenes. Never put text, numbers or evidence in an image, and run plan first. Generated footage is sparing (default review threshold 20% of runtime). Read docs/continuity.md and the Gemini Omni skill. Use references and the film palette; review both joins. Discard generated clip audio and keep the shared mix. Footage-led shots follow docs/hero-footage.md: approved keyframe stills before any video call, cheap drafts before one final render, and seedance2_5 (Runway) or Veo per shot.
• Work guided (stop at the human checkpoints) unless asked for a one-shot film; in one-shot mode decide and log each checkpoint in DIRECTION.md (decide DIR rNNN for the rough cut and final). See docs/collaboration.md and checkpoints DIR.
• Show motion before bespoke work: the first look is a full-length rough cut (draft DIR --rough) from existing blocks, captions and declared placeholder beats; drawing every beat and reviewer rounds come after the person's notes. --rough relaxes only declared stand-ins, never facts, sources, audio or timing.
• Feedback goes through review/ (docs/editing.md, skills/clearframe-review/SKILL.md): record notes against the revision watched (note --rev), edit only the note's beats, revise for a before/after candidate, and record only what the person actually said with accept/reject --by NAME --said. Applied is not accepted. Edit recorded narration with cut/uncut/split/merge, never by changing vo.
• Run plan before paid generation and honor the user's scope/budget. No paid calls merely to test code.
• Render sheet, open the image, run check, then render/review the complete MP4. Use review DIR for decoded frames around cuts and word boundaries, and qa DIR for time bugs a still cannot show (one-frame pops, stretches where the picture barely changes, world seams that jump, export tags, loudness, the music drop) plus a 360 px phone sheet. Both bind the video to its receipt first (evidence in qa.json: bound, unbound, stale or invalid); only bound evidence is about the film. Passing diagnostics alone does not establish visual quality, accurate transcription or factual correctness.
• Native frame output must depend only on frame number and prepared inputs (job, plan, staged media, bundled fonts). No live generation, random state or wall-clock animation in the renderer's frame function (blocks, stages or compositing).
• The library holds sources, not outputs. Never commit renders, contact sheets, review evidence or receipts; they go to build/. Add one curated example per capability, judge its rendered frames against professional references (an FT or Bloomberg chart, a premium brand film) before committing, and keep on-screen copy product-native: no disclaimers about what a picture does not measure. test/repo-hygiene.test.mjs enforces the binary allowlist.
• Preserve unrelated changes. Archived browser source is for recovery only; no fallback renderer is active.
• The renderer (packages/engine/src/scene/native) keeps its Cargo target in ~/.cache/clearframe/scene/target (or CLEARFRAME_SCENE_CACHE/target); never commit it (test/repo-hygiene.test.mjs). Native builds use one Cargo job and at most two supported workers. On this 8 GB Mac, run one full render or full test suite at a time. Reuse the warm cache and retain at least 20 GiB free before expensive work. Full high-resolution renders need at least a five-minute harness allowance or resumable execution, including audio finishing; keep waiting on the same process.
• docs/guide.html is the living guide: how ClearFrame works and how to prompt it. When a feature, command or rule changes, update the guide in the same change (its header comment lists the sources of truth), along with the CHANGELOG.
• Keep strict TypeScript, Effect boundary decoding and the configured lint rules enabled. Run the workspace guardrails for runtime changes. Add focused behavior tests for regressions and failure paths; do not claim visual or provider acceptance from compiler checks.
• When independent custom scene work benefits from parallel agents, give each agent one owned native module and the storyboard/visual brief; avoid concurrent heavy builds.

Useful commands: pnpm cf help, doctor, build, new DIR --playbook NAME --treatment ID, ingest DIR --markdown|--audio, reference VIDEO, themes, treatments, sketch, critique DIR, voice DIR --draft, align DIR --whisper, sheet DIR --draft [--grid], check DIR --draft, render DIR --draft, qa DIR, beatmap DIR, paper DIR, draft DIR --rough, note DIR, revise DIR --note ID, diff DIR, runlog DIR. Install with pnpm install --frozen-lockfile, then pnpm build. Full workspace validation: pnpm guardrails; Node contract tests: pnpm test. Tests import the built runtime, so rebuild after source edits. The review loop end to end (native, local Whisper): node scripts/review-e2e.mjs OUT. Engine coverage and measurements: scripts/engine-parity.mjs OUT, scripts/engine-bench.mjs OUT PROJECT…, scripts/engine-coverage.mjs; Rust tests for the scene crate: cargo test --manifest-path packages/engine/src/scene/native/Cargo.toml --release --locked --jobs 1 with CARGO_TARGET_DIR="$HOME/.cache/clearframe/scene/target".