@qnroa/qtype 0.0.1

package/templates/en/QTYPE.md

@@ -0,0 +1,618 @@
+# QTYPE — LLM Typing-Practice Card Spec
+
+You maintain a typing-practice card repository. This file defines the **rules** and **operations**. On entering the repo, read this file end-to-end once, then execute by the rules.
+
+qtype is a typing-practice tool driven by Markdown source and typed via the OS keyboard (Chinese IME supported). The user picks topics or drops raw material; the Agent reads, distills, splits into cards, files, and maintains.
+
+The whole document is organized into four modules: **Concepts / Format / Operations / Rules**.
+
+---
+
+## Concepts
+
+### Philosophy
+
+- 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).
+
+### 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) |
+
+### 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
+│   ├── .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
+    ├── .gitkeep
+    ├── YYYY-MM-DD-<slug>.md
+    └── 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.
+
+### 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:
+
+```yaml
+---
+title: <deck title>
+language: <target language ISO code, e.g. en / zh / ja>
+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.
+
+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.
+
+### 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.
+
+### 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
+
+**Word card**
+
+```md
+---
+type: word
+phonetic: /əˈbæn.dən/
+gloss: 抛弃, 放弃
+tags: [gre]
+difficulty: 2
+---
+## Q: abandon
+## A: abandon
+```
+
+**Sentence card**
+
+```md
+---
+type: sentence
+translation: 熟能生巧。
+tags: [idiom]
+difficulty: 3
+---
+## Q: Practice makes perfect.
+## A: Practice makes perfect.
+```
+
+**Normal card**
+
+```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.
+```
+
+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.
+
+### `index.md` format
+
+`index.md` lives at repo root, grouped by tag. It **must** be updated after every ingest / update / quiz-gen.
+
+```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>
+
+| Deck | Cards | Language | Summary | Updated |
+|---|---|---|---|---|
+| [Title 3](material/<file-3>.md) | 40 | mixed | one-line summary | YYYY-MM-DD |
+```
+
+Rules:
+
+- 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.
+
+```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
+
+## [YYYY-MM-DD] cascade | <triggering deck>
+- affected: [Deck X](material/<X>.md), [Deck Y](material/<Y>.md)
+
+## [YYYY-MM-DD] check | N issues, M auto-fixed
+
+## [YYYY-MM-DD] level-up | <merge/split description>
+```
+
+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`.
+
+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).
+
+**Step 2: cut into cards**
+
+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.**
+
+Trigger: the user says "quiz-gen JavaScript closures", "give me 30 GRE high-frequency words", "make a React hooks quiz deck".
+
+**Steps**
+
+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".
+
+**Rules**
+
+- 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.
+
+### Check
+
+**When the user's `qtype check` fails, the Agent fixes.**
+
+Trigger: the user runs `qtype check` (see CLI section) and hands the error list to the Agent.
+
+**Agent handling**:
+
+**Deterministic (auto-fix)**:
+
+- **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.
+
+**Heuristic (report only)**:
+
+- **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.
+
+**Report & log**: give the user a fix report, then append `## [YYYY-MM-DD] check | N issues, M auto-fixed`.
+
+### Level-up
+
+**Restructure a scatter of small decks into a coherent series.**
+
+Trigger: the user says "merge these decks", "split this deck into beginner/advanced", "organize the GRE lists into list 1 / 2 / 3".
+
+**Steps**
+
+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.
+
+**Don't**:
+
+- **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.
+
+---
+
+## 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) |
+
+### Quick reference
+
+**Ingest a source**:
+
+```
+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
+```
+
+**Update a deck**:
+
+```
+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**:
+
+```
+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
+```
+
+**Level-up restructure**:
+
+```
+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
+```
+
+---
+
+## CLI Commands (for the user, not for you)
+
+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.
+
+| 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. |
+
+**Notes**:
+
+- 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.
+
+---
+
+## 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.
+
+**Fatal errors**: the build aborts (no files emitted) if:
+
+- 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`.

package/templates/en/README.md

@@ -0,0 +1,64 @@
+# {{name}}
+
+An LLM-maintained **{{description}}** typing deck, following the [QTYPE spec](./QTYPE.md).
+
+> You pick topics and throw in material. An LLM Agent produces structured Markdown cards. You practice typing; progress stays local.
+
+## Scope
+
+<!-- Use a nested list to define the first- and second-level topics this deck covers, e.g.:
+
+- **English**
+  - GRE vocab: list 1 / list 2 / list 3
+  - High-frequency patterns: conditionals / subjunctive
+- **Frontend**
+  - JavaScript fundamentals
+  - React hooks
+
+`TODO.md`'s "missing / thin coverage / covered" buckets are driven by this section.
+-->
+
+## Layout
+
+```
+{{name}}/
+├── QTYPE.md          # authoring spec (source of truth)
+├── AGENTS.md         # symlink → QTYPE.md (created by qtype init)
+├── CLAUDE.md         # symlink → QTYPE.md (created by qtype init)
+├── GEMINI.md         # symlink → QTYPE.md (created by qtype init)
+├── README.md         # this file (scope maintained by humans)
+├── TODO.md           # gap list (Agent-maintained)
+├── index.md          # global deck index
+├── log.md            # activity log (append-only)
+├── material/            # deck files (one .md per deck)
+│   └── assets/<slug>/
+├── raw/              # (optional) raw material for the Agent to process
+│   └── assets/<slug>/
+└── qtype.config.json # typing / theme / target-speed config
+```
+
+## Common operations (ask the LLM to run these)
+
+| Operation | Trigger | Effect |
+|---|---|---|
+| ingest    | `ingest <path-or-topic>` | read material or generate → create/update deck → append log |
+| quiz-gen  | `generate <N> cards on <topic>` | build a new deck from a topic |
+| update    | `edit <field> in <deck-slug>` | modify an existing deck |
+| cascade   | `cascade check` | after editing one deck, sync related ones |
+| check     | `check` (or run the CLI) | validate card formatting |
+| level-up  | `merge/split <slug>` | reorganize too-small / too-large decks |
+
+Full rules live in [QTYPE.md](./QTYPE.md).
+
+## CLI commands you run yourself
+
+| Command | Effect |
+|---|---|
+| `qtype check` | Validate deck files. **Read-only**, CI-friendly. |
+| `qtype publish build` | Build a static site under `dist/`. |
+| `qtype publish serve` | Preview typing locally. |
+| `qtype pack` | Bundle the entire deck repo into a shareable archive. |
+
+## Typing settings
+
+`qtype.config.json` controls theme, hint mode, target WPM, Tab-key behavior, etc. Defaults are generated on first run.

package/templates/en/TODO.md

@@ -0,0 +1,7 @@
+# TODO
+
+Coverage gaps for this deck repo. Maintained by Agents through the standard operations; you may also edit it by hand.
+
+- [ ] missing
+- [ ] thin coverage
+- [x] covered