Wanderland Tutorial Storyboard

The curriculum map for the tutorial corpus on wanderland.dev. Where the style guide names voice and shape, this storyboard names the concept order — what each tutorial introduces, what it assumes, where it sits in a series. Read it before drafting a new tutorial or updating an existing one so the layering stays consistent: don't reintroduce a concept already covered upstream, don't skip a foundation a downstream tutorial leans on.

The corpus today is two arcs: the Getting Started trio that scaffolds a new wanderland-core application, and the Engine in a Box series that builds a real puzzle engine on top of that foundation.

Getting Started

Three posts, taken in order. By the end the reader has a working my-app/ directory with custom boundaries, scenarios passing under three test lenses, and an HTTP adapter wrapping external calls — the framework's surface for a typical microservice.

1. Hello World

• Slug: wanderland-dev-tutorial-hello-world
• Status: Active

Scope: Scaffold a new wanderland-core application from empty directory through running tests, in 21 numbered steps.

Introduces:

• Project structure: Gemfile, config.yml, config.ru, Rakefile, lib/<app_name>/boundaries/
• Wanderland.boot(config_path) and the Runtime
• Custom boundary registration (Wanderland::Boundary.register)
• Routes — single-boundary form (boundary: and name:)
• Three runtime modes: --type http, --type cli, --type test
• Scenarios under scenarios: in config.yml
• Three test lenses on one scenarios block: --type test runner, X-Wanderland-Verify HTTP probe, Scenario.rspec_describe! rspec hook
• --wanderland-verify CLI flag

Assumes: Ruby fundamentals, Bundler.

2. Writing Boundaries

• Slug: wanderland-dev-writing-boundaries
• Status: Active

Scope: Walk through writing two real-world HTTP-calling boundaries (baby_lookup, babies_by_origin) end-to-end with halts and scenarios.

Introduces:

• Boundary anatomy in depth: identity, scopes, capabilities, input_shape, output_shape, when_shape
• Halt semantics — boundaries raising stop signals
• Required vs optional params (declared in input_shape)
• Net::HTTP.get_response directly inside a boundary (foreshadowing adapters)
• Multi-scenario coverage (happy paths plus error paths)

Assumes: Hello World — project structure, scenarios block, custom boundary basics. Ruby HTTP basics.

3. Adapter Modes

• Slug: wanderland-dev-adapter-modes
• Status: Active

Scope: Port the two HTTP boundaries from Writing Boundaries onto the HTTP adapter; record cassettes; introduce per-scenario mocks; toggle modes via env.

Introduces:

• Adapter concept and how it composes (boundary declares adapters: [:http], route mounts the adapter, framework wires the rest)
• Three adapter modes: live, replay, mock
• Cassette recording (--wanderland-record-to) and cassette file format
• Per-scenario mock declarations: inline envelope, !Fixture (lift cassette), !Merge (twist cassette)
• Mock-mode toggle for scenarios
• Environment override (WANDERLAND_HTTP_MODE)
• Adapter facade vs Net::HTTP escape hatch
• When-to-reach-for-which guidance for the three mock styles

Assumes: Writing Boundaries — HTTP boundary code. Hello World — config.yml, scenarios.

Engine in a Box

Six posts, taken in order, drafted iteratively. The series scaffolds sprout-engine — a wanderland-core application that runs grid-shaped workflows for the puzzle UI in sprout-shorts-context-accumulating-dag. Each post extends the previous one's running engine.

1. Engine in a Box

• Slug: wanderland-dev-tutorial-engine-service
• Status: Skeleton

Scope: Scaffold sprout-engine from empty directory to running Docker container with the full introspection surface answering against an /echo route.

Introduces:

• Brand-new wanderland-core app pattern (sibling of the wanderland-core symlink, not built on hello-world)
• Liveness triptych: /health, /status, /healthcheck
• Five introspection endpoints: /inspect/routes, /inspect/route/:name, /inspect/boundaries, /inspect/boundary/:name, /inspect/diagnostics
• The eleven CORE_ROUTES (framework-mounted, immutable)
• Five framework default injections: enforce_denials, verify_route, trace_emit, format, seal
• Compiled chain composition (user_chain vs compiled_chain)
• Diagnostics cache for boot-time conditions
• Dockerfile and docker-compose for a wanderland-core service

Assumes: Hello World — project bones, routes. Bundler, Docker basics.

2. Walking the Grid

• Slug: wanderland-dev-tutorial-engine-grid-route
• Status: Skeleton

Scope: Add a grid route (POST /run, POST /run/step) that walks Nita's grocery errand. Introduces run_grid, the located-context model, ShapeMatcher in depth, and pause-resume mechanics.

Introduces:

• Grid routes vs chain routes — workflow logic, end-user customization, Zapier-style composition
• grid: YAML shorthand → synthetic chain: [run_grid] slot
• run_grid system boundary; chain-slot architecture (no special grid path)
• Located context: item is { id, position, context, awaiting?, halted? } — no separate state field
• Wanderland::Context access patterns: bracket (context["bag"]), dot (context.boundary_name), chainable filters (signed, for_boundary, by_identity, with_capability)
• Cells, springs, harvests, connections
• Item lifecycle: seed → tick → harvest, with pause and halt branches
• Stateless stepping — /run runs to completion, /run/step advances one tick
• args_override for resume after a pause
• Pause-on-input-shape-miss (recoverable)
• Dead-end halt (:signals:stop:grid:dead-end, unrecoverable)
• ShapeMatcher in depth: field keys vs predicate keys; count, gte, in_order, first, nth, etc.; custom predicate registration
• oculus_fence boundary (calls oculus's stateless fence-execute API; surfaces session_id)
• emit_signal boundary (returns crossing with :signals:web:<action> type_addr)
• Scenarios as the puzzle's solved-state contract; route mode vs boundary mode

Assumes: Engine in a Box #1 — sprout-engine scaffold, introspection surface. Hello World — scenarios, --type test, rspec hook. Writing Boundaries — boundary registration anatomy.

3. Web Signals

• Slug: wanderland-dev-tutorial-engine-web-signals
• Status: Planned

Scope: Fan events[] out via window.lanternBus; drive <oculus-node> scene swaps; opt into the full trace via X-Wanderland-Trace.

4. Puzzle Component

• Slug: wanderland-dev-tutorial-engine-puzzle-component
• Status: Planned

Scope: Native <wanderland-puzzle> Custom Element. Render-from-state, Run / Step buttons, walks events[], calls lanternBus.emit(action, payload).

5. Puzzle IDE

• Slug: wanderland-dev-tutorial-engine-puzzle-ide
• Status: Planned

Scope: Palette, placements loader, modeline-base header, footer modelines, trace panel with playback controls, harvests panel.

6. Shorts Integration

• Slug: wanderland-dev-tutorial-engine-shorts-integration
• Status: Planned

Scope: Drive sprout-shorts-context-accumulating-dag scene swaps from the puzzle. Wire wanderland-engine into the larger sprout compose orchestration.

Concept index

Quick "where is X introduced?" lookup for the active corpus.

How to use this storyboard

When drafting or updating a tutorial:

• Find where the post sits in the curriculum (which arc, which position).
• Read the Assumes for that post and confirm everything listed is genuinely covered upstream. If something isn't, decide: introduce it here, push it to a prior post, or add a missing prior post.
• Read the Introduces for that post and decide which concepts are actually new in this post versus carried forward. Reframe the body so each new concept gets its anatomy lesson, examples, and diagnostics; assumed concepts get a brief reminder and a cross-link, not a re-introduction.
• Update this storyboard's Introduces / Assumes for the post when the body settles. The storyboard moves with the corpus; stale entries are worse than missing ones.

Site Audit

wanderland.dev