@lotics/cli 0.151.0 → 0.152.1

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)}`);
@@ -45993,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"
     ]
   },
@@ -74491,6 +74516,9 @@ ${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,
@@ -74509,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,
@@ -74579,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;
@@ -102516,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");
@@ -102534,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", {
@@ -102572,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) {
@@ -102598,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));
@@ -102623,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);
@@ -102647,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:
@@ -103677,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") {

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;

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)}`);

package/docs/cli_reference.md

@@ -24,10 +24,12 @@ Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. S
 | `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |
 | `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,23 +24,30 @@ 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>'
 ```
 
 This reads the body from your filesystem and creates the doc through `create_knowledge`
 (prints the new id). A raw `lotics run create_knowledge @doc.json` works too — read a large
-`content` from a file or stdin. Either way, `create_knowledge` takes three things:
+`content` from a file or stdin. `create_knowledge` takes five fields, three of them required:
 
-- `name` — what it is.
+- `name` — what it is. Just the name: **grouping belongs in `tags`, not in a prefix baked into
+  every title.**
 - `description` — what the doc is **and what to grep it for**: its vocabulary and the synonyms
   an ambiguous query would use. Surfaced in the tree before any body is read, and truncated at
   200 characters. See *Write for grep* below.
 - `content` — Markdown.
+- `tags` *(optional)* — the labels someone would filter by, e.g. `["Hồ sơ NOXH", "Khoản 13"]`.
+  Give **every** one that is true of the doc, not just the main one — a corpus is narrowed by
+  intersecting tags, so a doc carrying one label can only ever be found down one path. On
+  `update_knowledge` the array **replaces** what is stored, so resend the labels it should keep.
+- `files` *(optional)* — file ids of the source `.docx`/`.pdf`/`.xlsx` the doc was built from,
+  stored alongside it so a reader can open the original. The body stays the searchable text.
 
 A new doc is created **owned by you, active in your own agent context, and private** — no one
-else can see it yet. (The tool itself takes only name/description/content; attaching files to a
-doc and changing its default-active state are done through the web app / REST surface, not this
-tool.)
+else can see it yet. Changing a doc's default-active state is done through the web app / REST
+surface, not this tool.
 
 ## Access vs. activation — both are required
 
@@ -143,13 +150,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 +208,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.151.0",
+  "version": "0.152.1",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {