oasis_test_v2 0.0.0 → 0.2.1

package/dist/outline/outline-kb.mjs

@@ -0,0 +1,1486 @@
+#!/usr/bin/env node
+/**
+ * Deterministic Outline-backed LLM Wiki tool.
+ * No LLM decisions live here: paths, immutability, hashes, plans and lint are program rules.
+ */
+
+import { createHash } from "node:crypto";
+import { lookup } from "node:dns/promises";
+import { readFile } from "node:fs/promises";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { BlockList, isIP } from "node:net";
+import { basename, dirname, extname, isAbsolute, relative, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_SOURCE_BYTES = 5 * 1024 * 1024;
+const MAX_WECHAT_IMAGE_BYTES = 4 * 1024 * 1024;
+const MAX_WECHAT_IMAGES = 20;
+const MAX_WECHAT_TOTAL_IMAGE_BYTES = 24 * 1024 * 1024;
+const META_FENCE = "yaml";
+const CONTENT_HASH_PENDING = "pending";
+const USAGE = "Usage: outline-kb <command> [arguments] [--collection ID] [--root ID]. Run outline-kb <command> --help for the exact contract.";
+const WRITE_COMMANDS = new Set(["init", "create", "update", "append", "import-file", "import-url", "import-wechat", "apply"]);
+const QUERY_COMMANDS = new Set(["status", "search", "read", "read-many", "search-and-read"]);
+const INGEST_FORBIDDEN_COMMANDS = new Set(["init", "create", "update", "append", "apply", "lint"]);
+const MAINTENANCE_ALLOWED_COMMANDS = new Set(["status", "validate-maintenance-plan"]);
+const WECHAT_ARTICLE_HOSTS = new Set(["mp.weixin.qq.com", "weixin.qq.com"]);
+const WECHAT_FETCH_HEADERS = Object.freeze({
+  "user-agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0 Safari/537.36",
+  accept: "text/html,application/xhtml+xml",
+  "accept-language": "zh-CN,zh;q=0.9,en;q=0.7",
+});
+const PLAN_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  required: ["jobId", "operations"],
+  additionalProperties: false,
+  properties: {
+    jobId: { type: "string", minLength: 1 },
+    sourceHash: { type: "string" },
+    operations: {
+      type: "array",
+      items: {
+        oneOf: [
+          { type: "object", required: ["type", "path", "contentFile"], properties: { type: { const: "create" }, path: { type: "string" }, contentFile: { type: "string" } }, additionalProperties: false },
+          { type: "object", required: ["type", "path", "contentFile", "expectedUpdatedAt"], properties: { type: { const: "update" }, path: { type: "string" }, contentFile: { type: "string" }, expectedUpdatedAt: { type: "string" } }, additionalProperties: false },
+          { type: "object", required: ["type", "path", "contentFile"], properties: { type: { const: "append" }, path: { const: "log" }, contentFile: { type: "string" } }, additionalProperties: false },
+        ],
+      },
+    },
+  },
+};
+const PLAN_EXAMPLE = {
+  jobId: "knowledge-job-20260806-001",
+  operations: [
+    { type: "create", path: "wiki/synthesis/example", contentFile: "synthesis.md" },
+    { type: "update", path: "wiki/index", contentFile: "index.md", expectedUpdatedAt: "2026-08-06T00:00:00.000Z" },
+    { type: "append", path: "log", contentFile: "log.md" },
+  ],
+};
+const MAINTENANCE_PLAN_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  required: ["jobId", "operations"],
+  additionalProperties: false,
+  properties: {
+    jobId: { type: "string", minLength: 1 },
+    sourceHash: { type: "string" },
+    operations: {
+      type: "array",
+      items: {
+        oneOf: [
+          { type: "object", required: ["type", "path", "contentFile"], properties: { type: { const: "create" }, path: { type: "string" }, contentFile: { type: "string" } }, additionalProperties: false },
+          { type: "object", required: ["type", "path", "contentFile"], properties: { type: { const: "update" }, path: { type: "string" }, contentFile: { type: "string" } }, additionalProperties: false },
+        ],
+      },
+    },
+  },
+};
+const MAINTENANCE_PLAN_EXAMPLE = {
+  jobId: "knowledge-maintenance-20260831-001",
+  operations: [
+    { type: "create", path: "wiki/concepts/example", contentFile: "concept.md" },
+    { type: "update", path: "wiki/synthesis/existing", contentFile: "synthesis.md" },
+  ],
+};
+const HELP_FAILURE_EXAMPLE = { ok: false, error: { code: "USAGE", message: "missing required argument" } };
+const PLAN_FAILURE_EXAMPLES = [
+  { ok: false, error: { code: "PLAN_FILE_NOT_FOUND", message: "Plan file not found", details: { path: "/workspace/kb-plan/plan.json" } } },
+  { ok: false, error: { code: "PLAN_JSON_INVALID", message: "Plan file contains invalid JSON", details: { path: "/workspace/kb-plan/plan.json" } } },
+  { ok: false, error: { code: "CONTENT_FILE_NOT_FOUND", message: "Plan content file not found", details: { path: "/workspace/kb-plan/source-note.md", contentFile: "source-note.md", operationIndex: 0, operationType: "create", operationPath: "wiki/sources/example" } } },
+  { ok: false, error: { code: "CONTENT_FILE_UNREADABLE", message: "Plan content file is unreadable", details: { path: "/workspace/kb-plan/source-note.md", contentFile: "source-note.md", operationIndex: 0, operationType: "create", operationPath: "wiki/sources/example" } } },
+];
+const COMMAND_HELP = {
+  status: { usage: "outline-kb status", description: "Verify the injected Outline identity." },
+  init: { usage: "outline-kb init --collection ID [--root ID]", description: "Create missing fixed wiki pages. Use only during setup or explicit repair." },
+  tree: { usage: "outline-kb tree [PATH] --collection ID [--root ID]", description: "List the configured root tree. This is a full-tree operation." },
+  search: { usage: "outline-kb search QUERY --limit 10 [--under PATH] --collection ID [--root ID]", description: "Return scoped top-K search metadata without page bodies." },
+  read: { usage: "outline-kb read PATH_OR_ID --collection ID [--root ID]", description: "Read one scoped page." },
+  "read-many": { usage: "outline-kb read-many REF [REF...] --collection ID [--root ID]", description: "Read multiple scoped pages with one tree snapshot." },
+  "search-and-read": { usage: "outline-kb search-and-read QUERY --limit 8 [--under PATH] --collection ID [--root ID]", description: "Search scoped top-K results and batch-read their bodies with one tree snapshot." },
+  create: { usage: "outline-kb create PATH --file CONTENT.md --collection ID [--root ID]", description: "Create one validated wiki page." },
+  update: { usage: "outline-kb update PATH --file CONTENT.md --expected-updated-at ISO --collection ID [--root ID]", description: "CAS-update one non-raw page." },
+  append: { usage: "outline-kb append log --file LOG.md --job-id ID --collection ID [--root ID]", description: "Idempotently append to the maintenance log." },
+  "import-file": { usage: "outline-kb import-file FILE --path raw/PATH [--text-file EXTRACTED.md] [--content-type TYPE] --collection ID [--root ID]", description: "Import Markdown/TXT/PDF as immutable raw evidence; PDF requires extracted text." },
+  "import-url": { usage: "outline-kb import-url URL --path raw/PATH --collection ID [--root ID]", description: "Fetch a public URL and import immutable raw evidence. WeChat article URLs are routed to the dedicated parser automatically." },
+  "import-wechat": { usage: "outline-kb import-wechat WECHAT_URL --path raw/PATH --collection ID [--root ID]", description: "Capture a WeChat Official Account article with #js_content and publisher metadata validation." },
+  "validate-plan": { usage: "outline-kb validate-plan PLAN.json --collection ID [--root ID]", description: "Validate local files, plan schema and every CAS precondition without writing.", pathResolution: "Every contentFile is resolved relative to the PLAN.json directory.", planSchema: PLAN_SCHEMA, example: PLAN_EXAMPLE, failureExamples: PLAN_FAILURE_EXAMPLES },
+  "validate-maintenance-plan": { usage: "outline-kb validate-maintenance-plan PLAN.json", description: "Validate local maintenance Candidate files without reading or writing Outline. Available only in the system-owned network-maintenance profile.", pathResolution: "Every contentFile is resolved relative to the PLAN.json directory.", planSchema: MAINTENANCE_PLAN_SCHEMA, example: MAINTENANCE_PLAN_EXAMPLE, failureExamples: PLAN_FAILURE_EXAMPLES },
+  apply: { usage: "outline-kb apply PLAN.json --collection ID [--root ID]", description: "Preflight all local files and the complete plan, apply it, then return deterministic lint.", pathResolution: "Every contentFile is resolved relative to the PLAN.json directory.", planSchema: PLAN_SCHEMA, example: PLAN_EXAMPLE, failureExamples: PLAN_FAILURE_EXAMPLES },
+  lint: { usage: "outline-kb lint --collection ID [--root ID]", description: "Full-library deterministic health check. Do not run inside Query." },
+};
+
+function successExample(command) {
+  if (command === "search" || command === "read-many" || command === "search-and-read" || command === "tree") {
+    return { ok: true, documents: [{ id: "document-id", title: "Example", path: "wiki/concepts/example", url: "https://outline.example/doc/example", updatedAt: "2026-08-06T00:00:00.000Z" }] };
+  }
+  if (command === "read") return { ok: true, document: { id: "document-id", title: "Example", path: "wiki/concepts/example", url: "https://outline.example/doc/example", text: "..." } };
+  if (command === "validate-plan") return { ok: true, jobId: PLAN_EXAMPLE.jobId, sourceHash: null, operations: PLAN_EXAMPLE.operations };
+  if (command === "validate-maintenance-plan") return { ok: true, jobId: MAINTENANCE_PLAN_EXAMPLE.jobId, sourceHash: null, operations: MAINTENANCE_PLAN_EXAMPLE.operations };
+  if (command === "apply") return { ok: true, jobId: PLAN_EXAMPLE.jobId, results: [], lint: { ok: true, errors: [], warnings: [] }, status: "succeeded" };
+  return { ok: true };
+}
+
+const privateAddresses = new BlockList();
+for (const [network, prefix] of [
+  ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8],
+  ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.168.0.0", 16],
+  ["198.18.0.0", 15], ["224.0.0.0", 4], ["240.0.0.0", 4],
+]) privateAddresses.addSubnet(network, prefix, "ipv4");
+for (const [network, prefix] of [["::", 128], ["::1", 128], ["fc00::", 7], ["fe80::", 10], ["ff00::", 8]]) {
+  privateAddresses.addSubnet(network, prefix, "ipv6");
+}
+
+export class OutlineKbError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.name = "OutlineKbError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function cleanBaseUrl(value) {
+  const url = new URL(value);
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new OutlineKbError("INVALID_BASE_URL", "Outline base URL must use http or https");
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+function isPrivateAddress(address, family) {
+  const type = family === 6 ? "ipv6" : "ipv4";
+  if (type === "ipv6" && address.toLowerCase().startsWith("::ffff:")) return true;
+  return privateAddresses.check(address, type);
+}
+
+async function resolvePublicAddress(hostname) {
+  const host = hostname.replace(/^\[|\]$/g, "");
+  const literalFamily = isIP(host);
+  const addresses = literalFamily ? [{ address: host, family: literalFamily }] : await lookup(host, { all: true, verbatim: true });
+  if (addresses.length === 0) throw new OutlineKbError("URL_FETCH", `Source host did not resolve: ${hostname}`);
+  if (addresses.some(({ address, family }) => isPrivateAddress(address, family))) {
+    throw new OutlineKbError("UNSAFE_SOURCE_URL", `Source URL resolves to a private or local address: ${hostname}`);
+  }
+  return addresses[0];
+}
+
+/** Fetch public web text with DNS pinning, redirect re-validation and a hard response-size cap. */
+export async function fetchPublicText(input, { maxRedirects = 5, maxBytes = MAX_SOURCE_BYTES, headers = {} } = {}) {
+  let current = new URL(input);
+  for (let redirect = 0; redirect <= maxRedirects; redirect++) {
+    if (current.protocol !== "http:" && current.protocol !== "https:") {
+      throw new OutlineKbError("INVALID_SOURCE_URL", "Source URL must use http or https");
+    }
+    if (current.username || current.password) throw new OutlineKbError("UNSAFE_SOURCE_URL", "Source URL must not contain credentials");
+    const resolved = await resolvePublicAddress(current.hostname);
+    const response = await new Promise((resolveResponse, rejectResponse) => {
+      const transport = current.protocol === "https:" ? httpsRequest : httpRequest;
+      const request = transport(current, {
+        method: "GET",
+        headers: { "user-agent": "Oasis-Outline-KB/1", accept: "text/html,text/plain,application/xhtml+xml", "accept-encoding": "identity", ...headers },
+        lookup(_hostname, options, callback) {
+          if (options?.all) callback(null, [resolved]);
+          else callback(null, resolved.address, resolved.family);
+        },
+      }, (incoming) => {
+        const status = incoming.statusCode ?? 0;
+        if (status >= 300 && status < 400 && incoming.headers.location) {
+          incoming.resume();
+          resolveResponse({ redirect: new URL(incoming.headers.location, current).toString() });
+          return;
+        }
+        if (status < 200 || status >= 300) {
+          incoming.resume();
+          rejectResponse(new OutlineKbError("URL_FETCH", `URL fetch failed (${status})`));
+          return;
+        }
+        const contentType = String(incoming.headers["content-type"] ?? "").toLowerCase();
+        if (contentType && !contentType.startsWith("text/") && !contentType.startsWith("application/xhtml+xml")) {
+          incoming.resume();
+          rejectResponse(new OutlineKbError("UNSUPPORTED_URL_CONTENT", `URL returned unsupported content type: ${contentType}`));
+          return;
+        }
+        const chunks = [];
+        let size = 0;
+        incoming.on("data", (chunk) => {
+          size += chunk.length;
+          if (size > maxBytes) incoming.destroy(new OutlineKbError("URL_TOO_LARGE", `URL response exceeds ${maxBytes} bytes`));
+          else chunks.push(chunk);
+        });
+        incoming.on("end", () => resolveResponse({ text: Buffer.concat(chunks).toString("utf8") }));
+        incoming.on("error", rejectResponse);
+      });
+      request.setTimeout(DEFAULT_TIMEOUT_MS, () => request.destroy(new OutlineKbError("URL_FETCH", "URL fetch timed out")));
+      request.on("error", rejectResponse);
+      request.end();
+    });
+    if (response.redirect) {
+      if (redirect === maxRedirects) throw new OutlineKbError("URL_FETCH", "URL redirect limit exceeded");
+      current = new URL(response.redirect);
+      continue;
+    }
+    return { url: current.toString(), text: response.text };
+  }
+  throw new OutlineKbError("URL_FETCH", "URL redirect limit exceeded");
+}
+
+/** Fetch one public binary asset with the same SSRF and redirect boundary as page capture. */
+export async function fetchPublicBinary(input, { maxRedirects = 5, maxBytes = MAX_WECHAT_IMAGE_BYTES, headers = {} } = {}) {
+  let current = new URL(input);
+  for (let redirect = 0; redirect <= maxRedirects; redirect++) {
+    if (current.protocol !== "http:" && current.protocol !== "https:") throw new OutlineKbError("INVALID_SOURCE_URL", "Source URL must use http or https");
+    if (current.username || current.password) throw new OutlineKbError("UNSAFE_SOURCE_URL", "Source URL must not contain credentials");
+    const resolved = await resolvePublicAddress(current.hostname);
+    const response = await new Promise((resolveResponse, rejectResponse) => {
+      const transport = current.protocol === "https:" ? httpsRequest : httpRequest;
+      const request = transport(current, {
+        method: "GET",
+        headers: { "user-agent": WECHAT_FETCH_HEADERS["user-agent"], accept: "image/*", "accept-encoding": "identity", referer: "https://mp.weixin.qq.com/", ...headers },
+        lookup(_hostname, options, callback) {
+          if (options?.all) callback(null, [resolved]);
+          else callback(null, resolved.address, resolved.family);
+        },
+      }, (incoming) => {
+        const status = incoming.statusCode ?? 0;
+        if (status >= 300 && status < 400 && incoming.headers.location) {
+          incoming.resume();
+          resolveResponse({ redirect: new URL(incoming.headers.location, current).toString() });
+          return;
+        }
+        if (status < 200 || status >= 300) {
+          incoming.resume();
+          rejectResponse(new OutlineKbError("WECHAT_IMAGE_FETCH", `WeChat image fetch failed (${status})`));
+          return;
+        }
+        const contentType = String(incoming.headers["content-type"] ?? "").split(";", 1)[0].trim().toLowerCase();
+        if (contentType && !contentType.startsWith("image/")) {
+          incoming.resume();
+          rejectResponse(new OutlineKbError("WECHAT_IMAGE_FETCH", `WeChat image returned unsupported content type: ${contentType}`));
+          return;
+        }
+        const chunks = [];
+        let size = 0;
+        incoming.on("data", (chunk) => {
+          size += chunk.length;
+          if (size > maxBytes) incoming.destroy(new OutlineKbError("WECHAT_IMAGE_TOO_LARGE", `WeChat image exceeds ${maxBytes} bytes`));
+          else chunks.push(chunk);
+        });
+        incoming.on("end", () => resolveResponse({ bytes: Buffer.concat(chunks), contentType: contentType || "application/octet-stream" }));
+        incoming.on("error", rejectResponse);
+      });
+      request.setTimeout(DEFAULT_TIMEOUT_MS, () => request.destroy(new OutlineKbError("WECHAT_IMAGE_FETCH", "WeChat image fetch timed out")));
+      request.on("error", rejectResponse);
+      request.end();
+    });
+    if (response.redirect) {
+      if (redirect === maxRedirects) throw new OutlineKbError("URL_FETCH", "URL redirect limit exceeded");
+      current = new URL(response.redirect);
+      continue;
+    }
+    if (!response.bytes?.byteLength) throw new OutlineKbError("WECHAT_IMAGE_FETCH", "WeChat image response was empty");
+    return { url: current.toString(), bytes: response.bytes, contentType: response.contentType };
+  }
+  throw new OutlineKbError("URL_FETCH", "URL redirect limit exceeded");
+}
+
+function decodeHtmlEntities(value) {
+  const named = { amp: "&", apos: "'", gt: ">", lt: "<", nbsp: " ", quot: '"' };
+  return String(value ?? "").replace(/&(#(?:x[0-9a-f]+|\d+)|[a-z]+);/gi, (_match, entity) => {
+    const lower = entity.toLowerCase();
+    if (lower.startsWith("#")) {
+      const codePoint = Number.parseInt(lower.slice(lower.startsWith("#x") ? 2 : 1), lower.startsWith("#x") ? 16 : 10);
+      return Number.isInteger(codePoint) && codePoint >= 0 && codePoint <= 0x10ffff ? String.fromCodePoint(codePoint) : _match;
+    }
+    return named[lower] ?? _match;
+  });
+}
+
+function normalizeWechatText(value) {
+  return decodeHtmlEntities(String(value ?? "").replace(/<br\s*\/?\s*>/gi, "\n").replace(/<[^>]+>/g, " "))
+    .replace(/[\u200b\ufeff]/g, "")
+    .replace(/[ \t\r\f\v]+/g, " ")
+    .replace(/ *\n */g, "\n")
+    .trim();
+}
+
+function escapePattern(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function elementInnerHtmlById(page, id) {
+  const pattern = new RegExp(`<([a-z][\\w:-]*)\\b[^>]*\\bid\\s*=\\s*(["'])${escapePattern(id)}\\2[^>]*>`, "i");
+  const opening = pattern.exec(page);
+  if (!opening) return "";
+  const tag = opening[1];
+  const start = opening.index + opening[0].length;
+  const tokens = new RegExp(`<\\/?${escapePattern(tag)}\\b[^>]*>`, "gi");
+  tokens.lastIndex = start;
+  let depth = 1;
+  for (let token = tokens.exec(page); token; token = tokens.exec(page)) {
+    if (/^<\//.test(token[0])) depth--;
+    else if (!/\/>$/.test(token[0])) depth++;
+    if (depth === 0) return page.slice(start, token.index);
+  }
+  return "";
+}
+
+function jsStringValue(page, names) {
+  for (const name of names) {
+    const match = new RegExp(`(?:var\\s+)?${escapePattern(name)}\\s*=\\s*(?:htmlDecode\\(\\s*)?(["'])((?:\\\\.|(?!\\1)[\\s\\S])*)\\1(?:\\s*\\))?`, "i").exec(page);
+    if (!match) continue;
+    return decodeHtmlEntities(match[2]
+      .replace(/\\x([0-9a-f]{2})/gi, (_all, hex) => String.fromCodePoint(Number.parseInt(hex, 16)))
+      .replace(/\\u([0-9a-f]{4})/gi, (_all, hex) => String.fromCodePoint(Number.parseInt(hex, 16)))
+      .replace(/\\\//g, "/")
+      .replace(/\\(["'])/g, "$1"));
+  }
+  return "";
+}
+
+function attributeValue(tag, name) {
+  const match = new RegExp(`\\b${escapePattern(name)}\\s*=\\s*(?:(["'])([\\s\\S]*?)\\1|([^\\s>]+))`, "i").exec(tag);
+  return decodeHtmlEntities(match?.[2] ?? match?.[3] ?? "").trim();
+}
+
+export function isWeChatArticleUrl(input) {
+  try {
+    const url = new URL(input);
+    return (url.protocol === "http:" || url.protocol === "https:") && WECHAT_ARTICLE_HOSTS.has(url.hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+
+export function parseWeChatArticle(input, sourceUrl) {
+  if (!isWeChatArticleUrl(sourceUrl)) throw new OutlineKbError("INVALID_WECHAT_URL", "URL must point to a supported WeChat article host");
+  const page = String(input ?? "");
+  const contentHtml = elementInnerHtmlById(page, "js_content");
+  if (!contentHtml) throw new OutlineKbError("WECHAT_ARTICLE_INVALID", "WeChat article body #js_content was not found; the page may be a challenge or deleted article");
+  const bodyText = normalizeWechatText(contentHtml.replace(/<script\b[\s\S]*?<\/script>/gi, "").replace(/<style\b[\s\S]*?<\/style>/gi, ""));
+  if (bodyText.length < 200) throw new OutlineKbError("WECHAT_ARTICLE_INVALID", "WeChat article body is too short; the page may be a challenge or deleted article");
+
+  const title = normalizeWechatText(elementInnerHtmlById(page, "activity-name")) || jsStringValue(page, ["msg_title"]) || "未命名微信文章";
+  const account = normalizeWechatText(elementInnerHtmlById(page, "js_name")) || jsStringValue(page, ["nickname"]) || "未知公众号";
+  const explicitAuthor = normalizeWechatText(elementInnerHtmlById(page, "js_author_name")) || jsStringValue(page, ["author"]);
+  const author = explicitAuthor || account;
+  const timestamp = /(?:var\s+)?(?:create_time|ct)\s*=\s*["']?(\d{9,13})/i.exec(page)?.[1];
+  const publishedDate = timestamp ? new Date(Number(timestamp) < 1_000_000_000_000 ? Number(timestamp) * 1000 : Number(timestamp)) : null;
+  const publishedAt = publishedDate && !Number.isNaN(publishedDate.getTime()) ? publishedDate.toISOString() : "";
+  const images = [];
+  const prepared = contentHtml
+    .replace(/<script\b[\s\S]*?<\/script>/gi, "")
+    .replace(/<style\b[\s\S]*?<\/style>/gi, "")
+    .replace(/<([a-z][\w:-]*)\b[^>]*style\s*=\s*(["'])[^"']*display\s*:\s*none[^"']*\2[^>]*>[\s\S]*?<\/\1>/gi, "")
+    .replace(/<img\b[^>]*>/gi, (tag) => {
+      const url = attributeValue(tag, "data-src") || attributeValue(tag, "data-original") || attributeValue(tag, "src");
+      if (!/^https?:\/\//i.test(url)) return "";
+      const alt = attributeValue(tag, "alt") || `正文图片 ${images.length + 1}`;
+      images.push({ url, alt });
+      return `\n\n![${alt.replace(/[\[\]]/g, "")}](${url})\n\n`;
+    });
+  const markdownBody = decodeHtmlEntities(htmlToMarkdown(prepared));
+  if (normalizeWechatText(markdownBody).length < 200) throw new OutlineKbError("WECHAT_ARTICLE_INVALID", "WeChat article Markdown extraction produced insufficient content");
+  const publishedLine = publishedAt ? new Date(publishedAt).toLocaleString("zh-CN", { timeZone: "Asia/Shanghai", hour12: false }) : "未知";
+  const markdown = [
+    `# ${title}`,
+    "",
+    "> 微信公众号文章抓取",
+    `> 公众号/作者：${account} / ${author}`,
+    `> 发布时间：${publishedLine}`,
+    `> 原文：${sourceUrl}`,
+    "",
+    markdownBody,
+  ].join("\n").trim();
+  return { title, account, author, authorInferred: !explicitAuthor, publishedAt, markdown, images };
+}
+
+function scalar(value) {
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return JSON.stringify(value);
+  if (value === null || value === undefined) return "null";
+  const text = String(value);
+  return /^[A-Za-z0-9_.:/@+-]+$/.test(text) ? text : JSON.stringify(text);
+}
+
+function parseScalar(value) {
+  const text = value.trim();
+  if (text === "null") return null;
+  if (text === "true") return true;
+  if (text === "false") return false;
+  if (/^-?\d+(?:\.\d+)?$/.test(text)) return Number(text);
+  if ((text.startsWith("[") && text.endsWith("]")) || (text.startsWith('"') && text.endsWith('"'))) {
+    try { return JSON.parse(text); } catch { /* return literal below */ }
+  }
+  return text;
+}
+
+/** Outline rewrites traditional YAML frontmatter; fenced YAML survives Markdown round-trips. */
+export function encodeWikiDocument(metadata, body = "") {
+  const lines = Object.entries(metadata).map(([key, value]) => `${key}: ${scalar(value)}`);
+  return `\`\`\`${META_FENCE}\n${lines.join("\n")}\n\`\`\`\n\n${String(body)}`;
+}
+
+export function parseWikiDocument(text) {
+  const match = String(text ?? "").match(/^```yaml\n([\s\S]*?)\n```(?:\n+|$)([\s\S]*)$/);
+  if (!match) return { metadata: null, body: String(text ?? "") };
+  const metadata = {};
+  for (const line of match[1].split("\n")) {
+    if (!line.trim() || line.trimStart().startsWith("#")) continue;
+    const index = line.indexOf(":");
+    if (index <= 0) continue;
+    metadata[line.slice(0, index).trim()] = parseScalar(line.slice(index + 1));
+  }
+  return { metadata, body: match[2] ?? "" };
+}
+
+export function contentHash(input) {
+  const bytes = typeof input === "string" || Buffer.isBuffer(input) ? input : Buffer.from(input);
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function expectedType(path) {
+  const fixed = {
+    raw: "directory",
+    wiki: "directory",
+    "wiki/index": "index",
+    "wiki/overview": "overview",
+    "wiki/sources": "source-index",
+    "wiki/open-questions": "open-questions",
+    "wiki/concepts": "directory",
+    "wiki/synthesis": "directory",
+    log: "log",
+  };
+  if (fixed[path]) return fixed[path];
+  if (/^raw\/.+/.test(path)) return "raw";
+  if (/^wiki\/sources\/.+/.test(path)) return "source-note";
+  if (/^wiki\/concepts\/.+/.test(path)) return "concept";
+  if (/^wiki\/synthesis\/.+/.test(path)) return "synthesis";
+  return null;
+}
+
+function metadataIssues(path, text) {
+  const parsed = parseWikiDocument(text);
+  if (!parsed.metadata) return [{ code: "MISSING_METADATA", path }];
+  const metadata = parsed.metadata;
+  const issues = [];
+  const type = expectedType(path);
+  if (type && metadata.type !== type) issues.push({ code: "TYPE_MISMATCH", path, expected: type, actual: metadata.type ?? null });
+  const requireString = (field) => {
+    if (typeof metadata[field] !== "string" || !metadata[field].trim()) {
+      issues.push({ code: "MISSING_REQUIRED_METADATA", path, field });
+    }
+  };
+  const requireArray = (field) => {
+    if (!Array.isArray(metadata[field]) || metadata[field].length === 0) {
+      issues.push({ code: "MISSING_REQUIRED_METADATA", path, field });
+    }
+  };
+  if (type === "raw") {
+    requireString("source_kind");
+    requireString("source_hash");
+    requireString("content_hash");
+    if (typeof metadata.content_hash === "string" && contentHash(parsed.body) !== metadata.content_hash) {
+      issues.push({ code: "RAW_CONTENT_HASH_MISMATCH", path, expected: metadata.content_hash, actual: contentHash(parsed.body) });
+    }
+  }
+  if (type === "source-note") {
+    requireString("raw_ref");
+    requireString("ingested");
+    requireArray("topics");
+  }
+  if (type === "concept" || type === "synthesis") {
+    requireString("topic");
+    requireString("updated");
+    requireArray("sources");
+  }
+  if ((type === "overview" || type === "source-index") && (!Number.isInteger(metadata.source_count) || metadata.source_count < 0)) {
+    issues.push({ code: "MISSING_REQUIRED_METADATA", path, field: "source_count" });
+  }
+  if (type === "index") requireString("updated");
+  if (type === "log" && metadata.append_only !== true) issues.push({ code: "MISSING_REQUIRED_METADATA", path, field: "append_only" });
+  return issues;
+}
+
+function assertDocument(path, text) {
+  const issue = metadataIssues(path, text)[0];
+  if (issue) throw new OutlineKbError(issue.code, `${path} has invalid fenced metadata`, issue);
+}
+
+function assertRawPath(pathInput) {
+  const path = normalizePath(pathInput);
+  if (!path.startsWith("raw/")) throw new OutlineKbError("RAW_PATH_REQUIRED", `Import path must be under raw/: ${path}`);
+  return path;
+}
+
+function normalizeApiDocument(raw, baseUrl) {
+  const value = raw?.document ?? raw;
+  if (!value || typeof value !== "object") return null;
+  const relativeUrl = value.url ?? value.publishedUrl ?? null;
+  return {
+    ...value,
+    id: value.id ?? value.documentId ?? null,
+    title: value.title ?? "",
+    text: value.text ?? "",
+    parentDocumentId: value.parentDocumentId ?? null,
+    updatedAt: value.updatedAt ?? null,
+    url: relativeUrl ? new URL(relativeUrl, `${baseUrl}/`).toString() : null,
+  };
+}
+
+export class OutlineApiClient {
+  constructor({ baseUrl, apiToken, fetchImpl = globalThis.fetch, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+    if (!apiToken) throw new OutlineKbError("MISSING_TOKEN", "Outline API token is required");
+    this.baseUrl = cleanBaseUrl(baseUrl);
+    this.apiToken = apiToken;
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async call(endpoint, payload = {}) {
+    let response;
+    try {
+      response = await this.fetchImpl(`${this.baseUrl}/api/${endpoint}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${this.apiToken}`, "content-type": "application/json" },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (error) {
+      throw new OutlineKbError("OUTLINE_NETWORK", `Outline ${endpoint} request failed`, { cause: String(error) });
+    }
+    let body;
+    try { body = await response.json(); } catch { body = null; }
+    if (!response.ok || body?.ok === false) {
+      const message = body?.message ?? body?.error ?? `HTTP ${response.status}`;
+      throw new OutlineKbError("OUTLINE_API", `Outline ${endpoint} failed: ${message}`, {
+        endpoint,
+        status: response.status,
+        error: body?.error,
+      });
+    }
+    return body;
+  }
+
+  async authInfo() {
+    return this.call("auth.info", {});
+  }
+
+  async listDocuments(collectionId) {
+    const documents = [];
+    let offset = 0;
+    for (;;) {
+      const body = await this.call("documents.list", { collectionId, limit: 100, offset });
+      for (const raw of body?.data ?? []) {
+        const document = normalizeApiDocument(raw, this.baseUrl);
+        if (document?.id) documents.push(document);
+      }
+      const total = Number(body?.pagination?.total ?? documents.length);
+      offset += Number(body?.pagination?.limit ?? 100);
+      if (documents.length >= total || !(body?.pagination?.nextPath)) break;
+    }
+    return documents;
+  }
+
+  async info(id) {
+    const body = await this.call("documents.info", { id });
+    const document = normalizeApiDocument(body?.data, this.baseUrl);
+    if (!document?.id) throw new OutlineKbError("INVALID_RESPONSE", "Outline documents.info returned no document");
+    return document;
+  }
+
+  async create({ title, text, collectionId, parentDocumentId }) {
+    const body = await this.call("documents.create", {
+      title,
+      text,
+      collectionId,
+      ...(parentDocumentId ? { parentDocumentId } : {}),
+      publish: true,
+    });
+    const document = normalizeApiDocument(body?.data, this.baseUrl);
+    if (!document?.id) throw new OutlineKbError("INVALID_RESPONSE", "Outline documents.create returned no document");
+    return document;
+  }
+
+  async update({ id, text, title }) {
+    const body = await this.call("documents.update", { id, text, ...(title ? { title } : {}), publish: true });
+    const document = normalizeApiDocument(body?.data, this.baseUrl);
+    if (!document?.id) throw new OutlineKbError("INVALID_RESPONSE", "Outline documents.update returned no document");
+    return document;
+  }
+
+  async search(query, collectionId) {
+    const body = await this.call("documents.search", { query, collectionId });
+    return (body?.data ?? []).map((raw) => normalizeApiDocument(raw, this.baseUrl)).filter(Boolean);
+  }
+
+  async uploadAttachment({ documentId, filePath, contentType }) {
+    const file = await readFile(filePath);
+    const name = basename(filePath);
+    return this.uploadAttachmentData({ documentId, name, bytes: file, contentType });
+  }
+
+  async uploadAttachmentData({ documentId, name, bytes, contentType }) {
+    const created = await this.call("attachments.create", {
+      name,
+      documentId,
+      contentType,
+      size: bytes.byteLength,
+    });
+    const data = created?.data ?? {};
+    if (!data.uploadUrl) throw new OutlineKbError("ATTACHMENT_UNSUPPORTED", "Outline did not return an attachment upload URL");
+    const form = new FormData();
+    for (const [key, value] of Object.entries(data.form ?? {})) form.append(key, String(value));
+    form.append("file", new Blob([bytes], { type: contentType }), name);
+    const upload = await this.fetchImpl(new URL(data.uploadUrl, `${this.baseUrl}/`), {
+      method: "POST",
+      body: form,
+      signal: AbortSignal.timeout(this.timeoutMs),
+    });
+    if (!upload.ok) throw new OutlineKbError("ATTACHMENT_UPLOAD", `Outline attachment upload failed (${upload.status})`);
+    return data.attachment ?? { name, url: data.url ?? null };
+  }
+}
+
+function normalizePath(input) {
+  const value = String(input ?? "").trim().replace(/^\/+|\/+$/g, "").replace(/\/{2,}/g, "/");
+  if (!value || value.split("/").some((part) => !part || part === "." || part === "..")) {
+    throw new OutlineKbError("INVALID_PATH", `Invalid logical path: ${input}`);
+  }
+  return value;
+}
+
+function isUuid(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+
+async function mapConcurrent(values, limit, mapper) {
+  const results = new Array(values.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(limit, values.length) }, async () => {
+    for (;;) {
+      const index = next++;
+      if (index >= values.length) return;
+      results[index] = await mapper(values[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+export class OutlineWiki {
+  constructor(client, { collectionId, rootDocumentId = null, fetchUrl = fetchPublicText, fetchBinary = fetchPublicBinary }) {
+    if (!collectionId) throw new OutlineKbError("MISSING_COLLECTION", "collectionId is required");
+    this.client = client;
+    this.collectionId = collectionId;
+    this.rootDocumentId = rootDocumentId || null;
+    this.fetchUrl = fetchUrl;
+    this.fetchBinary = fetchBinary;
+  }
+
+  async snapshot() {
+    const documents = await this.client.listDocuments(this.collectionId);
+    const byId = new Map(documents.map((document) => [document.id, document]));
+    const pathById = new Map();
+    const buildPath = (document, seen = new Set()) => {
+      if (pathById.has(document.id)) return pathById.get(document.id);
+      if (seen.has(document.id)) throw new OutlineKbError("TREE_CYCLE", `Outline document tree has a cycle at ${document.id}`);
+      seen.add(document.id);
+      if (document.id === this.rootDocumentId) {
+        pathById.set(document.id, "");
+        return "";
+      }
+      const parent = document.parentDocumentId ? byId.get(document.parentDocumentId) : null;
+      if (this.rootDocumentId && !parent) return null;
+      const parentPath = parent ? buildPath(parent, seen) : "";
+      if (parentPath === null) return null;
+      const path = [parentPath, document.title].filter(Boolean).join("/");
+      pathById.set(document.id, path);
+      return path;
+    };
+    const byPath = new Map();
+    const scopedById = new Map();
+    for (const document of documents) {
+      const path = buildPath(document);
+      if (path === null) continue;
+      const scoped = { ...document, path };
+      scopedById.set(document.id, scoped);
+      const aliases = path === "" ? [document.title] : [path];
+      for (const alias of aliases) {
+        if (byPath.has(alias)) throw new OutlineKbError("AMBIGUOUS_PATH", `Duplicate logical path: ${alias}`);
+        byPath.set(alias, scoped);
+      }
+    }
+    return { documents: [...scopedById.values()], byPath, byId, scopedById };
+  }
+
+  async resolve(ref, snapshot = null) {
+    const tree = snapshot ?? await this.snapshot();
+    if (isUuid(ref)) {
+      const document = tree.scopedById.get(ref);
+      if (!document) throw new OutlineKbError("NOT_FOUND", `No document ${ref} in the configured knowledge root`);
+      return document;
+    }
+    const path = normalizePath(ref);
+    const document = tree.byPath.get(path);
+    if (!document) throw new OutlineKbError("NOT_FOUND", `No Outline document at logical path ${path}`);
+    return document;
+  }
+
+  async tree(under = null) {
+    const snapshot = await this.snapshot();
+    const prefix = under ? `${normalizePath(under)}/` : "";
+    return snapshot.documents
+      .filter((document) => !under || document.path === normalizePath(under) || document.path.startsWith(prefix))
+      .sort((a, b) => a.path.localeCompare(b.path));
+  }
+
+  async read(ref, snapshot = null) {
+    const document = await this.resolve(ref, snapshot);
+    return { ...(await this.client.info(document.id)), path: document.path };
+  }
+
+  async readMany(refs, snapshot = null) {
+    const tree = snapshot ?? await this.snapshot();
+    const resolved = [];
+    const seen = new Set();
+    for (const ref of refs) {
+      const document = await this.resolve(ref, tree);
+      if (seen.has(document.id)) continue;
+      seen.add(document.id);
+      resolved.push(document);
+    }
+    return Promise.all(resolved.map(async (document) => ({ ...(await this.client.info(document.id)), path: document.path })));
+  }
+
+  async create(pathInput, text, snapshot = null) {
+    const path = normalizePath(pathInput);
+    assertDocument(path, text);
+    const tree = snapshot ?? await this.snapshot();
+    const existing = tree.byPath.get(path);
+    if (existing) {
+      const current = await this.client.info(existing.id);
+      if (current.text.trim() === text.trim()) return { status: "existing", document: current };
+      throw new OutlineKbError("ALREADY_EXISTS", `${path} already exists with different content`);
+    }
+    const parts = path.split("/");
+    const title = parts.pop();
+    const parentPath = parts.join("/");
+    const parentDocumentId = parentPath
+      ? (await this.resolve(parentPath, tree)).id
+      : this.rootDocumentId;
+    const document = await this.client.create({ title, text, collectionId: this.collectionId, parentDocumentId });
+    const scoped = { ...document, path };
+    tree.documents.push(scoped);
+    tree.byPath.set(path, scoped);
+    tree.byId.set(document.id, document);
+    tree.scopedById.set(document.id, scoped);
+    return {
+      status: "created",
+      document,
+    };
+  }
+
+  async update(pathInput, text, expectedUpdatedAt, snapshot = null) {
+    const path = normalizePath(pathInput);
+    if (path === "raw" || path.startsWith("raw/")) throw new OutlineKbError("RAW_IMMUTABLE", `Cannot update immutable path ${path}`);
+    if (path === "log") throw new OutlineKbError("LOG_APPEND_ONLY", "log can only be changed through append");
+    assertDocument(path, text);
+    if (!expectedUpdatedAt) throw new OutlineKbError("MISSING_PRECONDITION", `${path} update requires expectedUpdatedAt`);
+    const current = await this.read(path, snapshot);
+    if (current.text.trim() === text.trim()) return { status: "unchanged", document: current };
+    if (current.updatedAt !== expectedUpdatedAt) {
+      throw new OutlineKbError("UPDATE_CONFLICT", `${path} changed after the plan was created`, {
+        expectedUpdatedAt,
+        actualUpdatedAt: current.updatedAt,
+      });
+    }
+    return { status: "updated", document: await this.client.update({ id: current.id, text }) };
+  }
+
+  async appendLog(fragment, jobId, snapshot = null) {
+    if (!jobId) throw new OutlineKbError("MISSING_JOB_ID", "append log requires jobId");
+    const current = await this.read("log", snapshot);
+    const marker = `<!-- job:${jobId} -->`;
+    if (current.text.includes(marker)) return { status: "existing", document: current };
+    const text = `${current.text.trimEnd()}\n\n${marker}\n${fragment.trim()}\n`;
+    return { status: "appended", document: await this.client.update({ id: current.id, text }) };
+  }
+
+  async init() {
+    const definitions = [
+      ["raw", { type: "directory" }, "# 原始来源\n\n只创建新版本，不覆盖已有内容。"],
+      ["wiki", { type: "directory" }, "# Wiki"],
+      ["wiki/index", { type: "index", updated: new Date().toISOString().slice(0, 10) }, "# 知识库索引\n\n- [全局综述](kb://wiki/overview)\n- [来源](kb://wiki/sources)\n- [概念](kb://wiki/concepts)\n- [综合](kb://wiki/synthesis)\n- [待研究问题](kb://wiki/open-questions)"],
+      ["wiki/overview", { type: "overview", source_count: 0 }, "# 全局综述"],
+      ["wiki/sources", { type: "source-index", source_count: 0 }, "# 来源目录"],
+      ["wiki/open-questions", { type: "open-questions" }, "# 待研究问题"],
+      ["wiki/concepts", { type: "directory" }, "# 概念"],
+      ["wiki/synthesis", { type: "directory" }, "# 综合"],
+      ["log", { type: "log", append_only: true }, "# 维护日志"],
+    ];
+    const tree = await this.snapshot();
+    const results = new Map(await Promise.all(definitions
+      .filter(([path]) => tree.byPath.has(path))
+      .map(async ([path]) => [path, { path, status: "existing", document: await this.read(path, tree) }])));
+    for (const [path, metadata, body] of definitions) {
+      if (tree.byPath.has(path)) continue;
+      const parts = path.split("/");
+      const title = parts.pop();
+      const parentPath = parts.join("/");
+      const parentDocumentId = parentPath ? (await this.resolve(parentPath, tree)).id : this.rootDocumentId;
+      const document = await this.client.create({
+        title,
+        text: encodeWikiDocument(metadata, body),
+        collectionId: this.collectionId,
+        parentDocumentId,
+      });
+      const scoped = { ...document, path };
+      tree.documents.push(scoped);
+      tree.byPath.set(path, scoped);
+      tree.byId.set(document.id, document);
+      tree.scopedById.set(document.id, scoped);
+      results.set(path, { path, status: "created", document });
+    }
+    return definitions.map(([path]) => results.get(path));
+  }
+
+  async search(query, under = null, limit = 10, snapshot = null) {
+    const matches = await this.client.search(query, this.collectionId);
+    const tree = snapshot ?? await this.snapshot();
+    const pathOf = new Map(tree.documents.map((document) => [document.id, document.path]));
+    const prefix = under ? `${normalizePath(under)}/` : null;
+    const explicitRaw = under ? (normalizePath(under) === "raw" || normalizePath(under).startsWith("raw/")) : false;
+    return matches
+      .map((document) => {
+        const path = pathOf.get(document.id);
+        return path === undefined ? null : { ...document, path };
+      })
+      .filter((document) => document
+        && (explicitRaw || !(document.path === "raw" || document.path.startsWith("raw/")))
+        && (!under || document.path === normalizePath(under) || document.path.startsWith(prefix)))
+      .slice(0, Math.max(1, Math.min(Number(limit) || 10, 20)));
+  }
+
+  async searchAndRead(query, { under = null, limit = 8 } = {}) {
+    const tree = await this.snapshot();
+    const matches = await this.search(query, under, limit, tree);
+    return this.readMany(matches.map((document) => document.id), tree);
+  }
+
+  async finalizeRawImport(path, document) {
+    const current = await this.client.info(document.id);
+    const parsed = parseWikiDocument(current.text);
+    const actualHash = contentHash(parsed.body);
+    const pending = parsed.metadata?.content_hash_state === CONTENT_HASH_PENDING;
+    if (!pending) {
+      if (parsed.metadata?.content_hash === actualHash) return current;
+      throw new OutlineKbError("RAW_CONTENT_HASH_MISMATCH", `${path} content changed after import`, {
+        path,
+        expected: parsed.metadata?.content_hash ?? null,
+        actual: actualHash,
+      });
+    }
+
+    const { content_hash_state: _state, ...metadata } = parsed.metadata;
+    const updated = await this.client.update({
+      id: current.id,
+      text: encodeWikiDocument({ ...metadata, content_hash: actualHash }, parsed.body),
+    });
+    const verified = await this.client.info(updated.id);
+    const verifiedParsed = parseWikiDocument(verified.text);
+    const verifiedHash = contentHash(verifiedParsed.body);
+    if (verifiedParsed.metadata?.content_hash !== verifiedHash) {
+      throw new OutlineKbError("RAW_CONTENT_HASH_UNSTABLE", `${path} did not stabilize after Outline Markdown normalization`, {
+        path,
+        expected: verifiedParsed.metadata?.content_hash ?? null,
+        actual: verifiedHash,
+      });
+    }
+    return verified;
+  }
+
+  async createRaw(path, metadata, body) {
+    const created = await this.create(path, encodeWikiDocument({
+      ...metadata,
+      content_hash: contentHash(body),
+      content_hash_state: CONTENT_HASH_PENDING,
+    }, body));
+    return { ...created, document: await this.finalizeRawImport(path, created.document) };
+  }
+
+  async createWechatRaw(path, metadata, article, assets) {
+    const pendingMetadata = {
+      ...metadata,
+      image_archived_count: 0,
+      content_hash: contentHash(article.markdown),
+      content_hash_state: CONTENT_HASH_PENDING,
+    };
+    const created = await this.create(path, encodeWikiDocument(pendingMetadata, article.markdown));
+    let body = article.markdown;
+    const attachments = [];
+    let failed = 0;
+    const archiveErrors = [];
+    for (const [index, asset] of assets.entries()) {
+      try {
+        const extension = ({ "image/gif": ".gif", "image/jpeg": ".jpg", "image/png": ".png", "image/webp": ".webp" })[asset.contentType] ?? ".bin";
+        const name = `wechat-${String(index + 1).padStart(2, "0")}-${contentHash(asset.image.url).slice(0, 10)}${extension}`;
+        const attachment = await this.client.uploadAttachmentData({ documentId: created.document.id, name, bytes: asset.bytes, contentType: asset.contentType });
+        const attachmentUrl = attachment?.url ? new URL(attachment.url, `${this.client.baseUrl}/`).toString() : "";
+        if (!attachmentUrl) throw new OutlineKbError("ATTACHMENT_UNSUPPORTED", "Outline attachment response did not contain a URL");
+        body = body.split(`](${asset.image.url})`).join(`](${attachmentUrl})`);
+        attachments.push({ name, url: attachmentUrl, sourceUrl: asset.image.url });
+      } catch (error) {
+        failed++;
+        archiveErrors.push(error instanceof Error ? error.message : String(error));
+      }
+    }
+    const finalizedMetadata = {
+      ...metadata,
+      image_archived_count: attachments.length,
+      ...(failed ? { image_archive_failed: failed } : {}),
+      content_hash: contentHash(body),
+      content_hash_state: CONTENT_HASH_PENDING,
+    };
+    const updated = await this.client.update({ id: created.document.id, text: encodeWikiDocument(finalizedMetadata, body) });
+    return {
+      ...created,
+      document: await this.finalizeRawImport(path, updated),
+      attachments,
+      ...(failed ? { warnings: [{ code: "WECHAT_IMAGE_ARCHIVE_PARTIAL", message: `${failed} WeChat images could not be archived; original URLs were retained`, errors: archiveErrors }] } : {}),
+    };
+  }
+
+  async importFile(filePath, rawPath, { textFile = null, contentType = null } = {}) {
+    const path = assertRawPath(rawPath);
+    const bytes = await readFile(filePath);
+    const hash = contentHash(bytes);
+    const extension = extname(filePath).toLowerCase();
+    if (![".md", ".txt", ".pdf"].includes(extension)) {
+      throw new OutlineKbError("UNSUPPORTED_FILE_TYPE", "V1 only supports Markdown, TXT and PDF files");
+    }
+    const tree = await this.snapshot();
+    for (const document of tree.documents.filter((item) => item.path.startsWith("raw/"))) {
+      const current = await this.client.info(document.id);
+      if (parseWikiDocument(current.text).metadata?.source_hash === hash) {
+        return { status: "existing", sourceHash: hash, document: await this.finalizeRawImport(document.path, current), path: document.path };
+      }
+    }
+    const type = contentType ?? (extension === ".pdf" ? "application/pdf" : "text/plain");
+    let sourceText;
+    if (extension === ".pdf") {
+      if (!textFile) throw new OutlineKbError("PDF_TEXT_REQUIRED", "PDF import requires --text-file with extracted Markdown");
+      sourceText = await readFile(textFile, "utf8");
+    } else {
+      sourceText = bytes.toString("utf8");
+    }
+    const metadata = {
+      type: "raw",
+      source_kind: extension === ".pdf" ? "pdf" : "file",
+      source_name: basename(filePath),
+      source_hash: hash,
+      imported_at: new Date().toISOString(),
+    };
+    const created = await this.createRaw(path, metadata, sourceText);
+    let attachment = null;
+    if (extension === ".pdf") {
+      attachment = await this.client.uploadAttachment({ documentId: created.document.id, filePath, contentType: type });
+    }
+    return { ...created, sourceHash: hash, attachment, searchableText: extension !== ".pdf" || Boolean(textFile) };
+  }
+
+  async importUrl(urlInput, rawPath) {
+    const path = assertRawPath(rawPath);
+    const parsedUrl = new URL(urlInput);
+    if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+      throw new OutlineKbError("INVALID_SOURCE_URL", "Source URL must use http or https");
+    }
+    const url = parsedUrl.toString();
+    const wechat = isWeChatArticleUrl(url);
+    const fetched = await this.fetchUrl(url, wechat ? { headers: WECHAT_FETCH_HEADERS } : undefined);
+    const html = fetched.text;
+    const hash = contentHash(html);
+    const tree = await this.snapshot();
+    for (const document of tree.documents.filter((item) => item.path.startsWith("raw/"))) {
+      const current = await this.client.info(document.id);
+      const metadata = parseWikiDocument(current.text).metadata;
+      if (metadata?.source_hash === hash || (wechat && metadata?.source_url === url)) {
+        return { status: "existing", sourceHash: metadata.source_hash ?? hash, document: await this.finalizeRawImport(document.path, current), path: document.path };
+      }
+    }
+    const article = wechat ? parseWeChatArticle(html, url) : null;
+    const markdown = article?.markdown ?? htmlToMarkdown(html);
+    const uniqueImages = article?.images.filter((image, index, items) => items.findIndex((item) => item.url === image.url) === index) ?? [];
+    let imageBytes = 0;
+    const assets = article
+      ? await mapConcurrent(uniqueImages.slice(0, MAX_WECHAT_IMAGES), 4, async (image) => {
+          const fetchedImage = await this.fetchBinary(image.url);
+          imageBytes += fetchedImage.bytes.byteLength;
+          if (imageBytes > MAX_WECHAT_TOTAL_IMAGE_BYTES) {
+            throw new OutlineKbError("WECHAT_IMAGES_TOO_LARGE", `WeChat images exceed ${MAX_WECHAT_TOTAL_IMAGE_BYTES} total bytes`);
+          }
+          return { image, ...fetchedImage };
+        })
+      : [];
+    const metadata = {
+      type: "raw",
+      source_kind: wechat ? "wechat" : "url",
+      source_url: url,
+      ...(fetched.url !== url ? { resolved_url: fetched.url } : {}),
+      ...(article ? {
+        source_title: article.title,
+        source_account: article.account,
+        source_author: article.author,
+        ...(article.authorInferred ? { source_author_inferred: true } : {}),
+        ...(article.publishedAt ? { published_at: article.publishedAt } : {}),
+        image_count: article.images.length,
+        ...(uniqueImages.length > MAX_WECHAT_IMAGES ? { image_archive_skipped: uniqueImages.length - MAX_WECHAT_IMAGES } : {}),
+      } : {}),
+      source_hash: hash,
+      fetched_at: new Date().toISOString(),
+    };
+    const imported = article
+      ? await this.createWechatRaw(path, metadata, article, assets)
+      : await this.createRaw(path, metadata, markdown);
+    return {
+      ...imported,
+      sourceHash: hash,
+      ...(article ? { sourceKind: "wechat", article: { title: article.title, account: article.account, author: article.author, authorInferred: article.authorInferred, publishedAt: article.publishedAt, imageCount: article.images.length } } : {}),
+    };
+  }
+
+  async importWeChatUrl(url, rawPath) {
+    if (!isWeChatArticleUrl(url)) throw new OutlineKbError("INVALID_WECHAT_URL", "import-wechat requires a WeChat article URL");
+    return this.importUrl(url, rawPath);
+  }
+
+  async validatePlan(plan, planFile = null, snapshot = null, preflight = null) {
+    const local = preflight ?? await preflightPlanFiles(plan, planFile);
+    const tree = snapshot ?? await this.snapshot();
+    const availablePaths = new Set(tree.byPath.keys());
+    const validated = [];
+    for (const operation of local.operations) {
+      const path = operation.path;
+      if (operation.type === "create") {
+        const parentPath = path.split("/").slice(0, -1).join("/");
+        if (parentPath && !availablePaths.has(parentPath)) {
+          throw new OutlineKbError("INVALID_PLAN", `create parent must exist or be created earlier in the plan: ${parentPath}`);
+        }
+        availablePaths.add(path);
+      }
+      const content = operation.content;
+      if (operation.type === "create" && tree.byPath.has(path)) {
+        const current = await this.client.info(tree.byPath.get(path).id);
+        if (current.text.trim() !== content.trim()) throw new OutlineKbError("ALREADY_EXISTS", `${path} exists with different content`);
+      }
+      if (operation.type === "update") {
+        if (!operation.expectedUpdatedAt) throw new OutlineKbError("MISSING_PRECONDITION", `${path} update requires expectedUpdatedAt`);
+        const listed = await this.resolve(path, tree);
+        const current = await this.client.info(listed.id);
+        if (current.text.trim() !== content.trim() && current.updatedAt !== operation.expectedUpdatedAt) {
+          throw new OutlineKbError("UPDATE_CONFLICT", `${path} changed after plan creation`, {
+            expectedUpdatedAt: operation.expectedUpdatedAt,
+            actualUpdatedAt: current.updatedAt,
+          });
+        }
+      }
+      validated.push({ ...operation, path, content });
+    }
+    return { jobId: local.jobId, sourceHash: local.sourceHash, operations: validated };
+  }
+
+  async applyPlan(plan, planFile = null, preflight = null) {
+    const local = preflight ?? await preflightPlanFiles(plan, planFile);
+    const tree = await this.snapshot();
+    const validated = await this.validatePlan(plan, planFile, tree, local);
+    const results = [];
+    for (const operation of validated.operations) {
+      if (operation.type === "create") results.push({ path: operation.path, ...(await this.create(operation.path, operation.content, tree)) });
+      if (operation.type === "update") results.push({ path: operation.path, ...(await this.update(operation.path, operation.content, operation.expectedUpdatedAt, tree)) });
+      if (operation.type === "append") results.push({ path: operation.path, ...(await this.appendLog(operation.content, validated.jobId, tree)) });
+    }
+    const fullLint = await this.lint(tree);
+    const changedPaths = validated.operations.map((operation) => operation.path);
+    const changesKnowledge = changedPaths.some((path) => path === "raw" || path.startsWith("raw/") || path === "wiki" || path.startsWith("wiki/"));
+    const changesSources = changedPaths.some((path) => path.startsWith("wiki/sources/"));
+    const touchesCurrentChange = (issue) => {
+      const issuePath = typeof issue?.path === "string" ? normalizePath(issue.path) : "";
+      if (!issuePath) return true;
+      if (changesKnowledge && issue.code === "MISSING_REQUIRED") return true;
+      if (changesSources && issue.code === "SOURCE_COUNT_MISMATCH") return true;
+      return changedPaths.some((path) => path === issuePath || path.startsWith(`${issuePath}/`) || issuePath.startsWith(`${path}/`));
+    };
+    const errors = fullLint.errors.filter(touchesCurrentChange);
+    const healthErrors = fullLint.errors.filter((issue) => !touchesCurrentChange(issue));
+    const lint = { ...fullLint, ok: errors.length === 0, errors, ...(healthErrors.length ? { healthErrors } : {}) };
+    return { jobId: validated.jobId, results, lint, status: lint.ok ? "succeeded" : "needs_repair" };
+  }
+
+  async lint(snapshot = null) {
+    const tree = snapshot ?? await this.snapshot();
+    const errors = [];
+    const warnings = [];
+    const required = ["raw", "wiki", "wiki/index", "wiki/overview", "wiki/sources", "wiki/open-questions", "wiki/concepts", "wiki/synthesis", "log"];
+    for (const path of required) if (!tree.byPath.has(path)) errors.push({ code: "MISSING_REQUIRED", path });
+
+    const scopedDocuments = tree.documents.filter((document) => document.path !== "");
+    const loadedDocuments = await mapConcurrent(scopedDocuments, 8, async (document) => {
+      const current = await this.client.info(document.id);
+      return { ...current, path: document.path, parsed: parseWikiDocument(current.text) };
+    });
+    const loaded = new Map(loadedDocuments.map((document) => [document.path, document]));
+    for (const document of loaded.values()) {
+      errors.push(...metadataIssues(document.path, document.text));
+      for (const marker of ["citation-needed", "conflict", "stale"]) {
+        if (document.text.includes(marker)) warnings.push({ code: marker.toUpperCase().replace("-", "_"), path: document.path });
+      }
+      for (const ref of linkRefs(document.text)) {
+        if (!tree.byPath.has(ref)) errors.push({ code: "BROKEN_LINK", path: document.path, target: ref });
+      }
+    }
+
+    const raws = [...loaded.values()].filter((document) => /^raw\/.+/.test(document.path));
+    const sources = [...loaded.values()].filter((document) => /^wiki\/sources\/.+/.test(document.path));
+    const sourceByRaw = new Map();
+    for (const source of sources) {
+      const rawRef = source.parsed.metadata?.raw_ref;
+      if (typeof rawRef !== "string" || !loaded.has(rawRef)) {
+        errors.push({ code: "SOURCE_RAW_MISSING", path: source.path, target: rawRef ?? null });
+      } else if (sourceByRaw.has(rawRef)) {
+        errors.push({ code: "DUPLICATE_SOURCE_NOTE", path: source.path, target: rawRef });
+      } else {
+        sourceByRaw.set(rawRef, source.path);
+        if (!linkRefs(source.text).includes(rawRef)) errors.push({ code: "SOURCE_RAW_LINK_MISSING", path: source.path, target: rawRef });
+      }
+    }
+    for (const raw of raws) if (!sourceByRaw.has(raw.path)) errors.push({ code: "RAW_WITHOUT_SOURCE_NOTE", path: raw.path });
+
+    const concepts = [...loaded.values()].filter((document) => /^wiki\/(?:concepts|synthesis)\/.+/.test(document.path));
+    const citedSources = new Set();
+    const topics = new Map();
+    for (const document of concepts) {
+      const refs = document.parsed.metadata?.sources;
+      if (!Array.isArray(refs) || refs.length === 0) errors.push({ code: "GENERATED_WITHOUT_SOURCE", path: document.path });
+      for (const ref of Array.isArray(refs) ? refs : []) {
+        if (typeof ref !== "string" || !/^wiki\/sources\/.+/.test(ref)) errors.push({ code: "SOURCE_REF_INVALID", path: document.path, target: ref });
+        else if (!loaded.has(ref)) errors.push({ code: "SOURCE_REF_MISSING", path: document.path, target: ref });
+        else citedSources.add(ref);
+      }
+      const topic = document.parsed.metadata?.topic;
+      if (typeof topic === "string") {
+        if (topics.has(topic)) errors.push({ code: "DUPLICATE_TOPIC", path: document.path, other: topics.get(topic), topic });
+        else topics.set(topic, document.path);
+      }
+    }
+    for (const source of sources) if (!citedSources.has(source.path)) errors.push({ code: "SOURCE_NOT_IN_CONCEPT", path: source.path });
+
+    const expectedCount = sources.length;
+    for (const path of ["wiki/sources", "wiki/overview"]) {
+      const actual = loaded.get(path)?.parsed.metadata?.source_count;
+      if (actual !== expectedCount) errors.push({ code: "SOURCE_COUNT_MISMATCH", path, expected: expectedCount, actual: actual ?? null });
+    }
+
+    const conceptPages = [...loaded.values()].filter((document) => /^wiki\/concepts\/.+/.test(document.path));
+    for (let left = 0; left < conceptPages.length; left++) {
+      for (let right = left + 1; right < conceptPages.length; right++) {
+        const a = conceptPages[left];
+        const b = conceptPages[right];
+        const score = titleSimilarity(a.title, b.title);
+        if (score >= 0.8) warnings.push({ code: "SIMILAR_CONCEPT_TITLE", path: a.path, other: b.path, score: Number(score.toFixed(2)) });
+      }
+    }
+
+    const reachable = new Set(["wiki/index"]);
+    const queue = ["wiki/index"];
+    while (queue.length) {
+      const path = queue.shift();
+      const document = loaded.get(path);
+      if (!document) continue;
+      const refs = [...linkRefs(document.text), ...(Array.isArray(document.parsed.metadata?.sources) ? document.parsed.metadata.sources : [])];
+      if (typeof document.parsed.metadata?.raw_ref === "string") refs.push(document.parsed.metadata.raw_ref);
+      for (const ref of refs) if (!reachable.has(ref) && loaded.has(ref)) { reachable.add(ref); queue.push(ref); }
+    }
+    for (const document of loaded.values()) {
+      if (["raw", "wiki", "wiki/concepts", "wiki/synthesis", "log"].includes(document.path)) continue;
+      if (!reachable.has(document.path)) errors.push({ code: "UNREACHABLE", path: document.path });
+    }
+    return { ok: errors.length === 0, files: loaded.size, rawCount: raws.length, sourceCount: sources.length, errors, warnings };
+  }
+}
+
+function linkRefs(text) {
+  const refs = [];
+  const pattern = /\]\(kb:\/\/([^\s)]+)\)/g;
+  for (const match of String(text ?? "").matchAll(pattern)) {
+    try { refs.push(decodeURIComponent(match[1])); }
+    catch { refs.push(match[1]); }
+  }
+  return refs;
+}
+
+function titleSimilarity(left, right) {
+  const a = String(left ?? "").toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "");
+  const b = String(right ?? "").toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "");
+  if (a.length < 4 || b.length < 4 || a === b) return a === b && a.length >= 4 ? 1 : 0;
+  const previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      current[j] = Math.min(
+        current[j - 1] + 1,
+        previous[j] + 1,
+        previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    previous.splice(0, previous.length, ...current);
+  }
+  return 1 - previous[b.length] / Math.max(a.length, b.length);
+}
+
+function htmlToMarkdown(html) {
+  return String(html)
+    .replace(/<script\b[\s\S]*?<\/script>/gi, "")
+    .replace(/<style\b[\s\S]*?<\/style>/gi, "")
+    .replace(/<h1\b[^>]*>([\s\S]*?)<\/h1>/gi, "# $1\n\n")
+    .replace(/<h2\b[^>]*>([\s\S]*?)<\/h2>/gi, "## $1\n\n")
+    .replace(/<h3\b[^>]*>([\s\S]*?)<\/h3>/gi, "### $1\n\n")
+    .replace(/<h4\b[^>]*>([\s\S]*?)<\/h4>/gi, "#### $1\n\n")
+    .replace(/<h5\b[^>]*>([\s\S]*?)<\/h5>/gi, "#### $1\n\n")
+    .replace(/<h6\b[^>]*>([\s\S]*?)<\/h6>/gi, "#### $1\n\n")
+    .replace(/<blockquote\b[^>]*>([\s\S]*?)<\/blockquote>/gi, "> $1\n\n")
+    .replace(/<li\b[^>]*>([\s\S]*?)<\/li>/gi, "- $1\n")
+    .replace(/<br\s*\/?\s*>/gi, "\n")
+    .replace(/<\/p>/gi, "\n\n")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function operationFileDetails(fullPath, contentFile, operation, operationIndex, error = null) {
+  return {
+    path: fullPath,
+    contentFile,
+    operationIndex,
+    operationType: operation?.type ?? null,
+    operationPath: operation?.path ?? null,
+    ...(error?.code ? { fsCode: error.code } : {}),
+  };
+}
+
+async function readPlanFile(planFile) {
+  const full = resolve(planFile);
+  let text;
+  try {
+    text = await readFile(full, "utf8");
+  } catch (error) {
+    const code = error?.code === "ENOENT" ? "PLAN_FILE_NOT_FOUND" : "PLAN_FILE_UNREADABLE";
+    const message = code === "PLAN_FILE_NOT_FOUND" ? `Plan file not found: ${full}` : `Plan file is unreadable: ${full}`;
+    throw new OutlineKbError(code, message, { path: full, ...(error?.code ? { fsCode: error.code } : {}) });
+  }
+  try {
+    return { path: full, plan: JSON.parse(text) };
+  } catch (error) {
+    throw new OutlineKbError("PLAN_JSON_INVALID", `Plan file contains invalid JSON: ${full}`, {
+      path: full,
+      parseMessage: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+async function readPlanContent(contentFile, planFile, operation, operationIndex) {
+  if (!contentFile || typeof contentFile !== "string") throw new OutlineKbError("INVALID_PLAN", "operation requires contentFile");
+  const base = planFile ? dirname(resolve(planFile)) : process.cwd();
+  const full = resolve(base, contentFile);
+  const rel = relative(base, full);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    throw new OutlineKbError("INVALID_PLAN", `contentFile escapes plan directory: ${contentFile}`, operationFileDetails(full, contentFile, operation, operationIndex));
+  }
+  try {
+    return await readFile(full, "utf8");
+  } catch (error) {
+    const code = error?.code === "ENOENT" ? "CONTENT_FILE_NOT_FOUND" : "CONTENT_FILE_UNREADABLE";
+    const message = code === "CONTENT_FILE_NOT_FOUND" ? `Plan content file not found: ${full}` : `Plan content file is unreadable: ${full}`;
+    throw new OutlineKbError(code, message, operationFileDetails(full, contentFile, operation, operationIndex, error));
+  }
+}
+
+async function preflightPlanFiles(plan, planFile = null, options = {}) {
+  if (!plan || typeof plan !== "object" || Array.isArray(plan) || !Array.isArray(plan.operations)) {
+    throw new OutlineKbError("INVALID_PLAN", "Plan must contain an operations array");
+  }
+  if (!plan.jobId || typeof plan.jobId !== "string") throw new OutlineKbError("INVALID_PLAN", "Plan requires jobId");
+  const seen = new Set();
+  const operations = [];
+  const allowedOperationTypes = options.allowedOperationTypes ?? new Set(["create", "update", "append"]);
+  for (let index = 0; index < plan.operations.length; index++) {
+    const operation = plan.operations[index];
+    if (!operation || !allowedOperationTypes.has(operation.type)) {
+      throw new OutlineKbError("INVALID_PLAN", `Unsupported operation at index ${index}`);
+    }
+    const path = normalizePath(operation.path);
+    if (seen.has(path)) throw new OutlineKbError("INVALID_PLAN", `Plan contains more than one operation for ${path}`);
+    seen.add(path);
+    if (operation.type === "update" && (path === "raw" || path.startsWith("raw/"))) {
+      throw new OutlineKbError("RAW_IMMUTABLE", `Plan cannot update ${path}`);
+    }
+    if (path === "log" && operation.type !== "append") throw new OutlineKbError("LOG_APPEND_ONLY", "Plan may only append log");
+    if (operation.type === "append" && path !== "log") throw new OutlineKbError("INVALID_PLAN", "append is only supported for log");
+    const content = await readPlanContent(operation.contentFile, planFile, operation, index);
+    if (operation.type !== "append" && options.validateMetadata !== false) assertDocument(path, content);
+    operations.push({ ...operation, path, content });
+  }
+  return { jobId: plan.jobId, sourceHash: plan.sourceHash ?? null, operations };
+}
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = new Map();
+  for (let index = 0; index < argv.length; index++) {
+    const value = argv[index];
+    if (!value.startsWith("--")) { positional.push(value); continue; }
+    const key = value.slice(2);
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith("--")) flags.set(key, "true");
+    else { flags.set(key, next); index++; }
+  }
+  return { positional, flags };
+}
+
+function need(value, message) {
+  if (!value) throw new OutlineKbError("USAGE", message);
+  return value;
+}
+
+function positiveLimit(value, fallback) {
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > 20) {
+    throw new OutlineKbError("USAGE", "--limit must be an integer from 1 to 20");
+  }
+  return parsed;
+}
+
+function publicDocument(document) {
+  if (!document) return document;
+  const { id, title, path, url, parentDocumentId, updatedAt, text } = document;
+  return { id, title, ...(path ? { path } : {}), url, parentDocumentId, updatedAt, ...(text !== undefined ? { text } : {}) };
+}
+
+async function run(argv, env = process.env) {
+  const { positional, flags } = parseArgs(argv);
+  const command = positional.shift();
+  if (flags.has("help") || command === "help" || command === "-h") {
+    const help = command && command !== "help" && command !== "-h" ? COMMAND_HELP[command] : null;
+    return help
+      ? { ok: true, command, ...help, successExample: successExample(command), failureExample: HELP_FAILURE_EXAMPLE }
+      : { ok: true, usage: USAGE, commands: Object.keys(COMMAND_HELP), failureExample: HELP_FAILURE_EXAMPLE };
+  }
+  if (env.OUTLINE_KB_QUERY_MODE === "1" && !QUERY_COMMANDS.has(command)) {
+    throw new OutlineKbError("QUERY_COMMAND_DISABLED", `outline-kb ${command ?? "<missing>"} is disabled for a knowledge query`);
+  }
+  if (env.OUTLINE_KB_READ_ONLY === "1" && WRITE_COMMANDS.has(command)) {
+    throw new OutlineKbError("READ_ONLY", `outline-kb ${command} is disabled for a read-only knowledge query`);
+  }
+  if (env.OUTLINE_KB_INGEST_MODE === "1" && INGEST_FORBIDDEN_COMMANDS.has(command)) {
+    throw new OutlineKbError("INGEST_COMMAND_DISABLED", `outline-kb ${command} is disabled until the ingest Candidate is approved`);
+  }
+  if (command === "validate-maintenance-plan" && env.OUTLINE_KB_MAINTENANCE_MODE !== "1") {
+    throw new OutlineKbError("MAINTENANCE_MODE_REQUIRED", "validate-maintenance-plan is only available to a system-owned knowledge maintenance session");
+  }
+  if (env.OUTLINE_KB_MAINTENANCE_MODE === "1" && !MAINTENANCE_ALLOWED_COMMANDS.has(command)) {
+    throw new OutlineKbError("MAINTENANCE_COMMAND_DISABLED", `outline-kb ${command ?? "<missing>"} is disabled for a knowledge maintenance Candidate session`);
+  }
+  let planInput = null;
+  if (command === "validate-plan" || command === "validate-maintenance-plan" || command === "apply") {
+    const loaded = await readPlanFile(need(positional[0], `${command} requires a JSON plan file`));
+    const systemManagedMetadata = command === "validate-maintenance-plan" || (command === "validate-plan"
+      && env.OUTLINE_KB_INGEST_MODE === "1"
+      && env.OASIS_KNOWLEDGE_SYSTEM_METADATA === "1");
+    planInput = {
+      ...loaded,
+      preflight: await preflightPlanFiles(loaded.plan, loaded.path, {
+        validateMetadata: !systemManagedMetadata,
+        ...(command === "validate-maintenance-plan" ? { allowedOperationTypes: new Set(["create", "update"]) } : {}),
+      }),
+    };
+  }
+  if (command === "validate-maintenance-plan") {
+    return { ok: true, ...planInput.preflight };
+  }
+  const client = new OutlineApiClient({ baseUrl: need(env.OUTLINE_BASE_URL, "OUTLINE_BASE_URL is required"), apiToken: need(env.OUTLINE_API_TOKEN, "OUTLINE_API_TOKEN is required") });
+  if (command === "status") {
+    const info = await client.authInfo();
+    const user = info?.data?.user ?? info?.data ?? {};
+    return { ok: true, identity: user.name ?? user.email ?? user.id ?? "outline-api", baseUrl: client.baseUrl };
+  }
+  const collectionId = flags.get("collection") ?? env.OUTLINE_COLLECTION_ID;
+  const rootDocumentId = flags.get("root") ?? env.OUTLINE_ROOT_DOCUMENT_ID ?? null;
+  const wiki = new OutlineWiki(client, { collectionId: need(collectionId, "--collection is required"), rootDocumentId });
+  if (command === "init") return { ok: true, results: (await wiki.init()).map((item) => ({ ...item, document: publicDocument(item.document) })) };
+  if (command === "tree") return { ok: true, documents: (await wiki.tree(positional[0] ?? null)).map(publicDocument) };
+  if (command === "search") return { ok: true, documents: (await wiki.search(need(positional[0], "search requires a query"), flags.get("under") ?? null, positiveLimit(flags.get("limit"), 10))).map(publicDocument) };
+  if (command === "read") return { ok: true, document: publicDocument(await wiki.read(need(positional[0], "read requires a path or document id"))) };
+  if (command === "read-many") {
+    if (positional.length === 0) throw new OutlineKbError("USAGE", "read-many requires one or more paths or document ids");
+    return { ok: true, documents: (await wiki.readMany(positional)).map(publicDocument) };
+  }
+  if (command === "search-and-read") return { ok: true, documents: (await wiki.searchAndRead(need(positional[0], "search-and-read requires a query"), { under: flags.get("under") ?? null, limit: positiveLimit(flags.get("limit"), 8) })).map(publicDocument) };
+  if (command === "create") {
+    const result = await wiki.create(need(positional[0], "create requires a path"), await readFile(need(flags.get("file"), "create requires --file"), "utf8"));
+    return { ok: true, ...result, document: publicDocument(result.document) };
+  }
+  if (command === "update") {
+    const result = await wiki.update(need(positional[0], "update requires a path"), await readFile(need(flags.get("file"), "update requires --file"), "utf8"), flags.get("expected-updated-at"));
+    return { ok: true, ...result, document: publicDocument(result.document) };
+  }
+  if (command === "append") {
+    const path = need(positional[0], "append requires log");
+    if (path !== "log") throw new OutlineKbError("USAGE", "append only supports log");
+    const result = await wiki.appendLog(await readFile(need(flags.get("file"), "append requires --file"), "utf8"), need(flags.get("job-id"), "append requires --job-id"));
+    return { ok: true, ...result, document: publicDocument(result.document) };
+  }
+  if (command === "import-file") {
+    const result = await wiki.importFile(need(positional[0], "import-file requires a file"), need(flags.get("path"), "import-file requires --path"), { textFile: flags.get("text-file") ?? null, contentType: flags.get("content-type") ?? null });
+    return { ok: true, ...result, document: publicDocument(result.document) };
+  }
+  if (command === "import-url") {
+    const result = await wiki.importUrl(need(positional[0], "import-url requires a URL"), need(flags.get("path"), "import-url requires --path"));
+    return { ok: true, ...result, document: publicDocument(result.document) };
+  }
+  if (command === "import-wechat") {
+    const result = await wiki.importWeChatUrl(need(positional[0], "import-wechat requires a WeChat article URL"), need(flags.get("path"), "import-wechat requires --path"));
+    return { ok: true, ...result, document: publicDocument(result.document) };
+  }
+  if (command === "validate-plan" || command === "apply") {
+    const { path: file, plan, preflight } = planInput;
+    const result = command === "apply" ? await wiki.applyPlan(plan, file, preflight) : await wiki.validatePlan(plan, file, null, preflight);
+    return { ok: command === "apply" ? result.lint.ok : true, ...result };
+  }
+  if (command === "lint") return await wiki.lint();
+  throw new OutlineKbError("USAGE", USAGE);
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  try {
+    const result = await run(argv);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    if (result?.ok === false) process.exitCode = 2;
+  } catch (error) {
+    const known = error instanceof OutlineKbError;
+    process.stderr.write(`${JSON.stringify({ ok: false, error: { code: known ? error.code : "INTERNAL", message: known ? error.message : "outline-kb failed", ...(known && error.details ? { details: error.details } : {}) } })}\n`);
+    process.exitCode = 1;
+  }
+}
+
+const invoked = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : "";
+if (import.meta.url === invoked) await main();
+
+export { htmlToMarkdown, linkRefs, normalizePath, run };