# flashcards@0.1

**Status:** normative. **Inherits:** [`../conventions.md`](../conventions.md) — envelope,
preservation, safe rendering, and shared diagnostics. It has no items and does not inherit the
shared task model: a card is a prompt with answer content, not a checkbox. **Schema:**
[`schema.json`](schema.json). **Fixtures:** [`fixtures/`](fixtures/). **Owns diagnostic codes:**
`MDTO1000`–`MDTO1099`.

**Companion skill:** [Authoring and editorial guidance](https://markdownto.ai/specs/flashcards.skill.md) (non-normative).

---

## 1. Purpose

`flashcards@0.1` describes a **study deck**: each level-2 heading is a question and the Markdown
blocks beneath it are the answer revealed when the card flips. The source reads like a compact
study guide; the HTML turns the same bytes into a focused keyboard-friendly review surface.

---

## 2. Grammar

### 2.1 Envelope

```yaml
---
markdownto: flashcards@0.1
title: Systems fundamentals
---
```

Only the shared `title` and `id` frontmatter keys are reserved. Unknown keys are preserved and inert.

### 2.2 Cards

`##` means a **flashcard question**. At least one card is required (`MDTO1000`); the question must
be non-empty (`MDTO1001`) and unique after case-insensitive comparison (`MDTO1002`). One optional
leading `#` title is allowed; every other heading level is `MDTO1003`.

The answer is every block after the question and before the next `##`: paragraphs, lists,
blockquotes, tables, code, and inert HTML source are all preserved through the shared content block
model. Content before the first question is `MDTO1004`, and a question with no answer is `MDTO1005`.

### 2.3 Canonical IR

The IR sits at `result.flashcards`, beside `result.document`. It carries ordered cards; each card
has `question`, source-faithful `answer` blocks, and a source position. The renderer never invents
an answer or persists which side was last visible: flip state is presentation only.

### 2.4 Diagnostics

| Code | Severity | Meaning |
|---|---|---|
| `MDTO1000` | error | Document has no flashcards. |
| `MDTO1001` | error | Question heading is empty. |
| `MDTO1002` | error | Question is duplicated. |
| `MDTO1003` | error | Heading level is invalid. |
| `MDTO1004` | error | Answer content appears before the first question. |
| `MDTO1005` | error | A card has no answer content. |

---

## 3. Rationale

**Why questions are headings.** A deck remains readable in every Markdown viewer and a card keeps
rich, multi-block answers without introducing a delimiter language. `##` has exactly one meaning:
the boundary and front of a card.

**Why there is no remembered score.** Correctness and spaced-repetition scheduling need identity,
history, and conflict rules. Version 0.1 is an honest portable deck and review surface; it does not
hide mutable study history outside the file.

---

## 4. Examples

```markdown
---
markdownto: flashcards@0.1
title: Systems fundamentals
---

## What does idempotent mean?

Repeating the operation has the same effect as performing it once.

## Why use a write-ahead log?

It makes intended changes durable before the main data pages are updated.
```

---

## 5. Verb reference

`flashcards@0.1` owns the vocabulary **review**.

| Verb | Signature | Source edit |
|---|---|---|
| `review` | `mdto flashcards review [--card <n>]` | None. Prints every prompt and answer, or one 1-based card. |

The HTML Flip, Previous, and Next controls change presentation only and never edit Markdown.

### Common flags

`--file <path>` · `--card <n>` · `--json` · `--help`