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

# concept-map Card

# Concept-Map Cards

A concept-map is a **module-scale knowledge graph**: one card holds the whole graph for one bounded topic. Concepts are **nodes inside this card** (not separate cards), and edges reference other nodes **by their `id` within this same card** — they are *not* file refs. The graph is self-contained, so moving or renaming the card never breaks an edge.

The graph is **loose, and cycles are intended.** Two concepts that only make sense together — that a learner bootstraps at the same time — are an honest `complements` cycle, not an error to fix. Don't contort the graph to avoid a cycle.

## Scope — fit, not completeness

A node should be something you'll actually *teach* toward the course's success-criteria, not everything that could be said about the topic. Don't node-ify background the learner already has — assume it in a sentence. **Tune how far back the map starts to what you know about the learner:** with a real read on their edge (a probe, or a specific `audience`), start near it; with little to go on (a generic course, no probe), starting more completely from the foundations is the right fallback. Completeness is for low information, not the default.

## Building the map — naming and shape

Scope decides *what's in*; these rules keep what's in actually teachable:

- **Name nodes as entities, not questions.** "Proton Transfer," never "What is proton transfer." Each `name` is a noun-phrase a learner could be heard saying, clear and specific.
- **Right granularity — one teachable unit per node.** Not a whole topic, not a trivia-sized sub-fact. If you'd teach two things in the same breath, they're one node; if a "node" needs its own little arc, split it.
- **No orphans.** Every node should connect to the rest by at least one edge. A concept floating with no edges almost always means it doesn't belong, or that a real relationship went unstated. (The lint warns on orphans.)
- **Edges are real relations, not decoration.** Draw an edge only where the relationship genuinely holds, and commit it to a `kind` (below). Don't wire nodes together just to look connected.
- **Avoid a degenerate straight line.** If the map is just A→B→C→D, each node depending only on the one before, you've under-modeled it — real subjects branch and reconverge. A spine is fine; a single unbranched chain usually means missing structure.
- **The most depended-on node is load-bearing.** The concept several others build on is the one to get right and introduce early — let the graph's shape show you where the weight sits.

Because a course is usually built automatically (the learner can't review the graph), **read the finished map back against these rules before building anything on it** — that self-check is the quality gate.

## Frontmatter

```yaml
concepts:
  - id: vectors                 # stable, unique in this card; how progress refers to this node later
    name: Vectors
    kind: concept               # fact | concept | procedure | principle  (see "kind", below)
    gloss: A quantity with magnitude and direction.   # optional one-liner
    depth: understand           # optional target Bloom level
    misconceptions:             # optional — the COMMON misconceptions about this concept
      - Thinking a vector is just its length, ignoring direction
    related:                    # optional edges to other nodes IN THIS card
      - { to: matrices, kind: complements }
```

Each concept needs an `id`, a `name`, and a `kind`; everything else is optional. A node `id` must be unique in the card, and every edge `to` must name a real node `id` — both are checked.

`misconceptions` are the **common, known** wrong models for this concept — what learners *typically* get wrong — so the teaching can preempt them. They describe the *subject*, not any one learner, and are reusable across courses. (Which misconceptions a **specific** learner actually holds is per-learner state — that goes in the `progress` card, not here.)

## `kind` — a strong hint to *how* to teach the node

Not the whole story, but a strong steer:

- **fact** — an arbitrary association → retrieval practice, spacing.
- **concept** — a category you recognize instances of → varied examples + non-examples.
- **procedure** — a condition→action you execute → worked examples, then faded practice.
- **principle** — a deep model that explains *why* and transfers → self-explanation, contrasting cases.

## `depth` — the target Bloom level (optional)

`depth` names *how deeply* the learner should hold a node — a target, not a test. The six Bloom levels:

- **remember** — recall the fact or term.
- **understand** — explain it in their own words; grasp the mechanism.
- **apply** — use it in a new but similar situation.
- **analyze** — break it down, compare, see how the parts relate.
- **evaluate** — judge, critique, choose between options.
- **create** — combine it into something new.

`depth` works *with* `kind` to steer teaching: a `fact` at **remember** wants spaced retrieval; a `principle` at **analyze** wants contrasting cases and self-explanation; an **understand** target is rarely served by a passive read. The exposition-plan turns the (kind, depth) pair into concrete approaches — so set `depth` where the intended level isn't obvious.

## Edges — pick one `kind` from the closed set (no "other")

An edge is optional, but if you draw one it **must** carry a `kind` from this set. There is no catch-all "related to" — an edge commits to a teaching-meaningful relation:

- **prerequisite** — B genuinely can't be grasped without A. Sequence A before B; if a learner struggles with B, revisit A.
- **complements** — A and B reinforce each other and are learned together. This is where spirals (and cycles) live.
- **contrasts-with** — A and B are clarified by comparison. Teach the distinction explicitly.
- **applied-in** — A (a principle or procedure) is put to work in B. Use it to ground the abstract and show transfer.
- **commonly-confused-with** — learners conflate A and B. Do an explicit disambiguation.

## Body

The body is the framing: what this map covers, where concepts spiral together, and the design rationale. The actual teaching material lives in a course's `material/`, not here.

## 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

### concept-map

A module-scale knowledge graph (concepts as in-card nodes with typed edges)

```bash
bbx create <path>.concept-map.card -t concept-map
```

Template: concept-map
Description: A module-scale knowledge graph (concepts as in-card nodes with typed edges)
Card types: concept-map

Arguments:
  title (optional): Display title