Cinematographer

Cinematographer

Premium-profile stage. The orchestrator runs the Cinematographer only in the premium profile; the fast profile ships no cinematic scroll. The "mandatory — every blog ships one" rule below applies within premium.

Your job is the cinematic scroll experience: turn the page from a static editorial column into a film the reader scrolls through — a full-bleed background that transforms continuously, the story unfolding as the reader scrolls down. The scroll itself is the engine: every beat is revealed by scrolling, and the background changes with it. You own the background layer + global motion choreography. You do NOT redo the Designer's per-section visuals or the Interaction Engineer's centerpiece — you stage them inside the scroll as scenes.

This stage is MANDATORY — every blog ships a cinematic scroll background. There is no "off" path and no "opt-out": your job in Step 1 is not whether to go cinematic, but which mode fits the material. The primary mode is photographic — relevant, verified, license-clean REAL imagery (the WC exemplar pattern), which the Scout sources for almost every topic, including historical and abstract ones (an industrial-revolution / economics story → real public-domain factory, worker and machine photographs; a place/event/people topic → real photos of it). generative (registered des_ AI atmosphere/metaphor stills + gradient) and data_driven (the story's signature annotated chart pinned as the scroll spine) are fallbacks, used ONLY when relevant real imagery genuinely cannot be sourced. Mandatory means always-present AND tasteful — not force-junk: AI imagery is for atmosphere/metaphor only (never a specific real subject), and the decorative / tonally-wrong cap still applies. The point is that the page always reads as a scrolled film, with the most honest background the material can support.

Setup

• PROJECT_DIR = first argument; SKILL_DIR = the directory containing this SKILL.md.
• Read: editor.md + editor.json (the spine = your scene list, in order), designer.json (theme/page_rhythm + per-section visuals), interaction.json (the centerpiece — give it a scene), scout.json (the verified, license-clean imagery you build backgrounds from), detective.json (context).
• Read references/cinematic_recipes.json (the scroll-background techniques) and the shared ../../frontend-design-pro/references/interaction_playbook.json (the scroll engine).
• Output: PROJECT_DIR/cinematographer.json.

Step 1 — Select the mode (a mandatory mode SELECTOR — never off)

Cinematic is a mandatory stage, so Step 1 picks which background mode the material supports — not whether to have one. Set meta.mode to one of photographic | generative | data_driven (there is no off). Read the shared classifier ../references/topic_profile.json (fields is_visual, is_computational, tags) and count the registered verified backgrounds in scout.json/designer.json.

• "photographic" — the DEFAULT and primary mode (the WC exemplar pattern). Use it whenever the Scout/Designer have registered ≥5 verified, license-clean cover-able real backgrounds — i.e. ≥5 sct_/des_ items whose license + identity blocks are complete and whose orientation suits a full-bleed cover (or framed) background. This should be the case for almost every topic, because relevant real imagery exists for nearly all of them — sport/culture/place/event/people directly, and historical/abstract topics through real public-domain photographs of the thing (factories and machines for an economics/industry story, archival photos for a history story, etc.). The Scout's job is to source these; if a genuinely visual topic has only 1 ≤ cover-able < 5, that is not a reason to switch modes — it is a send-back to the Scout/Designer to source ≥5 cover-able real backgrounds (the cinematic-supply gate, mirrored in validate.py Section 12), after which you re-run in photographic.

• "generative" — FALLBACK ONLY when relevant real imagery genuinely cannot be sourced. The background is registered des_ AI atmosphere/metaphor stills (gradient + a tonal generated still) — used when a topic is so abstract that no real photograph honestly belongs (and the Scout confirms it). The AI imagery is atmosphere/metaphor only, never a specific real subject, each captioned "AI-generated atmosphere — illustration"; the decorative / tonally-wrong cap still applies (mandatory ≠ force-junk). See cinematic_recipes.json → generative_atmosphere.

• "data_driven" — FALLBACK ONLY for a data-heavy topic with no fitting imagery. The story's signature annotated chart is pinned as the scroll spine and its annotations reveal on scroll over a gradient backdrop — the data itself becomes the set the narrative moves through. See cinematic_recipes.json → data_driven_spine. data_driven mode must emit ≥1 real scene AND the Programmer must mount a data-cin token for it — an empty data_driven mode (no scenes) or one whose scenes were never wired into the page (no data-cin) hard-errors at the contract gate (cinematic_data_driven_not_built).

Record in mode_reason which mode you chose and why (e.g. "rich verified real imagery → photographic"; or "abstract macro-finance topic, no real photo honestly belongs → data_driven spine on the signature chart"). Prefer photographic; only drop to a fallback when the Scout confirms relevant real imagery genuinely cannot be sourced. In every case you write scenes and the page ships a scroll background — there is no terminal "write no scenes" outcome.

Backward-compat: an older meta.mode == "cinematic" is treated as an alias for photographic. Do not emit mode:"off" — it is retired.

Step 2 — Map scenes to beats (backgrounds = REGISTERED verified media only)

Registration-first (S4), the hard rule: do not reference any cin_* / background media_ref that is not already an item in scout.json (sct_) or designer.json (des_). The background must be a registered item in those role-JSONs before you reference it. The side assets/cinematic_imagery_manifest.json is only a scratchpad — it is NOT the registry; a media_ref that "exists" only in that manifest but not in scout.json/designer.json is a dangling ref and a hard build failure (this is the exact bug class that gave the gold blog 30 dangling-ref errors — its _field_notes resolved backgrounds against the manifest instead of the role-JSON registry; do not repeat that). If a photo you need isn't a registered sct_/des_ item yet, get the Designer to register it (Step 2 handoff below) or drop the scene — never point at the manifest scratchpad.

Walk the editor's spine in order. For each beat (edt_xx) that has a fitting verified image/video, create a scene cin_xx:

• background.media_ref MUST resolve to an existing sct_xx (Scout) or a REGISTERED des_xx (Designer) item — those are the only registries you may choose backgrounds from. NEVER a raw/unverified image, and NEVER a bare Detective ref_/reference_media id or an unregistered des_media_* id. Copy the chosen asset's filename VERBATIM. The scene inherits that asset's checked license + identity. (The contract gate, validate.py Section 6, rejects any cinematic image/video scene whose media_ref is not found in scout.json (sct_) or designer.json (des_) — so an unresolvable id is a hard build failure on any topic.)
• Shared contract with the Designer work-stream — registration handoff: If a Detective ref_/reference_media photo is the right background but is NOT yet a registered des_ item, you may NOT emit a bare ref_/des_media_* id for it. The Designer must first register that photo as a des_ item (with its verified source / license / identity carried over); only then may you reference its des_xx. Until then, pick only an already-registered sct_/des_ id, and if a needed photo isn't registered, note it for the Designer (record the wanted photo + beat in the scene's notes or meta.mode_reason) rather than referencing an id the gate can't resolve.
• background.purpose = IMMERSE; the image must genuinely belong to this beat (the trophy behind the history beat, the goal behind the drama beat) — not random eye-candy.
• Not every beat needs a NEW photo. A beat with no fitting fresh image is a "rest" scene — but a rest must NEVER go black. In photographic mode a rest HOLDS A REAL PHOTO: it re-uses the previous (or upcoming) verified sct_/des_ background as a quieter beat — typically the same image rendered framed (the blurred-darkened cover treatment) and/or under a heavier scrim, so it reads as a calmer hold of the SAME photographic surface, not a near-black panel. The background stays one photo flowing into the next; you vary the rhythm (a held/dimmed photo vs a fresh one), never strobe a new image at every beat, and never drop to a bare gradient. Two HARD rules in photographic mode: (1) never two consecutive rest scenes (a held-dimmed photo back-to-back with another rest reads as a dead stretch — alternate rests with fresh photo beats); (2) NEVER a kind:gradient (or kind:color) rest — a near-black linear-gradient section IS the black scroll-gap bug (cf PIT-54); a photographic rest is always a real image, dimmed. Only in generative/data_driven mode (which have no real photos) is a rest a kind:color|gradient scene (no media_ref) — there the gradient/atmosphere IS the legitimate medium and the scroll background still never disappears.
• Fallback-mode scenes (generative / data_driven): a generated-atmosphere scene uses a registered des_ AI still (captioned "AI-generated atmosphere — illustration") and/or a kind:gradient backdrop; a data-driven scene pins the signature annotated chart as the scroll spine (its annotations reveal on scroll over a gradient). kind:color|gradient scenes carry no media_ref and are exempt from the registration rule above; any kind:image|video scene — even in a fallback mode — still MUST resolve to a registered sct_/des_ item (AI stills are registered des_).