retiam 2.0.1 → 2.0.3

package/agent/skill/references/explainers.md

@@ -0,0 +1,123 @@
+# Explainer production with Retiam
+
+Use this for educational animations. Ordinary title animations and other short
+edits do not need a lesson plan. An AI coding harness authors the subject model,
+script and TypeScript scenes; the CLI supplies deterministic production tools.
+No particular AI provider or additional agent service is required.
+
+## Start from the learner's question
+
+Read `lesson/lesson.json` and the existing source. Establish the topic, audience,
+prerequisites, learning objective, duration constraints and requested style from
+the prompt. Infer routine choices; ask only about consequential missing context.
+The supplied area lesson is a working API reference, not the requested subject.
+Replace its model and beats when the user asks for another topic.
+
+Research claims that need verification. Record source IDs, titles, links or
+notes in `sources`, and connect factual claims to those IDs. Explicitly mark an
+illustrative model. A numeric simulation may be correct for its assumptions yet
+misrepresent the real system; explain assumptions and avoid false causality.
+
+Plan a visible construction and the narration together. Useful beats include a
+question, a prediction, a counterexample, a mechanism, a generalization, an
+application and a resolved takeaway. Choose the sequence for the subject rather
+than forcing every topic into the same chapter count. Each beat records `goal`,
+`visibleChange` and `focus`. Text such as “explain the process” is not a visible
+change; “a molecule passes through the membrane while concentration decreases” is.
+
+## Select the visual mechanism
+
+- Algorithms: derive graph, table, queue and code updates from one execution trace.
+  Check a result against an independent reference. Use native `Code` and
+  `retiam/graphs`; introduce auxiliary representations only when they help.
+- Mathematics: vary a parameter, deform geometry, decompose areas, or connect a
+  construction to `Tex`. Transfer identity and color into the notation.
+- Physics: use `retiam/physics` when rigid-body dynamics explain the phenomenon;
+  mathematical fields or a deterministic analytic model may be more appropriate.
+- Biology and other processes: author an accurate conceptual model and use
+  local interactions, flows and scale changes. Use vectors, shapes or labeled
+  assets; a process illustration need not pretend to be a physical simulation.
+- History, economics and data: anchor timelines, maps, comparisons and charts to
+  sources. Reveal changes and relationships without animating an unsupported
+  causal claim.
+
+Use the matching native sublibrary for supported features. Do not import every
+library just to exercise the engine. Novel subjects still need original scenes.
+
+## Write for a curious teacher
+
+Keep formal definitions and conditions exact. Around them, invite the learner to
+predict, give space to think, and explain why an observed event matters. Vary the
+rhythm: not every sentence needs a question. Avoid forced jokes and filler.
+
+For example: “A currently says four. What if we go through B?” Then a real pause
+while the route lights up. “Two, plus one… three. That's better. Let's remember it.”
+Do not expose the candidate or subtitle answer during that prediction pause.
+
+Keep performance notes out of spoken text. A narration segment has an `id`,
+`text`, and optional `pauseAfterMs`. Segments need not correspond one-to-one to
+visual actions. Split at purposeful thinking pauses, retaining coherent speech
+between them. Edge remains the default. When ElevenLabs is selected, use its
+native provider and the initialization/performance guidance in [tts.md](tts.md).
+Keep caption/cue `text` clean; put delivery markup in a segment's `speechText`.
+Other generators may normalize recordings into `PreparedSpeech`.
+Include narration in an explainer unless the user requests a silent treatment.
+The sample's disabled narration is an offline-preview convenience, not a reason
+to omit the requested video's spoken explanation.
+
+## Public workflow
+
+The core authoring types and runtime are exported by `retiam/explainer`. Pure
+validation, compilation and style resolution also import in Node through
+`retiam/explainer/plan`. Find declarations with `retiam context --json`.
+
+1. Edit the lesson and write a subject model under `src/`. Persist the requested
+   profile in `style`. `retiam lesson style excalidraw` selects the whiteboard look;
+   custom style objects extend a preset. Read [styles.md](styles.md) for the look.
+2. Run `npm run lesson:check`. It checks schema/source references and any prepared
+   audio. Its `requiredReview` remains a separate obligation, not a quality score.
+3. For narration set `narration.enabled` to true, then run
+   `npm run lesson:prepare`. First-time native synthesis needs network access;
+   subsequent calls use the native cache. It writes `lesson/prepared.json` and
+   public audio files. Keep them for reproducible export. Silent preview timings
+   are explicitly marked `estimated` and are not locked speech timings.
+4. Import the lesson and optional prepared manifest into the scene. Use
+   `prepareLesson(this, plan, {prepared})`, then `await lesson.run(handlers)`.
+   All handlers are built before playback. Put mutations in animations or `b.at()`;
+   do not mutate shared objects directly while constructing later beat handlers.
+5. Bind timing to `b.cue('name')` and `b.durationMs`. A cue identifies a segment
+   and optionally a spoken phrase; repeated phrases require `occurrence`.
+   Missing, ambiguous or stale cues fail visibly instead of drifting silently.
+   Check timing with `npm run lesson:timeline`.
+6. Type-check and lint, then capture setup, prediction, reveal, transition and
+   conclusion frames. `lesson check --json` lists useful sample times. Open the
+   PNGs and watch representative short clips for pacing. Fix observed issues.
+7. Render with the normal Retiam renderer and export captions with
+   `npm run lesson:captions`. Inspect final video/audio streams, listen to speech,
+   check synchronization and pauses, and update `lesson/review.json` with concrete
+   evidence. Report any unavailable checks honestly.
+
+The runtime preloads audio, compiles one frame-aligned clock, and schedules all
+clips and visual beat groups on that clock. Native speech and imported assets
+share `durationMs`, word timestamps and a URL in `PreparedSpeech`. Caption cues
+are grouped within speech segments so they cannot bridge a thinking pause.
+
+## Small executable reference
+
+Copy `../examples/AreaLesson.ts` from the skill directory into `src/scenes/` to
+run it. `npx create-retiam my-video --template explainer` opens this construction
+with the lesson JSON editable outside the scene. The sample is silent by default
+so a fresh preview works offline; enable native narration when needed.
+
+`styleGeometry`, `drawGeometry`, `transferValue` and `emphasize` supply reusable
+motion behaviors. Use public Retiam entities for the rest of the construction.
+A style profile does not automatically make a static scene explanatory.
+
+## Review evidence
+
+In `lesson/review.json`, keep automatic command results separate from observed
+facts. Record a frame/clip path, the beat reviewed, what was observed and whether
+it was fixed. Inspect overlaps, readable label sizes, stable identity, meaningful
+motion, prediction/reveal order, and a conclusion with time to read. Check claims
+against sources and domain calculations against independent results. A passing
+plan check cannot establish factual or pedagogical correctness.

package/agent/skill/references/quality.md

@@ -0,0 +1,151 @@
+# 3Blue1Brown-inspired visual explanations
+
+The default direction is a 3Blue1Brown-inspired mathematical explainer, built
+with Retiam. Teach through visual intuition and evolving constructions. Match
+the user's subject, audience, duration, and aspect ratio; an explicitly different
+style or palette overrides this default.
+
+## Default visual and narrative direction
+
+- **Start with a question worth seeing answered.** Give the viewer a concrete
+  example to predict or inspect. Build intuition before naming the general rule.
+- **Make the mathematical objects the main actors.** Let a graph, geometry,
+  field, system, or construction occupy the stage. Develop it through the
+  explanation, with enough spatial continuity to follow what changed and why.
+- **Use a clean dark canvas.** Favor black or deep charcoal, crisp geometry,
+  white mathematical typography, and a few clear accents. Blue and warm yellow
+  are useful starting accents; assign colors by mathematical role and preserve
+  those roles between diagrams, symbols, and transitions. Keep grids subdued.
+- **Let notation grow from the construction.** Introduce a formula when the
+  diagram has established its meaning. Place corresponding terms and objects
+  in the same colors. Transform relevant terms deliberately, exposing the
+  reasoning instead of replacing complete screens of equations.
+- **Choreograph discoveries.** Use smooth drawing, motion, decomposition,
+  regrouping, comparison, and parameter sweeps. Focus the camera or emphasize
+  an object when a detail becomes important. Leave time for the viewer to make
+  an inference before stating it, then test or generalize the insight.
+- **Narrate as an explanation.** When using narration, generate it through
+  `retiam/tts`. Use conversational questions and precise language, synchronize
+  speech with visible events, and allow meaningful silent pauses. Keep requested
+  subtitles unobtrusive so they leave room for the mathematical construction.
+  Match vocal delivery to the beat's question, discovery, or resolution. For
+  expressive ElevenLabs delivery follow [tts.md](tts.md): choose model-compatible
+  cues, listen to a representative sample, and preserve clean caption text.
+
+The goal is a clear, satisfying visual argument. Choose 2D or 3D according to
+the concept. Use a slide, dashboard, or another aesthetic when requested.
+
+## Plan events the viewer can see
+
+For each substantial beat, identify:
+
+| Decision | Useful answer |
+| --- | --- |
+| What must become clear? | A relationship, cause, comparison, or mechanism |
+| What visibly changes? | A path, configuration, parameter, grouping, or viewpoint |
+| What carries continuity? | The same point, node, symbol, shape, or color meaning |
+| Where should the eye go? | One object or relationship at a time |
+| What warrants a pause? | A meaningful comparison or resolved result |
+
+Write an action such as “the second point travels along the curve while the
+secant rotates and the gap collapses.” “Explain the derivative” or “show the next
+heading” does not specify a visual event. Derive the number and length of beats
+from the explanation; do not impose the same five scenes on every subject.
+
+Prefer an evolving construction: establish the objects, expose a contrast or
+problem, show the mechanism changing the state, then resolve and generalize.
+Preserve enough context that the viewer can understand each transformation.
+
+## Choreograph meaning
+
+- **Carry the idea in geometry.** Trace an actual route, move a point along its
+  function, deform the existing object, reveal how pieces assemble, or run the
+  simulation. Text describes a result after the viewer has seen its cause.
+- **Preserve identity.** Move or transform the same object between states. Keep
+  variable colors consistent between diagrams and formulas. Use matching-symbol
+  transforms for a meaningful equation change when appropriate.
+  When unrelated symbols should disappear, use `morphUnmatched: false` rather
+  than deforming every leftover glyph into a new one.
+- **Direct attention.** Establish context, emphasize the current relationship,
+  and widen the view for the result. Zoom or pan only when a close relationship,
+  changing frontier, or new scale benefits from it. A well-composed static shot
+  can support excellent motion; constant camera movement can obscure it.
+- **Use a few distinct motion functions.** Drawing reveals structure; travel
+  shows flow; a morph preserves correspondence; a brief pulse marks a state
+  change; a hold gives time to infer. Choose the functions the concept needs.
+- **Coordinate timing.** Related changes should happen together. Give an action
+  an appropriate acceleration, settle, and readable pause. Use `Concurrent`
+  with an explicit group duration so its defaults do not retime the children.
+  Use linear progress for uniform physical/data sweeps and eased motion for
+  entrances or changes that should settle; follow the actual simulated model.
+- **Keep labels local and short.** Anchor a cost near the affected node or a
+  quantity beside its geometric span. Prefer a few precise words to paragraphs.
+  Use `Tex` for formulas and meaningful term matching, not plain text equations.
+- **Let narration explain why.** Align each utterance with the event it explains.
+  If requested, use `retiam/tts` and its prepared audio duration. Repeatedly
+  replacing paragraphs beside an otherwise idle diagram is not enough motion.
+
+Choose colors for hierarchy and meaning, with enough contrast for the output.
+Keep guides quieter than active geometry and leave negative space. The default
+dark palette supports the construction; glow, 3D, and sound effects need an
+explanatory purpose.
+
+## Presentation patterns to revise
+
+For an animation brief, revise these patterns unless they serve a specific need:
+
+- A permanent title/header, large body panel, footer, chapter number, and page
+  counter framing every beat in the same layout.
+- A diagram occupying one corner while most of the frame is explanatory text.
+- An entire screen fading away, followed by a new heading and another fade-in.
+- A long voiceover over a static scene with only a progress bar or decorative glow.
+- Identical reveal timing for every beat, or unrelated objects appearing at once.
+- An algorithm shown mainly as table rows changing while its mechanism stays idle.
+
+For example, a Dijkstra explanation can begin with a question about competing
+routes in the graph. Let the viewer predict a winner, then show why counting
+roads can fail when their costs differ. Make the reason for finalizing the
+cheapest unsettled cost visible using the nonnegative-edge assumption.
+Trace the inspected edge, show the candidate cost beside the affected node, and
+visibly retain or reject that route. Move attention with the active frontier,
+keep cost and settled-state meanings consistent, then dim explored clutter and
+trace the winning path. Use a priority queue or table when explaining that
+structure, rather than reserving half the canvas for one throughout the video.
+Follow actual weighted relaxation order; decorative propagation must not imply
+an incorrect algorithm.
+
+## Working reference
+
+[SecantToTangent.ts](../examples/SecantToTangent.ts) is a silent visual reference:
+
+| Time | Visible event | Purpose |
+| --- | --- | --- |
+| 0–3.1 s | Draw the curve, mark two points, introduce the secant and its gap | Establish the construction |
+| 3.1–6.3 s | Move the second point along the curve; the line rotates and the gap shrinks | Show what determines the secant slope |
+| 6.3–11.1 s | Bring attention closer and continue the convergence | Make the limiting relationship visible |
+| 11.1–13.1 s | Resolve the tangent and transform the equation | Connect geometry to notation |
+| 13.1–19.5 s | Move the tangent point across both sides of the curve, updating the slope | Generalize beyond one frozen example |
+| 19.5–21.5 s | Hold the resolved construction | Allow the takeaway to register |
+
+The smaller `ExplainMotion.ts` and `NarratedMotion.ts` examples isolate API and
+speech mechanics. They are not visual templates for finished explainers.
+
+## Review the rendered evidence
+
+Capture the setup, the middle of the main mechanism, a transition, and the resolved
+state at the intended aspect ratio. Open the PNGs and watch playback.
+
+- Is the mathematical/data relationship correct throughout the motion?
+- Does the construction establish intuition before introducing the general rule?
+- Do corresponding geometric objects and mathematical terms keep their color meaning?
+- Is the focal object clear, with readable labels and no accidental overlap or clipping?
+- Does the main action demonstrate the idea without requiring every caption?
+- Can the viewer follow the same object through transitions and reframing?
+- Do motion and pauses feel purposeful when watched at normal speed?
+- Does the conclusion remain visible long enough to read?
+
+Compare the middle of adjacent beats. If only the heading or paragraph changes,
+redesign the visible action. A deliberate reading hold or final rest is useful;
+idle slides throughout an explanation need revision. Record concrete observed
+issues and fix them. Lint and type checks cannot judge aesthetic quality or
+explanatory correctness, and static screenshots cannot establish pacing.

package/agent/skill/references/styles.md

@@ -0,0 +1,58 @@
+# Visual style profiles
+
+Teaching goals and visual style are independent. Read the user's prompt first.
+An explicit requested style overrides `lesson/lesson.json`; save that choice so
+future revisions remain consistent. Keep the same mathematical/content model and
+narration cues when restyling. Preserve explicit brand, aspect and accessibility
+constraints. `retiam lesson styles --json` gives actual tokens for this version.
+
+## mathematical — default, matching the Dijkstra video
+
+Use navy `#0A1020`, light text, vivid blue and gold, with mint, coral, violet and
+teal available as stable object identities. Color carries meaning across the
+construction, labels, formulas and data transfers. Do not turn the palette into
+random per-frame decoration. Let lines trace real paths, values travel between
+representations, replacements settle smoothly and discarded candidates fade.
+Ask a question, allow a thinking pause, then reveal its answer through geometry.
+Use native `Tex` and syntax-highlighted `Code` where they explain the subject.
+Introduce tables and queues as teaching objects only when relevant. Maintain
+spatial continuity through derivations and applications; conclude with the idea
+that the evolving construction has established.
+
+## excalidraw — hand-drawn whiteboard
+
+Use warm paper, dark ink, blue and amber markers. The profile selects Retiam's
+bundled `excalifont` for vector labels. Use native `toExcalidraw` through
+`styleGeometry`, and `drawGeometry` for progressive sketch drawing. Use seeded,
+restrained roughness, intentional arrows and light hatching. Keep mathematical
+symbols readable in `Tex`. A question, sketched experiment and resolving annotation
+can share one evolving board. Use dark paper as a custom override if requested.
+Do not apply roughness to every text glyph or continuously jitter all labels.
+
+## minimal — clear vector construction
+
+Use a light canvas, precise outlines, generous negative space and a small number
+of semantic colors. Motion should isolate a relation: align, compare, decompose,
+transfer or resolve. Keep labels local and avoid filling the quiet space with
+paragraphs. Minimal graphics can still carry a lively teacher's narration.
+
+## cinematic — deliberate depth and staging
+
+Use a dark canvas, violet/teal accents, slower establishing moves and a strong
+focus for the current event. Use depth or 3D when it explains a spatial relation;
+2D with deliberate staging is also valid. Lighting and highlights support the
+mechanism. Keep labels and formulas clear as the camera moves, and let the
+resolved state rest. Motion quality does not require constant camera movement.
+
+## Custom override
+
+A prompt can describe a new palette or reference look. Preserve the selected
+profile's useful behavior while overriding tokens in JSON, for example:
+
+```json
+{"style":{"extends":"excalidraw","name":"Night chalkboard","background":"#122322","ink":"#F4F2DD","primary":"#7DE1C4","secondary":"#F1CC75","muted":"#94AAA5","accents":["#7DE1C4","#F1CC75"]}}
+```
+
+`resolveStyle` validates the tokens. Fonts must be bundled aliases or available
+user-supplied font assets. Profile changes affect only entities using the profile;
+agent-authored custom colors/materials must be reviewed during a restyle.

package/agent/skill/references/tts.md

@@ -0,0 +1,166 @@
+# Retiam narration: synthesis and performance
+
+Use `retiam/tts` for speech, timing, subtitles, and the scene voiceover bus.
+Microsoft Edge is the default. Use the native `ElevenLabsTTSProvider` when the
+user selects ElevenLabs and supplies credentials. Preserve the chosen provider;
+diagnose failures rather than silently switching generators or installing Python
+TTS tools. Read the installed declarations before using newer options.
+
+## ElevenLabs: initialize the provider directly
+
+No ElevenLabs Vite plugin or Vite configuration is needed. For a self-contained
+scene example, put `new ElevenLabsTTSProvider()`, `await provider.init({ apiKey,
+voiceId, ... })`, and `await provider.synthesize(...)` inside `Scene.run()`.
+Pass the key directly to initialization. A `.env`, `process.env`, a preparation
+script, and pre-generated audio are optional workflows, not setup requirements;
+do not introduce them when the user requests a simple in-scene example.
+Register synthesis in `composer.pendingTasks` before awaiting it for headless
+rendering. A provider instance can be used directly; selecting it globally is
+only needed when using the `TTS`, `Speak`, or `speak()` facades.
+
+To select an initialized provider globally:
+
+```ts
+import { ElevenLabsTTSProvider, TTS } from 'retiam/tts';
+
+export async function useExpressiveVoice(apiKey: string, voiceId: string) {
+  const provider = new ElevenLabsTTSProvider();
+  await provider.init({
+    apiKey, voiceId,
+    modelId: 'eleven_v3',
+    voiceSettings: { stability: 0.5 },
+  });
+  TTS.setProvider(provider);
+  return provider;
+}
+```
+
+`apiKey` and `voiceId` come from the caller's setup, not literal credentials
+committed to a scene. Browser initialization uses the caller's key directly and
+makes it accessible to that browser. For private preparation use Node's
+`retiam/tts/node` entry point, with the same provider API, and ship the generated
+audio. Do not add ElevenLabs credentials or middleware to `vite.config.ts`.
+Initialization validates local settings without generating audio or fetching
+voices. Use `await provider.fetchVoices()` when choosing a voice;
+`provider.getVoices()` and `TTS.findVoice()` then use that fetched catalog.
+Require a real ElevenLabs voice ID, not an Edge ID or an invented display name.
+
+The default model is `eleven_multilingual_v2`. Select an available expressive
+model such as `eleven_v3` or `eleven_v4` deliberately when directing with audio
+tags. Keep a compatible model/voice pairing throughout a speaker's performance.
+The provider accepts open model IDs, MP3 output formats, model-specific voice
+settings, language, seed, pronunciation dictionaries, and neighboring-text context.
+Per-line overrides go in `elevenlabs`; `speed` can also be supplied at the top
+level. Omitted voice/rate settings inherit provider defaults through `Speak`,
+`speak()` and `TTSNarrationComponent`. `TTS.init()` preserves the selected provider;
+`TTS.configure()` explicitly restores the default Edge client.
+
+## Direct a natural explanation
+
+Choose the emotional action of a beat: inviting a prediction, weighing a
+possibility, making a discovery, or calmly resolving the explanation. Let the
+voice express that action. A constant promotional excitement or a cue on every
+sentence makes an explanation harder to follow. Keep the speaker recognizable
+across beats, with a voice suited to the requested language and audience.
+
+Write speech for listening: concrete questions, contractions, varied sentence
+lengths, and emphasis on the relationship changing on screen. Read technical
+symbols as intended speech; keep formulas and concise notation in the visuals.
+Prefer phrase or paragraph performances to synthesizing isolated words, so the
+model can carry an idea through to its conclusion. Split at genuine explanatory
+boundaries, preserving neighboring context when needed.
+
+Model-specific controls:
+
+- On v3/v4, use occasional delivery tags such as `[curious]` or `[excited]` for
+  a meaningful change in delivery. These models do not support SSML break tags;
+  use punctuation and phrasing for vocal pauses. Test the chosen voice's delivery.
+- On v2 models, use natural punctuation and supported SSML breaks sparingly.
+  Do not assume v3 audio tags work on v2 or Edge. Edge supports its own `pitch`
+  prosody; ElevenLabs rejects nonzero Edge pitch settings.
+- Lower stability can increase variation; higher stability can reduce it.
+  Treat settings as voice/model-dependent. Adjust a short representative sample
+  after listening, rather than maximizing style or copying one preset everywhere.
+- Supported speed is 0.7–1.2. Start close to the voice's natural pace and use
+  explicit scene holds for prediction time. A seed is best-effort, not guaranteed
+  repeatability; approved local audio provides repeatable rendering.
+
+Keep performance directions out of captions. Supply clean `displayText` when
+synthesis text contains delivery or pronunciation markup:
+
+```ts
+import { Speak } from 'retiam/tts';
+
+export function directedLine() {
+  return new Speak('[curious] What changes if we move this point?', {
+    displayText: 'What changes if we move this point?',
+    elevenlabs: { modelId: 'eleven_v3', voiceSettings: { stability: 0.5 } },
+  });
+}
+```
+
+Listen for pronunciation, expression, unwanted vocalizations, rushed endings,
+and pauses before approving a voice. Regenerate only the lines that need it.
+Keep approved audio across visual revisions; settings alone cannot lock a
+performance. Do not spend credits merely to test whether initialization works.
+See the model-specific [ElevenLabs delivery guide](https://elevenlabs.io/docs/overview/capabilities/text-to-speech/best-practices)
+when using an unfamiliar model or control.
+
+## Lessons and prepared speech
+
+For ElevenLabs lessons set `narration.provider` to `elevenlabs`, set `voice` to
+the chosen voice ID, and put model/delivery settings under `narration.elevenlabs`.
+Keep each segment's `text` clean for captions and cue phrases. Optional
+`speechText` contains the exact synthesis script, including delivery tags.
+Keep actual prediction/reveal gaps in `pauseAfterMs`, separate from vocal rhythm.
+
+`retiam lesson prepare` supports both native providers. For ElevenLabs the CLI
+reads `ELEVENLABS_API_KEY` from its environment and passes it to provider.init().
+The key does not go in the lesson JSON. It caches audio and word timings and
+writes `lesson/prepared.json` plus `public/narration/*.mp3`. Reuse those assets
+for subsequent preview and render. Changing delivery text or voice settings
+invalidates the corresponding prepared speech. The runtime can also synthesize
+using an initialized matching global provider or an explicit synthesis adapter.
+
+## Edge browser and renderer setup
+
+Only Edge uses the existing Vite proxy. New projects already enable it. For an
+older project, preserve other plugins and add `msEdgeTTSPlugin` from
+`retiam/vite` on the server side. Its route is `/api/tts/msedge/synthesize` in
+Vite development/preview and Retiam's renderer. Static hosts need that server
+route or prepared audio. Never import the Vite plugin into scene code.
+
+## Timeline recipe
+
+Use [NarratedMotion.ts](../examples/NarratedMotion.ts) as the executable
+integration recipe, adapting its speech and visual action to the brief.
+
+- Use `Speak` for simultaneous narration and motion. Set `entity` to an entity
+  already added to the scene, so playback uses that scene's audio bus.
+- Call `prepareAudio()` before locking timings. Register the synthesis promise
+  in `this.composer.pendingTasks` before awaiting it. Do not register playback
+  promises or `this.play(...)`: those require timeline steps and would deadlock.
+- Derive motion duration from prepared `Speak.duration`. Pass that duration to
+  `Concurrent` too, so its defaults do not rescale the narration.
+- `await speak(this, text, options)` handles playback, subtitles, ducking and
+  scene pacing. For headless use, pre-synthesize the same text/options and
+  register only synthesis as pending work. The provider caches that result.
+- `TTS.speak(...)` is a lower-level client facade; it does not pace the scene.
+- Add `Subtitles` and pass it to the narration. Caption text uses the generated
+  audio's `text`; ElevenLabs character alignment is converted to word timings
+  for lesson cues. Missing timing metadata is not a license to guess cue times.
+- `stream()` yields sentence-sized complete audio results, not transport byte
+  chunks. A directed line with `displayText` stays one performance.
+
+## Diagnose and verify
+
+For ElevenLabs, check initialization, voice/model compatibility, API permissions,
+quota/rate-limit errors, and network access. Errors surface without automatic
+paid retries. After disposal the provider requires initialization again. For
+Edge, a 404 means missing middleware/route; a 502 means upstream synthesis
+failed. Inspect the actual error before changing providers.
+
+Browser autoplay may require a user gesture; headless tools supply their own
+autoplay flag. Verify that exported video contains non-silent audio, listen to
+the performance, and check synchronization. A type check or visual snapshot
+does not establish speech quality.

package/agent/templates/explainer/lesson.json

@@ -0,0 +1,25 @@
+{
+  "version": 1,
+  "title": "Why does area grow so fast?",
+  "topic": "How a square's area changes when its side length doubles",
+  "audience": "Curious beginners",
+  "objective": "See why doubling both side lengths produces four unit squares.",
+  "style": "mathematical",
+  "narration": {"enabled": false, "provider": "msedge", "voice": "en-US-AndrewNeural", "speed": 1, "pitch": "+0Hz", "volume": 1},
+  "sources": [],
+  "claims": [{"id":"area-model","text":"A square of side two can be partitioned into four squares of side one.","sourceIds":[],"illustrative":true}],
+  "beats": [
+    {"id":"predict","goal":"Invite a prediction before exposing the area.","visibleChange":"Draw one unit square and mark its side length.","focus":"The original square","minDurationMs":4500,
+      "narration":[{"id":"question","text":"Here is one unit square. If we double its side length, what happens to its area?","pauseAfterMs":900}],
+      "cues":[{"id":"show","segment":"question"}]},
+    {"id":"grow","goal":"Separate a change in side length from a change in area.","visibleChange":"Expand the outline while retaining the original square.","focus":"Both sides grow","minDurationMs":5000,
+      "narration":[{"id":"expand","text":"Let's double both sides. The original square still fits in the corner. How much new space have we made?","pauseAfterMs":700}],
+      "cues":[{"id":"expand","segment":"expand"}]},
+    {"id":"count","goal":"Discover the four equal areas through decomposition.","visibleChange":"Reveal the three additional unit squares in sequence.","focus":"Four equal pieces","minDurationMs":5000,
+      "narration":[{"id":"reveal","text":"One here, another above, and one more in the corner. Together with our original square, that makes four."}],
+      "cues":[{"id":"reveal","segment":"reveal"}]},
+    {"id":"connect","goal":"Connect the construction to the general area relationship.","visibleChange":"Keep all four pieces visible and reveal the equation below them.","focus":"Side length and area","minDurationMs":4500,
+      "narration":[{"id":"insight","text":"Two times the side length gives four times the area. That's the square in side squared: two growing directions, multiplied together."}],
+      "cues":[{"id":"equation","segment":"insight"}]}
+  ]
+}

package/agent/templates/explainer/review.json

@@ -0,0 +1,6 @@
+{
+  "automated": {},
+  "observations": [],
+  "requiredReview": ["Check factual claims and illustrative model assumptions.","Inspect the beginning, prediction pause, main mechanism, transition and conclusion.","Watch a short preview at normal speed to assess pacing and attention.","Verify the final audio track, captions and video dimensions."],
+  "status": "not-reviewed"
+}

package/agent/templates/explainer/styles.json

@@ -0,0 +1,92 @@
+{
+  "mathematical": {
+    "name": "Dijkstra-style mathematical explainer",
+    "background": "#0A1020",
+    "ink": "#ECF0F5",
+    "muted": "#74869C",
+    "primary": "#6CD5FF",
+    "secondary": "#F7CF73",
+    "font": "roboto",
+    "strokeWidth": 0.035,
+    "rough": false,
+    "roughness": 0,
+    "fillStyle": "solid",
+    "motion": {
+      "drawMs": 1200,
+      "moveMs": 1400,
+      "holdMs": 700
+    },
+    "accents": [
+      "#65F0C4",
+      "#FF879F",
+      "#BA98FF",
+      "#55DDE0"
+    ]
+  },
+  "excalidraw": {
+    "name": "Excalidraw whiteboard",
+    "background": "#FFFDF7",
+    "ink": "#263238",
+    "muted": "#7B858C",
+    "primary": "#1971C2",
+    "secondary": "#D46B08",
+    "font": "excalifont",
+    "strokeWidth": 0.04,
+    "rough": true,
+    "roughness": 0.7,
+    "fillStyle": "hachure",
+    "motion": {
+      "drawMs": 1600,
+      "moveMs": 1500,
+      "holdMs": 900
+    },
+    "accents": [
+      "#1971C2",
+      "#D46B08"
+    ]
+  },
+  "minimal": {
+    "name": "Minimal vector",
+    "background": "#F8FAFC",
+    "ink": "#17212B",
+    "muted": "#68788A",
+    "primary": "#2563EB",
+    "secondary": "#C2410C",
+    "font": "roboto",
+    "strokeWidth": 0.025,
+    "rough": false,
+    "roughness": 0,
+    "fillStyle": "solid",
+    "motion": {
+      "drawMs": 900,
+      "moveMs": 1100,
+      "holdMs": 650
+    },
+    "accents": [
+      "#2563EB",
+      "#C2410C"
+    ]
+  },
+  "cinematic": {
+    "name": "Cinematic diagrams",
+    "background": "#080B18",
+    "ink": "#F4F1FF",
+    "muted": "#8290AA",
+    "primary": "#B79AFF",
+    "secondary": "#58E0CE",
+    "font": "roboto",
+    "strokeWidth": 0.04,
+    "rough": false,
+    "roughness": 0,
+    "fillStyle": "solid",
+    "motion": {
+      "drawMs": 1500,
+      "moveMs": 2000,
+      "holdMs": 1000
+    },
+    "accents": [
+      "#B79AFF",
+      "#58E0CE"
+    ]
+  }
+}

package/bin/agent-kit.js

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {copyLessonKit} from './lesson-project.js';
+
+export const agentKitRoot = fileURLToPath(new URL('../agent/', import.meta.url));
+
+/** Used only while creating an empty project or preparing a fresh template. */
+export function copyAgentKit(directory, options = {}) {
+    const files = [];
+    for (const name of ['AGENTS.md', 'CLAUDE.md']) {
+        fs.copyFileSync(path.join(agentKitRoot, name), path.join(directory, name));
+        files.push(name);
+    }
+    const destination = path.join(directory, '.agents/skills/retiam');
+    fs.cpSync(path.join(agentKitRoot, 'skill'), destination, { recursive: true });
+    function collect(folder) {
+        for (const entry of fs.readdirSync(folder, { withFileTypes: true })) {
+            const location = path.join(folder, entry.name);
+            if (entry.isDirectory()) collect(location);
+            else files.push(path.relative(directory, location).split(path.sep).join('/'));
+        }
+    }
+    collect(destination);
+    return [...files,...copyLessonKit(directory,options)];
+}