Hero

Hero

Premium-profile stage. The orchestrator runs the Hero only in the premium profile; in fast the Designer's static cover image is used instead. The "animated cover is the default, every run has one" rules below apply within premium.

Your job is the cover — the first thing the reader sees, before the headline, before any prose. The cover is the most load-bearing detail of the whole page: it is the hook. A crafted animated cover is the DEFAULT — you walk a deterministic source ladder and the cover ends up a short muted <video> loop on every rung but the last; a static <img> cover is only the recorded final fallback when every animation rung degraded.

You own the hero video + its static furniture (headline band, kicker, credit, decorative monogram/chips/particles/scrim). You do NOT own the pick-a-side interactive overlay — that is the Interaction Engineer's int_01. You do NOT redo the scroll background — the Cinematographer stages your cover as the first cinematic scene (cin_00). You realize the Designer's content.hero_strategy as a rendered, verifiable cover.

Setup

• PROJECT_DIR = first argument; SKILL_DIR = the directory containing this SKILL.md (.../skills/data2story-pro/hero).
• Read: editor.json (interactives.hero — does the centerpiece front-load on the teaser?), scout.json (verified sct_ stills / clips), designer.json (content.hero_strategy + any registered des_ stills), interaction.json (the int_01 the centerpiece resolved to), and the shared ../references/topic_profile.json (is_visual / tags — same classifier the Detective resolved).
• Reuse the Designer's media scripts: image2video (SKILL_DIR/../designer/scripts/openrouter-image2video/scripts/generate_video_from_image.py), text2image (.../openrouter-text2image/...), and optimize_assets.py (SKILL_DIR/../designer/scripts/optimize_assets.py). Generation routes through OpenRouter (OPENROUTER_API_KEY must be set).
• Read references/hero_recipes.json (the source ladder + the winning-pattern build recipe + the IP record) and references/schema.json (the hero.json shape) before rendering.
• Output: PROJECT_DIR/hero.json + assets → PROJECT_DIR/assets/teaser.webm + teaser_web.mp4 + teaser.jpg (poster). The hero IS the teaser section.

When to run

Always — every run has exactly one cover. There is no "skip the hero" path: the floor of the ladder (an abstract generated still, animated) is always available, so even a sober computational topic with no star entity gets a moving cover. The only thing the ladder decides is which source feeds the cover, never whether there is one. (A genuinely abstract topic still gets a cover; it is just an atmospheric/abstract one, often the interactive rung.)

Step 1 — Resolve the source (the deterministic ladder)

Walk the rungs in references/hero_recipes.json source_ladder and take the first that resolves — this is deterministic, not a free pick. Record the chosen rung in meta.source_ladder_rung + a one-line meta.why:

0. Interactive-hero passthrough — if editor.json.interactives.hero is non-null AND its section == "teaser", the centerpiece interaction is the Interaction Engineer's int_01. Render the animated backdrop behind it (descend rungs 1-4 for the still/motion) and yield the click surface: set hero.interactive_overlay_ref = "int_01". You own the video + static furniture; the Interaction Engineer owns the pick-a-side overlay.
1. Scout real still (no public figure) → image2video the still into a cinemagraph; default Veo is fine for non-faces.
2. Recognizable real PUBLIC FIGURE, WITH a fetched identity-verified photo → image2video --model kwaivgi/kling-v3.0-std (the one faces-safe model — Veo/Wan deterministically refuse real faces, code 15236754). This is allowed-with-conditions, not banned: the face is held enough to avoid warping, but subtle natural motion IS permitted (slight head/body sway, a blink) on top of the moving atmosphere/lighting. Warp-quality guard: reject any candidate where the face distorts → fall back to ffmpeg Ken-Burns + boomerang on the same still (faces stay original pixels). Set subject_is_real_public_figure:true + a proportionate AI-motion-added disclosure (a small caption that the motion was added / it is not real footage — lightweight, not a banner). The thing that stays disallowed is generating the face from scratch (photoreal OR illustration) — the still here is always FETCHED.
3. License-clean STOCK clip → a Scout sct_ kind:"video". R5 constraint: stock video isn't fetched today (fetch_stock.py is images-only), so restrict this rung to a Commons/Openverse CC clip or a verified oEmbed — not a paid stock-video API. A copyrighted self-hosted clip is a des_ publish_blocker (see the IP record).
4. Abstract/atmospheric still → text2image a no-real-referent still (mood/texture/metaphor), then image2video it. The always-available floor that keeps even a sober cover moving.
5. Static fallback (only) → ship the poster as a static <img>: kind:"image", assets.video_webm/_mp4 = null, with a recorded media_blocker. The ONLY sanctioned static-cover path — reachable only when every animation rung degraded (image2video printed FALLBACK_USED=static_poster / VIDEO_UNUSED=1, or no clip/still could be produced).

The real-subject guard from the Designer doctrine still holds: a recognizable real subject is a FETCHED verified still (Scout sct_ / Detective ref_), never a generated one; image2video of a real face is only ever a held cinemagraph (subtle motion within the warp guard) via the faces-safe model with proportionate disclosure. The model facts (which models refuse real faces, the 4/6/8 duration constraint, the upscale recipe) live in references/hero_recipes.json ip_record (and the Designer's video_pipeline.json).

Honor topic_profile.ai_face_policy (real-person subjects). When the Detective resolved an ai_face_policy (the topic involves real people — see ../detective/SKILL.md and ../references/topic_profile.json), it governs the cover. The default is animate the real photo: a real-person subject WITH a fetched, identity-verified photo → rung 2 (the subtle cinemagraph + warp guard + proportionate disclosure above). AI face is allowed-with-conditions, never blanket-banned here. When the real-person subject has NO usable verified photo (no_photo_fallback:"theme_first_no_person"), do NOT generate the person — neither a photoreal fake nor an illustration of the person — and skip rung 2; instead take a THEME-FIRST non-person cover, in this order, stopping at the first that expresses the theme: (a) real scene/object media — license-clean real imagery of the setting/objects/symbols (NOT the person), animated per rung 1/3; (b) data-as-cover — the story's signature visualization animated (the data IS the theme); (c) conceptual / typographic cover; (d) abstract atmospheric (generative, non-figurative) via rung 4 — last resort only. Theme-first means: if real scene/object media or the data can carry the theme, do not drop to the abstract floor. Sensitivity is NOT a hard gate — animate regardless of context and optimize for quality; if ai_face_policy.sensitivity_advisory is set (deceased persons, minors, criminal allegations), carry it through as a one-line note for the Critic — it never blocks the build.

Step 2 — Render + optimize

• Animate with a motion-only prompt (describe only what moves: flags ripple, smoke drifts, floodlights flicker; subject and faces held still, no camera shake). The cover must read as ALIVE at a glance — never near-still. Require a clearly-visible PRIMARY motion + 1-2 strong SECONDARY motions. GOOD: the canonical hero_v5 — a player standoff with national flags waving boldly behind (subjects held, atmosphere unmistakably moving). BAD: the dusk sky and thin clouds drift slowly, a faint pulse over an otherwise-static stadium (a subtle cinemagraph that reads as a still — the weak current output, a richness fail). When the subject itself must stay still (building / landscape / held face), require a bold animated foreground: rippling/waving flags, a surging crowd, rising smoke/steam/embers, a sweeping floodlight, strong sky parallax. Motion is IN-PLACE / cyclic (wheels spinning, flags waving, smoke rising, crowd surging, sky drifting) — never translate the subject across/off the frame (a train driving off-screen / a rocket flying out of frame cannot loop seamlessly). Pick the concrete motion concept from references/hero_recipes.json topic_motion_library (topic-adaptive; free choice within the guides). Keep the source still as the <video poster> so the cover degrades to frame-0. Duration is one of 4 | 6 | 8 (the OpenRouter video endpoint accepts no other).
• Seamless loop (hard): post-process every hero clip into a clean loop so head meets tail invisibly — a raw model clip almost always jumps. Default = ffmpeg boomerang/ping-pong (forward then reversed: [0]reverse[r];[0][r]concat, inherently seamless); alt = crossfade the loop point (xfade, blend last ~0.5s into first ~0.5s) when reverse looks unnatural. ffmpeg is not on PATH — resolve it via the imageio-ffmpeg wheel (python3 -c "import imageio_ffmpeg,sys;sys.stdout.write(imageio_ffmpeg.get_ffmpeg_exe())"), exactly as optimize_assets.py does. Record the technique in hero.json as loop ("boomerang" | "xfade" | "native"); the on-page <video> keeps the loop attribute. (The ffmpeg Ken-Burns fallback is already a boomerang.)
• After the render, always run python3 SKILL_DIR/../designer/scripts/optimize_assets.py PROJECT_DIR/assets/ — it writes the VP9 .webm + H.264 _web.mp4 + poster and repoints filenames. Web-weight cover budget: < 3 MB. (A heavier 2K upscaled hero is tolerated only when the page can clearly afford it — see hero_recipes.json / the Designer's ai_upscale; the default ships the optimized _web copies.) Reference the _web copies in hero.assets.
• Verify the files exist (ls -la PROJECT_DIR/assets/teaser.*). If image2video printed FALLBACK_USED=..., transcribe it into hero.source.fallback_used; static_poster means the cover degraded to a still → set kind:"image" and the rung-5 fields + a media_blocker.