opencode-wiki-historian 0.2.0 → 0.4.0

package/dist/templates/skeletons.d.ts

@@ -46,3 +46,10 @@ export declare const G4_EN: string;
 export declare const G5_ZH: string;
 /** G5 — current-state ledger, en (section-for-section twin of G5_ZH). */
 export declare const G5_EN: string;
+/** 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 declare const G6_ZH: string;
+/** G6 — how-to manual, en (section-for-section twin of G6_ZH). */
+export declare const G6_EN: string;

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,8 +551,109 @@ 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
 
 <!-- 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**: Active <!-- or 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**: Active <!-- or 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,22 +7,46 @@
 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 { listPages, readPage } from '../wiki/pages.read.js';
+import { classifyGenre, genreSkeleton, GENRES } from '../templates/genres.js';
+import { evidenceSkeleton } from '../templates/evidence.js';
+import { checklistAdvisory, collisionAdvisory, enforceTierPath, errEnvelope, frontDumpAdvisory, MACHINE_TIER_NOTE, okJson, pageDeps, 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([]),
     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);
+/** 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. ` +
@@ -31,42 +55,96 @@ 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 offSections = sectionRefusalJson(args.path, deps.options.sections);
+            if (offSections !== null)
+                return offSections;
+            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;
+            // 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() === '') {
-                const genre = args.genre ?? classifyGenre({ title: args.title, body: args.description ?? '' }).genre;
+                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 }),
+                    });
+                }
                 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 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: 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 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,
-                    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 }),
+                    ...(advisories.length === 0 ? {} : { advisory: advisories.join('\n') }),
                 });
             }
             catch (err) {

package/dist/tools/local.js

@@ -8,6 +8,9 @@ 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 { 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,20 +56,62 @@ 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 stamps + redirect stubs) — one bounded read per row'),
 };
 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 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);
+        }
+    }
+    const rows = snapshot.rows.map((r) => ({ ...r, tags: tagIndex.get(`${r.locale}\u0000${r.path}`) ?? [] }));
+    const readBody = deep
+        ? async (path, locale) => {
+            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;
+            }
+        }
+        : undefined;
+    const report = await buildMaintainReport({ rows, mapGeneratedAt: snapshot.generatedAt, mapStaleSeconds: snapshot.staleSeconds }, { deep, readBody });
+    return {
+        action: 'maintain',
+        deep: report.deep,
+        generatedAt: report.generatedAt,
+        rowCount: report.rowCount,
+        report,
+        markdown: renderMaintainMarkdown(report),
+        urls: reportUrls(deps.options.baseUrl, CACHE_PATH, 'en'),
+    };
+}
 // --- historian_map -----------------------------------------------------------
 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. ` +
-            `${URL_MANDATE}.`,
+            `maintain runs the read-only curation sweep (twin gap, near-duplicate titles, staleness, diffusion/orphan ` +
+            `candidates, tag vocab, section distribution; deep:true adds per-body freshness stamps + redirect stubs) and ` +
+            `answers a markdown report with a stable-key JSON tail. ${URL_MANDATE}.`,
         args: MAP_ARGS,
         execute: async (raw) => {
             const args = MapArgsSchema.parse(raw);
@@ -91,6 +136,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) {