@lotics/cli 0.87.0 → 0.88.0

package/README.md

@@ -10,6 +10,20 @@ Lotics is an AI-powered operations platform. Through this CLI you can:
 - Administer the workspace — invite members, manage groups, share resources, transfer ownership, browse connected accounts (OAuth attach is web-only)
 - Create and manage apps, knowledge docs, and files
 
+## Capability guides
+
+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):
+
+- [`docs/document_templates.md`](docs/document_templates.md) — generate finished documents
+  (PDF, Excel, Word, email) by filling reusable templates: the five template types, the
+  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.
+
+Both point to `lotics tools <name>` for exact input schemas.
+
 ## Install
 
 ```bash

package/dist/render_page.js

@@ -58303,11 +58303,10 @@ ${e.toString()}`);
     return val && typeof val === "object" ? val : {};
   }
 
-  // ../xlsx/src/biff8_reader.ts
+  // ../shared/src/ole.ts
   var OLE2_MAGIC2 = [208, 207, 17, 224, 161, 177, 26, 225];
   var ENDOFCHAIN = 4294967294;
   var FREESECT = 4294967295;
-  var DEFAULT_MAX_ROWS = 1e4;
   function isOle2(bytes) {
     return bytes.length >= 8 && OLE2_MAGIC2.every((b, i3) => bytes[i3] === b);
   }
@@ -58322,7 +58321,7 @@ ${e.toString()}`);
     const firstMiniFatSector = u32(60);
     const firstDifatSector = u32(68);
     if (sectorSize < 512 || sectorSize > 1 << 20) {
-      throw new Error("Unsupported .xls: invalid OLE2 sector size");
+      throw new Error("Unsupported OLE2 file: invalid sector size");
     }
     const sectorOffset = (n) => sectorSize * (n + 1);
     const maxSectors = Math.ceil(bytes.length / sectorSize) + 1;
@@ -58384,6 +58383,25 @@ ${e.toString()}`);
     const readStream = (e) => e.size >= miniCutoff ? readBig(e.start, e.size) : readMini(e.start, e.size);
     return dir.filter((e) => e.type === 2).map((e) => ({ name: e.name, bytes: readStream(e) }));
   }
+  function utf16le(b) {
+    let s = "";
+    for (let i3 = 0; i3 + 1 < b.length; i3 += 2) s += String.fromCharCode(b[i3] | b[i3 + 1] << 8);
+    return s;
+  }
+  function concat(parts) {
+    let total = 0;
+    for (const p of parts) total += p.length;
+    const out = new Uint8Array(total);
+    let o = 0;
+    for (const p of parts) {
+      out.set(p, o);
+      o += p.length;
+    }
+    return out;
+  }
+
+  // ../xlsx/src/biff8_reader.ts
+  var DEFAULT_MAX_ROWS = 1e4;
   var REC = {
     FORMULA: 6,
     EOF: 10,
@@ -58682,22 +58700,6 @@ ${e.toString()}`);
     }
     return s;
   }
-  function utf16le(b) {
-    let s = "";
-    for (let i3 = 0; i3 + 1 < b.length; i3 += 2) s += String.fromCharCode(b[i3] | b[i3 + 1] << 8);
-    return s;
-  }
-  function concat(parts) {
-    let total = 0;
-    for (const p of parts) total += p.length;
-    const out = new Uint8Array(total);
-    let o = 0;
-    for (const p of parts) {
-      out.set(p, o);
-      o += p.length;
-    }
-    return out;
-  }
   function builtinFormat(id) {
     const DATES = {
       14: "m/d/yyyy",

package/dist/src/cli.js

@@ -30830,12 +30830,12 @@ export default defineConfig({
     // default export the dev optimizer won't synthesize unbundled ("does not
     // provide an export named 'default'") \u2014 blanking the iframe the moment a
     // markdown component mounts. Pre-bundling react-markdown folds the whole
-    // subtree (incl. style-to-js) into one interop'd chunk; remark-gfm (imported
-    // alongside it) is pre-bundled for the same consistency. Both are regular
-    // deps of @lotics/ui (hoisted), so they need no package.json entry here.
+    // subtree (incl. style-to-js) into one interop'd chunk. It is a regular dep
+    // of @lotics/ui (hoisted), so it needs no package.json entry here. (The GFM
+    // plugin @lotics/ui composes is pure ESM \u2014 no CJS interop to force.)
     include: [
       "react-native-svg",
-      "react-markdown", "remark-gfm",
+      "react-markdown",
       "react-native-web", "@react-native/normalize-colors",
       "inline-style-prefixer/lib/createPrefixer",
       "inline-style-prefixer/lib/plugins/crossFade",
@@ -43352,11 +43352,10 @@ function ensureVmlArray(val) {
   return Array.isArray(val) ? val : [val];
 }
 
-// ../xlsx/src/biff8_reader.ts
+// ../shared/src/ole.ts
 var OLE2_MAGIC2 = [208, 207, 17, 224, 161, 177, 26, 225];
 var ENDOFCHAIN = 4294967294;
 var FREESECT = 4294967295;
-var DEFAULT_MAX_ROWS = 1e4;
 function isOle2(bytes) {
   return bytes.length >= 8 && OLE2_MAGIC2.every((b, i2) => bytes[i2] === b);
 }
@@ -43371,7 +43370,7 @@ function readCfbStreams(bytes) {
   const firstMiniFatSector = u32(60);
   const firstDifatSector = u32(68);
   if (sectorSize < 512 || sectorSize > 1 << 20) {
-    throw new Error("Unsupported .xls: invalid OLE2 sector size");
+    throw new Error("Unsupported OLE2 file: invalid sector size");
   }
   const sectorOffset = (n) => sectorSize * (n + 1);
   const maxSectors = Math.ceil(bytes.length / sectorSize) + 1;
@@ -43433,6 +43432,25 @@ function readCfbStreams(bytes) {
   const readStream = (e) => e.size >= miniCutoff ? readBig(e.start, e.size) : readMini(e.start, e.size);
   return dir.filter((e) => e.type === 2).map((e) => ({ name: e.name, bytes: readStream(e) }));
 }
+function utf16le(b) {
+  let s = "";
+  for (let i2 = 0; i2 + 1 < b.length; i2 += 2) s += String.fromCharCode(b[i2] | b[i2 + 1] << 8);
+  return s;
+}
+function concat(parts) {
+  let total = 0;
+  for (const p of parts) total += p.length;
+  const out = new Uint8Array(total);
+  let o = 0;
+  for (const p of parts) {
+    out.set(p, o);
+    o += p.length;
+  }
+  return out;
+}
+
+// ../xlsx/src/biff8_reader.ts
+var DEFAULT_MAX_ROWS = 1e4;
 var REC = {
   FORMULA: 6,
   EOF: 10,
@@ -43731,22 +43749,6 @@ function readUnicodeShort(b, offset, lenBytes) {
   }
   return s;
 }
-function utf16le(b) {
-  let s = "";
-  for (let i2 = 0; i2 + 1 < b.length; i2 += 2) s += String.fromCharCode(b[i2] | b[i2 + 1] << 8);
-  return s;
-}
-function concat(parts) {
-  let total = 0;
-  for (const p of parts) total += p.length;
-  const out = new Uint8Array(total);
-  let o = 0;
-  for (const p of parts) {
-    out.set(p, o);
-    o += p.length;
-  }
-  return out;
-}
 function builtinFormat(id) {
   const DATES = {
     14: "m/d/yyyy",

package/dist/starter_template.js

@@ -235,12 +235,12 @@ export default defineConfig({
     // default export the dev optimizer won't synthesize unbundled ("does not
     // provide an export named 'default'") — blanking the iframe the moment a
     // markdown component mounts. Pre-bundling react-markdown folds the whole
-    // subtree (incl. style-to-js) into one interop'd chunk; remark-gfm (imported
-    // alongside it) is pre-bundled for the same consistency. Both are regular
-    // deps of @lotics/ui (hoisted), so they need no package.json entry here.
+    // subtree (incl. style-to-js) into one interop'd chunk. It is a regular dep
+    // of @lotics/ui (hoisted), so it needs no package.json entry here. (The GFM
+    // plugin @lotics/ui composes is pure ESM — no CJS interop to force.)
     include: [
       "react-native-svg",
-      "react-markdown", "remark-gfm",
+      "react-markdown",
       "react-native-web", "@react-native/normalize-colors",
       "inline-style-prefixer/lib/createPrefixer",
       "inline-style-prefixer/lib/plugins/crossFade",

package/docs/document_templates.md

@@ -0,0 +1,153 @@
+# Document Templates
+
+Turn workspace data into finished documents — invoices, contracts, reports, letters,
+labels, emails — by filling a reusable template instead of writing a file from scratch.
+You register a template once, then generate a filled file (or a rendered email) from it as
+many times as you like, feeding it data from records, a workflow, or an agent run.
+
+This is a **capability + usage** guide. For the exact input schema of any tool named here,
+run `lotics tools <tool_name>` — that is always the source of truth for arguments.
+
+## The five template types
+
+| Type | What it fills | Output | Create with |
+|---|---|---|---|
+| `pdf-form` | fields overlaid on an **uploaded PDF** at fixed positions | PDF | `create_pdf_template` (mode `form`) |
+| `html` (a PDF) | an **HTML + Handlebars** layout you write from scratch | PDF | `create_pdf_template` (mode `html`) |
+| `excel` | an **uploaded `.xlsx`** with `{{marker}}` cells | `.xlsx` | `create_excel_template` |
+| `word` | an **uploaded `.docx`** with `{{marker}}`s | `.docx` | `create_word_template` |
+| `email` | an **inline HTML + Handlebars** body, rendered when the email is sent | email | `create_email_template` |
+
+Two shapes underneath: **file-backed** (`pdf-form`, `excel`, `word`) clone an uploaded
+office file and mark it up; **inline** (`html`, `email`) store the markup you author directly.
+
+## The lifecycle: create → generate → chain
+
+1. **Create** a template — register the file (or inline markup) and declare a `variables`
+   map (the named slots the template fills). This returns a template id (`tpl_…`).
+2. **Generate** a filled file — call the matching `generate_*_from_template` with the
+   template id, a `filename` (no extension), and a `data` map keyed by your variable names.
+   It substitutes the markers and returns a **generated file** (with a `file_id`).
+3. **Chain** the result — generation only *produces* the file. Attaching it to a record,
+   sending it, or saving it locally is a separate step: inside a workflow, pass the returned
+   `file_id` to the next step; from the CLI, `lotics download <file_id>` fetches it.
+
+Email is the exception: there is **no** `generate_email_from_template`. An email template is
+rendered to a subject + body **at send time** from the template and the data the send step
+supplies — so you author it with `create_email_template` and a workflow/app send step (or the
+web composer) does the rendering and delivery. External agents send their own email directly.
+
+## Creating each type
+
+### PDF from HTML (`create_pdf_template`, mode `html`)
+
+Write a full HTML document with inline CSS and `{{variable}}` placeholders; it renders to PDF
+via a headless browser. Good for invoices, reports, letters, certificates — anything whose
+layout you control. Declare `variables` (plain text, rich `html`, an auto-rendered `table`,
+or a `list`), and optionally `format` (page size) and `orientation`. See
+`lotics tools create_pdf_template` for the exact variable shapes.
+
+### PDF form (`create_pdf_template`, mode `form`)
+
+For an existing PDF you must fill in place (a government form, a printed contract):
+
+1. `lotics upload ./form.pdf` → a `file_id`.
+2. `create_pdf_template` with mode `form` and that `file_id`.
+3. `analyze_pdf_template` — extracts the labels and their positions off the page.
+4. `update_pdf_template` — define the positioned fields (`text` / `checkbox` / `image`, each
+   with a page + x/y/size) in `variables`.
+
+Form-mode data is scalar-only (text, numbers, checkboxes) — one value per positioned field.
+
+### Excel (`create_excel_template`)
+
+1. Build a `.xlsx` in Excel (or with `lotics xlsx`) and put `{{marker}}`s in the cells that
+   should be filled. `lotics upload ./template.xlsx` → a `file_id`.
+2. `create_excel_template` with that `template_file_id` and a `variables` map. Markers are
+   **validated at create time** — a structural error (mismatched loop, unknown helper, bad
+   placement) blocks the save, and declared variables with no matching marker come back in
+   `unmarked_variables` (skipped, not filled).
+
+To inspect or add markers on the uploaded file without leaving the CLI: `excel_get_range` /
+`excel_find_cells` to look, `excel_update_range` to write markers, `validate_excel_template`
+to re-check. Pass raw numbers / ISO dates / booleans at generate time — the cell's number
+format handles display.
+
+### Word (`create_word_template`)
+
+1. Build a `.docx` with `{{marker}}`s where values go. `lotics upload ./template.docx`.
+2. `create_word_template` with the `template_file_id` and `variables`. As with Excel, an
+   unmarked declared variable comes back in `unmarked_variables` and is skipped.
+
+To add markers/loops/conditionals to the uploaded file from the CLI: `word_replace_text`,
+`word_insert_loop`, `word_insert_conditional` (and their `remove_*` counterparts).
+
+### Email (`create_email_template`)
+
+Inline HTML + Handlebars, no uploaded file. Declare `variables`, and optionally a default
+`subject` (which itself supports `{{variable}}` expressions) and default to/cc/bcc. The body
+and subject render from the data at send time.
+
+## Markers, at a usage level
+
+Every type supports three shapes of substitution. The exact syntax differs per engine — read
+the create-tool description for the reference; here is the capability:
+
+- **Scalar** — a single value in one spot: `{{name}}`, `{{total}}`. Whole-cell scalars in
+  Excel preserve their type via the cell's number format.
+- **Repeating rows / line items** — one template row rendered once per item in a list, for
+  invoice lines, order rows, tables. Excel and the HTML/email engines use a Handlebars-style
+  `{{#each items}}…{{/each}}`; Word uses `{{FOR item IN items}}…{{$item.field}}…{{END-FOR item}}`
+  (the `word_insert_loop` tool writes these command rows for you). The HTML and email types
+  also offer an auto-rendered `table` variable — declare its columns and pass an array, no
+  hand-written loop. (Excel always uses the `{{#each}}` marker rows — it has no auto-rendered
+  `table` type; its variable types are string/number/date/boolean/array.)
+- **Conditional sections** — a block shown only when a condition holds (a "paid" stamp, an
+  optional notes block). Excel/HTML/email use `{{#if}}…{{else}}…{{/if}}`; Word uses
+  `word_insert_conditional`.
+
+Run `lotics tools create_excel_template`, `create_word_template`, `create_pdf_template`, or
+`create_email_template` for each engine's exact marker grammar and helper list — don't guess it.
+
+## Generating a filled file
+
+```bash
+# See what a template expects, then fill it
+lotics tools generate_excel_from_template
+lotics run get_template '{"template_id":"tpl_..."}'          # its declared variables
+lotics run generate_excel_from_template '{"document_template_id":"tpl_...","filename":"invoice-1042","data":{"company_name":"Acme","total":1042,"items":[...]}}'
+lotics download <file_id> -o ./out/
+```
+
+- `data` is a map keyed by your variable names. Scalars for scalar/form fields; arrays for
+  `table`/`list`/loop variables. `filename` excludes the extension (the type sets it).
+- Each `generate_*_from_template` returns a generated file object; take its `file_id` onward.
+- In a workflow, a **generate step** calls the same tools and hands the `file_id` to the next
+  step (attach to a record, send as an attachment, etc.) — see `docs/workflow_engine.md` in
+  the platform docs.
+
+## Discovering and managing templates
+
+Four unified tools work across all five types:
+
+| Tool | Does |
+|---|---|
+| `query_templates` | list templates (optionally filter by type: excel/word/pdf/email) |
+| `get_template` | one template's full definition, incl. the `variables` it expects |
+| `clone_template` | copy a template to iterate on |
+| `delete_template` | remove a template |
+
+Call `get_template` before generating when you don't already know a template's variable names.
+
+## Reaching the tools
+
+```bash
+lotics tools                              # all categories
+lotics tools create_word_template         # one tool: full description + input schema
+lotics run <tool> '<json-args>'           # execute (inline JSON, @file.json, or piped stdin)
+```
+
+The template tools live in the categories **PDF Templates**, **Excel Templates**,
+**Word Templates**, **Email Templates**, and **Templates** (the unified query/get/clone/delete).
+Uploading the source file for a file-backed template is `lotics upload <file>`; fetching a
+generated file is `lotics download <file_id>`.

package/docs/knowledge_docs.md

@@ -0,0 +1,112 @@
+# Knowledge Docs
+
+Knowledge docs are the AI's **rulebook layer** — the workspace-specific facts and rules an
+agent can't know on its own: your price list, your product codes, your SOPs, your shipping
+tariffs, your glossary of in-house terms. You write them once; the agent **searches and reads
+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.
+
+This is a **capability + usage** guide. For the exact input schema of any tool named here, run
+`lotics tools <tool_name>`.
+
+## Rulebook, not methodology
+
+Put in a knowledge doc the things the model **cannot guess**: your specific numbers, codes,
+names, exceptions, and policies. Do **not** put in it general skills the model already has
+("how to write a polite email", "how to summarize"). If the agent would get it right without
+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`
+
+```bash
+lotics run create_knowledge @doc.json      # content is large → read from a file or stdin
+```
+
+`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.
+- `content` — Markdown.
+
+A new doc is created **owned by you, active in your own agent context, and private** — no one
+else can see it yet. (The tool itself takes only name/description/content; attaching files to a
+doc and changing its default-active state are done through the web app / REST surface, not this
+tool.)
+
+## Access vs. activation — both are required
+
+A knowledge doc reaches an agent only when **two** conditions hold for that member:
+
+1. **Access** — the member can `use` the doc. New docs are private to the owner; share them
+   with other members or groups using the IAM tool `share_resource` (category **Admin**;
+   `unshare_resource` to revoke).
+2. **Activation** — the doc is *active* in that member's agent context. Activation is
+   **separate from sharing**: a member can have access to a doc that is switched off in their
+   context, and it won't reach their agent. Each doc has a default-active state (on by default),
+   and each member can override it on or off for themselves. Activation is toggled in the web
+   app, per member — there is no CLI tool for it.
+
+So: shared + active → the agent can find and read it. Shared but deactivated → invisible to
+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
+
+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.
+
+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.
+
+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:
+
+- Organize under clear Markdown headers, so the doc can be outlined and read by section.
+- 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`
+
+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). 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.
+
+## Package-managed knowledge
+
+A knowledge doc can also be delivered as part of a **content package** — a versioned corpus of
+docs (and document templates) published from one workspace and installed into others. Install
+delivers the docs; upgrade refreshes them in place. Authoring, sharing, and retrieval work the
+same either way; the package layer just manages distribution and version pinning. See
+`docs/packages.md` in the platform docs for the publish/install/upgrade lifecycle.
+
+## 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
+```
+
+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**).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.87.0",
+  "version": "0.88.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {
@@ -11,7 +11,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "docs"
   ],
   "scripts": {
     "build": "tsgo && node scripts/build_cli.mjs",