@cloud411716/fancy-webnovel 2.2.0 → 3.0.3

package/plugins/fancy-export/index.js

@@ -0,0 +1,63 @@
+/**
+ * fancy-export：把 SurrealDB 故事图导出成项目根下的中文 Markdown。
+ *
+ * 这个插件只读数据库，不调用 LLM，也不写阶段 JSON。
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { notify } from '#infra';
+import { openStoryGraph } from '../fancy-story-builder/storydb/client.js';
+import { exportStoryGraph } from './exporter.js';
+import { resolveProject } from '../../lib/projects.js';
+
+export const inject = ['commands'];
+
+function helpText() {
+  return `📖 故事导出 用法
+
+/fancy-export                  - 导出当前项目到 <项目目录>/导出
+/fancy-export --project <名字|UUID> - 指定项目
+/fancy-export help             - 显示本帮助`;
+}
+
+function cwdOf(session) {
+  return session && session.header && session.header.cwd ? session.header.cwd : null;
+}
+
+export async function apply(ctx) {
+  ctx.commands.register({
+    name: 'fancy-export',
+    description: '📖 故事导出 ( usage: /fancy-export | help )',
+    input: { hint: '.' },
+    handler: async (invocation) => {
+      const session = invocation.agent.session;
+      const raw = String(invocation.rawInput || '').trim().toLowerCase();
+      if (raw === 'help') return notify(session, 'success', helpText());
+      if (raw && raw !== 'all') {
+        return notify(session, 'error', '不支持的参数：' + raw + '\n\n' + helpText());
+      }
+
+      let project = null;
+      try {
+        project = await resolveProject({ cwd: cwdOf(session) });
+      } catch (err) {
+        return notify(session, 'error', '❌ ' + (err && err.message ? err.message : String(err)));
+      }
+
+      let sdb = null;
+      try {
+        sdb = await openStoryGraph(project.dir, { project });
+        const result = await exportStoryGraph(sdb, project.dir);
+        return notify(session, 'success', [
+          '✅ 已导出到 ' + result.dir,
+          '文件：' + result.files + ' 个 · 细纲：' + result.outlines + ' 章 · 正文：' + result.chapters + ' 章',
+        ].join('\n'));
+      } catch (err) {
+        return notify(session, 'error', '❌ 导出失败：' + (err && err.message ? err.message : String(err)));
+      } finally {
+        if (sdb) await sdb.close();
+      }
+    },
+  });
+}

package/plugins/fancy-import/import-driver.js

@@ -210,10 +210,18 @@ export function flattenQuota(quota) {
 export function buildRoundPrompt(o) {
   const round = o.round;
   const ctx = o.context || {};
+  // 项目根**绝对路径**：读文件、写文件都要用它。
+  //
+  // 为什么必须给绝对路径：LLM 的工作目录未必是项目根。
+  // 用相对路径（`设定/raw/sources/骨架/实体.json`）时，产物会落到
+  // LLM 当前目录下的 `设定/...` 下 —— 插件在项目根下找不到文件，
+  // 只会报一句"文件没有生成"，模型完全不知道自己写歪了。
+  const projectRoot = ctx.projectRoot || '';
+  const abs = (rel) => (projectRoot ? projectRoot + '/' + rel : rel);
   const parts = [];
 
   if (o.contract) {
-    parts.push(o.contract.trim());
+    parts.push(o.contract.trim().replace(/\$\{projectRoot\}/g, projectRoot || '（项目根）'));
     parts.push('');
     parts.push('---');
     parts.push('');
@@ -224,14 +232,16 @@ export function buildRoundPrompt(o) {
 
   parts.push('## 旧稿在哪');
   parts.push('');
-  parts.push('- 正文：`设定/raw/sources/写作/`（第001章.md ~ 第' +
+  parts.push('- 正文：`' + abs('设定/raw/sources/写作/') + '`（第001章.md ~ 第' +
     String(ctx.chapterCount || 0).padStart(3, '0') + '章.md，共 ' + (ctx.chapterCount || 0) + ' 章）');
   if (ctx.settingCount) {
-    parts.push('- 设定资料：`设定/raw/sources/导入资料/`（' + ctx.settingCount + ' 个文件）');
+    parts.push('- 设定资料：`' + abs('设定/raw/sources/导入资料/') + '`（' + ctx.settingCount + ' 个文件）');
   } else {
     parts.push('- 设定资料：没有（旧稿只有正文）');
   }
   parts.push('- **先读这些文件再动笔**，不要凭想象填。');
+  parts.push('- **路径一律用上面给的绝对路径**：你的工作目录未必是项目根，');
+  parts.push('  用相对路径会读不到旧稿、把产物写到别的地方去。');
   parts.push('');
 
   if (ctx.excerpts && ctx.excerpts.length) {
@@ -264,10 +274,11 @@ export function buildRoundPrompt(o) {
   parts.push('## 本轮要写的文件');
   parts.push('');
   for (const f of round.files) {
-    parts.push('- `设定/raw/sources/' + round.dir + '/' + f.name + '`');
+    parts.push('- `' + abs('设定/raw/sources/' + round.dir + '/' + f.name) + '`');
   }
   parts.push('');
   parts.push('**只写上面这几个文件。** 其余阶段的文件本轮不要动。');
+  parts.push('**用上面给的绝对路径写**（目录不存在就先建目录），不要用相对路径。');
   parts.push('');
 
   if (round.id === 'input') {
@@ -301,6 +312,18 @@ export function buildRoundPrompt(o) {
     parts.push('');
   }
 
+  parts.push('## 本轮怎么算完成');
+  parts.push('');
+  parts.push('- 你只管**把上面那几个文件写出来**；内容对不对由插件的校验器判，不用自己跑校验。');
+  parts.push('- 写完后插件会跑校验器。**下一轮派活里没有「上一轮的校验错误」这一节 = 这一轮通过了**。');
+  parts.push('- 下一轮派活里**有**「上一轮的校验错误」= 没通过：按那节里的错误码改');
+  parts.push('  （错误码的含义见上面契约的「四、会被拦下的东西」），**只改错误点名的字段**，');
+  parts.push('  改完**重新写整个文件**（产物是整份覆盖，不是打补丁）。');
+  parts.push('- 派活标题里的「第 N 次尝试」是第几次。同一轮最多试 ' + IMPORT_MAX_ATTEMPTS + ' 次；');
+  parts.push('  第 ' + IMPORT_MAX_ATTEMPTS + ' 次仍未通过，插件会停在这一轮，');
+  parts.push('  并在导入报告里把它列成「未通过」——这时候不要继续自己往下写别的阶段。');
+  parts.push('');
+
   parts.push('## 交活');
   parts.push('');
   parts.push('写完给一段话汇报：本轮写了哪些文件、各写了多少条、哪些内容旧稿里没有（已留空）。');
@@ -558,8 +581,8 @@ export function renderImportReport(o) {
   lines.push('## 五、下一步');
   lines.push('');
   lines.push('1. 修掉上面的待补项（可以直接重新跑 `/fancy-import` 覆盖）。');
-  lines.push('2. 跑 `/fancy-story-builder writing` 让台账与章节对齐（导入只登记旧稿已有的事实）。');
-  lines.push('3. 跑 `/fancy-story-builder deslop` 去掉旧稿里的 AI 味。');
+  lines.push('2. 跑 `/fancy-build write` 让台账与章节对齐（导入只登记旧稿已有的事实）。');
+  lines.push('3. 跑 `/fancy-build deslop` 去掉旧稿里的 AI 味。');
   lines.push('');
 
   return lines.join('\n');

package/plugins/fancy-import/index.js

@@ -266,7 +266,7 @@ function importStamp() {
 export async function apply(ctx) {
   ctx.commands.register({
     name: 'fancy-import',
-    description: '📥 旧稿导入 ( usage: /fancy-import <旧稿目录或文件> )',
+    description: '📥 旧稿导入 ( usage: /fancy-import <旧稿目录或文件> | help )',
     input: {
       hint: '旧稿目录或文件'
     },
@@ -274,11 +274,15 @@ export async function apply(ctx) {
       const session = invocation.agent.session;
       const { signal } = invocation;
 
+      if ((invocation.rawInput || '').trim().toLowerCase() === 'help') {
+        return notify(session, 'success', importTemplates.notify({ type: 'help' }));
+      }
+
       const projectRoot = getProjectRoot(session);
       if (!projectRoot) {
         return notify(session, 'error', importTemplates.notify({
           type: 'no_project_root',
-          err: '会话未提供 cwd'
+          err: '会话未提供当前工作目录'
         }));
       }
 
@@ -290,7 +294,7 @@ export async function apply(ctx) {
       if (!deployedRes.ok || !deployedRes.config) {
         return notify(session, 'error', importTemplates.notify({
           type: deployedRes.reason === 'not_found' ? 'not_initialized' : 'no_source',
-          err: '.fancy-deployed 读不到（' + (deployedRes.reason || '未知') + '）'
+          err: '无法读取 .fancy-deployed（' + (deployedRes.reason || '未知原因') + '）'
         }));
       }
       const deployedConfig = deployedRes.config;
@@ -371,7 +375,11 @@ export async function apply(ctx) {
         chapterCount: scan.chapters.length,
         settingCount: scan.settings.length,
         excerpts: pickExcerpts(scan.chapters),
-        quota: null
+        quota: null,
+        // 项目根绝对路径：派活提示词里的产物路径、模板路径、词表路径都用它。
+        // 少了它，LLM 拿到的还是相对路径，产物会写到 LLM 自己的工作目录里，
+        // 插件在项目根下找不到文件，只会报"文件没有生成"。
+        projectRoot,
       };
 
       const report = await runImportStage({
@@ -726,5 +734,5 @@ export function rhythmInfeasibleReason(T, BC) {
   return '旧稿只有 ' + T + ' 章，达不到骨架阶段的规模要求：' +
     '支线配额 ' + BC + ' 要求区间 [' + lower + ', ' + upper + '] 无解' +
     '（' + feasible + '）。' +
-    '建议把支线数改到上面的可行区间，或改用 /fancy-story-builder 从骨架重新起稿。';
+    '建议把支线数改到上面的可行区间，或改用 /fancy-build 从骨架重新起稿。';
 }

package/plugins/fancy-import/prompts/01-import-prompt.md

@@ -9,6 +9,14 @@
 
 ---
 
+## 〇、路径口径
+
+**项目根的绝对路径：`${projectRoot}`**
+
+本文件与每轮派活里出现的路径都相对于项目根，但**读文件、写文件一律用绝对路径**（`<项目根>/...`）——你的工作目录未必是项目根：用相对路径会读不到旧稿，也会把产物写到别的地方去，插件在项目根下找不到文件，只会回一句"文件没有生成"。
+
+---
+
 ## 一、核心铁律
 
 > 1. **只反推，不创作**。旧稿里没有的人物、势力、地点、伏笔**不许新增**。
@@ -30,16 +38,16 @@
 
 ## 二、产物清单
 
-| 阶段 | 文件 | 落盘路径 |
+| 阶段 | 文件 | 落盘路径（绝对路径） |
 |---|---|---|
-| 骨架 | 实体.json | `设定/raw/sources/骨架/实体.json` |
-| 骨架 | 关系.json | `设定/raw/sources/骨架/关系.json` |
-| 骨架 | 层级.json | `设定/raw/sources/骨架/层级.json` |
-| 血肉 | 角色.json 等 8 个 | `设定/raw/sources/血肉/<名字>.json` |
-| 节奏 | 章节规划.json 等 4 个 | `设定/raw/sources/节奏/<名字>.json` |
-| 写作 | 4 个台账 | `设定/raw/sources/写作/台账/<名字>.json` |
-
-**`骨架/框架.json` 由插件生成，不要写。** 里面的 `quota` 是插件从旧稿实际规模
+| 骨架 | 实体.json | `${projectRoot}/设定/raw/sources/骨架/实体.json` |
+| 骨架 | 关系.json | `${projectRoot}/设定/raw/sources/骨架/关系.json` |
+| 骨架 | 层级.json | `${projectRoot}/设定/raw/sources/骨架/层级.json` |
+| 血肉 | 角色.json 等 8 个 | `${projectRoot}/设定/raw/sources/血肉/<名字>.json` |
+| 节奏 | 章节规划.json 等 4 个 | `${projectRoot}/设定/raw/sources/节奏/<名字>.json` |
+| 写作 | 4 个台账 | `${projectRoot}/设定/raw/sources/写作/台账/<名字>.json` |
+
+**`${projectRoot}/设定/raw/sources/骨架/框架.json` 由插件生成，不要写。**里面的 `quota` 是插件从旧稿实际规模
 反推出来的（推不出来的按公式补齐），你写的实体条数必须和它对得上。
 
 ---
@@ -66,8 +74,8 @@
 ### 3.3 字段与枚举
 
 - 字段结构、id 规则、枚举取值：**以 `模板/` 下对应模板为准**
-  （`模板/骨架/实体模板.json` 等）。
-- 枚举词表（角色类型、冲突类型、伏笔类型…）：**以 `references/glossary.md` 为准**。
+  （`${projectRoot}/模板/骨架/实体模板.json` 等，**用绝对路径读**）。
+- 枚举词表（角色类型、冲突类型、伏笔类型…）：**以 `${projectRoot}/references/glossary.md` 为准**。
   写错枚举值会被校验器拦下。
 
 ---
@@ -81,8 +89,15 @@
 | id 规则 | `ID_FORMAT` / `ID_DUP` | id 不符合 `C001` / `F001` 这类格式，或 id 重复 |
 | 枚举 | `ENUM_INVALID` | 取值不在 glossary 的词表里 |
 | 引用 | `REF_UNKNOWN` | 关系里引用了不存在的 id |
-| 结构 | `DERIVATION_MISSING` | 框架.json 缺推导记录（**这个由插件生成，你不用管**） |
+| 配额 | `QUOTA_MISMATCH` | 条数和 `框架.json` 里的 `quota` 对不上 |
+| 结构 | `DERIVATION_MISSING` | `${projectRoot}/设定/raw/sources/骨架/框架.json` 缺推导记录（**这个由插件生成，你不用管**） |
 | 内容 | `NAME_PLACEHOLDER` / `TEXT_PLACEHOLDER` / `TEXT_TOO_SHORT` / `TEXT_DUPLICATE` | 实体名是"主角1"这类标签、字段是"待补充"这类占位、字段太短、同质化 |
+| 没落盘 | `NO_OUTPUT` | **插件没等到你写文件**：多半是路径写歪了（用了相对路径），也可能是这一轮超时或被中断 |
+| 没落盘 | `READ` | 插件在项目根下没找到本轮要写的文件，或它不是合法 JSON |
+| 校验器 | `VALIDATOR_CRASH` | 校验脚本自己崩了——**不是你的产物有问题**，照原样再交一次即可 |
+
+**什么算这一轮通过**：插件跑完校验器，**没有回任何错误**就是通过。
+下一轮派活里如果带着「上一轮的校验错误」，就是没通过，按第五节处理。
 
 ---
 
@@ -92,10 +107,20 @@
 
 1. **只改错误指向的字段**。错误没提到的部分不要动。
 2. **按 `hint` 的方向改**，不要绕过。
-3. **不要为了通过校验而编造内容**。校验器拦下"实体名是占位名"时，
-   正确做法是**删掉这个编出来的实体**，不是给它起个像样的名字。
+3. **不要为了通过校验而编造内容**。校验器拦下"实体名是占位名"时，正确做法是**删掉这个编出来的实体**，不是给它起个像样的名字。
 4. 改完**重新写整个文件**（产物是整份覆盖，不是打补丁）。
 
+**上面几类特殊错误码另说**：
+
+- `NO_OUTPUT` / `READ`（文件没落盘）→ **先确认你用的是绝对路径**
+  （派活里给的那条 `<项目根>/设定/raw/sources/...`），目录不存在就先建目录，然后把整个文件**重新写一遍**。
+  不要因为"内容我已经想好了"就跳过写文件——
+  没落盘 = 这一轮没做，下一次还会重来。
+- `VALIDATOR_CRASH`（校验器自己崩了）→ 不用改产物，原样重交一次。
+
+**同一轮最多试 3 次**（派活标题里写着"第 N 次尝试"）。
+第 3 次还没通过，插件会停在这一轮并写进导入报告；这时候**不要自己接着往下写别的阶段**，等插件告诉你下一步。
+
 **汇报格式**（每轮完成后给一段话）：
 
 ```

package/plugins/fancy-import/templates.js

@@ -10,26 +10,35 @@ export const importTemplates = {
    */
   notify({ type, err, extra, chapters, files, rounds, failed }) {
     switch (type) {
+      case 'help':
+        return `📥 旧稿导入 用法
+
+/fancy-import <旧稿目录或文件>  导入旧稿并自动切章
+/fancy-import                  默认读取项目内的 旧稿/ 目录
+/fancy-import help             显示本帮助
+
+作用：把旧稿导入到 设定/raw/sources/，并纳入 llm_wiki 项目。`;
+
       case 'no_project_root':
-        return '❌ 无法确定项目目录：' + (err || '会话未提供 cwd') + '。请在项目目录下运行该命令。';
+        return '❌ 无法确定项目目录：' + (err || '会话未提供当前工作目录') + '。请在项目目录下运行该命令。';
 
       case 'not_initialized':
-        return '⚠️ 当前目录尚未初始化，请先运行 /fancy-bootstrap 进行初始化。';
+        return '⚠️ 当前目录不属于已初始化的 fancy-webnovel 工作区。请先运行 /fancy-bootstrap 初始化工作区。';
 
       case 'no_source':
-        return '❌ 导入失败：' + (err || '未知错误');
+        return '❌ 旧稿导入失败：' + (err || '未知错误');
 
       case 'no_source_arg':
         return '⚠️ 请指定要导入的旧稿路径：\n'
           + '/fancy-import <旧稿目录或文件>\n'
-          + '（目录里的 .txt / .md 会被扫描；正文与设定资料自动归类）';
+          + '（目录中的 .txt / .md 文件会被扫描，正文与设定资料将自动归类。）';
 
       case 'deploy_failed':
-        return '❌ 导入阶段文件部署失败：' + (err || '未知错误') + '。请检查磁盘空间与目录权限后重试。';
+        return '❌ 导入阶段文件部署失败：' + (err || '未知错误') + '。请检查磁盘空间和目录权限后重试。';
 
       case 'setup_id_unavailable':
         return '❌ 未能建立 llm-wiki 设定项目：' + (err || '未知原因') +
-          '\n导入的产物要落在「设定」目录下才会被纳管，请先按提示处理 llm-wiki 配置。';
+          '\n导入产物必须位于「设定」目录下才会被纳管。请先按提示完成 llm-wiki 配置。';
 
       case 'import_done':
         return '✅ 导入完成：' + chapters + ' 章旧稿已转成 story-builder 格式，' +
@@ -38,8 +47,8 @@ export const importTemplates = {
           (extra ? '\n\n' + extra : '');
 
       case 'import_incomplete':
-        return '⚠️ 导入完成，但有 ' + (failed || 0) + ' 轮反推未通过校验。' +
-          '**导入的产物目前不完整**，待补清单见 `导入报告/导入报告.md`。' +
+        return '⚠️ 旧稿导入已完成，但有 ' + (failed || 0) + ' 轮反推未通过校验。' +
+          '**当前导入产物不完整**，待补清单见 `导入报告/导入报告.md`。' +
           (extra ? '\n\n' + extra : '');
 
       default:

package/plugins/fancy-material/exporter.js

@@ -0,0 +1,153 @@
+/**
+ * Material library Markdown export for atomic blocks.
+ *
+ * Every record is one small block (name + tags + genres + optional note), so
+ * the export is deliberately terse:
+ *
+ *   ## 命名
+ *   ### 地名（place_name）
+ *   #### 归墟
+ *   - **tags**：地名、海、尽头、仙侠
+ *   - **genres**：仙侠、通用
+ */
+
+import path from 'path';
+import { atomicWriteFile } from '#atomic-write';
+import { localIsoString } from '#workspace';
+import { connectMaterial } from '#material-db';
+import { KIND_GROUPS, KIND_LABELS } from './kinds.js';
+
+const KIND_ORDER = KIND_GROUPS.flatMap((group) => group.kinds);
+const GROUP_OF = new Map();
+for (const group of KIND_GROUPS) {
+  for (const kind of group.kinds) GROUP_OF.set(kind, group.title);
+}
+
+function text(value) {
+  return String(value == null ? '' : value).replace(/\r?\n/g, ' ').trim();
+}
+
+function heading(value) {
+  return text(value).replace(/\s+/g, ' ').trim() || '（未命名）';
+}
+
+function valueText(value) {
+  if (value === undefined || value === null || value === '') return '—';
+  if (Array.isArray(value)) {
+    return value.length ? value.map((item) => text(item)).join('、') : '—';
+  }
+  return text(value);
+}
+
+/**
+ * Render atomic materials as Markdown.
+ *
+ * @param {Array<object>} records
+ * @param {{workspace?: string, database?: string, exported_at?: string}} [meta]
+ * @returns {string}
+ */
+export function renderMaterialMarkdown(records, meta = {}) {
+  const list = Array.isArray(records) ? records : [];
+  const byKind = new Map();
+  for (const record of list) {
+    const kind = String(record && record.kind || 'unknown');
+    if (!byKind.has(kind)) byKind.set(kind, []);
+    byKind.get(kind).push(record);
+  }
+  for (const rows of byKind.values()) {
+    rows.sort((a, b) => String(a.name || '').localeCompare(String(b.name || ''), 'zh-CN'));
+  }
+
+  const lines = [];
+  lines.push('# 网文创作素材库');
+  lines.push('');
+  lines.push('> 导出时间：' + (meta.exported_at || localIsoString()));
+  if (meta.workspace) lines.push('> 工作区：' + meta.workspace);
+  if (meta.database) lines.push('> 数据库：' + meta.database);
+  lines.push('> 素材：' + list.length + ' 条 · 类型：' + byKind.size + ' 个');
+  lines.push('');
+
+  if (!list.length) {
+    lines.push('暂无素材。运行 `/fancy-material` 生成，或 `/fancy-material import <文件>` 导入。');
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  lines.push('## 目录');
+  lines.push('');
+  for (const group of KIND_GROUPS) {
+    const rows = group.kinds.reduce((sum, kind) => sum + (byKind.get(kind)?.length || 0), 0);
+    if (!rows) continue;
+    lines.push(`- ${group.title}：${rows} 条`);
+  }
+  lines.push('');
+
+  for (const group of KIND_GROUPS) {
+    const groupRows = group.kinds.reduce((sum, kind) => sum + (byKind.get(kind)?.length || 0), 0);
+    if (!groupRows) continue;
+    lines.push('## ' + group.title);
+    lines.push('');
+    for (const kind of group.kinds) {
+      const rows = byKind.get(kind) || [];
+      if (!rows.length) continue;
+      lines.push(`### ${KIND_LABELS[kind] || kind}（${kind}）`);
+      lines.push('');
+      for (const record of rows) {
+        lines.push('#### ' + heading(record.name));
+        lines.push('');
+        lines.push('- **tags**：' + valueText(record.tags));
+        lines.push('- **genres**：' + valueText(record.genres));
+        if (record.source) lines.push('- **source**：' + text(record.source));
+        if (record.note) lines.push('- **note**：' + text(record.note));
+        lines.push('');
+      }
+    }
+  }
+
+  // Include any unknown kinds at the end rather than silently dropping them.
+  const unknown = [...byKind.keys()].filter((kind) => !KIND_ORDER.includes(kind));
+  if (unknown.length) {
+    lines.push('## 其他');
+    lines.push('');
+    for (const kind of unknown) {
+      lines.push(`### ${kind}`);
+      lines.push('');
+      for (const record of byKind.get(kind)) {
+        lines.push('#### ' + heading(record.name));
+        lines.push('');
+        lines.push('- **tags**：' + valueText(record.tags));
+        lines.push('- **genres**：' + valueText(record.genres));
+        if (record.source) lines.push('- **source**：' + text(record.source));
+        if (record.note) lines.push('- **note**：' + text(record.note));
+        lines.push('');
+      }
+    }
+  }
+
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\n*$/, '\n');
+}
+
+/**
+ * Query the material DB and write `<workspace>/素材库.md`.
+ *
+ * @param {string} root workspace directory
+ * @returns {Promise<{file: string, count: number, kinds: number, database: string}>}
+ */
+export async function exportMaterials(root) {
+  const { db, database } = await connectMaterial(root);
+  try {
+    const rows = await db.query('SELECT kind, name, tags, genres, note, source FROM material ORDER BY kind, name;');
+    const records = Array.isArray(rows) && Array.isArray(rows[0]) ? rows[0] : [];
+    const file = path.join(path.resolve(root), '素材库.md');
+    const markdown = renderMaterialMarkdown(records, {
+      workspace: root,
+      database,
+      exported_at: localIsoString(),
+    });
+    atomicWriteFile(file, markdown, { mode: 0o644 });
+    const kinds = new Set(records.map((record) => record.kind).filter(Boolean));
+    return { file, count: records.length, kinds: kinds.size, database };
+  } finally {
+    try { await db.close(); } catch { /* ignore */ }
+  }
+}