@lotics/cli 0.98.0 → 0.100.0

package/AGENTS.md

@@ -0,0 +1,61 @@
+# @lotics/cli — agent index
+
+The model an agent needs before driving this CLI: which surface answers which question, what the
+conventions are, and where the traps are. It deliberately does **not** list commands — `lotics --help`
+is generated from the code and is the only always-current inventory.
+
+| Read | For |
+|---|---|
+| `lotics --help` | The verb inventory (§ COMMANDS) and global flags. Authoritative; never stale. |
+| `lotics tools` · `lotics tools <name>` | The agent tool registry and one tool's full JSON Schema. |
+| [docs/cli_reference.md](./docs/cli_reference.md) | Per-command contracts, flags, exit codes, and gotchas — the detail `--help` compresses. Read it before hand-building a `set_app_*` payload: several tools REPLACE rather than patch, and a CLI verb already owns the safe assembly. |
+| [docs/document_templates.md](./docs/document_templates.md) | Generating PDF/Excel/Word/email from reusable templates. |
+| [docs/knowledge_docs.md](./docs/knowledge_docs.md) | Authoring the workspace facts an agent can't guess; access-vs-activation; catalog-then-stage retrieval. |
+| [README.md](./README.md) | Install, auth, and worked examples. |
+
+## Two surfaces, and the trap between them
+
+**`lotics tools` is not the CLI's capability list.** There are two disjoint surfaces:
+
+- **Tools** (`lotics tools`, `lotics run <tool>`) — the *agent tool registry*: what an agent, workflow,
+  or automation may call. Workspace data, templates, knowledge, admin.
+- **Commands** (`lotics --help` § COMMANDS) — the CLI's *own verbs*. Auth and org/workspace scoping,
+  file upload/download/preview, local `.xlsx`/`.docx` authoring, and the whole custom-code app loop
+  (scaffold, pull, deploy, codegen, dev, and running a bound workflow or agent end to end).
+
+Several capabilities exist **only** as commands and appear nowhere in `lotics tools` — downloading a
+file and running a bound app agent are the two that most often get mistaken for missing. Concluding
+"the platform can't do X" from the tool list alone is a mistake; check both.
+
+⚠️ **`lotics <subcommand> --help` prints the generic top-level help.** It does not describe the
+subcommand, so an unhelpful response there is *not* evidence the subcommand is absent. To find out
+whether something exists, read `lotics --help` § COMMANDS — the whole section, not a narrow grep.
+
+## Conventions that hold across every command
+
+- **Scope is resolved per invocation.** `LOTICS_ORG` / `LOTICS_WORKSPACE` (or `LOTICS_API_KEY`) scope a
+  single call without changing the active org or a directory pin — the safe way to touch one tenant
+  from a shell serving many. Every command echoes its resolved target to **stderr** (`lotics → <org> /
+  <workspace>`); read it back before trusting a write. Resolution precedence is in README § Organizations.
+- **Large payloads bypass `ARG_MAX`** — `lotics run <tool> @args.json` or piped stdin. A leading `@` is
+  unambiguously a file path (JSON args start with `{`). The same ingest applies to `app workflow run`
+  and `app agent run`.
+- **stdout is the payload, stderr is the narration.** Progress, status lines, and the target echo go to
+  stderr; the result goes to stdout, so piping stays clean. `--json` switches stdout from the
+  agent-readable summary to the full structured object.
+- **Exit codes are assertable.** A command that runs remote work exits non-zero when that work failed —
+  `app workflow run` on `status:"error"`, `app agent run` on any settled status other than `completed`,
+  `workspace doctor` on findings. Scripts can gate on them.
+- **Text output is the default and is built for reading**; reach for `--json` only when a field is
+  needed programmatically.
+
+## Where this CLI is not the answer
+
+- **Authoring a binding via `app deploy`.** Deploy ships code, queries, and capabilities — it never
+  authors bindings. Workflow bodies go through `app workflow set`, agent instructions through
+  `app agent set` (both edit a file on disk that `app pull` wrote from the live row). A binding's TYPED
+  half — an agent's `tool_names`/`inputs`/`outputs`, a workflow's schemas — is authored by the
+  `set_app_*` tools. A manifest alias with no server binding only fails at the app's first call, so
+  deploy warns about the mismatch.
+- **OAuth connections.** Attaching a connected account is web-only; the CLI can list them.
+- **Anything needing a browser.** `app dev` and `file preview` shell out to a local Chrome.

package/README.md

@@ -12,6 +12,11 @@ Lotics is an AI-powered operations platform. Through this CLI you can:
 
 ## Capability guides
 
+**Driving this CLI from an agent? Start at [AGENTS.md](./AGENTS.md)** (`node_modules/@lotics/cli/AGENTS.md`)
+— which surface answers which question, the conventions that hold across every command, and the traps.
+Per-command contracts, flags, exit codes and gotchas are in
+[docs/cli_reference.md](./docs/cli_reference.md); `lotics --help` is the always-current verb list.
+
 Two of the platform's primary surfaces have dedicated usage guides that ship inside this
 package (reachable at `node_modules/@lotics/cli/docs/*.md` once installed):
 

package/dist/src/cli.js

@@ -44758,6 +44758,20 @@ var LoticsClient = class {
   async setAppQuery(app_id, alias, declaration) {
     return this.execute("set_app_query", { app_id, alias, declaration });
   }
+  /**
+   * Bind (create or replace) an app agent by alias via the `set_app_agent` tool
+   * — the deploy-free authoring path for `apps.agents`, parallel to
+   * `setAppWorkflow`/`setAppQuery`.
+   *
+   * `set_app_agent` REPLACES the whole declaration, so this takes the whole
+   * declaration. `lotics app agent set` is the caller that assembles it (prose
+   * from `src/agents/<alias>.md`, typed fields from the manifest) precisely so
+   * no caller has to remember that a partial payload silently drops
+   * `instructions`, `outputs` and the model pin.
+   */
+  async setAppAgent(app_id, alias, declaration) {
+    return this.execute("set_app_agent", { app_id, alias, ...declaration });
+  }
   /**
    * Fetch one app workflow's faithful source + bound input/output schemas via
    * `get_app_workflow`. `source` is the JS-subset body re-rendered from the
@@ -64486,6 +64500,9 @@ var queryOutputColumnSchema = zod_default.object({
   ),
   source_field_key: zod_default.string().optional().describe(
     "Source field this column originates from. Populated alongside source_table_id for passthrough columns."
+  ),
+  computed: zod_default.boolean().optional().describe(
+    "True when the value is DERIVED rather than a passthrough of the addressed field \u2014 a link extraction reads a field on the link TARGET, so the row's own source record is a different table. Such a column may still carry source addressing (it is what resolves labels and option sets), but that addressing is NOT a write target: writable_target is refused on a computed column and on anything that passes one through."
   )
 });
 var queryOutputSchemaSchema = zod_default.object({
@@ -70074,8 +70091,14 @@ async function fetchLatestNpmVersion(packageName) {
     return null;
   }
 }
+function toManifestAgents(agents) {
+  return Object.fromEntries(
+    Object.entries(agents).map(([alias, { instructions: _prose, ...typed }]) => [alias, typed])
+  );
+}
 var WORKFLOWS_DIR = path5.join("src", "workflows");
 var WORKFLOW_GLOBALS_DIR = path5.join(".lotics", "workflows");
+var AGENTS_DIR = path5.join("src", "agents");
 var WORKFLOW_TSCONFIG_EXCLUDES = ["src/workflows", ".lotics/workflows"];
 var LOTICS_INCLUDE_GLOB = ".lotics/**/*";
 var STALE_LOTICS_INCLUDES = /* @__PURE__ */ new Set([".lotics", "./.lotics", ".lotics/"]);
@@ -70123,6 +70146,39 @@ ${envelope.prefix}${body}${envelope.suffix}
 `);
   return file2;
 }
+function agentFilePath(projectDir, alias) {
+  return path5.join(projectDir, AGENTS_DIR, `${alias}.md`);
+}
+function agentFileHeader(alias) {
+  return `<!-- lotics: instructions for agent "${alias}".
+     Pulled from the LIVE app row; edit here, then: lotics app agent set ${alias}
+     The typed fields (inputs/outputs/tool_names/model_id) live in package.json#lotics.agents.${alias} -->`;
+}
+function stripAgentHeader(text) {
+  return text.replace(/<!--\s*lotics:[\s\S]*?-->\n?/g, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+function writeAgentFile(projectDir, alias, instructions) {
+  fs4.mkdirSync(path5.join(projectDir, AGENTS_DIR), { recursive: true });
+  const file2 = agentFilePath(projectDir, alias);
+  fs4.writeFileSync(file2, `${agentFileHeader(alias)}
+
+${instructions.replace(/\s+$/, "")}
+`);
+  return file2;
+}
+function writeAgentFiles(projectDir, agents) {
+  const written = [];
+  for (const [alias, declaration] of Object.entries(agents)) {
+    const instructions = declaration.instructions;
+    if (typeof instructions !== "string" || instructions.trim() === "") {
+      console.error(`\u26A0 Skipped src/agents/${alias}.md \u2014 the live declaration carries no instructions.`);
+      continue;
+    }
+    writeAgentFile(projectDir, alias, instructions);
+    written.push(alias);
+  }
+  return written;
+}
 async function writeWorkflowFiles(client, projectDir, app_id, workflows) {
   const written = [];
   for (const [alias, declaration] of Object.entries(workflows)) {
@@ -70425,9 +70481,15 @@ function stampPulledManifest(projectDir, args) {
     version_number: args.version_number,
     workflows: args.workflows,
     queries: args.queries,
-    agents: args.agents
+    // The prose is stripped here and only here: `args.agents` is the LIVE map
+    // (its instructions feed `writeAgentFiles`), the manifest gets the typed half.
+    agents: toManifestAgents(args.agents)
+  });
+  writeAppDts(projectDir, {
+    workflows: args.workflows,
+    queries: args.queries,
+    agents: toManifestAgents(args.agents)
   });
-  writeAppDts(projectDir, { workflows: args.workflows, queries: args.queries, agents: args.agents });
 }
 async function downloadToFile(url2, destPath) {
   const response = await fetch(url2);
@@ -70588,6 +70650,15 @@ async function appPull(client, args) {
       );
     }
   }
+  const agents = app.agents ?? {};
+  if (Object.keys(agents).length > 0) {
+    const written = writeAgentFiles(targetPath, agents);
+    if (written.length > 0) {
+      console.error(
+        `Wrote ${written.length} agent instruction ${written.length === 1 ? "file" : "files"} to ${AGENTS_DIR}/ (${written.join(", ")})`
+      );
+    }
+  }
   console.error(`Installing npm dependencies...`);
   await runNpm(["install"], targetPath);
   console.error(`
@@ -70949,6 +71020,40 @@ Agent "${args.alias}" run ${run.id} \u2192 ${run.status}${run.error_message ? `:
   );
   if (run.status !== "completed") process.exit(1);
 }
+async function appAgentSet(client, args) {
+  const projectDir = process.cwd();
+  const meta3 = readAppMeta(projectDir);
+  const app = await client.getApp(meta3.app_id);
+  const live = app.agents?.[args.alias];
+  if (!live) {
+    console.error(
+      `App ${meta3.app_id} has no bound agent "${args.alias}". Bind it first (set_app_agent), then 'lotics app pull' to write its instructions.`
+    );
+    process.exit(1);
+  }
+  const file2 = agentFilePath(projectDir, args.alias);
+  if (!fs4.existsSync(file2)) {
+    console.error(
+      `No instructions at ${path5.relative(projectDir, file2)}. Run 'lotics app pull ${meta3.app_id}' to write ${AGENTS_DIR}/${args.alias}.md, then edit it.`
+    );
+    process.exit(1);
+  }
+  const instructions = stripAgentHeader(fs4.readFileSync(file2, "utf-8"));
+  if (instructions === "") {
+    console.error(
+      `${path5.relative(projectDir, file2)} is empty after stripping the header \u2014 refusing to push an empty prompt.`
+    );
+    process.exit(1);
+  }
+  const res = await client.setAppAgent(meta3.app_id, args.alias, { ...live, instructions });
+  if (res.error) {
+    console.error(`Failed to set agent "${args.alias}": ${res.error}`);
+    process.exit(1);
+  }
+  console.error(
+    `Set agent "${args.alias}" (${instructions.length} chars of instructions` + (live.model_id ? `, ${live.model_id}` : "") + `). Typed fields taken from the live row.`
+  );
+}
 async function appWorkflowSet(client, args) {
   const projectDir = process.cwd();
   const meta3 = readAppMeta(projectDir);
@@ -89375,13 +89480,184 @@ var formattingSchema = external_exports.object({
   superscript: external_exports.boolean().optional(),
   subscript: external_exports.boolean().optional(),
   all_caps: external_exports.boolean().optional(),
-  small_caps: external_exports.boolean().optional()
+  small_caps: external_exports.boolean().optional(),
+  language: external_exports.object({
+    value: external_exports.string().optional().describe("Latin-script proofing language, e.g. vi-VN"),
+    east_asia: external_exports.string().optional(),
+    bidi: external_exports.string().optional()
+  }).optional().describe(
+    "Proofing language (`w:lang`). Changes nothing about how the run renders \u2014 it selects the dictionary Word spell-checks it against, so a value written into a form keeps the form's own language instead of inheriting the label's"
+  )
 });
 var runSchema = external_exports.object({
   text: external_exports.string(),
   formatting: formattingSchema.optional()
 });
 
+// ../ooxml/src/queries.ts
+function getBodyElementType(el) {
+  const tag = getTagName(el);
+  if (tag === "w:p") return "paragraph";
+  if (tag === "w:tbl") return "table";
+  return "other";
+}
+function extractParagraphText(el) {
+  const tag = getTagName(el);
+  if (tag !== "w:p") return "";
+  const parts = [];
+  for (const child of getChildren(el)) {
+    const childTag = getTagName(child);
+    if (childTag === "w:r") {
+      for (const runChild of getChildren(child)) {
+        if (getTagName(runChild) === "w:t") {
+          parts.push(getTextContent(runChild));
+        }
+      }
+    } else if (childTag === "w:hyperlink") {
+      for (const hlChild of getChildren(child)) {
+        if (getTagName(hlChild) === "w:r") {
+          for (const runChild of getChildren(hlChild)) {
+            if (getTagName(runChild) === "w:t") {
+              parts.push(getTextContent(runChild));
+            }
+          }
+        }
+      }
+    }
+  }
+  return parts.join("");
+}
+function getRunsFromParagraph(el) {
+  const runs = [];
+  for (const child of getChildren(el)) {
+    if (getTagName(child) !== "w:r") continue;
+    let text = "";
+    let hasText = false;
+    for (const grandchild of getChildren(child)) {
+      if (getTagName(grandchild) !== "w:t") continue;
+      hasText = true;
+      for (const tn of getChildren(grandchild)) {
+        if (typeof tn["#text"] === "string") text += tn["#text"];
+      }
+    }
+    if (hasText) runs.push({ element: child, text });
+  }
+  return runs;
+}
+function writeRunText(runElement, newText) {
+  const children = getChildren(runElement);
+  const textNode = { "w:t": [{ "#text": newText }], ":@": { "@_xml:space": "preserve" } };
+  const indices = children.flatMap((c, i2) => getTagName(c) === "w:t" ? [i2] : []);
+  if (indices.length === 0) {
+    children.push(textNode);
+    return;
+  }
+  children[indices[0]] = textNode;
+  for (let i2 = indices.length - 1; i2 >= 1; i2--) children.splice(indices[i2], 1);
+}
+function setRunText(run, newText) {
+  writeRunText(run.element, newText);
+  run.text = newText;
+}
+function computeReplacementRanges(text, query, replacement, matchType, maxReplacements, startCount) {
+  const ranges = [];
+  let count = startCount;
+  if (matchType === "exact") {
+    if (text === query && count < maxReplacements) {
+      ranges.push({ start: 0, end: text.length, replacement });
+      count++;
+    }
+    return { ranges, count };
+  }
+  if (matchType === "regex") {
+    const re2 = new RegExp(query, "gi");
+    let match2;
+    while (count < maxReplacements && (match2 = re2.exec(text)) !== null) {
+      ranges.push({ start: match2.index, end: match2.index + match2[0].length, replacement });
+      count++;
+      if (match2[0].length === 0) re2.lastIndex++;
+    }
+    return { ranges, count };
+  }
+  if (query.length === 0) return { ranges, count };
+  const lower2 = text.toLowerCase();
+  const lowerQuery = query.toLowerCase();
+  let searchFrom = 0;
+  while (count < maxReplacements) {
+    const idx = lower2.indexOf(lowerQuery, searchFrom);
+    if (idx === -1) break;
+    ranges.push({ start: idx, end: idx + query.length, replacement });
+    searchFrom = idx + query.length;
+    count++;
+  }
+  return { ranges, count };
+}
+function applyRangeReplacements(runs, ranges) {
+  if (ranges.length === 0) return;
+  const bounds = [];
+  let offset = 0;
+  for (const run of runs) {
+    bounds.push({ run, start: offset, end: offset + run.text.length });
+    offset += run.text.length;
+  }
+  const joined = runs.map((r) => r.text).join("");
+  const sorted = [...ranges].sort((a, b) => a.start - b.start);
+  for (const { run, start: runStart, end: runEnd } of bounds) {
+    let next = "";
+    let cursor = runStart;
+    for (const range2 of sorted) {
+      if (range2.end <= runStart || range2.start >= runEnd) continue;
+      const keepUntil = Math.min(range2.start, runEnd);
+      const from = Math.max(cursor, runStart);
+      if (keepUntil > from) next += joined.slice(from, keepUntil);
+      if (runStart <= range2.start && range2.start < runEnd) next += range2.replacement;
+      cursor = Math.max(cursor, range2.end);
+    }
+    const tail = Math.max(cursor, runStart);
+    if (runEnd > tail) next += joined.slice(tail, runEnd);
+    if (next !== run.text) setRunText(run, next);
+  }
+}
+function replaceInParagraph(el, query, replacement, matchType, maxReplacements, replacementsMade) {
+  if (!extractParagraphText(el)) return replacementsMade;
+  const runs = getRunsFromParagraph(el);
+  if (runs.length === 0) return replacementsMade;
+  const text = runs.length === 1 ? runs[0].text : runs.map((r) => r.text).join("");
+  const { ranges, count } = computeReplacementRanges(text, query, replacement, matchType, maxReplacements, replacementsMade);
+  applyRangeReplacements(runs, ranges);
+  return count;
+}
+function replaceText(bodyElements, query, replacement, matchType = "contains", maxReplacements = Infinity) {
+  if (matchType === "regex") {
+    try {
+      new RegExp(query);
+    } catch {
+      throw new Error(`Invalid regex pattern: ${query}`);
+    }
+  }
+  let replacementsMade = 0;
+  for (let i2 = 0; i2 < bodyElements.length && replacementsMade < maxReplacements; i2++) {
+    const el = bodyElements[i2];
+    const type = getBodyElementType(el);
+    if (type === "paragraph") {
+      replacementsMade = replaceInParagraph(el, query, replacement, matchType, maxReplacements, replacementsMade);
+    } else if (type === "table") {
+      for (const child of getChildren(el)) {
+        if (getTagName(child) !== "w:tr") continue;
+        for (const cell of getChildren(child)) {
+          if (getTagName(cell) !== "w:tc") continue;
+          for (const p of getChildren(cell)) {
+            if (getTagName(p) === "w:p" && replacementsMade < maxReplacements) {
+              replacementsMade = replaceInParagraph(p, query, replacement, matchType, maxReplacements, replacementsMade);
+            }
+          }
+        }
+      }
+    }
+  }
+  return replacementsMade;
+}
+
 // ../ooxml/src/sections.ts
 var PAGE_SIZES = {
   letter: { w: 12240, h: 15840 },
@@ -90377,170 +90653,6 @@ async function ensureContentTypeOverride(doc, partName, contentType) {
   doc.zip.file("[Content_Types].xml", updated);
 }
 
-// ../ooxml/src/queries.ts
-function getBodyElementType(el) {
-  const tag = getTagName(el);
-  if (tag === "w:p") return "paragraph";
-  if (tag === "w:tbl") return "table";
-  return "other";
-}
-function extractParagraphText(el) {
-  const tag = getTagName(el);
-  if (tag !== "w:p") return "";
-  const parts = [];
-  for (const child of getChildren(el)) {
-    const childTag = getTagName(child);
-    if (childTag === "w:r") {
-      for (const runChild of getChildren(child)) {
-        if (getTagName(runChild) === "w:t") {
-          parts.push(getTextContent(runChild));
-        }
-      }
-    } else if (childTag === "w:hyperlink") {
-      for (const hlChild of getChildren(child)) {
-        if (getTagName(hlChild) === "w:r") {
-          for (const runChild of getChildren(hlChild)) {
-            if (getTagName(runChild) === "w:t") {
-              parts.push(getTextContent(runChild));
-            }
-          }
-        }
-      }
-    }
-  }
-  return parts.join("");
-}
-function getRunsFromParagraph(el) {
-  const runs = [];
-  for (const child of getChildren(el)) {
-    if (getTagName(child) !== "w:r") continue;
-    let text = "";
-    let textIdx = -1;
-    const children = getChildren(child);
-    for (let i2 = 0; i2 < children.length; i2++) {
-      if (getTagName(children[i2]) === "w:t") {
-        const tChildren = getChildren(children[i2]);
-        for (const tn of tChildren) {
-          if (typeof tn["#text"] === "string") {
-            text += tn["#text"];
-          }
-        }
-        textIdx = i2;
-      }
-    }
-    if (textIdx >= 0) {
-      runs.push({ element: child, text, textNodeIndex: textIdx });
-    }
-  }
-  return runs;
-}
-function setRunText(run, newText) {
-  const children = getChildren(run.element);
-  children[run.textNodeIndex] = {
-    "w:t": [{ "#text": newText }],
-    ":@": { "@_xml:space": "preserve" }
-  };
-  run.text = newText;
-}
-function computeReplacementRanges(text, query, replacement, matchType, maxReplacements, startCount) {
-  const ranges = [];
-  let count = startCount;
-  if (matchType === "exact") {
-    if (text === query && count < maxReplacements) {
-      ranges.push({ start: 0, end: text.length, replacement });
-      count++;
-    }
-    return { ranges, count };
-  }
-  if (matchType === "regex") {
-    const re2 = new RegExp(query, "gi");
-    let match2;
-    while (count < maxReplacements && (match2 = re2.exec(text)) !== null) {
-      ranges.push({ start: match2.index, end: match2.index + match2[0].length, replacement });
-      count++;
-      if (match2[0].length === 0) re2.lastIndex++;
-    }
-    return { ranges, count };
-  }
-  if (query.length === 0) return { ranges, count };
-  const lower2 = text.toLowerCase();
-  const lowerQuery = query.toLowerCase();
-  let searchFrom = 0;
-  while (count < maxReplacements) {
-    const idx = lower2.indexOf(lowerQuery, searchFrom);
-    if (idx === -1) break;
-    ranges.push({ start: idx, end: idx + query.length, replacement });
-    searchFrom = idx + query.length;
-    count++;
-  }
-  return { ranges, count };
-}
-function applyRangeReplacements(runs, ranges) {
-  if (ranges.length === 0) return;
-  const bounds = [];
-  let offset = 0;
-  for (const run of runs) {
-    bounds.push({ run, start: offset, end: offset + run.text.length });
-    offset += run.text.length;
-  }
-  const joined = runs.map((r) => r.text).join("");
-  const sorted = [...ranges].sort((a, b) => a.start - b.start);
-  for (const { run, start: runStart, end: runEnd } of bounds) {
-    let next = "";
-    let cursor = runStart;
-    for (const range2 of sorted) {
-      if (range2.end <= runStart || range2.start >= runEnd) continue;
-      const keepUntil = Math.min(range2.start, runEnd);
-      const from = Math.max(cursor, runStart);
-      if (keepUntil > from) next += joined.slice(from, keepUntil);
-      if (runStart <= range2.start && range2.start < runEnd) next += range2.replacement;
-      cursor = Math.max(cursor, range2.end);
-    }
-    const tail = Math.max(cursor, runStart);
-    if (runEnd > tail) next += joined.slice(tail, runEnd);
-    if (next !== run.text) setRunText(run, next);
-  }
-}
-function replaceInParagraph(el, query, replacement, matchType, maxReplacements, replacementsMade) {
-  if (!extractParagraphText(el)) return replacementsMade;
-  const runs = getRunsFromParagraph(el);
-  if (runs.length === 0) return replacementsMade;
-  const text = runs.length === 1 ? runs[0].text : runs.map((r) => r.text).join("");
-  const { ranges, count } = computeReplacementRanges(text, query, replacement, matchType, maxReplacements, replacementsMade);
-  applyRangeReplacements(runs, ranges);
-  return count;
-}
-function replaceText(bodyElements, query, replacement, matchType = "contains", maxReplacements = Infinity) {
-  if (matchType === "regex") {
-    try {
-      new RegExp(query);
-    } catch {
-      throw new Error(`Invalid regex pattern: ${query}`);
-    }
-  }
-  let replacementsMade = 0;
-  for (let i2 = 0; i2 < bodyElements.length && replacementsMade < maxReplacements; i2++) {
-    const el = bodyElements[i2];
-    const type = getBodyElementType(el);
-    if (type === "paragraph") {
-      replacementsMade = replaceInParagraph(el, query, replacement, matchType, maxReplacements, replacementsMade);
-    } else if (type === "table") {
-      for (const child of getChildren(el)) {
-        if (getTagName(child) !== "w:tr") continue;
-        for (const cell of getChildren(child)) {
-          if (getTagName(cell) !== "w:tc") continue;
-          for (const p of getChildren(cell)) {
-            if (getTagName(p) === "w:p" && replacementsMade < maxReplacements) {
-              replacementsMade = replaceInParagraph(p, query, replacement, matchType, maxReplacements, replacementsMade);
-            }
-          }
-        }
-      }
-    }
-  }
-  return replacementsMade;
-}
-
 // ../docx/src/parse/parser.ts
 var import_jszip2 = __toESM(require_lib4(), 1);
 async function parseDocx(buffer) {
@@ -91680,6 +91792,10 @@ COMMANDS
                                        (inputs: inline JSON, @file, or stdin; streams
                                         progress to stderr, reports the settled run;
                                         --session <id> continues a thread; --json)
+  lotics app agent set <alias>         Push the edited src/agents/<alias>.md instructions
+                                       + the manifest's typed fields through set_app_agent
+                                       (set_app_agent REPLACES the declaration \u2014 this
+                                        sends it whole so nothing is silently dropped)
   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)
@@ -92495,6 +92611,8 @@ Available workspaces:`);
         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.");
+        console.error("");
+        console.error("       lotics app agent set <alias>   Push src/agents/<alias>.md back through set_app_agent");
         process.exit(1);
       };
       if (action === "run") {
@@ -92522,6 +92640,16 @@ Available workspaces:`);
         });
         return;
       }
+      if (action === "set") {
+        const alias = restArgs[0];
+        if (!alias) {
+          console.error("Usage: lotics app agent set <alias>");
+          console.error("       Edits src/agents/<alias>.md (written by 'lotics app pull').");
+          process.exit(1);
+        }
+        await appAgentSet(client, { alias });
+        return;
+      }
       agentUsage();
     }
     if (subcommand === "query") {

package/dist/src/client.d.ts

@@ -867,6 +867,24 @@ export declare class LoticsClient {
         ast: unknown;
         params?: Record<string, unknown>;
     }): Promise<ToolExecuteResult>;
+    /**
+     * Bind (create or replace) an app agent by alias via the `set_app_agent` tool
+     * — the deploy-free authoring path for `apps.agents`, parallel to
+     * `setAppWorkflow`/`setAppQuery`.
+     *
+     * `set_app_agent` REPLACES the whole declaration, so this takes the whole
+     * declaration. `lotics app agent set` is the caller that assembles it (prose
+     * from `src/agents/<alias>.md`, typed fields from the manifest) precisely so
+     * no caller has to remember that a partial payload silently drops
+     * `instructions`, `outputs` and the model pin.
+     */
+    setAppAgent(app_id: string, alias: string, 
+    /** The WHOLE declaration. Typed loosely on purpose: the caller builds it by
+     *  spreading the live one, so a field the server adds later is forwarded
+     *  without this signature (or the caller) having to learn about it. */
+    declaration: Record<string, unknown> & {
+        instructions: string;
+    }): Promise<ToolExecuteResult>;
     /**
      * Fetch one app workflow's faithful source + bound input/output schemas via
      * `get_app_workflow`. `source` is the JS-subset body re-rendered from the

package/dist/src/client.js

@@ -560,6 +560,24 @@ export class LoticsClient {
     async setAppQuery(app_id, alias, declaration) {
         return this.execute("set_app_query", { app_id, alias, declaration });
     }
+    /**
+     * Bind (create or replace) an app agent by alias via the `set_app_agent` tool
+     * — the deploy-free authoring path for `apps.agents`, parallel to
+     * `setAppWorkflow`/`setAppQuery`.
+     *
+     * `set_app_agent` REPLACES the whole declaration, so this takes the whole
+     * declaration. `lotics app agent set` is the caller that assembles it (prose
+     * from `src/agents/<alias>.md`, typed fields from the manifest) precisely so
+     * no caller has to remember that a partial payload silently drops
+     * `instructions`, `outputs` and the model pin.
+     */
+    async setAppAgent(app_id, alias, 
+    /** The WHOLE declaration. Typed loosely on purpose: the caller builds it by
+     *  spreading the live one, so a field the server adds later is forwarded
+     *  without this signature (or the caller) having to learn about it. */
+    declaration) {
+        return this.execute("set_app_agent", { app_id, alias, ...declaration });
+    }
     /**
      * Fetch one app workflow's faithful source + bound input/output schemas via
      * `get_app_workflow`. `source` is the JS-subset body re-rendered from the

package/docs/cli_reference.md

@@ -0,0 +1,50 @@
+# @lotics/cli — CLI Command Reference
+
+Per-command syntax, flags, contracts, and gotchas for the public `lotics` CLI. Start at [AGENTS.md](../AGENTS.md) for the model this reference assumes; `lotics --help` is the authoritative, always-current verb list.
+
+| Command | What it does |
+|---|---|
+| `lotics` / `lotics --help` | Show full help with capabilities, tool categories, workflow |
+| `lotics auth signup <email>` | Create account + org + API key, sends magic link email. Registers the new org as a profile; `--local` pins this directory to it (pointer) instead of setting the global default. |
+| `lotics auth api-key [key]` | `whoami` → **upsert** the key's org as a profile in the global store (never overwrites). `--local` additionally pins this directory to it (pointer) instead of setting the global default. |
+| `lotics auth web` | Send a magic link email to access the web app (requires auth) |
+| `lotics auth whoami` | Print active account name, email, org, resolved workspace, and the resolution **source** (flag/env/local/app-manifest/global). `--json` adds `workspace_id` + `source`. |
+| `lotics auth logout [<name\|id>]` | In a pinned dir: delete the local pin. Else: remove one profile (default the active org). `--all`: wipe the global store. |
+| `lotics org` | List saved orgs (profiles) from the global store, marks active for this directory (a local pin wins over the global default). |
+| `lotics org use <name\|id> [--local]` | Switch the active org by org name (case-insensitive, ambiguous → error) or id. No flag → global `active_org`; `--local` → a `.lotics/config.json` pointer in the current dir. |
+| `lotics workspace` | List workspaces in the active org, marks current with `(current)` |
+| `lotics workspace select <id>` | Set the workspace in the **active scope** — a local pin if the dir has one, else the active org's global profile |
+| `lotics workspace create <name>` | Create a new workspace (admin only), auto-switches to it. |
+| `lotics workspace delete <id> --yes` | Delete a workspace by id (admin only). **Soft delete** — `archived_at` is set, so it drops out of listings and can no longer be selected (the workspace middleware resolves `x-workspace-id` through `getById`, which excludes archived rows, so its tables/records/etc. go dark), while the data is retained and recoverable. Its **apps are cascade-archived** too — every app entry point (embedded, public link, standalone subdomain) resolves its workspace from the app row via `getApp`/`getBySubdomain` (gated only on the app's own `archived_at`), bypassing the middleware, so without the cascade a deleted workspace's apps would keep serving/mutating data (incl. anonymous public links). Refuses the org's **only** active workspace (400) and any workspace outside the caller's org (404). Requires `--yes` to confirm (destructive; the CLI is used non-interactively). |
+| `lotics workspace doctor` | Report workspace-wide dangling schema references via `GET /v1/workspaces/dangling-references` — every active app/workflow artifact whose prefixed schema id no longer resolves, printed as `<referent.kind> "<name>" (<id>) → <namespace> <id> (missing)`; healthy prints a one-line all-clear. **Exits non-zero (exit 1) on findings** so scripts can gate on it. Resolves the first workspace like every data command (runs before the global workspace resolution). Admin-only. |
+| `lotics tools` | List tools by category with descriptions |
+| `lotics tools <name>` | Full description + JSON Schema for one tool |
+| `lotics run <tool> '<json>'` | Execute a tool (text output via toModelOutput). Args may also come from a file (`lotics run <tool> @args.json`) or piped stdin (`cat args.json \| lotics run <tool>`) — both bypass the OS `ARG_MAX` limit for large payloads (a knowledge-doc `content`, a bulk update). A leading `@` on the args is unambiguously a file path (JSON args start with `{`). |
+| `lotics run <tool> --json '<json>'` | Execute a tool (full JSON output) |
+| `lotics upload <file\|dir...>` | Upload files/directories via multipart POST to /v1/files |
+| `lotics 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 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 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; this avoids the stray nested `./<name>/` subdir a pull-from-inside-the-app used to drop. — `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. 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_id`/…) — 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 |
+| `lotics app deploy -m <message>` | **`-m` is REQUIRED** (CLI errors without a non-empty message) — each deploy is a version row read back by `lotics app versions`, so a blank message loses the audit trail. npm run build; tar source + dist; POST /v1/apps/{id}/versions multipart. Carries code + queries + capabilities only — workflow bindings are NOT a deploy concern (`set_app_workflow` / `remove_app_workflow` own `apps.workflows`; the manifest's `workflows` map is a pulled reflection used only for `useWorkflow` codegen). Deploy DOES send the manifest's `lotics.workflows` alias KEYS (not the bindings) as `workflow_aliases`, recorded on the version row so `remove_app_workflow` can refuse to unbind an alias the served version still declares. After a successful deploy it also **warns loudly about any `lotics.workflows` / `lotics.agents` alias declared in the manifest but NOT bound on the server** (a `getApp` diff via `warnIfUnboundAliases`) — since deploy never binds them, that would otherwise throw only at the app's first `useWorkflow` / `useAgentRun` call; the warning points to `lotics app workflow set` / `set_app_agent`. Advisory only (never fails the deploy). |
+| `lotics app versions [app_id]` | `GET /v1/apps/{id}/versions` — print deploy history newest-first (version number, timestamp, deployer name, build status, the `-m` message; `*` marks the currently-served version). app_id from the local manifest, or pass one to inspect any app without pulling it. Admin-only server-side (mirrors deploy + source download). Answers "what shipped, when, by whom" — e.g. whether a fix was live at an incident's time. The deploy pipeline already persisted all of this in `app_versions`; this is the read surface. Title → stderr, table → stdout (pipeable). |
+| `lotics app codegen [path]` | Regenerate `.lotics/*` from the manifest + workspace schema **without a deploy**. The three `.d.ts` companions (`app_{workflows,queries,agents}.d.ts`) are always rewritten (synchronous, no network). When credentials resolve, also rewrites the **runtime** `.lotics/app_fields.ts` — **branched on whether the app is a package installation** (`getApp().package_id` set, from `generate_package_fields.ts`): a **linked/published** app emits the BINDING form (`F`/`OPT`/`ROLE` resolved from the installation's LIVE binding — via `appBinding` / the `binding` RPC — at module load through `getAppBinding()` + top-level await, so the source stays portable across every install); a **bespoke** app emits the BAKED form (`generate_app_fields.ts`) — a real `.ts` exporting `F` (table→field→`"fld_…"`) + `OPT` (table→select-field→option→`"opt_…"`) keyed by display-name aliases, for the tables the app's queries reference (+ optional `package.json#lotics.codegen.tables` allowlist). Both forms share the `F`/`OPT` shape (contract aliases derive from the same slugified display names), so a published origin's deployed source compiles unchanged. Writing the BINDING form also heals the project's vitest setup (`ensureAppVitestSetup`, folded into the same write boundary): the binding form awaits `getAppBinding()` (a network call) at module load, so without a stub `npm test` fails to collect any test that imports the app graph — the heal writes `vitest.setup.ts` (mocks only `getAppBinding`, returning an echo binding: any alias → a self-identifying `fld:test:…`/`opt:test:…`/`grp:test:…` id) if absent, and warns the one-liner to add to `vite.config.ts`'s `test.setupFiles` if the wiring is missing (TS source isn't safely munged, mirroring `ensureAppTsconfig`'s JSONC-tsconfig warn). New scaffolds ship both. Also refreshes each bound workflow's `.lotics/workflows/<alias>.globals.d.ts` + re-wraps its EXISTING `src/workflows/<alias>.ts` body in the current envelope (strips + re-wraps; never re-fetches the body, so local edits survive). A getApp / binding / schema / dts-fetch failure is non-fatal (warns, keeps the last-generated files). |
+| `lotics app workflow run <alias> '<json>'` | Execute a bound app workflow end-to-end via `appWorkflow`. `app_id` comes from the local manifest; the alias must be bound (`set_app_workflow`). Inputs ingest exactly like `lotics run` (inline JSON / `@file` / stdin — bulk inputs bypass `ARG_MAX`). Prints the full `{status,message,data,files,side_effects}` JSON to stdout + a one-line summary to stderr; exits non-zero on `status:"error"` (assertable). `--print-created` (alias `--report-effects`) renders the honest post-run harvest (GAP-58): created records grouped by table, a paste-ready `lotics run delete_records …` per table, then the **mandatory caveat** naming what cannot be auto-undone (external integrations + notifications) and that sub-workflows may have run. `--cleanup` (DEFAULT OFF, implies the report) additionally runs the deletes for harvested records ONLY — never files / external / notifications. Neither is a rollback — a rollback is structurally impossible here. |
+| `lotics app workflow set <alias>` | Push the edited `src/workflows/<alias>.ts` body through `set_app_workflow` (the single author of `apps.workflows`). Reads the body from disk (header + `/// <reference>` + `export {};` marker + the `__workflow` wrapper all stripped) + the typed `inputs`/`outputs` from `package.json#lotics.workflows.<alias>`; the **server** re-verifies the body and echoes the bound `outputs` (declared, else DERIVED from `return({ data })`). When the manifest declared NO `outputs`, the DERIVED echo is written back into `package.json#lotics.workflows.<alias>.outputs` (a SURGICAL write — preserves `knowledge`/`config` and every other manifest field) and that alias's types are refreshed in place, so `useWorkflow("<alias>")`'s `result.data` is typed immediately with no hand-copy and no second `lotics app codegen`; an explicitly-declared `outputs` is authoritative and never overwritten. Deploy still never authors workflows — this is a CLI convenience over the existing tool. Clear error + non-zero exit on a missing file, an alias absent from the manifest, or a verify failure. |
+| `lotics app agent set <alias>` | Push the edited `src/agents/<alias>.md` instructions back through `set_app_agent` — the agent mirror of `app workflow set`, and the deploy-free authoring path for `apps.agents`. Reads the prose from disk (the `<!-- lotics: … -->` header stripped) and the typed fields (`inputs`/`outputs`/`tool_names`/`model_id`/`effort_level`/`knowledge_doc_ids`/`query_aliases`/`workflow_aliases`) from `package.json#lotics.agents.<alias>`, then sends them as ONE declaration. That assembly is the point: **`set_app_agent` REPLACES the declaration rather than patching it**, so a hand-built payload that sets one field silently drops the instructions, the output schema and the model pin — a silent, unrecoverable edit against a live prompt. Clear error + non-zero exit on a missing file, an alias absent from the manifest, or a file that is empty once the header is stripped (refusing to push an empty prompt). `app pull` writes the file; edit, then `set`. |
+| `lotics app query set <alias>` | Push `package.json#lotics.queries.<alias>` (`{ ast, params? }`) to `apps.queries` through `set_app_query` — the deploy-free inner loop for named queries, the mirror of `app workflow set`. The **server** validates it exactly as a deploy does (alias identifier, workspace-only tables, resolvable fields, declared params). Note: `apps.queries` is manifest-authoritative, so the next `lotics app deploy` re-syncs the whole map from the manifest — keep the declaration in the manifest to survive. Clear error + non-zero exit on an alias absent from the manifest or a validation failure. |
+| `lotics app agent run <app_id> <alias> ['<json>'\|@file\|stdin]` | Run a bound app agent end-to-end (GAP-87). A run needs no deployed UI bundle — just the app row + the bound agent declaration + member auth — so the **`app_id` is explicit** (not read from a local manifest). Inputs ingest exactly like `lotics run` (inline JSON / `@file` / stdin; empty = `{}`). Opens the run's SSE (`appAgentRunStream`), streams `text-delta` prose to **stderr** as live progress, then reports from the **settled run RECORD** (`listAgentRuns`, polled to a terminal status — the client stream can close a beat before the run settles, or drop while it runs on server-side): default prints the run's structured `output` (JSON) or final text to **stdout** + a status line to stderr; `--json` prints the full run summary to stdout. Selects THIS run by the `x-app-agent-run-id` header (ordering-independent). Exits 0 **only** when the settled status is `completed`; otherwise non-zero with the run's error surfaced. A settled run that never appears fails loudly (never a silent success). A fresh `session_id` is minted per run (self-contained); `--session <id>` continues an existing thread (prior runs become the agent's context). |
+| `lotics app workflow pull` | Rewrite every `src/workflows/<alias>.ts` from the server (faithful body per bound alias via `get_app_workflow`) **+ its `.lotics/workflows/<alias>.globals.d.ts`** (via `getAppWorkflowDts`, so the body is locally typecheckable via `lotics app workflow check`) without a full `app pull` (no source archive, no npm install). A legacy alias with no rendered source warns and is skipped; a dts-fetch failure is non-fatal (body still written with the fallback wrapper, typecheck degraded). Also idempotently patches the main `tsconfig.json` `exclude` to cover `src/workflows` + `.lotics/workflows` so a pre-existing app's `npm run typecheck` never loads the bodies or the colliding per-alias globals. |
+| `lotics app workflow check [alias]` | Check the editable workflow bodies locally, no auth / no network, in the **server's own order** — parse, then type-check. **Parse** runs `parseWorkflowJs` from `@lotics/shared` (the SAME module `verifyWorkflow` calls, never a second implementation — that is what let the two diverge once) over the stripped body `set` would upload, with `toolNames: undefined` (the CLI ships no tool registry, so tool-name resolution stays a server check while every shape/scope rule runs here). A body the subset rejects reports **that error alone** and skips the compiler — it never reaches the server's compiler either, so tsc's opinion of it is noise. **Type-check** then builds an **isolated** `ts.Program` per alias from exactly that alias's `{body, globals}` pair — mirroring the server, which verifies one body at a time — so the per-alias ambient `trigger` never collides and `trigger.app_workflow.inputs` is checked against the right alias (GAP-59). All aliases run in ONE node process (N programs, not N `tsc` spawns), with the SAME compile options the server uses at set-time verify (lib `es2022` with no DOM, target ES2022, strict, NodeNext, `types:[]`, skipLibCheck) and the app's OWN `typescript` (resolved from its `node_modules`, never bundled into the CLI). What the compiler sees is the **checked source**, not the file: `rewriteAccumulatorAppends` from `@lotics/shared` — the SAME transform the server applies before its set-time compile — is applied in memory, so a pulled body's canonical `out = concat(out, [item])` accumulator checks green here exactly as it saves there (compiling the raw text went red on it), and the body on disk is never rewritten. Reports `<file>:<line>:<col> - <TS####\|subset>` at the **physical** line in `src/workflows/<alias>.ts`, so an editor jump lands on the offending code (these are deliberately NOT `set`'s body-relative numbers — `set` prints no file path, so there is no format to agree with); exits non-zero if any alias fails. Green is honest but not total: `set` additionally resolves names, lints and structurally validates against the live workspace — passes that need its tables and tool schemas, so they cannot run offline, and the success line says so. A bound alias with no body file yet warns + skips; a body with no globals errors (run a pull). |
+| `lotics app subdomain <new-subdomain>` | Rename the app's public `<slug>.lotics.app` address via `PUT /v1/apps/{id}/subdomain`. app_id comes from the local `package.json` manifest; the chosen slug must be a valid DNS label and free; the old address stops resolving. |
+| `lotics app rename "<new name>"` | Change the app's display name (launcher/title) via the `update_app` tool. app_id comes from the local `package.json` manifest; the public address (`subdomain`) and code (`deploy`) are unchanged. |
+| `lotics app dev [path] [--port=N] [--vite-port=N] [--view-as=<member_id>]` | Spawn Vite dev server + an RPC-forwarding HTTP server. The wrapper page embeds the iframe with `sandbox="allow-scripts allow-same-origin"` matching production; postMessage ops (query / workflow / members / context / upload / openExternal / urlState / agentRun) are forwarded to api.lotics.ai using the CLI's API key — file bytes move in **both** directions through the dev server's own relays, never browser↔storage (the former GAP-44): dev runs against the PROD bucket, whose CORS admits `https://*.lotics.app` and not `http://localhost:<port>`, so a direct browser transfer is blocked — no upload could complete and no preview engine (PDF/Word/Excel all FETCH the bytes) could read a file. `upload` mints a presigned URL and PUTs it **to `PUT /_upload/<file_id>`** (`dev/upload_relay.ts`) from the wrapper page — same-origin, so no preflight and no CORS — and Node forwards it on; every presigned `url`/`thumbnail_url`/`preview_url` on a **file object** in an RPC result is rewritten to **`GET /_file/<token>`** (`dev/file_relay.ts`, absolute — the iframe would resolve a relative path against Vite), which streams the bytes back with `Range` passthrough (206s intact, so PDF seeking works) and an `Access-Control-Allow-Origin` for the Vite origin (the one cross-origin hop left is OUR response to allow). Neither relay ever takes a destination from the client — it gets a `file_id`/token and transfers only to/from a URL it minted or observed itself, so there is no client-controlled target and no SSRF surface. A URL in a record's own text cell is NOT rewritten. Production is unchanged (direct-to-storage, no bytes through the API server); `openExternal` and `urlState.get/set` are handled locally (the latter read/write the wrapper page's own address bar — `set` writes in place via `replaceState` and browser back/forward broadcast a `url-state` message back, so `useUrlState` survives refresh and is shareable in the dev loop; in-app *routing* is the app's own (the iframe owns its url via `@lotics/app-sdk/router`), and the wrapper bakes the saved screen (`_loc`) into the iframe src on load so a refresh restores it, mirroring production); `agentRun` (streaming) is proxied through `POST /_agent_run`, which opens the run's SSE with the CLI key and pipes chunks back to the iframe (`stream-chunk`* → `stream-end`), so `useAgentRun` works in the dev loop just like production; `context` resolves the viewer (`member_id` from `cli/whoami` + `comments_enabled` from the local manifest) and fetches the installation's stored `config` live from the app row, so `useConfig()` renders the same values as production. `--view-as` (global flag; also `LOTICS_VIEW_AS`) threads `x-view-as-member-id` so `is_current_member` + `context` resolve to that member — **admin key only** (the server 403s a non-admin), writes stay attributed to the key owner. Hot reload via Vite; full DevTools / Playwright access via plain localhost. The dev-optimizer pre-bundle list (`optimizeDeps.include`, load-bearing for dev) is imported from `@lotics/ui/vite` (`loticsOptimizeDeps`) rather than hardcoded in the scaffold, so it tracks the installed `@lotics/ui` and can never go stale. Binds **loopback only** (`127.0.0.1`) — `/_rpc` dispatches with the developer's API key, so a socket on every interface would hand anyone on the network full read/write on the workspace. |
+| `lotics ui link <component> [--ui-src <path>] [--remove]` | Dev-link `@lotics/ui` to `packages/ui/src` by inserting (or removing) a package-wide `{ find: /^@lotics\/ui\/(.+)$/, replacement: "<absUiSrc>/$1" }` alias in the app's `vite.config.ts` resolve.alias — so edits to `packages/ui/src` go live (HMR) and bundle on deploy, without a publish round-trip. **`packages/ui/src` resolution:** walk up for a monorepo checkout, else the explicit `--ui-src <abs path>` / `LOTICS_UI_SRC` env — that's how an **EXTERNAL app** (one that consumes `@lotics/ui` from npm, e.g. under `~/lotics_apps`) links the local kit; fails loud when neither resolves, or when `--ui-src` isn't a directory. No auth (local file edit). Idempotent. `component` is advisory/validation only (the alias covers every subpath). **Vite-only, by design:** the app's `tsc` still resolves `@lotics/ui` from `node_modules` (the published `.d.ts`) — the kit `src` can't be typechecked inside an app because it's RN-Web (uses `react-native-web` types the app resolves as base `react-native`), so typecheck the kit in `packages/ui` and let the finalize publish restore the app's own typecheck. Reminds to restart dev + `rm node_modules/.vite`, and to finalize (`--remove` + publish-chain bump). |
+| `lotics xlsx <subcmd>` | Local .xlsx read/write/edit using the bundled `@lotics/xlsx` engine (no auth, no network). 14 named subcommands (read, write, set-cell, clear-range, merge, unmerge, add-sheet, delete-sheet, rename-sheet, insert-rows, delete-rows, insert-cols, delete-cols, set-style) + `batch` for applying multiple of the same 14 ops in a single parse/export cycle. `read` also takes `--sheet <name>` (limit output to one sheet — unknown name fails with the available list) and `--range <sheet>!<A1:G60>` (limit to a cell window; the `<sheet>!` prefix is optional when `--sheet` supplies the sheet, a single cell like `S1!B2` is a 1×1 window) to trim a large workbook's JSON — the output shape is unchanged, only the `sheets` array and each sheet's `cells` map are filtered. Atomic in-place write (temp file + rename). |
+| `lotics docx <subcmd>` | Local .docx read/write/edit using the bundled `@lotics/docx` engine (OOXML round-trip surface only — no ProseMirror baggage). Subcommands: read, write, append-paragraph, insert-paragraph, delete-block, replace-text, batch. A legacy `.doc` (Word 97–2003 OLE2 binary) is detected in `loadFile` and routed through `@lotics/ooxml`'s `loadDocxFromBuffer` (which re-emits it as real OOXML) before reading — so `lotics docx read` works on a `.doc`, not just a `.docx`. Opaque blocks (tables, custom XML) preserved verbatim. Atomic in-place write. |
+| `lotics file preview <file\|fil_id> [-o out.png]` | (also `lotics preview`) Render a .docx/.xlsx to a PNG using the SAME engines the frontend FilePreview uses (`@lotics/docx` `loadDocxIntoElement` / `@lotics/xlsx` `drawSpreadsheet`) — so what you see matches an operator. Accepts a **local path** OR a stored **`fil_…` id** (`isStoredFileId` — a bare id, no extension): an id is first downloaded to a temp dir via `downloadFileById` (the `signed_url` presign path — same authority as `lotics file download`), rendered, then the transient source is removed; with no `-o` the PNG lands in cwd under the stored file's base name (`defaultPreviewOutputPath`). Drives a headless Chrome over **CDP with only Node built-ins** (`WebSocket`/`fetch`/`http`/`child_process`) — zero npm deps, the CLI stays a single bundled binary. The browser render logic is a separate esbuild **browser** bundle shipped at `dist/render_page.js` (built by `build_cli.mjs`, excluded from the node `tsgo`), served over a throwaway localhost http server and screenshotted full-page. **Requires a Chrome/Chromium on the machine** — detected from `CHROME_PATH`/`LOTICS_CHROME`, then Playwright's installed chromium, then system paths — inherent to rendering these browser formats; a clear "install a browser" error otherwise. PDFs need no render (open them directly). |
+

package/docs/knowledge_docs.md

@@ -7,8 +7,8 @@ them on demand** while it works, pulling in only the lines it needs.
 
 They are deliberately **not** injected into the agent wholesale. Bulk-loading every doc into
 every request would burn the context budget and drown the signal. Instead the agent retrieves
-from them through a search funnel, so a 10,000-line tariff book costs nothing until a question
-actually touches it.
+from them line by line — grep, then read — so a 10,000-line tariff book costs nothing until a
+question actually touches it, and a 10MB one is no different.
 
 This is a **capability + usage** guide. For the exact input schema of any tool named here, run
 `lotics tools <tool_name>`.
@@ -34,9 +34,9 @@ This reads the body from your filesystem and creates the doc through `create_kno
 `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
-  colloquial terms, and what to read for detail. This is surfaced when the doc is *found*,
-  before its content is read, so the agent knows whether to open it.
+- `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.
 
 A new doc is created **owned by you, active in your own agent context, and private** — no one
@@ -61,28 +61,84 @@ 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 — catalog, then read
+## How an agent uses a doc — ls, grep, cat
+
+Docs are not injected wholesale. The agent works the corpus like a filesystem, and all three
+verbs respect access + activation, so only docs the caller may use ever surface.
+
+1. **`list_knowledge`** — `ls`. The corpus as a folder tree: name, id, folder, and a truncated
+   description. No bodies.
+2. **`grep_knowledge`** — `grep -rn`. Substring match across every readable doc (or one doc, or
+   one folder), returning **doc, line number, and the matching line**. It runs inside Postgres,
+   so only matching lines cross the wire.
+3. **`read_knowledge`** — `cat` / `sed -n 'X,Yp'`. Read a doc whole or by line range, to see
+   the context around a hit.
+
+Matching is **substring, not ranked** — there is no index and no tokenizer, which is why a
+corpus in any script works and why nothing goes stale. The consequence is that the *agent*
+does the narrowing: a distinctive phrase is sharply selective, a whole question matches
+everything. `grep_knowledge` always reports `total_matches`, so "too broad" is visible and
+cheap to fix.
+
+### Matching options
+
+- **Diacritics fold by default** — `ca phe` matches `cà phê`. `diacritic_insensitive: false` matches
+  tone marks exactly.
+- **Case folds by default**, independently of diacritics. `case_sensitive: true` matches case
+  exactly — useful for an acronym (`NK` vs `nk`) that a folded search would blur.
+- **Whitespace is normalized on both sides.** A body converted from PDF, Word or Excel carries
+  non-breaking spaces, soft hyphens, zero-width marks and padded runs that nobody types into a
+  query; those fold to ordinary single spaces before matching, so a correct search does not return
+  a silent zero on text that is present. Your pattern is normalized the same way.
+- **`regex: true`** treats the pattern as a POSIX regular expression: quantifiers, character
+  classes, alternation, anchors, and **`\y` for a word boundary**. Note `\y`, not `\b` — Postgres
+  spells it differently, and `\b` is rewritten for you rather than silently matching nothing.
+  Literal is the default on purpose: `0901.11.20` as a regex would also match `0901X11Y20`.
 
-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. **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>`.
-
-Structure your content so a reader lands on the answer without loading the rest:
+```
+grep_knowledge({ pattern: "\\yNK\\y", regex: true, case_sensitive: true })
+```
 
-- 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.
+### What a result is bounded by
+
+A result carries at most 40.000 characters. Matched lines are admitted first and context fills
+what remains, so an answer is never dropped to make room for a neighbouring line. Anything the
+budget cut is REPORTED — `chars_elided_matches` (an answer was dropped) and
+`context_omitted_matches` (an answer was kept without the context you asked for) mean different
+things and call for different fixes: narrow the pattern, or ask for fewer `context_lines`.
+Individual lines longer than 600 characters are clipped and marked, with `read_knowledge` giving
+the rest.
+
+`total_matches` is always the true total, even when fewer are shown.
+
+## Write for grep — the rules that decide whether an answer is findable
+
+Retrieval addresses **lines**. Every rule below follows from that one fact, and ignoring them
+is the difference between a doc that answers and a doc that merely exists.
+
+- **One self-contained fact per line.** A grep hit returns *that line*. For dense or tabular
+  data — a price row, a tariff code, a charge entry — put the whole record on one line.
+- **Repeat the searchable terms on every line; headings do not carry down.** A line reading
+  `Rate: 15%` under a heading `Roasted coffee` will never match a search for `coffee`. Restate
+  the identifying terms inline, even when it reads redundantly to a human. This is the single
+  rule most often got wrong.
+- **Keep a line under ~600 characters.** Past that the line is truncated in the agent's view
+  and marked as cut; the agent can still `read_knowledge` for the rest, but it costs a round
+  trip. Put the identifying terms early and the long tail late.
+- **Put synonyms and translations on the line itself.** A bilingual row (`Cà phê, đã rang /
+  Coffee, roasted`) matches queries in either language for free. The same trick carries
+  colloquial terms next to official ones.
+- **For prose, keep a rule and its exception close.** A hit returns one line, so a rule on line
+  40 and its exception on line 90 can be retrieved apart. Use `context_lines` when reading, and
+  keep related clauses adjacent when writing.
+
+Markdown headings are ordinary text — useful for a human and for orienting a `read_knowledge`,
+but they carry no retrieval weight of their own.
+
+**The description is the discovery hint.** It is what the agent sees in the tree before it has
+read a byte of the body, so it is the only clue for *what term to grep for*. Write it to name
+the doc's vocabulary — the words that actually appear inside it. Keep it to a sentence: it is
+truncated at 200 characters, and a keyword-stuffed description is cut, not rewarded.
 
 ## Updating a doc — `lotics knowledge update`
 
@@ -95,8 +151,8 @@ Send only the fields you're changing. `--from` / `--content` replaces the body;
 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.
+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.
 
 ## Package-managed knowledge
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.98.0",
+  "version": "0.100.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
   },
   "files": [
     "dist",
+    "AGENTS.md",
     "README.md",
     "docs"
   ],