opencode-wiki-historian 0.3.0 → 0.5.0

package/dist/templates/skeletons.js

@@ -7,7 +7,7 @@
  *
  * Contract of every skeleton constant:
  *  - Rubric dimension C anatomy: H1 placeholder → status line
- *    `**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD`
+ *    `**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD`
  *    → one-line scope (`This page answers:` / `本页回答：`) → tail
  *    `Related Pages`/`相关页面` section with a real-link hint (SYN-9 fixed tail).
  *  - wiki.js 2.x expression pieces only: blockquote admonitions
@@ -26,7 +26,7 @@
 /** G1 — 事件/复盘页 (incident postmortem), zh. */
 export const G1_ZH = `# 页面标题（占位：写完后替换为实际标题，须与页面 title 一致）
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **本页回答：** 一句话范围句（占位：本页记录哪次故障/事件的起因、影响与处置）
 
@@ -117,7 +117,7 @@ export const G1_ZH = `# 页面标题（占位：写完后替换为实际标题
 /** G1 — incident postmortem, en (section-for-section twin of G1_ZH). */
 export const G1_EN = `# Page Title (placeholder: replace with the real title, must match the page title)
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **This page answers:** one-line scope sentence (placeholder: which incident this page records, its impact and handling)
 
@@ -208,7 +208,7 @@ See footnote[^1].
 /** G2 — 对比/选型页 (comparison / selection), zh. */
 export const G2_ZH = `# 页面标题（占位：写完后替换为实际标题，须与页面 title 一致）
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **本页回答：** 一句话范围句（占位：本页在哪些对象之间、按什么维度对比，结论是什么）
 
@@ -258,7 +258,7 @@ export const G2_ZH = `# 页面标题（占位：写完后替换为实际标题
 /** G2 — comparison / selection, en (section-for-section twin of G2_ZH). */
 export const G2_EN = `# Page Title (placeholder: replace with the real title, must match the page title)
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **This page answers:** one-line scope sentence (placeholder: what is compared, on which dimensions, and the pick)
 
@@ -308,7 +308,7 @@ export const G2_EN = `# Page Title (placeholder: replace with the real title, mu
 /** G3 — 清单/参考页 (inventory / reference), zh. */
 export const G3_ZH = `# 页面标题（占位：写完后替换为实际标题，须与页面 title 一致）
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **本页回答：** 一句话范围句（占位：本页收录哪类条目、覆盖到哪里、不覆盖什么）
 
@@ -343,7 +343,7 @@ export const G3_ZH = `# 页面标题（占位：写完后替换为实际标题
 /** G3 — inventory / reference, en (section-for-section twin of G3_ZH). */
 export const G3_EN = `# Page Title (placeholder: replace with the real title, must match the page title)
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **This page answers:** one-line scope sentence (placeholder: which entries are covered, up to what boundary)
 
@@ -378,7 +378,7 @@ export const G3_EN = `# Page Title (placeholder: replace with the real title, mu
 /** G4 — 概念/原理解析页 (concept / explanation), zh. */
 export const G4_ZH = `# 页面标题（占位：写完后替换为实际标题，须与页面 title 一致）
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **本页回答：** 一句话范围句（占位：本页解释哪个概念，读者看完能理解什么）
 
@@ -416,7 +416,7 @@ export const G4_ZH = `# 页面标题（占位：写完后替换为实际标题
 /** G4 — concept / explanation, en (section-for-section twin of G4_ZH). */
 export const G4_EN = `# Page Title (placeholder: replace with the real title, must match the page title)
 
-**状态/Status**: Active <!-- or Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 自检通过后改 Active/Historical/Superseded --> · **日期/Date**: YYYY-MM-DD
 
 **This page answers:** one-line scope sentence (placeholder: which concept is explained and what the reader will understand)
 
@@ -457,7 +457,7 @@ export const G4_EN = `# Page Title (placeholder: replace with the real title, mu
  *  belongs to G1 event pages, linked from 变更记录. */
 export const G5_ZH = `# 页面标题（占位：写完后替换为实际标题，须与页面 title 一致）
 
-**状态/Status**: Active <!-- or Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 复核后改 Active / Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
 
 **本页回答：** 当前部署状态（占位：写明范围）
 
@@ -508,7 +508,7 @@ export const G5_ZH = `# 页面标题（占位：写完后替换为实际标题
 /** G5 — current-state ledger, en (section-for-section twin of G5_ZH). */
 export const G5_EN = `# Page Title (placeholder: replace with the real title, must match the page title)
 
-**状态/Status**: Active <!-- or Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
+**状态/Status**: draft <!-- 复核后改 Active / Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
 
 **This page answers:** what is deployed and running right now (placeholder: name the system and scope)
 
@@ -556,3 +556,104 @@ export const G5_EN = `# Page Title (placeholder: replace with the real title, mu
 ## Related Pages
 
 <!-- List the real page paths that link here and back. Event histories go in G1 pages, cited in Evidence. -->`;
+/** G6 — 操作手册/how-to 页 (goal-titled operational manual), zh. Diátaxis doing
+ *  leg: a reader with one goal follows the numbered steps to the outcome; every
+ *  step carries 动作 + 预期结果 + 失败处置. Concepts stay in G4 pages, raw
+ *  command lists in G3 pages, linked from 相关页面. */
+export const G6_ZH = `# 如何做某事（占位：目标句式标题，须与页面 title 一致）
+
+**状态/Status**: draft <!-- 复核后改 Active / Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
+
+**本页回答：** 如何完成某事（占位：写明具体目标）
+
+> **提示**
+> 操作手册面向带着目标来的读者：步骤可复制、可执行、可核对。
+> 原理写 G4 概念页，命令清单写 G3 页，从相关页面链过来。
+{.is-info}
+
+## 目标
+
+<!-- 1–2 句：完成后读者得到什么结果。成功判据须可观察。 -->
+
+## 前置条件
+
+<!-- 权限、版本、依赖、环境变量逐项列出。每项须能当场自检。 -->
+
+| 条件 | 检查方法 | 预期结果 |
+| --- | --- | --- |
+| example-service 可达 | \`curl -s http://example.com:8000/health\` | HTTP 200 |
+
+## 操作步骤
+
+<!-- 编号步骤，每步三段：动作、预期结果、失败处置。命令须可直接复制。 -->
+
+1. **动作**：<!-- 做什么或运行哪条命令。 -->
+   **预期结果**：<!-- 正常时看到的输出或状态。 -->
+   **失败处置**：<!-- 未达预期时的补救，或链向 G1/G4 页。 -->
+
+## 回退
+
+<!-- 出错后如何恢复原状：撤销命令、备份位置。不可逆操作须前置警告。 -->
+
+## 元数据表
+
+| 元数据 | 值 |
+| --- | --- |
+| 状态 | <!-- Active / Superseded-by: <path> / Deprecated --> |
+| 上次核实 | <!-- YYYY-MM-DD，在哪套环境按本页步骤重跑过 --> |
+| 复核周期 | <!-- 如每 90 天，到期重跑本页步骤 --> |
+| 被取代于 | <!-- 新手册路径，无则填 — --> |
+| 来源类型 | <!-- human / agent / imported --> |
+
+## 相关页面
+
+<!-- 列出互链的真实页面路径。原理在 G4，清单在 G3，事故史在 G1。 -->`;
+/** G6 — how-to manual, en (section-for-section twin of G6_ZH). */
+export const G6_EN = `# How to Do X (placeholder: goal-titled heading, must match the page title)
+
+**状态/Status**: draft <!-- 复核后改 Active / Superseded-by: <path> / Deprecated --> · **日期/Date**: YYYY-MM-DD
+
+**This page answers:** how to finish one concrete task (placeholder: name the goal)
+
+> **Tip**
+> A how-to serves readers who arrive with a goal: steps are copy-pasteable and checkable.
+> Concepts belong in G4 pages, raw command lists in G3 pages, linked under Related Pages.
+{.is-info}
+
+## Goal
+
+<!-- One or two sentences: the outcome the reader gets. State an observable success test. -->
+
+## Prerequisites
+
+<!-- Permissions, versions, dependencies, env vars: one row each. Every row must be self-checkable. -->
+
+| Condition | Check | Expected |
+| --- | --- | --- |
+| example-service reachable | \`curl -s http://example.com:8000/health\` | HTTP 200 |
+
+## Steps
+
+<!-- Numbered steps, three legs per step: action, expected result, on failure. Commands must be copy-pasteable. -->
+
+1. **Action**: <!-- what to run or change. -->
+   **Expected result**: <!-- the output or state that proves success. -->
+   **On failure**: <!-- the fix, or a link to the G1/G4 page. -->
+
+## Rollback
+
+<!-- How to restore the prior state: revert commands, backup locations. Warn before any irreversible step. -->
+
+## Metadata
+
+| Field | Value |
+| --- | --- |
+| Status | <!-- Active / Superseded-by: <path> / Deprecated --> |
+| Last verified | <!-- YYYY-MM-DD and the environment the steps were re-run in --> |
+| Review by | <!-- e.g. every 90 days; re-run the steps when due --> |
+| Superseded by | <!-- path of the newer manual, or — --> |
+| Source kind | <!-- human / agent / imported --> |
+
+## Related Pages
+
+<!-- Real page paths that link here and back. Why-it-works lives in G4, checklists in G3, incidents in G1. -->`;

package/dist/tools/create.js

@@ -7,16 +7,16 @@
 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 { listPages, readPage } from '../wiki/pages.read.js';
+import { classifyGenre, genreSkeleton, GENRES } from '../templates/genres.js';
 import { evidenceSkeleton } from '../templates/evidence.js';
-import { enforceTierPath, errEnvelope, frontDumpAdvisory, MACHINE_TIER_NOTE, okJson, pageDeps, tierMismatchJson, TIERS, urlPair, URL_MANDATE, } from './shared.js';
+import { checklistAdvisory, collisionAdvisory, enforceTierPath, errEnvelope, frontDumpAdvisory, MACHINE_TIER_NOTE, okJson, pageDeps, publishGateRefusalJson, sectionRefusalJson, tierMismatchJson, TIERS, urlPair, URL_MANDATE, } from './shared.js';
 const s = tool.schema;
-const GENRES = ['G1', 'G2', 'G3', 'G4', 'G5'];
 const ARGS_SHAPE = {
     path: s.string().describe('Wiki path, e.g. docs/guides/foo (first segment must NOT look like a locale code)'),
     title: s.string().describe('Page title'),
     content: s.string().optional().describe('Page body (markdown). ABSENT → local template mode, nothing written'),
-    genre: s.enum(GENRES).optional().describe('Genre hint: G1..G5 (template mode / classification)'),
+    genre: s.enum(GENRES).optional().describe('Genre hint: G1..G6 (template mode / classification)'),
     locale: s.enum(['en', 'zh']).default('en'),
     isPublished: s.boolean().default(true),
     tags: s.array(s.string()).default([]),
@@ -25,6 +25,28 @@ const ARGS_SHAPE = {
     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);
+/** Best-effort collision advice for the content branch: read-only pre-checks
+ *  whose every failure is SWALLOWED — the write proceeds with no advice
+ *  rather than being blocked or errored by the adviser itself (the
+ *  "hint, never throw" precedent above). */
+async function collisionAdvice(deps, probe) {
+    const client = deps.getClient();
+    let exists = false;
+    try {
+        exists = (await readPage(client, probe.path, probe.locale)) !== null;
+    }
+    catch {
+        /* failed existence read → assume absence: never advise on unknowns */
+    }
+    let inventory = [];
+    try {
+        inventory = await listPages(client);
+    }
+    catch {
+        /* failed inventory read → no duplicate advice */
+    }
+    return collisionAdvisory({ ...probe, exists, inventory });
+}
 export function makeCreateTool(deps) {
     return tool({
         description: `Create a wiki page: primary locale content plus an optional auto-translated twin. ` +
@@ -40,6 +62,9 @@ export function makeCreateTool(deps) {
             catch (err) {
                 return errEnvelope(err);
             }
+            const offSections = sectionRefusalJson(args.path, deps.options.sections);
+            if (offSections !== null)
+                return offSections;
             const mismatch = enforceTierPath(tier, args.path);
             if (mismatch !== null)
                 return tierMismatchJson(mismatch);
@@ -50,6 +75,10 @@ export function makeCreateTool(deps) {
             const localeHint = isEvidence && args.locale === 'zh'
                 ? 'evidence pages are monolingual en — the locale argument was forced to "en"'
                 : undefined;
+            // Genre is resolved ONCE, above the template/content fork (v4 todo 4):
+            // the template branch feeds it the skeleton, the content branch the
+            // pre-write checklist gate. Explicit arg wins over classification.
+            const genre = args.genre ?? classifyGenre({ title: args.title, body: args.description ?? '' }).genre;
             if (args.content === undefined || args.content.trim() === '') {
                 if (isEvidence) {
                     // Evidence pages are not genre-templated: echo the machine skeleton.
@@ -70,7 +99,6 @@ export function makeCreateTool(deps) {
                         ...(localeHint === undefined ? {} : { localeHint }),
                     });
                 }
-                const genre = args.genre ?? classifyGenre({ title: args.title, body: args.description ?? '' }).genre;
                 return okJson({
                     mode: 'template',
                     genre,
@@ -81,6 +109,16 @@ export function makeCreateTool(deps) {
                 });
             }
             try {
+                const gate = publishGateRefusalJson(args.content, locale, args.path, deps.options.baseUrl);
+                if (gate !== null)
+                    return gate;
+                const collision = await collisionAdvice(deps, {
+                    tier,
+                    path: args.path,
+                    locale,
+                    title: args.title,
+                    baseUrl: deps.options.baseUrl,
+                });
                 const result = await createPage(pageDeps(deps), {
                     path: args.path,
                     locale,
@@ -92,7 +130,12 @@ export function makeCreateTool(deps) {
                     twin: isEvidence ? false : args.twin,
                     description: args.description,
                 });
-                const advisory = frontDumpAdvisory(tier, args.content);
+                const advisories = [
+                    frontDumpAdvisory(tier, args.content),
+                    collision,
+                    // Evidence raw material is not a genre page — the gate is front-only.
+                    isEvidence ? null : checklistAdvisory(genre, args.content),
+                ].filter((a) => a !== null);
                 return okJson({
                     mode: 'create',
                     path: args.path,
@@ -104,7 +147,7 @@ export function makeCreateTool(deps) {
                     urls: urlPair(result),
                     ...(isEvidence ? { note: MACHINE_TIER_NOTE } : {}),
                     ...(localeHint === undefined ? {} : { localeHint }),
-                    ...(advisory === null ? {} : { advisory }),
+                    ...(advisories.length === 0 ? {} : { advisory: advisories.join('\n') }),
                 });
             }
             catch (err) {

package/dist/tools/local.js

@@ -8,6 +8,10 @@ import { tool } from '@opencode-ai/plugin';
 import { TranslateError } from '../translate.js';
 import { buildChronology, filterRowsByPath } from '../chronology.js';
 import { getMap, refreshMapCache, CACHE_PATH } from '../map.js';
+import { buildMaintainReport, renderMaintainMarkdown } from '../maintain.js';
+import { buildSurfaceReport, renderSurfaceMarkdown } from '../surface.js';
+import { normalizeLocale, PathValidationError } from '../wiki/locale.js';
+import { listPages, readPage } from '../wiki/pages.read.js';
 import { errEnvelope, okJson, reportUrls, URL_MANDATE } from './shared.js';
 const s = tool.schema;
 const TRANSLATE_ARGS = {
@@ -53,11 +57,71 @@ export function makeTranslateSnippetTool(deps) {
     });
 }
 const MAP_ARGS = {
-    action: s.enum(['show', 'refresh', 'timeline']).default('show'),
+    action: s.enum(['show', 'refresh', 'timeline', 'maintain']).default('show'),
     days: s.number().int().positive().optional().describe('timeline: keep only rows updated within the last N days'),
     path: s.string().optional().describe('timeline: section/path prefix filter (e.g. ops)'),
+    deep: s.boolean().optional().describe('maintain: additionally read every page body (freshness + stubs + broken/stacked links + twin parity + zh-first + unfinished skeletons + claim ledgers) — one bounded read per row, cached across both scans'),
 };
 const MapArgsSchema = s.object(MAP_ARGS);
+/** maintain: light tier is map rows + ONE read-only pages.list pass per locale
+ *  (the mirror's MapRow carries no tags; the list join restores the vocab view);
+ *  deep additionally reads each body via readPage. Reserved-path pages (e.g.
+ *  'home', probe p1) answer null instead of killing the sweep. Read-only. */
+async function runMaintain(deps, mapDeps, snapshot, deep) {
+    const client = deps.getClient();
+    const tagIndex = new Map();
+    const liveInventory = [];
+    const locales = [...new Set(deps.options.locales.map(normalizeLocale))].sort();
+    for (const locale of locales) {
+        for (const item of await listPages(client, { locale })) {
+            tagIndex.set(`${item.locale}\u0000${item.path}`, item.tags);
+            liveInventory.push({ path: item.path, locale: item.locale, isPublished: item.isPublished });
+        }
+    }
+    const rows = snapshot.rows.map((r) => ({ ...r, tags: tagIndex.get(`${r.locale}\u0000${r.path}`) ?? [] }));
+    const bodyCache = new Map();
+    const readBody = deep
+        ? (path, locale) => {
+            const key = `${locale}\u0000${path}`;
+            const hit = bodyCache.get(key);
+            if (hit !== undefined)
+                return hit;
+            const pending = (async () => {
+                try {
+                    return (await readPage(client, path, locale))?.content ?? null;
+                }
+                catch (err) {
+                    // Unreadable page (invalid path / transport) is a scan miss, not a report failure.
+                    if (err instanceof PathValidationError)
+                        return null;
+                    throw err;
+                }
+            })();
+            bodyCache.set(key, pending);
+            return pending;
+        }
+        : undefined;
+    const report = await buildMaintainReport({ rows, mapGeneratedAt: snapshot.generatedAt, mapStaleSeconds: snapshot.staleSeconds }, { deep, readBody });
+    const surface = await buildSurfaceReport({
+        rows,
+        generatedAt: report.generatedAt,
+        baseUrl: deps.options.baseUrl,
+        liveInventory,
+        deep,
+        readBody,
+    });
+    return {
+        action: 'maintain',
+        schema: 'historian.maintain.v2',
+        deep: report.deep,
+        generatedAt: report.generatedAt,
+        rowCount: report.rowCount,
+        report,
+        surface,
+        markdown: `${renderMaintainMarkdown(report)}\n\n${renderSurfaceMarkdown(surface)}`,
+        urls: reportUrls(deps.options.baseUrl, CACHE_PATH, 'en'),
+    };
+}
 // --- historian_map -----------------------------------------------------------
 export function makeMapTool(deps) {
     return tool({
@@ -67,7 +131,11 @@ export function makeMapTool(deps) {
             `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. ` +
-            `${URL_MANDATE}.`,
+            `maintain runs the read-only curation sweep + surface report (twin gap, near-duplicate titles, staleness, ` +
+            `diffusion/orphan candidates, tag vocab, section distribution, map-vs-live coverage, nav hygiene; ` +
+            `deep:true adds per-body freshness, stub reachability, broken/stacked/index-less links, twin parity, ` +
+            `unfinished skeletons, claim ledgers) and ` +
+            `answers a markdown report with a stable-key JSON tail. ${URL_MANDATE}.`,
         args: MAP_ARGS,
         execute: async (raw) => {
             const args = MapArgsSchema.parse(raw);
@@ -92,6 +160,9 @@ export function makeMapTool(deps) {
                         urls: reportUrls(deps.options.baseUrl, CACHE_PATH, 'en'),
                     });
                 }
+                if (args.action === 'maintain') {
+                    return okJson(await runMaintain(deps, mapDeps, snapshot, args.deep ?? false));
+                }
                 return okJson({
                     action: 'show',
                     generatedAt: snapshot.generatedAt,

package/dist/tools/mutate.js

@@ -6,12 +6,11 @@
  */
 import { tool } from '@opencode-ai/plugin';
 import { deletePage, movePage } from '../wiki/pages.js';
-import { selfReviewChecklist } from '../templates/genres.js';
-import { confirmRequiredJson, errEnvelope, okJson, urlPair, URL_MANDATE, pageDeps } from './shared.js';
+import { GENRES, selfReviewChecklist } from '../templates/genres.js';
+import { confirmRequiredJson, errEnvelope, okJson, sectionRefusalJson, urlPair, URL_MANDATE, pageDeps, } from './shared.js';
 import { reformatPageDraft } from '../migrate.js';
 import { applyMigration } from '../migrate-apply.js';
 const s = tool.schema;
-const GENRES = ['G1', 'G2', 'G3', 'G4', 'G5'];
 const DELETE_ARGS = {
     path: s.string(),
     locale: s.enum(['en', 'zh']).default('en'),
@@ -28,6 +27,9 @@ export function makeDeleteTool(deps) {
             const args = DeleteArgsSchema.parse(raw);
             if (args.confirm !== 'yes')
                 return confirmRequiredJson('historian_delete', args.confirm);
+            const offSections = sectionRefusalJson(args.path, deps.options.sections);
+            if (offSections !== null)
+                return offSections;
             try {
                 const result = await deletePage(pageDeps(deps), args.path, args.locale, 'yes');
                 return okJson({
@@ -62,6 +64,11 @@ export function makeMoveTool(deps) {
             const args = MoveArgsSchema.parse(raw);
             if (args.confirm !== 'yes')
                 return confirmRequiredJson('historian_move', args.confirm);
+            // The allow-list guards the DESTINATION (the write target); the source
+            // page may legally live somewhere the new configuration no longer admits.
+            const offSections = sectionRefusalJson(args.newPath, deps.options.sections);
+            if (offSections !== null)
+                return offSections;
             try {
                 const destLocale = args.newLocale ?? args.locale;
                 const result = await movePage(pageDeps(deps), args.path, args.locale, args.newPath, destLocale, 'yes');

package/dist/tools/read.js

@@ -5,7 +5,7 @@
  */
 import { tool } from '@opencode-ai/plugin';
 import { normalizeLocale } from '../wiki/locale.js';
-import { readPage, searchPages } from '../wiki/pages.js';
+import { listPages, readPage, searchPages } from '../wiki/pages.js';
 import { errEnvelope, okJson, reportUrls, URL_MANDATE } from './shared.js';
 const s = tool.schema;
 const READ_ARGS = {
@@ -56,22 +56,89 @@ export function makeReadTool(deps) {
         },
     });
 }
+const TAG_MODES = ['any', 'all'];
 const SEARCH_ARGS = {
     query: s.string(),
     kind: s.enum(['title', 'content']).default('content').describe('Informational intent; the wiki index covers both title and content'),
+    tags: s
+        .array(s.string().min(1))
+        .min(1)
+        .max(5)
+        .refine((arr) => arr.every((t) => t.trim().length > 0), {
+        message: 'tags entries must be non-blank (whitespace-only rejected)',
+    })
+        .optional()
+        .describe('Filter to pages carrying these tags (1-5). tagsMode "all" (DEFAULT) = EVERY listed tag ' +
+        'must be present on the page — the server $tags mechanism is AND-only. tagsMode "any" = at ' +
+        'LEAST ONE tag matches (client-side per-tag fan-out + union). Entries are trimmed and ' +
+        'deduped; blank entries are rejected. Result rows include each page\'s tags so the agent ' +
+        'can see the live tag vocabulary.'),
+    tagsMode: s
+        .enum(TAG_MODES)
+        .default('all')
+        .describe('"all" (default): every tag must match (server-side AND, one request). "any": at least one tag (client-side union).'),
 };
 const SearchArgsSchema = s.object(SEARCH_ARGS);
+/** (path, locale) identity for union dedupe and query intersection. The NUL
+ *  separator cannot appear in a path or locale, so concatenation stays injective. */
+const matchKey = (path, locale) => `${locale}\u0000${path}`;
+/** Keys of the text-query result set, locale-normalized. Rows whose locale is
+ *  outside the en/zh whitelist never equal a list row (those are always en/zh),
+ *  so they simply cannot join the intersection. */
+function textKeysOf(resp) {
+    const keys = new Set();
+    for (const r of resp.results) {
+        try {
+            keys.add(matchKey(r.path, normalizeLocale(r.locale)));
+        }
+        catch {
+            /* unsupported locale — legacy mapper keeps the row with url:null; the tag
+               intersection just ignores it */
+        }
+    }
+    return keys;
+}
+/** tagsMode "any": one list call PER tag, unioned and deduped by (path, locale).
+ *  Resilience contract: a failed leg is dropped and named in `failed` — no new
+ *  error class surfaces while ≥1 leg survives; only when EVERY leg fails does
+ *  the original rejection propagate unchanged (standard error envelope). */
+async function unionByAnyTag(client, tags) {
+    const legs = await Promise.allSettled(tags.map((t) => listPages(client, { tags: [t] })));
+    const seen = new Set();
+    const rows = [];
+    const failures = [];
+    legs.forEach((leg, i) => {
+        if (leg.status === 'fulfilled') {
+            for (const row of leg.value) {
+                const k = matchKey(row.path, row.locale);
+                if (!seen.has(k)) {
+                    seen.add(k);
+                    rows.push(row);
+                }
+            }
+        }
+        else {
+            failures.push({ tag: tags[i], reason: leg.reason });
+        }
+    });
+    if (failures.length === tags.length)
+        throw failures[0].reason; // schema guarantees tags.length ≥ 1
+    return { rows, failed: failures.map((f) => f.tag) };
+}
 // --- historian_search --------------------------------------------------------
 export function makeSearchTool(deps) {
     return tool({
         description: `Full-text search over the wiki. kind is informational intent only — the live wiki.js ` +
             `search indexes title AND content (the engine signature is search(query, path, locale), no field scope). ` +
+            `Optional tags filter: tagsMode "all" (DEFAULT) requires EVERY tag on the page (server-side ` +
+            `AND); "any" matches AT LEAST ONE tag. Result rows carry each page's tags. ` +
             `Results carry their en/zh URLs. ${URL_MANDATE}.`,
         args: SEARCH_ARGS,
         execute: async (raw) => {
             const args = SearchArgsSchema.parse(raw);
             try {
-                const resp = await searchPages(deps.getClient(), args.query);
+                const client = deps.getClient();
+                const resp = await searchPages(client, args.query);
                 const results = resp.results.map((r) => {
                     try {
                         const locale = normalizeLocale(r.locale);
@@ -88,12 +155,53 @@ export function makeSearchTool(deps) {
                         return { id: r.id, title: r.title, description: r.description, path: r.path, locale: r.locale, url: null };
                     }
                 });
+                if (args.tags === undefined) {
+                    // Legacy path — no tags given, no tags keys leak into the envelope.
+                    return okJson({
+                        query: args.query,
+                        kind: args.kind,
+                        totalHits: resp.totalHits,
+                        suggestions: resp.suggestions,
+                        results,
+                    });
+                }
+                const wanted = [...new Set(args.tags.map((t) => t.trim()))];
+                let tagged;
+                let tagsFailed;
+                switch (args.tagsMode) {
+                    case 'all':
+                        // Straight passthrough: ONE request, the server's $tags AND mechanism.
+                        tagged = await listPages(client, { tags: wanted });
+                        tagsFailed = [];
+                        break;
+                    case 'any': {
+                        const union = await unionByAnyTag(client, wanted);
+                        tagged = union.rows;
+                        tagsFailed = union.failed;
+                        break;
+                    }
+                }
+                const textKeys = textKeysOf(resp);
+                const matched = tagged
+                    .filter((row) => textKeys.has(matchKey(row.path, row.locale)))
+                    .map((row) => ({
+                    id: row.id,
+                    title: row.title,
+                    description: row.description,
+                    path: row.path,
+                    locale: row.locale,
+                    url: reportUrls(deps.options.baseUrl, row.path, row.locale)[row.locale],
+                    tags: row.tags,
+                }));
                 return okJson({
                     query: args.query,
                     kind: args.kind,
-                    totalHits: resp.totalHits,
+                    tags: wanted,
+                    tagsMode: args.tagsMode,
+                    tagsFailed,
+                    totalHits: matched.length,
                     suggestions: resp.suggestions,
-                    results,
+                    results: matched,
                 });
             }
             catch (err) {