@qnroa/qtype 0.0.1 → 0.0.3

package/templates/en/QTYPE.md

@@ -15,604 +15,264 @@ The whole document is organized into four modules: **Concepts / Format / Operati
 - The user picks **topics** or **drops materials**. You **read, distill, cut into cards, file, and maintain**.
 - You are not a Q&A bot — you are the **author of a typing-practice card library**. Every card must be something a real person can actually type.
 - `raw/` is where the user drops source material (optional dir). **Never modify its contents**.
-- Each `.md` file under `material/` is one deck, **fully maintained by you** (except cards marked as hand-edited).
-- Cards are not arbitrary Q&A pairs — they are **strings a human can type on an OS keyboard** (or via Chinese IME).
+- Each `.md` file under `material/` is one material, **fully maintained by you** (except hand-edited cards).
+- Cards are **strings a human can type on an OS keyboard** (or via Chinese IME).
 
 ### Terminology
 
 | Term | Definition |
 |---|---|
-| Repo | A standalone qtype directory (e.g. `my-typing-deck/`) |
-| Deck | A single `.md` file under `material/`, containing many cards |
-| Card | One `## Q:` + `## A:` unit, preceded by a frontmatter block |
-| Tag | Category marker on a card or deck; used for filtering and index grouping |
-| Word card | `type: word`; drills spelling and word form; requires `phonetic` and `gloss` |
-| Sentence card | `type: sentence`; drills continuous typing of a sentence; requires `translation` |
-| Normal card | `type: normal` (default); Q is a prompt, A is the answer; most free-form |
-| Raw material | Source file under `raw/` (optional); used by ingest to derive cards |
-| Log | `log.md`, append-only timeline |
-| Review progress | Local practice progress produced by the Web UI (not the Agent's concern) |
+| Repo | A standalone qtype directory |
+| Material | One `.md` file under `material/`, containing many cards |
+| Card | One `#` H1 with its body |
+| Tag | Material-level classification marker |
+| type | Material's kind, deciding card internal shape: `word` / `sentence` / `article` / `snippet` / `qa` / `code` |
 
 ### Directory Layout
 
 ```
 <repo-root>/
-├── QTYPE.md           # this file (rules and operations; language chosen at repo creation)
-├── AGENTS.md          # symlink → QTYPE.md
-├── CLAUDE.md          # symlink → QTYPE.md
-├── GEMINI.md          # symlink → QTYPE.md
-├── README.md          # repo intro (maintained by human)
-├── TODO.md            # backlog (maintained by todo command)
-├── index.md           # table of contents of all decks, grouped by tag
-├── log.md             # append-only timeline
-├── qtype.config.json  # user-tunable settings (theme, target WPM, hint mode, ...)
-├── material/             # decks you write
+├── QTYPE.md
+├── AGENTS.md, CLAUDE.md, GEMINI.md  # symlinks → QTYPE.md
+├── README.md
+├── TODO.md
+├── index.md
+├── log.md
+├── qtype.config.json
+├── material/
 │   ├── .gitkeep
-│   ├── <slug>.md      # one deck per file
-│   └── assets/        # images / audio referenced by decks
-│       └── <deck-slug>/
-│           └── xxx.png
-└── raw/               # (optional) source materials dropped by the user
+│   ├── <slug>.md
+│   └── assets/<material-slug>/
+└── raw/
     ├── .gitkeep
     ├── YYYY-MM-DD-<slug>.md
-    └── assets/
-        └── <raw-slug>/
+    └── assets/<raw-slug>/
 ```
 
-Rules:
-
-- Under `material/`, all deck files are **flat**. Only one subdirectory is allowed: `assets/` (for images and other binaries referenced by decks).
-- Under `raw/`, all source files are **flat**. Only one subdirectory is allowed: `assets/`.
-- `material/assets/<deck-slug>/` and `raw/assets/<raw-slug>/`: grouped by the owning md file's slug, to avoid global name collisions.
-- **On first operation, sanity-check the skeleton**: the user normally initializes. If the Agent enters a repo and finds `material/` / `index.md` / `log.md` missing, create them by spec. When creating `material/` or `raw/`, drop a `.gitkeep`.
-- `raw/` is optional — if the user never drops materials, don't create it.
-- Only create the directories and files specified here. **Never** create anything outside the rules.
-
 ---
 
 ## Format
 
-### Naming
-
-**Deck filename**
-
-- Path: `material/<slug>.md`.
-- `<slug>`: kebab-case of the topic, lowercase, ASCII letters and hyphens, ≤ 60 chars. For Chinese topics use an English translation or pinyin.
-- On collision, append `-2` / `-3`.
-- Examples: `gre-vocab-list-3.md`, `react-hooks-quiz.md`, `toefl-idioms.md`.
-
-**Raw filename**
-
-- Path: `raw/YYYY-MM-DD-<slug>.md`.
-- `YYYY-MM-DD`: the date the material was collected into this repo.
-- `<slug>`: kebab-case of the source title.
-- Untitled paste: `YYYY-MM-DD-note-<N>.md`.
-
-**Assets naming**
-
-- `material/assets/<deck-slug>/` and `raw/assets/<raw-slug>/`: grouped by the owning file's slug; consistent slug means one directory.
+### Material-level frontmatter
 
-### Links
-
-**Use Markdown links only, never Wikilinks.**
-
-| Context | Path form | Example |
-|---|---|---|
-| Deck references another deck | `./<slug>.md` | `[GRE Frequent](./gre-vocab-list-3.md)` |
-| Deck references a raw file | `../raw/<file>.md` | `[Source](../raw/2026-08-14-mdn-closures.md)` |
-| Deck references image in material/assets | `./assets/<deck-slug>/<file>` | `![Diagram](./assets/react-hooks-quiz/lifecycle.png)` |
-| Deck references image in raw/assets | `../raw/assets/<raw-slug>/<file>` | `![Original](../raw/assets/2026-08-14-mdn-closures/scope.png)` |
-| index.md / log.md reference a deck | From repo root | `material/gre-vocab-list-3.md` |
-
-Rules:
-
-- **Never** use `[[wikilink]]` syntax.
-- **Never** use absolute paths. Every link must start with `./` or `../`.
-- Link targets must actually exist.
-
-### Deck-level frontmatter
-
-Each deck file begins with one YAML frontmatter block describing the whole deck:
+Each material begins with one YAML frontmatter block. **It decides the shape of every card in the file**:
 
 ```yaml
 ---
-title: <deck title>
-language: <target language ISO code, e.g. en / zh / ja>
+title: <material title>
+type: word | sentence | article | snippet | qa | code
 tags: [<tag-1>, <tag-2>]
 created: YYYY-MM-DD
 updated: YYYY-MM-DD
 ---
 ```
 
-Fields:
-
-- `title`: deck title. Human-readable; can contain non-ASCII.
-- `language`: the primary language of the answer text (drives IME hint and input expectations). Common values: `en`, `zh`, `ja`, `mixed`.
-- `tags`: array or space-separated string. At least one; used for grouping in `index.md`.
-- `created` / `updated`: dates. Bump `updated` on any content change.
+- `title`: human-readable
+- `type`: **required**. Decides how every card is parsed and rendered
+- `tags`: array or space-separated
+- `created` / `updated`: dates. Bump `updated` on any content change
 
-Directly after the deck frontmatter comes the first card's own frontmatter (separated by a `---` line). No deck-level body prose — put commentary in README or the index.
+**One material, one type. All cards in a file share the same shape.**
 
-### Card frontmatter
-
-Each card starts with its own frontmatter block. Fields:
-
-| Field | Values | Applies to | Notes |
-|---|---|---|---|
-| `type` | `normal` \| `word` \| `sentence` | All | Default `normal`. |
-| `tags` | Array or space-separated string | Optional | Card-level tags; can overlap with deck tags. |
-| `difficulty` | Integer 1..5 | Optional | 1=trivial, 5=hardest. Default 3. |
-| `hint` | `none` \| `ghost` | Optional | Overrides the global hint mode. Omit = follow global. |
-| `phonetic` | IPA string, `/…/` or `[…]` | Word cards | e.g. `/əˈbæn.dən/`. |
-| `gloss` | Native-language gloss (typically simplified Chinese) | Word cards | e.g. `抛弃, 放弃`. |
-| `translation` | Translation of the sentence | Sentence cards | Meaning-preserving; not word-for-word. |
-
-Rules:
-
-- Word cards **must** have `phonetic` and `gloss`.
-- Sentence cards **must** have `translation`.
-- Normal cards may omit all optional fields.
-- Fields not listed above are not allowed — this keeps the format stable.
+There is **no card-level frontmatter**. All per-card info lives in markdown structure.
 
 ### Card structure
 
-A card consists of frontmatter, a `## Q:` line, and a `## A:` line:
-
-```md
----
-type: word
-phonetic: /əˈbæn.dən/
-gloss: 抛弃, 放弃
-tags: [gre]
-difficulty: 2
----
-## Q: abandon
-## A: abandon
-```
-
-Rules:
-
-- `## Q:` — the prompt. Shown to the user during practice.
-- `## A:` — **the exact text the user is expected to type**.
-- Cards are separated by a blank line + `---` + a blank line (i.e. the start of the next card's frontmatter).
-- The deck frontmatter's closing `---` is followed immediately by the first card's opening frontmatter — no prose between them.
-
-**Answer-text constraints (contents of `## A:`)**:
-
-- Only characters typable via the OS keyboard (including Chinese IME) are allowed. Emojis, zero-width chars, and most exotic Unicode are rejected.
-- Full-width Chinese punctuation is auto-normalized by the tool (smart quotes → straight quotes, em-dash → double hyphen, etc.). Write punctuation naturally.
-- Length **should** stay under 200 characters — longer answers hurt the practice UX. Split into multiple cards.
-- Spaces, newlines (Enter), and Tab characters are allowed. Newlines inside an answer must be real newlines (a blank line would break Markdown parsing — use a soft break or no break).
-
-### Card examples
+**H1 (`#`) splits cards.** Each H1 starts a new card. The next H1 is the next card. **No `---` between cards.**
 
-**Word card**
+**Six card shapes, keyed by material `type`**:
 
-```md
----
-type: word
-phonetic: /əˈbæn.dən/
-gloss: 抛弃, 放弃
-tags: [gre]
-difficulty: 2
----
-## Q: abandon
-## A: abandon
-```
+#### type: word
 
-**Sentence card**
+Word / short phrase. H1 = typing target; H2/H3/H4 are optional annotation slots at fixed positions.
 
 ```md
----
-type: sentence
-translation: 熟能生巧。
-tags: [idiom]
-difficulty: 3
----
-## Q: Practice makes perfect.
-## A: Practice makes perfect.
-```
+# abandon
+## /əˈbæn.dən/
+### to give up, forsake
+#### ![](./assets/vocab/abandon.jpg)
 
-**Normal card**
+# ephemeral
+## /əˈfem(ə)rəl/
+### short-lived
 
-```md
----
-type: normal
-tags: [js, closures]
-difficulty: 4
----
-## Q: What is a closure in JavaScript?
-## A: A function bundled with its lexical scope, letting it access variables from where it was defined.
+# barebones
 ```
 
-For normal cards, the A section is **what the user types**; Q is the prompt. A can be a code snippet, a phrase, a full sentence — subject to the answer-text constraints.
+| Level | Content | Optional |
+|---|---|---|
+| **H1** | Typing target (the word) | Required |
+| **H2** | Phonetic / pinyin | Optional |
+| **H3** | Gloss / definition | Optional |
+| **H4** | Image, in `![](url)` markdown | Optional |
 
-### `index.md` format
+#### type: sentence
 
-`index.md` lives at repo root, grouped by tag. It **must** be updated after every ingest / update / quiz-gen.
+Single sentence. **Same shape as word.** H1 = typing target (full sentence).
 
 ```md
----
-updated: YYYY-MM-DD
----
-
-# Index
-
-## <tag-1>
-
-| Deck | Cards | Language | Summary | Updated |
-|---|---|---|---|---|
-| [Title 1](material/<file-1>.md) | 32 | en | one-line summary | YYYY-MM-DD |
-| [Title 2](material/<file-2>.md) | 25 | zh | one-line summary | YYYY-MM-DD |
-
-## <tag-2>
+# Practice makes perfect.
+### With enough practice you master anything.
 
-| Deck | Cards | Language | Summary | Updated |
-|---|---|---|---|---|
-| [Title 3](material/<file-3>.md) | 40 | mixed | one-line summary | YYYY-MM-DD |
+# The unexamined life is not worth living.
+### Reflect on your life to give it depth.
 ```
 
-Rules:
+#### type: article
 
-- One `##` heading per tag. **A deck can appear under multiple tags** if it has multiple `tags` values — list it in every relevant section.
-- Under each tag, **only one markdown table** — nothing else.
-- Link paths start from the repo root (`index.md` is at the root).
-- Summary ≤ 60 characters; one line describing the deck's topic.
-- `Cards` reflects the actual card count in the deck file.
-
-### `log.md` format
-
-`log.md` lives at repo root, chronologically appended (new entries at the end). **Never delete entries.** Every operation **must** append one entry.
+Prose. **H1 = title (not typed). The body under H1 is the typing target.**
 
 ```md
----
-updated: YYYY-MM-DD
----
-
-# Log
-
-## [YYYY-MM-DD] ingest | <source title or new deck name>
-- created: [Deck A](material/<A>.md) — N cards
-- updated: [Deck B](material/<B>.md) — appended M cards
-
-## [YYYY-MM-DD] quiz-gen | <topic>
-- created: [Deck C](material/<C>.md) — N cards
-
-## [YYYY-MM-DD] update | <deck name>
-- appended: N
-- fixed: M
+# Morning ritual
 
-## [YYYY-MM-DD] cascade | <triggering deck>
-- affected: [Deck X](material/<X>.md), [Deck Y](material/<Y>.md)
+Wake up early. Drink a glass of water. Start typing for ten minutes.
+Consistency beats intensity — that's how habits compound over time.
 
-## [YYYY-MM-DD] check | N issues, M auto-fixed
+# 200-word self-intro
 
-## [YYYY-MM-DD] level-up | <merge/split description>
+Hello, my name is Alice. I'm a software engineer based in Shanghai.
 ```
 
-Rules:
-
-- Every ingest / update / quiz-gen / cascade / check / level-up appends one entry.
-- Heading format: `## [YYYY-MM-DD] <op> | <note>`.
-- Entries are **append-only**; do not delete or modify existing ones.
-- `grep "^## \[" log.md` scans all entries.
-
----
-
-## Operations
-
-### Ingest
-
-**Turn source material into a stack of typable cards.**
-
-Trigger: the user says "ingest <path-or-url>", "make cards from this article", "process this word list".
-
-**Step 1: fetch (drop source into raw/)**
-
-Four cases:
-
-Case A: input is a URL
-- Use whatever web-fetching tool is available; convert to markdown. If none is available, ask the user to paste the content.
-- Save to `raw/YYYY-MM-DD-<slug>.md`.
-- Write frontmatter: `source: <URL>` + `collected: YYYY-MM-DD`.
-
-Case B: input is a local file (`ingest /path/to/wordlist.pdf`)
-- Convert to markdown, copy to `raw/YYYY-MM-DD-<slug>.md`.
-- Write frontmatter: `source: <original path>` + `collected: YYYY-MM-DD`.
-
-Case C: input is pasted text
-- Save to `raw/YYYY-MM-DD-note-<N>.md`.
-- Write frontmatter: `source: pasted text` + `collected: YYYY-MM-DD`.
+Images (`![](url)`) may appear in the body — they render but are **stripped from the typing text**.
 
-Case D: input is a topic description ("give me 20 high-frequency GRE words from memory")
-- **Skip fetch**; go straight to Step 2 (this is the quiz-gen path — see Quiz-gen).
+#### type: snippet
 
-**Step 2: cut into cards**
+Short composition. **Structurally identical to article** (H1 = title, not typed; body below H1 = typing target). The difference is purely visual: snippet renders **vertically centered with centered text alignment**, so it reads like a poster — good for poems, aphorisms, slogans, short standalone passages.
 
-Read the source and split by material type:
-
-- **Word list** → one word card per entry. Grab IPA from the material; if absent, look up an authoritative source; if unknown, leave blank and report in log. Gloss goes in simplified Chinese (or the configured native language).
-- **Sentence / example collection** → one sentence card per line. Translation from the material or a natural translation.
-- **Article / tutorial / code snippet** → extract key points as normal cards. Q is the question, A is a concise answer. Avoid answers > 200 chars — split if longer.
-
-**Step 3: decide which deck it belongs to**
-
-- Scan `material/` for existing decks on the closest topic:
-  - Same topic, existing deck has < 50 cards → append to it.
-  - Same topic, existing deck has ≥ 50 cards → create a follow-on deck (e.g. `gre-vocab-list-4.md`).
-  - No matching deck → create `material/<slug>.md` with a fresh deck frontmatter.
-- **One deck, one topic.** Never mix TypeScript with English vocabulary in one file.
-
-**Step 4: verify typability**
-
-For each new card's `## A:`:
-
-- Scan characters; reject emojis, zero-widths, control chars (except Tab / Enter).
-- Full-width punctuation is auto-normalized by the tool — write naturally.
-- Length > 200 chars → split into multiple cards, giving each Q a different angle.
-- On word cards, A must equal the target word from Q (this drills spelling, not meaning).
-
-**Step 5: update index.md and log.md**
-
-- index.md: add rows for new decks; on appended decks, bump `Cards` and `updated`. See Index format.
-- log.md: append one ingest entry. See Log format.
-
-**Step 6: tell the user**
-
-Briefly report in the conversation what was created / appended / total card count. The user reviews via `git diff` and commits.
-
-**The Agent does not run `git add` / `git commit` / `git push`.**
-
-**Don't**:
-
-- **Don't** "preview and wait for confirmation" — write by the rules directly.
-- **Don't** ingest multiple sources at once — one at a time, so topic judgments don't interfere.
-- **Don't** mix topics in one deck — create more decks instead.
-
-### Update
-
-**Fix or extend an existing deck.**
-
-Trigger: the user says "add a few cards on X to `<deck>`", "fix the IPA on the abandon card in `<deck>`", "merge these cards into `<deck>`".
-
-**Steps**
-
-1. **Read the target deck**: locate cards to change or the position to append.
-2. **Apply changes**:
-   - **Append**: add new cards to the end of the file, following the format.
-   - **Fix**: only touch the specified field or the specified card's Q/A/frontmatter. **Don't touch** anything not asked for.
-   - **Delete**: only when explicitly requested; do not proactively tidy.
-3. **Verify typability**: same as Ingest Step 4.
-4. **Bump the deck frontmatter `updated`**.
-5. **Update index.md** if card count changed.
-6. **Append log.md**: `## [YYYY-MM-DD] update | <deck name>` with counts.
-
-**Don't**:
-
-- **Don't** modify hand-edited cards — see the rules section on `<!-- hand-edited -->`.
-- **Don't** re-tidy sections that weren't asked to be touched.
-- **Don't** rewrite the whole deck unless the user explicitly asks.
-
-### Cascade
-
-**After a big change, check related decks.**
-
-Trigger: automatic when an Ingest or Update involves **many cards** (≥ 10), a **topic-scope change** (e.g. a deck goes from "GRE list" to "GRE + TOEFL mixed"), or **terminology renames**.
-
-**Steps**
-
-1. **Scan index.md**: find decks sharing tags or with related topics.
-2. **Check each one** for:
-   - Terminology consistency — did the new deck adopt a new term the old decks should follow?
-   - Duplicate cards — remove duplicates from whichever deck has the lower quality version.
-   - IPA / gloss / translation conflicts — the same word/sentence should have consistent fields across decks.
-3. **Fix conflicts**: prefer "newer wins" or "higher quality wins". Touch **only** conflicting items — do not retidy.
-4. **Bump `updated` on every deck you touched**.
-5. **Append log.md**: `## [YYYY-MM-DD] cascade | <triggering deck>` with the affected list.
-
-Cascade completes **before the triggering operation returns**, not later.
-
-### Quiz-gen
-
-**Fabricate a stack of cards from a topic description.**
+```md
+# Quiet Night Thought
 
-Trigger: the user says "quiz-gen JavaScript closures", "give me 30 GRE high-frequency words", "make a React hooks quiz deck".
+Bright moonlight before my bed —
+Could it be frost on the ground?
+I lift my head to look at the moon,
+Then lower it, thinking of home.
 
-**Steps**
+# Simplicity is the ultimate sophistication.
 
-1. **Confirm topic and count**: default 25 cards; use whatever count the user specifies.
-2. **Choose card type**:
-   - Vocabulary → mostly word cards.
-   - Sentences for language learning → mostly sentence cards.
-   - Programming / concept knowledge → normal cards (Q is question, A is a short answer).
-3. **Follow Ingest Steps 2–6**: cut cards → decide deck (usually new) → verify typability → update index / log.
-4. **In log, use `quiz-gen` (not `ingest`)** and mark source as "from training memory".
+Attributed to Leonardo da Vinci.
+```
 
-**Rules**
+Pick article vs snippet by tone: paragraphs meant for flow reading with surrounding context → article; short, standalone, needs breathing room → snippet.
 
-- Content must be accurate. If unsure (e.g. IPA of a rare word), leave blank with a note — do not fabricate.
-- One topic, one deck per invocation.
+#### type: qa
 
-### Check
+Q&A. **H1 = card name, `## Q` = prompt, `## A` = typing target.**
 
-**When the user's `qtype check` fails, the Agent fixes.**
+```md
+# Closures
 
-Trigger: the user runs `qtype check` (see CLI section) and hands the error list to the Agent.
+## Q
+What is a closure in JavaScript? Give a practical example.
 
-**Agent handling**:
+## A
+A closure is a function combined with its lexical scope. When the inner function is referenced from outside, its captured variables are kept alive. The classic example is a counter factory.
+```
 
-**Deterministic (auto-fix)**:
+#### type: code
 
-- **Illegal characters** in answer text (emoji / zero-width / control) → strip or drop the card.
-- **Frontmatter errors**: field name misspelled, wrong type, missing required field → fix it.
-- **Word card missing phonetic/gloss, sentence card missing translation** → fill it in (if unknown, place `TODO` and report).
-- **Answer > 200 chars** → split into multiple cards, giving each Q a different angle.
-- **index.md inconsistency**: deck file exists but not in index → add row; card count changed → update.
-- **Broken internal link**: target missing → search `material/` for a same-named file; unique match → repair; otherwise report.
+Coding problem. **Same shape as qa**, with A containing a fenced code block — the code inside is the typing target.
 
-**Heuristic (report only)**:
+````md
+# Two Sum
 
-- **Duplicate cards**: same Q + A across decks. Report; the user decides whether to merge.
-- **Deck too large**: > 100 cards → recommend split.
-- **Deck too small**: < 5 cards → recommend merge.
-- **Orphan deck**: the deck's tag appears only on this one deck in index.md. Might be a new topic, might be miscategorized. Report.
+## Q
+Given `nums` and `target`, return the indices of the two numbers that add up to target.
 
-**Report & log**: give the user a fix report, then append `## [YYYY-MM-DD] check | N issues, M auto-fixed`.
+## A
+```py
+class Solution:
+    def twoSum(self, nums, target):
+        seen = {}
+        for i, x in enumerate(nums):
+            if target - x in seen:
+                return [seen[target - x], i]
+            seen[x] = i
+```
+````
 
-### Level-up
+The code fence's language tag drives Shiki syntax highlighting (`ts` / `py` / `go` / ...).
 
-**Restructure a scatter of small decks into a coherent series.**
+### Universal rules
 
-Trigger: the user says "merge these decks", "split this deck into beginner/advanced", "organize the GRE lists into list 1 / 2 / 3".
+- Authors don't need to remember low-level micro-conventions ("phonetic must be inline code" — none of that). Structure is enough.
+- Typing targets may include spaces, newlines (Enter), Tab
+- Target length **should** stay ≤ 200 chars per card — split longer content
+- Only OS-keyboard-typable characters. Emoji, zero-widths, control chars (except Tab / Enter) are rejected
+- Full-width Chinese punctuation is auto-normalized by the tool
 
-**Steps**
+### Rich rendering (display side, never typed)
 
-1. **Read all involved decks**: full frontmatter + all cards.
-2. **Decide split strategy**:
-   - **Merge**: many small decks → one large deck (by topic, difficulty, or tag).
-   - **Split**: one large deck → several smaller ones (by difficulty tier, by subtopic).
-   - **Reorder**: rearrange cards within a deck — e.g. by ascending `difficulty`, alphabetical, or learning order.
-3. **Write new deck files** using the deck naming rules (e.g. `gre-vocab-list-1.md`).
-4. **Delete or empty old deck files**: post-merge originals get removed; post-split originals get removed. Use `rm` — do not proactively `git rm`.
-5. **Update index.md and log.md**: adjust rows and links; append `## [YYYY-MM-DD] level-up | <description>`.
-6. **Preserve card content**: don't change Q / A / IPA / gloss / translation — level-up is a reorganization, not a content edit. Hand-edited cards (see rules) migrate as-is.
+Display-side slots (`## Q` prompts, article / snippet bodies, gloss) support three kinds of rich content beyond plain markdown:
 
-**Don't**:
+- **Mermaid diagrams**: ` ```mermaid ` fences; `publish build` pre-renders to SVG
+- **Math**: inline `$…$`, block `$$…$$`; KaTeX lazy-loads (~280KB)
+- **Standard markdown**: code blocks, images, bold, italic
 
-- **Don't** modify card content during level-up. Use Update for content changes.
-- **Don't** delete user data on a hunch — if unsure whether an old file should be removed, ask.
+Example — put the equation in `## Q`, keep `## A` typable:
 
+```md
+---
+type: qa
+tags: [math]
 ---
 
-## Rules
-
-### Prohibitions
-
-The following are **strictly forbidden**:
-
-1. **Never modify raw/ contents.** Files under `raw/` are read-only by default. Moving, renaming, or deleting requires explicit user instruction.
-2. **Never write untypable characters.** Emojis, zero-widths, control characters (except Tab and Enter) in an answer are forbidden. If unsure, prefer ASCII or omit.
-3. **Never write over-long answers.** `## A:` should be ≤ 200 characters. Longer → split. Don't make the user type for ten minutes.
-4. **Never mix topics in one deck.** One deck, one topic. TypeScript and English vocabulary do not co-exist in a single file. Create more decks instead.
-5. **Never modify hand-edited cards.** A card whose body contains the HTML comment `<!-- hand-edited -->` is read-only to the Agent. To change it, ask the user first. Cascade skips these.
-6. **Never use Wikilinks.** `[[foo]]` is banned. Use `[text](./path.md)`.
-7. **Never use absolute paths.** All links must be relative, starting with `./` or `../`.
-8. **Never run `git commit` / `push`.** The user decides commits.
-9. **Never create directories outside the rules.** Under `material/`, only flat `.md` files and an `assets/` subdirectory are allowed. Under `raw/`, likewise. Structures like `material/words/` or `material/2026/` are forbidden.
-10. **Never fabricate IPA / gloss / translation.** For uncertain fields, leave them blank and report in log — do not invent.
-
-### Content language
-
-- Deck `title`, `index.md` summaries, `log.md` entries: **primarily the repo language (e.g. Chinese), with technical terms in their original form**.
-- Word card `gloss`: **the native language** (usually simplified Chinese; the repo may specify otherwise).
-- Sentence card `translation`: translation into the user's native language (default simplified Chinese). Meaning-preserving, not word-for-word.
-- The card `## A:` answer text itself: **in the deck's target language**, preserved verbatim from the source (English words stay English, Japanese sentences stay Japanese).
-
-### Card count guidance
-
-- **20–50 cards per deck** is the sweet spot.
-- < 5: too thin — consider merging (Level-up).
-- \> 100: too thick — consider splitting (Level-up).
-- A single Ingest / Quiz-gen usually produces ~25 cards. Beyond that, quality degrades.
-
-### Difficulty scale
-
-`difficulty` semantics (default 3):
-
-| Value | Meaning |
-|---|---|
-| 1 | Trivial recognition, no thought (common words, common-sense facts) |
-| 2 | Read at a glance, no recall needed (common phrases, basic grammar) |
-| 3 | Brief recall required (default, most cards) |
-| 4 | Real thought or a longer answer (concept explanations, sentence composition) |
-| 5 | Hard — long answers or complex concepts (small code snippets, long-sentence dictation) |
+# Gaussian integral
 
-### Quick reference
+## Q
+Evaluate the integral:
 
-**Ingest a source**:
+$$\int_{-\infty}^{\infty} e^{-x^2}\,dx = ?$$
 
-```
-raw/YYYY-MM-DD-<slug>.md          ← write source (flat, optional)
-material/<slug>.md                    ← write or append to deck
-index.md                           ← update row (cards / updated)
-log.md                             ← append ## [date] ingest | title
+## A
+sqrt(pi)
 ```
 
-**Update a deck**:
+**Rendering happens only on the display side. Typing targets (`## A` / word H1 / etc.) still must be plain keyboard-typable text.**
 
-```
-material/<slug>.md                    ← append/fix cards, bump updated
-index.md                           ← update cards & updated
-log.md                             ← append ## [date] update | deck name
-```
-
-**Quiz-gen from a topic**:
-
-```
-material/<slug>.md                    ← create new deck
-index.md                           ← add row
-log.md                             ← append ## [date] quiz-gen | topic
-```
-
-**Check errors reported by user**:
+### Naming
 
-```
-classify errors, auto-fix or report
-auto-fix: chars / frontmatter / length / index consistency
-report only: duplicates / oversized / undersized / orphans
-log.md                             ← append ## [date] check | N issues
-```
+Material files: `material/<slug>.md`
+- kebab-case, ASCII lowercase + hyphens, ≤ 60 chars
+- Chinese topics: use English translation or pinyin
+- Collision: append `-2` / `-3`
 
-**Level-up restructure**:
+### Links
 
-```
-read old decks → decide merge/split/reorder
-write new material/*.md
-rm old files
-index.md                           ← rows added/removed
-log.md                             ← append ## [date] level-up | description
-```
+- **Markdown link syntax only**, no Wikilinks
+- No absolute paths — start with `./` or `../`
+- Targets must actually exist
 
 ---
 
-## CLI Commands (for the user, not for you)
+## Operations
 
-The following commands are run **by the user** in a terminal. Don't try to invoke them; but recognize them when the user reports errors.
+Ingest, Update, Quiz-gen, Cascade, Check, Level-up — semantics as before. Key change: **decide the material's `type` first, then write cards in that shape**.
 
-| Command | Purpose |
-|---|---|
-| `qtype check` | Validate the repo: scans for **untypable characters**, **missing/malformed frontmatter**, **over-long answers**, **index inconsistencies** (fatal) + duplicate cards / oversized / undersized decks (warnings). **Writes no files.** |
-| `qtype publish build` | Build the repo into a static site in `dist/`. |
-| `qtype publish serve` | Local server for the practice UI in the browser. Supports Chinese IME, target-WPM cursor, blind / ghost hint modes. |
-| `qtype publish init --ci github` | Generate a GitHub Actions workflow. |
+### Deciding `type`
 
-**Notes**:
+- Vocabulary, terms → **word**
+- Individual sentences, quotes → **sentence**
+- Paragraphs, essays, poems → **article**
+- Concept questions, interviews → **qa**
+- Coding problems, snippets → **code**
 
-- After ingest / update / quiz-gen, you don't need to run these; CI runs them on commit.
-- User reports "check says card XXX has illegal characters" — locate the card and fix per the Check section.
-- User reports "publish serve won't let me practice this card" — usually A contains untypable chars or exceeds the length cap — fix via Check.
+**One material, one type.** Mixed content → multiple materials.
 
 ---
 
-## Publish output (background only)
-
-`qtype publish build` produces roughly:
-
-```
-dist/
-├── index.html                     ← SPA shell
-├── material/<slug>.html              ← one shell per deck (<noscript> plain-HTML fallback embedded)
-├── _app/                          ← view bundle
-│   └── app.js + chunks/...
-└── _data/
-    └── repo.json                  ← single data snapshot (decks / cards / metadata)
-```
-
-The Web UI supports: Chinese IME input (diffs against the target after commit), three card types (`type: normal | word | sentence`), target-speed cursor, blind / ghost hints, full-width punctuation auto-normalization, space / Enter / Tab characters.
+## Rules
 
-**Fatal errors**: the build aborts (no files emitted) if:
+### Prohibitions
 
-- Any card's answer contains untypable characters.
-- Any card's frontmatter is missing a required field or has a wrong type.
-- Any deck's frontmatter is missing `title` / `language` / `tags`.
-- A word card is missing `phonetic` / `gloss`, or a sentence card is missing `translation`.
+1. **Never modify raw/** — read-only by default
+2. **Never write untypable characters** — emojis, zero-widths, control chars (except Tab & Enter)
+3. **Never write over-long answers** — target text ≤ 200 chars per card; split if longer
+4. **One topic per material** — no mixing
+5. **Never modify hand-edited cards** — cards containing `<!-- hand-edited -->` are read-only to the Agent
+6. **No Wikilinks**
+7. **No absolute paths**
+8. **Never `git commit` / `push`** — the user commits
+9. **No unspec'd directories** — flat `material/` + `assets/` only
+10. **Never fabricate IPA / gloss / translation** — leave blank, report in log
+11. **One `type` per material** — no mixing
+12. **No card-level frontmatter** — per-card info lives in markdown structure