@thinkingai/ae-cli 6.0.52 → 6.0.54

package/dist/{te-kb-3TS73NO6.js → te-kb-MHDOST62.js}

@@ -2,23 +2,23 @@ import { createRequire as __createRequire } from 'node:module'; const require =
 import {
   kbApi,
   kbUpload
-} from "./chunk-57RRFUEZ.js";
+} from "./chunk-FMNNGNYO.js";
 import {
   TeAgentApiError
-} from "./chunk-HBGADCKA.js";
+} from "./chunk-PLE722AJ.js";
 import {
   CapabilityGatewayError
-} from "./chunk-HFGZGYCG.js";
+} from "./chunk-EOYSKMXN.js";
 import {
   printError
-} from "./chunk-DX5CDO34.js";
+} from "./chunk-KFNMQTZI.js";
 import "./chunk-Y74WTIKJ.js";
-import "./chunk-7XGFSUOM.js";
-import "./chunk-7FTTULED.js";
+import "./chunk-GIK6EDUG.js";
+import "./chunk-UQ77JXYH.js";
 import {
   CliValidationError,
   PermissionError
-} from "./chunk-MAPZ7VB6.js";
+} from "./chunk-WNGFSIOB.js";
 
 // src/commands/te-kb/target-scope.ts
 function getExternalKnowledgeBaseTargetScope(ctx) {
@@ -30,12 +30,164 @@ function getExternalKnowledgeBaseTargetScope(ctx) {
   );
 }
 
-// src/commands/te-kb/source-check-updates.ts
-var API_PATH = "/agent/api/external/knowledge-bases/sources/check-updates";
+// src/commands/te-kb/source-check-url-updates.ts
+var API_PATH = "/agent/api/external/knowledge-bases/sources/check-url-updates";
 function body(ctx) {
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
   return { name: ctx.str("name").trim(), sourceId: ctx.str("id").trim(), ...scope ? { scope } : {} };
 }
+var sourceCheckUrlUpdates = {
+  service: "kb",
+  resource: "source",
+  command: "check-url-updates",
+  risk: "write",
+  description: "Submit an asynchronous update check for one compiled custom URL source. Success means accepted only. Read kb +list-sources for update markers; an unchanged state does not prove completion. Does not compile.",
+  flags: [
+    { name: "name", type: "string", required: true, minLength: 1, maxLength: 200, desc: "Knowledge base name" },
+    { name: "id", type: "string", required: true, minLength: 1, maxLength: 191, desc: "Stable custom URL source ID from kb +list-sources" },
+    { name: "scope", type: "string", desc: "Exact scope: personal | company (omit for personal then company lookup)" }
+  ],
+  validate: (ctx) => {
+    for (const [flag2, max] of [["name", 200], ["id", 191]]) {
+      const value = ctx.str(flag2).trim();
+      if (!value || value.length > max) throw new CliValidationError(`Invalid --${flag2}: expected 1-${max} characters.`);
+    }
+    getExternalKnowledgeBaseTargetScope(ctx);
+  },
+  dryRun: (ctx) => ({ method: "POST", url: `${ctx.host().replace(/\/$/, "")}${API_PATH}`, body: body(ctx) }),
+  execute: (ctx) => kbApi(ctx, "POST", API_PATH, {}, body(ctx), { preserveErrorMetadata: true })
+};
+
+// src/commands/te-kb/schema-import.ts
+import { promises as fs } from "fs";
+import path from "path";
+var ROOT = "/agent/api/external/knowledge-bases/schema";
+var options = { preserveBusinessErrorCode: true, preserveErrorMetadata: true };
+var flag = (name, type, desc, required = false) => ({ name, type, desc, required });
+var targetFlags = [flag("name", "string", "Knowledge base name", true), flag("scope", "string", "Exact scope: personal | company")];
+var identityFlags = [flag("import-id", "string", "Stable import ID", true)];
+var mutationFlags = [flag("revision", "number", "Expected candidate revision", true), flag("request-id", "string", "Idempotency key; reuse only for identical retries", true)];
+var hashFlag = flag("hash", "string", "Expected candidate SHA256", true);
+var fileFlag = { ...flag("file", "string", "Local UTF-8 Markdown file, at most 256 KiB", true), sensitive: true };
+var waitFlags = [flag("wait", "boolean", "Poll until this task finishes; never abandon on timeout"), { ...flag("timeout", "number", "Wait timeout in seconds"), default: 300, min: 1, max: 3600 }];
+var modelFlag = flag("model", "string", "Optional stable model reference");
+function target(ctx) {
+  return { name: ctx.str("name"), scope: getExternalKnowledgeBaseTargetScope(ctx) };
+}
+function endpoint(ctx, action) {
+  if (action === "download") return ROOT;
+  if (action === "upload" || action === "list") return ROOT + "/imports";
+  const suffix = action === "status" ? "" : action === "save" ? "content" : action === "reject" ? "reject-optimization" : action;
+  return `${ROOT}/imports/${encodeURIComponent(ctx.str("import-id"))}${suffix ? "/" + suffix : ""}`;
+}
+function body2(ctx, action) {
+  const result = { expectedRevision: ctx.num("revision"), requestId: ctx.str("request-id") };
+  if (["validate", "optimize", "apply"].includes(action)) result.contentHash = ctx.str("hash");
+  if (["validate", "optimize"].includes(action) && ctx.str("model")) result.model = ctx.str("model");
+  if (action === "optimize" && ctx.list("issue-id").length) result.issueIds = ctx.list("issue-id");
+  if (action === "apply") {
+    if (ctx.str("report-id")) result.reportId = ctx.str("report-id");
+    result.expectedSchemaHash = ctx.bool("schema-absent") ? null : ctx.str("schema-hash");
+  }
+  return result;
+}
+function query(ctx, action) {
+  if (action === "download") return { ...target(ctx), download: "1" };
+  if (action === "list") return { ...target(ctx), limit: ctx.num("limit") || 20, cursor: ctx.str("cursor") || void 0 };
+  if (action === "content") return { target: ctx.str("target") || "current", download: ctx.str("output") ? "1" : void 0 };
+  if (action === "diff") return { baseline: ctx.str("baseline") || "current-schema" };
+  return {};
+}
+function validate(ctx, action) {
+  if (["upload", "list", "download"].includes(action)) getExternalKnowledgeBaseTargetScope(ctx);
+  for (const name of ["import-id", "request-id", "replaces-import-id"]) if (ctx.str(name) && !/^[A-Za-z0-9_-]{1,191}$/.test(ctx.str(name))) throw new CliValidationError(`Invalid --${name}`);
+  for (const name of ["hash", "schema-hash", "report-id"]) if (ctx.str(name) && !/^[a-f0-9]{64}$/.test(ctx.str(name))) throw new CliValidationError(`Invalid --${name}; expected SHA256`);
+  for (const name of ["revision", "replaced-revision"]) if (ctx.num(name) && (!Number.isInteger(ctx.num(name)) || ctx.num(name) < 1)) throw new CliValidationError(`Invalid --${name}`);
+  if (action === "apply" && Boolean(ctx.str("schema-hash")) === ctx.bool("schema-absent")) throw new CliValidationError("Specify exactly one of --schema-hash or --schema-absent");
+  if (action === "upload" && Boolean(ctx.str("replaces-import-id")) !== Boolean(ctx.num("replaced-revision"))) throw new CliValidationError("Replacement requires --replaces-import-id and --replaced-revision");
+  if (action === "content" && !["current", "original", "optimization-input", "optimized"].includes(ctx.str("target") || "current")) throw new CliValidationError("Invalid --target");
+  if (action === "diff" && !["original", "optimization-input", "current-schema"].includes(ctx.str("baseline") || "current-schema")) throw new CliValidationError("Invalid --baseline");
+}
+async function readMarkdown(ctx) {
+  const absolute = path.resolve(ctx.str("file")), stat = await fs.stat(absolute);
+  if (!stat.isFile() || stat.size > 262144 || path.extname(absolute).toLowerCase() !== ".md") throw new CliValidationError("--file must be a Markdown file of at most 256 KiB");
+  const bytes = await fs.readFile(absolute);
+  if (bytes.length > 262144) throw new CliValidationError("--file exceeds 256 KiB");
+  new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+  return { absolute, bytes };
+}
+async function waitSchemaImport(ctx, initial, api = kbApi, sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms))) {
+  const deadline = Date.now() + (ctx.num("timeout") || 300) * 1e3;
+  let current = initial;
+  while (current.task && Date.now() < deadline) {
+    await sleep(Math.min(2e3, Math.max(1, deadline - Date.now())));
+    current = await api(ctx, "GET", `${ROOT}/imports/${encodeURIComponent(initial.id)}`, {}, void 0, options);
+  }
+  return { ...current, waitTimedOut: Boolean(current.task) };
+}
+async function executeSchemaImport(ctx, action, api = kbApi, upload = kbUpload) {
+  let result;
+  if (action === "upload") {
+    const { absolute, bytes } = await readMarkdown(ctx);
+    const form = new FormData();
+    form.set("file", new Blob([new Uint8Array(bytes)]), path.basename(absolute));
+    form.set("name", ctx.str("name"));
+    form.set("requestId", ctx.str("request-id"));
+    const scope = getExternalKnowledgeBaseTargetScope(ctx);
+    if (scope) form.set("scope", scope);
+    if (ctx.str("model")) form.set("model", ctx.str("model"));
+    if (ctx.str("replaces-import-id")) {
+      form.set("replacesImportId", ctx.str("replaces-import-id"));
+      form.set("expectedReplacedRevision", String(ctx.num("replaced-revision")));
+    }
+    result = await upload(ctx, endpoint(ctx, action), form, {}, options);
+  } else if (["download", "list", "status", "content", "diff"].includes(action)) {
+    const binary = action === "download" || action === "content" && Boolean(ctx.str("output"));
+    result = await api(ctx, "GET", endpoint(ctx, action), query(ctx, action), void 0, { ...options, ...binary ? { responseType: "bytes" } : {} });
+    if (binary) {
+      const output = path.resolve(ctx.str("output"));
+      const bytes = Buffer.from(result.bytes);
+      await fs.writeFile(output, bytes, { flag: "wx" });
+      return { output, sizeBytes: bytes.length };
+    }
+    if (action === "diff" && ctx.str("output")) {
+      const output = path.resolve(ctx.str("output"));
+      await fs.writeFile(output, result.diff, { flag: "wx" });
+      return { ...result, output };
+    }
+  } else {
+    const input = body2(ctx, action);
+    if (action === "save") {
+      const { bytes } = await readMarkdown(ctx);
+      input.content = bytes.toString("utf8");
+    }
+    result = await api(ctx, action === "save" ? "PUT" : "POST", endpoint(ctx, action), {}, input, options);
+  }
+  return ctx.bool("wait") && result.task ? waitSchemaImport(ctx, result, api) : result;
+}
+function command(action, name, description, flags, risk) {
+  return { service: "kb", command: name, description, flags, risk, validate: (ctx) => validate(ctx, action), dryRun: (ctx) => ({ method: action === "save" ? "PUT" : ["upload", "validate", "optimize", "reject", "apply", "abandon"].includes(action) ? "POST" : "GET", url: ctx.host().replace(/\/$/, "") + endpoint(ctx, action), params: query(ctx, action), body: action === "upload" ? { ...target(ctx), requestId: ctx.str("request-id"), file: "[REDACTED]", model: ctx.str("model") || void 0, replacesImportId: ctx.str("replaces-import-id") || void 0, expectedReplacedRevision: ctx.num("replaced-revision") || void 0 } : ["save", "validate", "optimize", "reject", "apply", "abandon"].includes(action) ? { ...body2(ctx, action), ...action === "save" ? { content: "[REDACTED]" } : {} } : void 0 }), execute: (ctx) => executeSchemaImport(ctx, action) };
+}
+var schemaDownload = command("download", "+schema-download", "Download formal schema bytes without rewriting.", [...targetFlags, flag("output", "string", "New destination file; never overwrite", true)], "read");
+var schemaImport = command("upload", "+schema-import", "Upload a candidate with basic checks; AI validation is explicit and formal schema is unchanged.", [...targetFlags, fileFlag, flag("request-id", "string", "Upload idempotency key", true), modelFlag, flag("replaces-import-id", "string", "Explicit pending import to replace"), flag("replaced-revision", "number", "Expected revision of replaced import"), ...waitFlags], "write");
+var schemaImportList = command("list", "+schema-import-list", "List your pending candidates.", [...targetFlags, { ...flag("limit", "number", "Page size, 1 to 100"), default: 20, min: 1, max: 100 }, flag("cursor", "string", "Continuation cursor")], "read");
+var schemaImportStatus = command("status", "+schema-import-status", "Read candidate status, report and durable receipt.", [...identityFlags, ...waitFlags], "read");
+var schemaImportContent = command("content", "+schema-import-content", "Read or download unmodified candidate bytes.", [...identityFlags, flag("target", "string", "current | original | optimization-input | optimized"), flag("output", "string", "Optional new destination file")], "read");
+var schemaImportDiff = command("diff", "+schema-import-diff", "Read full actual diff and current formal hash.", [...identityFlags, flag("baseline", "string", "original | optimization-input | current-schema"), flag("output", "string", "Optional new diff file")], "read");
+var schemaImportSave = command("save", "+schema-import-save", "Save edits without calling a model.", [...identityFlags, ...mutationFlags, fileFlag], "write");
+var schemaImportValidate = command("validate", "+schema-import-validate", "Validate this exact saved revision.", [...identityFlags, ...mutationFlags, hashFlag, modelFlag, ...waitFlags], "write");
+var schemaImportOptimize = command("optimize", "+schema-import-optimize", "Repair selected issues once and independently revalidate.", [...identityFlags, ...mutationFlags, hashFlag, modelFlag, { ...flag("issue-id", "string", "Repeat to select repairable issues"), variadic: true }, ...waitFlags], "write");
+var schemaImportReject = command("reject", "+schema-import-reject", "Restore the most recent repair input.", [...identityFlags, ...mutationFlags], "write");
+var schemaImportApply = command("apply", "+schema-import-apply", "Apply after reviewing full diff; BASE_CHANGED requires a new review.", [...identityFlags, ...mutationFlags, hashFlag, flag("report-id", "string", "Optional AI report ID; retained for compatibility"), flag("schema-hash", "string", "Formal hash from a recent diff"), flag("schema-absent", "boolean", "Explicitly confirm formal schema is absent")], "write");
+var schemaImportAbandon = command("abandon", "+schema-import-abandon", "Abandon candidate and invalidate pending tasks.", [...identityFlags, ...mutationFlags], "high-risk-write");
+var schemaImportCommands = [schemaDownload, schemaImport, schemaImportList, schemaImportStatus, schemaImportContent, schemaImportDiff, schemaImportSave, schemaImportValidate, schemaImportOptimize, schemaImportReject, schemaImportApply, schemaImportAbandon];
+
+// src/commands/te-kb/source-check-updates.ts
+var API_PATH2 = "/agent/api/external/knowledge-bases/sources/check-updates";
+function body3(ctx) {
+  const scope = getExternalKnowledgeBaseTargetScope(ctx);
+  return { name: ctx.str("name").trim(), sourceId: ctx.str("id").trim(), ...scope ? { scope } : {} };
+}
 var sourceCheckUpdates = {
   service: "kb",
   resource: "source",
@@ -48,16 +200,16 @@ var sourceCheckUpdates = {
     { name: "scope", type: "string", desc: "Exact scope: personal | company (omit for personal then company lookup)" }
   ],
   validate: (ctx) => {
-    for (const [flag, max] of [["name", 200], ["id", 191]]) {
-      const value = ctx.str(flag).trim();
-      if (!value || value.length > max) throw new CliValidationError(`Invalid --${flag}: expected 1-${max} characters.`);
+    for (const [flag2, max] of [["name", 200], ["id", 191]]) {
+      const value = ctx.str(flag2).trim();
+      if (!value || value.length > max) throw new CliValidationError(`Invalid --${flag2}: expected 1-${max} characters.`);
     }
     getExternalKnowledgeBaseTargetScope(ctx);
   },
-  dryRun: (ctx) => ({ method: "POST", url: `${ctx.host().replace(/\/$/, "")}${API_PATH}`, body: body(ctx) }),
+  dryRun: (ctx) => ({ method: "POST", url: `${ctx.host().replace(/\/$/, "")}${API_PATH2}`, body: body3(ctx) }),
   execute: async (ctx) => {
     try {
-      return await kbApi(ctx, "POST", API_PATH, {}, body(ctx), { preserveErrorMetadata: true });
+      return await kbApi(ctx, "POST", API_PATH2, {}, body3(ctx), { preserveErrorMetadata: true });
     } catch (error) {
       const hint = "Read kb +list-sources to confirm the current source state before retrying.";
       if (error instanceof PermissionError) {
@@ -84,14 +236,185 @@ var sourceCheckUpdates = {
   }
 };
 
-// src/commands/te-kb/source-mutation.ts
-import { promises as fs } from "fs";
-import path from "path";
+// src/commands/te-kb/source-text.ts
+import { promises as fs2 } from "fs";
+import path2 from "path";
 var API = "/agent/api/external/knowledge-bases";
-var apiOptions = { preserveErrorMetadata: true };
+var textApiOptions = { preserveErrorMetadata: true, retryUnauthorized: false, redactErrorDetails: true };
 var maxBytes = 50 * 1024 * 1024;
+var targetFlags2 = [
+  { name: "name", type: "string", required: true, desc: "Exact knowledge base name from kb +list" },
+  { name: "scope", type: "string", required: true, desc: "Exact knowledge base scope: personal or company" }
+];
+var textInputFlags = [
+  { name: "text", type: "string", sensitive: true, desc: "Complete text body; mutually exclusive with --file and --stdin" },
+  { name: "file", type: "string", desc: "One UTF-8 .md, .markdown or .txt file, at most 50 MiB; creates a Markdown source" },
+  { name: "stdin", type: "boolean", desc: "Explicitly read the complete UTF-8 body from stdin; mutually exclusive with --text and --file" }
+];
+function hasTextFlag(ctx) {
+  return ctx.has ? ctx.has("text") : Boolean(ctx.str("text"));
+}
+function validateTextInput(ctx) {
+  const hasFile = ctx.has ? ctx.has("file") : Boolean(ctx.str("file"));
+  const count = Number(hasTextFlag(ctx)) + Number(hasFile) + Number(ctx.bool("stdin"));
+  if (count !== 1) throw new CliValidationError("Provide exactly one of --text, --file or --stdin.");
+  if (hasFile && !ctx.str("file").trim()) throw new CliValidationError("--file must name a regular file.");
+}
+function validateTarget(ctx) {
+  const name = ctx.str("name");
+  if (!name.trim() || name.length > 200 || /[\x00-\x1f\x7f]/.test(name)) {
+    throw new CliValidationError("--name must contain 1 to 200 characters without control characters.");
+  }
+  if (!["personal", "company"].includes(ctx.str("scope"))) throw new CliValidationError("--scope must be personal or company.");
+}
+function tooLarge() {
+  return new CliValidationError("Text content exceeds 50 MiB (52428800 UTF-8 bytes).", { code: "SOURCE_FILE_TOO_LARGE" });
+}
+async function boundedBytes(stream) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of stream) {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += bytes.length;
+    if (size > maxBytes) throw tooLarge();
+    chunks.push(bytes);
+  }
+  return Buffer.concat(chunks, size);
+}
+async function readTextInput(ctx) {
+  validateTextInput(ctx);
+  let content;
+  if (hasTextFlag(ctx)) {
+    content = ctx.str("text");
+    if (/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(content)) {
+      throw new CliValidationError("Text content must contain valid Unicode.", { code: "SOURCE_TEXT_ENCODING_UNSUPPORTED" });
+    }
+  } else {
+    let bytes;
+    if (ctx.bool("stdin")) {
+      if (process.stdin.isTTY) throw new CliValidationError("--stdin requires piped UTF-8 input; interactive input is not supported.");
+      bytes = await boundedBytes(process.stdin);
+    } else {
+      const filename = path2.resolve(ctx.str("file"));
+      if (![".md", ".markdown", ".txt"].includes(path2.extname(filename).toLowerCase())) {
+        throw new CliValidationError("--file must be a UTF-8 .md, .markdown or .txt file.");
+      }
+      const handle = await fs2.open(filename, "r");
+      try {
+        const stat = await handle.stat();
+        if (!stat.isFile()) throw new CliValidationError("--file must be a regular file.");
+        if (stat.size > maxBytes) throw tooLarge();
+        bytes = await boundedBytes(handle.createReadStream({ autoClose: false }));
+      } finally {
+        await handle.close();
+      }
+    }
+    try {
+      content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    } catch {
+      throw new CliValidationError("Text input must be valid UTF-8; no encoding conversion is performed.", { code: "SOURCE_TEXT_ENCODING_UNSUPPORTED" });
+    }
+  }
+  const sizeBytes = Buffer.byteLength(content, "utf8");
+  if (sizeBytes > maxBytes) throw tooLarge();
+  if (!content.trim()) throw new CliValidationError("Text content must not be empty or whitespace-only.", { code: "SOURCE_TEXT_EMPTY" });
+  return { content, sizeBytes };
+}
+function target2(ctx) {
+  return { name: ctx.str("name").trim(), scope: ctx.str("scope") };
+}
+var sourceCreateText = {
+  service: "kb",
+  resource: "source",
+  command: "create-text",
+  risk: "write",
+  description: "Create one ordinary Markdown source from text, a UTF-8 file or stdin. Saves only; does not compile or publish.",
+  flags: [
+    ...targetFlags2,
+    { name: "title", type: "string", desc: "Optional display title (1-200 Unicode characters); the server derives it from content when omitted" },
+    ...textInputFlags
+  ],
+  validate: (ctx) => {
+    validateTarget(ctx);
+    validateTextInput(ctx);
+    if (ctx.has?.("title") || ctx.str("title")) {
+      const title = ctx.str("title").trim();
+      if (!title || [...title].length > 200 || /[\p{Cc}/\\]/u.test(title) || [".", ".."].includes(title)) {
+        throw new CliValidationError("--title must contain 1 to 200 Unicode characters without control characters or path separators.");
+      }
+    }
+  },
+  dryRun: async (ctx) => {
+    const { sizeBytes } = await readTextInput(ctx);
+    return {
+      method: "POST",
+      url: `${ctx.host().replace(/\/$/, "")}${API}/sources/text`,
+      body: { ...target2(ctx), ...ctx.str("title") ? { title: ctx.str("title").trim() } : {}, inputMethod: "text_input", content: "<redacted>" },
+      sizeBytes
+    };
+  },
+  execute: async (ctx) => kbApi(ctx, "POST", `${API}/sources/text`, {}, {
+    ...target2(ctx),
+    ...ctx.str("title") ? { title: ctx.str("title").trim() } : {},
+    content: (await readTextInput(ctx)).content,
+    inputMethod: "text_input"
+  }, textApiOptions)
+};
+async function outputPath(ctx) {
+  if (!ctx.str("out")) return void 0;
+  const output = path2.resolve(ctx.str("out"));
+  try {
+    await fs2.lstat(output);
+  } catch (error) {
+    if (error.code === "ENOENT") return output;
+    throw error;
+  }
+  throw new CliValidationError("--out must name a new file; existing files are never overwritten.");
+}
+var sourceReadText = {
+  service: "kb",
+  resource: "source",
+  command: "read-text",
+  risk: "read",
+  sensitiveOutput: true,
+  description: "Read complete ordinary UTF-8 text with its matching revision and format. Optionally save original bytes to a new local file.",
+  flags: [
+    ...targetFlags2,
+    { name: "id", type: "string", required: true, desc: "Current stable source ID from kb +list-sources" },
+    { name: "out", type: "string", desc: "Write the complete original UTF-8 bytes to a new file; output metadata only and never overwrite" }
+  ],
+  validate: (ctx) => {
+    validateTarget(ctx);
+    const id = ctx.str("id");
+    if (!id.trim() || id.length > 191 || /[\x00-\x1f\x7f]/.test(id)) throw new CliValidationError("--id must contain 1 to 191 characters without control characters.");
+    if (ctx.has?.("out") && !ctx.str("out").trim()) throw new CliValidationError("--out must name a new file.");
+  },
+  dryRun: async (ctx) => ({
+    method: "GET",
+    url: `${ctx.host().replace(/\/$/, "")}${API}/sources/${encodeURIComponent(ctx.str("id").trim())}/text`,
+    params: target2(ctx),
+    ...ctx.str("out") ? { out: await outputPath(ctx) } : {}
+  }),
+  execute: async (ctx) => {
+    const output = await outputPath(ctx);
+    const result = await kbApi(ctx, "GET", `${API}/sources/${encodeURIComponent(ctx.str("id").trim())}/text`, target2(ctx), void 0, textApiOptions);
+    if (!result || typeof result.content !== "string" || !["markdown", "text"].includes(result.contentFormat) || !Number.isSafeInteger(result.item?.contentRevision) || result.item.contentRevision < 1) {
+      throw new Error("KB text protocol error: expected complete content, format and a positive contentRevision.");
+    }
+    if (!output) return result;
+    await fs2.writeFile(output, result.content, { encoding: "utf8", flag: "wx" });
+    return { item: result.item, contentFormat: result.contentFormat, out: output };
+  }
+};
+
+// src/commands/te-kb/source-mutation.ts
+import { promises as fs3 } from "fs";
+import path3 from "path";
+var API2 = "/agent/api/external/knowledge-bases";
+var apiOptions = { preserveErrorMetadata: true };
+var maxBytes2 = 50 * 1024 * 1024;
 var fileExtensions = /* @__PURE__ */ new Set([".md", ".markdown", ".txt", ".csv", ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".svg"]);
-var identityFlags = [
+var identityFlags2 = [
   { name: "name", type: "string", required: true, desc: "Exact knowledge base name from kb +list" },
   { name: "scope", type: "string", required: true, desc: "Exact knowledge base scope: personal or company" },
   { name: "id", type: "string", required: true, desc: "Current stable source ID from kb +list-sources" }
@@ -100,48 +423,48 @@ var typeFlag = { name: "source-type", type: "string", required: true, desc: "Cur
 var revisionFlag = { name: "expected-revision", type: "number", required: true, min: 1, max: 2147483647, desc: "Current contentRevision from kb +list-sources; never automatically retry a conflict" };
 var previewFlag = { name: "preview-id", type: "string", required: true, desc: "Exact previewId returned by ZIP replace or restore" };
 function validateIdentity(ctx) {
-  for (const [flag, max] of [["name", 200], ["id", 191], ["preview-id", 191]]) {
-    const value = ctx.str(flag);
-    if ((flag !== "preview-id" || value) && (!value.trim() || value.length > max || /[\x00-\x1f\x7f]/.test(value))) {
-      throw new CliValidationError(`--${flag} must contain 1 to ${max} characters without control characters.`);
+  for (const [flag2, max] of [["name", 200], ["id", 191], ["preview-id", 191]]) {
+    const value = ctx.str(flag2);
+    if ((flag2 !== "preview-id" || value) && (!value.trim() || value.length > max || /[\x00-\x1f\x7f]/.test(value))) {
+      throw new CliValidationError(`--${flag2} must contain 1 to ${max} characters without control characters.`);
     }
   }
   if (!["personal", "company"].includes(ctx.str("scope"))) throw new CliValidationError("--scope must be personal or company.");
 }
-function positiveInteger(ctx, flag) {
-  const value = ctx.num(flag);
-  if (!Number.isSafeInteger(value) || value < 1 || value > 2147483647) throw new CliValidationError(`--${flag} must be an integer from 1 to 2147483647.`);
+function positiveInteger(ctx, flag2) {
+  const value = ctx.num(flag2);
+  if (!Number.isSafeInteger(value) || value < 1 || value > 2147483647) throw new CliValidationError(`--${flag2} must be an integer from 1 to 2147483647.`);
 }
 function validateMutation(ctx) {
   validateIdentity(ctx);
   positiveInteger(ctx, "expected-revision");
   if (!["file", "zip"].includes(ctx.str("source-type"))) throw new CliValidationError("--source-type must be file or zip; URL sources cannot be replaced or restored.");
 }
-function query(ctx) {
+function query2(ctx) {
   return { name: ctx.str("name").trim(), scope: ctx.str("scope") };
 }
 function sourceEndpoint(ctx, suffix) {
-  return `${API}/sources/${encodeURIComponent(ctx.str("id").trim())}/${suffix}`;
+  return `${API2}/sources/${encodeURIComponent(ctx.str("id").trim())}/${suffix}`;
 }
 function previewEndpoint(ctx) {
   return sourceEndpoint(ctx, `directory/previews/${encodeURIComponent(ctx.str("preview-id").trim())}`);
 }
-function dryRequest(ctx, method, endpoint2, body2) {
-  return { method, url: `${ctx.host().replace(/\/$/, "")}${endpoint2}`, params: query(ctx), ...body2 === void 0 ? {} : { body: body2 } };
+function dryRequest(ctx, method, endpoint3, body4) {
+  return { method, url: `${ctx.host().replace(/\/$/, "")}${endpoint3}`, params: query2(ctx), ...body4 === void 0 ? {} : { body: body4 } };
 }
 async function replacementFile(ctx, read) {
-  const file = path.resolve(ctx.str("file"));
-  const extension = path.extname(file).toLowerCase();
+  const file = path3.resolve(ctx.str("file"));
+  const extension = path3.extname(file).toLowerCase();
   if (ctx.str("source-type") === "zip" ? extension !== ".zip" : !fileExtensions.has(extension)) {
     throw new CliValidationError("--file must be a ZIP for a ZIP source, or a supported non-ZIP file for a file source. File sources must keep their original format.");
   }
-  const handle = await fs.open(file, "r");
+  const handle = await fs3.open(file, "r");
   try {
     const stat = await handle.stat();
-    if (!stat.isFile() || stat.size > maxBytes) throw new CliValidationError("--file must be a regular file of at most 50 MB.");
+    if (!stat.isFile() || stat.size > maxBytes2) throw new CliValidationError("--file must be a regular file of at most 50 MB.");
     const content = read ? await handle.readFile() : void 0;
-    if (content && content.length > maxBytes) throw new CliValidationError("--file exceeds 50 MB.");
-    return { file, filename: path.basename(file), sizeBytes: content?.length ?? stat.size, content };
+    if (content && content.length > maxBytes2) throw new CliValidationError("--file exceeds 50 MB.");
+    return { file, filename: path3.basename(file), sizeBytes: content?.length ?? stat.size, content };
   } finally {
     await handle.close();
   }
@@ -157,26 +480,40 @@ var sourceReplace = {
   resource: "source",
   command: "replace",
   risk: "write",
-  description: "Replace a file source draft, or prepare a ZIP archive replacement preview. ZIP changes require source commit. Does not compile or publish.",
-  flags: [...identityFlags, typeFlag, revisionFlag, { name: "file", type: "string", required: true, desc: "Local replacement file, at most 50 MB; same format, different filename allowed" }],
+  description: "Replace a file source draft from a file or complete text, or prepare a ZIP archive replacement preview. ZIP changes require source commit. Does not compile or publish.",
+  flags: [...identityFlags2, typeFlag, revisionFlag, ...textInputFlags.map((flag2) => flag2.name === "file" ? { ...flag2, desc: "Local replacement file, at most 50 MiB; same format, different filename allowed; mutually exclusive with --text and --stdin" } : flag2)],
   validate: (ctx) => {
     validateMutation(ctx);
-    if (!ctx.str("file").trim()) throw new CliValidationError("--file is required.");
+    validateTextInput(ctx);
+    if ((hasTextFlag(ctx) || ctx.bool("stdin")) && ctx.str("source-type") !== "file") {
+      throw new CliValidationError("--text and --stdin require --source-type file and an ordinary text source.");
+    }
   },
   dryRun: async (ctx) => {
+    if (hasTextFlag(ctx) || ctx.bool("stdin")) {
+      const { sizeBytes: sizeBytes2 } = await readTextInput(ctx);
+      return { ...dryRequest(ctx, "PUT", sourceEndpoint(ctx, "text"), { expectedRevision: ctx.num("expected-revision"), inputMethod: "text_input", content: "<redacted>" }), sizeBytes: sizeBytes2 };
+    }
     const { file, filename, sizeBytes } = await replacementFile(ctx, false);
     return { ...dryRequest(ctx, ctx.str("source-type") === "zip" ? "POST" : "PUT", replaceEndpoint(ctx), replaceFields(ctx)), multipart: { file, filename, sizeBytes, content: "<redacted>" } };
   },
   execute: async (ctx) => {
+    if (hasTextFlag(ctx) || ctx.bool("stdin")) {
+      return kbApi(ctx, "PUT", sourceEndpoint(ctx, "text"), query2(ctx), {
+        content: (await readTextInput(ctx)).content,
+        expectedRevision: ctx.num("expected-revision"),
+        inputMethod: "text_input"
+      }, textApiOptions);
+    }
     const file = await replacementFile(ctx, true);
     const form = new FormData();
     form.append("file", new Blob([new Uint8Array(file.content)]), file.filename);
     for (const [key, value] of Object.entries(replaceFields(ctx))) form.append(key, String(value));
-    return kbUpload(ctx, replaceEndpoint(ctx), form, query(ctx), { ...apiOptions, method: ctx.str("source-type") === "zip" ? "POST" : "PUT" });
+    return kbUpload(ctx, replaceEndpoint(ctx), form, query2(ctx), { ...apiOptions, method: ctx.str("source-type") === "zip" ? "POST" : "PUT" });
   }
 };
 function restoreEndpoint(ctx) {
-  return `${API}/versions/${ctx.num("version")}/sources/${encodeURIComponent(ctx.str("id").trim())}/restore`;
+  return `${API2}/versions/${ctx.num("version")}/sources/${encodeURIComponent(ctx.str("id").trim())}/restore`;
 }
 function restoreBody(ctx) {
   return { expectedRevision: ctx.num("expected-revision"), ...ctx.str("source-type") === "zip" ? ctx.str("path") ? { target: "file", path: ctx.str("path") } : { target: "source" } : {} };
@@ -188,7 +525,7 @@ var sourceRestore = {
   risk: "write",
   description: "Restore one current source draft from a published version. File sources restore immediately; ZIP source or child restores return a preview. Does not roll back the whole knowledge base or publish.",
   flags: [
-    ...identityFlags,
+    ...identityFlags2,
     typeFlag,
     revisionFlag,
     { name: "version", type: "number", required: true, min: 1, max: 2147483647, desc: "Published version number from kb +versions; use the latest number to discard unpublished changes" },
@@ -203,7 +540,7 @@ var sourceRestore = {
     }
   },
   dryRun: (ctx) => dryRequest(ctx, "POST", restoreEndpoint(ctx), restoreBody(ctx)),
-  execute: (ctx) => kbApi(ctx, "POST", restoreEndpoint(ctx), query(ctx), restoreBody(ctx), apiOptions)
+  execute: (ctx) => kbApi(ctx, "POST", restoreEndpoint(ctx), query2(ctx), restoreBody(ctx), apiOptions)
 };
 var sourcePreview = {
   service: "kb",
@@ -212,7 +549,7 @@ var sourcePreview = {
   risk: "read",
   description: "Read one page of a ZIP replacement or restore preview, including additions, modifications and deletions.",
   flags: [
-    ...identityFlags,
+    ...identityFlags2,
     previewFlag,
     { name: "cursor", type: "string", desc: "Opaque nextCursor returned by the previous preview page" },
     { name: "limit", type: "number", default: 100, min: 1, max: 200, desc: "Preview page size from 1 to 200" }
@@ -222,8 +559,8 @@ var sourcePreview = {
     if (!Number.isInteger(ctx.num("limit")) || ctx.num("limit") < 1 || ctx.num("limit") > 200) throw new CliValidationError("--limit must be an integer from 1 to 200.");
     if (ctx.str("cursor").length > 4096) throw new CliValidationError("--cursor must be at most 4096 characters.");
   },
-  dryRun: (ctx) => ({ ...dryRequest(ctx, "GET", previewEndpoint(ctx)), params: { ...query(ctx), limit: ctx.num("limit"), ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {} } }),
-  execute: (ctx) => kbApi(ctx, "GET", previewEndpoint(ctx), { ...query(ctx), limit: ctx.num("limit"), ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {} }, void 0, apiOptions)
+  dryRun: (ctx) => ({ ...dryRequest(ctx, "GET", previewEndpoint(ctx)), params: { ...query2(ctx), limit: ctx.num("limit"), ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {} } }),
+  execute: (ctx) => kbApi(ctx, "GET", previewEndpoint(ctx), { ...query2(ctx), limit: ctx.num("limit"), ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {} }, void 0, apiOptions)
 };
 var sourceCommit = {
   service: "kb",
@@ -231,13 +568,13 @@ var sourceCommit = {
   command: "commit",
   risk: "high-risk-write",
   description: "Confirm a reviewed ZIP replacement or restore preview. May delete missing files; changes only the draft. On uncertain outcome, inspect state before any retry.",
-  flags: [...identityFlags, previewFlag, revisionFlag],
+  flags: [...identityFlags2, previewFlag, revisionFlag],
   validate: (ctx) => {
     validateIdentity(ctx);
     positiveInteger(ctx, "expected-revision");
   },
   dryRun: (ctx) => dryRequest(ctx, "POST", `${previewEndpoint(ctx)}/commit`, { expectedRevision: ctx.num("expected-revision"), confirmed: true }),
-  execute: (ctx) => kbApi(ctx, "POST", `${previewEndpoint(ctx)}/commit`, query(ctx), { expectedRevision: ctx.num("expected-revision"), confirmed: true }, apiOptions)
+  execute: (ctx) => kbApi(ctx, "POST", `${previewEndpoint(ctx)}/commit`, query2(ctx), { expectedRevision: ctx.num("expected-revision"), confirmed: true }, apiOptions)
 };
 var sourceCancel = {
   service: "kb",
@@ -245,20 +582,20 @@ var sourceCancel = {
   command: "cancel",
   risk: "high-risk-write",
   description: "Discard an uncommitted ZIP replacement or restore preview; leaves the source draft unchanged.",
-  flags: [...identityFlags, previewFlag],
+  flags: [...identityFlags2, previewFlag],
   validate: validateIdentity,
   dryRun: (ctx) => dryRequest(ctx, "DELETE", previewEndpoint(ctx)),
   execute: async (ctx) => {
-    await kbApi(ctx, "DELETE", previewEndpoint(ctx), query(ctx), void 0, { ...apiOptions, responseType: "empty" });
+    await kbApi(ctx, "DELETE", previewEndpoint(ctx), query2(ctx), void 0, { ...apiOptions, responseType: "empty" });
     return { previewId: ctx.str("preview-id"), cancelled: true };
   }
 };
 
 // src/commands/te-kb/add.ts
-import { promises as fs2 } from "fs";
-import * as path2 from "path";
+import { promises as fs4 } from "fs";
+import * as path4 from "path";
 import TurndownService from "turndown";
-var API_PATH2 = "/agent/api/external/knowledge-bases/sources/upload";
+var API_PATH3 = "/agent/api/external/knowledge-bases/sources/upload";
 var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([
   ".zip",
   ".md",
@@ -305,7 +642,7 @@ function sanitizeFilename(name) {
   return cleaned || "document";
 }
 function getMimeType(filename) {
-  const ext = path2.extname(filename).toLowerCase();
+  const ext = path4.extname(filename).toLowerCase();
   switch (ext) {
     case ".zip":
       return "application/zip";
@@ -348,23 +685,23 @@ function getMimeType(filename) {
   }
 }
 async function readLocalFile(filePath) {
-  const ext = path2.extname(filePath).toLowerCase();
+  const ext = path4.extname(filePath).toLowerCase();
   if (!SUPPORTED_EXTENSIONS.has(ext)) {
     throw new Error(`Unsupported file extension (${ext || "none"}): ${filePath}`);
   }
-  const content = await fs2.readFile(filePath);
-  const filename = path2.basename(filePath);
+  const content = await fs4.readFile(filePath);
+  const filename = path4.basename(filePath);
   return { filename, content, mimeType: getMimeType(filename), origin: "file", source: filePath };
 }
 async function readDirectory(dir) {
-  const entries = await fs2.readdir(dir, { withFileTypes: true });
+  const entries = await fs4.readdir(dir, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
     if (!entry.isFile()) continue;
-    const ext = path2.extname(entry.name).toLowerCase();
+    const ext = path4.extname(entry.name).toLowerCase();
     if (!SUPPORTED_EXTENSIONS.has(ext)) continue;
-    const full = path2.join(dir, entry.name);
-    const content = await fs2.readFile(full);
+    const full = path4.join(dir, entry.name);
+    const content = await fs4.readFile(full);
     files.push({ filename: entry.name, content, mimeType: getMimeType(entry.name), origin: "dir", source: full });
   }
   if (files.length === 0) {
@@ -399,10 +736,10 @@ async function fetchAsMarkdown(rawUrl) {
   };
 }
 async function resolveLocalPath(p) {
-  const abs = path2.resolve(p);
+  const abs = path4.resolve(p);
   let stat;
   try {
-    stat = await fs2.stat(abs);
+    stat = await fs4.stat(abs);
   } catch {
     throw new Error(`Path not found: ${p}`);
   }
@@ -438,7 +775,7 @@ function dedupeByFilename(files) {
     const count = used.get(f.filename) ?? 0;
     used.set(f.filename, count + 1);
     if (count === 0) return f;
-    const ext = path2.extname(f.filename);
+    const ext = path4.extname(f.filename);
     const stem = f.filename.slice(0, f.filename.length - ext.length);
     return { ...f, filename: `${stem}-${count}${ext}` };
   });
@@ -473,17 +810,17 @@ var add = {
   },
   dryRun: (ctx) => {
     const items = normalizeFilesInput(ctx.json("files"));
-    const body2 = {
+    const body4 = {
       name: ctx.str("name")
     };
     const scope = getExternalKnowledgeBaseTargetScope(ctx);
-    if (scope) body2.scope = scope;
-    body2.files = items.map((item) => ({ value: item, type: classifyInput(item) }));
-    body2.contentType = "multipart/form-data";
+    if (scope) body4.scope = scope;
+    body4.files = items.map((item) => ({ value: item, type: classifyInput(item) }));
+    body4.contentType = "multipart/form-data";
     return {
       method: "POST",
-      url: `${ctx.host().replace(/\/$/, "")}${API_PATH2}`,
-      body: body2
+      url: `${ctx.host().replace(/\/$/, "")}${API_PATH3}`,
+      body: body4
     };
   },
   execute: async (ctx) => {
@@ -491,7 +828,7 @@ var add = {
     const scope = getExternalKnowledgeBaseTargetScope(ctx);
     const files = await collectFiles(ctx);
     const form = buildForm(name, scope, files);
-    const result = await kbUpload(ctx, API_PATH2, form);
+    const result = await kbUpload(ctx, API_PATH3, form);
     return {
       uploaded: files.map((f) => ({ filename: f.filename, origin: f.origin, source: f.source })),
       result
@@ -500,7 +837,7 @@ var add = {
 };
 
 // src/commands/te-kb/compile.ts
-var API_PATH3 = "/agent/api/external/knowledge-bases/compile";
+var API_PATH4 = "/agent/api/external/knowledge-bases/compile";
 var VALID_MODES = /* @__PURE__ */ new Set(["incremental", "full"]);
 function getMode(ctx) {
   const mode = ctx.str("mode") || "incremental";
@@ -510,15 +847,15 @@ function getMode(ctx) {
   return mode;
 }
 function buildBody(ctx) {
-  const body2 = {
+  const body4 = {
     name: ctx.str("name"),
     mode: getMode(ctx)
   };
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
-  if (scope) body2.scope = scope;
+  if (scope) body4.scope = scope;
   const model = ctx.str("model");
-  if (model) body2.model = model;
-  return body2;
+  if (model) body4.model = model;
+  return body4;
 }
 var compile = {
   service: "kb",
@@ -537,19 +874,19 @@ var compile = {
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH3}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH4}`,
     body: buildBody(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH3, {}, buildBody(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH4, {}, buildBody(ctx))
 };
 
 // src/commands/te-kb/remove.ts
-var API_PATH4 = "/agent/api/external/knowledge-bases";
+var API_PATH5 = "/agent/api/external/knowledge-bases";
 function buildBody2(ctx) {
-  const body2 = { name: ctx.str("name") };
+  const body4 = { name: ctx.str("name") };
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
-  if (scope) body2.scope = scope;
-  return body2;
+  if (scope) body4.scope = scope;
+  return body4;
 }
 var remove = {
   service: "kb",
@@ -565,14 +902,14 @@ var remove = {
   },
   dryRun: (ctx) => ({
     method: "DELETE",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH4}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH5}`,
     body: buildBody2(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "DELETE", API_PATH4, {}, buildBody2(ctx))
+  execute: async (ctx) => kbApi(ctx, "DELETE", API_PATH5, {}, buildBody2(ctx))
 };
 
 // src/commands/te-kb/create.ts
-var API_PATH5 = "/agent/api/external/knowledge-bases/create";
+var API_PATH6 = "/agent/api/external/knowledge-bases/create";
 var VALID_SCOPES = /* @__PURE__ */ new Set(["personal", "company"]);
 function getScope(ctx) {
   const scope = ctx.str("scope") || "company";
@@ -600,19 +937,19 @@ function normalizeTags(raw) {
   return tags;
 }
 function buildBody3(ctx) {
-  const body2 = {
+  const body4 = {
     scope: getScope(ctx),
     name: ctx.str("name")
   };
   const description = ctx.str("description");
-  if (description) body2.description = description;
+  if (description) body4.description = description;
   const tags = normalizeTags(ctx.json("tags"));
-  if (tags && tags.length > 0) body2.tags = tags;
+  if (tags && tags.length > 0) body4.tags = tags;
   const projectId = ctx.str("project-id");
-  if (projectId) body2.projectId = projectId;
+  if (projectId) body4.projectId = projectId;
   const projectName = ctx.str("project-name");
-  if (projectName) body2.projectName = projectName;
-  return body2;
+  if (projectName) body4.projectName = projectName;
+  return body4;
 }
 var create = {
   service: "kb",
@@ -633,14 +970,14 @@ var create = {
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH5}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH6}`,
     body: buildBody3(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH5, {}, buildBody3(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH6, {}, buildBody3(ctx))
 };
 
 // src/commands/te-kb/rm-source.ts
-var API_PATH6 = "/agent/api/external/knowledge-bases/sources";
+var API_PATH7 = "/agent/api/external/knowledge-bases/sources";
 function sourceSelector(ctx) {
   const id = ctx.str("id").trim();
   if (id) return { id };
@@ -649,12 +986,12 @@ function sourceSelector(ctx) {
   throw new CliValidationError("One of --id or --display-name is required.");
 }
 function buildBody4(ctx) {
-  const body2 = {
+  const body4 = {
     name: ctx.str("name")
   };
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
-  if (scope) body2.scope = scope;
-  return { ...body2, ...sourceSelector(ctx) };
+  if (scope) body4.scope = scope;
+  return { ...body4, ...sourceSelector(ctx) };
 }
 var rmSource = {
   service: "kb",
@@ -673,18 +1010,18 @@ var rmSource = {
   },
   dryRun: (ctx) => ({
     method: "DELETE",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH6}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH7}`,
     body: buildBody4(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "DELETE", API_PATH6, {}, buildBody4(ctx), {
+  execute: async (ctx) => kbApi(ctx, "DELETE", API_PATH7, {}, buildBody4(ctx), {
     preserveErrorMetadata: true
   })
 };
 
 // src/commands/te-kb/schema.ts
-import fs3 from "fs";
-import path3 from "path";
-var API_PATH7 = "/agent/api/external/knowledge-bases/schema";
+import fs5 from "fs";
+import path5 from "path";
+var API_PATH8 = "/agent/api/external/knowledge-bases/schema";
 var MAX_CUSTOM_INSTRUCTIONS_CHARS = 1e4;
 function getCustomInstructions(ctx) {
   const inline = ctx.str("custom-instructions");
@@ -692,7 +1029,7 @@ function getCustomInstructions(ctx) {
   if (inline && file) {
     throw new Error("Use either --custom-instructions or --custom-instructions-file, not both.");
   }
-  const content = file ? fs3.readFileSync(path3.resolve(file), "utf8") : inline;
+  const content = file ? fs5.readFileSync(path5.resolve(file), "utf8") : inline;
   if (file && !content.trim()) {
     throw new Error("--custom-instructions-file is empty.");
   }
@@ -702,20 +1039,20 @@ function getCustomInstructions(ctx) {
   return content;
 }
 function buildBody5(ctx) {
-  const body2 = {
+  const body4 = {
     name: ctx.str("name")
   };
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
-  if (scope) body2.scope = scope;
-  if (ctx.bool("force")) body2.force = true;
+  if (scope) body4.scope = scope;
+  if (ctx.bool("force")) body4.force = true;
   const model = ctx.str("model");
-  if (model) body2.model = model;
+  if (model) body4.model = model;
   const customInstructions = getCustomInstructions(ctx);
-  if (customInstructions) body2.customInstructions = customInstructions;
-  return body2;
+  if (customInstructions) body4.customInstructions = customInstructions;
+  return body4;
 }
 async function executeSchema(ctx, api = kbApi) {
-  return api(ctx, "POST", API_PATH7, {}, buildBody5(ctx), {
+  return api(ctx, "POST", API_PATH8, {}, buildBody5(ctx), {
     preserveBusinessErrorCode: true
   });
 }
@@ -750,21 +1087,21 @@ var schema = {
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH7}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH8}`,
     body: buildBody5(ctx)
   }),
   execute: executeSchema
 };
 
 // src/commands/te-kb/status.ts
-var API_PATH8 = "/agent/api/external/knowledge-bases/status";
+var API_PATH9 = "/agent/api/external/knowledge-bases/status";
 function buildBody6(ctx) {
-  const body2 = {
+  const body4 = {
     name: ctx.str("name")
   };
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
-  if (scope) body2.scope = scope;
-  return body2;
+  if (scope) body4.scope = scope;
+  return body4;
 }
 var status = {
   service: "kb",
@@ -780,21 +1117,21 @@ var status = {
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH8}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH9}`,
     body: buildBody6(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH8, {}, buildBody6(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH9, {}, buildBody6(ctx))
 };
 
 // src/commands/te-kb/kb-index.ts
-var API_PATH9 = "/agent/api/external/knowledge-bases/index";
+var API_PATH10 = "/agent/api/external/knowledge-bases/index";
 function buildBody7(ctx) {
-  const body2 = {};
+  const body4 = {};
   const sources = ctx.json("sources");
-  if (sources) body2.sources = sources;
+  if (sources) body4.sources = sources;
   const locale = ctx.str("locale");
-  if (locale) body2.locale = locale;
-  return body2;
+  if (locale) body4.locale = locale;
+  return body4;
 }
 var kbIndex = {
   service: "kb",
@@ -812,14 +1149,14 @@ var kbIndex = {
   risk: "read",
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH9}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH10}`,
     body: buildBody7(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH9, {}, buildBody7(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH10, {}, buildBody7(ctx))
 };
 
 // src/commands/te-kb/kb-list.ts
-var API_PATH10 = "/agent/api/external/knowledge-bases/list";
+var API_PATH11 = "/agent/api/external/knowledge-bases/list";
 var DEFAULT_BUILD_STATUS = "compiled";
 var VALID_BUILD_STATUSES = ["idle", "pending", "compiling", "compiled", "failed"];
 function getBuildStatus(ctx) {
@@ -836,12 +1173,12 @@ function validateBuildStatus(ctx) {
   }
 }
 function buildBody8(ctx) {
-  const body2 = {
+  const body4 = {
     buildStatus: getBuildStatus(ctx)
   };
   const locale = ctx.str("locale");
-  if (locale) body2.locale = locale;
-  return body2;
+  if (locale) body4.locale = locale;
+  return body4;
 }
 var kbList = {
   service: "kb",
@@ -863,23 +1200,24 @@ var kbList = {
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH10}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH11}`,
     body: buildBody8(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH10, {}, buildBody8(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH11, {}, buildBody8(ctx))
 };
 
 // src/commands/te-kb/list-sources.ts
-var API_PATH11 = "/agent/api/external/knowledge-bases/sources";
+var API_PATH12 = "/agent/api/external/knowledge-bases/sources";
 var MAX_KNOWLEDGE_BASE_NAME_LENGTH = 200;
 function knowledgeBaseName(ctx) {
   return ctx.str("name").trim();
 }
 function buildUrl(ctx) {
-  const url2 = new URL(`${ctx.host().replace(/\/$/, "")}${API_PATH11}`);
+  const url2 = new URL(`${ctx.host().replace(/\/$/, "")}${API_PATH12}`);
   url2.searchParams.set("name", knowledgeBaseName(ctx));
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
   if (scope) url2.searchParams.set("scope", scope);
+  if (ctx.str("content-type")) url2.searchParams.set("contentType", ctx.str("content-type"));
   return url2.toString();
 }
 var listSources = {
@@ -900,7 +1238,8 @@ var listSources = {
       type: "string",
       required: false,
       desc: "Exact knowledge base scope: personal | company (omit for personal \u2192 company fallback)"
-    }
+    },
+    { name: "content-type", type: "string", desc: "Source content filter: all (default) or text (ordinary .md, .markdown and .txt files only)" }
   ],
   risk: "read",
   validate: (ctx) => {
@@ -914,6 +1253,9 @@ var listSources = {
       );
     }
     getExternalKnowledgeBaseTargetScope(ctx);
+    if ((ctx.has?.("content-type") || ctx.str("content-type")) && !["all", "text"].includes(ctx.str("content-type"))) {
+      throw new CliValidationError("--content-type must be all or text.");
+    }
   },
   dryRun: (ctx) => ({
     method: "GET",
@@ -923,26 +1265,82 @@ var listSources = {
     const params = { name: knowledgeBaseName(ctx) };
     const scope = getExternalKnowledgeBaseTargetScope(ctx);
     if (scope) params.scope = scope;
-    return kbApi(ctx, "GET", API_PATH11, params, void 0, {
+    if (ctx.str("content-type")) params.contentType = ctx.str("content-type");
+    return kbApi(ctx, "GET", API_PATH12, params, void 0, {
       preserveErrorMetadata: true,
       retryUnauthorized: false
     });
   }
 };
 
+// src/commands/te-kb/usage-list.ts
+var API_PATH13 = "/agent/api/external/knowledge-bases/usage-logs";
+function query3(ctx) {
+  const scope = getExternalKnowledgeBaseTargetScope(ctx);
+  return {
+    name: ctx.str("name").trim(),
+    ...scope ? { scope } : {},
+    page: ctx.num("page"),
+    pageSize: ctx.num("page-size")
+  };
+}
+var usageList = {
+  service: "kb",
+  resource: "usage",
+  command: "list",
+  risk: "read",
+  description: "List one page of compilation usage logs. durationMs is elapsed time in milliseconds; null means not recorded.",
+  flags: [
+    { name: "name", type: "string", required: true, minLength: 1, maxLength: 200, desc: "Exact knowledge base name from kb +list" },
+    { name: "scope", type: "string", desc: "Exact scope: personal | company (omit for personal then company lookup)" },
+    { name: "page", type: "number", default: 1, min: 1, max: 2147483647, desc: "Page number, starting at 1" },
+    { name: "page-size", type: "number", default: 20, min: 1, max: 100, desc: "Records per page, from 1 to 100" }
+  ],
+  validate: (ctx) => {
+    const name = ctx.str("name").trim();
+    if (!name || name.length > 200) throw new CliValidationError("--name must contain 1 to 200 characters.");
+    getExternalKnowledgeBaseTargetScope(ctx);
+    for (const [flag2, max] of [["page", 2147483647], ["page-size", 100]]) {
+      const value = ctx.num(flag2);
+      if (!Number.isInteger(value) || value < 1 || value > max) {
+        throw new CliValidationError(`--${flag2} must be an integer from 1 to ${max}.`);
+      }
+    }
+  },
+  dryRun: (ctx) => ({ method: "GET", url: `${ctx.host().replace(/\/$/, "")}${API_PATH13}`, params: query3(ctx) }),
+  execute: async (ctx) => {
+    try {
+      return await kbApi(ctx, "GET", API_PATH13, query3(ctx), void 0, { preserveErrorMetadata: true });
+    } catch (error) {
+      if (error instanceof PermissionError) {
+        error.message = "Permission denied when reading knowledge base usage logs.";
+      } else if (error instanceof CapabilityGatewayError) {
+        const messages = {
+          KB_USAGE_LOGS_INVALID_REQUEST: "Invalid knowledge base usage query parameters.",
+          KB_USAGE_LOGS_RATE_LIMITED: "Knowledge base usage query rate limit exceeded. Try again later.",
+          KB_USAGE_LOGS_NOT_FOUND: "Knowledge base not found in the requested scope.",
+          KB_USAGE_LOGS_INTERNAL_ERROR: "Failed to read knowledge base usage logs. Try again later."
+        };
+        if (error.code && messages[error.code]) error.message = messages[error.code];
+      }
+      throw error;
+    }
+  }
+};
+
 // src/commands/te-kb/kb-grep.ts
-var API_PATH12 = "/agent/api/external/knowledge-bases/grep";
+var API_PATH14 = "/agent/api/external/knowledge-bases/grep";
 function buildBody9(ctx) {
-  const body2 = {
+  const body4 = {
     query: ctx.str("query"),
     sources: ctx.json("sources"),
     paths: ctx.json("paths")
   };
   const topK = ctx.optionalNum("top-k");
-  if (topK !== void 0) body2.topK = topK;
+  if (topK !== void 0) body4.topK = topK;
   const locale = ctx.str("locale");
-  if (locale) body2.locale = locale;
-  return body2;
+  if (locale) body4.locale = locale;
+  return body4;
 }
 var kbGrep = {
   service: "kb",
@@ -974,14 +1372,14 @@ var kbGrep = {
   risk: "read",
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH12}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH14}`,
     body: buildBody9(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH12, {}, buildBody9(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH14, {}, buildBody9(ctx))
 };
 
 // src/commands/te-kb/kb-read.ts
-var API_PATH13 = "/agent/api/external/knowledge-bases/read";
+var API_PATH15 = "/agent/api/external/knowledge-bases/read";
 var VALID_EXPAND_MODES = /* @__PURE__ */ new Set(["block", "none"]);
 var MAX_READ_LIMIT = 2e3;
 function readExpand(ctx) {
@@ -1005,20 +1403,20 @@ function readLimit(ctx) {
   return limit;
 }
 function buildBody10(ctx) {
-  const body2 = {
+  const body4 = {
     source: ctx.json("source"),
     path: ctx.str("path")
   };
   const offset = ctx.optionalNum("offset");
-  if (offset !== void 0) body2.offset = offset;
+  if (offset !== void 0) body4.offset = offset;
   const limit = ctx.optionalNum("limit");
-  if (limit !== void 0) body2.limit = limit;
+  if (limit !== void 0) body4.limit = limit;
   const expand = readExpand(ctx);
-  if (expand) body2.expand = expand;
-  if (ctx.bool("outline")) body2.outline = true;
+  if (expand) body4.expand = expand;
+  if (ctx.bool("outline")) body4.outline = true;
   const locale = ctx.str("locale");
-  if (locale) body2.locale = locale;
-  return body2;
+  if (locale) body4.locale = locale;
+  return body4;
 }
 var kbRead = {
   service: "kb",
@@ -1059,10 +1457,10 @@ var kbRead = {
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH13}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH15}`,
     body: buildBody10(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH13, {}, buildBody10(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH15, {}, buildBody10(ctx))
 };
 
 // src/commands/te-kb/ask-shared.ts
@@ -1081,12 +1479,12 @@ function isTransientAskPollError(error) {
     error.message
   );
 }
-async function pollUntilSettled(getStatus, executionId, options = {}) {
-  const intervalMs = options.intervalMs ?? ASK_POLL_INTERVAL_MS;
-  const timeoutMs = options.timeoutMs ?? ASK_POLL_TIMEOUT_MS;
-  const maxTransientFailures = options.maxTransientFailures ?? ASK_MAX_TRANSIENT_POLL_FAILURES;
-  const now = options.now ?? Date.now;
-  const sleep = options.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
+async function pollUntilSettled(getStatus, executionId, options2 = {}) {
+  const intervalMs = options2.intervalMs ?? ASK_POLL_INTERVAL_MS;
+  const timeoutMs = options2.timeoutMs ?? ASK_POLL_TIMEOUT_MS;
+  const maxTransientFailures = options2.maxTransientFailures ?? ASK_MAX_TRANSIENT_POLL_FAILURES;
+  const now = options2.now ?? Date.now;
+  const sleep = options2.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
   const startTime = now();
   let transientFailures = 0;
   while (true) {
@@ -1143,16 +1541,16 @@ function validateLocale(locale) {
   }
 }
 function buildBody11(ctx) {
-  const body2 = {
+  const body4 = {
     question: ctx.str("question")
   };
   const sources = ctx.json("sources");
-  if (sources) body2.sources = sources;
+  if (sources) body4.sources = sources;
   const modelId = ctx.str("model-id");
-  if (modelId) body2.modelId = modelId;
+  if (modelId) body4.modelId = modelId;
   const locale = ctx.str("locale");
-  if (locale) body2.locale = locale;
-  return body2;
+  if (locale) body4.locale = locale;
+  return body4;
 }
 var ask = {
   service: "kb",
@@ -1272,24 +1670,24 @@ var askStatus = {
 };
 
 // src/commands/te-kb/url.ts
-var API_PATH14 = "/agent/api/external/knowledge-bases/sources/url";
+var API_PATH16 = "/agent/api/external/knowledge-bases/sources/url";
 function validateUrl(url2) {
   if (!/^https?:\/\//i.test(url2)) {
     throw new Error(`Invalid --url: ${url2}. Must be an http(s) URL`);
   }
 }
 function buildBody12(ctx) {
-  const body2 = {
+  const body4 = {
     name: ctx.str("name"),
     url: ctx.str("url")
   };
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
-  if (scope) body2.scope = scope;
+  if (scope) body4.scope = scope;
   const displayName = ctx.str("display-name");
-  if (displayName) body2.displayName = displayName;
+  if (displayName) body4.displayName = displayName;
   const parseInstruction = ctx.str("parse-instruction");
-  if (parseInstruction) body2.parseInstruction = parseInstruction;
-  return body2;
+  if (parseInstruction) body4.parseInstruction = parseInstruction;
+  return body4;
 }
 var url = {
   service: "kb",
@@ -1309,16 +1707,16 @@ var url = {
   },
   dryRun: (ctx) => ({
     method: "POST",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH14}`,
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH16}`,
     body: buildBody12(ctx)
   }),
-  execute: async (ctx) => kbApi(ctx, "POST", API_PATH14, {}, buildBody12(ctx))
+  execute: async (ctx) => kbApi(ctx, "POST", API_PATH16, {}, buildBody12(ctx))
 };
 
 // src/commands/te-kb/import.ts
-import { promises as fs4 } from "fs";
-import path4 from "path";
-var API_PATH15 = "/agent/api/external/knowledge-bases/import";
+import { promises as fs6 } from "fs";
+import path6 from "path";
+var API_PATH17 = "/agent/api/external/knowledge-bases/import";
 var MAX_SNAPSHOT_ARCHIVE_BYTES = 50 * 1024 * 1024;
 var VALID_SCOPES2 = /* @__PURE__ */ new Set(["personal", "company"]);
 function getScope2(ctx) {
@@ -1354,16 +1752,16 @@ function normalizeTags2(raw) {
   return tags;
 }
 function validateArchivePath(filePath) {
-  if (path4.extname(filePath).toLocaleLowerCase("en-US") !== ".zip") {
+  if (path6.extname(filePath).toLocaleLowerCase("en-US") !== ".zip") {
     throw new Error("--file must point to a .zip archive");
   }
 }
 async function readArchive(filePath) {
   validateArchivePath(filePath);
-  const absolutePath = path4.resolve(filePath);
+  const absolutePath = path6.resolve(filePath);
   let stat;
   try {
-    stat = await fs4.stat(absolutePath);
+    stat = await fs6.stat(absolutePath);
   } catch {
     throw new Error(`File not found: ${filePath}`);
   }
@@ -1373,7 +1771,7 @@ async function readArchive(filePath) {
   if (stat.size > MAX_SNAPSHOT_ARCHIVE_BYTES) {
     throw new Error("--file must not exceed 50 MB");
   }
-  return { absolutePath, bytes: await fs4.readFile(absolutePath) };
+  return { absolutePath, bytes: await fs6.readFile(absolutePath) };
 }
 function appendOptionalFields(ctx, form) {
   const description = ctx.str("description").trim();
@@ -1440,7 +1838,7 @@ var importSnapshot = {
     form.append(
       "file",
       new Blob([Uint8Array.from(archive.bytes)], { type: "application/zip" }),
-      path4.basename(archive.absolutePath)
+      path6.basename(archive.absolutePath)
     );
     form.append("name", ctx.str("name").trim());
     form.append("scope", getScope2(ctx));
@@ -1448,7 +1846,7 @@ var importSnapshot = {
     try {
       return await kbUpload(
         ctx,
-        API_PATH15,
+        API_PATH17,
         form,
         { scope: getScope2(ctx) },
         { preserveErrorMetadata: true, retryUnauthorized: true }
@@ -1477,7 +1875,7 @@ var importSnapshot = {
 };
 
 // src/commands/te-kb/import-status.ts
-var API_PATH16 = "/agent/api/external/knowledge-bases/import";
+var API_PATH18 = "/agent/api/external/knowledge-bases/import";
 var MAX_REQUEST_ID_LENGTH = 191;
 function requestIdFrom(ctx) {
   return ctx.str("request-id").trim();
@@ -1508,7 +1906,7 @@ var importStatus = {
   },
   dryRun: (ctx) => ({
     method: "GET",
-    url: `${ctx.host().replace(/\/$/, "")}${API_PATH16}?requestId=${encodeURIComponent(requestIdFrom(ctx))}`
+    url: `${ctx.host().replace(/\/$/, "")}${API_PATH18}?requestId=${encodeURIComponent(requestIdFrom(ctx))}`
   }),
   execute: async (ctx) => {
     const hint = "Verify the request ID and that the server supports kb +import-status. Do not retry the import until its status is known.";
@@ -1516,7 +1914,7 @@ var importStatus = {
       return await kbApi(
         ctx,
         "GET",
-        API_PATH16,
+        API_PATH18,
         { requestId: requestIdFrom(ctx) },
         void 0,
         { preserveErrorMetadata: true, retryUnauthorized: true }
@@ -1547,8 +1945,8 @@ var importStatus = {
 };
 
 // src/commands/te-kb/source-directory.ts
-import { promises as fs5 } from "fs";
-import path5 from "path";
+import { promises as fs7 } from "fs";
+import path7 from "path";
 var sourceFlags = [
   { name: "name", type: "string", required: true, desc: "Knowledge base name (personal then company)" },
   { name: "id", type: "string", required: true, desc: "ZIP source ID copied from +list-sources" }
@@ -1564,9 +1962,9 @@ var revisionFlag2 = {
 var apiOptions2 = { preserveErrorMetadata: true, retryUnauthorized: false };
 var maxFileBytes = 50 * 1024 * 1024;
 function validateIdentity2(ctx) {
-  for (const [flag, max] of [["name", 200], ["id", 191]]) {
-    const value = ctx.str(flag).trim();
-    if (!value || value.length > max) throw new CliValidationError(`Invalid --${flag}.`);
+  for (const [flag2, max] of [["name", 200], ["id", 191]]) {
+    const value = ctx.str(flag2).trim();
+    if (!value || value.length > max) throw new CliValidationError(`Invalid --${flag2}.`);
   }
 }
 function relativePath(ctx, allowRoot = false) {
@@ -1584,14 +1982,14 @@ function validateMutation2(ctx) {
     throw new CliValidationError("--expected-revision must be a positive safe integer.");
   }
 }
-function endpoint(ctx, suffix = "directory") {
+function endpoint2(ctx, suffix = "directory") {
   return `/agent/api/external/knowledge-bases/sources/${encodeURIComponent(ctx.str("id").trim())}/${suffix}`;
 }
-function query2(ctx) {
+function query4(ctx) {
   return { name: ctx.str("name").trim(), path: ctx.str("path") };
 }
-function preview(ctx, method, suffix = "directory", body2) {
-  return { method, url: `${ctx.host().replace(/\/$/, "")}${endpoint(ctx, suffix)}`, ...body2 ? { body: body2 } : { params: query2(ctx) } };
+function preview(ctx, method, suffix = "directory", body4) {
+  return { method, url: `${ctx.host().replace(/\/$/, "")}${endpoint2(ctx, suffix)}`, ...body4 ? { body: body4 } : { params: query4(ctx) } };
 }
 function mutationBody(ctx, operation) {
   return { name: ctx.str("name").trim(), expectedRevision: ctx.num("expected-revision"), operations: [operation] };
@@ -1614,9 +2012,9 @@ var sourceLs = {
       throw new CliValidationError("--limit must be an integer from 1 to 200.");
     }
   },
-  dryRun: (ctx) => ({ ...preview(ctx, "GET"), params: { ...query2(ctx), limit: ctx.num("limit"), ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {} } }),
-  execute: (ctx) => kbApi(ctx, "GET", endpoint(ctx), {
-    ...query2(ctx),
+  dryRun: (ctx) => ({ ...preview(ctx, "GET"), params: { ...query4(ctx), limit: ctx.num("limit"), ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {} } }),
+  execute: (ctx) => kbApi(ctx, "GET", endpoint2(ctx), {
+    ...query4(ctx),
     limit: ctx.num("limit"),
     ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {}
   }, void 0, apiOptions2)
@@ -1639,12 +2037,12 @@ var sourceRead = {
   },
   dryRun: (ctx) => preview(ctx, "GET", "raw"),
   execute: async (ctx) => {
-    const result = await kbApi(ctx, "GET", endpoint(ctx, "raw"), query2(ctx), void 0, { ...apiOptions2, responseType: "bytes" });
+    const result = await kbApi(ctx, "GET", endpoint2(ctx, "raw"), query4(ctx), void 0, { ...apiOptions2, responseType: "bytes" });
     const bytes = Buffer.from(result.bytes);
     const metadata = { path: ctx.str("path"), sizeBytes: bytes.length, contentType: result.contentType };
     if (ctx.str("output")) {
-      const output = path5.resolve(ctx.str("output"));
-      await fs5.writeFile(output, bytes, { flag: "wx" });
+      const output = path7.resolve(ctx.str("output"));
+      await fs7.writeFile(output, bytes, { flag: "wx" });
       return { ...metadata, output };
     }
     if (ctx.str("encoding") === "base64") return { ...metadata, encoding: "base64", content: bytes.toString("base64") };
@@ -1656,8 +2054,8 @@ var sourceRead = {
   }
 };
 async function fileOperation(ctx, dryRun) {
-  const file = path5.resolve(ctx.str("file"));
-  const handle = await fs5.open(file, "r");
+  const file = path7.resolve(ctx.str("file"));
+  const handle = await fs7.open(file, "r");
   try {
     const stat = await handle.stat();
     if (!stat.isFile() || stat.size > maxFileBytes) throw new CliValidationError("--file must be a regular file of at most 50 MB.");
@@ -1692,7 +2090,7 @@ var sourcePut = {
     if (!["add", "replace"].includes(ctx.str("action"))) throw new CliValidationError("--action must be add or replace.");
   },
   dryRun: async (ctx) => preview(ctx, "POST", "directory", mutationBody(ctx, await fileOperation(ctx, true))),
-  execute: async (ctx) => kbApi(ctx, "POST", endpoint(ctx), {}, mutationBody(ctx, await fileOperation(ctx, false)), apiOptions2)
+  execute: async (ctx) => kbApi(ctx, "POST", endpoint2(ctx), {}, mutationBody(ctx, await fileOperation(ctx, false)), apiOptions2)
 };
 function deleteOperation(ctx) {
   return { action: "delete", path: ctx.str("path"), confirmed: true, ...ctx.bool("recursive") ? { recursive: true } : {} };
@@ -1710,15 +2108,15 @@ var sourceRm = {
   ],
   validate: validateMutation2,
   dryRun: (ctx) => preview(ctx, "POST", "directory", mutationBody(ctx, deleteOperation(ctx))),
-  execute: (ctx) => kbApi(ctx, "POST", endpoint(ctx), {}, mutationBody(ctx, deleteOperation(ctx)), apiOptions2)
+  execute: (ctx) => kbApi(ctx, "POST", endpoint2(ctx), {}, mutationBody(ctx, deleteOperation(ctx)), apiOptions2)
 };
 
 // src/commands/te-kb/version-management.ts
-import { promises as fs6 } from "fs";
-import path6 from "path";
-var API2 = "/agent/api/external/knowledge-bases/versions";
+import { promises as fs8 } from "fs";
+import path8 from "path";
+var API3 = "/agent/api/external/knowledge-bases/versions";
 var apiOptions3 = { preserveErrorMetadata: true, retryUnauthorized: false };
-var targetFlags = [
+var targetFlags3 = [
   { name: "name", type: "string", required: true, minLength: 1, maxLength: 200, desc: "Exact knowledge base name copied from +list" },
   { name: "scope", type: "string", desc: "Exact personal or company scope; omit for personal then company lookup" }
 ];
@@ -1729,18 +2127,18 @@ var pagingFlags = [
   { name: "limit", type: "number", default: 100, min: 1, max: 200, desc: "Page size from 1 to 200" }
 ];
 var pathFlag2 = { name: "path", type: "string", desc: "Exact path relative to the historical source directory" };
-function positiveInteger2(ctx, flag) {
-  const value = ctx.num(flag);
-  if (!Number.isSafeInteger(value) || value < 1 || value > 2147483647) throw new CliValidationError(`--${flag} must be a positive integer no greater than 2147483647.`);
+function positiveInteger2(ctx, flag2) {
+  const value = ctx.num(flag2);
+  if (!Number.isSafeInteger(value) || value < 1 || value > 2147483647) throw new CliValidationError(`--${flag2} must be a positive integer no greater than 2147483647.`);
   return value;
 }
-function validateTarget(ctx) {
+function validateTarget2(ctx) {
   const name = ctx.str("name").trim();
   if (!name || name.length > 200) throw new CliValidationError("--name must contain 1 to 200 characters.");
   getExternalKnowledgeBaseTargetScope(ctx);
 }
 function validateVersion(ctx) {
-  validateTarget(ctx);
+  validateTarget2(ctx);
   positiveInteger2(ctx, "version");
 }
 function validateSource(ctx) {
@@ -1760,52 +2158,52 @@ function validatePath(ctx, required = false) {
     throw new CliValidationError("--path must be a normalized relative path inside the historical source.");
   }
 }
-function query3(ctx) {
+function query5(ctx) {
   const scope = getExternalKnowledgeBaseTargetScope(ctx);
   return { name: ctx.str("name").trim(), ...scope ? { scope } : {} };
 }
 function pageQuery(ctx) {
-  return { ...query3(ctx), limit: ctx.num("limit"), ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {} };
+  return { ...query5(ctx), limit: ctx.num("limit"), ...ctx.str("cursor") ? { cursor: ctx.str("cursor") } : {} };
 }
 function versionEndpoint(ctx, suffix = "") {
-  return `${API2}/${positiveInteger2(ctx, "version")}${suffix}`;
+  return `${API3}/${positiveInteger2(ctx, "version")}${suffix}`;
 }
 function sourceEndpoint2(ctx, action) {
   return versionEndpoint(ctx, `/sources/${encodeURIComponent(ctx.str("id").trim())}/${action}`);
 }
-function preview2(ctx, endpoint2, params, body2) {
-  return { method: body2 ? "POST" : "GET", url: `${ctx.host().replace(/\/$/, "")}${endpoint2}`, params, ...body2 ? { body: body2 } : {} };
+function preview2(ctx, endpoint3, params, body4) {
+  return { method: body4 ? "POST" : "GET", url: `${ctx.host().replace(/\/$/, "")}${endpoint3}`, params, ...body4 ? { body: body4 } : {} };
 }
 var versions = {
   service: "kb",
   command: "+versions",
   risk: "read",
   description: "List immutable published versions and the latest version ID, one page at a time.",
-  flags: [...targetFlags, ...pagingFlags],
+  flags: [...targetFlags3, ...pagingFlags],
   validate: (ctx) => {
-    validateTarget(ctx);
+    validateTarget2(ctx);
     validatePage(ctx);
     if (ctx.str("cursor") && (!/^[1-9][0-9]*$/.test(ctx.str("cursor")) || Number(ctx.str("cursor")) > 2147483647)) throw new CliValidationError("--cursor must be a version number returned as nextCursor.");
   },
-  dryRun: (ctx) => preview2(ctx, API2, pageQuery(ctx)),
-  execute: (ctx) => kbApi(ctx, "GET", API2, pageQuery(ctx), void 0, apiOptions3)
+  dryRun: (ctx) => preview2(ctx, API3, pageQuery(ctx)),
+  execute: (ctx) => kbApi(ctx, "GET", API3, pageQuery(ctx), void 0, apiOptions3)
 };
 var versionShow = {
   service: "kb",
   command: "+version-show",
   risk: "read",
   description: "Read one published version summary without reading current sources.",
-  flags: [...targetFlags, versionFlag],
+  flags: [...targetFlags3, versionFlag],
   validate: validateVersion,
-  dryRun: (ctx) => preview2(ctx, versionEndpoint(ctx), query3(ctx)),
-  execute: (ctx) => kbApi(ctx, "GET", versionEndpoint(ctx), query3(ctx), void 0, apiOptions3)
+  dryRun: (ctx) => preview2(ctx, versionEndpoint(ctx), query5(ctx)),
+  execute: (ctx) => kbApi(ctx, "GET", versionEndpoint(ctx), query5(ctx), void 0, apiOptions3)
 };
 var versionSources = {
   service: "kb",
   command: "+version-sources",
   risk: "read",
   description: "List historical sources and stable IDs from one immutable version.",
-  flags: [...targetFlags, versionFlag, ...pagingFlags, { name: "source-type", type: "string", desc: "Optional source type filter: file | url | zip" }],
+  flags: [...targetFlags3, versionFlag, ...pagingFlags, { name: "source-type", type: "string", desc: "Optional source type filter: file | url | zip" }],
   validate: (ctx) => {
     validateVersion(ctx);
     validatePage(ctx);
@@ -1819,21 +2217,21 @@ var versionDiff = {
   command: "+version-diff",
   risk: "read",
   description: "Compare historical source additions, deletions, content, and metadata between two versions.",
-  flags: [...targetFlags, { ...versionFlag, name: "from", desc: "Before version number" }, { ...versionFlag, name: "to", desc: "After version number" }],
+  flags: [...targetFlags3, { ...versionFlag, name: "from", desc: "Before version number" }, { ...versionFlag, name: "to", desc: "After version number" }],
   validate: (ctx) => {
-    validateTarget(ctx);
+    validateTarget2(ctx);
     positiveInteger2(ctx, "from");
     positiveInteger2(ctx, "to");
   },
-  dryRun: (ctx) => preview2(ctx, `${API2}/compare`, { ...query3(ctx), from: ctx.num("from"), to: ctx.num("to") }),
-  execute: (ctx) => kbApi(ctx, "GET", `${API2}/compare`, { ...query3(ctx), from: ctx.num("from"), to: ctx.num("to") }, void 0, apiOptions3)
+  dryRun: (ctx) => preview2(ctx, `${API3}/compare`, { ...query5(ctx), from: ctx.num("from"), to: ctx.num("to") }),
+  execute: (ctx) => kbApi(ctx, "GET", `${API3}/compare`, { ...query5(ctx), from: ctx.num("from"), to: ctx.num("to") }, void 0, apiOptions3)
 };
 var versionTree = {
   service: "kb",
   command: "+version-tree",
   risk: "read",
   description: "List a historical ZIP or URL source directory without changing current files.",
-  flags: [...targetFlags, versionFlag, sourceFlag, pathFlag2, ...pagingFlags],
+  flags: [...targetFlags3, versionFlag, sourceFlag, pathFlag2, ...pagingFlags],
   validate: (ctx) => {
     validateSource(ctx);
     validatePath(ctx);
@@ -1847,30 +2245,30 @@ var versionRead = {
   command: "+version-read",
   risk: "read",
   description: "Preview one historical directory child file; unsupported or oversized files return metadata only.",
-  flags: [...targetFlags, versionFlag, sourceFlag, { ...pathFlag2, required: true }],
+  flags: [...targetFlags3, versionFlag, sourceFlag, { ...pathFlag2, required: true }],
   validate: (ctx) => {
     validateSource(ctx);
     validatePath(ctx, true);
   },
-  dryRun: (ctx) => preview2(ctx, sourceEndpoint2(ctx, "file"), { ...query3(ctx), path: ctx.str("path") }),
-  execute: (ctx) => kbApi(ctx, "GET", sourceEndpoint2(ctx, "file"), { ...query3(ctx), path: ctx.str("path") }, void 0, apiOptions3)
+  dryRun: (ctx) => preview2(ctx, sourceEndpoint2(ctx, "file"), { ...query5(ctx), path: ctx.str("path") }),
+  execute: (ctx) => kbApi(ctx, "GET", sourceEndpoint2(ctx, "file"), { ...query5(ctx), path: ctx.str("path") }, void 0, apiOptions3)
 };
 var versionDownload = {
   service: "kb",
   command: "+version-download",
   risk: "read",
   description: "Download one ordinary historical file source to a new local file. ZIP/URL directories cannot be downloaded.",
-  flags: [...targetFlags, versionFlag, sourceFlag, { name: "output", type: "string", required: true, desc: "New local output path; existing files are never overwritten" }],
+  flags: [...targetFlags3, versionFlag, sourceFlag, { name: "output", type: "string", required: true, desc: "New local output path; existing files are never overwritten" }],
   validate: (ctx) => {
     validateSource(ctx);
     if (!ctx.str("output").trim()) throw new CliValidationError("--output is required.");
   },
-  dryRun: (ctx) => ({ ...preview2(ctx, sourceEndpoint2(ctx, "raw"), query3(ctx)), output: path6.resolve(ctx.str("output")) }),
+  dryRun: (ctx) => ({ ...preview2(ctx, sourceEndpoint2(ctx, "raw"), query5(ctx)), output: path8.resolve(ctx.str("output")) }),
   execute: async (ctx) => {
-    const result = await kbApi(ctx, "GET", sourceEndpoint2(ctx, "raw"), query3(ctx), void 0, { ...apiOptions3, responseType: "bytes" });
-    const output = path6.resolve(ctx.str("output"));
+    const result = await kbApi(ctx, "GET", sourceEndpoint2(ctx, "raw"), query5(ctx), void 0, { ...apiOptions3, responseType: "bytes" });
+    const output = path8.resolve(ctx.str("output"));
     const bytes = Buffer.from(result.bytes);
-    await fs6.writeFile(output, bytes, { flag: "wx" });
+    await fs8.writeFile(output, bytes, { flag: "wx" });
     return { versionNumber: ctx.num("version"), sourceId: ctx.str("id").trim(), sizeBytes: String(bytes.length), output };
   }
 };
@@ -1883,7 +2281,7 @@ var rollback = {
   risk: "high-risk-write",
   description: "Restore an earlier version as a new publication. Replace target-source drafts, delete other compiled sources, and preserve unpublished additions. Reuse request-id on network retries.",
   flags: [
-    ...targetFlags,
+    ...targetFlags3,
     versionFlag,
     { name: "request-id", type: "string", required: true, maxLength: 191, desc: "Caller-generated stable ASCII request ID; reuse exactly for retries of this logical operation" },
     { name: "expected-latest-version-id", type: "string", required: true, maxLength: 191, desc: "latestVersionId returned by +versions; conflicts require fresh discovery and a new intentional request" }
@@ -1894,26 +2292,31 @@ var rollback = {
     const latest = ctx.str("expected-latest-version-id");
     if (!latest || latest.length > 191) throw new CliValidationError("--expected-latest-version-id must contain 1 to 191 characters.");
   },
-  dryRun: (ctx) => preview2(ctx, versionEndpoint(ctx, "/rollback"), query3(ctx), rollbackBody(ctx)),
-  execute: (ctx) => kbApi(ctx, "POST", versionEndpoint(ctx, "/rollback"), query3(ctx), rollbackBody(ctx), apiOptions3)
+  dryRun: (ctx) => preview2(ctx, versionEndpoint(ctx, "/rollback"), query5(ctx), rollbackBody(ctx)),
+  execute: (ctx) => kbApi(ctx, "POST", versionEndpoint(ctx, "/rollback"), query5(ctx), rollbackBody(ctx), apiOptions3)
 };
 var rollbackStatus = {
   service: "kb",
   command: "+rollback-status",
   risk: "read",
   description: "Read one persisted rollback operation without polling. A running operation with errorCode requires administrator review; never retry it as a new write.",
-  flags: [...targetFlags, { name: "operation-id", type: "string", required: true, minLength: 1, maxLength: 191, desc: "operationId returned by +rollback" }],
+  flags: [...targetFlags3, { name: "operation-id", type: "string", required: true, minLength: 1, maxLength: 191, desc: "operationId returned by +rollback" }],
   validate: (ctx) => {
-    validateTarget(ctx);
+    validateTarget2(ctx);
     if (!ctx.str("operation-id").trim() || ctx.str("operation-id").length > 191) throw new CliValidationError("--operation-id must contain 1 to 191 characters.");
   },
-  dryRun: (ctx) => preview2(ctx, `${API2}/operations/${encodeURIComponent(ctx.str("operation-id").trim())}`, query3(ctx)),
-  execute: (ctx) => kbApi(ctx, "GET", `${API2}/operations/${encodeURIComponent(ctx.str("operation-id").trim())}`, query3(ctx), void 0, apiOptions3)
+  dryRun: (ctx) => preview2(ctx, `${API3}/operations/${encodeURIComponent(ctx.str("operation-id").trim())}`, query5(ctx)),
+  execute: (ctx) => kbApi(ctx, "GET", `${API3}/operations/${encodeURIComponent(ctx.str("operation-id").trim())}`, query5(ctx), void 0, apiOptions3)
 };
 
 // src/commands/te-kb/index.ts
 var commands = [
+  usageList,
+  ...schemaImportCommands,
   sourceCheckUpdates,
+  sourceCheckUrlUpdates,
+  sourceCreateText,
+  sourceReadText,
   sourceReplace,
   sourceRestore,
   sourcePreview,
@@ -1958,6 +2361,7 @@ export {
   compile,
   create,
   te_kb_default as default,
+  executeSchemaImport,
   importSnapshot,
   importStatus,
   kbGrep,
@@ -1970,23 +2374,41 @@ export {
   rollback,
   rollbackStatus,
   schema,
+  schemaDownload,
+  schemaImport,
+  schemaImportAbandon,
+  schemaImportApply,
+  schemaImportCommands,
+  schemaImportContent,
+  schemaImportDiff,
+  schemaImportList,
+  schemaImportOptimize,
+  schemaImportReject,
+  schemaImportSave,
+  schemaImportStatus,
+  schemaImportValidate,
   sourceCancel,
   sourceCheckUpdates,
+  sourceCheckUrlUpdates,
   sourceCommit,
+  sourceCreateText,
   sourceLs,
   sourcePreview,
   sourcePut,
   sourceRead,
+  sourceReadText,
   sourceReplace,
   sourceRestore,
   sourceRm,
   status,
   url,
+  usageList,
   versionDiff,
   versionDownload,
   versionRead,
   versionShow,
   versionSources,
   versionTree,
-  versions
+  versions,
+  waitSchemaImport
 };