@qnroa/qtype 0.0.1 → 0.0.3

package/dist/cli/commands/content/lint/action.js

@@ -6,67 +6,61 @@
  *   - Each file parses to at least one Q/A card (error)
  *   - No card contains characters unmapped in the keystroke plan (error)
  */
-import fs from 'node:fs';
-import path from 'node:path';
 import { info, success, error, warn } from '../../../utils/output.js';
 import { ensureQtypeRepo } from '../../../utils/repoGuard.js';
 import { t } from '../../../i18n/index.js';
 import { parseMaterial } from '../../../../core/parser/parseMaterial.js';
+import { walkMaterial, readMaterial, MATERIAL_DIR } from '../../../utils/material.js';
 const TITLE_RE = /^title:\s*(.+)$/m;
 const HEADING_RE = /^#\s+.+$/m;
 export async function contentLintAction(opts = {}) {
     const root = ensureQtypeRepo(opts.path ?? process.cwd());
-    const materialDir = path.join(root, 'material');
     if (!opts.json)
         info(t('content.lint.msg.scanning', { path: root }));
     const issues = [];
     let cardTotal = 0;
     let materialCount = 0;
-    if (fs.existsSync(materialDir)) {
-        for (const name of fs.readdirSync(materialDir).sort()) {
-            if (!name.endsWith('.md'))
-                continue;
-            materialCount++;
-            const rel = path.posix.join('material', name);
-            const src = fs.readFileSync(path.join(materialDir, name), 'utf8');
-            // File-level title (soft): warn if neither frontmatter title nor
-            // a top-level heading is present — the browser view has nothing to
-            // show as the material's name.
-            const head = src.slice(0, 2048);
-            if (!TITLE_RE.test(head) && !HEADING_RE.test(head)) {
-                issues.push({
-                    code: 'material.emptyTitle',
-                    path: rel,
-                    message: t('content.lint.issue.emptyTitle', { path: rel }),
-                });
-            }
-            const material = parseMaterial(src, rel);
-            cardTotal += material.cards.length;
-            if (material.cards.length === 0) {
+    for (const file of walkMaterial(root)) {
+        materialCount++;
+        const rel = `${MATERIAL_DIR}/${file.rel}`;
+        const src = readMaterial(file);
+        // File-level title (soft): warn if neither frontmatter title nor
+        // a top-level heading is present — the browser view has nothing to
+        // show as the material's name.
+        const head = src.slice(0, 2048);
+        if (!TITLE_RE.test(head) && !HEADING_RE.test(head)) {
+            issues.push({
+                code: 'material.emptyTitle',
+                path: rel,
+                message: t('content.lint.issue.emptyTitle', { path: rel }),
+            });
+        }
+        const material = parseMaterial(src, rel);
+        cardTotal += material.cards.length;
+        if (material.cards.length === 0) {
+            issues.push({
+                code: 'material.noCards',
+                path: rel,
+                message: t('content.lint.issue.noCards', { path: rel }),
+            });
+            continue;
+        }
+        material.cards.forEach((c, i) => {
+            if (c.unknownChars.length > 0) {
+                const chars = [...new Set(c.unknownChars)];
                 issues.push({
-                    code: 'material.noCards',
+                    code: 'material.unknownChars',
                     path: rel,
-                    message: t('content.lint.issue.noCards', { path: rel }),
-                });
-                continue;
-            }
-            material.cards.forEach((c, i) => {
-                if (c.unknownChars.length > 0) {
-                    const chars = [...new Set(c.unknownChars)];
-                    issues.push({
-                        code: 'material.unknownChars',
+                    card: i + 1,
+                    chars,
+                    message: t('content.lint.issue.unknownChars', {
                         path: rel,
                         card: i + 1,
-                        chars,
-                        message: t('content.lint.issue.unknownChars', {
-                            path: rel,
-                            card: i + 1,
-                            chars: chars.join(' '),
-                        }),
-                    });
-                }
-            });
-        }
+                        chars: chars.join(' '),
+                    }),
+                });
+            }
+        });
     }
     // `emptyTitle` is treated as a warning (informational). Anything else is an error.
     const errorIssues = issues.filter((i) => i.code !== 'material.emptyTitle');

package/dist/cli/commands/content/search/action.js

@@ -1,56 +1,66 @@
 /**
  * `qtype content search <query>` action — grep-style search over material/*.md.
  *
- * Simple case-insensitive substring match on card questions + answers. Not
- * ranked — just returns first-N hits so a user can pipe grep-style output
- * into vim/less. Deliberately dumb: fits the "types of cards, not a knowledge
- * graph" scope of qtype.
+ * Simple case-insensitive substring match on card questions + answers,
+ * with optional tag / type / limit filters and a --json output mode for
+ * scripting. Not ranked — just returns first-N hits, insertion order.
  */
-import fs from 'node:fs';
-import path from 'node:path';
 import { info, dim } from '../../../utils/output.js';
 import { ensureQtypeRepo } from '../../../utils/repoGuard.js';
 import { t } from '../../../i18n/index.js';
 import { parseMaterial } from '../../../../core/parser/parseMaterial.js';
+import { walkMaterial, readMaterial, MATERIAL_DIR } from '../../../utils/material.js';
 export async function contentSearchAction(query, opts = {}) {
     const root = ensureQtypeRepo(opts.path ?? process.cwd());
-    const materialDir = path.join(root, 'material');
     const limit = opts.limit ?? 20;
+    const tagFilter = opts.tag?.map((t) => t.toLowerCase()) ?? [];
+    const typeFilter = opts.type?.map((t) => t.toLowerCase()) ?? [];
     const q = query.toLowerCase();
     const hits = [];
-    if (fs.existsSync(materialDir)) {
-        outer: for (const name of fs.readdirSync(materialDir).sort()) {
-            if (!name.endsWith('.md'))
+    outer: for (const file of walkMaterial(root)) {
+        const rel = `${MATERIAL_DIR}/${file.rel}`;
+        const src = readMaterial(file);
+        const material = parseMaterial(src, rel);
+        const materialType = material.meta.type?.toLowerCase() ?? 'article';
+        if (typeFilter.length > 0 && !typeFilter.includes(materialType))
+            continue;
+        const materialTags = (material.meta.tags ?? []).map((t) => t.toLowerCase());
+        if (tagFilter.length > 0 &&
+            !tagFilter.every((wanted) => materialTags.includes(wanted))) {
+            continue;
+        }
+        for (let i = 0; i < material.cards.length; i++) {
+            const card = material.cards[i];
+            const question = card.question ?? card.title;
+            const qLc = question.toLowerCase();
+            const aLc = card.answer.toLowerCase();
+            if (!qLc.includes(q) && !aLc.includes(q))
                 continue;
-            const rel = path.posix.join('material', name);
-            const src = fs.readFileSync(path.join(materialDir, name), 'utf8');
-            const material = parseMaterial(src, rel);
-            material.cards.forEach((card, i) => {
-                const qLc = card.question.toLowerCase();
-                const aLc = card.answer.toLowerCase();
-                if (!qLc.includes(q) && !aLc.includes(q))
-                    return;
-                const snippetSrc = qLc.includes(q) ? card.question : card.answer;
-                const idx = snippetSrc.toLowerCase().indexOf(q);
-                const start = Math.max(0, idx - 20);
-                const end = Math.min(snippetSrc.length, idx + q.length + 40);
-                const snippet = (start > 0 ? '…' : '') +
-                    snippetSrc.slice(start, end).replace(/\n+/g, ' ') +
-                    (end < snippetSrc.length ? '…' : '');
-                hits.push({
-                    file: rel,
-                    card: i + 1,
-                    question: card.question,
-                    answer: card.answer,
-                    snippet,
-                });
-                if (hits.length >= limit)
-                    return;
+            const snippetSrc = qLc.includes(q) ? question : card.answer;
+            const idx = snippetSrc.toLowerCase().indexOf(q);
+            const start = Math.max(0, idx - 20);
+            const end = Math.min(snippetSrc.length, idx + q.length + 40);
+            const snippet = (start > 0 ? '…' : '') +
+                snippetSrc.slice(start, end).replace(/\n+/g, ' ') +
+                (end < snippetSrc.length ? '…' : '');
+            hits.push({
+                file: rel,
+                card: i + 1,
+                title: card.title,
+                question,
+                answer: card.answer,
+                snippet,
+                type: material.meta.type,
+                tags: material.meta.tags ?? [],
             });
             if (hits.length >= limit)
                 break outer;
         }
     }
+    if (opts.json) {
+        console.log(JSON.stringify({ query, count: hits.length, hits }, null, 2));
+        return;
+    }
     if (hits.length === 0) {
         info(t('content.search.msg.noResults'));
         return;

package/dist/cli/commands/content/search/i18n.js

@@ -5,6 +5,9 @@ export const messages = {
         'content.search.arg.query': '搜索关键词',
         'content.search.arg.path': '仓库路径（默认当前目录）',
         'content.search.opt.limit': '最多返回结果数（默认 20）',
+        'content.search.opt.tag': '按 tag 过滤 material（可多次；需全部匹配）',
+        'content.search.opt.type': '按 material 类型过滤（可多次指定）',
+        'content.search.opt.json': '以 JSON 输出结果，便于脚本处理',
         'content.search.msg.noResults': '没有找到匹配的结果',
         'content.search.msg.results': '找到 {count} 个结果',
     },
@@ -14,6 +17,9 @@ export const messages = {
         'content.search.arg.query': 'Search query',
         'content.search.arg.path': 'Repo path (default: current directory)',
         'content.search.opt.limit': 'Max results (default: 20)',
+        'content.search.opt.tag': 'Filter by tag (repeatable; all must match)',
+        'content.search.opt.type': 'Filter by material type (repeatable)',
+        'content.search.opt.json': 'Emit results as JSON for scripting',
         'content.search.msg.noResults': 'No results found',
         'content.search.msg.results': 'Found {count} results',
     },

package/dist/cli/commands/content/search/index.js

@@ -17,8 +17,26 @@ export const contentSearchCmd = {
             parser: (v) => parseInt(v, 10),
             defaultValue: 20,
         },
+        {
+            flags: '--tag <tag...>',
+            describe: () => t('content.search.opt.tag'),
+        },
+        {
+            flags: '--type <type...>',
+            describe: () => t('content.search.opt.type'),
+        },
+        {
+            flags: '--json',
+            describe: () => t('content.search.opt.json'),
+        },
     ],
     action: async (query, pathArg, opts) => {
-        await contentSearchAction(query, { path: pathArg, limit: opts.limit });
+        await contentSearchAction(query, {
+            path: pathArg,
+            limit: opts.limit,
+            tag: opts.tag,
+            type: opts.type,
+            json: opts.json,
+        });
     },
 };

package/dist/cli/commands/content/validate/action.js

@@ -11,49 +11,47 @@
  *   - Tag consistency: warns when the same tag is used with different
  *     casing (`react` vs `React`)
  */
-import fs from 'node:fs';
-import path from 'node:path';
 import { info, success, error, warn } from '../../../utils/output.js';
 import { ensureQtypeRepo } from '../../../utils/repoGuard.js';
 import { t } from '../../../i18n/index.js';
 import { parseMaterial } from '../../../../core/parser/parseMaterial.js';
+import { walkMaterial, readMaterial, MATERIAL_DIR } from '../../../utils/material.js';
 export async function contentValidateAction(opts = {}) {
     const root = ensureQtypeRepo(opts.path ?? process.cwd());
-    const materialDir = path.join(root, 'material');
     if (!opts.json)
         info(t('content.validate.msg.validating', { path: root }));
     const errors = [];
     const warnings = [];
     let cardTotal = 0;
-    const files = [];
+    const materials = walkMaterial(root);
     // ── Filename uniqueness (case-insensitive) ──────────────
-    if (fs.existsSync(materialDir)) {
+    // Compares by the full relative path — a file at en/a.md and one
+    // at zh/a.md are NOT a collision (different folders), whereas
+    // a.md and A.md at the same level are.
+    {
         const seen = new Map();
-        for (const name of fs.readdirSync(materialDir).sort()) {
-            if (!name.endsWith('.md'))
-                continue;
-            files.push(name);
-            const key = name.toLowerCase();
+        for (const file of materials) {
+            const key = file.rel.toLowerCase();
             const prior = seen.get(key);
-            if (prior && prior !== name) {
+            if (prior && prior !== file.rel) {
                 errors.push({
                     code: 'duplicate.file',
-                    path: name,
-                    message: t('content.validate.err.duplicateFile', { file: name }),
+                    path: file.rel,
+                    message: t('content.validate.err.duplicateFile', { file: file.rel }),
                     extra: { collidesWith: prior },
                 });
             }
             else {
-                seen.set(key, name);
+                seen.set(key, file.rel);
             }
         }
     }
     // ── Parse every material, then run cross-file checks ────
     const questionIndex = new Map(); // normalized Q → "path#card"
     const tagVariants = new Map(); // lower → { original casings }
-    for (const name of files) {
-        const rel = path.posix.join('material', name);
-        const src = fs.readFileSync(path.join(materialDir, name), 'utf8');
+    for (const file of materials) {
+        const rel = `${MATERIAL_DIR}/${file.rel}`;
+        const src = readMaterial(file);
         const material = parseMaterial(src, rel);
         cardTotal += material.cards.length;
         material.cards.forEach((card, i) => {
@@ -72,8 +70,9 @@ export async function contentValidateAction(opts = {}) {
                     extra: { chars },
                 });
             }
-            // Duplicate card questions across the corpus.
-            const key = card.question.trim().toLowerCase();
+            // Duplicate card titles across the corpus (title stands in as the
+            // card identity — the H1 text uniquely names each card).
+            const key = card.title.trim().toLowerCase();
             if (key.length > 0) {
                 const prior = questionIndex.get(key);
                 const here = `${rel}#${cardIdx}`;
@@ -93,14 +92,16 @@ export async function contentValidateAction(opts = {}) {
                     questionIndex.set(key, here);
                 }
             }
-            // Tag casing consistency.
-            for (const tag of card.meta.tags) {
-                const lower = tag.toLowerCase();
-                const set = tagVariants.get(lower) ?? new Set();
-                set.add(tag);
-                tagVariants.set(lower, set);
-            }
+            // Card-level tag consistency was removed with the frontmatter
+            // simplification — only material-level tags exist now, handled below.
         });
+        // Material-level tag casing consistency.
+        for (const tag of material.meta.tags) {
+            const lower = tag.toLowerCase();
+            const set = tagVariants.get(lower) ?? new Set();
+            set.add(tag);
+            tagVariants.set(lower, set);
+        }
     }
     for (const [lower, variants] of tagVariants) {
         if (variants.size > 1) {
@@ -116,7 +117,7 @@ export async function contentValidateAction(opts = {}) {
     }
     const result = {
         ok: errors.length === 0,
-        stats: { materials: files.length, cards: cardTotal, warnings: warnings.length },
+        stats: { materials: materials.length, cards: cardTotal, warnings: warnings.length },
         errors,
         warnings,
     };

package/dist/cli/commands/index.js

@@ -4,7 +4,6 @@ import { publishCmd } from './publish/index.js';
 import { checkCmd } from './check/index.js';
 import { contentCmd } from './content/index.js';
 import { configCmd } from './config/index.js';
-import { pluginCmd } from './plugin/index.js';
 import { packCmd } from './pack/index.js';
 export const allCommands = [
     initCmd,
@@ -13,7 +12,6 @@ export const allCommands = [
     checkCmd,
     contentCmd,
     packCmd,
-    pluginCmd,
     configCmd,
 ];
-export { initCmd, repoCmd, publishCmd, checkCmd, contentCmd, packCmd, pluginCmd, configCmd, };
+export { initCmd, repoCmd, publishCmd, checkCmd, contentCmd, packCmd, configCmd, };

package/dist/cli/commands/pack/index.js

@@ -9,6 +9,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { t } from '../../i18n/index.js';
 import { error, info, success } from '../../utils/output.js';
+import { MATERIAL_DIR } from '../../utils/material.js';
 import { messages } from './i18n.js';
 const IGNORE = new Set(['dist', 'node_modules', '.git']);
 export const packCmd = {
@@ -21,7 +22,7 @@ export const packCmd = {
     ],
     action: async (opts) => {
         const cwd = process.cwd();
-        if (!fs.existsSync(path.join(cwd, 'material'))) {
+        if (!fs.existsSync(path.join(cwd, MATERIAL_DIR))) {
             error(t('pack.err.noMaterial'));
             process.exitCode = 1;
             return;

package/dist/cli/commands/publish/build/action.js

@@ -20,11 +20,13 @@ import { createRepoKv } from '../../../bootstrap.js';
 import { deriveAesKey, encryptString, DEFAULT_ARGON2_PARAMS, } from '../../../../core/encrypt.js';
 import { verifyPassword } from '../password/action.js';
 import { prerenderMermaid, emptyMermaidPass } from './mermaidPass.js';
+import { parseMaterialFrontmatter } from '../../../../core/parser/frontmatter.js';
+import { walkMaterial, readMaterial, MATERIAL_DIR } from '../../../utils/material.js';
 export async function publishBuildAction(opts = {}) {
     const cwd = opts.path ? path.resolve(opts.path) : process.cwd();
     const outDir = path.resolve(cwd, opts.out ?? 'dist');
     const viewBundle = resolveBundle('dist/view');
-    const materialDir = path.join(cwd, 'material');
+    const materialDir = path.join(cwd, MATERIAL_DIR);
     info(t('publish.build.msg.parsing', { path: cwd }));
     if (!fs.existsSync(viewBundle) ||
         !fs.existsSync(path.join(viewBundle, 'index.html'))) {
@@ -41,12 +43,15 @@ export async function publishBuildAction(opts = {}) {
     const mermaidMode = await resolveMermaidMode(cwd);
     const repoLang = await resolveRepoLang(cwd);
     const materials = [];
-    for (const name of fs.readdirSync(materialDir)) {
-        if (!name.endsWith('.md'))
-            continue;
-        const body = fs.readFileSync(path.join(materialDir, name), 'utf8');
-        const title = readTitle(body) ?? name.replace(/\.md$/, '');
-        materials.push({ name, body, title });
+    for (const file of walkMaterial(cwd)) {
+        const body = readMaterial(file);
+        const filename = file.rel.split('/').pop() ?? file.rel;
+        const title = readTitle(body) ?? filename.replace(/\.md$/, '');
+        const fm = parseMaterialFrontmatter(body).meta;
+        const fallbackType = file.rel.includes('/') ? file.rel.split('/')[0] : '';
+        const type = fm.type ?? fallbackType;
+        const cardCount = countH1(body);
+        materials.push({ name: file.rel, body, title, type, tags: fm.tags, cardCount });
     }
     // Mermaid pre-render — scan all bodies, produce svg + css maps.
     const mermaid = mermaidMode === 'prerender'
@@ -63,19 +68,29 @@ export async function publishBuildAction(opts = {}) {
     // view bundle. Since dev-seed content lives at repo root's examples/
     // (served only by the vite dev middleware, not the bundle), this is a
     // no-op today — kept in case a future build tool ships anything here.
-    const targetMaterial = path.join(outDir, 'material');
+    const targetMaterial = path.join(outDir, MATERIAL_DIR);
     fs.rmSync(targetMaterial, { recursive: true, force: true });
     fs.mkdirSync(targetMaterial, { recursive: true });
     const entries = [];
     for (const m of materials) {
+        const outPath = encryptCtx
+            ? path.join(targetMaterial, `${m.name}.enc.json`)
+            : path.join(targetMaterial, m.name);
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
         if (encryptCtx) {
             const blob = await encryptString(encryptCtx.key, m.body);
-            fs.writeFileSync(path.join(targetMaterial, `${m.name}.enc.json`), JSON.stringify(blob));
+            fs.writeFileSync(outPath, JSON.stringify(blob));
         }
         else {
-            fs.writeFileSync(path.join(targetMaterial, m.name), m.body);
+            fs.writeFileSync(outPath, m.body);
         }
-        entries.push({ file: m.name, title: m.title });
+        entries.push({
+            file: m.name,
+            title: m.title,
+            type: m.type,
+            tags: m.tags,
+            cardCount: m.cardCount,
+        });
     }
     // Mermaid SVG map + CSS: the view fetches these alongside index.json and
     // looks up each fence by its trimmed source when rendering material bodies.
@@ -196,6 +211,19 @@ function readTitle(source) {
     const m = head.match(/^title:\s*(.+)$/m);
     return m ? m[1].trim().replace(/^["']|["']$/g, '') : null;
 }
+/**
+ * Cheap card-count estimator — counts top-level `#` H1 lines in the
+ * body. Enough for the library's "N cards" chip without full markdown
+ * parse. Matches the parser's `splitByH1` semantics.
+ */
+function countH1(source) {
+    let n = 0;
+    for (const line of source.split('\n')) {
+        if (/^#\s+/.test(line))
+            n++;
+    }
+    return n;
+}
 function countCards(materialDir) {
     let n = 0;
     for (const name of fs.readdirSync(materialDir)) {

package/dist/cli/commands/repo/new/action.js

@@ -62,11 +62,30 @@ export async function repoNewAction(opts) {
         fs.writeFileSync(path.join(repoDir, fileName), readTemplate(templatesDir, fileName, vars));
         console.log(`  + ${fileName}`);
     }
-    // 4. Seed material/example.md and empty .gitkeep so the directory exists
-    //    but stays trivially prunable if the user wipes the seed.
+    // 4. Seed one starter per material type + .gitkeep so the directory
+    //    exists but stays trivially prunable if the user wipes the seed.
+    //    Each starter is a valid `qtype check`-clean deck the user can
+    //    copy, rename, and edit. Their image assets ship alongside so the
+    //    demos render out of the box.
     fs.mkdirSync(path.join(repoDir, 'material'), { recursive: true });
-    fs.writeFileSync(path.join(repoDir, 'material', 'example.md'), readTemplate(templatesDir, path.join('material', 'example.md'), vars));
-    console.log(`  + material/example.md`);
+    const starters = [
+        ['word', 'apple.svg'],
+        ['sentence', 'pangram.svg'],
+        ['article', 'sunrise.svg'],
+        ['snippet', 'moon.svg'],
+        ['qa', 'login-flow.svg'],
+        ['code', 'tree.svg'],
+    ];
+    for (const [type, asset] of starters) {
+        const mdRel = path.join('material', `${type}.md`);
+        fs.writeFileSync(path.join(repoDir, mdRel), readTemplate(templatesDir, mdRel, vars));
+        console.log(`  + ${mdRel}`);
+        const assetRel = path.join('material', 'assets', type, asset);
+        const assetDir = path.dirname(path.join(repoDir, assetRel));
+        fs.mkdirSync(assetDir, { recursive: true });
+        fs.writeFileSync(path.join(repoDir, assetRel), readTemplate(templatesDir, assetRel, vars));
+        console.log(`  + ${assetRel}`);
+    }
     fs.writeFileSync(path.join(repoDir, 'material', '.gitkeep'), '');
     console.log(`  + material/.gitkeep`);
     // 5. Write .qtype/config.json with the repo language.

package/dist/cli/commands/repo/new/i18n.js

@@ -16,7 +16,7 @@ export const messages = {
         'repo.new.msg.done': '仓库已建好：{path}',
         'repo.new.msg.nextSteps': '下一步：',
         'repo.new.msg.next.cd': 'cd {name}',
-        'repo.new.msg.next.edit': 'vim material/example.md    # 或添加新的 material/*.md',
+        'repo.new.msg.next.edit': 'ls material/               # 6 种类型的入门模板，改哪个都行',
         'repo.new.msg.next.commit': 'git add -A && git commit  # 首次提交',
         'repo.new.msg.next.gitHint': 'git init                  # 如需版本控制，也可以 qtype repo new --git',
         'repo.new.tpl.defaultDescription': '资料库',
@@ -38,7 +38,7 @@ export const messages = {
         'repo.new.msg.done': 'Repo created: {path}',
         'repo.new.msg.nextSteps': 'Next steps:',
         'repo.new.msg.next.cd': 'cd {name}',
-        'repo.new.msg.next.edit': 'vim material/example.md    # or add new material/*.md',
+        'repo.new.msg.next.edit': 'ls material/               # 6 starter templates, edit any of them',
         'repo.new.msg.next.commit': 'git add -A && git commit  # initial commit',
         'repo.new.msg.next.gitHint': 'git init                  # or re-run with qtype repo new --git',
         'repo.new.tpl.defaultDescription': 'material library',

package/dist/cli/commands/repo/sync/action.js

@@ -16,12 +16,32 @@ function buildSyncPlan() {
         { kind: 'file', target: 'TODO.md', source: 'TODO.md', managed: false },
         { kind: 'file', target: 'index.md', source: 'index.md', managed: false },
         { kind: 'file', target: 'log.md', source: 'log.md', managed: false },
-        {
+        // Starter cards — one per material type. Users copy the one that
+        // matches what they're writing, rename it, edit content, and are
+        // off to the races. Every file is a valid `qtype check`-clean deck
+        // out of the box (the smoke test asserts this).
+        ...['word', 'sentence', 'article', 'snippet', 'qa', 'code'].map((type) => ({
             kind: 'file',
-            target: 'material/example.md',
-            source: path.join('material', 'example.md'),
+            target: `material/${type}.md`,
+            source: path.join('material', `${type}.md`),
             managed: false,
-        },
+        })),
+        // Starter card image assets — SVGs referenced by the starters.
+        // `currentColor`-stroked so they inherit the site's text color and
+        // adapt to dark/light theme without extra work.
+        ...[
+            ['word', 'apple.svg'],
+            ['sentence', 'pangram.svg'],
+            ['article', 'sunrise.svg'],
+            ['snippet', 'moon.svg'],
+            ['qa', 'login-flow.svg'],
+            ['code', 'tree.svg'],
+        ].map(([type, name]) => ({
+            kind: 'file',
+            target: `material/assets/${type}/${name}`,
+            source: path.join('material', 'assets', type, name),
+            managed: false,
+        })),
         // ── Skeleton (create-only, never touched) ───────
         { kind: 'dir', target: '.qtype', managed: false },
         { kind: 'dir', target: 'material', managed: false },

package/dist/cli/commands/repo/templates.js

@@ -9,7 +9,8 @@ import { fileURLToPath } from 'node:url';
  *   ├── en/
  *   │   ├── QTYPE.md  README.md  TODO.md  index.md  log.md
  *   │   └── material/
- *   │       └── example.md
+ *   │       ├── word.md      article.md   qa.md
+ *   │       └── sentence.md  snippet.md   code.md
  *   └── zh/
  *       └── (same files)
  *