Story authoring workflow

Keep one loop in mind while authoring:

1. start from a small .story.yaml,
2. preview it as soon as it runs,
3. borrow from the nearest checked-in sample,
4. export or capture proof once the timing works.

Start from the smallest sample that teaches the next idea

Use the samples in this order:

• Quick start for one create → set → wait flow,
• samples/story/sample.story.yaml for a longer single-file tour,
• task-focused samples such as settle-demo, camera-world-demo, design-system, tts-demo, or video-demo when you need a specific capability.

That keeps your working file small instead of copying several unrelated features at once.

Keep related files beside the Story

The checked-in samples use relative paths for reusable pieces:

• ./sprites/split-flap in composite-sprite.story.yaml
• ./designs/dark in design-system.story.yaml
• assets/flower.mp4 in video-demo.story.yaml

Follow the same pattern in your own folder so the Story, its assets, reusable sprites, and design layers stay portable together.

Preview early, not only at the end

story preview samples/story/sample.story.yaml

Preview is the fastest way to check layout, pacing, and obvious syntax mistakes before you invest more work.

Pick the closest sample for each task

Goal	Sample
Spring timing and wait: settle	samples/story/settle-demo.story.yaml
Camera, world, and screen space	samples/story/camera-world-demo.story.yaml
Matching path reveal and motion timing	samples/story/path-motion-trim.story.yaml
Reusable custom sprites	samples/story/composite-sprite.story.yaml
Shared tokens and styles	samples/story/design-system.story.yaml
Speech and narration timing	samples/story/tts-demo.story.yaml
Local MP4 playback	samples/story/video-demo.story.yaml

Read the smallest relevant sample before inventing syntax from memory.

Use guides first, reference second

• Stay in getting started and guides while learning a workflow.
• Jump to reference when you need an exact CLI option or field name.
• Use Specs only when a guide intentionally points you there for deeper contracts.

That keeps the learning path focused on authoring tasks instead of engine internals.