retiam 2.0.1 → 2.0.2

package/agent/skill/references/explainers.md

@@ -0,0 +1,121 @@
+# 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. The built-in voice remains the default. Change a provider only when
+requested; additional providers 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,148 @@
+# 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.
+
+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,72 @@
+# Native Retiam narration
+
+Generate speech for Retiam scenes through `retiam/tts`. It supplies synthesis,
+timing, subtitle synchronization, and playback through the scene's voiceover bus.
+The built-in provider uses Microsoft Edge neural speech over the network. It
+does not require installing Python TTS packages.
+
+Use [NarratedMotion.ts](../examples/NarratedMotion.ts) as the executable recipe.
+Copy it into `src/scenes/` to preview or render it. Adapt the text, voice, and
+motion to the brief. Use a different speech generator only if the user requests
+one; diagnose failures in this path instead of silently replacing it.
+
+## Browser and renderer setup
+
+New projects enable the native proxy in their Vite configuration. For an existing
+project using an engine release that provides `retiam/vite`, preserve its other
+plugins and add:
+
+```ts
+import { defineConfig } from 'vite';
+import { msEdgeTTSPlugin } from 'retiam/vite';
+
+export default defineConfig({ plugins: [msEdgeTTSPlugin()] });
+```
+
+This is a **server-side** import. Scene code imports speech APIs from `retiam/tts`.
+The middleware serves `/api/tts/msedge/synthesize` in Vite development and preview
+servers, including the Vite server started by Retiam's render/snapshot commands.
+A static production host needs an equivalent server endpoint or pre-generated
+audio; bundling the page alone does not host speech synthesis.
+
+## Timeline recipe
+
+- Use `Speak` as an animation for simultaneous narration and motion. Set `entity`
+  to an entity already added to the scene so speech uses that scene's audio bus.
+  Call `prepareAudio()` first; its result sets the animation's exact duration.
+- Register the **synthesis promise** in `this.composer.pendingTasks` before
+  awaiting it. Headless tools can then wait for network speech generation without
+  advancing the scene past the narration. Do not register `this.play(...)` or
+  `speak(...)` promises there: they need timeline updates and would deadlock.
+- Set accompanying motion duration from the prepared `Speak.duration`. Avoid
+  guessing speech duration from word counts. Also pass that duration explicitly
+  to `Concurrent` so the group's defaults do not rescale the prepared narration.
+- For sequential narration, `await speak(this, text, options)` synthesizes,
+  plays, synchronizes optional subtitles, and waits for the utterance duration.
+  Pre-synthesize that text with `TTS.synthesize(text, options)` and register only
+  its synthesis promise before headless rendering; the default provider caches
+  the result in memory.
+- `TTS.speak(...)` is a different, lower-level client facade. Its playback result
+  does not itself provide the scene's `wait(...)` pacing.
+- Add `new Subtitles({ fontSize, bottomOffset, maxWidth, ... })` to the scene, and
+  pass it as `subtitles`. Keep the caption area within the shot. Caption timing
+  uses the generated audio metadata.
+- `voice` is a voice ID such as `en-US-JennyNeural`; `speed` is a multiplier
+  such as `1.0`, `pitch` accepts values such as `'+0Hz'`, and playback `volume`
+  is 0–1. Follow installed types for more options.
+
+## Diagnose native TTS failures
+
+1. A missing `retiam/vite` import means the installed engine predates this setup
+   or its build is incomplete. Check `retiam context --json` and the installed
+   package version before changing providers.
+2. HTTP 404 at `/api/tts/msedge/synthesize` means the middleware is absent or the
+   configured endpoint differs. Fix the Vite configuration and restart the server.
+3. HTTP 502 means the proxy ran but synthesis failed. Read the server error;
+   check network access and the requested voice. Do not present silent audio as
+   a successful narration render.
+4. Browser autoplay may require a click or keypress to unlock audio in Studio.
+   The headless CLI supplies its autoplay flag.
+5. For exported video, verify an audio stream exists and listen to the result.
+   Snapshots verify visuals only. Speech generation requires network access on a
+   cache miss; the middleware caches audio in `node_modules/.cache/msedge-tts`.

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)];
+}

package/bin/cli.js

@@ -20,13 +20,17 @@ const exportScript = path.join(__dirname, 'export.js');
 const lintScript = path.join(__dirname, 'lint.js');
 const snapshotScript = path.join(__dirname, 'snapshot.js');
 const initScript = path.join(__dirname, 'init.js');
+const contextScript = path.join(__dirname, 'context.js');
+const lessonScript = path.join(__dirname, 'lesson.js');
 
 function runScript(scriptPath, scriptArgs) {
     if (scriptPath === renderScript || scriptPath === snapshotScript) {
         try {
             createRequire(import.meta.url).resolve('puppeteer');
         } catch {
-            console.error('Retiam installation is incomplete: its required Puppeteer dependency is missing. Reinstall Retiam in your project with: npm install retiam');
+            const message = 'Retiam installation is incomplete: its required Puppeteer dependency is missing. Reinstall Retiam in your project with: npm install retiam';
+            if (scriptPath === snapshotScript && scriptArgs.includes('--json')) console.log(JSON.stringify({ status: 'error', message }));
+            console.error(message);
             process.exit(1);
         }
     }
@@ -48,6 +52,8 @@ Usage:
   npx retiam help <command>                 (detailed help for a single command)
 
 Commands Overview:
+  lesson           Teaching plans, styles, native narration, cue timelines, and captions
+  context          Locate version-matched agent guidance, examples, and API declarations
   init, create     Initialize a complete Retiam WebGPU animation skeleton project
   lint             Statically analyze scenes for runtime hazards and async timing bugs
   snapshot         Capture multi-timestamp visual PNG keyframes via headless WebGPU
@@ -85,7 +91,7 @@ Commands Overview:
 
 ================================================================================
 2. SNAPSHOT (npx retiam snapshot <file> [options])
-   Capture visual PNG keyframe snapshots at specific timeline seconds.
+   Run the named scene directly and capture PNGs at fixed-step timeline seconds.
 
    Arguments:
      <file>                    Target scene TypeScript file (e.g. MyScene.ts)
@@ -95,6 +101,8 @@ Commands Overview:
      -w, --width <px>          Snapshot width in pixels (default: 1280)
      -h, --height <px>         Snapshot height in pixels (default: 720)
      -o, --out <dir>           Output directory for images (default: ./outputs/snapshot)
+     --fps <num>              Timeline step rate (default: 60)
+     --timeout <ms>           Browser operation timeout (default: 120000)
      --json                    Output structured JSON for agents & CI automation
      --help                    Show snapshot-specific help
 
@@ -113,6 +121,8 @@ Commands Overview:
    Options:
      -n, --name <name>         Project name for package.json (default: directory name)
      --title <text>            Hero text for starter Hello World scene (default: Hello World)
+     --template <name>         basic (default) or explainer worked construction
+     --style <name>            mathematical (Dijkstra default), excalidraw, minimal, cinematic
      --pm <manager>            Package manager: npm, pnpm, yarn, bun (default: auto or npm)
      -f, --force               Overwrite destination directory if files already exist
      -y, --yes                 Skip interactive prompts and use defaults
@@ -167,7 +177,13 @@ Commands Overview:
 `);
 }
 
-if (command === 'lint') {
+if (command === 'lesson') {
+    runScript(lessonScript, args.slice(1));
+}
+else if (command === 'context') {
+    runScript(contextScript, args.slice(1));
+}
+else if (command === 'lint') {
     // Usage: npx retiam lint src/MyScene.ts [--json]
     runScript(lintScript, args.slice(1));
 }
@@ -189,7 +205,11 @@ else if (command === 'render') {
 } 
 else if (command === 'help') {
     const sub = args[1];
-    if (sub === 'lint') {
+    if (sub === 'lesson') {
+        runScript(lessonScript, ['--help']);
+    } else if (sub === 'context') {
+        runScript(contextScript, ['--help']);
+    } else if (sub === 'lint') {
         runScript(lintScript, ['--help']);
     } else if (sub === 'snapshot') {
         runScript(snapshotScript, ['--help']);