@lotics/cli 0.91.0 → 0.92.0

package/dist/src/client.d.ts

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

package/dist/src/client.js

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

package/docs/knowledge_docs.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.91.0",
+  "version": "0.92.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {
@@ -22,6 +22,7 @@
   },
   "devDependencies": {
     "@lotics/docx": "*",
+    "@lotics/ooxml": "*",
     "@lotics/shared": "*",
     "@lotics/xlsx": "*",
     "@types/node": "^22.15.21",