@lotics/cli 0.152.2 → 0.154.0

package/docs/knowledge_docs.md

@@ -72,36 +72,57 @@ 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,
+2. **`grep_knowledge`** — `grep -rn`. 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 is **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.
+
+### Literal by default, expression on request
+
+`pattern` is **literal text** — every character matches itself. Set `regex: true` to read it as
+a POSIX regular expression instead.
+
+```
+grep_knowledge({ pattern: "C/O (Form E)" })
+grep_knowledge({ pattern: "\\yNK\\y", regex: true, case_sensitive: true })
+```
+
+The default is the safe one rather than the conventional one, and the asymmetry is worth
+knowing. As an expression, `C/O (Form E)` searches for `C/O Form E` — not in the document — and
+returns a confident zero; `[CŨ]` becomes a one-character class and matches every `C` in the
+corpus. Both look like ordinary answers. A literal search has no such failure: the worst case
+is an expression sent without the flag, which finds nothing and says so, naming the search that
+ran and what to pass instead.
 
 ### Matching options
 
-- **Diacritics fold by default** — `ca phe` matches `cà phê`. `diacritic_insensitive: false` matches
-  tone marks exactly.
+- **Tone marks match exactly by default.** `diacritic_insensitive: true` folds them, so `ca phe`
+  matches `cà phê` — reach for it when the pattern was typed without them, not by habit: folding
+  strips the pattern to ASCII, where a short Vietnamese word matches inside unrelated words
+  (`mã` finds `manifest`). An empty result tells you when folding would have matched.
 - **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`.
-
-```
-grep_knowledge({ pattern: "\\yNK\\y", regex: true, case_sensitive: true })
-```
+  a silent zero on text that is present. A literal pattern is normalized the same way; an
+  expression is left byte-exact, since collapsing its whitespace would rewrite it.
+- **What `regex: true` supports**: quantifiers, character classes, alternation, anchors,
+  backreferences, non-greedy forms, `(?i)`, and both lookahead and lookbehind. A word boundary
+  is **`\y`**, not `\b` — Postgres spells it differently, and `\b` is rewritten for you rather
+  than silently matching nothing. Named groups and `\p{…}` are likewise rewritten to their POSIX
+  equivalents. A `\p{…}` with no POSIX equivalent, and a malformed expression, are both refused
+  with the reason.
+
+Where an expression cannot express the question at all — a value that must be computed, a
+layout matching cannot address — stage the doc into a code run instead (`code_exec` with
+`knowledge_doc_ids` puts it at `inputs/knowledge/<id>.md` as a real file).
 
 ### What a result is bounded by
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.152.2",
+  "version": "0.154.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {