@lotics/cli 0.91.2 → 0.92.0

package/README.md

@@ -20,7 +20,7 @@ package (reachable at `node_modules/@lotics/cli/docs/*.md` once installed):
   create → generate → chain lifecycle, and the marker capabilities.
 - [`docs/knowledge_docs.md`](docs/knowledge_docs.md) — the AI's rulebook layer: authoring the
   workspace facts an agent can't guess, the access-vs-activation model, and the
-  search → grep → read retrieval funnel agents use to pull only the lines they need.
+  catalog-then-stage retrieval model agents use to pull only the lines they need.
 
 Both point to `lotics tools <name>` for exact input schemas.
 
@@ -164,6 +164,22 @@ Edits mutate the file in place via an atomic temp-file + rename. Unknown OOXML c
 
 Run `lotics xlsx` or `lotics docx` with no subcommand for the full list.
 
+## Knowledge docs
+
+A file-native surface over the workspace's knowledge docs — the AI's rulebook layer. The body is a Markdown file: `create`/`update` read it from your filesystem, `get` writes it back. See [`docs/knowledge_docs.md`](docs/knowledge_docs.md) for the model.
+
+```bash
+lotics knowledge list                                         # catalog: id, name, description (--json)
+lotics knowledge create --name "Shipping tariffs" \
+  --description "HS-coded rates; searchable by lane and code" \
+  --from ./tariffs.md                                         # or --content '<inline>'; prints the new id
+lotics knowledge get kdc_... -o ./tariffs.md                  # body → file (omit -o for stdout; --json = full doc)
+lotics knowledge update kdc_... --from ./tariffs.md           # send only what changed (--name / --description too)
+lotics knowledge rm kdc_...                                   # archive
+```
+
+`create` / `update` send the body inline; the server mints and version-chains the content file (and `update` diffs + resolves concurrency internally — no token to pass). `get` is the one content-read path, hydrating the body server-side.
+
 ## Custom-code apps
 
 ```bash

package/dist/src/cli.js

@@ -22135,7 +22135,7 @@ var require_lib2 = __commonJS({
       }
       if (this.state !== PENDING) {
         var resolver = this.state === FULFILLED ? onFulfilled : onRejected;
-        unwrap(promise2, resolver, this.outcome);
+        unwrap2(promise2, resolver, this.outcome);
       } else {
         this.queue.push(new QueueItem(promise2, onFulfilled, onRejected));
       }
@@ -22156,15 +22156,15 @@ var require_lib2 = __commonJS({
       handlers.resolve(this.promise, value);
     };
     QueueItem.prototype.otherCallFulfilled = function(value) {
-      unwrap(this.promise, this.onFulfilled, value);
+      unwrap2(this.promise, this.onFulfilled, value);
     };
     QueueItem.prototype.callRejected = function(value) {
       handlers.reject(this.promise, value);
     };
     QueueItem.prototype.otherCallRejected = function(value) {
-      unwrap(this.promise, this.onRejected, value);
+      unwrap2(this.promise, this.onRejected, value);
     };
-    function unwrap(promise2, func, value) {
+    function unwrap2(promise2, func, value) {
       immediate(function() {
         var returnValue;
         try {
@@ -29585,7 +29585,7 @@ var require_lib3 = __commonJS({
 // src/cli.ts
 import dns from "node:dns";
 import net2 from "node:net";
-import fs8 from "node:fs";
+import fs9 from "node:fs";
 import path7 from "node:path";
 import readline from "node:readline";
 
@@ -29750,6 +29750,16 @@ var LoticsClient = class {
     }
     return this.request("POST", "/v1/tools/execute", body);
   }
+  // --- Knowledge docs ---
+  /**
+   * Fetch one knowledge doc with its hydrated `content` — the single content-read
+   * path for a non-sandbox client (the `list_knowledge` tool returns metadata
+   * only, and the sandbox-staging read path is unavailable here). Works for both
+   * the file-model and legacy parked-column rows. Mirrors GET /v1/knowledge_docs/{id}.
+   */
+  async getKnowledgeDoc(knowledge_doc_id) {
+    return this.request("GET", `/v1/knowledge_docs/${encodeURIComponent(knowledge_doc_id)}`);
+  }
   // --- Apps ---
   async getApp(app_id) {
     return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}`);
@@ -33876,6 +33886,9 @@ function parseArgs(argv) {
     viewAs: void 0,
     uiSrc: void 0,
     name: void 0,
+    description: void 0,
+    from: void 0,
+    content: void 0,
     timezone: void 0,
     message: void 0,
     local: false,
@@ -33923,6 +33936,15 @@ function parseArgs(argv) {
       case "--name":
         flags.name = argv[++i2];
         break;
+      case "--description":
+        flags.description = argv[++i2];
+        break;
+      case "--from":
+        flags.from = argv[++i2];
+        break;
+      case "--content":
+        flags.content = argv[++i2];
+        break;
       case "--timezone":
         flags.timezone = argv[++i2];
         break;
@@ -67828,6 +67850,148 @@ async function runDocxCommand(subcommand, toolArgs, restArgs) {
   }
 }
 
+// src/knowledge.ts
+import fs8 from "node:fs";
+function readBodyFile(filePath) {
+  if (!fs8.existsSync(filePath)) fail(`File not found: ${filePath}`);
+  return fs8.readFileSync(filePath, "utf-8");
+}
+function resolveBody(flags, required2) {
+  if (flags.from !== void 0 && flags.content !== void 0) {
+    fail("Pass either --from <file> or --content <str>, not both.");
+  }
+  if (flags.from !== void 0) return readBodyFile(flags.from);
+  if (flags.content !== void 0) return flags.content;
+  if (required2) fail("A body is required \u2014 pass --from <file.md> or --content <str>.");
+  return void 0;
+}
+function unwrap(res) {
+  if (res.error) fail(res.error);
+  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 : [];
+  if (flags.json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+  if (results.length === 0) {
+    console.error("No knowledge docs in this workspace.");
+    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 wId = Math.max("ID".length, ...rows.map((r) => r.id.length));
+  const wName = Math.max("NAME".length, ...rows.map((r) => r.name.length));
+  const pad = (s, n) => s.padEnd(n);
+  console.log(`${pad("ID", wId)}  ${pad("NAME", wName)}  DESCRIPTION`);
+  for (const r of rows) {
+    console.log(`${pad(r.id, wId)}  ${pad(r.name, wName)}  ${r.description}`.trimEnd());
+  }
+}
+async function knowledgeCreate(client, flags) {
+  const name = flags.name;
+  if (!name) fail("Usage: lotics knowledge create --name <name> [--description <d>] (--from <file.md> | --content <str>)");
+  const content = resolveBody(flags, true);
+  const result = unwrap(
+    await client.execute("create_knowledge", {
+      name,
+      // The tool requires a description (empty string is accepted); the CLI
+      // treats it as optional and defaults to "".
+      description: flags.description ?? "",
+      content
+    })
+  );
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const doc = result;
+  const id = typeof doc.id === "string" ? doc.id : "";
+  console.error(`Created knowledge doc: ${typeof doc.name === "string" ? doc.name : name} (${id})`);
+  console.log(id);
+}
+async function knowledgeGet(client, id, flags) {
+  if (!id) fail("Usage: lotics knowledge get <id> [-o <file.md>]");
+  const doc = await client.getKnowledgeDoc(id);
+  if (flags.output) {
+    writeFileAtomic(flags.output, Buffer.from(doc.content, "utf-8"));
+    return;
+  }
+  if (flags.json) {
+    console.log(JSON.stringify(doc, null, 2));
+    return;
+  }
+  console.log(doc.content);
+}
+async function knowledgeUpdate(client, id, flags) {
+  if (!id) fail("Usage: lotics knowledge update <id> [--from <file.md> | --content <str>] [--name <n>] [--description <d>]");
+  const content = resolveBody(flags, false);
+  if (content === void 0 && flags.name === void 0 && flags.description === void 0) {
+    fail("Nothing to update. Pass at least one of --from/--content, --name, or --description.");
+  }
+  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;
+  const result = unwrap(await client.execute("update_knowledge", args));
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.error(`Updated knowledge doc: ${id}`);
+}
+async function knowledgeRm(client, id, flags) {
+  if (!id) fail("Usage: lotics knowledge rm <id>");
+  const result = unwrap(await client.execute("delete_knowledge", { knowledge_doc_id: id }));
+  if (flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.error(`Deleted knowledge doc: ${id}`);
+}
+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]
+      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 rm <id> [--json]
+      Archive a doc.`);
+}
+async function runKnowledgeCommand(client, subcommand, toolArgs, flags) {
+  switch (subcommand) {
+    case "list":
+      return knowledgeList(client, flags);
+    case "create":
+      return knowledgeCreate(client, flags);
+    case "get":
+      return knowledgeGet(client, toolArgs, flags);
+    case "update":
+      return knowledgeUpdate(client, toolArgs, flags);
+    case "rm":
+      return knowledgeRm(client, toolArgs, flags);
+    default:
+      if (subcommand) fail(`Unknown knowledge subcommand: ${subcommand}`);
+      printKnowledgeHelp();
+      return;
+  }
+}
+
 // src/preview.ts
 import { spawn as spawn3 } from "node:child_process";
 import { createServer } from "node:http";
@@ -68099,6 +68263,16 @@ COMMANDS
   lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
   lotics app rename "<new name>"       Rename the app's display name (launcher title)
   lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
+  lotics knowledge list                List knowledge docs (id, name, description)
+  lotics knowledge create --name <n> [--description <d>] --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 rm <id>             Archive a doc
   lotics ui link <component> [--ui-src <path>] [--remove]
                                        Dev-link @lotics/ui to packages/ui/src (Vite alias
                                        + tsc paths) for live HMR + typecheck. Monorepo apps
@@ -68359,9 +68533,9 @@ function resolveUploadPaths(rawPaths) {
   const result = [];
   for (const p of rawPaths) {
     const resolved = path7.resolve(p);
-    const stat = fs8.statSync(resolved);
+    const stat = fs9.statSync(resolved);
     if (stat.isDirectory()) {
-      const entries = fs8.readdirSync(resolved, { withFileTypes: true });
+      const entries = fs9.readdirSync(resolved, { withFileTypes: true });
       for (const entry of entries) {
         if (entry.isFile()) {
           result.push(path7.join(resolved, entry.name));
@@ -68573,7 +68747,7 @@ async function main() {
     }
     return;
   }
-  if (command !== "tools" && command !== "upload" && command !== "run" && command !== "download" && command !== "workspace" && command !== "app") {
+  if (command !== "tools" && command !== "upload" && command !== "run" && command !== "download" && command !== "workspace" && command !== "app" && command !== "knowledge") {
     console.error(`Unknown command: ${command}`);
     console.error('Run "lotics --help" for usage.');
     process.exit(1);
@@ -68734,6 +68908,10 @@ Available workspaces:`);
     return;
   }
   await resolveWorkspace(client, ctx);
+  if (command === "knowledge") {
+    await runKnowledgeCommand(client, subcommand, toolArgs, flags);
+    return;
+  }
   if (command === "app") {
     if (subcommand === "create") {
       const name = toolArgs;
@@ -68813,7 +68991,7 @@ Available workspaces:`);
         const ingested = await ingestJsonArgs({
           rawArg: restArgs[1],
           stdinIsTTY: process.stdin.isTTY ?? false,
-          readFile: (p) => fs8.readFileSync(p, "utf-8"),
+          readFile: (p) => fs9.readFileSync(p, "utf-8"),
           readStdin
         });
         if (ingested.kind === "error") {
@@ -68965,7 +69143,7 @@ ${JSON.stringify(info.input_schema, null, 2)}`);
     const ingested = await ingestJsonArgs({
       rawArg: toolArgs,
       stdinIsTTY: process.stdin.isTTY ?? false,
-      readFile: (p) => fs8.readFileSync(p, "utf-8"),
+      readFile: (p) => fs9.readFileSync(p, "utf-8"),
       readStdin
     });
     if (ingested.kind === "error") {

package/dist/src/client.d.ts

@@ -55,6 +55,25 @@ export interface ToolInfo {
     description: string;
     input_schema: unknown;
 }
+/**
+ * A single knowledge doc with its HYDRATED body — the shape of
+ * `GET /v1/knowledge_docs/{id}`. `content` is resolved server-side from the
+ * doc's content file (or the parked column for a legacy row), so this is the
+ * one content-read path a non-sandbox client has. `content_file_id` is the
+ * concurrency token the REST PATCH echoes; the `update_knowledge` TOOL CASes
+ * internally, so a CLI caller never needs to pass it.
+ */
+export interface KnowledgeDocDetail {
+    id: string;
+    workspace_id: string;
+    name: string;
+    description: string;
+    content: string;
+    content_file_id: string | null;
+    files: unknown[];
+    created_at: string;
+    updated_at: string;
+}
 export interface FileUploadResult {
     files: Array<{
         id: string;
@@ -142,6 +161,13 @@ export declare class LoticsClient {
         format?: "json" | "text";
         timeoutMs?: number;
     }): Promise<ToolExecuteResult>;
+    /**
+     * Fetch one knowledge doc with its hydrated `content` — the single content-read
+     * path for a non-sandbox client (the `list_knowledge` tool returns metadata
+     * only, and the sandbox-staging read path is unavailable here). Works for both
+     * the file-model and legacy parked-column rows. Mirrors GET /v1/knowledge_docs/{id}.
+     */
+    getKnowledgeDoc(knowledge_doc_id: string): Promise<KnowledgeDocDetail>;
     getApp(app_id: string): Promise<{
         id: string;
         name: string;

package/dist/src/client.js

@@ -187,6 +187,16 @@ export class LoticsClient {
         }
         return this.request("POST", "/v1/tools/execute", body);
     }
+    // --- Knowledge docs ---
+    /**
+     * Fetch one knowledge doc with its hydrated `content` — the single content-read
+     * path for a non-sandbox client (the `list_knowledge` tool returns metadata
+     * only, and the sandbox-staging read path is unavailable here). Works for both
+     * the file-model and legacy parked-column rows. Mirrors GET /v1/knowledge_docs/{id}.
+     */
+    async getKnowledgeDoc(knowledge_doc_id) {
+        return this.request("GET", `/v1/knowledge_docs/${encodeURIComponent(knowledge_doc_id)}`);
+    }
     // --- Apps ---
     async getApp(app_id) {
         return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}`);

package/docs/knowledge_docs.md

@@ -21,13 +21,17 @@ names, exceptions, and policies. Do **not** put in it general skills the model a
 the doc, the doc is noise. A knowledge doc earns its place only by carrying external facts
 tied to your workspace.
 
-## Creating a doc — `create_knowledge`
+## Creating a doc — `lotics knowledge create`
 
 ```bash
-lotics run create_knowledge @doc.json      # content is large → read from a file or stdin
+lotics knowledge create --name "Shipping tariffs" \
+  --description "HS-coded rates; searchable by lane and code" \
+  --from ./tariffs.md            # the body is a Markdown file; or --content '<inline>'
 ```
 
-`create_knowledge` takes three things:
+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:
 
 - `name` — what it is.
 - `description` — what the doc is **and how to retrieve from it**: its vocabulary, synonyms for
@@ -57,40 +61,42 @@ So: shared + active → the agent can find and read it. Shared but deactivated
 that member's agent. This is the token economy in action — activation is how a member curates
 which rulebooks their agent carries.
 
-## How an agent uses a doc — the retrieval funnel
+## How an agent uses a doc — catalog, then read
 
-The agent narrows from "which doc" to "which lines" in three steps. All four tools respect
-access + activation, so they only ever surface docs the caller may use.
+Docs are not injected wholesale. The agent finds the right doc from a **catalog**, then reads
+only what it needs. Both steps respect access + activation, so only docs the caller may use ever
+surface.
 
-1. **Find the doc** — `search_knowledge` (keyword query → matching docs + a snippet) or
-   `query_knowledge` (list every active doc). Returns *docs*, not the lines inside them.
-2. **Locate lines within one doc** — `grep_knowledge` (regex over the lines of a single doc,
-   returns matches with line numbers). Matching is **diacritics-insensitive by default** — a
-   plain-ASCII query matches accented Vietnamese text — and can be case-insensitive too.
-3. **Read the section** — `read_knowledge`. Pass `outline: true` first to get the Markdown
-   header map (a table of contents with line numbers), then read a section with `offset` (the
-   1-based first line) + `limit` (line count). A large doc never returns whole; reads are
-   line-numbered and paged.
+1. **Catalog** — `list_knowledge` returns every usable doc as `{ id, name, description }` — no
+   bodies. This is why the *description* carries the weight: it is what the agent reads before
+   deciding to open a doc. Write it to sell the doc — its vocabulary, the colloquial synonyms an
+   ambiguous query would use, and what it covers.
+2. **Read** — the chat agent stages the chosen doc's content file into a code run and greps it
+   there (the body arrives as a file to `cat`/`grep`). Over this CLI you read a body directly
+   with `lotics knowledge get <id>`.
 
-The whole point of the funnel is that the agent lands on the exact section that answers the
-question without ever loading the rest. Structure your content so it works:
+Structure your content so a reader lands on the answer without loading the rest:
 
-- Organize under clear Markdown headers, so the doc can be outlined and read by section.
+- Organize under clear Markdown headers.
 - Keep each searchable unit self-contained — a section for prose, **one record per line** for
   dense/tabular data (a price row, a code entry) — carrying both the terms someone would search
   for and its answer.
 - Lead with the most-queried fields.
 - Note colloquial synonyms next to official terms, so an ambiguous query still matches.
 
-## Updating a doc — `update_knowledge`
+## Updating a doc — `lotics knowledge update`
 
-Send only the fields you're changing. Content edits are **diffs**, not a full rewrite: pass an
-`edits` array (replace / insert / append operations) plus the `expected_version` you got from
-`read_knowledge` (optimistic concurrency — a stale version is rejected). Over the CLI, the default
-`read_knowledge` text output omits the version — read `current_version` from `lotics run read_knowledge … --json`.
-Refine structure as you
-learn what users actually ask: add the synonym that failed to match, split the section that was
-too coarse to grep. See `lotics tools update_knowledge` for the edit shape.
+```bash
+lotics knowledge update kdc_... --from ./tariffs.md   # replace the body (--name / --description too)
+```
+
+Send only the fields you're changing. `--from` / `--content` replaces the body; `--name` /
+`--description` 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 the
+section that was too coarse to read.
 
 ## Package-managed knowledge
 
@@ -103,12 +109,12 @@ same either way; the package layer just manages distribution and version pinning
 ## Reaching the tools
 
 ```bash
-lotics tools                        # all categories (knowledge tools are under "Knowledge")
-lotics tools grep_knowledge         # one tool: full description + input schema
-lotics run create_knowledge @doc.json
-echo '{"query":"tariff"}' | lotics run search_knowledge
+lotics knowledge list                   # catalog: id, name, 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 `create_knowledge`, `update_knowledge`, `query_knowledge`,
-`search_knowledge`, `grep_knowledge`, `read_knowledge`, and `delete_knowledge`. Sharing a doc
-to other members is `share_resource` / `unshare_resource` (category **Admin**).
+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
+**Admin**).

package/package.json

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