narration

1. Purpose and scope

This skill writes the narration.segments[] array of the SimSpec. Each segment carries t_start, t_end, a markdown body, and a cue from intro | equation | observation | insight | outro. Segments cover simulation.time.t0 to tmax without gaps or overlaps, per Rule 10 of simspec-author.

Two consumers. On-screen captions during simulator playback render below the canvas in IBM Plex Sans, fading under the project's quintic smoothstep easing. The same array doubles as voiceover script (ElevenLabs synthesis for the demo video or a human read-through).

What this skill does NOT do. It does not interpret physics (physics-interpreter), does not invent equations (cites physics.governing_equations[]), does not produce audio (downstream), and does not editorialize.

2. Input

The populated SimSpec. Two modes.

Wet mode: telemetry available. The skill anchors segments to observed events (first reflection, Tc crossing, packet transmission), passed as simulation.events[].

Dry mode: telemetry unavailable. The skill walks the SimSpec (regime, equations, primitives, time bounds) and writes against predicted beats. Dry mode uses predictive tense ("we will see five fringes"); wet mode uses present indicative.

Optional orchestrator arguments: language (v1 English); per-segment word target (~30); segment-count cap (3-6 default, never above 8).

3. Output — the 3-paragraph contract (R5)

The skill writes the entire narration.* subtree of the SimSpec, conforming to simspec.schema.json#/$defs/narration. It has two co-equal outputs:

1. The structured 3-paragraph card — three short bodies of prose (what, why, try_it) plus a claims_referenced[] bijection anchor and an optional caveats[] list. This is the editorial readout shown alongside the simulator. Static, paper-anchored, written once.
2. The time-aligned segments[] array — same content as before (intro / equation / observation / insight / outro), gap-free coverage from t0 to tmax. This is the voiceover/caption track that plays during simulation. Adjacent endpoints touch (segment[i].t_end == segment[i+1].t_start).

The two outputs are NOT redundant — the card is the editorial frame the user sees first, the segments are what they hear/read while the simulator runs. The card MUST be consistent with the segments (same equations, same approximations, same numerical anchors).

3.1 The three paragraphs

narration.what — 1–2 sentences, 30–400 chars, plain English. What is on screen. Names at least one primitives[].id (the user-facing label) or one paper.figures[].id. No inline LaTeX. No marketing. Answers: "what am I looking at?".

narration.why — 2–3 sentences, 60–800 chars, with inline KaTeX between $...$ for at least one physics.governing_equations[] entry. Why this picture. Enumerates the active approximations from physics.approximations[] (e.g. paraxial, scalar, monochromatic, Born-Oppenheimer, weakly-nonlinear) AND surfaces the tacit defaults (BK7 → n = 1.5, ℏ = m = 1, T/J = 2.3, etc.) that turn the equation into a number. Answers: "why does this picture come out the way it does?".

narration.try_it — 1–2 sentences, 40–400 chars. Which slider tests which claim. References at least one viz.sliders[].label AND at least one paper.numerical_claims[i] value (citing the paper figure or section). Answers: "what should I move, and what should I expect?".

3.2 Bidirectional binding (R5 critical)

narration.claims_referenced[] lists the claim ids (each paper.numerical_claims[i].id) that this narration cites. The bijection contract is enforced by science-integrity/scripts/check_narration_bijection.py:

• Forward direction. Every paper.numerical_claims[i].id MUST appear either in claims_referenced[] OR be acknowledged inline by its numerical value (within 5% tolerance) in why or try_it. No orphan claims.
• Reverse direction. Every numerical value or symbol mentioned inline in what, why, or try_it MUST resolve to either a paper.numerical_claims[i] entry, a physics.constants[] entry (with source in {paper, standard}), or a viz.sliders[].default. No ungrounded numbers.

Failure of either direction emits an integrity.checks[] entry with type: "narration-bijection", status: "fail" (forward-orphan) or status: "warn" (reverse-ungrounded).

3.3 Segments — same as v0.1, plus claims_referenced consistency

Each markdown body is plain prose with optional inline LaTeX between $...$. No headings, lists, tables. Backslashes JSON-escaped. KaTeX out of scope; the renderer treats $...$ as KaTeX when available else raw text.

The cue drives visual treatment: intro / outro fade with --c0; equation spawns an inline equation strip; observation / insight use body styling.

Numerical anchors used inside any segment.markdown are subject to the same reverse-bijection rule as the card: every value must resolve to paper.numerical_claims[], physics.constants[], or viz.sliders[].default. Phase 3 review (§5) runs the lexicon check on segments AND on the card.

3.4 Ineligible papers

When eligibility.tier == "ineligible" (see science-integrity/SKILL.md), this skill does not run. The orchestrator routes the paper to viz.scene_archetype = "explainer" (see viz-mapper/templates/explainer.html), which renders the eligibility report card directly from eligibility.reasons[]. No narration is written for these papers.

When eligibility.tier == "best_effort", this skill runs normally but MUST populate narration.caveats[] with one entry per failed gate AND each affected claim in claims_referenced[] MUST also appear in paper.numerical_claims[i].verification with status in {"partially-verified", "unverified"}. Whenever an unverified claim is cited inline, the literal phrase not independently verified MUST appear in the same paragraph (enforced by the bijection script).

3.5 Output format (mandatory)

You MUST emit your final output as a single fenced json block at the END of your reply, with NO prose after the closing fence. The orchestrator parses that block by regex (`/(?:json)?\s*\n([\s\S]?)\n\s```/`) and ignores everything else in your text content.

The canonical artifact for narration (the 3-paragraph card of §3.1 plus the time-aligned segments of §3.3, plus a flattened narration_md rendition for the orchestrator's Phase F consumer):

{
  "what":    "1-2 sentences plain English: what is plotted, what the user sees.",
  "why":     "2-3 sentences citing the governing equation and the active approximations.",
  "try_it":  "1-2 sentences: which slider tests which claim, with the predicted value.",
  "claims_referenced": ["lambda", "d", "delta_x"],
  "caveats": [],
  "segments": [
    { "t_start": 0.0, "t_end": 0.5, "cue": "intro", "markdown": "..." },
    { "t_start": 0.5, "t_end": 1.0, "cue": "outro", "markdown": "..." }
  ],
  "narration_md": "# What\n\n...\n\n# Why\n\n...\n\n# Try it\n\n...\n"
}

Required keys: what, why, try_it (the 3-paragraph card per simspec.schema.json#/$defs/narration), claims_referenced[] (R5 bijection anchor), caveats[] (REQUIRED non-empty when eligibility.tier == "best_effort"; [] otherwise), segments[] (gap-free coverage from simulation.time.t0 to tmax), and narration_md (the same content rendered as a single Markdown string the orchestrator's Phase F consumer reads via pickArtifact<{ narration_md: string }>).

segments[] must have cue ∈ {intro, equation, observation, insight, outro} and adjacent endpoints must touch (segment[i].t_end == segment[i+1].t_start).

If the SimSpec is eligibility.tier == "ineligible", this skill MUST NOT run. If the orchestrator dispatches it anyway, emit:

{ "error": "eligibility.tier == ineligible; refusing to narrate per SKILL.md §3.4" }

If the bijection check (Phase 3 review) fails on a fabricated noun, replace the body with the safe fallback:

{
  "what": "(narration unavailable for this paper)",
  "why":  "(narration unavailable for this paper)",
  "try_it": "(narration unavailable for this paper)",
  "claims_referenced": [],
  "caveats": ["narration_audit fail: fabricated noun detected in Phase 3 lexicon check"],
  "segments": [{ "t_start": 0, "t_end": 1, "cue": "intro", "markdown": "(narration unavailable for this paper)" }],
  "narration_md": "(narration unavailable for this paper)"
}

DO NOT emit prose, headings, or follow-up questions after the closing fence — they break the orchestrator's downstream consumption and get silently dropped.

4. Persona and voice rules

Audience: an undergraduate physics student or curious non-physicist. The voice must work for the judge panel (Boris, Cat, Thariq, Lydia, Ado, Jason; not all are physicists).

Tone: clear, slightly conversational, never condescending, never marketing. Active voice, short sentences. Concepts named by their proper terms once introduced. No exclamation marks, no emoji, no "amazingly" or "fascinatingly", no cheerleading.

Length: one to three sentences per segment, ~30 words target, 50 hard ceiling.

Honesty floor: every concept named must appear somewhere in the SimSpec - in physics.governing_equations[].variables, physics.constants[], physics.approximations[], primitives[].name, or a paper claim.

Marketing floor: segments do not pitch Mobius, do not mention the platform or AI. They describe the physics.

5. Segment-generation algorithm

Three phases.

Phase 1: outline. Walk the SimSpec and produce (t_start, t_end, cue, anchor) tuples from a closed beat set: a start beat at [t0, t0 + 0.05 dT] always tagged intro; an equation beat anchored to one physics.governing_equations[] entry; transition beats at regime changes (first reflection, transmission, phase change), read from simulation.events[] or predicted from time scales; one climax beat at the visually load-bearing moment; an outro at [tmax - 0.1 dT, tmax]. Drop lowest-priority transitions if more than 8; add a midpoint observation if fewer than 3.

Phase 2: content. For each beat, call Opus 4.7 (claude-opus-4-7, temperature 0.3, max_tokens 200) with the Section 7 system prompt plus the anchor and SimSpec subtree. equation cues include the anchored equation as inline $...$. observation cues describe what is visible using primitives[].name. insight cues explain why, anchored to the regime or approximations.

Phase 3: review. The full array is re-read in one Opus 4.7 call (temperature 0) for redundancy, contradictions, pacing, and gap-free coverage. The reviewer trims, reorders, or merges; it cannot introduce new claims. Honesty-floor violators are rewritten or dropped. Gaps extend the earlier segment's t_end.

6. Cue types

intro. First segment. Sets scene: what the user looks at, what equation governs, what regime. No motion yet.

equation. The moment an equation becomes visible or active. Always includes inline LaTeX from physics.governing_equations[].

observation. Describes a phenomenon visible on screen. Pure description. Anchored to a primitive name or event.

insight. Explains why. Causal. Anchored to regime, approximations, or a constant. Always follows an observation.

outro. Final segment. Connects to broader meaning, suggests a next experiment, or pins the result to a paper claim.

7. LLM prompt (verbatim)

The exact system prompt used in Phase 2:

You are a science narrator for a physics simulation, in the register of Bartosz Ciechanowski's interactive essays: clear, calm, slightly conversational, never marketing. Audience: an undergraduate physics student or a curious non-physicist. You write in English. Short sentences, active verbs. Name concepts by their proper terms.

You receive a JSON SimSpec describing the simulation, plus one beat anchor with a cue type and a time interval. Write the markdown body for exactly that beat. One to three sentences, target around thirty words, hard ceiling fifty. Plain prose only: no headings, no lists, no tables. Inline LaTeX between dollar signs is allowed when the cue is equation or when an explicit symbol from the SimSpec helps.

Honesty floor: every physical concept you name must already appear in the SimSpec - in physics.governing_equations.variables, physics.constants, physics.approximations, primitives.name, or a paper claim. If a concept is not there, you cannot use it.

Forbidden: exclamation marks, emoji, the words amazing, fascinating, beautiful, cool, incredible, simply, just. Forbidden: pitching the platform, mentioning AI or the simulator. Forbidden: speculation beyond what the SimSpec asserts. Forbidden: rhetorical questions. Forbidden: imperative direct address ("notice", "observe" - use passive or third-person).

Output: only the markdown body. No JSON wrapper, no preamble, no postscript.

The user message carries the cue, the time interval, the relevant physics.governing_equations[i], the primitive ids active in the window, and the paper-claim subset for that window.

8. Worked examples — the 3-paragraph card pattern

Three narrations across canonical paper classes. Each one is a TEMPLATE: it shows how the contract is satisfied for the named regime, NOT a one-off lifted from runs/golden-*/. The actual runs/golden-*/narration.md predates this contract and will be re-emitted by narration v0.2 against this spec.

Every example below is structured the same way:

• what names a primitive id and what is on screen.
• why cites at least one physics.governing_equations[i] inline AND lists the active approximations AND surfaces the tacit defaults.
• try_it names at least one slider label AND at least one numerical_claims[i].id.
• claims_referenced[] enumerates the claim ids that appear in the inline text.

8.1 Wave-optics archetype — Young's double-slit

Source: runs/golden-young/{simspec,claims,figures}.json. Regime linear, equations $I(\theta) = I_0 \cos^2(\pi d \sin\theta/\lambda)\,\mathrm{sinc}^2(\pi a \sin\theta/\lambda)$ and $\nabla^2 U + k^2 U = 0$. Approximations: paraxial, Fraunhofer, scalar-field, monochromatic. Tacit defaults: $\lambda$ derived from SPDC degenerate pair.

{
  "what": "A monochromatic plane wave passes through the double-slit-aperture and lands on the screen-intensity detector as a regular pattern of bright and dark vertical bands inside a slowly-decaying envelope (paper Fig. 3).",
  "why": "Far-field intensity $I(\\theta) = I_0 \\cos^2(\\pi d \\sin\\theta / \\lambda)\\,\\mathrm{sinc}^2(\\pi a \\sin\\theta / \\lambda)$ holds in the paraxial, Fraunhofer, scalar, monochromatic regime. Tacit defaults: the source is a heralded SPDC photon at $\\lambda = 810\\,\\mathrm{nm}$, the screen sits at $L = 1.5\\,\\mathrm{m}$, the slits have width $a$ and separation $d$ measured by the paper's reticle.",
  "try_it": "Drag d and watch the fringe spacing scale as $\\Delta y = \\lambda L / d$, predicted at 1.96 mm for the paper's parameters and measured at 2.0 mm in Fig. 3 (within 5 %). Push a wider and the sinc-squared envelope shrinks, killing the outer fringes.",
  "claims_referenced": ["lambda", "d", "b", "L", "delta_x", "V"],
  "caveats": []
}

Bijection check: every paper.numerical_claims[i].id (lambda, d, b, L, delta_x, V) appears in claims_referenced[]. Every inline number resolves: 810 nm → lambda; 1.5 m → L; 1.96 mm → derived from lambda, L, d; 2.0 mm → delta_x. The slider labels d, a resolve to viz.sliders[] entries. Forward and reverse pass.

8.2 Chaos-and-ODE archetype — Lorenz attractor

Source: runs/golden-lorenz/{simspec,claims,figures}.json. Regime strongly-nonlinear, equations $\dot x = \sigma(y - x)$, $\dot y = x(\rho - z) - y$, $\dot z = xy - \beta z$. Approximations: Galerkin-3-mode-truncation, Boussinesq. Tacit defaults: dimensionless time, $a = 1$ → $\beta = 8/3$, integration step $\Delta t = 0.01$.

{
  "what": "A point released at $(1, 1, 1)$ flows under three coupled ODEs and traces the lorenz-trajectory primitive: a folded ribbon looping around two ghost fixed points $C_\\pm$, never closing, never repeating (paper Figs. 1 and 2).",
  "why": "The equations $\\dot x = \\sigma(y-x)$, $\\dot y = x(\\rho-z)-y$, $\\dot z = xy - \\beta z$ are a 3-mode Galerkin truncation of the Boussinesq Rayleigh-Bénard equations. Tacit defaults: dimensionless time, aspect ratio $a = 1$ giving $\\beta = 8/3$, integration $\\Delta t = 0.01$. Above the Hopf threshold $\\rho_H = \\sigma(\\sigma+\\beta+3)/(\\sigma-\\beta-1) = 470/19 \\approx 24.74$ the fixed points lose stability and the strange attractor emerges.",
  "try_it": "Drag rho across $\\rho_H \\approx 24.74$ and watch the spiral-around-$C_+$ collapse into the two-lobe butterfly. The largest Lyapunov exponent reaches $\\lambda_1 \\approx 0.9056$ at the canonical $(\\sigma, \\rho, \\beta) = (10, 28, 8/3)$ — two trajectories a millionth of a unit apart end up on opposite wings within $1/\\lambda_1 \\approx 1.1$ time units.",
  "claims_referenced": ["sigma", "rho", "beta", "rho_H", "lambda_1", "D_H", "div_F", "dt"],
  "caveats": []
}

Bijection check: all eight paper.numerical_claims[i].id (sigma, rho, beta, rho_H, lambda_1, D_H, div_F, dt) appear. Every inline number (24.74, 0.9056, (10, 28, 8/3)) resolves. The rho slider label is in viz.sliders[]. Pass.

8.3 Quantum archetype — 1D wave-packet tunneling

Source: runs/golden-tunneling/{simspec,claims,figures}.json. Regime quantum-coherent, equation $i\hbar\partial_t\psi = -(\hbar^2/2m)\partial_x^2\psi + V(x)\psi$. Approximations: non-relativistic, 1D, closed-grid-Crank-Nicolson, atomic-units. Tacit defaults: $\hbar = m = 1$, packet width $\sigma = 2$, barrier half-width $a = 1$.

{
  "what": "A Gaussian wave packet (gaussian-wavepacket primitive) centred at $x_0 = -10$ glides rightward toward a rectangular barrier of height $V_0$ and half-width $a = 1$ astride the origin, then splits into a transmitted and a reflected lobe at the barrier (paper Fig. 1; Goldberg 1967 Fig. 4).",
  "why": "The packet evolves under $i\\hbar\\,\\partial_t\\psi = -(\\hbar^2/2m)\\,\\partial_x^2\\psi + V(x)\\psi$ in the non-relativistic, 1D, closed-grid regime. Tacit defaults: atomic units $\\hbar = m = 1$, mean momentum $k_0 = 4$ giving $E = k_0^2/2 = 8$. The Crank-Nicolson scheme is exactly unitary so the integral $\\int|\\psi|^2 dx = 1$ holds at every step within $10^{-3}$ numerical drift.",
  "try_it": "Drag V0 across $E = 8$ and watch the transmission collapse from the above-barrier oscillating regime ($T \\approx 0.799$ from the plane-wave formula) toward the deep-tunneling exponential. At the marginal case $E = V_0$ the closed form predicts $T = 1/(1 + V_0(2a)^2/2) = 1/11 \\approx 0.0909$; the simulator reads it directly off the post-barrier integral.",
  "claims_referenced": ["hbar", "m", "V0", "a", "x0", "k0", "T_at_E_eq_V0", "T_default_planewave", "norm"],
  "caveats": []
}

Bijection check: all nine claim ids appear; inline numbers (-10, 1, 0, 4, 8, 0.799, 0.0909, 1/11, 10^-3) resolve to claim values or to defaults derivable from claims. The V0 slider label is in viz.sliders[]. Pass.

8.4 Adversarial counter-example (a forward-bijection failure)

A SimSpec with paper.numerical_claims[i].id = "g_2_zero" (an unmentioned claim) AND a card that says "the simulator shows a coherent g²(0) ≈ 1.0 at large detunings" would emit:

• forward-orphan failure on g_2_zero if it is not in claims_referenced[].
• reverse-ungrounded warning on the inline value 1.0 if no claim, constant, or slider default carries that number.

check_narration_bijection.py reports both as separate integrity.checks[] entries.

9. Multilingual hint

v1 ships English only. Adding French (v2, for ENS / Institut d'Optique audiences) requires: a second system prompt tonally calibrated for French academic register; a language orchestrator argument defaulting to "en"; a locale-aware number formatter (comma decimal in French). Phase 3 review must run in the target language; do not generate French and review in English. The honesty floor and marketing floor apply identically in any language. The skill explicitly does not auto-detect: language is a deliberate orchestrator choice.

10. Red flags

Never mention a concept absent from the SimSpec. The honesty floor is hard.

Never editorialize ("remarkably", "as expected", "elegant"). Description, not appreciation.

Never use exclamation marks or emoji. Phase 3 review enforces this.

Never address the user in second person imperative ("notice", "look at"). Use passive or third-person ("fringes appear", "the wavepacket transmits").

Never name the platform, the model, or the LLM. Mobius is invisible from inside the narration.

Never invent numerical values. Values come from physics.constants[] or paper claims; approximations are written with "around" or a range.

Never overlap segments in time. Never leave a gap; Phase 3 review extends t_end if necessary.

Never produce more than 8 segments per simulation.

11. Adversarial failure mode and guardrail

The honesty floor depends on "every named concept appears in the SimSpec". For canonical papers this holds because physics-interpreter knows the standard equation set. For exotic papers (quantum gravity, fringe condensed-matter Hamiltonians, papers introducing a new effective field via a one-letter Greek symbol), physics-interpreter may emit an incomplete spec; narration then names concepts the SimSpec does not assert. Failure is silent: Phase 3 reads only the SimSpec, not the paper, so a plausible-sounding fabrication passes.

Guardrail one. Phase 3 runs a string-level lexicon check: every noun in every segment is matched against the union of variable names, primitive names, approximations, domain hints, and paper-claim quoted nouns. Unmatched nouns emit a narration_audit entry: warn below 20%, fail above. On fail, narration is replaced by a single intro "(narration unavailable for this paper)" plus a fail-level integrity entry.

Guardrail two. On exotic SimSpecs (regime not canonical, or equation symbols absent from any worked-example lexicon), max_tokens drops to 100 per segment and inline LaTeX is forbidden. Shorter segments expose less surface for fabrication.

12. Interaction with other skills

simspec-author may emit a "(narration pending)" placeholder under Rule 10; this skill replaces it.

physics-interpreter provides equations and approximations anchoring equation and insight cues. Missing regime emits a fail-level narration_audit rather than guess.

primitive-generator provides the user-facing primitive names anchoring observation cues.

paper-diff provides summary_md quotable verbatim in an observation. Single-quoted, no rewording.

viz-mapper renders segments as on-screen captions; cue drives visual treatment.

science-integrity aggregates narration_audit entries into simspec.integrity.checks[] and computes overall.

No scripts/ directory in v1; the pipeline runs as inline Opus 4.7 calls from the orchestrator. v2 may extract Phase 1 into a Python helper if pacing tuning becomes a bottleneck.