opencode-wiki-historian 0.2.0 → 0.3.0

package/README.md

@@ -7,11 +7,11 @@ opencode-historian 把 wiki.js 的读写、翻译、页型规范、迁移工具
 功能一览:
 
 * 10 个 `historian_*` 工具，覆盖创建、更新、追加、翻译、搜索、阅读、地图/时间轴、迁移、删除、移动
-* Skill v4 随插件自动注入（config hook），无需手动安装 skill 文件
+* Skill v5 随插件自动注入（config hook），无需手动安装 skill 文件
 * G1 至 G5 页型契约，每种页型对应专属骨架模板
 * 双语孪生页面（en/zh）自动翻译，翻译引擎可配置
 * 页面地图缓存、本地镜像与时间轴聚合视图
-* 开工前置查阅回路（reading loop，默认开）+ `/historian-capture` 会话留痕（默认关）
+* 开工前置查阅回路（reading loop，默认关，双信号启用）+ `/historian-capture` 会话留痕（默认关）
 * 试点与评测均通过：pilot 7 页迁移 PASS，eval 7/7 场景首跑全过
 
 ## 史官宣言 / The Historian's Manifest
@@ -49,7 +49,7 @@ SRE postmortem 文化单独值得点名：它把"事件"当一等文档对待，
 | 五柱页型 | G1 事件复盘 / G2 对比选型 / G3 清单索引 / G4 概念原理 / G5 现状账本，写前声明页型，套固定骨架、过来源列检查 | `src/templates/genres.ts`，skill Phase 1.5 |
 | 双视图 | 地图视图（en/zh 对应关系，Locale/Twin 列）+ 时间轴视图（ISO 周分组，支持 `days` 窗口与 `path` 前缀过滤，人读周表 + 机读 weeks JSON） | `historian_map` 的 `action:'show'` / `action:'timeline'` |
 | 迁移与评分门禁 | 存量页按骨架重排：dry-run 评分在前，`apply=true` 自动 pre-image 备份；每页写入后过 10 项自检门 | `historian_migrate`，`selfReviewChecklist()` |
-| 前置查阅回路 | 向每次请求的 system 提示注入"先查 wiki"指令：动这台机器的部署/历史/坑/决定之前先 `historian_search`、查 timeline、核对 G5 卡的核实日期，引用查过的页面 URL | `readingLoop` 选项（默认 `true`），`src/index.ts` 的 `experimental.chat.system.transform` 钩子 |
+| 前置查阅回路 | 向每次请求的 system 提示注入"先查 wiki"指令（单块合并：追加到最后一个 system 块，绝不产生第二条 system 消息；双信号门控：选项与本机哨兵文件同时到位才注入）：动这台机器的部署/历史/坑/决定之前先 `historian_search`、查 timeline、核对 G5 卡的核实日期，引用查过的页面 URL | `readingLoop` 选项（默认 false，开启需配置+哨兵双确认）+ 哨兵文件 `~/.config/opencode/historian-reading-loop.json`，`src/index.ts` 的 `experimental.chat.system.transform` 钩子 |
 | 主动留痕 | `/historian-capture` 命令把当前会话总结成 G1 事件页；开启 `capture.enabled` 后额外在会话空闲时弹一次提醒，仅提醒，绝不自动写页 | `src/index.ts` 的 `config` / `event` 钩子 |
 
 G5 现状卡回答"现在跑着什么"，timeline 回答"最近两周变了什么"。比如问"`service-a` 现在监听哪个端口"，应当命中现状账本里的一行（形如 `example.com:8000`，带上次核实日期与验证命令），而不是某次会话的聊天记录。这两样合起来，wiki 才从文档堆变成可查询的运维账本。
@@ -75,7 +75,18 @@ G5 现状卡回答"现在跑着什么"，timeline 回答"最近两周变了什
 
    → 分诊为事件复盘，声明 G1 → `historian_page_create`（`genre: "G1"`）→ 回报 `http://<your-wiki>:3000/team-notes/<slug>` 与它的 `/zh/` 孪生页。
 4. **检索与整理**：`historian_search` 按主题查；`historian_map` 的 `show` 看双语地图、`timeline`（可选 `days` / `path`）看最近变动；存量页不合规用 `historian_migrate` 先 dry-run 再 apply。
-5. **开关**：严格 OpenAI 兼容后端（如 vLLM，会拒绝多条 system 消息）把 `"readingLoop": false` 关掉；想要空闲留痕提醒就 `"capture": { "enabled": true }`，`/historian-capture` 命令本身与开关无关、始终注册。
+5. **开关**：reading loop 默认 false，开启需配置+哨兵双确认，两步缺一不可：
+
+   1. 插件二元组第二参数写 `"readingLoop": true`：`["opencode-wiki-historian", { "readingLoop": true }]`
+   2. 人工写入本机哨兵文件（agent 不能自我启用）：
+
+      ```bash
+      cat > ~/.config/opencode/historian-reading-loop.json <<'EOF'
+      {"version":1,"confirmed":true}
+      EOF
+      ```
+
+   任一信号缺失即不注入；配置已开而哨兵缺失时，插件加载期会打一条提示（给出哨兵路径与内容），不会静默失灵。删除哨兵文件即刻回退，无需改配置。想要空闲留痕提醒就 `"capture": { "enabled": true }`，`/historian-capture` 命令本身与开关无关、始终注册。
 
 ### 解耦声明 / Decoupling
 
@@ -131,7 +142,7 @@ opencode run --command historian --message "historian_map show"
 
 如果工具列表中出现 `historian_page_create` 等 10 个工具，安装成功。
 
-> **升级提示**：如果你之前使用过 historian v2 的扁平 skill 文件（如 `~/.config/opencode/skills/historian.md`），需要先重命名为 `historian.md.v2-disabled` 或移到别处。插件通过 config hook 自动注入 v4 skill，两个同名 skill 不能共存。
+> **升级提示**：如果你之前使用过 historian v2 的扁平 skill 文件（如 `~/.config/opencode/skills/historian.md`），需要先重命名为 `historian.md.v2-disabled` 或移到别处。插件通过 config hook 自动注入 v5 skill，两个同名 skill 不能共存。
 
 ## 配置 / Configuration
 
@@ -170,7 +181,7 @@ opencode run --command historian --message "historian_map show"
 | `translate.providerKey` | string | 未配置 | jsonc 兜底腿读取的 provider 名；须显式设置才会启用该腿 |
 | `sections` | string[] | `[]`（不限制） | 插件可操作的 wiki 路径前缀白名单 |
 | `locales` | string[] | `["en", "zh"]` | 启用的语言列表 |
-| `readingLoop` | boolean | `true` | 向每次请求注入"先查 wiki"的开工前置查阅 advisory；拒绝多条 system 消息的严格 OpenAI 兼容后端（如 vLLM）须设 `false` |
+| `readingLoop` | boolean | `false` | 开工前置查阅 advisory，向每次请求注入"先查 wiki"提示；默认 false，true 需配置+哨兵双确认（见「使用方式」开关步骤）；单块合并追加到最后一个 system 块，绝不产生第二条 system 消息，vLLM 等拒绝多条 system 的严格后端同样安全 |
 | `capture.enabled` | boolean | `false` | 开启后会话空闲时弹一次 `/historian-capture` 留痕提醒；仅提醒，不自动写页 |
 
 `translate.endpoint` 解析链（优先级从高到低）：`translate.endpoint` 选项 → 环境变量 `HISTORIAN_TRANSLATE_ENDPOINT` → 未配置。包内**不**内置任何网关地址；未配置时翻译调用直接以 `translate.endpoint not configured` 失败（见降级行为）。
@@ -196,6 +207,12 @@ opencode run --command historian --message "historian_map show"
 
 key 缺失时 `ConfigError` 记录一次日志，插件工具全部禁用，opencode 正常启动不受影响。`translate.endpoint` 未配置时双语孪生功能降级为 pending 状态（`twinReason: 'translate.endpoint not configured — ...'`），创建页面只写入请求 locale 的内容，不会发起任何翻译网络请求。
 
+### 已知限制
+
+| 现象 | 定性 | 说明 |
+|---|---|---|
+| 裸配置未传 `translate` 选项（三段 key 链 `translate.apiKey` → `DASHSCOPE_API_KEY` → `translate.providerKey` 全缺）时插件工具全部禁用 | by design | 翻译腿是写操作的前提，缺 key 时宁可整体禁用也不静默半成品；配置按上方选项全表补齐即恢复。缺配置时的部分降级（工具照常注册、仅翻译调用失败）在议 |
+
 ## wiki.js 前置检查 / Prerequisites
 
 安装插件前，确认 wiki.js 实例已完成以下配置。本插件不自动执行任何管理端操作。
@@ -279,6 +296,26 @@ zh: http://<host>/zh/ops/example
 
 更细的 20 条写作规则散布在 `skills/historian/references/` 目录下各参考文件中，agent 加载 skill 时自动读取。
 
+## 前台 / 后台 / 证据三层 / Three Content Tiers
+
+wiki 内容按读者分三层，工具按层执行不同语义（`historian_page_create` 的 `tier` 参数）：
+
+| 层 | 位置 | 职责 |
+|---|---|---|
+| 前台 (front) | 主题章节的 G1-G5 页 | 人写人读的知识页；双语孪生、进索引；只放提炼后的内容与链接 |
+| 后台 (backstage) | `_meta/` 页 + 本地镜像文件 | 机器记账：page-map 缓存页、迁移 checkpoint、reading loop 哨兵文件；不参与人读正文 |
+| 证据 (evidence) | `_evidence/` | 超 10 行原始件（日志、转写、大 diff）的归宿：单语 en、不发布（匿名访问 404 是 by design），人类页面只链接不复制 |
+
+用法示例：
+
+```jsonc
+// 大段原始材料先落证据页，再在人读页附录里给链接
+historian_page_create({ path: "_evidence/<topic>--<yyyymmdd>", tier: "evidence", content: "<原始件全文>" })
+```
+
+- **软提醒语义（soft advisory）**：写前台页时若内容含超过 30 行的围栏代码块，工具结果附一条 `advisory`，提示把原始件搬到 `_evidence/` 页、正文改放决定性摘录（每段 ≤10 行）+ 证据页链接 + 外部链接（commit/PR/告警）。提醒归提醒，写入永不阻断；证据层页自身不跑这项检查。
+- **镜像与快照页分工**：本地镜像 `~/.config/opencode/historian-map.json` 是活查询的唯一来源（`historian_map show` 直接读它）；`_meta/page-map` wiki 页是审计账本，`historian_map refresh` 每次提交一个新修订，wiki 的页面历史即全库变更时间线。
+
 ## wiki.js 用法与定制化 / Usage Guide
 
 ### Markdown 速查
@@ -348,7 +385,7 @@ wiki.js GraphQL API 有 9 个常见陷阱。插件在内部处理了每一个（
 
 1. 重命名旧 skill 文件：`mv ~/.config/opencode/skills/historian.md ~/.config/opencode/skills/historian.md.v2-disabled`
 2. 在 `opencode.json[c]` 的 `plugin` 数组中添加 `opencode-wiki-historian`
-3. 重启 opencode，`/historian` 命令可用即表示 v4 skill 已注入
+3. 重启 opencode，`/historian` 命令可用即表示 v5 skill 已注入
 
 ## 运维 / Operations
 

package/dist/chronology.js

@@ -4,6 +4,7 @@
  * Kept out of map.ts to hold both modules under the 250 pure-LOC ceiling.
  */
 import { classifyGenre } from './templates/genres.js';
+import { INTERNAL_NAMESPACES } from './tools/shared.js';
 const DAY_MS = 86_400_000;
 const WEEK_MS = 7 * DAY_MS;
 /** ISO-8601 week key: the Thursday inside the row's Monday-start week fixes
@@ -42,7 +43,12 @@ export function buildChronology(rows, opts) {
     const cutoff = opts?.days === undefined
         ? Number.NEGATIVE_INFINITY
         : (opts.now ?? new Date()).getTime() - opts.days * DAY_MS;
+    // Machine-namespace rows (INTERNAL_NAMESPACES) are dropped before grouping:
+    // the ledger page and evidence raw material are not wiki content, and their
+    // churn would drown the human timeline. All other namespaces (incl.
+    // `_sandbox`) stay visible.
     const kept = rows
+        .filter((r) => !INTERNAL_NAMESPACES.includes(r.path.split('/')[0]))
         .map((r) => ({ r, t: Date.parse(r.updatedAt) }))
         .filter((x) => !Number.isNaN(x.t) && x.t >= cutoff)
         .sort((a, b) => b.t - a.t ||

package/dist/config.d.ts

@@ -37,9 +37,12 @@ export interface HistorianOptions {
      *  real authorization gate. Consumers must treat [] as allow-any. */
     readonly sections: readonly string[];
     readonly locales: readonly string[];
-    /** v2 reading-loop gate: true (the shipped default) makes the plugin push a
-     *  consult-the-wiki advisory block into every chat request's system array via
-     *  the experimental.chat.system.transform hook. false = hook is a pure no-op. */
+    /** v3 reading-loop gate (double signal): false by default. The plugin pushes
+     *  a consult-the-wiki advisory block into every chat request's system array
+     *  via the experimental.chat.system.transform hook ONLY when this option is
+     *  true AND the local confirmation sentinel agrees (src/loop-state.ts:
+     *  ~/.config/opencode/historian-reading-loop.json, written by hand).
+     *  默认 false，true 需配置+哨兵双确认；either signal missing = pure no-op. */
     readonly readingLoop: boolean;
     /** v2 capture gate: reminder-only. When enabled the event hook fires one
      *  TUI toast per idle session nudging the agent/user to run the
@@ -79,8 +82,9 @@ export declare const DEFAULT_TRANSLATE_MODEL = "qwen3.7-plus";
 /** Empty = no path-prefix restriction (see HistorianOptions.sections). */
 export declare const DEFAULT_SECTIONS: readonly string[];
 export declare const DEFAULT_LOCALES: readonly ["en", "zh"];
-/** Reading loop is on unless explicitly disabled (plan v2 todo 8). */
-export declare const DEFAULT_READING_LOOP = true;
+/** Reading loop is opt-in: activated only when configured true AND the local
+ *  sentinel confirms it (plan v3 todo 1; see src/loop-state.ts). */
+export declare const DEFAULT_READING_LOOP = false;
 /** Capture reminders are opt-in (plan v2 todo 9). */
 export declare const DEFAULT_CAPTURE_ENABLED = false;
 /**

package/dist/config.js

@@ -27,8 +27,9 @@ export const DEFAULT_TRANSLATE_MODEL = 'qwen3.7-plus';
 /** Empty = no path-prefix restriction (see HistorianOptions.sections). */
 export const DEFAULT_SECTIONS = [];
 export const DEFAULT_LOCALES = ['en', 'zh'];
-/** Reading loop is on unless explicitly disabled (plan v2 todo 8). */
-export const DEFAULT_READING_LOOP = true;
+/** Reading loop is opt-in: activated only when configured true AND the local
+ *  sentinel confirms it (plan v3 todo 1; see src/loop-state.ts). */
+export const DEFAULT_READING_LOOP = false;
 /** Capture reminders are opt-in (plan v2 todo 9). */
 export const DEFAULT_CAPTURE_ENABLED = false;
 // --- Resolution -------------------------------------------------------------

package/dist/index.d.ts

@@ -8,8 +8,11 @@
  *   - config: mutates cfg.skills.paths to ship the bundled skills/ directory
  *     and registers the /historian-capture command (todo 9)
  *   - tool: 10 historian_* tools wired by buildTools(opts)
- *   - experimental.chat.system.transform: pushes the historian-first reading
- *     loop advisory onto output.system[] (gated by opts.readingLoop)
+ *   - experimental.chat.system.transform: merges the historian-first reading
+ *     loop advisory into the LAST system block (single-block-safe append — a
+ *     second entry is never added). v3 double gate: 默认 false，true 需配置+哨兵双确认.
+ *     Both the readingLoop option and the on-machine confirmation sentinel
+ *     (src/loop-state.ts, re-read per request, never cached) must pass.
  *   - event: on session.idle emits ONE capture reminder toast per session
  *     (gated by opts.capture.enabled; reminder-only — the page write happens
  *     through /historian-capture -> historian_page_create, never here)

package/dist/index.js

@@ -8,8 +8,11 @@
  *   - config: mutates cfg.skills.paths to ship the bundled skills/ directory
  *     and registers the /historian-capture command (todo 9)
  *   - tool: 10 historian_* tools wired by buildTools(opts)
- *   - experimental.chat.system.transform: pushes the historian-first reading
- *     loop advisory onto output.system[] (gated by opts.readingLoop)
+ *   - experimental.chat.system.transform: merges the historian-first reading
+ *     loop advisory into the LAST system block (single-block-safe append — a
+ *     second entry is never added). v3 double gate: 默认 false，true 需配置+哨兵双确认.
+ *     Both the readingLoop option and the on-machine confirmation sentinel
+ *     (src/loop-state.ts, re-read per request, never cached) must pass.
  *   - event: on session.idle emits ONE capture reminder toast per session
  *     (gated by opts.capture.enabled; reminder-only — the page write happens
  *     through /historian-capture -> historian_page_create, never here)
@@ -22,7 +25,9 @@
  * contract.
  */
 import { fileURLToPath } from 'url';
+import { homedir } from 'node:os';
 import { resolveOptions } from './config.js';
+import { isReadingLoopConfirmed, loopStatePath } from './loop-state.js';
 import { buildTools } from './tools.js';
 /** Resolve the absolute path to the bundled skills/ directory. Uses
  *  import.meta.url so it works whether loaded from dist/ (compiled) or src/
@@ -55,8 +60,9 @@ const CAPTURE_COMMAND_TEMPLATE = [
     '',
     '1. Draft four sections: 过程/Process (what was done, in order), 原因/Cause (why it was needed), 后果/Consequence (impact, artifacts), 改进/Improvement (follow-ups, preventions).',
     "2. Run historian_map action:'show' to see existing sections, then choose a short factual path under one.",
-    '3. Save with historian_page_create (genre "G1"); the zh twin is auto-created. If the session only repeated known knowledge, say so and skip writing.',
-    '4. Echo both page URLs (en + zh) back to the user.',
+    '3. If the session produced raw artifacts (logs, transcripts, big diffs), first store each via historian_page_create with tier:"evidence" under `_evidence/`, then cite those URLs in the G1 appendix.',
+    '4. Save with historian_page_create (genre "G1"); the zh twin is auto-created. If the session only repeated known knowledge, say so and skip writing.',
+    '5. Echo both page URLs (en + zh) back to the user.',
 ].join('\n');
 const CAPTURE_TOAST_MESSAGE = '会话空闲：有值得留存的决定/修复/踩坑就跑 /historian-capture。Session idle — run /historian-capture if it produced decisions, fixes, or pitfalls worth keeping.';
 async function server(input, options) {
@@ -71,6 +77,14 @@ async function server(input, options) {
         console.error('[opencode-historian] Failed to resolve plugin options; tools disabled.', err instanceof Error ? err.message : err);
         return {};
     }
+    // Once per plugin load (never in the per-request hot path): a config-only
+    // opt-in leaves the loop dark because this machine has not confirmed it —
+    // point at the missing second signal instead of silently no-oping forever.
+    if (opts.readingLoop === true && !isReadingLoopConfirmed(homedir())) {
+        console.error('[opencode-historian] readingLoop enabled in config but not confirmed on this machine; to activate, create ' +
+            loopStatePath(homedir()) +
+            ' with {"version":1,"confirmed":true}');
+    }
     const captureReminded = new Set();
     const hooks = {
         config: async (cfg) => {
@@ -90,9 +104,19 @@ async function server(input, options) {
             try {
                 if (opts.readingLoop !== true)
                     return;
+                if (!isReadingLoopConfirmed(homedir()))
+                    return;
                 if (output.system.some((block) => block.includes('historian_search')))
                     return;
-                output.system.push(READING_LOOP_ADVISORY);
+                if (output.system.length === 0) {
+                    output.system.push(READING_LOOP_ADVISORY);
+                }
+                else {
+                    // Single-block-safe merge: a second system entry makes strict chat
+                    // templates (e.g. vLLM) reject the request with HTTP 400.
+                    const last = output.system.length - 1;
+                    output.system[last] += '\n\n' + READING_LOOP_ADVISORY;
+                }
             }
             catch (err) {
                 // A broken inject must never crash a chat request (plan v2 todo 8).

package/dist/loop-state.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Sentinel state for the v3 reading loop (double gate, config + machine).
+ *
+ * The reading loop activates only when BOTH signals agree: the plugin option
+ * `readingLoop: true` (see src/config.ts) and a confirmation sentinel written
+ * BY HAND on this machine at '<home>/.config/opencode/historian-reading-loop.json'
+ * holding {"version":1,"confirmed":true}. Agent self-enablement is forbidden by
+ * design, so the reader here is deliberately tolerant: a missing file, bad
+ * JSON, wrong shape, mismatched version, or any read error yields false.
+ * This function NEVER throws.
+ *
+ * The home directory is an injectable parameter so unit tests drive fixtures
+ * under tmp dirs; the real ~/.config is never touched (same discipline as
+ * src/config.ts / test/config.test.ts).
+ */
+/** Sentinel schema version accepted by the reader (strict equality, not truthy). */
+export declare const LOOP_STATE_VERSION = 1;
+/** Path of the human-written reading-loop confirmation sentinel under a home dir. */
+export declare function loopStatePath(home: string): string;
+/**
+ * True only when the sentinel exists and parses to an object with
+ * version === LOOP_STATE_VERSION and confirmed === true (both strict).
+ * Parsed via parseJsonc, so comments in the sentinel are a bonus feature.
+ *
+ * Pure-sync and intentionally NOT cached: callers re-check per request so a
+ * mid-session sentinel write or removal takes effect immediately.
+ */
+export declare function isReadingLoopConfirmed(home: string): boolean;

package/dist/loop-state.js

@@ -0,0 +1,46 @@
+/**
+ * Sentinel state for the v3 reading loop (double gate, config + machine).
+ *
+ * The reading loop activates only when BOTH signals agree: the plugin option
+ * `readingLoop: true` (see src/config.ts) and a confirmation sentinel written
+ * BY HAND on this machine at '<home>/.config/opencode/historian-reading-loop.json'
+ * holding {"version":1,"confirmed":true}. Agent self-enablement is forbidden by
+ * design, so the reader here is deliberately tolerant: a missing file, bad
+ * JSON, wrong shape, mismatched version, or any read error yields false.
+ * This function NEVER throws.
+ *
+ * The home directory is an injectable parameter so unit tests drive fixtures
+ * under tmp dirs; the real ~/.config is never touched (same discipline as
+ * src/config.ts / test/config.test.ts).
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseJsonc, isRecord } from './jsonc.js';
+/** Sentinel schema version accepted by the reader (strict equality, not truthy). */
+export const LOOP_STATE_VERSION = 1;
+/** Path of the human-written reading-loop confirmation sentinel under a home dir. */
+export function loopStatePath(home) {
+    return join(home, '.config', 'opencode', 'historian-reading-loop.json');
+}
+/**
+ * True only when the sentinel exists and parses to an object with
+ * version === LOOP_STATE_VERSION and confirmed === true (both strict).
+ * Parsed via parseJsonc, so comments in the sentinel are a bonus feature.
+ *
+ * Pure-sync and intentionally NOT cached: callers re-check per request so a
+ * mid-session sentinel write or removal takes effect immediately.
+ */
+export function isReadingLoopConfirmed(home) {
+    const path = loopStatePath(home);
+    let parsed;
+    try {
+        parsed = parseJsonc(readFileSync(path, 'utf8'), path);
+    }
+    catch {
+        return false; // missing file, unreadable, or malformed JSONC — all mean "not confirmed"
+    }
+    if (!isRecord(parsed)) {
+        return false; // top-level array / string / number / null — wrong shape
+    }
+    return parsed.version === LOOP_STATE_VERSION && parsed.confirmed === true;
+}

package/dist/map.d.ts

@@ -1,6 +1,12 @@
 /**
  * Locale-aware page map (todo 10): full cross-locale inventory with en/zh twin
  * pairing, rendered as the markdown `_meta/page-map` cache page + local mirror.
+ *
+ * Intended readers: harness cache-read scripts, the admin UI, and
+ * remote/cross-machine review. Role split — live queries (getMap) read the
+ * LOCAL MIRROR (historian-map.json) only and never this wiki page; the wiki
+ * page exists as the audit ledger (each refresh commits a new revision) and
+ * for human inspection.
  */
 import type { HistorianOptions } from './config.js';
 import type { GqlClient } from './wiki/client.js';
@@ -40,7 +46,7 @@ export declare function mirrorPath(home: string): string;
  *  namespace pages are excluded — they are not anonymously reachable), twins
  *  paired by exact path, rows sorted by path then locale. */
 export declare function buildPageMap(deps: MapDeps): Promise<PageMap>;
-export declare function renderMapMarkdown(rows: readonly MapRow[]): string;
+export declare function renderMapMarkdown(rows: readonly MapRow[], generatedAt: string): string;
 export interface RefreshOptions {
     readonly now?: Date;
     readonly homeDir?: string;

package/dist/map.js

@@ -1,6 +1,12 @@
 /**
  * Locale-aware page map (todo 10): full cross-locale inventory with en/zh twin
  * pairing, rendered as the markdown `_meta/page-map` cache page + local mirror.
+ *
+ * Intended readers: harness cache-read scripts, the admin UI, and
+ * remote/cross-machine review. Role split — live queries (getMap) read the
+ * LOCAL MIRROR (historian-map.json) only and never this wiki page; the wiki
+ * page exists as the audit ledger (each refresh commits a new revision) and
+ * for human inspection.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -89,9 +95,17 @@ export async function buildPageMap(deps) {
     return { rows, stats: { rows: rows.length, paths: sortedPaths.length, perLocale: perLocaleCounts, missingTwinPaths } };
 }
 // --- renderMapMarkdown ------------------------------------------------------
-export function renderMapMarkdown(rows) {
+export function renderMapMarkdown(rows, generatedAt) {
+    const perLocale = { en: 0, zh: 0 };
+    for (const r of rows)
+        if (r.locale === 'en' || r.locale === 'zh')
+            perLocale[r.locale] += 1;
+    const preamble = `> Snapshot generated ${generatedAt} · ${rows.length} pages (${perLocale.en}/${perLocale.zh}). ` +
+        `This page is the audit ledger: each 'historian_map refresh' commits a new wiki revision (page ` +
+        `history = chronological record of the whole wiki). Live queries read the local mirror ` +
+        `(historian-map.json); this page serves harness audits, the admin UI, and cross-machine review.`;
     const lines = rows.map((r) => `| ${r.id} | ${r.locale} | ${r.path} | ${r.title.replaceAll('|', '\\|')} | ${r.url} | ${r.twinUrl ?? '—'} | ${r.updatedAt} |`);
-    return [HEADER_ROW, '| --- | --- | --- | --- | --- | --- | --- |', ...lines, ''].join('\n');
+    return [preamble, '', HEADER_ROW, '| --- | --- | --- | --- | --- | --- | --- |', ...lines, ''].join('\n');
 }
 // --- Local mirror -----------------------------------------------------------
 function writeMirror(home, mirror) {
@@ -159,7 +173,7 @@ export async function refreshMapCache(deps, opts) {
     const home = opts?.homeDir ?? homedir();
     const { rows, stats } = await buildPageMap(deps);
     writeMirror(home, { generatedAt: now.toISOString(), rows, stats });
-    const markdown = renderMapMarkdown(rows);
+    const markdown = renderMapMarkdown(rows, now.toISOString());
     const existing = await readPage(deps.client, CACHE_PATH, 'en');
     if (existing === null) {
         await createPage(deps, {

package/dist/templates/evidence.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Machine-tier evidence page skeleton (v3 todo 5).
+ *
+ * Evidence pages live under the internal namespaces (`_meta/`, `_evidence/`),
+ * are hidden and monolingual — the wiki is their only store (no local mirror,
+ * no bilingual twin machinery). They are deliberately NOT genre-templated:
+ * the G1–G5 anatomy rubric targets human front pages, while an evidence page
+ * is a verbatim capture plus provenance, and nothing else.
+ *
+ * The shape mirrors the `_meta/page-map` cache precedent (src/map.ts): header
+ * blockquote with source/captured/context metadata, an empty fenced block the
+ * caller fills with the raw material verbatim, and a capture-context section
+ * whose three placeholder lines the caller replaces at capture time.
+ */
+export interface EvidenceSkeletonInput {
+    /** Path of the human page this evidence backs (placeholder hint when unknown). */
+    readonly sourcePath: string;
+    /** URL of that human page. */
+    readonly sourceUrl: string;
+    /** ISO-8601 capture timestamp, supplied by the caller (pure function: no clock reads). */
+    readonly capturedAt: string;
+    /** One-line context for why this material was captured. */
+    readonly context: string;
+}
+/** Full markdown skeleton for one machine-tier evidence page. Pure string
+ *  transform — deterministic, no state, no I/O; empty inputs degrade to
+ *  visible placeholders, never `undefined` leakage. */
+export declare function evidenceSkeleton(o: EvidenceSkeletonInput): string;

package/dist/templates/evidence.js

@@ -0,0 +1,34 @@
+/**
+ * Machine-tier evidence page skeleton (v3 todo 5).
+ *
+ * Evidence pages live under the internal namespaces (`_meta/`, `_evidence/`),
+ * are hidden and monolingual — the wiki is their only store (no local mirror,
+ * no bilingual twin machinery). They are deliberately NOT genre-templated:
+ * the G1–G5 anatomy rubric targets human front pages, while an evidence page
+ * is a verbatim capture plus provenance, and nothing else.
+ *
+ * The shape mirrors the `_meta/page-map` cache precedent (src/map.ts): header
+ * blockquote with source/captured/context metadata, an empty fenced block the
+ * caller fills with the raw material verbatim, and a capture-context section
+ * whose three placeholder lines the caller replaces at capture time.
+ */
+/** Full markdown skeleton for one machine-tier evidence page. Pure string
+ *  transform — deterministic, no state, no I/O; empty inputs degrade to
+ *  visible placeholders, never `undefined` leakage. */
+export function evidenceSkeleton(o) {
+    return [
+        `> 机器层证据页 (machine-tier evidence). 来源页 (source): [${o.sourcePath}](${o.sourceUrl})` +
+            ` · 采集 (captured): ${o.capturedAt} · 上下文 (context): ${o.context}`,
+        '',
+        '## 原文 (verbatim)',
+        '',
+        '```',
+        '```',
+        '',
+        '## 采集环境 (capture context)',
+        '',
+        '- 命令 (command): `<the exact command as executed>`',
+        '- 目录 (cwd): `<working directory at capture time>`',
+        '- 时间 (time): `<capture timestamp>`',
+    ].join('\n');
+}

package/dist/templates/skeletons.js

@@ -106,7 +106,7 @@ export const G1_ZH = `# 页面标题（占位：写完后替换为实际标题
 
 ## 附录
 
-<!-- 原始证据：告警截图、日志片段、commit/PR 链接。脚注示例： -->
+<!-- 决定性摘录（每段 ≤10 行）+ 证据页链接（\`_evidence/...\`，historian_page_create tier:"evidence" 建页）+ 外部链接（commit/PR/告警）。脚注示例： -->
 见脚注[^1]。
 
 [^1]: 来源链接（替换为真实出处）
@@ -197,7 +197,7 @@ export const G1_EN = `# Page Title (placeholder: replace with the real title, mu
 
 ## Appendix
 
-<!-- Raw evidence: alert screenshots, log excerpts, commit/PR links. Footnote example: -->
+<!-- Decisive excerpts (≤10 lines each) + evidence-page links (\`_evidence/...\`, created via historian_page_create with tier:"evidence") + external links (commits/PRs/alerts). Footnote example: -->
 See footnote[^1].
 
 [^1]: Source link (replace with the real source)
@@ -500,7 +500,7 @@ export const G5_ZH = `# 页面标题（占位：写完后替换为实际标题
 | --- | --- | --- |
 | YYYY-MM-DD | 初版快照 | — |
 
-<!-- 追加式小表：只记影响清单行的变更。完整历史写 G1 事件页并互链。 -->
+<!-- 追加式小表：只记影响清单行的变更。完整历史写 G1 事件页并互链；「依据」可指向证据页 URL（\`_evidence/...\`）。 -->
 
 ## 相关页面
 
@@ -551,7 +551,7 @@ export const G5_EN = `# Page Title (placeholder: replace with the real title, mu
 | --- | --- | --- |
 | YYYY-MM-DD | initial snapshot | — |
 
-<!-- Append-only mini table for list-affecting changes. Full history lives in G1 event pages. -->
+<!-- Append-only mini table for list-affecting changes. Full history lives in G1 event pages; Evidence may point at an evidence-page URL (\`_evidence/...\`). -->
 
 ## Related Pages
 

package/dist/tools/create.js

@@ -8,7 +8,8 @@ import { tool } from '@opencode-ai/plugin';
 import { validatePath } from '../wiki/locale.js';
 import { createPage } from '../wiki/pages.js';
 import { classifyGenre, genreSkeleton } from '../templates/genres.js';
-import { errEnvelope, okJson, urlPair, URL_MANDATE, pageDeps } from './shared.js';
+import { evidenceSkeleton } from '../templates/evidence.js';
+import { enforceTierPath, errEnvelope, frontDumpAdvisory, MACHINE_TIER_NOTE, okJson, pageDeps, tierMismatchJson, TIERS, urlPair, URL_MANDATE, } from './shared.js';
 const s = tool.schema;
 const GENRES = ['G1', 'G2', 'G3', 'G4', 'G5'];
 const ARGS_SHAPE = {
@@ -21,6 +22,7 @@ const ARGS_SHAPE = {
     tags: s.array(s.string()).default([]),
     twin: s.boolean().default(true).describe('Auto-create the opposite-locale twin via translation'),
     description: s.string().optional(),
+    tier: s.enum(TIERS).default('front').describe('front = bilingual human page; evidence = machine page under _meta/ or _evidence/ (hidden, unpublished, monolingual en)'),
 };
 const ArgsSchema = s.object(ARGS_SHAPE);
 export function makeCreateTool(deps) {
@@ -31,42 +33,78 @@ export function makeCreateTool(deps) {
         args: ARGS_SHAPE,
         execute: async (raw) => {
             const args = ArgsSchema.parse(raw);
+            const tier = args.tier;
             try {
                 validatePath(args.path);
             }
             catch (err) {
                 return errEnvelope(err);
             }
+            const mismatch = enforceTierPath(tier, args.path);
+            if (mismatch !== null)
+                return tierMismatchJson(mismatch);
+            // Evidence pages are monolingual en: a zh locale is FORCED to en with an
+            // envelope hint — plan ruling: hint, never throw.
+            const isEvidence = tier === 'evidence';
+            const locale = isEvidence ? 'en' : args.locale;
+            const localeHint = isEvidence && args.locale === 'zh'
+                ? 'evidence pages are monolingual en — the locale argument was forced to "en"'
+                : undefined;
             if (args.content === undefined || args.content.trim() === '') {
+                if (isEvidence) {
+                    // Evidence pages are not genre-templated: echo the machine skeleton.
+                    // The source page is unknown at template time, so the fields ship as
+                    // placeholder hints; the description arg (if given) is the context hint.
+                    return okJson({
+                        mode: 'template',
+                        locale,
+                        skeleton: evidenceSkeleton({
+                            sourcePath: '<human-page-path>',
+                            sourceUrl: '<human-page-url>',
+                            capturedAt: new Date().toISOString(),
+                            context: args.description ?? '<one-line context>',
+                        }),
+                        note: 'Nothing was written to the wiki (template mode, no content). Paste the raw material verbatim ' +
+                            'into the 原文 fence, replace the <human-page-path> / <human-page-url> / <one-line context> ' +
+                            'placeholders with the citing human page, then call historian_page_create again with tier:"evidence" and content.',
+                        ...(localeHint === undefined ? {} : { localeHint }),
+                    });
+                }
                 const genre = args.genre ?? classifyGenre({ title: args.title, body: args.description ?? '' }).genre;
                 return okJson({
                     mode: 'template',
                     genre,
-                    locale: args.locale,
-                    skeleton: genreSkeleton(genre, args.locale),
+                    locale,
+                    skeleton: genreSkeleton(genre, locale),
                     note: 'Nothing was written to the wiki (template mode, no content). Fill the skeleton and call historian_page_create again with content.',
+                    ...(localeHint === undefined ? {} : { localeHint }),
                 });
             }
             try {
                 const result = await createPage(pageDeps(deps), {
                     path: args.path,
-                    locale: args.locale,
+                    locale,
                     title: args.title,
                     content: args.content,
-                    tags: args.tags,
-                    isPublished: args.isPublished,
-                    twin: args.twin,
+                    tags: isEvidence ? [...new Set([...args.tags, 'evidence'])] : args.tags,
+                    isPublished: isEvidence ? false : args.isPublished,
+                    isPrivate: isEvidence,
+                    twin: isEvidence ? false : args.twin,
                     description: args.description,
                 });
+                const advisory = frontDumpAdvisory(tier, args.content);
                 return okJson({
                     mode: 'create',
                     path: args.path,
-                    locale: args.locale,
+                    locale,
                     pageId: result.pageId,
                     twinStatus: result.twinStatus,
                     twinReason: result.twinReason,
                     twinId: result.twinId,
                     urls: urlPair(result),
+                    ...(isEvidence ? { note: MACHINE_TIER_NOTE } : {}),
+                    ...(localeHint === undefined ? {} : { localeHint }),
+                    ...(advisory === null ? {} : { advisory }),
                 });
             }
             catch (err) {

package/dist/tools/local.js

@@ -62,7 +62,8 @@ const MapArgsSchema = s.object(MAP_ARGS);
 export function makeMapTool(deps) {
     return tool({
         description: `Inspect (show), rebuild (refresh), or aggregate recent updates (timeline) over the en/zh page map ` +
-            `with its local mirror + _meta/page-map cache page. ` +
+            `with its local mirror + _meta/page-map cache page. Two roles: the local mirror is the live query ` +
+            `source for show/timeline; the wiki page is the audit ledger (every refresh commits a new wiki revision). ` +
             `show reads the local mirror (zero writes); refresh rebuilds from the wiki and writes the mirror + cache page ` +
             `(idempotent — the engine upserts via full RMW); timeline groups mirror rows by ISO week (newest first, ` +
             `optional days window + section/path prefix filter) into a human markdown table + machine-readable weeks JSON. ` +

package/dist/tools/shared.d.ts

@@ -50,3 +50,30 @@ export declare function okJson(body: Record<string, unknown>): ToolResult;
 export declare function errEnvelope(err: unknown): ToolResult;
 /** Destructive-action gate: refusal BEFORE any fetch when confirm is absent. */
 export declare function confirmRequiredJson(toolName: string, got: unknown): ToolResult;
+/** Machine namespaces: pages whose first path segment lives here are hidden
+ *  machine-tier pages (the `_meta/page-map` cache precedent in src/map.ts —
+ *  isPublished:false + isPrivate:true + tags + twin:false). */
+export declare const INTERNAL_NAMESPACES: readonly ["_meta", "_evidence"];
+/** Plan-mandated note on every evidence-tier success envelope (verbatim). */
+export declare const MACHINE_TIER_NOTE = "machine-tier page; anonymous visits 404 by design";
+/** Tier enum values — single source of truth. The zod schema itself must be
+ *  declared locally per tool via `s.enum(TIERS)`: exporting a zod value from
+ *  here breaks declaration emit (TS2742 — tool.schema is zod 4.1.8 nested in
+ *  @opencode-ai/plugin, unnameable without a zod import, and root zod is v3). */
+export declare const TIERS: readonly ["front", "evidence"];
+/** Page tier: 'front' = bilingual human surface; 'evidence' = machine namespace. */
+export type Tier = (typeof TIERS)[number];
+/** True when the path's first segment is an internal (machine) namespace. */
+export declare function isInternalPath(path: string): boolean;
+/** Pure tier↔path guard: null when the pair is legal, an error string when
+ *  not (evidence ⇒ internal namespace; front ⇒ NOT internal). */
+export declare function enforceTierPath(tier: Tier, path: string): string | null;
+/** Tier↔path mismatch → uniform failure envelope (no fetch has run yet). */
+export declare function tierMismatchJson(message: string): ToolResult;
+/** Evidence-tier zh-side input → refusal envelope (monolingual invariant). */
+export declare function monolingualRefusalJson(toolName: string, argumentName: string): ToolResult;
+/** Soft-gate advisory for front-tier raw dumps: null when nothing to say
+ *  (evidence tier NEVER checked — machine pages are the raw-material home;
+ *  fence at or under the limit). The advisory is informational only: every
+ *  caller still performs the write. */
+export declare function frontDumpAdvisory(tier: Tier, content: string): string | null;

package/dist/tools/shared.js

@@ -85,3 +85,103 @@ function hintFor(errorKind) {
             return 'Inspect the message and retry.';
     }
 }
+// --- Tier plumbing (v3 todo 4) ------------------------------------------------
+/** Machine namespaces: pages whose first path segment lives here are hidden
+ *  machine-tier pages (the `_meta/page-map` cache precedent in src/map.ts —
+ *  isPublished:false + isPrivate:true + tags + twin:false). */
+export const INTERNAL_NAMESPACES = ['_meta', '_evidence'];
+/** Plan-mandated note on every evidence-tier success envelope (verbatim). */
+export const MACHINE_TIER_NOTE = 'machine-tier page; anonymous visits 404 by design';
+/** Tier enum values — single source of truth. The zod schema itself must be
+ *  declared locally per tool via `s.enum(TIERS)`: exporting a zod value from
+ *  here breaks declaration emit (TS2742 — tool.schema is zod 4.1.8 nested in
+ *  @opencode-ai/plugin, unnameable without a zod import, and root zod is v3). */
+export const TIERS = ['front', 'evidence'];
+/** True when the path's first segment is an internal (machine) namespace. */
+export function isInternalPath(path) {
+    const first = path.split('/')[0];
+    return INTERNAL_NAMESPACES.includes(first);
+}
+/** Pure tier↔path guard: null when the pair is legal, an error string when
+ *  not (evidence ⇒ internal namespace; front ⇒ NOT internal). */
+export function enforceTierPath(tier, path) {
+    const internal = isInternalPath(path);
+    switch (tier) {
+        case 'evidence':
+            return internal
+                ? null
+                : `tier "evidence" requires a machine namespace path (${INTERNAL_NAMESPACES.map((n) => `${n}/`).join(' or ')}) — got '${path}'`;
+        case 'front':
+            return internal
+                ? `tier "front" cannot write to the machine namespace '${path}' — use tier "evidence" for ${INTERNAL_NAMESPACES.map((n) => `${n}/`).join(' or ')} paths`
+                : null;
+    }
+}
+/** Tier↔path mismatch → uniform failure envelope (no fetch has run yet). */
+export function tierMismatchJson(message) {
+    return dump({
+        ok: false,
+        error: 'tier-path-mismatch',
+        errorKind: 'TierPathMismatchError',
+        message,
+        actionableHint: 'Pass the tier that matches the path namespace: _meta/ and _evidence/ are machine (evidence) paths; everything else is front.',
+    });
+}
+/** Evidence-tier zh-side input → refusal envelope (monolingual invariant). */
+export function monolingualRefusalJson(toolName, argumentName) {
+    return dump({
+        ok: false,
+        error: 'evidence-monolingual',
+        errorKind: 'TierMonolingualError',
+        message: `${toolName} received "${argumentName}" on an evidence-tier page, which is monolingual en`,
+        actionableHint: 'Drop the zh-side argument (locale "zh" / sectionZh) — evidence machine pages never carry a bilingual twin.',
+    });
+}
+// --- Front-tier raw-dump soft gate (v3 todo 6) --------------------------------
+/** Contract band (SKILL.md SYN-16): a human page stays a 5-10 line excerpt;
+ *  longer raw material belongs on an evidence page. Strictly ABOVE this many
+ *  fence-interior lines triggers the advisory — 30 is the soft gate, never a
+ *  hard refusal. Deliberately layered vs the contract bands; do not unify. */
+const FRONT_DUMP_FENCE_LIMIT = 30;
+/** Longest fenced code block in the content, counting lines STRICTLY inside
+ *  the ``` fences (fence markers excluded). An unterminated fence counts to
+ *  EOF. Fences opening at line start (after optional indentation) close on
+ *  the next ```-leading line. */
+function longestFenceLines(content) {
+    let longest = 0;
+    let inside = false;
+    let count = 0;
+    for (const line of content.split('\n')) {
+        if (line.trimStart().startsWith('```')) {
+            if (inside) {
+                if (count > longest)
+                    longest = count;
+                inside = false;
+                count = 0;
+            }
+            else {
+                inside = true;
+                count = 0;
+            }
+        }
+        else if (inside) {
+            count++;
+        }
+    }
+    if (inside && count > longest)
+        longest = count; // unterminated fence → EOF
+    return longest;
+}
+/** Soft-gate advisory for front-tier raw dumps: null when nothing to say
+ *  (evidence tier NEVER checked — machine pages are the raw-material home;
+ *  fence at or under the limit). The advisory is informational only: every
+ *  caller still performs the write. */
+export function frontDumpAdvisory(tier, content) {
+    if (tier !== 'front')
+        return null;
+    const lines = longestFenceLines(content);
+    if (lines <= FRONT_DUMP_FENCE_LIMIT)
+        return null;
+    return (`content contains a ${lines}-line fenced block; per contract, move raw material to a ` +
+        `tier:"evidence" page under _evidence/ and link it from the human page (SYN-16)`);
+}

package/dist/tools/write.js

@@ -7,7 +7,7 @@
 import { tool } from '@opencode-ai/plugin';
 import { appendSection, createPage, updatePage, PageNotFoundError } from '../wiki/pages.js';
 import { readPage } from '../wiki/pages.read.js';
-import { errEnvelope, okJson, urlPair, URL_MANDATE, pageDeps } from './shared.js';
+import { enforceTierPath, errEnvelope, frontDumpAdvisory, isInternalPath, MACHINE_TIER_NOTE, monolingualRefusalJson, okJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, pageDeps, } from './shared.js';
 const s = tool.schema;
 const UPDATE_ARGS = {
     path: s.string(),
@@ -36,6 +36,7 @@ export function makeUpdateTool(deps) {
                     description: args.description,
                     tags: args.tags,
                 });
+                const advisory = frontDumpAdvisory(inferredTier(page.path), args.content ?? '');
                 return okJson({
                     mode: 'update',
                     path: args.path,
@@ -51,6 +52,7 @@ export function makeUpdateTool(deps) {
                         updatedAt: result.page.updatedAt,
                     },
                     urls: urlPair(result),
+                    ...(advisory === null ? {} : { advisory }),
                 });
             }
             catch (err) {
@@ -59,6 +61,11 @@ export function makeUpdateTool(deps) {
         },
     });
 }
+/** Path-only tier resolution (same rule the append fallback uses): an
+ *  internal namespace first segment ⇒ evidence, anything else ⇒ front. */
+function inferredTier(path) {
+    return isInternalPath(path) ? 'evidence' : 'front';
+}
 async function bootstrapTwin(deps, primary, section, source) {
     const translate = source === 'translate' ? deps.translate : undefined;
     try {
@@ -84,21 +91,40 @@ const APPEND_ARGS = {
     section: s.string(),
     locale: s.enum(['en', 'zh']).default('en'),
     sectionZh: s.string().optional().describe('Explicit zh section; when absent the zh side falls back to translation/wiring'),
+    tier: s.enum(TIERS).optional().describe('Explicit tier; absent → inferred from the path (first segment _meta/ or _evidence/ ⇒ evidence, else front)'),
 };
 const AppendArgsSchema = s.object(APPEND_ARGS);
 export function makeAppendTool(deps) {
     return tool({
         description: `Append a section to an existing page (engine append + RMW). For the en page with a MISSING zh twin, ` +
             `the twin is auto-created — from sectionZh when given, else translated when the translator is wired. ` +
+            `Evidence-tier pages (_meta/ or _evidence/) are monolingual en — no twin handling. ` +
             `${URL_MANDATE}.`,
         args: APPEND_ARGS,
         execute: async (raw) => {
             const args = AppendArgsSchema.parse(raw);
+            // Exactly ONE resolution rule: explicit tier arg wins; otherwise infer
+            // from the path prefix (internal namespace ⇒ evidence).
+            const tier = args.tier ?? inferredTier(args.path);
+            const mismatch = enforceTierPath(tier, args.path);
+            if (mismatch !== null)
+                return tierMismatchJson(mismatch);
+            const isEvidence = tier === 'evidence';
+            if (isEvidence && args.locale === 'zh') {
+                return monolingualRefusalJson('historian_page_append', 'locale "zh"');
+            }
+            if (isEvidence && args.sectionZh !== undefined) {
+                return monolingualRefusalJson('historian_page_append', 'sectionZh');
+            }
             try {
                 const appended = await appendSection(pageDeps(deps), args.path, args.locale, args.section);
                 let zhStatus;
                 let zhNote;
-                if (args.locale === 'zh') {
+                if (isEvidence) {
+                    zhStatus = 'skipped';
+                    zhNote = 'evidence tier is monolingual en — no zh twin is bootstrapped or touched.';
+                }
+                else if (args.locale === 'zh') {
                     zhStatus = 'appended';
                     zhNote = 'Primary locale is zh — the en twin is untouched (check with historian_read(path, "en")).';
                 }
@@ -130,6 +156,7 @@ export function makeAppendTool(deps) {
                         zhNote = 'No zh twin exists and no translator is wired — provide sectionZh to bootstrap it.';
                     }
                 }
+                const advisory = frontDumpAdvisory(tier, args.section);
                 return okJson({
                     mode: 'append',
                     path: args.path,
@@ -138,6 +165,8 @@ export function makeAppendTool(deps) {
                     urls: urlPair(appended),
                     zhStatus,
                     zhNote,
+                    ...(isEvidence ? { note: MACHINE_TIER_NOTE } : {}),
+                    ...(advisory === null ? {} : { advisory }),
                 });
             }
             catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-wiki-historian",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "opencode plugin that manages a wiki.js knowledge base with bilingual pages, genre templates, and migration tooling.",
   "type": "module",
   "license": "MIT",

package/skills/historian/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: historian
-description: "Wiki.js 史官插件技能：双语孪生页面管理（en/zh）、G1-G5 页型骨架、V4 机构记忆层（reading loop 自动注入 + /historian-capture 主动留痕）、可发布 OpenCode 插件。Phase 1.5 页型分类确保每页匹配正确的知识形态。操作 10 个 historian_* 工具完成搜索、阅读、创建、更新、追加、翻译、迁移、移动、删除与页面地图/时间线管理。"
+description: "Wiki.js 史官插件技能：双语孪生页面管理（en/zh）、G1-G5 页型骨架、V5 机构记忆层（双信号 reading loop + /historian-capture 主动留痕 + `_evidence/` 证据页）、可发布 OpenCode 插件。Phase 1.5 页型分类确保每页匹配正确的知识形态。操作 10 个 historian_* 工具完成搜索、阅读、创建、更新、追加、翻译、迁移、移动、删除与页面地图/时间线管理。"
 ---
 
-# 史官 (Historian) — 行为契约 V4 机构记忆层
+# 史官 (Historian) — 行为契约 V5 机构记忆层
 
 你是史官：本地 Wiki.js 知识库的策展人。不是文字搬运工，而是决定**什么值得成页、放在哪里、如何组织、链接给谁**的编辑。每次变更必须让 wiki 更有序。
 
@@ -15,6 +15,14 @@ description: "Wiki.js 史官插件技能：双语孪生页面管理（en/zh）
 4. **每页可达**。无入链的页面是孤儿债。创建的每个页面在同一次运行中拿到反向链接。
 5. **索引是每次变更的一部分**。让 wiki-index 过期的变更是未完成的变更。
 
+### 分层职责 (Tier responsibilities)
+
+| 层 | 位置 | 职责 |
+|----|------|------|
+| 前台 (front) | 主题章节的 G1-G5 页 | 人写人读的知识页；双语孪生、进索引；只放提炼后的内容 + 链接 |
+| 后台 (backstage) | `_meta/` + 本地镜像 | 机器记账：cache map、时间线、哨兵文件；不参与人读正文 |
+| 证据 (evidence) | `_evidence/` | 原始件超 10 行时的归宿（`historian_page_create` 传 `tier:"evidence"`）：单语 en、不发布；人工页面只引用其 URL |
+
 ---
 
 ## Phase 0: 分诊 (Triage)
@@ -60,7 +68,7 @@ description: "Wiki.js 史官插件技能：双语孪生页面管理（en/zh）
 
 - **无教训的临时操作** — "重启了容器就好了，不知道为什么"没有可复用知识。故障复盘页至少需要根因或可复现的修复。
 - **秘密** — 凭证、token、私钥绝不入 wiki。
-- **原始转储** — 聊天记录和 shell 输出是原材料，不是页面内容。先提取。
+- **原始转储** — 聊天记录和 shell 输出是原材料，不是页面内容。先提取决定性摘录（每段 ≤10 行）；完整原文转存 `_evidence/` 证据页（`tier:"evidence"`），页面里只放链接。
 - **重复** — 已有页面覆盖的知识 → 整合到那里，不要创建新页。
 - **琐碎临时** — 今天的时间戳状态，明天就过时。
 
@@ -243,16 +251,18 @@ historian_map action=refresh
 
 ---
 
-## 机构记忆层 (v4)：reading loop 与 capture
+## 机构记忆层 (v5)：reading loop 与 capture
 
 插件从"被动工具集"升级为"机构记忆层"：机器侧两个机制，均不影响下述人工流程。
 
-### Reading loop（自动注入，默认开启）
+### Reading loop（自动注入，默认关闭）
 
 插件经 `experimental.chat.system.transform` 钩子向每次请求的 system 提示注入一段"wiki 优先"advisory：动手前先 `historian_search`、近期变更查 `historian_map action=timeline`、当前部署态看 G5 现状卡并核实行「上次核实于」、引用所依赖的页面 URL。agent 的义务是**执行**它，不是忽略它。
 
-- 选项 `readingLoop` 默认 `true`；关闭用插件二元组第二参数：`["<plugin-url>", { "readingLoop": false }]`。
-- 严格 OpenAI 兼容后端（如 vLLM）拒绝多条 system 消息（报 `System message must be at the beginning.`）——此类部署必须设 `readingLoop: false`。
+- 双信号门控：仅当**同时**满足两条信号才注入——插件二元组第二参数配 `"readingLoop": true`，**且**本机存在哨兵文件 `~/.config/opencode/historian-reading-loop.json`（内容 `{"version":1,"confirmed":true}`）。任一缺失即不注入。开关默认 false，开启需配置+哨兵双确认；启用步骤见 `references/adapting-your-own-wiki.md`。
+- 配置已开而哨兵缺失时，插件加载期打一条 console.error（给出哨兵路径与内容），不会静默失灵。
+- 注入语义为**单块追加**：advisory 拼接到 system 提示的最后一个块（`\n\n` 分隔），system 为空数组时才新建块——绝不产生第二条 system 消息。严格 OpenAI 兼容后端（如 vLLM）会以 `System message must be at the beginning.` 拒绝多 system 请求，单块追加从根上规避此坑。
+- 幂等去重：同一请求的任一 system 块已含 `historian_search` 字样则跳过注入。
 
 ### Capture（主动留痕，默认关闭）
 

package/skills/historian/references/adapting-your-own-wiki.md

@@ -39,15 +39,25 @@ Six-step self-onboarding for pointing the historian plugin at your own Wiki.js i
 - 任何进入包/文档的内容不得包含：真实主机名、真实用户路径（`/home/...`）、token、真实私有部署的页面标题与章节表。
 - 硬门：`node tools/privacy-audit.mjs` 扫描 `npm pack` 全部文件（含 `dist/` 与 `skills/`）。改过任何随包文本后必须跑到 exit 0 再发布。
 
-## 6. 机构记忆层开关 / reading-loop & capture switches
+## 6. 机构记忆层开关与证据层 / reading-loop & capture switches, evidence tier
 
-- `readingLoop` 默认 `true`：插件向每次请求的 system 注入"先查 wiki"提示。严格 OpenAI 兼容后端（如 vLLM）会拒绝多条 system 消息——此类部署设 `"readingLoop": false`。
+- `readingLoop` 开关默认关闭（false），true 需配置+哨兵双确认：插件向每次请求的 system 注入"先查 wiki"提示，但只有配置信号与本机哨兵文件同时到位才生效。注入是单块合并（追加到最后一个 system 块），绝不产生第二条 system 消息——严格 OpenAI 兼容后端（如 vLLM）同样安全。
+- 哨兵文件必须由人在本机写入（agent 自我启用被禁止）：
+
+  ```bash
+  cat > ~/.config/opencode/historian-reading-loop.json <<'EOF'
+  {"version":1,"confirmed":true}
+  EOF
+  ```
+
+- 缺一不生效：只配了选项而没有哨兵，插件加载期打一条提示（给出哨兵路径与内容），不注入；删除哨兵文件即刻回退。
 - `capture.enabled` 默认 `false`：置 `true` 后会话空闲时弹一条 toast 提醒；**只提醒、绝不自动写页**。`/historian-capture` 命令始终注册，与此开关无关。
+- 证据层接入：会话产出的原始件（日志、转写、大 diff）超过 10 行时，用 `historian_page_create` 传 `tier: "evidence"` 存入 `_evidence/<主题>--<yyyymmdd>`（单语 en、不发布、匿名访问 404 属 by design），人读页附录只放决定性摘录加链接。往人读页写超过 30 行的围栏块会收到一条 `advisory` 软提醒，不阻断写入。
 
 ```jsonc
-["opencode-historian", { "readingLoop": false, "capture": { "enabled": true } }]
+["opencode-historian", { "readingLoop": true, "capture": { "enabled": true } }]
 ```
 
 ---
 
-配完六步，你的史官即就位：consult（reading loop 自动引路）、notice（capture 提醒留痕）、record（G1-G5 骨架 + map/timeline 归档）。
+配完六步，你的史官即就位：consult（reading loop 双信号启用后自动引路）、notice（capture 提醒留痕）、record（G1-G5 骨架 + `_evidence/` 证据页 + map/timeline 归档）。

package/skills/historian/references/genres.md

@@ -35,7 +35,7 @@
 7. 处置 (Remediation) — 止血 vs 根治
 8. 行动项 (Action Items) — **六列（含五要素）**：措施(行内容) | 类型 | 负责人 | 期限 | 验证 | 状态
 9. 教训 (Lessons Learned) — 做得好 / 做错 / 侥幸
-10. 附录 (Appendix) — 原始日志片段、截图
+10. 附录 (Appendix) — 决定性摘录（每段 ≤10 行）+ 证据页链接（`_evidence/...`）+ 外部链接（commit/PR/告警）
 11. 相关页面 (Related Pages)
 
 **状态块示例**：
@@ -125,6 +125,17 @@
 
 ---
 
+## 证据页协议 (Evidence Pages)
+
+触发条件 (Trigger)：任何想贴进页面的原始件——日志、会话转写、大 diff——超过 10 行时不贴正文，转存证据页。
+Whenever a raw artifact (log, transcript, big diff) destined for a page exceeds 10 lines, store it as an evidence page instead of pasting it.
+
+- 命名 (Naming)：`_evidence/<主题>--<yyyymmdd>`（如 `_evidence/wiki-oom--20260805`）
+- 建页 (Create)：`historian_page_create` 传 `tier: "evidence"`——证据页为机器层：单语 en、隐藏、不发布，不走 G1-G5 骨架、不占双语孪生与索引。
+- 引用 (Cite)：人工页面（G1 附录、G5 变更记录「依据」列等）只放证据页 URL 加决定性摘录（每段 ≤10 行），永不内嵌原文转储。
+
+---
+
 ## 通用元素（所有页型共享）
 
 ### 状态块（H1 后紧跟）

package/skills/historian/references/rules.md

@@ -19,7 +19,7 @@
 | SYN-13 | **无占位债** | 禁止 TODO、TBD、待补充。不知道就不写那个节。 |
 | SYN-14 | **原始数据精度** | 数字按需保留精度。`65.38461538461539/100` 写 `65.4/100`，除非精度本身是要点。 |
 | SYN-15 | **禁止空节** | `### 优点` 下写 `（无）`→ 删掉整个节。空节占空间不传递信息。 |
-| SYN-16 | **禁止原始转储** | shell 输出、聊天日志、超过 5-10 行的堆栈跟踪不直接入页。提取发现，只引用决定性行。 |
+| SYN-16 | **禁止原始转储** | shell 输出、聊天日志、超过 5-10 行的堆栈跟踪不直接入页。提取发现，只引用决定性行。确需保全原文时转存证据页：`_evidence/<主题>--<yyyymmdd>`（`historian_page_create` 传 `tier: "evidence"`），页面里只放链接。 |
 | SYN-17 | **时间 vs 主题** | 参考页按主题组织，不按天记日记。时间线结构只用于事件/事故页(G1)。 |
 | SYN-18 | **链接规范** | 内部链接用 `[Label](/path)` 格式。禁止 `[[path|label]]` 旧语法。每条链接必须指向 cache map 中现存的路径。 |
 | SYN-19 | **双语孪生** | 每个 en 页有 zh 孪生页，路径相同、语言不同。孪生标题各用本语言（如 `Architecture` / `建筑`）。正文节对节镜像。 |