@namewta/speculo 2.0.5 → 2.1.0

package/skills-hub/writing/job-application/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: job-application
+description: "扫描指定知识库建成经历原件，再按岗位派生投递简历（md/docx/pdf）、3–4分钟自我介绍、经历绑定的预测题与提升计划。用户说求职、改简历、投递、JD定制、自我介绍、面试题、提升计划、经历库、知识库扫盘、/job-application 时使用。不编造知识库里没有的数字、职级或技能。"
+license: MIT
+---
+
+# 岗位投递与面试准备
+
+经历原件是资产，每次投递是衍生品。本文件足够开工；细则按需读 `references/`。不要把用户笔记、简历正文或电话邮箱写进本技能目录。
+
+## 强制入口
+
+`$SKILL_DIR` 是本 `SKILL.md` 所在文件夹（安装后常见 `~/.agents/skills/job-application`、`~/.claude/skills/job-application`，或项目里的对应目录）。运行根是当前会话的工作区，不是技能仓，也不是用户家目录。
+
+每次激活先解析路径，再选模式。解析顺序（高 → 低），`persist_root` 与 `kb_root` 分开取：
+
+1. 用户本轮明确给出的路径
+2. 已能定位的 `$persist_root/config.json`
+3. `$SKILL_DIR/config.json`
+4. 停下来问。**禁止猜测**，禁止默默写到 `$HOME` 或技能仓库根
+
+用户说「就用当前目录」时，`persist_root` = `<cwd>/job-application`。第一次运行必须确认 `kb_root` 和 `persist_root`，写完 JSON 再扫盘。
+
+确认后双写指针（只含路径和偏好，不含经历）：
+
+```bash
+python3 "$SKILL_DIR/scripts/write_config.py" \
+  --skill-dir "$SKILL_DIR" \
+  --persist-root "<abs>" \
+  --kb-root "<abs>" \
+  --locale zh \
+  --page-budget 2
+```
+
+`python3` 不可用时改 `python`。脚本把路径展开成绝对路径，写入 `$SKILL_DIR/config.json` 和 `$persist_root/config.json`。前者被技能内 `.gitignore` 忽略，不要提交。
+
+## 模式路由
+
+| 本轮输入 | 模式 |
+|---|---|
+| 只有知识库路径 | `ingest` 然后 `master`，停下来问岗位 |
+| 已有 corpus，给了 JD / 岗位 | `pack` |
+| 两者都有，且 manifest 里的 hash 变了 | 先 `ingest` + `master`，再 `pack` |
+| 只要自我介绍，但本轮还没有 tailored | 先 `apply` 再 `pitch` |
+| 点名只要题或只要提升计划 | `questions` 或 `improve`；没有 match-report 就先 `apply` |
+
+没有 corpus 不准 `apply`。没有 `claim_id` 的数字、职级、技术名不准进投递稿或自我介绍。
+
+## 产物布局
+
+只写在 `persist_root`。默认是 `<cwd>/job-application/`。
+
+```text
+<persist_root>/
+  INDEX.md
+  config.json
+  corpus/
+    corpus.md profile.md evidence-map.md stories.md
+    strengths.md known-gaps.md framings.md style-memory.md
+    methodology-cache.md ingest-log.md
+    sources/manifest.json
+    sources/excerpts/
+  applications/YYYY-MM-DD-<company>-<role>/
+    INDEX.md brief.md company-research.md match-report.md
+    resume-original.md resume-tailored.md
+    resume-tailored.docx resume-tailored.pdf resume-tailored.html
+    changelog.md speech.md questions.md story-bank.md
+    improvement-plan.md
+```
+
+同日同公司同岗位已存在时追加 `-01`，不覆盖。知识库只读：不移动、不改写用户笔记，也不把整库复制进 `persist_root`。
+
+## 模式
+
+### ingest
+
+1. `kb_root` 必须是已存在的目录，否则 `blocked-input`。
+2. 跑 `scripts/ingest_kb.py --kb-root ... --out "$persist_root/corpus/sources/manifest.json"`。
+3. 先读 manifest 和 `sources/INDEX.md`，再按关键词回读少量原文。单文件文本超过约 200KB 只摘头尾，摘录放 `sources/excerpts/`。禁止把整个知识库灌进上下文。
+
+### master
+
+从 manifest 选源，按 [templates/](templates/) 写出 `corpus.md`、`profile.md`（19 节标题必须齐全）、`evidence-map.md`、`stories.md`、`known-gaps.md`、`framings.md`。成就库每条有 `C-xxx`。同一事实两个数字时写入缺口并问用户一次，不取较大的那个。用户明确要求时才上网刷新 `methodology-cache.md`；网搜结果不得变成个人成就。冲突以源文件和 evidence-map 为准，不以写得更顺的句子为准。
+
+### apply
+
+冻结 JD 到 `brief.md`。先写 `resume-original.md`（本轮选用的原件切片），再写 `resume-tailored.md`。每条子弹行尾加 `<!-- claim:C-012 -->`。`changelog.md` 写原句、新句、理由、claim_id。`match-report.md` 四表：已覆盖、翻译后覆盖、诚实缺口、明确不写入。然后：
+
+```bash
+python3 "$SKILL_DIR/scripts/render_resume.py" \
+  --md "$APP/resume-tailored.md" \
+  --css "$SKILL_DIR/assets/resume.css" \
+  --out-dir "$APP"
+python3 "$SKILL_DIR/scripts/validate_claims.py" \
+  --evidence "$persist_root/corpus/evidence-map.md" \
+  --files "$APP/resume-tailored.md"
+```
+
+渲染缺依赖时 HTML/md 仍算内容完成，在回复里写降级，不要编一版「看起来像 PDF」的假文件。
+
+### pitch
+
+读本轮 tailored、brief、story-bank，不按公司文化凭空写通用稿。`speech.md` 含 180–240 秒正本、60–90 秒短版、被打断时的接法、数字对照表、不要讲的内容。数字必须和投递稿同一 claim。
+
+### questions
+
+题从四条交叉来：JD 必须项、本轮每条 bullet、被压缩但库里有的项目、诚实缺口。每题绑定 `story-id`，或明确写「无法作答」。缺口题只给诚实口径，不编故事。
+
+### improve
+
+A 呈现层：本周和 7 天内能改的口径、要补的证据。B 能力层：30/60/90 天可验证出口。禁止建议伪造证书、改在职时间、把他人成果写成独立完成。
+
+### pack
+
+顺序固定：`research`（写入 `company-research.md`）→ `apply` → 渲染 → `pitch` → `questions` → `improve` → `validate_claims.py`。中途失败停在当前步，不删已通过的上游文件。只有岗位名、没有 JD 原文时，可以有限检索补 JD，并在 brief 里标明「非官方原文」。
+
+## 硬规则
+
+1. 指针只写两份 `config.json`。简历、语料、PDF 只写 `persist_root`。
+2. 无 `claim_id` 不得出口数字、职级、技术名。缺数字就定性或标 `needs_proof`。
+3. 四层语言：事实 / 估计 / 解释 / 呈现选择。投递稿只用事实和已标记的估计。
+4. 翻译不是造假。把「写过内部工具」说成「交付过平台」需要语料里真有平台级范围。
+5. 背调红线不可改：学历、在职时间、公司名、正式职级、论文署名、开源仓库所有权。
+6. JD 有、库无 → 缺口表，不进技能栏。
+7. 新事实可以回写 corpus，但必须新增 source 和 claim，并在 changelog 说明。不得在 tailor 时偷偷改原件数字。
+8. 公司新闻不是用户的个人成就。
+9. 不自动调用本仓库其它 skill。不把 `config.json` 或用户笔记提交进 git。
+
+完整口径见 [references/honesty-gate.md](references/honesty-gate.md)。简历句式、ATS、中文页数见 [references/resume-playbook.md](references/resume-playbook.md)。口播结构见 [references/interview-speech.md](references/interview-speech.md)。
+
+## 回复格式
+
+每次返回：
+
+- 模式
+- `persist_root` 与 `kb_root`（绝对路径）
+- 已写文件
+- 跑过的脚本和退出码
+- 未关闭的 `needs_proof`
+- 下一步：继续本技能的哪个模式，或结束
+
+只有 `pack` 完成门全过才能说这套投递包做完了。只跑 `pitch` 时，完成只表示自我介绍写完。
+
+## 资源
+
+| 文件 | 何时读 |
+|---|---|
+| [references/persist-paths.md](references/persist-paths.md) | 路径、JSON 字段、第一次激活 |
+| [references/honesty-gate.md](references/honesty-gate.md) | 写任何对外句子之前 |
+| [references/ingest-protocol.md](references/ingest-protocol.md) | ingest |
+| [references/corpus-schema.md](references/corpus-schema.md) | master / profile 19 节 |
+| [references/resume-playbook.md](references/resume-playbook.md) | apply |
+| [references/jd-parse.md](references/jd-parse.md) | 拆 JD |
+| [references/interview-speech.md](references/interview-speech.md) | pitch |
+| [references/question-bank.md](references/question-bank.md) | questions |
+| [references/improvement-plan.md](references/improvement-plan.md) | improve |
+| [references/rendering.md](references/rendering.md) | 渲染降级 |
+| [references/company-research.md](references/company-research.md) | pack 里的公司调研 |
+| [scripts/](scripts/) | 扫盘、写指针、渲染、校验主张 |
+| [templates/](templates/) | 每个产物的标题骨架 |

package/skills-hub/writing/job-application/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Job application"
+  short_description: "从知识库生成经历原件，再按岗位派生简历、自我介绍、面试题和提升计划"
+  default_prompt: "Use $job-application to scan my knowledge base into a career corpus, then tailor a resume, 3-4 minute pitch, interview questions, and an improvement plan for a specific job. Do not invent metrics."

package/skills-hub/writing/job-application/assets/resume.css

@@ -0,0 +1,10 @@
+@page { size: A4; margin: 14mm; }
+html, body { margin: 0; padding: 0; background: #fff; color: #111; }
+body { font-family: "Segoe UI", "PingFang SC", "Noto Sans CJK SC", "Source Han Sans SC", sans-serif; font-size: 11pt; line-height: 1.35; }
+main.sheet { max-width: 180mm; margin: 0 auto; }
+h1 { font-size: 18pt; margin: 0 0 4pt; font-weight: 650; }
+h2 { font-size: 12pt; margin: 12pt 0 4pt; border-bottom: 0.4pt solid #222; padding-bottom: 2pt; }
+h3 { font-size: 11pt; margin: 8pt 0 2pt; }
+p, li { margin: 0 0 3pt; }
+ul { margin: 0 0 6pt 1.1em; padding: 0; }
+a { color: inherit; text-decoration: none; }

package/skills-hub/writing/job-application/config.example.json

@@ -0,0 +1,9 @@
+{
+  "schema_version": 1,
+  "skill": "job-application",
+  "persist_root": "/absolute/path/to/job-application",
+  "kb_root": "/absolute/path/to/knowledge-base",
+  "locale": "zh",
+  "page_budget": 2,
+  "updated_at": "2026-09-21T00:00:00.000Z"
+}

package/skills-hub/writing/job-application/references/company-research.md

@@ -0,0 +1,7 @@
+# 公司调研
+
+`company-research.md` 只记录公开事实：产品、团队公开岗位、近期发布、和 JD 直接相关的技术栈。每条带来源 URL 和日期。
+
+这些事实可以用于自我介绍的「为何此司」，不能写进用户的经历子弹。
+
+不确定的市场传闻标「未核实」，不进口播稿。

package/skills-hub/writing/job-application/references/corpus-schema.md

@@ -0,0 +1,33 @@
+# 原件
+
+`corpus.md` 是长文。`profile.md` 是给 tailor 用的稳定索引。两者冲突时，以 `evidence-map.md` 和源文件为准。
+
+## profile 19 节
+
+空节保留标题，不要删号。
+
+1. 身份
+2. 头条与目标岗位
+3. 摘要候选
+4. 经历快照
+5. 经历深挖
+6. 教育
+7. 证书与考试
+8. 技术技能（只收语料里出现过的）
+9. 领域经验
+10. 带人与协作
+11. 公开产物
+12. 语言
+13. 奖项
+14. 志愿与社团
+15. 兴趣（默认不进投递稿）
+16. 到岗与工作许可（敏感，只在 framings 批准后使用）
+17. 成就库（每条 `C-xxx`）
+18. 已知缺口
+19. 预批准表述
+
+## evidence-map
+
+表格列：`claim_id`、陈述、源 `src-id`、摘录、层级（事实/估计）。
+
+成就库里的每一条都必须在这张表出现。没有行，就不能被投递稿引用。

package/skills-hub/writing/job-application/references/honesty-gate.md

@@ -0,0 +1,29 @@
+# 诚实门
+
+这是导出硬门，不是写作风格建议。
+
+## 主张
+
+- 每条可对外使用的数字、职级、时间、技术名都要有 `C-xxx`。
+- 投递稿用 HTML 注释：`<!-- claim:C-012 -->`。
+- `validate_claims.py` 对不上 evidence-map 时，不得把该文件当成品交付。
+- 找不到数字就写定性描述，或标 `needs_proof` 并向用户要来源。不要编一个看起来合理的百分比。
+
+## 四层
+
+| 层 | 含义 | 能否进投递稿 |
+|---|---|---|
+| 事实 | 知识库或用户确认的原句 | 可以 |
+| 估计 | 用户标过「约 / 量级」 | 可以，必须保留「约」 |
+| 解释 | 你对动机、能力的归纳 | 只能进自我介绍，不能改写成事实 |
+| 呈现选择 | 详略、顺序、用哪个同义词 | 可以，但不得升级范围 |
+
+## 红线
+
+不可改：学历、在职起止、公司法定名、正式职级、论文署名、仓库所有权。
+
+JD 里有、语料里没有的技能，只出现在 match-report 的缺口表。
+
+翻译是换角度讲真事。没有平台级证据，就不要写成平台。
+
+提升计划里的未来完成时，不得写进「过去已经做到」。

package/skills-hub/writing/job-application/references/improvement-plan.md

@@ -0,0 +1,15 @@
+# 提升计划
+
+两栏，不要第三栏。
+
+## A. 呈现
+
+本周就能改的口径：顺序、动词、把项目翻译成 JD 的词。7 天内可补的证据：找回数字、补公开说明、向当事人核对范围。这些可以进下一版投递稿，但补到之前仍标 `needs_proof`。
+
+## B. 能力
+
+30 / 60 / 90 天。每项有一个可验证出口：一个小项目、一篇笔记、一次能演示的结果。未做完之前不写进简历。
+
+## 不要做
+
+买假证、改在职时间、把协作成果写成独立完成、用未来计划冒充过去业绩。

package/skills-hub/writing/job-application/references/ingest-protocol.md

@@ -0,0 +1,18 @@
+# 扫盘
+
+`ingest_kb.py` 递归读取 `kb_root`，不改源文件，不访问网络。
+
+跳过目录名以 `.` 开头的路径（含 `.git`、`.venv`、`.obsidian`），以及 `node_modules`、`__pycache__`、`dist`、`build`、`.idea`、`.vscode`。跳过 `.DS_Store`。不读隐藏目录里的文件。
+
+`sources/manifest.json` 每条：
+
+- `id`：首次按路径排序从 `src-0001` 编号。再次扫描时同一 `relpath` 保留原 `id`，新文件取尚未使用的下一个号
+- `relpath` 是稳定键。编号会因插入新文件而不再等于「当前排序第几」，主张要绑 `relpath` 或当次 `id`，不要凭记忆里的旧序号
+- `relpath`、`sha256`、`mtime`、`bytes`
+- `kind`：`text` 或 `binary`
+- `status`：`indexed`、`truncated`（大于 256KB）、`skipped-binary`
+- `summary`：第一段非标题正文，最多约 180 字
+
+hash 未变时保留旧 summary。二进制只记账，不解析。v1 不做 OCR。
+
+Agent 读完 manifest，按 [templates/sources-index.md](../templates/sources-index.md) 写 `sources/INDEX.md`，再按 `id` 回读少量原文。不要把清单外的整文件贴进上下文。超过约 200KB 的文本只摘头尾到 `sources/excerpts/`，摘录文件名用 `src-0001.md`。扫盘摘要写 `ingest-log.md`。

package/skills-hub/writing/job-application/references/interview-speech.md

@@ -0,0 +1,16 @@
+# 自我介绍
+
+正本 180–240 秒。短版 60–90 秒，只留一个 STAR。
+
+| 时间 | 内容 |
+|---|---|
+| 0:00–0:20 | 姓名、当前身份、一句话标签（年限 / 领域 / 一个可核对成果） |
+| 0:20–2:40 | 两段与本岗和本轮投递稿相同项目的 STAR |
+| 2:40–3:20 | 为何是这家、此刻能上手的一件事。只用公司公开事实加自己的 claim |
+| 3:20–3:40 | 收束，留一个可追问的钩子 |
+
+稿是重点顺序加关键数字，不是背诵台词。`speech.md` 要写「被打断时从哪一段接」。
+
+禁止：复读简历、从爱好开场、发明数字、把提升计划里的「还不会」说成「已经精通」。
+
+每个数字旁写对应的 `claim_id`，并在文末做对照表。

package/skills-hub/writing/job-application/references/jd-parse.md

@@ -0,0 +1,18 @@
+# 拆 JD
+
+`brief.md` 冻结原文。拆成三列：
+
+- 硬门槛：年限、学历、语言、工作许可、必须到岗的城市
+- 核心：反复出现的职责和技能
+- 加分：出现一次的工具或行业
+
+只有岗位名、没有 JD 时，可以检索公开招聘页补一份，并在 brief 顶部写「非官方原文」和 URL。检索不到就停，让用户粘贴，不要用通用岗位描述冒充这家公司的 JD。
+
+匹配表用四格，不要只用一个百分比：
+
+| 格 | 含义 |
+|---|---|
+| 已覆盖 | 语料里有直接证据 |
+| 翻译后覆盖 | 真事换了岗位用词，claim 仍在 |
+| 诚实缺口 | JD 有、库无 |
+| 不写入 | 真实但和本岗无关，或用户标记不公开 |

package/skills-hub/writing/job-application/references/persist-paths.md

@@ -0,0 +1,34 @@
+# 路径与 config.json
+
+`$SKILL_DIR` 是含 `SKILL.md` 的目录。`persist_root` 是产物根。`kb_root` 是用户知识库，只读。
+
+## 解析
+
+1. 本轮用户给出的路径优先。
+2. 其次读已存在的 `$persist_root/config.json`。
+3. 再读 `$SKILL_DIR/config.json`。
+4. 都没有就问。不要猜。
+
+「就用当前目录」= `<cwd>/job-application`。相对路径先展开成绝对路径再写入。
+
+## JSON
+
+两份文件字段相同。技能目录那份是指针，产物根那份是自描述。重装技能后，若用户还指向旧产物根，可从产物根把 JSON 抄回技能目录。
+
+```json
+{
+  "schema_version": 1,
+  "skill": "job-application",
+  "persist_root": "/abs/job-application",
+  "kb_root": "/abs/notes",
+  "locale": "zh",
+  "page_budget": 2,
+  "updated_at": "2026-09-21T00:00:00.000Z"
+}
+```
+
+禁止写入 token、简历正文、电话、邮箱、成就数字。
+
+改路径只重写 JSON，不自动搬家。用户要求搬家时，复制 `corpus/` 与 `applications/` 后再改指针。
+
+`persist_root` 不得落在 `$SKILL_DIR` 里面。`write_config.py` 会拒绝。

package/skills-hub/writing/job-application/references/question-bank.md

@@ -0,0 +1,19 @@
+# 预测题
+
+不要从网上抄一份通用 50 题。交叉这四类：
+
+1. JD 硬门槛和核心项
+2. 本轮投递稿的每一条 bullet
+3. 语料里与岗位相关、但本轮被压缩掉的项目
+4. 诚实缺口
+
+每题记录：
+
+- 题干
+- 为什么会被问（JD 原句或 bullet）
+- `story-id`，或「无法作答」
+- 30 秒口径和 2 分钟口径
+- 两到三个追问
+- 不会时的诚实降级
+
+缺口题不得带具体业绩。追问只挖投递稿和语料里已经有的决策、范围、失败和权衡。

package/skills-hub/writing/job-application/references/rendering.md

@@ -0,0 +1,9 @@
+# 渲染
+
+`render_resume.py` 始终写 `resume-tailored.html` 和 `render-status.json`。
+
+- 装了 `python-docx` 才写 docx
+- 装了 `weasyprint` 才写可选中文字的 PDF
+- 两者都没有时退出码 3。HTML 仍可用浏览器打印
+
+不要用截图冒充 PDF。CSS 是单栏、无图标、无表格。联系方式必须在 Markdown 正文里，不要放进 CSS 页眉。

package/skills-hub/writing/job-application/references/resume-playbook.md

@@ -0,0 +1,30 @@
+# 投递稿
+
+## 句式
+
+简历子弹用 XYZ，不要把 STAR 整段塞进一行。
+
+> 做成了 X，用 Y 衡量，靠 Z。
+
+例：把月结从 12 天收到 5 天，靠在 SAP 里自动做公司间对账。`<!-- claim:C-014 -->`
+
+自我介绍和面试答纲再用 STAR，压成两三句。
+
+量化只从语料里已有的六类里取：速度、规模、可靠性、业务、团队与过程、范围。没有数就不要造。
+
+## ATS
+
+- 单栏。标准标题：经历、项目、技能、教育。
+- 不用表格、文本框、图标、多栏、页眉页脚里的联系方式。
+- 联系方式在正文顶部。
+- PDF 必须是可选中的文字。渲染失败就交 HTML，不要交整页截图。
+- 关键词放三层：标题或摘要、技能分组、带工具和结果的子弹。
+- 缩写和全称成对出现一次。
+- JD 高频词取 3–5 个核，分别落在标题、摘要、子弹。不堆砌。
+- 不把 JD 有而库无的词写进技能栏。
+
+## 中文页数
+
+`page_budget` 默认 2。校招或实习可收成 1。超过预算时在 match-report 解释，而不是把字号压到不可读。
+
+互联网岗默认无照片、无政治面貌。JD 明确要求时才加。自我评价可省略；写了必须带 claim。

package/skills-hub/writing/job-application/scripts/README.md

@@ -0,0 +1,12 @@
+# scripts
+
+只依赖 Python 3 标准库，外加可选的 `python-docx` 与 `weasyprint`。缺可选库时简历仍会写出 HTML，进程以退出码 3 表示二进制降级，内容不算失败。
+
+```bash
+python3 scripts/write_config.py --skill-dir "$SKILL_DIR" --persist-root ./job-application --kb-root /path/to/notes
+python3 scripts/ingest_kb.py --kb-root /path/to/notes --out ./job-application/corpus/sources/manifest.json
+python3 scripts/render_resume.py --md ./app/resume-tailored.md --css assets/resume.css --out-dir ./app
+python3 scripts/validate_claims.py --evidence ./job-application/corpus/evidence-map.md --files ./app/resume-tailored.md
+```
+
+不要把真实 `config.json`、知识库或生成的 PDF 提交进本仓库。

package/skills-hub/writing/job-application/scripts/ingest_kb.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Scan a knowledge-base directory into sources/manifest.json. Read-only on sources."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+SKIP_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    "node_modules",
+    "__pycache__",
+    ".venv",
+    "venv",
+    "dist",
+    "build",
+    ".next",
+    ".idea",
+    ".vscode",
+}
+SKIP_FILES = {".DS_Store", "Thumbs.db"}
+TEXT_SUFFIXES = {
+    ".md",
+    ".txt",
+    ".html",
+    ".htm",
+    ".json",
+    ".yml",
+    ".yaml",
+    ".rst",
+    ".csv",
+    ".tsv",
+    ".py",
+    ".js",
+    ".mjs",
+    ".ts",
+    ".tsx",
+    ".jsx",
+    ".java",
+    ".go",
+    ".rs",
+    ".css",
+    ".xml",
+    ".toml",
+}
+MAX_READ = 256 * 1024
+SUMMARY_CHARS = 180
+
+
+def summary_of(text: str) -> str:
+    chunk = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            if chunk:
+                break
+            continue
+        chunk.append(stripped)
+        if sum(len(part) for part in chunk) >= SUMMARY_CHARS:
+            break
+    blob = " ".join(chunk).strip()
+    if len(blob) > SUMMARY_CHARS:
+        blob = blob[: SUMMARY_CHARS - 1].rstrip() + "…"
+    return blob
+
+
+def file_id(previous: dict, rel: str, used: set[str]) -> str:
+    prior = previous.get(rel) or {}
+    existing = prior.get("id")
+    if isinstance(existing, str) and existing.startswith("src-"):
+        return existing
+    number = 1
+    while True:
+        candidate = f"src-{number:04d}"
+        if candidate not in used:
+            used.add(candidate)
+            return candidate
+        number += 1
+
+
+def sha256_and_size(path: Path) -> tuple[str, int]:
+    digest = hashlib.sha256()
+    size = 0
+    with path.open("rb") as handle:
+        while True:
+            chunk = handle.read(1024 * 1024)
+            if not chunk:
+                break
+            size += len(chunk)
+            digest.update(chunk)
+    return digest.hexdigest(), size
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--kb-root", required=True)
+    parser.add_argument("--out", required=True)
+    args = parser.parse_args()
+
+    root = Path(args.kb_root).expanduser().resolve()
+    if not root.is_dir():
+        print(f"kb-root is not a directory: {root}", file=sys.stderr)
+        raise SystemExit(2)
+    out = Path(args.out).expanduser().resolve()
+    previous: dict[str, dict] = {}
+    if out.is_file():
+        try:
+            old = json.loads(out.read_text(encoding="utf-8"))
+            for item in old.get("files", []):
+                rel = item.get("relpath")
+                if rel:
+                    previous[rel] = item
+        except (OSError, json.JSONDecodeError):
+            previous = {}
+
+    files = []
+    used_ids: set[str] = set()
+    for item in previous.values():
+        existing = item.get("id")
+        if isinstance(existing, str) and existing.startswith("src-"):
+            used_ids.add(existing)
+    for path in sorted(root.rglob("*")):
+        if not path.is_file():
+            continue
+        parts = path.relative_to(root).parts
+        if any(part in SKIP_DIRS or part.startswith(".") for part in parts):
+            continue
+        if path.name in SKIP_FILES:
+            continue
+        rel = path.relative_to(root).as_posix()
+        digest, size = sha256_and_size(path)
+        mtime = datetime.fromtimestamp(path.stat().st_mtime, timezone.utc).strftime(
+            "%Y-%m-%dT%H:%M:%S.000Z"
+        )
+        kind = "text" if path.suffix.lower() in TEXT_SUFFIXES else "binary"
+        status = "indexed"
+        file_summary = ""
+        if kind == "binary":
+            status = "skipped-binary"
+        elif size > MAX_READ:
+            status = "truncated"
+            with path.open("rb") as handle:
+                file_summary = summary_of(handle.read(8192).decode("utf-8", errors="replace"))
+        else:
+            text = path.read_text(encoding="utf-8", errors="replace")
+            if "\x00" in text:
+                kind = "binary"
+                status = "skipped-binary"
+            else:
+                file_summary = summary_of(text)
+        prior = previous.get(rel)
+        if prior and prior.get("sha256") == digest and prior.get("summary"):
+            file_summary = prior["summary"]
+            if status == "indexed":
+                status = prior.get("status", status)
+        files.append(
+            {
+                "id": file_id(previous, rel, used_ids),
+                "relpath": rel,
+                "sha256": digest,
+                "mtime": mtime,
+                "bytes": size,
+                "kind": kind,
+                "summary": file_summary,
+                "status": status,
+            }
+        )
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "schema_version": 1,
+        "kb_root": str(root),
+        "scanned_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.000Z"),
+        "file_count": len(files),
+        "files": files,
+    }
+    out.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    print(f"{out} files={len(files)}")
+
+
+if __name__ == "__main__":
+    main()