dsh-data-domain-knowledge 0.1.0-alpha.3 → 0.1.0-alpha.4

package/README.md

@@ -1,6 +1,6 @@
 # dsh-data-domain-knowledge
 
-本地知识库插件：`01_source_truth` 保存 **SourceRaw**（原始可追溯文档），`02_wiki` 保存
+本地知识库插件：`01_source_raw` 保存 **SourceRaw**（原始可追溯文档），`02_wiki` 保存
 按主题聚合、可双向链接的 wiki 卡片，`03_compiled` 输出可检索的 **wikiNotes**、wiki
 知识图谱和向量索引，`<agentRoot>/memory/<库 id>` 保存版本快照、访问审计与反馈。默认使用本地 WeMM Python backend：从 WeMM
 原生 2048 维向量按 MRL 截取 1024 维，先做 binary/Hamming 粗筛，再用 int8 点积精算余弦
@@ -30,8 +30,8 @@
 
 | 段 | 名称 | 产物 | 关键配置 |
 | --- | --- | --- | --- |
-| 1 | SourceRaw | 原始可追溯文档：`01_source_truth/*.md` | `allowSourceTruth` / `rootDir` |
-| 2 | 编译 Compile | wiki：`02_wiki`（按主题聚合、可双向链接）；wikiNotes：`03_compiled/wiki_notes.json` | `schemaTypes` |
+| 1 | SourceRaw | 原始可追溯文档：`01_source_raw/*.md` | `allowSourceTruth` / `rootDir` |
+| 2 | 编译 Compile | wiki：`02_wiki`（**按 wiki 类型 schema 抽实体，直接入库**）；wikiNotes：`03_compiled/wiki_notes.json` | `extractCandidates` / `extractWithModel` / `wikiTypes` |
 | 3 | 构建 Build | wikiNotes → 向量索引；wiki → `03_compiled/knowledge_graph.json` | `embeddingProvider` / `embeddingModel` / `python` |
 | 4 | 召回 Recall | 多路（关键词 + 向量 + 知识图谱）召回 wikiNotes，取 `recallTopK`（默认 10），再解析父级 wiki 与该 wiki 的 1 跳知识图谱 | `recallTopK` / `recallMode` |
 | 5 | 重排 Rerank | BERT cross-encoder 对候选 wikiNotes 精排，取 `contextTopN`（默认 5）组成 `context` | `contextTopN` / `rerankProvider` / `rerankModel` |
@@ -40,15 +40,100 @@
 > 但「跑一次真实召回长什么样」是一个问题，分两栏会让用户先跑召回、再切到重排才能
 > 看到同一次运行的全貌。
 
-> 术语迁移：SourceRaw 曾叫 SourceRow / SourceTruth。磁盘目录 `01_source_truth`、工具名
+> 术语迁移：SourceRaw 曾叫 SourceRow / SourceTruth。磁盘目录 `01_source_raw`、工具名
 > `add_source` / `query_source_truth`、HTTP `/knowledge/sources`、设置键 `allowSourceTruth`
 > 与错误码 `SOURCE_TRUTH_DISABLED` 作为兼容名保留，语义等同 SourceRaw。
-> 「编译 / 构建」是同一次 `rebuild()`：编译的**按主题聚合**由 Agent 完成，
-> **wiki↔wiki 双向链接**与**分阶段重建**是设计目标，图谱当前只有 `supported_by` 溯源边。
+> 「编译 / 构建」是同一次 `rebuild()`：编译**按 wiki 类型 schema 抽实体**（模型优先、
+> 规则兜底），判重后直接写 `02_wiki`；**wiki↔wiki 双向链接**与**分阶段重建**是设计目标，
+> 图谱当前只有 `supported_by` 溯源边加规则抽出的 `relates_to`。
 
 - 设置项**不再有独立入口**：它们挂在 Agent 概览架构图的对应节点上（SourceRaw → 收录开关与
   知识库根目录；编译 → Schema；构建 → Embedding / Python；召回 → topK / 默认路线；
   重排 → topN / reranker；意图与上下文 → 意图路由），每个节点只保存本节点字段。
+- **编译直接入库（0044）**：`rebuild_knowledge` 的 Pass 0 对指纹变了的来源做实体抽取，
+  按 `entityType:entityId` / `title` / `metadata.aliases` 三重索引判重 —— 命中已有卡片就把
+  新正文**追加**进去（不覆盖、不丢弃），没命中就新建。缺必填小节 / 字段的卡片**照常入库**，
+  问题写进 `metadata.schema_issues`，面板显示成「待补」。**没有任何确认门**：卡片一写盘就进
+  wikiNotes、向量与图谱，立刻可召回。
+- **正文只读，备注可加**：卡片正文由编译产出，人改不了（手工写正文返回
+  `WIKI_CARD_IMMUTABLE`）。人的判断落在 front matter 的 `annotations` 上
+  （`kind: 'anomaly'` 表示异常点），**编译不会覆盖它**。review（`review_wiki_card`）在入库
+  之后做，它把卡片评分抬到 `REVIEWED_SCORE_FLOOR`，让它在召回时排前面一点（倍率 0.85–1.2）；
+  同时把生命周期从 `unreviewed` / `draft` 推进到 `reviewed`（撤销时只退回这一档，
+  不动 `active` / `deprecated` / `problem` —— 那些是人另外做过的决定）。
+  标注异常点会把有效评分压到 `ANOMALY_SCORE`，但卡片**照样召回得到**，只是排在后面。
+
+  **合并按小节折进去**：同一实体被第二份文档命中时，新正文并进相同标签的小节里，
+  每个小节只出现一次；原来还是占位（「（文档未说明）」）的小节被真内容替换。
+  两份正文里只要有一份没有 `##` 结构（规则路径切出来的原文），退回整段拼接。
+- **批量导入只编译一次**（0045）：`import_sources` 收一组来源（一次最多 50 份），逐份写入、
+  **整批只编译一次**，逐条汇报成败 —— 第 7 份坏了不会让前 6 份白写。十份文档不再是十次审批、
+  十次往返、十次抽取。它与 `POST /knowledge/import` 落到同一个运行时方法 `runtime.importSources`，
+  与单份的 `add_source` 只差「一次多少份」。
+- **对话流里有专用卡片**（0045）：`import_sources` / `recall_knowledge` / `rebuild_knowledge` /
+  `add_source` / `propose_wiki_cards` 各自带 `presentationMeta`，浏览器半按**工具名**注册
+  `tool.call.toolview`，于是对话里显示的是「导入 3 份来源并编译 · 写入 3 份 · 新建 2 张卡」
+  与可展开的命中列表（名次、分数、`entityType:entityId`、review 评分），而不是一坨 JSON。
+  meta 随会话日志落盘，所以**回放与当时看到的一致**。
+- **来源里的图跟着文字进卡片**（0047）：抽取那一段交给模型的是文字，模型不会把图带回来，
+  所以图由编译**单独**落位 —— 拿「图前最近那一段话」去各张卡片正文里比对（12 字滑窗，
+  容忍改写与「（参见图表12）」这类图号指引），命中就插在那段话后面；锚点对不上时退回
+  「图所在的来源小节」整节比对（还要至少命中 3 个滑窗），落点在正文里再用 4 字滑窗分高下；
+  两档都不够就**不挂** —— 宁可少一张图，也不把图挂到一张讲别的事的卡上，没落位的张数如实
+  进 `warnings`。收尾的署名图 / 二维码（图后没有正文且锚点很短）故意不挂。每张 wikiNote
+  只带**自己那一节**的图，因为多模态编码只吃每条的**第一张**图。图不参与抽取指纹，所以
+  0047 之前编好的库重编时，来源虽然被指纹跳过，图仍然会被补上。
+- **图片引用有三种写法，解析只认「真实存在的那个」**（0047）：`01_source_raw/_assets/…`
+  （规范形，知识库根相对）、`_assets/…`（转换内核早期写进 SourceRaw 的形式）、
+  `../../01_source_raw/_assets/…`（`cardHints` 给手工建卡的形式）。文档的资产清单与卡片的
+  `imagePaths` 走同一个 `assetRefCandidates`（根目录 → `01_source_raw/` → 文件自己的目录），
+  否则同一张图在文档里找得到、在卡片里找不到。派生字段（图片路径、来源分类）变了也算
+  「语料变了」，否则增量编译的空操作会把刷新结果丢掉。
+- **SourceRaw 的 front matter 是 OKF v0.2 形状**（0048）：`type`（唯一必填键，值就是
+  来源分类）、`title`、`description`、`resource`（底层资产地址）、`tags`、
+  `generated: {by, at}`（`by` = 谁解析的，`at` = **采集时间** —— OKF 里没有「抓取时间」
+  这个概念）、`sources: [{id, resource, title, author, last_modified}]`（对网页就是那个页面
+  本身：地址、标题、作者、发布时间）。`source_id` / `external_id` / `created_at` /
+  `updated_at` / `metadata` / `lineage` 是我们的扩展键（OKF 明确允许，且要求消费者容忍
+  未知键）。**旧文件的 `source_type` 仍然读得到**，存量文件由 `ensureLayout` 一次性迁移
+  （只搬已有的值，不编作者与发布时间 —— 0048 之前适配器把它们抽出来就扔了）。
+  规范：<https://github.com/GoogleCloudPlatform/open-knowledge-format>（v0.2）。
+- **来源分类可以声明元数据字段**（0048）：`SourceTypeDef.metadataFields` 是
+  `{key, label, description, required}` 的清单，`key` 用 front matter 顶层键或
+  `sources[0].author` 这种路径。面板「类型定义 → 来源分类」里可编辑；缺必填字段时
+  `add_source` 回一条 warning（`status: partial`）而**不拒收** —— 元数据缺失是信息不全，
+  不是「这份知识不存在」，拒收的代价是知识直接丢了。
+- **召回组装按「卡片」而不是按「片段」**（0050）：R1–R3 不变（多路召回 + RRF + 对候选池重排，
+  召回与重排的对象都是 wikiNotes），R4 改成四步 —— ① 取 notes 对应的 wiki 去重，一张卡片的等级
+  取它名下 note 的**最高重排分**，命中的小节挂在同一条上；② **在这之后**做 wiki → wiki 的
+  1 跳扩展（图上的 `relates_to` 边 + 共同来源，上限 20 张）；③ 按 `contextMaxChars`
+  （默认 20000，`0` = 不限）装箱：命中的 note 正文优先，扩展卡片先给标题 + 摘要 + 来路，
+  有余量才给正文；④ 装不下的落**系统临时目录**（`<os.tmpdir()>/dsh-knowledge-recall/<库>/<recallId>.md`），
+  上下文里留一行绝对路径 —— Agent 用自己的文件读取能力去取，读不到就调大
+  `context_max_chars` 重新召回。响应里 `budget` 是这次的真实账，`expansion` 是 1 跳扩展的结果。
+- **召回栏是一条三步的步骤轨**（0050）：召回（找）→ 重排（排）→ 扩展（展），箭头相连，每一步
+  带自己的真实计数（`关键词 12 · 向量 9` / `保留 5 · 丢 7` / `3 张 + 2 张`），没跑过时写「未运行」。
+  第一步的路由标签可点（点一下只看关键词或向量那一路的候选与分数）；第二步列出**全部**候选的
+  逐条 logit 与 sigmoid，被丢弃的置灰并写明「低于阈值 0.2」；第三步分两块（命中的卡片 / 1 跳扩展，
+  含被预算挡住的），末尾写「最终 N 个 wiki 进上下文」。旋钮跟着步骤走：路线与召回 topK 在第一步，
+  上下文 topN 在第三步。这份「面板账本」只在 HTTP 的 `detail=true` 上返回，工具调用不带它。
+- **编译的收尾段产出三样东西**（0049），都不调模型：
+  ①**索引页** `03_compiled/wiki-index.md` —— 按类型分组列出库里现有的卡片（链接 + 状态 +
+  待补数），末尾单列断链。它刻意不写生成时间与版本号：写了它每次重建都变一个字节，而增量
+  编译要靠「索引页变了没有」判断这一轮要不要真的落盘。落在 `03_compiled/` 而不是 `02_wiki/`，
+  因为后者每一份 `.md` 都会被当成一张卡片读进卡片清单。
+  ②**相关卡片** —— 写进卡片正文末尾一块（块首带 `<!-- compiled:related -->`，整块替换而不是
+  追加）。关系来源有两个：来源文档里写明的关系（双向都记），以及「同一份来源」（补前面没覆盖
+  到的，每张卡片上限 8 条）。**它不进召回单元**：相关块是导航不是知识，切进去会让
+  「毛利率怎么算」同时命中所有提到毛利率的卡片。
+  ③**断链检查** —— 正文里 `[[类型/名称]]` 指向不存在的卡片时，写成 `metadata.schema_issues` 里
+  `level: 'reference'` 的问题（卡片抽屉上那枚「引用」徽标终于有了内容），同时进 `lintCards()`
+  的待补清单。判据与判重同一套（类型 + entityId / 标题 / 别名）。
+- **工具返回值必须能被 JSON 装下**（0046）：`envelopeSuccess` / `envelopeFailure` 统一过一遍
+  `jsonSafe()`。原因很具体：`rebuild_knowledge` 只重建 wiki 时报告里的 `vectorQuantization` /
+  `embeddingDimension` 是 `undefined` —— 卡片、`wiki_notes`、图谱、FTS 全都已经落盘，调用方
+  收到的却是 `value is not lossless JSON`。工具返回值要原样进会话日志，而 HTTP 那条路是
+  `JSON.stringify`，同一个 `undefined` 在那里无声无息，所以这个错只在工具调用上现形。
 - 编译期一条 wiki 至少产出一条 note；正文按 `##`/`###` 分节且超过 800 字符时按节切分，
   首条 note 的 `unitId` 保持 `<entityType>:<entityId>`，后续为 `<entityType>:<entityId>#<n>`，
   每条 note 都带 `wikiId` 指回父级 wiki。`03_compiled/knowledge_units.json` 作为旧版兼容镜像保留。
@@ -82,7 +167,7 @@ Tita Data Agent → Agent 概览 →「构建」节点的设置中确认：
 
 知识库默认保存在 `~/.tita-data-agent/knowledge`；设置了 `DSH_KNOWLEDGE_ROOT`
 或已有旧的 `domain_knowledge` 目录时会优先沿用。点击「编译」后，
-`03_compiled` 会生成 `wiki_notes.json`、`knowledge_graph.json`、
+`03_compiled` 会生成 `wiki_notes.json`、`knowledge_graph.json`、`wiki-index.md`、
 `vector-manifest.json`、`vectors.binary` 和 `vectors.int8`。未修改的 wikiNote
 会复用已有向量，只有新增或变更的 note 重新编码；编码与重排各自使用常驻 Python
 worker（同一份 `src/python/embedding_worker.py`），避免每个请求重复加载模型。
@@ -107,7 +192,9 @@ BERT 重排默认使用 `BAAI/bge-reranker-base`；如需完全离线，可把
 多格式转换是本插件的一个子模块（`src/convert/`），与知识库共用同一次挂载、同一个
 侧边栏 Tab、同一套 runtime。解析由可选内核 `dsh-convert-core` 完成（内核不挂载，可独立
 运行），底层是 `@firecrawl/anydoc`（MIT / Rust / 预编译绑定），支持 doc、docx、ppt、
-pptx、xls、xlsx、odt、ods、odp、rtf、epub、csv 与文本层 PDF。
+pptx、xls、xlsx、odt、ods、odp、rtf、epub、csv 与文本层 PDF；另有本地音视频/图片
+（`iddoc`）、扫描件轻量 OCR（`scanned`：`.pdf` 报 `needsOcr` 时**自动兜底**）与
+网页 / 微信公众号文章（`web`：`kind=url` 抓链接，`.html/.htm` 收另存下来的页面）。
 
 | 项 | 值 |
 | --- | --- |
@@ -132,7 +219,7 @@ pptx、xls、xlsx、odt、ods、odp、rtf、epub、csv 与文本层 PDF。
 **不传 `kb` 的旧接口与旧工具一律作用于默认库，行为不变**。
 
 ```ts
-interface KnowledgeBase { id; name; description; rootDir; isDefault; sourceTypes; wikiTypes; wikiSchemaMode; createdAt; updatedAt; sourceCount; cardCount; noteCount; buildVersion }
+interface KnowledgeBase { id; name; description; rootDir; isDefault; sourceTypes; wikiTypes; createdAt; updatedAt; sourceCount; cardCount; noteCount; buildVersion }
 ```
 
 `sourceCount` / `cardCount` / `noteCount` / `buildVersion` 和每条分类/类型的计数都是
@@ -161,12 +248,12 @@ HTTP `GET /knowledge/bases` 在返回前先刷新。
 
 | 段 | 装什么 | 删掉的后果 |
 | --- | --- | --- |
-| `01_source_truth/<source_type>/` | SourceRaw，一级是**来源分类**，二级是文档 | 丢数据 |
+| `01_source_raw/<source_type>/` | SourceRaw，一级是**来源分类**，二级是文档（**文件名 = 标题**，0051） | 丢数据 |
 | `02_wiki/<entity_type>/` | Wiki 卡片，一级是卡片类型 | 丢结论 |
 | `03_compiled/` | wikiNotes / 向量 / 知识图谱 / 归因图谱 | 可重建 |
 
 **归因图谱也在这三段里**（v1.1）：一次排查的产物是一条来源分类为 `agent_diagnosis_case`
-的 SourceRaw（落 `01_source_truth/`），模板卡由类型定义派生、不落盘，字段级的归因图
+的 SourceRaw（落 `01_source_raw/`），模板卡由类型定义派生、不落盘，字段级的归因图
 落 `03_compiled/diagnosis_graph.json`。旧的 `05_diagnosis/` 撤销了；它里面的 `*.jsonl`
 如果还在，角色是**只读的迁移输入与历史快照** —— 不再被写，但仍然读得出来（证据与根因
 就从那里来），所以旧知识根不会因为这次改动而读不出内容。
@@ -176,7 +263,16 @@ schema 段已撤掉：它从建出来那天起就是一个**空目录**，分类
 启动时会把空的那个目录删掉 —— **非空则保留**：那就不属于「没用的空文件夹」了，
 删掉别人的文件比留一个空目录危险得多。
 
-`01_source_truth` 按分类分目录（而不是平铺）的理由与 `02_wiki` 一致：分类是每份来源的
+**文件名用标题（0051）。** `01_source_raw/<分类>/阿里集团大数据建设OneData体系.md` —— `ls`
+认得出、`grep` 文件名有用、`git diff` 看得出改的是哪份材料；`source_id`（`article:bc82…`）仍是
+稳定身份，住在 front matter 里。三条配套规则：①标题里的路径不安全字符换成 `-`、截断到 120 字符、
+只剩替换字符时退回 `source_id`；②**重名默认拒收**（`SOURCE_TITLE_DUPLICATED`，报错指出被谁占着，
+改标题再来）—— 标题是来源的核心属性，两份不同的东西同名是要人处理的信号，不该由命名规则悄悄加后缀；
+③确实要留两份同标题材料时显式传 `allow_duplicate_title: true`，落成 `<标题>-<内容哈希前 6 位>.md`
+并回一条 warning。改名与迁移（老段名 `01_source_truth` → `01_source_raw`、文件名换成标题）在
+`ensureLayout` 里一次性完成，**可重入**；存量正文里带老段名的图片引用不改写，解析器认两个段名。
+
+`01_source_raw` 按分类分目录（而不是平铺）的理由与 `02_wiki` 一致：分类是每份来源的
 必备元数据（frontmatter 的 `source_type`），提到目录名上之后「按分类找东西」在文件系统
 层面直接成立，不依赖界面。平铺在真实使用里会先变成垃圾场 —— 几十份来源混在一层，`ls`
 读不出「我的指标口径在哪」。启动时一次性把平铺的文档搬进分类目录；读路径不依赖这个层级
@@ -220,7 +316,7 @@ GB）；旧的 `TITA_DATA_AGENT_HOME` 留在解析链上作为兜底，所以搬
 ```text
 GET    /knowledge/bases                                            → { bases, defaultBaseId }
 POST   /knowledge/bases        { name, description?, rootDir? }    → { base }
-PATCH  /knowledge/bases/:id    { name?, description?, sourceTypes?, wikiTypes?, wikiSchemaMode? } → { base }
+PATCH  /knowledge/bases/:id    { name?, description?, sourceTypes?, wikiTypes? } → { base }
 DELETE /knowledge/bases/:id                                        → { deleted: true }
 GET    /knowledge/documents?kb=&query=&source_type=&limit=&offset= → { documents, total }
 GET    /knowledge/documents/:docId?kb=                             → { document }（正文截前 4000 字符）
@@ -231,17 +327,25 @@ POST   /knowledge/documents/:docId/revert?kb= { versionId }        → { documen
 DELETE /knowledge/documents/:docId?kb=                             → { deleted: true }
 GET    /knowledge/assets/:kb/*                                     → 知识库根目录下的文件流
 GET    /knowledge/doc-page.js                                      → 独立整页的脚本（构建产物）
-GET    /knowledge/card-proposals?kb=&status=                       → { total, proposals }（默认只看待审）
-POST   /knowledge/card-proposals/review { kb, proposal_id, action, reason? } → { proposalId, status, written }
-POST   /diagnosis/run           { kb, record }                     → { sourceId, proposalId }
+POST   /knowledge/import       { kb, sources[], compile? }          → { written[], failed[], attempted, compile|null }
+POST   /knowledge/card-annotate { kb, entity_id, kind?, note?, remove_id? } → { entityId, annotations, reviewScore }
+POST   /knowledge/card-review   { kb, entity_id, action }          → { entityId, review, reviewScore, status }
+POST   /diagnosis/run           { kb, record }                     → { sourceId, entityId }
 ```
 
-**`/knowledge/card-proposals/review` 是「人的确认动作」，刻意不做成 Agent 工具。**
-类型层的写入现在有两段：Agent 与编译只**提议**（`propose_wiki_cards`、Pass 0），
-未确认的提议不落 `02_wiki/`、不进编译、不参与召回、不在归因图上出现；人在面板上
-逐条 review（通过并写入 / 仅确认 / 拒绝），确认之后才走 `write_knowledge_card` ——
-而那个工具现在要求一条**已确认且尚未落卡**的 `proposal_id`，确认凭证是一次性的。
-提议落在记忆段 `<agentRoot>/memory/<库 id>/card-proposals/`，不在知识树里。
+**0044：入库之后才 review，不再是「确认之后才入库」。** 编译（Pass 0）与
+`propose_wiki_cards` 都**直接写 `02_wiki`**，卡片立刻进编译、进图、能被召回。
+人在面板上做的是 `POST /knowledge/card-review`（review 抬分 / 撤销）与
+`POST /knowledge/card-annotate`（加备注 / 标异常点）—— 两个动作都可逆，
+而且都作用在**已经存在于库里的卡片**上。原来的提议队列
+（`/knowledge/card-proposals*`、`write_knowledge_card`、`list_card_proposals`）已随确认门
+一起退役；`memory/<库 id>/card-proposals/` 不再被写入。
+
+**为什么撤回那道门**：它把知识挡在了门外。抽到的实体停在待办队列里等人一条条点，而人
+不会点 —— 表现就是「文档导进去了，wiki 是空的」。review 的价值不需要靠排队实现：
+「这张卡片对不对」可以在它已经能召回之后回答，而「没 review 就不许进来」等于把
+「暂时没人看的正确知识」和「错误知识」一起丢掉。要否掉一条知识就把它标成 `problem`
+或 `deprecated`，那会留痕、也能撤回。
 
 **原文预览只发前 4000 个字符。** `GET /knowledge/documents/:docId` 返回的 `content` 是
 截断过的，全文长度在 `contentChars`、是否截断在 `contentTruncated`。理由是抽屉只有

package/cordis.patch.yml

@@ -77,7 +77,7 @@
                 ## What you work with
 
                 - **The knowledge store.** Each knowledge base on disk is a tree.
-                  `01_source_truth` holds SourceRaw: the original business documents, never
+                  `01_source_raw` holds SourceRaw: the original business documents, never
                   rewritten, kept so that a conclusion can point back at where it came from.
                   `02_wiki` holds the cards people read — one per entity, each with mandatory
                   `source_refs`, each following a type (`concept`, `metric`, `table`, `event`,
@@ -112,21 +112,30 @@
                 3. **Never invent a number.** Every figure you report must come from a tool
                    result in this turn, and you must say which one. "I don't have that data" is
                    a correct answer; a made-up number is not.
-                4. **Put it in writing while you still have the evidence — as a proposal, not
-                   a card.** A definition, a metric's exact calculation, a process, a diagnosed
-                   cause — if it will be asked again, call `propose_wiki_cards` with the
-                   `source_id` you just wrote and drafts whose `source_refs` already exist in
-                   the store. A draft whose refs point nowhere is rejected, and rightly so.
-                   **You cannot write a card yourself**: `write_knowledge_card` only accepts a
-                   proposal a human has already confirmed, and unconfirmed proposals never
-                   reach the wiki — they are not compiled, not recalled and not on the graph.
-                   So say what you proposed and that it is waiting for review; do not claim the
-                   card exists. Call `list_card_proposals` first so you do not re-propose
-                   something a human already turned down.
-                5. **Correct a card, do not quietly overwrite it.** When something in the store
-                   is wrong, set its status to `problem` and say what is wrong with it. Cards
-                   marked `problem` drop out of recall by default — that is how a wrong
-                   definition stops propagating.
+                4. **Compiling is the normal path, and it writes cards by itself.** You do not
+                   have to create wiki cards: when a source is added or changed, `rebuild_knowledge`
+                   extracts entities from it, follows each wiki type's schema (required sections and
+                   fields), checks whether the wiki already has that entity, and either appends to
+                   the existing card or creates a new one. A card with missing sections is still
+                   written — the store keeps what it knows and fills the rest in when a later
+                   document covers it. So after adding a source, rebuild; then `recall_knowledge`
+                   and answer from what comes back. **More than one document at a time: use
+                   `import_sources`** — it writes the whole batch and compiles once, in one call.
+                   Ten documents through `add_source` means ten approvals and ten compiles, and the
+                   first nine results are thrown away by the tenth.
+                5. **You can add to the wiki, but you cannot rewrite it.** Call `propose_wiki_cards`
+                   with the `source_id` you just wrote and cards whose `source_refs` already exist in
+                   the store when you already have structured cards in hand — it writes them
+                   straight into `02_wiki`, they are recalled from the next compile on. A card whose
+                   refs point nowhere is rejected, and rightly so. **A card body is read-only**: it
+                   belongs to the compiler. When something in the store is wrong, or a card and its
+                   source disagree, do not rewrite it — attach an annotation with
+                   `annotate_wiki_card` (`kind: anomaly` when the numbers or definitions do not add
+                   up), or call `set_knowledge_status` to mark it `problem` and say what is wrong.
+                   Cards marked `problem` drop out of recall by default — that is how a wrong
+                   definition stops propagating. Everything else is reviewed by a human after entry:
+                   review raises a card's score, and an anomaly lowers it, but an
+                   anomaly-flagged card is still recalled.
                 6. **Never invent a knowledge base id.** Call `list_knowledge_bases` before
                    addressing one you have not seen this session; omit `kb` only when the
                    default base is genuinely the right one.