@lotics/cli 0.91.2 → 0.93.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
@@ -201,6 +217,14 @@ lotics app workflow set issueInvoice        # push the edited src/workflows/issu
 # authoritative, so the next `app deploy` re-syncs it — keep the manifest current.
 lotics app query set openInvoices           # push package.json#lotics.queries.openInvoices
 
+# Run a bound app agent end-to-end (no deployed UI needed — app row + declaration
+# + member auth). Streams progress to stderr; reports the SETTLED run (structured
+# output / final text) to stdout; exits 0 only when the run completed.
+lotics app agent run app_abc recognize '{"image_file_id":"fil_..."}'
+cat input.json | lotics app agent run app_abc recognize        # inputs via stdin/@file
+lotics app agent run app_abc recognize --json                  # full run summary to stdout
+lotics app agent run app_abc recognize --session cli-123 '{}'  # continue an existing thread
+
 # Dev-link @lotics/ui to packages/ui/src for live HMR (Vite alias; deploy bundles it)
 lotics ui link card                        # monorepo: packages/ui/src found automatically
 lotics ui link card --ui-src /abs/monorepo/packages/ui/src   # external app (e.g. ~/lotics_apps)

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)}`);
@@ -30214,6 +30224,18 @@ var LoticsClient = class {
     if (!res.ok) await this.throwResponseError(res);
     return res;
   }
+  /**
+   * A session's app-agent run history, oldest-first (the run just started is the
+   * last, and its exact id is on the stream response's `x-app-agent-run-id`
+   * header). Transcript excluded; structured `output`/`input` included. Mirrors
+   * GET /v1/apps/{app_id}/agent-runs.
+   */
+  async listAgentRuns(app_id, session_id) {
+    return this.request(
+      "GET",
+      `/v1/apps/${encodeURIComponent(app_id)}/agent-runs?session_id=${encodeURIComponent(session_id)}`
+    );
+  }
   /**
    * Mint a presigned URL for uploading a file into an app. Mirrors
    * POST /v1/apps/{app_id}/files/upload-url.
@@ -30545,6 +30567,16 @@ function upsertProfile(orgId, fields) {
     latest_version: config2.latest_version
   });
 }
+function clearProfileWorkspace(orgId) {
+  const config2 = loadGlobalConfig();
+  const existing = config2?.profiles?.[orgId];
+  if (!existing) return;
+  const { workspace_id: _dropped, ...rest } = existing;
+  saveGlobalConfig({
+    ...config2,
+    profiles: { ...config2.profiles, [orgId]: { ...rest } }
+  });
+}
 function removeProfile(orgId) {
   const config2 = loadGlobalConfig();
   if (!config2?.profiles?.[orgId]) return;
@@ -30643,6 +30675,7 @@ var VERSION = pkg.version;
 import fs4 from "node:fs";
 import path5 from "node:path";
 import { spawn as spawn2 } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { tmpdir } from "node:os";
 
 // src/starter_template.ts
@@ -33650,6 +33683,96 @@ async function appExecuteWorkflow(client, args) {
   }
   if (status === "error" || cleanupFailed) process.exit(1);
 }
+async function streamAgentTextDeltas(body, onText) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let accumulated = "";
+  try {
+    for (; ; ) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      const frames = buffer.split("\n\n");
+      buffer = frames.pop() ?? "";
+      for (const frame of frames) {
+        for (const line of frame.split("\n")) {
+          if (!line.startsWith("data:")) continue;
+          const payload = line.slice(5).trim();
+          if (!payload || payload === "[DONE]") continue;
+          let chunk;
+          try {
+            chunk = JSON.parse(payload);
+          } catch {
+            continue;
+          }
+          if (chunk.type === "text-delta" && chunk.delta) {
+            accumulated += chunk.delta;
+            onText(chunk.delta);
+          }
+        }
+      }
+    }
+  } catch {
+  } finally {
+    reader.releaseLock();
+  }
+  return accumulated;
+}
+var AGENT_RUN_POLL = {
+  intervalMs: 1e3,
+  settleTimeoutMs: 21 * 60 * 1e3,
+  existenceTimeoutMs: 5e3
+};
+var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+async function fetchSettledAgentRun(client, appId, sessionId, runId, timing) {
+  const settleDeadline = Date.now() + timing.settleTimeoutMs;
+  const existenceDeadline = Date.now() + timing.existenceTimeoutMs;
+  for (; ; ) {
+    const { runs } = await client.listAgentRuns(appId, sessionId);
+    const target = runId ? runs.find((r) => r.id === runId) : runs[runs.length - 1];
+    if (target) {
+      if (target.status !== "running" || Date.now() >= settleDeadline) return target;
+    } else if (Date.now() >= existenceDeadline) {
+      return void 0;
+    }
+    await sleep(timing.intervalMs);
+  }
+}
+async function appAgentRun(client, args, timing = AGENT_RUN_POLL) {
+  const sessionId = args.sessionId ?? `cli-${randomUUID()}`;
+  const continuing = args.sessionId !== void 0;
+  const res = await client.appAgentRunStream(args.app_id, args.alias, {
+    session_id: sessionId,
+    input: args.input
+  });
+  const runId = res.headers.get("x-app-agent-run-id") ?? void 0;
+  if (res.body) {
+    await streamAgentTextDeltas(res.body, (piece) => process.stderr.write(piece));
+  }
+  const run = await fetchSettledAgentRun(client, args.app_id, sessionId, runId, timing);
+  if (!run) {
+    console.error(`
+Could not find the settled run for session ${sessionId} on ${args.app_id}.`);
+    console.error("The run may still be in progress \u2014 re-check with `lotics run` against the app's agent-runs.");
+    process.exit(1);
+  }
+  if (args.json) {
+    console.log(JSON.stringify(run, null, 2));
+  } else if (run.output !== null && typeof run.output === "object") {
+    console.log(JSON.stringify(run.output, null, 2));
+  } else if (typeof run.output === "string") {
+    console.log(run.output);
+  }
+  console.error(
+    `
+Agent "${args.alias}" run ${run.id} \u2192 ${run.status}${run.error_message ? `: ${run.error_message}` : ""}`
+  );
+  console.error(
+    continuing ? `Session: ${sessionId}` : `Session: ${sessionId}  (fresh \u2014 pass --session ${sessionId} to continue this thread)`
+  );
+  if (run.status !== "completed") process.exit(1);
+}
 async function appWorkflowSet(client, args) {
   const projectDir = process.cwd();
   const meta3 = readAppMeta(projectDir);
@@ -33876,8 +33999,12 @@ 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,
+    session: void 0,
     local: false,
     all: false,
     yes: false,
@@ -33923,6 +34050,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;
@@ -33930,6 +34066,9 @@ function parseArgs(argv) {
       case "--message":
         flags.message = argv[++i2];
         break;
+      case "--session":
+        flags.session = argv[++i2];
+        break;
       case "--local":
         flags.local = true;
         break;
@@ -34000,6 +34139,36 @@ async function ingestJsonArgs(opts) {
   }
 }
 
+// src/org_commands.ts
+function printWorkspaceList(workspaces, currentId) {
+  for (const ws of workspaces) {
+    const marker = ws.id === currentId ? " (current)" : "";
+    console.error(`  ${ws.id}  ${ws.name}  ${ws.timezone}  ${ws.default_currency}${marker}`);
+  }
+}
+async function validateOrgWorkspacePin(client, orgId, profile) {
+  const pinned = profile.workspace_id;
+  if (!pinned) return;
+  let workspaces;
+  try {
+    workspaces = await client.listWorkspaces();
+  } catch (error51) {
+    const message = error51 instanceof Error ? error51.message : String(error51);
+    console.error(`Could not validate the pinned workspace (${message}) \u2014 keeping ${pinned}.`);
+    return;
+  }
+  if (workspaces.some((w) => w.id === pinned)) return;
+  clearProfileWorkspace(orgId);
+  console.error(`Pinned workspace ${pinned} is no longer in ${profile.org_name} \u2014 cleared the stale pin.`);
+  if (workspaces.length === 0) {
+    console.error("This organization has no workspaces yet.");
+    return;
+  }
+  console.error("Select one with:\n");
+  console.error("  lotics workspace select <id>\n");
+  printWorkspaceList(workspaces);
+}
+
 // src/xlsx.ts
 import fs6 from "node:fs";
 
@@ -67828,6 +67997,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";
@@ -67835,7 +68146,7 @@ import { readFileSync as readFileSync2, writeFileSync, existsSync, mkdtempSync,
 import { tmpdir as tmpdir2 } from "node:os";
 import { join, dirname, resolve, extname, basename } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
-import { setTimeout as sleep } from "node:timers/promises";
+import { setTimeout as sleep2 } from "node:timers/promises";
 var HERE = dirname(fileURLToPath2(import.meta.url));
 function fail2(msg) {
   console.error(msg);
@@ -67961,7 +68272,7 @@ async function runPreviewCommand(filePath, flags) {
         const p = parseInt(readFileSync2(portFile, "utf8").split("\n")[0], 10);
         if (p) cdpPort = p;
       }
-      if (!cdpPort) await sleep(100);
+      if (!cdpPort) await sleep2(100);
     }
     if (!cdpPort) throw new Error("Chrome did not expose a debugging port (launch failed?).");
     let target;
@@ -67971,7 +68282,7 @@ async function runPreviewCommand(filePath, flags) {
         target = list.find((t) => t.type === "page");
       } catch {
       }
-      if (!target?.webSocketDebuggerUrl) await sleep(100);
+      if (!target?.webSocketDebuggerUrl) await sleep2(100);
     }
     if (!target?.webSocketDebuggerUrl) throw new Error("No Chrome page target available.");
     const cdp = await cdpConnect(target.webSocketDebuggerUrl);
@@ -67993,7 +68304,7 @@ async function runPreviewCommand(filePath, flags) {
         if (v.warnings?.length) warnings.push(...v.warnings);
         break;
       }
-      await sleep(75);
+      await sleep2(75);
     }
     if (!done) throw new Error("Render timed out (page never signaled completion).");
     if (err2) throw new Error(`Render engine error: ${err2}`);
@@ -68096,9 +68407,23 @@ COMMANDS
   lotics app query set <alias>         Push package.json#lotics.queries.<alias> to
                                        apps.queries via set_app_query (no deploy;
                                        re-synced by the next deploy from the manifest)
+  lotics app agent run <app_id> <alias> '<json>'  Run a bound app agent end-to-end
+                                       (inputs: inline JSON, @file, or stdin; streams
+                                        progress to stderr, reports the settled run;
+                                        --session <id> continues a thread; --json)
   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
@@ -68321,12 +68646,6 @@ var SOURCE_LABELS = {
   local_pointer: "local .lotics/config.json (pin)",
   global_profile: "global active profile"
 };
-function printWorkspaceList(workspaces, currentId) {
-  for (const ws of workspaces) {
-    const marker = ws.id === currentId ? " (current)" : "";
-    console.error(`  ${ws.id}  ${ws.name}  ${ws.timezone}  ${ws.default_currency}${marker}`);
-  }
-}
 async function resolveWorkspace(client, ctx) {
   if (ctx.workspaceId) {
     client.setWorkspaceId(ctx.workspaceId);
@@ -68359,9 +68678,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));
@@ -68541,6 +68860,7 @@ async function main() {
           console.error("Note: a local pin (.lotics/config.json) overrides the global default in this directory. Use --local to change the pin here.");
         }
       }
+      await validateOrgWorkspacePin(new LoticsClient({ apiKey: profile.api_key }), orgId, profile);
       return;
     }
     if (subcommand && subcommand !== "list") {
@@ -68573,7 +68893,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);
@@ -68590,6 +68910,7 @@ async function main() {
     console.error("  lotics app workflow pull                  Rewrite src/workflows/*.ts from the server");
     console.error("  lotics app workflow check [alias]         Typecheck src/workflows bodies locally");
     console.error("  lotics app query set <alias>              Push lotics.queries.<alias> to apps.queries (no deploy)");
+    console.error("  lotics app agent run <app_id> <alias> '<json>'  Run a bound app agent (streams progress, reports the settled run)");
     console.error("  lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address");
     console.error(`  lotics app rename "<new name>"        Rename the app's display name (launcher title)`);
     console.error("  lotics app dev [path]                Run the app locally with HMR + RPC forwarding");
@@ -68734,6 +69055,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 +69138,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") {
@@ -68844,6 +69169,42 @@ Available workspaces:`);
       }
       workflowUsage();
     }
+    if (subcommand === "agent") {
+      const action = toolArgs;
+      const agentUsage = () => {
+        console.error("Usage: lotics app agent run <app_id> <alias> ['<json>'|@inputs.json|stdin] [--session <id>] [--json]");
+        console.error("       cat inputs.json | lotics app agent run <app_id> <alias>   (read inputs from stdin)");
+        console.error("Streams the run's progress to stderr; reports the settled run (structured output / text) to stdout.");
+        console.error("--session <id> continues an existing thread; omitted mints a fresh session per run.");
+        process.exit(1);
+      };
+      if (action === "run") {
+        const appId = restArgs[0];
+        const alias = restArgs[1];
+        if (!appId || !alias) {
+          agentUsage();
+        }
+        const ingested = await ingestJsonArgs({
+          rawArg: restArgs[2],
+          stdinIsTTY: process.stdin.isTTY ?? false,
+          readFile: (p) => fs9.readFileSync(p, "utf-8"),
+          readStdin
+        });
+        if (ingested.kind === "error") {
+          console.error(ingested.message);
+          process.exit(1);
+        }
+        await appAgentRun(client, {
+          app_id: appId,
+          alias,
+          input: ingested.args,
+          sessionId: flags.session,
+          json: flags.json
+        });
+        return;
+      }
+      agentUsage();
+    }
     if (subcommand === "query") {
       const action = toolArgs;
       if (action === "set") {
@@ -68965,7 +69326,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

@@ -50,11 +50,55 @@ export interface ToolExecuteResult {
     model_output?: string;
     error?: string;
 }
+/**
+ * A settled (or in-flight) app-agent run, the transcript-excluded projection
+ * `GET /v1/apps/{app_id}/agent-runs` returns. `output` is the STRUCTURED result
+ * for a typed agent (an object) or the final text for a free-text agent (a
+ * string); `status` is `running` until the run settles to `completed` / `error`
+ * / `aborted`. The authoritative record `lotics app agent run` reports from
+ * (never the stream).
+ */
+export interface AppAgentRunSummary {
+    id: string;
+    app_id: string;
+    agent_alias: string;
+    session_id: string;
+    status: string;
+    input: Record<string, unknown> | null;
+    output: string | Record<string, unknown> | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    } | null;
+    error_message: string | null;
+    triggered_by_member_id: string | null;
+    started_at: string;
+    completed_at: string | null;
+}
 export interface ToolInfo {
     name: string;
     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 +186,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;
@@ -848,6 +899,15 @@ export declare class LoticsClient {
         session_id: string;
         input: Record<string, unknown>;
     }, signal?: AbortSignal): Promise<Response>;
+    /**
+     * A session's app-agent run history, oldest-first (the run just started is the
+     * last, and its exact id is on the stream response's `x-app-agent-run-id`
+     * header). Transcript excluded; structured `output`/`input` included. Mirrors
+     * GET /v1/apps/{app_id}/agent-runs.
+     */
+    listAgentRuns(app_id: string, session_id: string): Promise<{
+        runs: AppAgentRunSummary[];
+    }>;
     /**
      * Mint a presigned URL for uploading a file into an app. Mirrors
      * POST /v1/apps/{app_id}/files/upload-url.

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)}`);
@@ -619,6 +629,15 @@ export class LoticsClient {
             await this.throwResponseError(res);
         return res;
     }
+    /**
+     * A session's app-agent run history, oldest-first (the run just started is the
+     * last, and its exact id is on the stream response's `x-app-agent-run-id`
+     * header). Transcript excluded; structured `output`/`input` included. Mirrors
+     * GET /v1/apps/{app_id}/agent-runs.
+     */
+    async listAgentRuns(app_id, session_id) {
+        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/agent-runs?session_id=${encodeURIComponent(session_id)}`);
+    }
     /**
      * Mint a presigned URL for uploading a file into an app. Mirrors
      * POST /v1/apps/{app_id}/files/upload-url.

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.93.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {