# Cramdeck — Sample Decks

> **Version 1.2.0** · Updated 2026-04-26 · See [CHANGELOG](../CHANGELOG.md)

A curated set of `.deck.md` files that exercise every card-authoring feature
the Integrations API supports today. Use them as:

- **Reference material** when writing your own decks by hand or with an LLM.
- **Smoke-test fixtures** to verify a new integration end-to-end.
- **Public starter content** — every sample here is real, accurate, and
  ready to publish.

Each file is a self-contained `.deck.md` document. To import any of them:

```bash
curl -X POST https://your-cramdeck-host/api/v1/integrations/decks/import \
  -H "Authorization: Bearer cdk_pat_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: text/markdown" \
  --data-binary @french-a1-essentials.deck.md
```

## Card-type cheat sheet

The card-types design system gives every card a **semantic type** (`extras.cardType`)
that drives the layout, accent, and editor affordances. Pick the type that
best matches the *kind of recall* the card asks for; the renderer takes care
of the rest.

| `cardType` | When to use | Default content types | Example deck |
|---|---|---|---|
| `basic` | Plain Q&A. Also the right pick for image-recognition cards (flag → country, picture → vocabulary). | markdown → markdown | French A1, Chemistry, World flags |
| `definition` | "What is X?" → meaning + key properties. | markdown → markdown | Chemistry, French A1 |
| `formula` | LaTeX equation on the front, explanation on the back. | latex → markdown | Physics |
| `name-formula` | Name ↔ formula pairings; set `direction: name->formula` or `formula->name`. | text → latex | Physics, Chemistry |
| `code-behavior` | Code snippet on the front, predict the output. | markdown → markdown | JS array methods |
| `comparison` | "X vs Y" — back is a structured table or list. | markdown → markdown | JS array methods |
| `procedure` | Numbered steps to follow. | markdown → markdown | JS array methods, World flags |
| `explanation` | "Why does X happen?" — mechanism behind a fact. Also fits images that need a longer back. | markdown → markdown | World flags |
| `pitfall` | Common mistake + better alternative. | markdown → markdown | Physics, JS array methods |

> **Image is a content choice, not a card type.** Attach `frontMedia` /
> `backMedia` to any card type. The renderer auto-applies the
> image-dominant 65/35 layout when the side has an image AND a short
> caption (≤ 60 chars); longer captions get a balanced 50/50 split. The
> retired `image-question` and `image-explanation` types are normalized
> on import to `basic` and `definition` respectively (deprecation
> warning emitted).

Legacy decks that still use `extras.template` (`default` / `math` / `code`)
keep working — the parser normalises them to the new `cardType` taxonomy
(`default → basic`, `math → formula`, `code → code-behavior`) and emits a
warning so authors know to upgrade.

## What each sample demonstrates

| File | Card types covered | Notes |
|---|---|---|
| `physics-mechanics-formulas.deck.md` | `formula`, `name-formula`, `pitfall` | LaTeX-rendered equations on the front; pitfall card includes a "better alternative" hint. |
| `chemistry-common-compounds.deck.md` | `name-formula` (both directions), `definition`, `basic` | HTML subscripts/superscripts for formulas; per-card `direction` flips the recall side. |
| `js-array-methods.deck.md` | `code-behavior`, `comparison`, `pitfall`, `procedure` | Markdown bodies with fenced code blocks; comparison card uses a Markdown table on the back. |
| `french-a1-essentials.deck.md` | `definition`, `basic` (with images) | Vocabulary cards with usage hints; two cards include `frontMedia` for picture-prompted recall — the renderer applies the image-dominant layout automatically. |
| `world-flags-europe.deck.md` | `basic` (with images), `explanation` (with images), `procedure` | External HTTPS image URLs from `flagcdn.com`; mixes flag-recognition cards (short caption → image-dominant layout) with longer explanation/procedure cards. |

Together the five samples cover every type in the registry.

## Card-meta block reference

Every per-card customization goes in a trailing `<!-- card: ... -->` block at
the end of the card. Indented YAML body:

```markdown
## Front

F = ma

## Back

Newton's second law.

<!-- card:
  cardType: formula
  subject: Physics
  topic: Newton's laws
  prompt: "Recall the formula and define each variable."
  difficulty: easy
  frontType: latex
  backType: markdown
-->
```

Supported keys (any subset; omit anything you don't need):

**Card-types axis (semantic structure):**

- `cardType` — one of `basic`, `definition`, `explanation`, `comparison`,
  `procedure`, `pitfall`, `formula`, `name-formula`, `code-behavior`.
  Drives layout, accent, and the category label shown on the rendered
  card. The retired `image-question` / `image-explanation` values are
  still accepted on import (normalized to `basic` / `definition`); do
  not emit them in new decks.
- `subject` — short subject name (e.g. `Physics`, `JavaScript`). Surfaces in
  the category label and selects a subject-specific accent colour when
  recognised (Chemistry blue, JavaScript amber, Physics green, Math violet).
- `topic` — narrower topic shown next to the subject (`Newton's laws`).
- `direction` — only meaningful for `name-formula`. One of
  `name->formula` or `formula->name`.
- `prompt` — short instructional prompt rendered below the front body
  (e.g. *"Predict the output before flipping."*).
- `difficulty` — one of `easy`, `medium`, `hard`. Surfaces in the editor.
- `tags` — array of short tags for filtering and search.

**Content-format axis (per-side):**

- `frontType` / `backType` — one of `text`, `markdown`, `html`, `latex`.
  Defaults to the type's defaults (see registry table).
- `contentType` — legacy global content type. Prefer the per-side keys.

**Media:**

- `frontMedia.imageUrl` / `frontMedia.imageAlt` — front-side image. URL
  must be `https://`. Base64 data URLs are rejected.
- `backMedia.imageUrl` / `backMedia.imageAlt` — back-side image, same rules.

**Other:**

- `oneSided: true` — front-only card; the back is hidden.
- `templateData` — free-form object reserved for type-specific options.
- `template` — **deprecated.** Legacy axis; the parser maps it to
  `cardType` and emits a warning. Use `cardType` directly in new decks.

## Frontmatter reference

Every deck must start with a YAML frontmatter block:

```yaml
---
title: My Deck
lang: en              # REQUIRED. BCP-47 — e.g. en, fr, pl, en-US.
description: Optional one-paragraph description.
tags: [tag1, tag2]    # Optional, max 32 entries.
visibility: private   # Optional. One of public | unlisted | private. Defaults to private.
---
```

The most common parser rejection is **missing `lang`** — it's mandatory
and validated against `^[a-z]{2}(-[A-Z]{2})?$`.

## Hard limits

- Max **250 cards per deck**.
- Image URLs must be `https://` (no `http://`, no `data:` URLs).
- `lang` must match `^[a-z]{2}(-[A-Z]{2})?$`.
- `visibility` must be one of `public`, `unlisted`, `private`.

See `../README.md` for the full integration setup, and `../ai-agent-author-prompt.md`
for an LLM-ready system prompt that produces correct decks on the first try.