Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# lesson-plan Card

# Lesson-Plan Cards

A lesson-plan is the **ordered delivery flow** of a course: the sequence of segments that says *what to do, in order*. It is the third course component alongside the other two, and the line between them matters:

- the **concept-map** says *what* to learn (the knowledge graph),
- the **exposition-plan** says *how* to present it and **why** (the rated approaches + rules),
- the **lesson-plan** just *sequences* it — what happens, in what order, live-or-material.

So the rationale for a choice lives in the exposition-plan; here, `do` is **terse** (the activity, not the argument for it).

## Segments

Each segment commits to one `mode`:

- **interactive** — the learning is in the back-and-forth: eliciting the learner's model, predict-and-explain, Socratic dialog. It happens live in chat; there's no pre-made artifact.
- **material** — a pre-made artifact carries it better than live talk: a `figure` to manipulate, a `doc` to read. The segment refs that card.

**Most early-course segments are interactive.** Reach for `material` only where a made artifact genuinely earns it (something worth re-reading, or a manipulable that beats description). A `material` segment may still carry an interactive `note` (e.g. "have them predict before revealing the figure") — that's how "both" is expressed without a third mode.

```yaml
segments:
  - do: Elicit their model — "what's actually moving when an acid reacts?"
    mode: interactive
    concepts: [proton-transfer]          # concept-map node id(s) this advances
  - do: Walk the proton-transfer figure; have them predict each step first
    mode: material
    status: ready                        # the card exists
    concepts: [proton-transfer, conjugate-pairs]
    material: { ref: /_content/courses/Acids.attach/material/Proton_Transfer.figure.card }
    note: Predict-then-reveal; don't just show it
  - do: Written recap of strong-vs-weak acids to re-read later
    mode: material
    status: planned                      # outlined, not built yet
    concepts: [acid-strength]
```

## Status — make deferral visible, never silent

A build does **not** author all the material up front. Most material segments stay outlined. Mark each material segment honestly:

- **ready** — the `material` card exists; ref it.
- **planned** — the card is outlined here but not built yet (authored later, during teaching).

The lint **warns** on a `material` segment that has neither a `material` ref nor `status: planned` — so "incomplete material" is a stated fact, not a hidden gap. A complete build is *not* "every segment authored"; it's "every material segment is `ready` or explicitly `planned`." A mostly-interactive, mostly-`planned` course is a complete plan.

## Concepts

`concepts` lists concept-map node `id`s the segment advances. They're checked against the course's concept-map (the sibling `*.concept-map.card`); a stale id warns, naming the segment.

## Body

The framing: the arc of the course, where it goes live vs material-backed, and why this ordering. Living — amend it as the course adapts. Use **neutral pronouns** (they/them) for the learner.

## The `contains:` field

Give this card a one-sentence `contains:` — the prime retrieval field for
`bbx search` and listings. How to write a good one (carry the information when
it's concise, never a list of parts, under 200 characters) is in the agent
guide's ABOUT_CARDS section.

## Templates

### lesson-plan

An ordered delivery flow (segments tagged interactive vs material, tied to the concept-map)

```bash
bbx create <path>.lesson-plan.card -t lesson-plan
```

Template: lesson-plan
Description: An ordered delivery flow (segments tagged interactive vs material, tied to the concept-map)
Card types: lesson-plan

Arguments:
  title (optional): Display title