Objective + recap cards as first-class artifacts

[jbrecht]

Source: instructional-designer pedagogy review, docs/reviews/2026-06-13-pedagogy-review.md (Part 2, item #3 — High impact / Medium feasibility, "Next").

User story

As a tutorial author, I want to declare learning objectives and a recap and have them rendered as title/objective and summary cards, so my video opens by telling learners what they'll be able to do and closes by consolidating it (advance-organizer, pre-training, and summary principles).

Why feasible now

• The spec already lists intro/outro cards as a deferred-but-designed-for post stage: tutorial-forge-spec.md:223 ("idle speed-up …, zoom-on-callout, intro/outro cards").
• The rendering path exists: the caption system already renders browser HTML → composited frames (packages/core/src/post/captions.ts), so cards reuse that machinery rather than a new renderer.
• The example already models this incidentally — opening organizer at packages/example-app/tutorials/getting-started.tutorial.ts:5, recap at :70 — making it explicit makes good practice reusable rather than accidental.

Scope

1. Add objectives?: string[] and/or summary?: string to the Tutorial type (packages/core/src/types.ts:81). Validate in validateTutorial() (packages/core/src/spec.ts).
2. Render an optional title/objective card before step 1 and an optional recap card after the final step, as composited frames in the post stage, held for a readable duration.
3. Localize via the existing translations mechanism (cards are text → must respect lang).
4. Cards should account for their duration in the manifest / chapter markers (coordinate with the chapters issue) so timestamps stay correct.

Acceptance criteria

• Tutorial.objectives / Tutorial.summary exist, typed, validated.
• When present, intro and recap cards render and composite correctly in the final MP4.
• Cards are optional — tutorials without them are unchanged.
• Card text is localizable through translations.
• Card timing is reflected in manifest totals and (if shipped) chapter markers.
• Documented in docs/writing-tutorials.md.

Open decisions (for maintainer)

• Card styling/templating: reuse captionStyle-like config vs. a dedicated card theme? Recommend a minimal built-in template first, theming later.
• Should objectives also be narrated (TTS) or purely visual? Recommend visual-only in v1 to avoid forcing redundancy; let authors put the spoken organizer in step-1 narration as they do today.