@lotics/cli 0.98.0 → 0.99.1

package/dist/src/cli.js

@@ -64486,6 +64486,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({

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