@lotics/cli 0.150.2 → 0.152.0

package/dist/src/cli.js

@@ -44434,6 +44434,22 @@ var LoticsClient = class {
   async getKnowledgeDoc(knowledge_doc_id) {
     return this.request("GET", `/v1/knowledge_docs/${encodeURIComponent(knowledge_doc_id)}`);
   }
+  /**
+   * Every doc's metadata — REST rather than the `list_knowledge` tool, because
+   * this is the surface a PERSON manages the corpus from and the tool is bound
+   * to what the assistant may browse. That distinction is the whole point of
+   * `include_hidden`: a hidden doc is out of the assistant's corpus by design,
+   * and someone still has to be able to find it in order to put it back.
+   */
+  async listKnowledgeDocs(opts) {
+    const qs = opts?.includeHidden ? "?include_hidden=true" : "";
+    return this.request("GET", `/v1/knowledge_docs${qs}`);
+  }
+  /** Apply one metadata change to a set of docs. Tags are an add/remove DIFF —
+   *  see the endpoint's own note on why a replacement is the wrong shape here. */
+  async bulkUpdateKnowledgeDocs(body) {
+    return this.request("PATCH", "/v1/knowledge_docs", body);
+  }
   // --- Apps ---
   async getApp(app_id) {
     return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}`);
@@ -45132,14 +45148,27 @@ var LoticsClient = class {
     );
   }
   async uploadFiles(filePaths, options) {
-    const formData = new FormData();
+    const items = [];
     for (let i2 = 0; i2 < filePaths.length; i2++) {
       const absolutePath = path2.resolve(filePaths[i2]);
-      const buffer = await fs2.promises.readFile(absolutePath);
-      const filename = options?.filenames?.[i2] ?? path2.basename(absolutePath);
-      const mimeType = getMimeType(filename);
-      const blob = new Blob([buffer], { type: mimeType });
-      formData.append("file", blob, filename);
+      items.push({
+        bytes: await fs2.promises.readFile(absolutePath),
+        filename: options?.filenames?.[i2] ?? path2.basename(absolutePath)
+      });
+    }
+    return this.uploadFileBytes(items);
+  }
+  /**
+   * Store files from bytes the caller already holds — the path for a caller that
+   * never had them on disk (an email attachment decoded in memory, a generated
+   * document, a fetched URL). `uploadFiles` is this with a read in front, so
+   * both routes hit one endpoint and one mime-derivation rule.
+   */
+  async uploadFileBytes(items) {
+    const formData = new FormData();
+    for (const item of items) {
+      const mimeType = item.mimeType ?? getMimeType(item.filename);
+      formData.append("file", new Blob([item.bytes], { type: mimeType }), item.filename);
     }
     const url2 = `${this.baseUrl}/v1/files`;
     const response = await fetch(url2, {
@@ -45152,6 +45181,92 @@ var LoticsClient = class {
   }
 };
 
+// src/upload_source.ts
+var MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
+var URL_FETCH_TIMEOUT_MS = 3e4;
+async function readStdinBytes(limit) {
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of process.stdin) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    total += buf.byteLength;
+    if (total > limit) return { tooLarge: true };
+    chunks.push(buf);
+  }
+  return Buffer.concat(chunks);
+}
+function decodeBase64Strict(input) {
+  const text = Buffer.from(input).toString("utf8").trim();
+  const canonical = text.replace(/\s+/g, "").replace(/=+$/, "");
+  if (canonical.length > 0 && !/^[A-Za-z0-9+/]+$/.test(canonical)) return null;
+  const decoded = Buffer.from(text, "base64");
+  if (decoded.toString("base64").replace(/=+$/, "") !== canonical) return null;
+  return decoded;
+}
+function filenameFromResponse(headers, url2) {
+  const disposition = headers.get("content-disposition");
+  const encoded = disposition?.match(/filename\*=\s*(?:UTF-8'')?"?([^";]+)"?/i);
+  const plain = disposition?.match(/filename=\s*"?([^";]+)"?/i);
+  const raw = encoded?.[1] ?? plain?.[1];
+  if (raw) return decodeURIComponent(raw.trim());
+  const last3 = new URL(url2).pathname.split("/").filter(Boolean).pop();
+  return last3 && last3.includes(".") ? decodeURIComponent(last3) : void 0;
+}
+async function resolveUploadSource(sourceFlag, flags) {
+  let bytes;
+  let filename = flags.as;
+  if (flags.url !== void 0) {
+    const controller = new AbortController();
+    const timer2 = setTimeout(() => controller.abort(), URL_FETCH_TIMEOUT_MS);
+    let response;
+    try {
+      response = await fetch(flags.url, { signal: controller.signal });
+    } catch (e) {
+      const reason = controller.signal.aborted ? `no response within ${URL_FETCH_TIMEOUT_MS}ms` : e instanceof Error ? e.message : String(e);
+      return { error: `Fetch failed for ${flags.url}: ${reason}` };
+    } finally {
+      clearTimeout(timer2);
+    }
+    if (!response.ok) {
+      return { error: `Fetch failed: ${response.status} ${response.statusText} for ${flags.url}` };
+    }
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_UPLOAD_BYTES) {
+      return { error: `That URL returns ${declared} bytes; the upload limit is ${MAX_UPLOAD_BYTES}.` };
+    }
+    bytes = new Uint8Array(await response.arrayBuffer());
+    filename ??= filenameFromResponse(response.headers, flags.url);
+  } else {
+    const read = await readStdinBytes(MAX_UPLOAD_BYTES);
+    if ("tooLarge" in read) {
+      return { error: `stdin exceeded the ${MAX_UPLOAD_BYTES}-byte upload limit.` };
+    }
+    if (read.byteLength === 0) {
+      return { error: `${sourceFlag} was given but stdin was empty \u2014 pipe the bytes in.` };
+    }
+    if (flags.base64) {
+      const decoded = decodeBase64Strict(read);
+      if (decoded === null) {
+        return {
+          error: "--base64 input is not valid base64: it contains characters outside the standard alphabet (base64url is not accepted) or is truncated."
+        };
+      }
+      bytes = decoded;
+    } else {
+      bytes = read;
+    }
+  }
+  if (bytes.byteLength > MAX_UPLOAD_BYTES) {
+    return { error: `That is ${bytes.byteLength} bytes; the upload limit is ${MAX_UPLOAD_BYTES}.` };
+  }
+  if (filename === void 0) {
+    return {
+      error: "--as <name> is required: no filename could be derived from the source, and the mime type comes from it."
+    };
+  }
+  return { bytes, filename };
+}
+
 // src/telemetry.ts
 import crypto from "node:crypto";
 import fs3 from "node:fs";
@@ -45894,15 +46009,24 @@ var COMMANDS = [
   {
     verbs: ["knowledge"],
     help: [
-      "  lotics knowledge list                List knowledge docs (id, name, description)",
-      "  lotics knowledge create --name <n> [--description <d>] --from <file.md>",
+      "  lotics knowledge list [--include-hidden]",
+      "                                       List knowledge docs (id, name, tags, description)",
+      "  lotics knowledge create --name <n> [--description <d>] [--tags <a,b>] --from <file.md>",
       "                                       Create a doc from a file (or --content <str>);",
       "                                       prints the new id",
       "  lotics knowledge get <id> [-o <file.md>]",
       "                                       Fetch a doc's content (to a file, or stdout;",
       "                                       --json for the full doc)",
-      "  lotics knowledge update <id> [--from <file.md> | --content <str>] [--name <n>] [--description <d>]",
-      "                                       Update a doc \u2014 sends only the fields you pass",
+      "  lotics knowledge update <id> [--from <file.md> | --content <str>] [--name <n>] [--description <d>] [--tags <a,b>]",
+      "                                       Update a doc \u2014 sends only the fields you pass;",
+      "                                       --tags REPLACES the doc's labels",
+      "  lotics knowledge tag <id...> [--add <a,b>] [--remove <c,d>]",
+      "                                       Re-label a set of docs; adds/removes apply to",
+      "                                       each doc's own labels",
+      "  lotics knowledge hide <id...>        Take docs out of circulation \u2014 gone from the",
+      "                                       Library list and from what the assistant browses",
+      "                                       and searches, still readable by id",
+      "  lotics knowledge unhide <id...>      Put them back",
       "  lotics knowledge rm <id>             Archive a doc"
     ]
   },
@@ -45928,6 +46052,9 @@ var COMMANDS = [
     aliases: ["upload", "download", "preview"],
     help: [
       "  lotics file upload <file|dir...>     Upload files (alias: lotics upload)",
+      "  lotics file upload --stdin --as <name>",
+      "                                       Upload bytes you already hold, piped on stdin",
+      "                                       (--base64 for base64; --url <url> to fetch first)",
       "  lotics file download <file_id>       Download a file by ID (alias: lotics download)",
       "  lotics file download record <record_id> <field_key>",
       "                                       Download all files on a record file field",
@@ -74389,10 +74516,16 @@ ${totalErrors} error${totalErrors === 1 ? "" : "s"} across ${results.length - pa
 }
 
 // src/args.ts
+function splitList(value2) {
+  return (value2 ?? "").split(",").map((part) => part.trim()).filter((part) => part !== "");
+}
 function parseArgs(argv) {
   const flags = {
     json: false,
     force: false,
+    stdin: false,
+    base64: false,
+    url: void 0,
     fromVersion: void 0,
     timeout: void 0,
     output: void 0,
@@ -74404,6 +74537,10 @@ function parseArgs(argv) {
     description: void 0,
     from: void 0,
     content: void 0,
+    tags: void 0,
+    add: void 0,
+    remove: void 0,
+    includeHidden: false,
     timezone: void 0,
     message: void 0,
     session: void 0,
@@ -74430,6 +74567,15 @@ function parseArgs(argv) {
       case "--force":
         flags.force = true;
         break;
+      case "--stdin":
+        flags.stdin = true;
+        break;
+      case "--base64":
+        flags.base64 = true;
+        break;
+      case "--url":
+        flags.url = argv[++i2];
+        break;
       case "--from-version":
         flags.fromVersion = argv[++i2];
         break;
@@ -74465,6 +74611,21 @@ function parseArgs(argv) {
       case "--content":
         flags.content = argv[++i2];
         break;
+      // Comma-separated AND repeatable, because a label can contain a space but
+      // never a comma, and an agent scripting this will reach for whichever form
+      // it happens to know. Both accumulate rather than the last winning.
+      case "--tags":
+        flags.tags = [...flags.tags ?? [], ...splitList(argv[++i2])];
+        break;
+      case "--add":
+        flags.add = [...flags.add ?? [], ...splitList(argv[++i2])];
+        break;
+      case "--remove":
+        flags.remove = [...flags.remove ?? [], ...splitList(argv[++i2])];
+        break;
+      case "--include-hidden":
+        flags.includeHidden = true;
+        break;
       case "--timezone":
         flags.timezone = argv[++i2];
         break;
@@ -102402,6 +102563,13 @@ async function runDocxCommand(subcommand, toolArgs, restArgs) {
 
 // src/knowledge.ts
 import fs12 from "node:fs";
+
+// ../shared/src/knowledge_tags.ts
+function isHiddenDoc(doc) {
+  return doc.hidden_at != null;
+}
+
+// src/knowledge.ts
 function readBodyFile(filePath) {
   if (!fs12.existsSync(filePath)) fail2(`File not found: ${filePath}`);
   return fs12.readFileSync(filePath, "utf-8");
@@ -102420,37 +102588,46 @@ function unwrap(res) {
   return res.result;
 }
 async function knowledgeList(client, flags) {
-  const result = unwrap(await client.execute("list_knowledge", {}));
-  const payload = result;
-  const results = Array.isArray(payload?.results) ? payload.results : [];
+  const docs = await client.listKnowledgeDocs({ includeHidden: flags.includeHidden });
   if (flags.json) {
-    console.log(JSON.stringify(results, null, 2));
+    console.log(JSON.stringify(docs, null, 2));
     return;
   }
-  if (results.length === 0) {
-    console.error("No knowledge docs in this workspace.");
+  if (docs.length === 0) {
+    console.error(
+      flags.includeHidden ? "No knowledge docs in this workspace." : "No knowledge docs in this workspace. Add --include-hidden if some may be out of circulation."
+    );
     return;
   }
-  const rows = results.map((r) => {
-    const doc = r;
-    return {
-      id: typeof doc.id === "string" ? doc.id : "",
-      name: typeof doc.name === "string" ? doc.name : "",
-      // Collapse whitespace so a multi-line description never breaks the row.
-      description: typeof doc.description === "string" ? doc.description.replace(/\s+/g, " ").trim() : ""
-    };
-  });
+  const rows = docs.map((doc) => ({
+    id: doc.id,
+    name: doc.name,
+    tags: doc.tags.join(", "),
+    // Collapse whitespace so a multi-line description never breaks the row.
+    description: doc.description.replace(/\s+/g, " ").trim(),
+    // The shared predicate, not a comparison written here: this CLI is pinned
+    // per version and runs against whatever backend a workspace is on, including
+    // one that predates the field, and reading its absence as hidden would mark
+    // every row.
+    hidden: isHiddenDoc(doc)
+  }));
   const wId = Math.max("ID".length, ...rows.map((r) => r.id.length));
   const wName = Math.max("NAME".length, ...rows.map((r) => r.name.length));
+  const wTags = Math.max("TAGS".length, ...rows.map((r) => r.tags.length));
   const pad = (s, n) => s.padEnd(n);
-  console.log(`${pad("ID", wId)}  ${pad("NAME", wName)}  DESCRIPTION`);
+  console.log(`${pad("ID", wId)}  ${pad("NAME", wName)}  ${pad("TAGS", wTags)}  DESCRIPTION`);
   for (const r of rows) {
-    console.log(`${pad(r.id, wId)}  ${pad(r.name, wName)}  ${r.description}`.trimEnd());
+    const description = r.hidden ? `(hidden) ${r.description}`.trimEnd() : r.description;
+    console.log(`${pad(r.id, wId)}  ${pad(r.name, wName)}  ${pad(r.tags, wTags)}  ${description}`.trimEnd());
   }
 }
 async function knowledgeCreate(client, flags) {
   const name2 = flags.name;
-  if (!name2) fail2("Usage: lotics knowledge create --name <name> [--description <d>] (--from <file.md> | --content <str>)");
+  if (!name2) {
+    fail2(
+      "Usage: lotics knowledge create --name <name> [--description <d>] [--tags <a,b>] (--from <file.md> | --content <str>)"
+    );
+  }
   const content = resolveBody(flags, true);
   const result = unwrap(
     await client.execute("create_knowledge", {
@@ -102458,7 +102635,11 @@ async function knowledgeCreate(client, flags) {
       // The tool requires a description (empty string is accepted); the CLI
       // treats it as optional and defaults to "".
       description: flags.description ?? "",
-      content
+      content,
+      // Filed at the moment it is made. Creating and then labelling is two round
+      // trips and leaves the doc unfiled in between, which is when a corpus
+      // acquires the untagged rows nobody goes back for.
+      ...flags.tags !== void 0 && { tags: flags.tags }
     })
   );
   if (flags.json) {
@@ -102484,15 +102665,20 @@ async function knowledgeGet(client, id, flags) {
   console.log(doc.content);
 }
 async function knowledgeUpdate(client, id, flags) {
-  if (!id) fail2("Usage: lotics knowledge update <id> [--from <file.md> | --content <str>] [--name <n>] [--description <d>]");
+  if (!id) {
+    fail2(
+      "Usage: lotics knowledge update <id> [--from <file.md> | --content <str>] [--name <n>] [--description <d>] [--tags <a,b>]"
+    );
+  }
   const content = resolveBody(flags, false);
-  if (content === void 0 && flags.name === void 0 && flags.description === void 0) {
-    fail2("Nothing to update. Pass at least one of --from/--content, --name, or --description.");
+  if (content === void 0 && flags.name === void 0 && flags.description === void 0 && flags.tags === void 0) {
+    fail2("Nothing to update. Pass at least one of --from/--content, --name, --description, or --tags.");
   }
   const args = { knowledge_doc_id: id };
   if (content !== void 0) args.content = content;
   if (flags.name !== void 0) args.name = flags.name;
   if (flags.description !== void 0) args.description = flags.description;
+  if (flags.tags !== void 0) args.tags = flags.tags;
   const result = unwrap(await client.execute("update_knowledge", args));
   if (flags.json) {
     console.log(JSON.stringify(result, null, 2));
@@ -102509,21 +102695,64 @@ async function knowledgeRm(client, id, flags) {
   }
   console.error(`Deleted knowledge doc: ${id}`);
 }
+function requireIds(ids, usage) {
+  const parsed = ids.filter((id) => id !== void 0).flatMap((id) => id.split(",")).map((id) => id.trim()).filter((id) => id !== "");
+  if (parsed.length === 0) fail2(usage);
+  return parsed;
+}
+async function knowledgeTag(client, ids, flags) {
+  const knowledge_doc_ids = requireIds(ids, "Usage: lotics knowledge tag <id...> [--add a,b] [--remove c,d]");
+  if (flags.add === void 0 && flags.remove === void 0) {
+    fail2("Pass --add <tags> and/or --remove <tags>.");
+  }
+  const updated = await client.bulkUpdateKnowledgeDocs({
+    knowledge_doc_ids,
+    ...flags.add !== void 0 && { add_tags: flags.add },
+    ...flags.remove !== void 0 && { remove_tags: flags.remove }
+  });
+  if (flags.json) {
+    console.log(JSON.stringify(updated, null, 2));
+    return;
+  }
+  for (const doc of updated) {
+    console.error(`${doc.id}  ${doc.tags.length > 0 ? doc.tags.join(", ") : "(no tags)"}`);
+  }
+}
+async function knowledgeSetHidden(client, ids, hidden, flags) {
+  const verb = hidden ? "hide" : "unhide";
+  const knowledge_doc_ids = requireIds(ids, `Usage: lotics knowledge ${verb} <id...>`);
+  const updated = await client.bulkUpdateKnowledgeDocs({ knowledge_doc_ids, hidden });
+  if (flags.json) {
+    console.log(JSON.stringify(updated, null, 2));
+    return;
+  }
+  console.error(
+    hidden ? `Hid ${updated.length} doc(s). They are out of the assistant's corpus; lotics knowledge list --include-hidden still finds them.` : `Restored ${updated.length} doc(s) to the corpus.`
+  );
+}
 function printKnowledgeHelp() {
   console.error(`Lotics knowledge commands \u2014 manage the AI's rulebook docs.
 
-  lotics knowledge list [--json]
-      Catalog every doc you can use (id, name, description).
-  lotics knowledge create --name <n> [--description <d>] (--from <file.md> | --content <str>) [--json]
+  lotics knowledge list [--include-hidden] [--json]
+      Catalog every doc you can use (id, name, tags, description).
+  lotics knowledge create --name <n> [--description <d>] [--tags <a,b>] (--from <file.md> | --content <str>) [--json]
       Create a doc; the body comes from a file or an inline string. Prints the new id.
   lotics knowledge get <id> [-o <file.md>] [--json]
       Fetch a doc's content \u2014 to <file.md>, or stdout. --json prints the full doc.
   lotics knowledge update <id> [--from <file.md> | --content <str>] [--name <n>] [--description <d>] [--json]
       Update a doc; sends only the fields you pass.
+  lotics knowledge tag <id...> [--add a,b] [--remove c,d] [--json]
+      Re-label a set of docs. Adds and removes are a DIFF applied to each doc's
+      own labels \u2014 use update --tags to state one doc's complete set.
+  lotics knowledge hide <id...> [--json]
+      Take docs out of circulation: gone from the Library's list and from what
+      the assistant browses and searches, still readable by id, nothing deleted.
+  lotics knowledge unhide <id...> [--json]
+      Put them back.
   lotics knowledge rm <id> [--json]
       Archive a doc.`);
 }
-async function runKnowledgeCommand(client, subcommand, toolArgs, flags) {
+async function runKnowledgeCommand(client, subcommand, toolArgs, flags, restArgs = []) {
   switch (subcommand) {
     case "list":
       return knowledgeList(client, flags);
@@ -102533,6 +102762,12 @@ async function runKnowledgeCommand(client, subcommand, toolArgs, flags) {
       return knowledgeGet(client, toolArgs, flags);
     case "update":
       return knowledgeUpdate(client, toolArgs, flags);
+    case "tag":
+      return knowledgeTag(client, [toolArgs, ...restArgs], flags);
+    case "hide":
+      return knowledgeSetHidden(client, [toolArgs, ...restArgs], true, flags);
+    case "unhide":
+      return knowledgeSetHidden(client, [toolArgs, ...restArgs], false, flags);
     case "rm":
       return knowledgeRm(client, toolArgs, flags);
     default:
@@ -102791,7 +103026,10 @@ FLAGS
   --json             Full JSON output (default is human-readable text)
   --timeout <ms>     Timeout for tool execution (default: 60000)
   -o <path>          Output dir for downloads
-  --as <name>        Override upload filename
+  --as <name>        Override upload filename (required with --stdin/--base64)
+  --stdin            Upload raw bytes piped on stdin instead of a path
+  --base64           Upload base64 piped on stdin (decoded strictly)
+  --url <url>        Fetch a URL and upload what it returns
   --api-key <key>    One-off API key (overrides saved config + env)
   --workspace <id>   One-off workspace override (alias: -w)
   --view-as <id>     Admin "View as": run every request as this member, so
@@ -103394,8 +103632,12 @@ async function main() {
     console.error('Run "lotics tools" to see available tools.');
     process.exit(1);
   }
-  if (command === "upload" && !subcommand) {
-    console.error("Usage: lotics upload <file|dir...> [--as <name>]");
+  if (command === "upload" && !subcommand && !flags.stdin && !flags.base64 && !flags.url) {
+    console.error("Usage:");
+    console.error("  lotics upload <file|dir...> [--as <name>]");
+    console.error("  lotics upload --stdin --as <name>     Raw bytes on stdin");
+    console.error("  lotics upload --base64 --as <name>    Base64 on stdin");
+    console.error("  lotics upload --url <url> [--as <name>]");
     console.error("Uploads files and returns their file_ids. Directories expand to their immediate files.");
     process.exit(1);
   }
@@ -103556,7 +103798,7 @@ Available workspaces:`);
   applyAppManifestWorkspace(ctx, command, subcommand, appPathArg, flags);
   await resolveWorkspace(client, ctx);
   if (command === "knowledge") {
-    await runKnowledgeCommand(client, subcommand, toolArgs, flags);
+    await runKnowledgeCommand(client, subcommand, toolArgs, flags, restArgs);
     return;
   }
   if (command === "app") {
@@ -103799,19 +104041,39 @@ ${JSON.stringify(info.input_schema, null, 2)}`);
     return;
   }
   if (command === "upload") {
-    const rawPaths = [subcommand, ...toolArgs ? [toolArgs] : [], ...restArgs];
-    const filePaths = resolveUploadPaths(rawPaths);
-    if (filePaths.length === 0) {
-      console.error("No files found in the specified paths.");
+    const sources = [flags.stdin && "--stdin", flags.base64 && "--base64", flags.url && "--url"].filter(Boolean);
+    if (sources.length > 1) {
+      console.error(`Pick one source: ${sources.join(", ")} were all given.`);
       process.exit(1);
     }
-    if (flags.as && filePaths.length > 1) {
-      console.error("Cannot use --as with multiple files.");
-      process.exit(1);
+    let upload;
+    if (sources.length === 1) {
+      const positional = [subcommand, toolArgs, ...restArgs].filter((v) => v !== void 0);
+      if (positional.length > 0) {
+        console.error(`${sources[0]} reads the bytes itself \u2014 drop the path argument (${positional.join(", ")}).`);
+        process.exit(1);
+      }
+      const resolved = await resolveUploadSource(String(sources[0]), flags);
+      if ("error" in resolved) {
+        console.error(resolved.error);
+        process.exit(1);
+      }
+      upload = await client.uploadFileBytes([resolved]);
+    } else {
+      const rawPaths = [subcommand, ...toolArgs ? [toolArgs] : [], ...restArgs];
+      const filePaths = resolveUploadPaths(rawPaths);
+      if (filePaths.length === 0) {
+        console.error("No files found in the specified paths.");
+        process.exit(1);
+      }
+      if (flags.as && filePaths.length > 1) {
+        console.error("Cannot use --as with multiple files.");
+        process.exit(1);
+      }
+      upload = await client.uploadFiles(filePaths, {
+        filenames: flags.as ? [flags.as] : void 0
+      });
     }
-    const upload = await client.uploadFiles(filePaths, {
-      filenames: flags.as ? [flags.as] : void 0
-    });
     if (upload.files.length === 0 && upload.errors.length > 0) {
       console.error(`Upload failed: ${upload.errors.map((e) => `${e.filename}: ${e.error}`).join(", ")}`);
       process.exit(1);

package/dist/src/client.d.ts

@@ -86,19 +86,24 @@ export interface ToolInfo {
  * as `expected_content_sha`; the `update_knowledge` TOOL CASes internally, so a
  * CLI caller never needs to pass it.
  */
-export interface KnowledgeDocDetail {
+/** A doc's metadata, as every listing serves it — no body. */
+export interface KnowledgeDocSummary {
     id: string;
     workspace_id: string;
     name: string;
     description: string;
-    /** Folder address; "" is root. */
-    path: string;
-    content: string;
+    /** How the doc is classified. Order-insensitive; empty means untagged. */
+    tags: string[];
+    /** When the doc was taken out of circulation, or null while it is in use. */
+    hidden_at: string | null;
     content_sha: string | null;
     files: unknown[];
     created_at: string;
     updated_at: string;
 }
+export interface KnowledgeDocDetail extends KnowledgeDocSummary {
+    content: string;
+}
 export interface FileUploadResult {
     files: Array<{
         id: string;
@@ -228,6 +233,24 @@ export declare class LoticsClient {
      * the file-model and legacy parked-column rows. Mirrors GET /v1/knowledge_docs/{id}.
      */
     getKnowledgeDoc(knowledge_doc_id: string): Promise<KnowledgeDocDetail>;
+    /**
+     * Every doc's metadata — REST rather than the `list_knowledge` tool, because
+     * this is the surface a PERSON manages the corpus from and the tool is bound
+     * to what the assistant may browse. That distinction is the whole point of
+     * `include_hidden`: a hidden doc is out of the assistant's corpus by design,
+     * and someone still has to be able to find it in order to put it back.
+     */
+    listKnowledgeDocs(opts?: {
+        includeHidden?: boolean;
+    }): Promise<KnowledgeDocSummary[]>;
+    /** Apply one metadata change to a set of docs. Tags are an add/remove DIFF —
+     *  see the endpoint's own note on why a replacement is the wrong shape here. */
+    bulkUpdateKnowledgeDocs(body: {
+        knowledge_doc_ids: string[];
+        add_tags?: string[];
+        remove_tags?: string[];
+        hidden?: boolean;
+    }): Promise<KnowledgeDocSummary[]>;
     getApp(app_id: string): Promise<{
         id: string;
         name: string;
@@ -1112,4 +1135,15 @@ export declare class LoticsClient {
     uploadFiles(filePaths: string[], options?: {
         filenames?: string[];
     }): Promise<FileUploadResult>;
+    /**
+     * Store files from bytes the caller already holds — the path for a caller that
+     * never had them on disk (an email attachment decoded in memory, a generated
+     * document, a fetched URL). `uploadFiles` is this with a read in front, so
+     * both routes hit one endpoint and one mime-derivation rule.
+     */
+    uploadFileBytes(items: {
+        bytes: Uint8Array<ArrayBuffer>;
+        filename: string;
+        mimeType?: string;
+    }[]): Promise<FileUploadResult>;
 }

package/dist/src/client.js

@@ -199,6 +199,22 @@ export class LoticsClient {
     async getKnowledgeDoc(knowledge_doc_id) {
         return this.request("GET", `/v1/knowledge_docs/${encodeURIComponent(knowledge_doc_id)}`);
     }
+    /**
+     * Every doc's metadata — REST rather than the `list_knowledge` tool, because
+     * this is the surface a PERSON manages the corpus from and the tool is bound
+     * to what the assistant may browse. That distinction is the whole point of
+     * `include_hidden`: a hidden doc is out of the assistant's corpus by design,
+     * and someone still has to be able to find it in order to put it back.
+     */
+    async listKnowledgeDocs(opts) {
+        const qs = opts?.includeHidden ? "?include_hidden=true" : "";
+        return this.request("GET", `/v1/knowledge_docs${qs}`);
+    }
+    /** Apply one metadata change to a set of docs. Tags are an add/remove DIFF —
+     *  see the endpoint's own note on why a replacement is the wrong shape here. */
+    async bulkUpdateKnowledgeDocs(body) {
+        return this.request("PATCH", "/v1/knowledge_docs", body);
+    }
     // --- Apps ---
     async getApp(app_id) {
         return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}`);
@@ -846,14 +862,40 @@ export class LoticsClient {
         }));
     }
     async uploadFiles(filePaths, options) {
-        const formData = new FormData();
+        // Sequential, not `Promise.all`: `lotics upload <dir>` expands a directory to
+        // every file in it, and reading them all at once opens one handle per file —
+        // EMFILE on a large directory. The upload itself is a single request either
+        // way, so concurrency here buys nothing.
+        const items = [];
         for (let i = 0; i < filePaths.length; i++) {
             const absolutePath = path.resolve(filePaths[i]);
-            const buffer = await fs.promises.readFile(absolutePath);
-            const filename = options?.filenames?.[i] ?? path.basename(absolutePath);
-            const mimeType = getMimeType(filename);
-            const blob = new Blob([buffer], { type: mimeType });
-            formData.append("file", blob, filename);
+            items.push({
+                bytes: await fs.promises.readFile(absolutePath),
+                filename: options?.filenames?.[i] ?? path.basename(absolutePath),
+            });
+        }
+        return this.uploadFileBytes(items);
+    }
+    /**
+     * Store files from bytes the caller already holds — the path for a caller that
+     * never had them on disk (an email attachment decoded in memory, a generated
+     * document, a fetched URL). `uploadFiles` is this with a read in front, so
+     * both routes hit one endpoint and one mime-derivation rule.
+     */
+    async uploadFileBytes(
+    // `Uint8Array<ArrayBuffer>`, not a bare `Uint8Array`: `Blob` takes a
+    // `BufferSource`, which excludes a `SharedArrayBuffer`-backed view. Every
+    // real source here (`readFile`, `Buffer.concat`, `response.arrayBuffer()`)
+    // is already ArrayBuffer-backed, so the narrower type states the
+    // requirement rather than casting it away at the call site.
+    items) {
+        const formData = new FormData();
+        for (const item of items) {
+            const mimeType = item.mimeType ?? getMimeType(item.filename);
+            // `Blob` copies a BufferSource by the VIEW's offset+length, so passing a
+            // pooled `Buffer` from `readFile` straight in is correct — no defensive
+            // re-copy, which would double peak memory on every upload.
+            formData.append("file", new Blob([item.bytes], { type: mimeType }), item.filename);
         }
         const url = `${this.baseUrl}/v1/files`;
         const response = await fetch(url, {

package/docs/cli_reference.md

@@ -22,12 +22,14 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics tools <name>` | Full description + JSON Schema for one tool |
 | `lotics run <tool> '<json>'` | Execute a tool (text output via toModelOutput). Args may also come from a file (`lotics run <tool> @args.json`) or piped stdin (`cat args.json \| lotics run <tool>`) — both bypass the OS `ARG_MAX` limit for large payloads (a knowledge-doc `content`, a bulk update). A leading `@` on the args is unambiguously a file path (JSON args start with `{`). |
 | `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |
-| `lotics upload <file\|dir...>` | Upload files/directories via multipart POST to /v1/files |
+| `lotics upload <file\|dir...>` · `--stdin` · `--base64` · `--url <url>` | Upload files/directories via multipart POST to /v1/files. A directory expands to its immediate files; `--as <name>` renames a single upload. **Three alternative byte sources, for a caller that never had the bytes on disk** — an attachment decoded in memory, a generated document, a signed download link — each mutually exclusive with the others and with a path argument: `--stdin` takes raw bytes on stdin, `--base64` takes base64 on stdin (the shape attachments arrive in), `--url <url>` fetches the URL first. `--stdin`/`--base64` REQUIRE `--as`, because stdin carries no filename and the mime type is derived from it; `--url` falls back to `Content-Disposition` then the URL's last path segment. `--base64` decodes STRICTLY — `Buffer.from(s, "base64")` silently skips invalid characters and truncates on bad padding, so a corrupted pipe would otherwise store a short file that only fails when a human opens it. The `--url` fetch happens in the CLI, not the server: the URL comes from the operator running the command, so routing it through the backend would add an SSRF surface to buy what `curl` already does. |
 | `lotics file download <file_id> [-o <dir>]` | (alias `lotics download`) Download a stored file: `GET /v1/files/{id}/signed_url` → fetch the presigned URL, saving under the stored filename (from the response's `Content-Disposition`) into `-o` (a **DIRECTORY** — note this is distinct from `lotics file preview`'s `-o`, which is a FILE path), else cwd. `lotics file download record <record_id> <field_key>` pulls every file on a record's file field. |
-| `lotics knowledge list` | List knowledge docs via the `list_knowledge` tool — a table of id, name, description (`--json` for the raw results array). |
-| `lotics knowledge create --name <n> [--description <d>] (--from <file.md> \| --content <str>)` | Read the body client-side (a file XOR an inline string — exactly one required), then call `create_knowledge` with `{ name, description, content }` (description defaults to `""`). Prints the new id to stdout. Large files ride the POST body fine. |
+| `lotics knowledge list [--include-hidden]` | `GET /v1/knowledge_docs` — a table of id, name, tags, description (`--json` for the docs). **REST, not the `list_knowledge` tool**: the tool answers what the ASSISTANT may browse, and a hidden doc is out of that corpus by definition, so a tool-backed listing could never show one and the person who hid it would have no way back to it. Hidden docs are left out unless `--include-hidden` asks; those rows are marked `(hidden)`. |
+| `lotics knowledge create --name <n> [--description <d>] [--tags <a,b>] (--from <file.md> \| --content <str>)` | Read the body client-side (a file XOR an inline string — exactly one required), then call `create_knowledge` with `{ name, description, content, tags? }` (description defaults to `""`). `--tags` files the doc as it is made, which is the only moment a corpus reliably gets labelled. Prints the new id to stdout. Large files ride the POST body fine. |
 | `lotics knowledge get <id> [-o <file.md>]` | `GET /v1/knowledge_docs/{id}` (`getKnowledgeDoc`) → the doc with its **hydrated `content`** (the one content-read path for a non-sandbox client; works for file-model AND legacy parked-column rows). `-o` writes the body via `writeFileAtomic`; else the body goes to stdout. `--json` prints the full doc instead. |
-| `lotics knowledge update <id> [--from <file.md> \| --content <str>] [--name <n>] [--description <d>]` | Call `update_knowledge` with **only** the provided fields (a body from --from/--content becomes `content`; the tool diffs + CASes the content change internally, so the CLI passes no `expected_content_file_id`). At least one field required; --from and --content are mutually exclusive. |
+| `lotics knowledge update <id> [--from <file.md> \| --content <str>] [--name <n>] [--description <d>] [--tags <a,b>]` | Call `update_knowledge` with **only** the provided fields (a body from --from/--content becomes `content`; the tool diffs + CASes the content change internally, so the CLI passes no `expected_content_file_id`). `--tags` REPLACES the doc's label set — the single-doc form, where the caller is looking at one doc and can state what it should carry. At least one field required; --from and --content are mutually exclusive. |
+| `lotics knowledge tag <id...> [--add <a,b>] [--remove <c,d>]` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, add_tags?, remove_tags? }` — one transaction over the whole set. A **DIFF applied to each doc's own labels**, never a replacement: the docs named on one command line carry different labels, so one array across them would strip whatever the others were filed under. Removal matches case-insensitively; adding a label a doc already carries writes nothing. Ids may be separate arguments or comma-separated. At least one of --add/--remove required. |
+| `lotics knowledge hide <id...>` / `lotics knowledge unhide <id...>` | `PATCH /v1/knowledge_docs` with `{ knowledge_doc_ids, hidden }`. Hiding takes docs out of every **listing** — the Library's list, `list_knowledge`, and the corpus `grep_knowledge` searches — while leaving IAM untouched and keeping them readable **by id** (`read_knowledge` with an id, a code run staging one, an app agent's declared set). So it can never silently break an app that depends on a doc, and unhiding costs nothing. Refuses the no-argument form rather than reading it as "everything". |
 | `lotics knowledge rm <id>` | Archive the doc via `delete_knowledge` (`{ knowledge_doc_id }`). The REST execute path does not gate `needsApproval`, so this runs unattended. |
 | `lotics app create <name> [path]` | Scaffold a Vite+React+TS custom-code app project; POST /v1/apps; npm install; vite build; upload as v1 |
 | `lotics app pull <app_id> [path]` | Download source archive from R2 (presigned), extract, npm install, stamp package.json's `lotics` field. With no `[path]`: refresh the cwd IN PLACE when it's already this app's own project (its manifest `app_id` matches — the documented `cd <app> && lotics app pull` flow), else clone into an `<name>/` subdir. **A pull never overwrites a file that differs from what it is about to write** — it writes only what is ABSENT or already identical, keeps the rest, and reports which files it kept plus the commands that close the gap. The same rule covers `src/workflows/<alias>.ts` and `src/agents/<alias>.md`, so an unpushed body or prompt survives too. Those two are written from the LIVE App row (`apps.workflows` / `apps.agents`), which owns them, and the archive's own copy of them is deliberately SKIPPED on extract: a deploy tars the whole source directory, so the tarball holds a deploy-time snapshot that is stale for anything authored since. The comparison is against the app's own content, not git, so it holds for a project that was never a repo. `--force` takes the app's copy and DISCARDS local edits; there is no other way to lose them. **When a pull ACROSS versions keeps files, the manifest is left on the OLDER of the two versions** — the tree is then part one and part the other, and claiming the newer would make `deploy`'s `prev_version_id` check pass and ship a half-and-half bundle. Older, not "the one it had": `--from-version` pulls a deliberately old revision, so the version it had is the NEWER side, and holding that would match what the server serves and let the old source ship. Either way a deploy from that tree is refused until you reconcile the listed files by hand and pull again, or take the app's copy with `--force`. The report says which version each side is on, because a kept file is your unshipped work when the project was already current and merely the OLD version when it was behind — and nothing in a byte comparison can tell those apart. **`--from-version <apv_…>`** pulls an OLDER revision instead of the current one (`lotics app versions` lists the ids) — point it at a NEW path to read a previous revision without disturbing the project you are in. The manifest records the version actually written, never the live pointer, so a deploy from that checkout is refused by the version guard rather than shipping old source over newer. — `workflows` and `agents` are sourced from the live App row (NOT the archived manifest), so `set_app_workflow` / `set_app_agent` authoring survives the pull. Regenerates `.lotics/app_{workflows,queries,agents}.d.ts` so `useWorkflow` / `useQuery` / `useAgentRun` stay typed, AND — AFTER `npm install`, so `node_modules/@lotics/ui` actually exists to read — `.lotics/react_native.d.ts` (the kit's web-only ViewStyle/TextStyle augmentation) and `.lotics/tsconfig.link.json`'s peer pins; a pulled project's own `tsc` used to fail the moment it used a component relying on the augmentation (Dialog, Picker, TimePicker, …) until `app codegen` was run by hand, because nothing had regenerated either one after install populated node_modules. AND the runtime `.lotics/app_fields.ts` (the same linked-vs-bespoke branch `app codegen` runs, off the app row already fetched — see that row for the two forms). That one is not optional: `app deploy` tars source with `--exclude=.lotics`, so no archive can carry it, and a pulled project whose `src/` imports `F`/`OPT` would fail to build with `Could not resolve "../../.lotics/app_fields"` until `app codegen` was run by hand. The write NAMES the form and the reason, because an in-place pull can FLIP a project between them (`opctl app publish` links an origin, `package eject` unlinks it) and that changes what the module does at load. Skipped under `--view-as` (the schema is read as that member and silently drops tables they cannot see — a narrowed `F` map compiles and then throws at runtime, worse than the missing module). A binding/schema fetch failure is non-fatal and names the right recovery for what is on disk: an existing file is kept, an ABSENT one warns about the build error and points at `app codegen`. Pull GENERATES but never RECONCILES `.lotics/` — deleting a companion whose alias the manifest no longer declares is `app codegen`'s alone, since pull's authority is the server's alias set and a declared-but-not-yet-`set` alias is supported. Also writes one `src/workflows/<alias>.ts` per bound workflow (faithful body from `get_app_workflow`) and one `src/agents/<alias>.md` per bound agent (its instructions, straight off the live row) — so the prose an author actually edits lives in a file, and pull always overwrites it from live, leaving no second copy to drift. A legacy workflow alias with no rendered source, or an agent with no instructions, warns and is skipped. The stamped `lotics.agents` map carries the TYPED half only (`inputs`/`outputs`/`tool_names`/`model_tier`/…) — an agent's prose lives solely in its `.md`, so there is never a second local copy to desync; a stale `instructions` left by an older CLI is inert and disappears on the next pull |

package/docs/knowledge_docs.md

@@ -24,6 +24,7 @@ the doc, the doc is noise.
 ```bash
 lotics knowledge create --name "Shipping tariffs" \
   --description "HS-coded rates; searchable by lane and code" \
+  --tags "HS,nhập khẩu" \        # file it as you make it — see Classifying, below
   --from ./tariffs.md            # the body is a Markdown file; or --content '<inline>'
 ```
 
@@ -143,13 +144,53 @@ lotics knowledge update kdc_... --from ./tariffs.md   # replace the body (--name
 ```
 
 Send only the fields you're changing. `--from` / `--content` replaces the body; `--name` /
-`--description` change metadata. `update_knowledge` resolves concurrency **internally** — it
+`--description` / `--tags` change metadata. `update_knowledge` resolves concurrency **internally** — it
 re-reads the current content pointer and version-chains the new body — so there is no version
 token to pass from the CLI. (The chat agent may instead send an `edits` array — anchored
 replace / insert / append — for a surgical change; see `lotics tools update_knowledge`.) Refine
 structure as you learn what users actually ask: add the synonym that failed to match, split a
 line that was too coarse, restate a term the heading was carrying.
 
+## Classifying a corpus — tags
+
+A doc carries a SET of labels, not a folder. Order does not matter, a doc can wear several, and
+the vocabulary is whatever the docs themselves use — a tag stops existing the moment nothing
+carries it.
+
+```bash
+lotics knowledge update kdc_... --tags "HS,nhập khẩu"    # ONE doc: state its complete set
+lotics knowledge tag kdc_a kdc_b --add HS --remove draft # MANY docs: a diff applied to each
+```
+
+The split is deliberate. Looking at one doc you know what it should carry, so `--tags` replaces.
+Across a set you do not — the docs carry different labels — so `tag` adds and removes against
+each doc's own set, and never states one classification for all of them. Removal ignores case;
+adding a label a doc already carries changes nothing.
+
+An agent narrows by tag rather than reading the whole corpus:
+
+```bash
+lotics tools list_knowledge   # takes an optional tag
+lotics tools grep_knowledge   # same
+```
+
+## Taking a doc out of circulation — `hide`
+
+```bash
+lotics knowledge hide kdc_...              # superseded, draft, source material
+lotics knowledge list --include-hidden     # find it again
+lotics knowledge unhide kdc_...            # put it back
+```
+
+A hidden doc is out of every **listing**: it is gone from the Library's list, from
+`list_knowledge`, and from the corpus `grep_knowledge` searches, so nothing finds it by browsing.
+It is not deleted, not unshared, and still **reads when addressed by id** — `read_knowledge` with
+its id, a code run staging it, an app agent that declares it. That is the point: hiding is a
+statement about discovery, so it cannot silently break an app that depends on a doc by name.
+
+Reach for it instead of `rm` whenever the material still matters: last year's tariff schedule, a
+handbook a newer one replaced, the raw source a curated doc was written from.
+
 ## Package-managed knowledge
 
 A knowledge doc can also be delivered as part of a **content package** — a versioned corpus of
@@ -161,12 +202,15 @@ same either way; the package layer just manages distribution and version pinning
 ## Reaching the tools
 
 ```bash
-lotics knowledge list                   # catalog: id, name, description
+lotics knowledge list                   # catalog: id, name, tags, description
 lotics knowledge get kdc_... -o doc.md  # read a body to a file (omit -o for stdout)
 lotics tools update_knowledge           # full input schema for any knowledge tool
 ```
 
 The Knowledge category covers `list_knowledge`, `create_knowledge`, `update_knowledge`, and
-`delete_knowledge` — fronted by the `lotics knowledge list | create | get | update | rm`
-commands. Sharing a doc to other members is `share_resource` / `unshare_resource` (category
+`delete_knowledge` — fronted by the `lotics knowledge list | create | get | update | tag | hide |
+unhide | rm` commands, and reachable over MCP as well, so a corpus can be authored from whichever
+surface you already work in. `list`, `tag`, `hide` and `unhide` go over REST rather than a tool, because
+they are a person's view of the corpus: the tools answer what the ASSISTANT may browse, and a
+hidden doc is out of that set by definition. Sharing a doc to other members is `share_resource` / `unshare_resource` (category
 **Admin**).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.150.2",
+  "version": "0.152.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {