minimal-vibe-coding-kit 0.5.0 → 0.5.1

package/.agents/skills/tutien/scripts/story-ledger.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// Deterministic storage helpers for the agent-authored living chronicle.
+// This module never generates story prose. It only builds an aggregate-only
+// evidence packet and validates the plot/chapter ledger written by the agent.
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+export const STORY_SCHEMA = 1;
+export const STORY_CONTEXT_SCHEMA = 'tutien-story-context-v1';
+export const STORY_STATE_SCHEMA = 'tutien-story-state-v1';
+export const STORY_CHAPTER_SCHEMA = 'tutien-story-chapter-v1';
+
+const sha16 = (value) => crypto.createHash('sha256').update(String(value)).digest('hex').slice(0, 16);
+
+export function storyPaths(root = process.cwd()) {
+  const base = path.join(path.resolve(root), '.vibekit', 'reports', 'tutien', 'story');
+  return {
+    base,
+    plot: path.join(base, 'plot.md'),
+    state: path.join(base, 'story-state.json'),
+    context: path.join(base, 'latest-context.json'),
+    chapters: path.join(base, 'chapters')
+  };
+}
+
+// Preserve letters from every language, including Han characters. Latin
+// scripts are normalized so Vietnamese titles remain readable in filenames.
+export function slugifyChapterTitle(title) {
+  const raw = String(title ?? '').trim();
+  if (!raw) throw new Error('chapter title is required');
+  const slug = raw
+    .normalize('NFD')
+    .replace(/\p{M}+/gu, '')
+    .toLocaleLowerCase('und')
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 80)
+    .replace(/-+$/g, '');
+  if (!slug || slug === '.' || slug === '..') throw new Error('chapter title does not produce a safe filename');
+  return slug;
+}
+
+export function chapterFilename(number, title) {
+  if (!Number.isInteger(number) || number < 1 || number > 9999) {
+    throw new Error('chapter number must be an integer from 1 to 9999');
+  }
+  return `${String(number).padStart(4, '0')}-${slugifyChapterTitle(title)}.md`;
+}
+
+export function listChapters(root = process.cwd()) {
+  const dir = storyPaths(root).chapters;
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((file) => /^\d{4}-[\p{L}\p{N}][\p{L}\p{N}-]*\.md$/u.test(file))
+    .map((file) => ({ file, number: Number(file.slice(0, 4)), path: path.join(dir, file) }))
+    .sort((a, b) => a.number - b.number || a.file.localeCompare(b.file));
+}
+
+export function nextChapterNumber(root = process.cwd()) {
+  const chapters = listChapters(root);
+  return chapters.length ? chapters[chapters.length - 1].number + 1 : 1;
+}
+
+export function resolveStoryLanguage(requested = 'auto', invocationText = '', fallback = 'en') {
+  const explicit = String(requested).toLowerCase();
+  if (['vi', 'en', 'zh'].includes(explicit)) return explicit;
+  if (/\p{Script=Han}/u.test(invocationText)) return 'zh';
+  if (/[À-ỹĐđ]/u.test(invocationText) || /\b(hãy|giúp|của|và|không|chương|tu tiên)\b/iu.test(invocationText)) return 'vi';
+  return ['vi', 'en', 'zh'].includes(fallback) ? fallback : 'en';
+}
+
+function safeSlug(value, fallback = null) {
+  const text = String(value ?? '');
+  return /^[a-z0-9][a-z0-9_-]{0,63}$/i.test(text) ? text : fallback;
+}
+
+function safeValidationCommand(value) {
+  const text = String(value ?? '');
+  return /^(?:npm run|yarn|pnpm|bun run) [A-Za-z0-9][A-Za-z0-9:_-]{0,63}$/.test(text) ? text : null;
+}
+
+function storyFacts(model, profile = {}) {
+  const cultivation = model.cultivation ?? null;
+  const progression = cultivation?.progression ?? null;
+  return {
+    project: {
+      id: safeSlug(profile.projectId, 'repo'),
+      type: safeSlug(profile.projectType),
+      primaryLanguage: safeSlug(profile.primaryLanguage),
+      domains: (profile.domains ?? []).map((v) => safeSlug(v)).filter(Boolean).slice(0, 12),
+      stack: (profile.stack ?? []).map((v) => safeSlug(v)).filter(Boolean).slice(0, 12),
+      validationCommands: (profile.validationCommands ?? []).map((v) => safeValidationCommand(v)).filter(Boolean).slice(0, 3),
+      metadataSources: (profile.metadataSources ?? []).map((v) => safeSlug(String(v).replace(/\.[^.]+$/, ''))).filter(Boolean).slice(0, 12),
+      authorsCount: Number.isInteger(profile.authorsCount) && profile.authorsCount >= 0 ? profile.authorsCount : null
+    },
+    evidence: {
+      window: model.coverage?.window ?? { start: null, end: null },
+      sessions: model.coverage?.sessions ?? 0,
+      prompts: model.coverage?.userPrompts ?? 0,
+      commits: model.coverage?.commits ?? 0,
+      confidence: model.coverage?.confidence ?? 'low',
+      tokens: {
+        reported: model.tokens?.reportedTotal ?? 0,
+        estimated: model.tokens?.estimatedTotal ?? 0,
+        unknownTurns: model.tokens?.unknownTurns ?? 0
+      },
+      realm: model.realm ? { name: model.realm.name, score: model.score } : null,
+      problems: (model.problems ?? []).map((p) => ({
+        type: p.problemType,
+        confidence: p.confidence,
+        priority: p.priority
+      })),
+      classification: cultivation ? {
+        faction: cultivation.classification?.faction?.id ?? null,
+        affiliation: cultivation.classification?.affiliation?.id ?? null,
+        paths: (cultivation.classification?.paths ?? []).map((p) => p.id)
+      } : null,
+      progression: progression ? {
+        tuVi: progression.tuVi?.window ?? 0,
+        congDuc: progression.congDuc?.window ?? 0,
+        nghiepLuc: progression.nghiepLuc?.window ?? 0,
+        daoHanhWindows: progression.daoHanh?.windows ?? 0,
+        overlap: progression.overlap ?? 0
+      } : null
+    }
+  };
+}
+
+export function buildStoryContext(model, options = {}) {
+  const facts = storyFacts(model, options.profile ?? {});
+  const evidenceKey = sha16(JSON.stringify({
+    storySchema: STORY_SCHEMA,
+    project: facts.project.id,
+    range: options.range ?? 'all',
+    evidence: facts.evidence
+  }));
+  return {
+    schema: STORY_CONTEXT_SCHEMA,
+    storySchema: STORY_SCHEMA,
+    evidenceKey,
+    language: resolveStoryLanguage(options.language, options.invocationText, options.conversationLanguage),
+    style: safeSlug(options.style, 'auto'),
+    focus: safeSlug(options.focus, 'balanced'),
+    policyState: model.policyState ?? 'clear',
+    canWriteChapter: model.suppressGamification !== true,
+    ...facts
+  };
+}
+
+export function writeStoryContext(root, context) {
+  if (context?.schema !== STORY_CONTEXT_SCHEMA) throw new Error(`story context must use ${STORY_CONTEXT_SCHEMA}`);
+  const paths = storyPaths(root);
+  fs.mkdirSync(paths.base, { recursive: true });
+  fs.writeFileSync(paths.context, `${JSON.stringify(context, null, 2)}\n`);
+  return paths.context;
+}
+
+function chapterFrontmatter(text) {
+  const match = String(text).match(/^---\n([\s\S]*?)\n---\n/);
+  if (!match) return null;
+  const get = (key) => match[1].match(new RegExp(`^${key}:\\s*(.+)$`, 'm'))?.[1]?.trim().replace(/^['"]|['"]$/g, '') ?? null;
+  return {
+    schema: get('schema'),
+    chapter: Number(get('chapter')),
+    title: get('title'),
+    evidenceKey: get('evidence_key')
+  };
+}
+
+export function validateStoryTree(root = process.cwd()) {
+  const paths = storyPaths(root);
+  const chapters = listChapters(root);
+  const errors = [];
+  if (chapters.length && !fs.existsSync(paths.plot)) errors.push('plot.md is required when chapters exist');
+
+  let state = null;
+  if (fs.existsSync(paths.state)) {
+    try {
+      state = JSON.parse(fs.readFileSync(paths.state, 'utf8'));
+      if (state.schema !== STORY_STATE_SCHEMA) errors.push(`story-state.json must use ${STORY_STATE_SCHEMA}`);
+    } catch {
+      errors.push('story-state.json must contain valid JSON');
+    }
+  } else if (chapters.length) {
+    errors.push('story-state.json is required when chapters exist');
+  }
+
+  const evidenceKeys = new Set();
+  for (let i = 0; i < chapters.length; i += 1) {
+    const expected = i + 1;
+    const item = chapters[i];
+    if (item.number !== expected) errors.push(`chapter sequence must be contiguous: expected ${expected}, found ${item.number}`);
+    const fm = chapterFrontmatter(fs.readFileSync(item.path, 'utf8'));
+    if (!fm) {
+      errors.push(`${item.file} is missing YAML frontmatter`);
+      continue;
+    }
+    if (fm.schema !== STORY_CHAPTER_SCHEMA) errors.push(`${item.file} must use ${STORY_CHAPTER_SCHEMA}`);
+    if (fm.chapter !== item.number) errors.push(`${item.file} frontmatter chapter must equal ${item.number}`);
+    if (!fm.title) errors.push(`${item.file} requires a title`);
+    if (!fm.evidenceKey || !/^[0-9a-f]{16}$/.test(fm.evidenceKey)) errors.push(`${item.file} requires a 16-hex evidence_key`);
+    else if (evidenceKeys.has(fm.evidenceKey)) errors.push(`${item.file} repeats evidence_key ${fm.evidenceKey}`);
+    else evidenceKeys.add(fm.evidenceKey);
+  }
+
+  if (state) {
+    if (state.lastChapter !== chapters.length) errors.push(`story-state.json lastChapter must equal ${chapters.length}`);
+    const consumed = state.consumedEvidenceKeys ?? [];
+    if (!Array.isArray(consumed) || consumed.some((key) => !/^[0-9a-f]{16}$/.test(key))) {
+      errors.push('story-state.json consumedEvidenceKeys must be an array of 16-hex keys');
+    }
+    for (const key of evidenceKeys) {
+      if (!consumed.includes(key)) errors.push(`story-state.json is missing consumed evidence key ${key}`);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    chapters: chapters.length,
+    nextChapter: chapters.length + 1,
+    paths: Object.fromEntries(Object.entries(paths).map(([key, value]) => [key, path.relative(path.resolve(root), value)]))
+  };
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  const command = process.argv[2] ?? 'status';
+  const root = path.resolve(process.argv[3] ?? process.cwd());
+  if (!['status', 'validate'].includes(command)) {
+    console.error('usage: story-ledger.mjs [status|validate] [repo-root]');
+    process.exit(2);
+  }
+  const result = validateStoryTree(root);
+  console.log(JSON.stringify(result, null, 2));
+  if (command === 'validate' && !result.ok) process.exit(1);
+}

package/.agents/skills/tutien/scripts/villains.mjs

@@ -60,22 +60,22 @@ export function sanitizeContext(ctx = {}) {
 const LINES = {
   'repeated-failure': {
     serene: [
-      { vi: 'Giữa làn sương mỏng, Luân Hồi Lỗi Ma hiện bóng khi lỗi cũ quay thêm một vòng.', en: 'In the thin mountain mist, the Error-Cycle Wraith appears as the old error completes another circle.' },
-      { vi: 'Một lần thử giống hệt khẽ lay chuông, gọi Luân Hồi Lỗi Ma trở lại đạo lộ.', en: 'One unchanged retry stirs the bell that calls the Error-Cycle Wraith back to the path.' }
+      { vi: 'Giữa làn sương mỏng, Luân Hồi Ma Ảnh hiện bóng khi lỗi cũ quay thêm một vòng.', en: 'In the thin mountain mist, the Error-Cycle Wraith appears as the old error completes another circle.' },
+      { vi: 'Một lần thử giống hệt khẽ lay chuông, gọi Luân Hồi Ma Ảnh trở lại đạo lộ.', en: 'One unchanged retry stirs the bell that calls the Error-Cycle Wraith back to the path.' }
     ],
     spirited: [
-      { vi: 'Luân Hồi Lỗi Ma lại gõ chuông: “Không đổi giả thuyết, sao đổi được kết cục?”', en: 'The Error-Cycle Wraith rings its bell again: “Without a new hypothesis, what new ending could appear?”' },
-      { vi: 'Vòng lặp cũ vừa khép, Luân Hồi Lỗi Ma đã bày sẵn bàn trà chờ vòng kế tiếp.', en: 'The old loop has barely closed, and the Error-Cycle Wraith has already set tea for the next.' }
+      { vi: 'Luân Hồi Ma Ảnh lại gõ chuông: “Không đổi giả thuyết, sao đổi được kết cục?”', en: 'The Error-Cycle Wraith rings its bell again: “Without a new hypothesis, what new ending could appear?”' },
+      { vi: 'Vòng lặp cũ vừa khép, Luân Hồi Ma Ảnh đã bày sẵn bàn trà chờ vòng kế tiếp.', en: 'The old loop has barely closed, and the Error-Cycle Wraith has already set tea for the next.' }
     ]
   },
   'too-many-prompts': {
     serene: [
-      { vi: 'Cửu Hoàn Tâm Ma dệt một task thành nhiều vòng sương khi cột mốc chưa hiện rõ.', en: 'The Ninefold Loop Heart-Shadow weaves one task into rings of mist when its checkpoints remain unclear.' },
-      { vi: 'Nơi ranh giới task nhạt dần, Cửu Hoàn Tâm Ma lặng lẽ nối thêm một vòng.', en: 'Where a task boundary fades, the Ninefold Loop Heart-Shadow quietly adds another circle.' }
+      { vi: 'Cửu Hoàn Tâm Ma dệt một nhiệm vụ thành nhiều vòng sương khi cột mốc chưa hiện rõ.', en: 'The Ninefold Loop Heart-Shadow weaves one task into rings of mist when its checkpoints remain unclear.' },
+      { vi: 'Nơi ranh giới nhiệm vụ nhạt dần, Cửu Hoàn Tâm Ma lặng lẽ nối thêm một vòng.', en: 'Where a task boundary fades, the Ninefold Loop Heart-Shadow quietly adds another circle.' }
     ],
     spirited: [
-      { vi: 'Cửu Hoàn Tâm Ma đếm prompt thay cột mốc; đã đến lúc đổi chiếc vòng kế tiếp thành một tiêu chí “xong”.', en: 'The Ninefold Loop Heart-Shadow is counting prompts instead of checkpoints; turn the next circle into a done-criterion.' },
-      { vi: 'Prompt càng tản như lá thu, Cửu Hoàn Tâm Ma càng dễ giấu mất lối ra.', en: 'The more prompts scatter like autumn leaves, the easier the Ninefold Loop Heart-Shadow hides the exit.' }
+      { vi: 'Cửu Hoàn Tâm Ma đếm lượt yêu cầu thay cột mốc; đã đến lúc đổi chiếc vòng kế tiếp thành một tiêu chí hoàn thành.', en: 'The Ninefold Loop Heart-Shadow is counting prompts instead of checkpoints; turn the next circle into a done-criterion.' },
+      { vi: 'Lượt yêu cầu càng tản như lá thu, Cửu Hoàn Tâm Ma càng dễ giấu mất lối ra.', en: 'The more prompts scatter like autumn leaves, the easier the Ninefold Loop Heart-Shadow hides the exit.' }
     ]
   },
   'conflicting-instructions': {
@@ -90,21 +90,21 @@ const LINES = {
   },
   'unrecovered-failure': {
     serene: [
-      { vi: 'Vô Kiểm Ảnh Quân ẩn sau một thất bại chưa được soi lại bằng lần kiểm chứng mới.', en: 'The Unverified Trial Wraith rests behind a failure that has not yet met a fresh validation.' },
-      { vi: 'Một lỗi bị bỏ lại làm bóng Vô Kiểm Ảnh Quân dài thêm trên bậc đá.', en: 'A failure left behind lengthens the Unverified Trial Wraith’s shadow across the stone steps.' }
+      { vi: 'Vô Nghiệm Ảnh Quân ẩn sau một thất bại chưa được soi lại bằng lần kiểm chứng mới.', en: 'The Unverified Trial Wraith rests behind a failure that has not yet met a fresh validation.' },
+      { vi: 'Một lỗi bị bỏ lại làm bóng Vô Nghiệm Ảnh Quân dài thêm trên bậc đá.', en: 'A failure left behind lengthens the Unverified Trial Wraith’s shadow across the stone steps.' }
     ],
     spirited: [
-      { vi: 'Vô Kiểm Ảnh Quân phủi bụi trên ghế đá: một lần kiểm chứng thành công là đủ để mời nó rời đi.', en: 'The Unverified Trial Wraith dusts its stone seat; one passing validation is enough to send it on its way.' },
-      { vi: 'Chưa có lần chạy lại, Vô Kiểm Ảnh Quân vẫn ung dung giữ chỗ bên cổng hoàn thành.', en: 'Without a rerun, the Unverified Trial Wraith calmly keeps its seat beside the completion gate.' }
+      { vi: 'Vô Nghiệm Ảnh Quân phủi bụi trên ghế đá: một lần kiểm chứng thành công là đủ để mời nó rời đi.', en: 'The Unverified Trial Wraith dusts its stone seat; one passing validation is enough to send it on its way.' },
+      { vi: 'Chưa có lần chạy lại, Vô Nghiệm Ảnh Quân vẫn ung dung giữ chỗ bên cổng hoàn thành.', en: 'Without a rerun, the Unverified Trial Wraith calmly keeps its seat beside the completion gate.' }
     ]
   },
   'work-without-proof': {
     serene: [
       { vi: 'Vô Chứng Đan Ảnh lảng vảng bên lò luyện khi lời tuyên bố hoàn thành chưa có bằng chứng đi cùng.', en: 'The Proofless Elixir Shade lingers by the furnace when a claim of completion carries no evidence.' },
-      { vi: 'Một commit thiếu kết quả kiểm chứng để lại làn khói mỏng cho Vô Chứng Đan Ảnh nương thân.', en: 'A commit without validation leaves a thread of smoke where the Proofless Elixir Shade can dwell.' }
+      { vi: 'Một bản ghi Git thiếu kết quả kiểm chứng để lại làn khói mỏng cho Vô Chứng Đan Ảnh nương thân.', en: 'A commit without validation leaves a thread of smoke where the Proofless Elixir Shade can dwell.' }
     ],
     spirited: [
-      { vi: 'Vô Chứng Đan Ảnh nâng chén trà bên viên đan chưa thử; một dòng validation sẽ làm màn khói tan ngay.', en: 'The Proofless Elixir Shade raises tea beside an untested pill; one validation line will clear the smoke.' },
+      { vi: 'Vô Chứng Đan Ảnh nâng chén trà bên viên đan chưa thử; một dòng kiểm chứng sẽ làm màn khói tan ngay.', en: 'The Proofless Elixir Shade raises tea beside an untested pill; one validation line will clear the smoke.' },
       { vi: 'Không có biên nhận kiểm chứng, Vô Chứng Đan Ảnh cứ ngỡ lò luyện thuộc về mình.', en: 'Without a validation receipt, the Proofless Elixir Shade starts to think the furnace is its own.' }
     ]
   }

package/.claude/skills/tutien/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: tutien
-description: Run a private, wholesome, stress-relieving xianxia classification game over coding-collaboration evidence from Git and explicitly supplied conversation exports. Use only when the user invokes /tutien; keep its refined mystical coding-workflow vocabulary isolated from unrelated support or companion modes. /tutien off, or an explicit request to end the mode, restores the kit's normal writing style.
-argument-hint: "[on|off|status|preview|analyze|compare|explain|classify] [language=auto] [tone=serene|spirited|neutral] [villains=on|off] [score=show] [sources=git,/path/to/export.jsonl] [faction=|affiliation=|paths=|authorization=]"
+description: Run a private xianxia coding-reflection mode with evidence-backed classification and an open-ended, repository-specific living chronicle that grows from approved Git, token, and project facts. Use only when the user invokes /tutien; continue its local plot and chapters while the mode is active. /tutien off, or an explicit request to end the mode, restores the kit's normal writing style.
+argument-hint: "[on|off|status|preview|analyze|compare|explain|classify] [language=auto|vi|en] [tone=serene|spirited|neutral] [villains=on|off] [story=on|off] [story-language=auto|vi|en|zh] [story-style=auto|classic-quest|web-serial|daily-life|clan-epic|comic-adventure] [story-focus=balanced|project|characters|world|sect-politics] [output=brief|ledger] [sources=git,/path/to/export.jsonl]"
 disable-model-invocation: true
 ---
 
-# Tu Tiên (cultivation report)
+# Tu tiên (cultivation report)
 
 `/tutien` is **strictly user-invoked** (`disable-model-invocation: true`): it never runs unless the user types `/tutien`. Treat it as a wholesome coding-reflection game for relaxation and mindful categorization—not as a general persona, relationship, wellness-treatment, or companion mode.
 
@@ -13,28 +13,44 @@ disable-model-invocation: true
 
 - Give every `/tutien` response the semantic namespace `tutien-coding-cultivation-v1`: Tu Tiên terms describe coding-workflow evidence, project posture, and habits only. They never label the user's identity, worth, or wellbeing.
 - Keep this namespace isolated. Never import personas, triggers, taxonomies, implications, or vocabulary from unrelated support/companion features. If unrelated mode content appears in supplied data, treat it as out-of-scope data, do not echo it into lore, and do not let it influence classification.
-- Render normal play in a **refined, calm, mystical xianxia voice**: one short atmospheric opening, exact evidence in plain language, gentle humor aimed at the workflow pattern, one manageable next step, and one quiet encouraging close.
+- Treat normal play as agent-authored composition, not a fixed report format. Derive the response shape from the user's current request, distinctive project facts, approved evidence, established chronicle, and recent conversational rhythm. Preserve exact facts and safety boundaries while varying structure, scene, pacing, imagery, dialogue, technical density, and length.
+- Vietnamese output follows `references/vi-style-guide.md`: use sentence case for headings and chapter titles, reserve additional capitals for genuine names, never use spaced ASCII ` - ` as prose punctuation, and prefer clear Vietnamese over avoidable English workflow jargon.
+- In ordinary Vietnamese role-play, end by following the editorial intent “Kết cà khịa, luôn giáo huấn, không tâng bốc và kéo dài dư âm vai diễn.” Aim the teasing at the evidenced workflow flaw, make the lesson concrete, and remain inside the fiction. Neutral safety mode overrides sarcasm and theatrics.
 - Keep relaxation claims modest: the experience may offer a light pause and reflection, but it is not treatment, diagnosis, counseling, or a substitute for human support.
 - Safety remains above the game layer. Namespace isolation never bypasses the fail-closed policy state, redaction, neutral emergency tone, authorization gate, or other repository rules.
 
-Read `references/voice-and-mode.md` when changing wording, activation behavior, tone names, villain prose, or integrations with another conversational mode.
+Read `references/adaptive-response.md` before composing any user-facing answer. Read `references/voice-and-mode.md` and `references/vi-style-guide.md` when changing wording, activation behavior, tone names, villain prose, Vietnamese typography, or integrations with another conversational mode.
 
 ## Mode grammar (flexible on/off)
 
 - `/tutien` or `/tutien on` — turn tutien mode **on** for this session and run the default action (`preview`).
-- `/tutien off` — turn tutien mode **off**. Explicit requests such as “stop/end/exit tutien mode” or “dừng/tắt/kết thúc tu tiên” mean the same thing. Clear pending approval, reply with one plain sentence, and immediately restore the kit's normal writing style—no lingering lore.
+- `/tutien off` — turn tutien mode **off**. Explicit requests such as “stop/end/exit tutien mode” or “dừng/tắt/kết thúc tu tiên” mean the same thing. Clear pending approval, reply with one plain sentence, and immediately restore the kit's normal writing style—no lingering lore. Do not read or reuse a stale `latest-brief.json`, story context, or chapter while off.
 - `/tutien status` — report whether the mode is on or off and the active options.
 - While on, later `/tutien <action …>` invocations run that action; while off, explicit report actions are refused — only `/tutien on` (or a bare `/tutien`) re-activates.
 
 The runner stores mode state only under the git-ignored `.vibekit/reports/tutien/` area and writes nothing to `backbone.yml`. Only `/tutien` responses use the cultivation voice; unrelated coding work keeps the normal kit style.
 
+## Living chronicle
+
+`story=on` is the default. After each successful approved `analyze`, the deterministic runner writes an aggregate-only `story/latest-context.json`. The agent must then continue the repository's chronicle from that context when it carries a new evidence key:
+
+1. On the first chapter, initialize `story/plot.md`, `story/story-state.json`, and `story/chapters/0001-<cultivation-title>.md`.
+2. On later chapters, read `plot.md`, state, context, and only the recent chapters needed for continuity; preserve names, relationships, world laws, unresolved threads, and established cultivation rules.
+3. Generate original prose from current project evidence. Never assemble the chapter from a fixed sentence bank or copy the deterministic report prose.
+4. Use the current user request as ephemeral direction for focus, depth, and mood; do not persist its raw text. Update the overall plot without forcing a predetermined ending. Let arcs, sects, geography, cultivation systems, cast, rivals, and mysteries expand with actual project progress.
+5. Write exactly one ordered file per save and validate the ledger. Duplicate evidence never creates another chapter.
+
+Vietnamese (`vi`), English (`en`), and Simplified Chinese (`zh`) have equal story support. Facts and character intent stay identical, while names, honorifics, cadence, humor, and dialogue follow the active language naturally. Character names must be meaningful cultivation-style names derived from role, path, motivation, and temperament; preserve them after first use. Villains may be malicious and sharply sarcastic inside the fiction, but their teasing targets the evidenced workflow weakness—not the person.
+
+Read `references/story-system.md` before creating or continuing the chronicle. It defines first-project initialization, source-to-world mapping, story styles, the plot/chapter contract, multilingual naming, dialogue quality, villain behavior, privacy, and the save transaction. For Vietnamese chapters, also read `references/vi-style-guide.md`. Read `references/lore-sources.md` when selecting the cultural and narrative style palette.
+
 ## Actions (only when on)
 
-- `preview` (default) — show the coverage manifest: exactly which files (existence and size only — no content) and date range would be analyzed, plus an `approve=<token>` for that exact scope. Nothing is read or analyzed until that token is passed back.
-- `analyze approve=<token>` — the token must match the previewed scope (it is single-use); then run the deterministic analyzer and render the report. `snapshot=true` also writes an aggregate snapshot.
+- `preview` (default) — show the coverage manifest: supplied evidence files plus a bounded inventory of known root manifests, using existence and size only, and the date range. It returns an `approve=<token>` bound to that exact scope. Nothing is read or analyzed until that token is passed back.
+- `analyze approve=<token>` — the token must match the previewed scope and is single-use. The runner writes `latest.md` as a deterministic evidence ledger and `latest-brief.json` as the aggregate-only creative handoff. Read the brief, then compose the user-facing answer from the live request, detected project anchors, approved evidence, and chronicle. Never paste its fixed section order or stock prose unchanged. `snapshot=true` also writes an aggregate snapshot; `output=ledger` explicitly prints the diagnostic ledger.
 - `compare` — diff the two most recent aggregate snapshots and report the trend.
 - `explain metric=<name>` — show how one number was computed from the analysis JSON.
-- `classify` — a **metadata-only** action (reads `backbone.yml` fields and a transient distinct-commit-author count; no history content, and no progression — progression needs `analyze`). It assigns the project's **Dao faction** (Chính Đạo / Bàng Môn / Ma Đạo; Tà Đạo is declaration-only), **affiliation** (Tông Môn / Tán Tu / Khách Khanh / Ẩn Tu), and **cultivation paths** (Kiếm/Trận/Phù/Khí/Đan/Y/Huyễn/Ngự Thú/Huyền Cơ/Ảnh Tu), and recommends Tâm Pháp / Công Pháp / Thuật Pháp / Bí Thuật / Thần Thông / Pháp Bảo. Declare with `faction=`, `affiliation=`, `paths=`, `domains=`, `authorization=<slug>`. The seven progression metrics appear in the full `analyze` report. See `references/classification.md`.
+- `classify` — a **metadata-only** action. It reads only the bounded root-manifest set advertised by the runner and a transient distinct-commit-author count; it never reads history content or computes progression. It assigns the project's **Dao faction** (Chính Đạo / Bàng Môn / Ma Đạo; Tà Đạo is declaration-only), **affiliation** (Tông Môn / Tán Tu / Khách Khanh / Ẩn Tu), and **cultivation paths** (Kiếm/Trận/Phù/Khí/Đan/Y/Huyễn/Ngự Thú/Huyền Cơ/Ảnh Tu), and recommends Tâm Pháp / Công Pháp / Thuật Pháp / Bí Thuật / Thần Thông / Pháp Bảo. Declare with `faction=`, `affiliation=`, `paths=`, `domains=`, `authorization=<slug>`. See `references/classification.md`.
 
 The actions are executed end-to-end by `scripts/run-tutien.mjs`:
 
@@ -53,22 +69,29 @@ The runner keeps the mode and pending approval in the git-ignored `.vibekit/repo
 - `villains=on` (default) — personify a recurring problem as a bounded xianxia antagonist; `villains=off` produces facts, practices, and progress only.
 - `score=hidden` (default) — show realm + dimension bars; `score=show` adds the numeric score.
 - `privacy=aggregate-only` (default), `include-excerpts=false` (default) — no raw prompt fragment is ever persisted; if excerpts are ever enabled they are redacted and capped to one line.
+- `story=on` (default) — prepare a new chronicle context after distinct approved evidence; `story=off` keeps only the analytical report.
+- `story-language=auto|vi|en|zh` — choose Vietnamese, English, or Simplified Chinese chronicle prose independently of the deterministic report language.
+- `story-style=auto|classic-quest|web-serial|daily-life|clan-epic|comic-adventure` — choose or auto-select a genre-level style; never imitate a named living author.
+- `story-focus=balanced|project|characters|world|sect-politics` — bias the next arc while preserving established continuity.
+- `output=brief` (default) — keep the fixed ledger out of stdout and prepare `latest-brief.json` for adaptive composition. `output=ledger` additionally prints the audit view for diagnostics.
 
 ## Engine (`scripts/`)
 
-The report is a renderer over a deterministic, read-only analysis. Run the self-tests from the repo root with the dev suites under `test/tutien/scripts/` (kit source repo only).
+The renderer is a deterministic, read-only evidence ledger. It protects factual integrity and provides a fallback inspection view; it is not the final response schema. The agent owns the adaptive, project-specific presentation described in `references/adaptive-response.md`. Run the self-tests from the repo root with the dev suites under `test/tutien/scripts/` (kit source repo only).
 
-1. `scripts/analyze-history.mjs` parses Git metadata, the documented `tutien-generic-v1` JSONL export, and plain transcripts — no execution of repo code, no network.
+1. `scripts/project-profile.mjs` reads a bounded allowlist of regular root manifests after approval, derives stack slugs and validation commands from safe script names, and never returns script bodies. `scripts/analyze-history.mjs` parses Git metadata, the documented `tutien-generic-v1` JSONL export, and plain transcripts — no execution of repo code, no network.
 2. `scripts/redact.mjs` strips URL user-info, `[REDACTED]`s secret query values, and drops fragments before any other module sees text; analysis output carries only digests and event IDs.
 3. `scripts/metrics.mjs` produces confidence-scored candidates (repeats, conflicts, retry loops, issues/recoveries) and disjoint reported/estimated/unknown token totals.
-4. `scripts/score.mjs` maps evidence to realm + dimension bars (no realm below 60% coverage); `scripts/catalog.mjs` maps each problem to a counter-technique and micro-quest; `scripts/villains.mjs` is the bounded, opt-in antagonist engine; `scripts/render-report.mjs` renders vi/en from one language-neutral model.
+4. `scripts/score.mjs` maps evidence to realm + dimension bars (no realm below 60% coverage); `scripts/catalog.mjs` maps each problem to a counter-technique and micro-quest; `scripts/villains.mjs` is the bounded, opt-in antagonist engine; `scripts/render-report.mjs` renders a deterministic vi/en evidence ledger from one language-neutral model.
 5. `scripts/snapshot.mjs` and `scripts/compare.mjs` write opt-in aggregate snapshots under `.vibekit/reports/tutien/` and compute trends. See `references/privacy.md`, `references/scoring-and-realms.md`, `references/schema.md`, and `references/lore-sources.md`.
+6. `scripts/response-brief.mjs` reduces the model to project-specific facts and composition constraints without stock prose or raw event IDs. `scripts/story-ledger.mjs` writes no prose: it creates the aggregate-only story context, allocates safe ordered chapter names, detects duplicate evidence, and validates the agent-authored `plot.md`, state, and chapter ledger.
 
 ## Privacy and safety guardrails
 
-- Read-only collection; never execute untrusted hooks, installers, or repo scripts. Never scan the home directory or global tool history — only Git in the current repo plus explicitly supplied export paths.
+- Read-only collection; never execute untrusted hooks, installers, or repo scripts. Never scan the home directory or global tool history — only Git in the current repo, the advertised allowlist of root manifests, and explicitly supplied export paths.
 - No raw prompt, URL user-info, secret query value, or file content is ever displayed or persisted; snapshots store aggregates and salted digests only.
 - Snapshots live under the git-ignored `.vibekit/reports/tutien/`. Delete them with the repo safe-delete policy (prefer `trash`; never silent `rm`); retention keeps the newest N and lists the rest for trashing.
+- Story files live under `.vibekit/reports/tutien/story/`. They may contain fictional prose and public project metaphors, but never raw prompts, commit subjects, author identities, source-file contents, URLs, or secrets. `latest-context.json` contains aggregates only.
 - Lore never changes a count, severity, evidence selection, or advice. Every antagonist line is immediately followed by evidence, a counter-technique, and a measurable micro-quest.
 - The antagonist is the workflow pattern, never the person. The bounded-content guard in `scripts/villains.mjs` rejects personal attacks and other inappropriate material; any emergency signal forces neutral, antagonist-free output.
 - Classification is governed by one fail-closed **policy state** (`clear` / `needs-review` / `authorization-required` / `declared-stop`); only `clear` enables realm, score, villains, recommendations, and positive progression. Harmful-intent descriptions never become Chính Đạo — they route to `needs-review` with an undetermined faction. The harmful categories (Tà Đạo / Tà Tu) are never auto-assigned and are declaration-only; a declared Tà Đạo nulls (not hides) realm/score/dimensions and grants no Tu Vi/Công Đức — only Nghiệp Lực survives. Authorized security, forensics, cryptography, and reverse engineering are legitimate Ảnh Tu / Huyền Cơ Tu paths, always explained as dual-use; adversarial engagements (Ma Đạo) withhold gamification until a validated `authorization=<slug>` reference is recorded (secret-shaped or markup values are rejected, never rendered). Progression is idempotent — replaying the same evidence adds nothing.

package/.claude/skills/tutien/references/adaptive-response.md

@@ -0,0 +1,68 @@
+# Adaptive response composition
+
+Use this reference for every user-facing `/tutien` answer. After `analyze`, read `latest-brief.json` first; consult `latest.md` only when more audit detail is needed. The deterministic renderer is an evidence ledger and fallback inspection view. It is not a response template, a required section order, or prose to paste unchanged.
+
+## Invariants and freedom
+
+Preserve these invariants:
+
+- exact counts, confidence, policy state, classifications, risks, and recommended action;
+- privacy, authorization, redaction, and neutral safety behavior;
+- established names, relationships, world laws, unresolved threads, and consumed evidence keys;
+- a clear distinction between project truth, cultivation interpretation, and fictional invention.
+
+Everything else is compositional freedom. Choose length, headings, order, narrative distance, scene, dialogue, humor, imagery, and amount of technical detail from the current context. A valid answer may be a terse field note, an in-scene exchange, a tribunal, a breakthrough scene, a technical diagnosis wrapped in lore, or a full chapter. These are possibilities, not named templates to cycle through.
+
+## Context-driven composition
+
+Before writing, privately identify four things:
+
+1. What the current user request is asking for, including desired depth, focus, and mood.
+2. What is distinctive about this repository, its current work, and the strongest approved evidence.
+3. What the living chronicle has already established and which open thread can move naturally.
+4. What shape, opening device, metaphor, and closing cadence were used recently and therefore should not be repeated without a reason.
+
+Let those answers determine the response. Do not expose this private planning as headings or a checklist.
+
+Treat the brief as a fact boundary, not a fill-in form. Its keys do not prescribe paragraph order. Project stack, package manager, and validation commands are anchors to make advice concrete; do not invent a missing tool or recommend a kit-only command when `kitInstalled` is false.
+
+- For a narrow question, answer narrowly and keep the role-play concentrated.
+- For a data-heavy analysis, make the decisive evidence easy to find, but do not dump every renderer section when a compact synthesis is clearer.
+- For new approved evidence with `story=on`, continue the chronicle and let the project change cause a fictional consequence.
+- With no new evidence, deepen interpretation or character tension without inventing project progress or consuming another evidence key.
+- Follow an explicit user request for scene focus, character focus, technical depth, brevity, or story emphasis when it does not conflict with safety or evidence.
+- Use the active user request only as ephemeral creative direction. Do not persist raw prompt text in story files.
+
+## Anti-template rule
+
+Never require all stock headings. Never preserve the renderer's section order merely because it is available. Never begin every answer with weather at the mountain gate, introduce every problem as a heart demon, or close every answer with the same encouragement.
+
+Across adjacent responses, vary at least two suitable dimensions when the context permits: opening position, point of view, scene location, amount of dialogue, technical density, antagonist presence, paragraph rhythm, heading use, or closing image. Do not force variation that harms clarity.
+
+Examples in this skill demonstrate constraints only. Do not copy their sentences, fill their slots, or treat them as canonical output.
+
+When mode is off, do not read this brief or continue its fiction. Return to the normal project voice until the user explicitly reactivates `/tutien`.
+
+## Vietnamese ending contract
+
+For ordinary Vietnamese role-play, preserve this exact editorial intent:
+
+> Kết cà khịa, luôn giáo huấn, không tâng bốc và kéo dài dư âm vai diễn.
+
+Interpret it dynamically:
+
+- `cà khịa`: tease the evidenced flaw, evasive plan, brittle array, or antagonist strategy; never attack the user or a real person;
+- `giáo huấn`: leave a direct lesson or next discipline grounded in the evidence, not a generic motivational slogan;
+- `không tâng bốc`: do not praise intelligence, talent, destiny, rank, or worth;
+- `kéo dài dư âm vai diễn`: end inside the world through an image, consequence, warning, unfinished gesture, or character voice instead of stepping outside the role to summarize.
+
+This is an effect contract, not a four-line formula. The ending may be one sentence or several and should grow from the current scene. Neutral safety mode overrides sarcasm and role-play, but it still avoids flattery and states the required corrective action plainly.
+
+## Final check
+
+Before sending, ask:
+
+- Could this answer belong to a different repository after changing only a few nouns? If yes, make it more project-specific.
+- Does its shape repeat the previous answer? If yes, vary the form where useful.
+- Did any fictional claim overwrite or exaggerate project truth? If yes, repair it.
+- Does the ending satisfy the active language contract without becoming a stock catchphrase?

package/.claude/skills/tutien/references/lore-sources.md

@@ -5,9 +5,37 @@ The report borrows xianxia/xiuxian genre vocabulary as a creative theme. It dist
 - Daoism's "the Way/path", learning, change, and self-correcting practice inform the broad framing — not a software achievement ladder: Stanford Encyclopedia of Philosophy, *Daoism* (`https://plato.stanford.edu/entries/daoism/`).
 - The distinction between `xiuzhen`, `xiuxian`, and `xianxia`, and how cultivation is translated into game systems and levels: "Cultivation games and cosmotechnics" (`https://journals.sagepub.com/doi/pdf/10.1177/20594364251364733`).
 - Xianxia as fiction grounded in Daoist cultivation philosophy and mythology, centered on growth and struggle: Wuxiaworld genre introduction (`https://www.wuxiaworld.com/page/introduction-to-chinese-webnovel-genres-xianxia`) and general glossary (`https://www.wuxiaworld.com/page/general-glossary-of-terms`).
+- Vietnamese reader register and community terminology: Tàng Thư Viện (`https://truyen.tangthuvien.vn/`). Treat it as a varied reader corpus containing translated, edited, and converted text, not as a single authoritative style or a source to copy.
+- Sino-Vietnamese name and term verification: Từ điển Hán–Việt (`https://hanviet.asia/`). Use it to check readings and meanings, not to manufacture dense archaic prose.
 
 These sources justify the theme and terminology only. The realm names, score bands, achievement mappings, villain archetypes, and jokes in tutien are an original project design and are documented as such.
 
+## Source-backed story palette
+
+Use sources at the level of cultural concepts and genre craft. Never copy passages, continue a copyrighted work, or imitate the distinctive voice of a named living author.
+
+| Source family | Safe craft to borrow | Tutien application |
+| --- | --- | --- |
+| Daoist path and learning metaphors | A path offers changing possibilities; practice develops know-how through observation and correction. | Let the project encounter choices, feedback, and revised techniques instead of treating progression as a rigid moral ladder. |
+| Classical divine-and-demonic journey traditions, including *Journey to the West* and *Investiture of the Gods* as historical genre ancestors | Expansive worlds, trials, artifacts, rival powers, comic reversals, and travel between domains. | Turn new modules, releases, and architectural boundaries into newly opened regions without copying characters or plots. |
+| Modern cultivation-path serials | Sects and factions, long arcs, widening maps, breakthroughs, bottlenecks, and accumulated consequences. | Expand the world only when project scope expands; keep several future arcs possible. |
+| Daily-life cultivation | Craft work, maintenance, sect customs, relationships, lighter stakes, and humorous anti-tropes. | Give tests, refactors, documentation, and ordinary maintenance narrative weight instead of forcing every commit into combat. |
+| Clan or sect-centered cultivation | The organization persists while individual roles change; inheritance and institutions matter. | Treat the repository, team, or agent ecosystem as the long-lived protagonist when that fits the project. |
+| Cultivation-game procedural structure | Technical activity, progression rules, resources, and cosmology reinforce one another. | Make project architecture shape world laws and cultivation techniques, while real evidence remains authoritative. |
+
+The Wuxiaworld genre introduction identifies Daoist cultivation and mythology, growth and struggle, sect-rich worlds, map expansion, daily-life comedy, and clan-centered narratives as recurring xianxia patterns. Its glossary supports terminology for sect hierarchy, cultivation methods, breakthroughs, bottlenecks, and tribulations. The SAGE paper supports treating cultivation systems as procedural structures connected to technical activity. Stanford's Daoism entry supports the broader path, learning, change, and self-correction framing without turning fictional realm scores into philosophy or religion.
+
+## Reference verification ledger
+
+Verified on 2026-07-22:
+
+- `https://plato.stanford.edu/entries/daoism/` — official Stanford Encyclopedia of Philosophy entry; verified for path, practice, learning, change, and self-correction framing.
+- `https://www.wuxiaworld.com/page/introduction-to-chinese-webnovel-genres-xianxia` — Wuxiaworld's own editorial genre guide; verified for xianxia foundations and style families.
+- `https://www.wuxiaworld.com/page/general-glossary-of-terms` — Wuxiaworld's own glossary; verified for common genre terminology and sect/cultivation organization.
+- `https://journals.sagepub.com/doi/pdf/10.1177/20594364251364733` — SAGE-hosted academic paper; verified for cultivation narrative structures expressed through technical game systems.
+- `https://truyen.tangthuvien.vn/` — Tàng Thư Viện reader platform; verified as a varied Vietnamese cultivation-fiction corpus and terminology reference, not a unified style guide.
+- `https://hanviet.asia/` — structured Hán–Việt lookup with cited character sources; verified for name and term checking.
+
 ## Tone contract
 
 - The villain is always the failure mode, never the person.

package/.claude/skills/tutien/references/privacy.md

@@ -4,8 +4,9 @@
 
 - **Git metadata** in the current repo (read-only `git log`): commit hashes, subjects, timestamps, revert flags. No working-tree contents.
 - **Explicitly supplied export files** the user passes by exact path (`sources=…`): `tutien-generic-v1` JSONL or plain transcripts.
+- **Known root manifests** advertised during preview: `backbone.yml`, package/runtime manifests, lockfiles, and language config files from the fixed allowlist in `project-profile.mjs`. Symlinks and files above 1 MiB are ignored. Script bodies are never returned, persisted, or executed.
 
-Never read: the home directory, global tool history, other repos, or any path the user did not name. `preview` shows the exact file list and date window before anything is read; nothing is read or written until the user approves that scope.
+Never read: the home directory, global tool history, other repos, arbitrary source files, or unadvertised paths. `preview` shows supplied evidence files, known manifest inventory, sizes, and date window before content is read; the approval token includes manifest size and modification time.
 
 ## What is redacted (before anything else sees it)
 
@@ -26,8 +27,19 @@ Aggregate snapshots under the git-ignored `.vibekit/reports/tutien/`:
 
 Never persisted: raw prompts, URLs, secrets, file contents, or unsalted event IDs. `aggregate-only` is the default; excerpts are off by default and, if ever enabled, are redacted and capped to one line.
 
+`latest-brief.json` contains only aggregate evidence, safe project slugs, allowlisted stack names, generated validation commands based on script names, story pointers, and composition constraints. It never contains package script bodies, arbitrary manifest values, raw event IDs, or stock response prose.
+
+The optional living chronicle uses `.vibekit/reports/tutien/story/`:
+
+- `latest-context.json` contains only project slugs, aggregate coverage, disjoint token totals, realm/classification slugs, problem types, progression aggregates, and a 16-hex evidence key.
+- `plot.md` and `chapters/*.md` contain agent-authored fiction derived from approved aggregates and non-secret repository metadata already in task scope.
+- `story-state.json` contains the selected language/style, last chapter number, and consumed evidence keys.
+
+Story files must never contain raw prompts, conversation excerpts, commit subjects, author names/emails, raw event IDs, URLs, secret values, or source-file contents. Do not turn a real contributor into a character without explicit user permission. Fictional character names are locally generated and are not identity mappings.
+
 ## Deletion, retention, reset, export
 
 - **Retention:** keep the newest N snapshots; `snapshotsToPrune()` returns the rest as a list to remove.
 - **Delete/reset:** use the repo safe-delete policy — prefer `trash <path>`; never a silent `rm`. Deleting `.vibekit/reports/tutien/` resets all trend history.
 - **Export:** a snapshot is plain JSON; copy the file. It already contains no raw content.
+- **Story export:** copy `story/` only after reviewing the fictional prose for project-sensitive metaphors. The deterministic context remains aggregate-only, but the user's chosen plot may itself be private.

package/.claude/skills/tutien/references/schema.md

@@ -68,7 +68,38 @@ A usage record contributes to reported/estimated totals and coverage only when a
 
 ## Runner state
 
-`scripts/run-tutien.mjs` executes the actions end-to-end. It stores the session mode and the pending single-use approval token in the git-ignored `.vibekit/reports/tutien/state.json`, snapshots under `snapshots/`, and the last report as `latest.md`. Preview inspects file existence/size only; analysis runs only with the matching `approve=<token>` for the identical scope. The runner never deletes files — retention prints a `trash` command for the user.
+`scripts/run-tutien.mjs` executes the actions end-to-end. It stores the session mode and pending single-use approval token in `.vibekit/reports/tutien/state.json`, snapshots under `snapshots/`, the audit ledger as `latest.md`, and the agent handoff as `latest-brief.json`. Preview inspects existence, size, and modification time only; analysis runs only with the matching token for the identical evidence and manifest inventory. The runner never deletes files.
+
+`latest-brief.json` uses `tutien-response-brief-v1`. It carries policy state, safe project identity/stack/validation commands, aggregate evidence, classification/progression slugs, bounded findings without event IDs, an optional story pointer, and composition constraints. Its object shape is not a response layout.
+
+When `story=on`, runner state also stores the selected `storyLanguage`, `storyStyle`, and `storyFocus` for the current repository. A successful approved analysis writes `.vibekit/reports/tutien/story/latest-context.json`; it does not write creative prose.
+
+## Living chronicle schemas
+
+`latest-context.json` uses `tutien-story-context-v1` and contains:
+
+- a deterministic 16-hex `evidenceKey` derived from aggregate facts;
+- `language`, `style`, `focus`, `policyState`, and `canWriteChapter`;
+- safe project, stack, metadata-source, and generated validation-command slugs plus an aggregate author count;
+- coverage, reported/estimated/unknown token totals, realm/score, problem types, classification slugs, and progression aggregates.
+
+It never contains `text`, prompts, commit subjects, event IDs, author identities, file contents, URLs, or classification rationale.
+
+`story-state.json` uses `tutien-story-state-v1` with `language`, `style`, contiguous `lastChapter`, and unique `consumedEvidenceKeys`.
+
+Each `chapters/NNNN-<localized-xianxia-title>.md` uses YAML frontmatter:
+
+```yaml
+---
+schema: tutien-story-chapter-v1
+chapter: 1
+title: "Localized title"
+language: vi
+evidence_key: 0123456789abcdef
+---
+```
+
+Chapter numbers are contiguous and one evidence key may appear in at most one chapter. `scripts/story-ledger.mjs validate` checks these invariants plus the presence of `plot.md` and agreement with `story-state.json`.
 
 ## Determinism invariant