sensemaking 0.3.2 → 0.4.0

package/skills/sense/SKILL.md

@@ -21,9 +21,11 @@ only as deep as the question needs.
    `a OR b OR c` for any-word matching.
 3. `sense peek <path>` — structure before reading: outline with `[L143-162, ~380t]` ranges,
    links both ways. ~17% the cost of reading the file.
-4. `Read` the line range peek gave you — not the whole file.
+4. `Read` — the payload. On large files, peek's line ranges let you read just the section
+   you need; small files are often cheaper to read whole.
 
-Every result is a reference, never file contents. Prefer `--format json` when consuming output.
+Every result is a reference, never file contents. Output defaults to a table, built for
+humans; `--format json` returns the same rows machine-parseable.
 
 ## Verbs
 
@@ -36,13 +38,16 @@ sense <name> [params...]                        # named query from sense.config.
 sense --list | status | rebuild
 ```
 
-- **Expand terms before searching.** Write `pricing OR billing OR invoicing`, not one word — you
-  know the synonyms; the index only knows the words in the files. Expand categories into their
-  likely members too: a note about TypeScript never says "programming language".
 - Terms pass verbatim to FTS5 MATCH. Bare words AND-join — one absent word means zero rows —
-  so write `OR` yourself when you want any-word matching; invalid syntax is an error, not a
-  rewrite.
-- **Over-fetch, then choose.** `--k 20`, read the rows, open the 2–3 that matter.
+  so write `OR` yourself when you want any-word matching; double-quote punctuated terms
+  (`"customer-facing"`, `"founder's"`); invalid syntax is an error, not a rewrite. The same
+  rules apply to search commands you write into subagent briefs.
+- When a search misses, the recall levers are: OR-in synonyms and concrete instances (the
+  index only knows the words in the files — a note about a specific tool rarely names its
+  category), and raise `--k` (a row costs ~30 tokens). Each widening adds candidates and
+  dilutes ranking, so the noise trade-off runs both ways.
+- A frontmatter query enumerates its matches deterministically; search ranks by term overlap,
+  so results shift as phrasing shifts. Trade-off: a query needs a known field, search doesn't.
 - `find` fuses BM25 with link-graph expansion; the `via` column says what produced each row —
   `match` (terms hit), `link` (connected to notes that hit), `match+link` (both).
 - `--where` takes a frontmatter condition against alias `f`, e.g. `"f.status = 'active' AND has(f.tags, 'x')"`.
@@ -66,15 +71,18 @@ sense query "SELECT j.value, COUNT(*) n FROM frontmatter, json_each(frontmatter.
 - Rank with `ORDER BY bm25(content, 10.0, 5.0, 1.0)` (title > summary > body); excerpt with
   `snippet(content, -1, '«', '»', '…', 10)`.
 - Select `content.title`/`content.summary` (always exist, empty when absent) rather than
-  `f.title`/`f.summary` (discovered columns — error on vaults that never declare them).
+  `f.title`/`f.summary` (discovered columns — error on trees that never declare them).
 - `has(field, value)`: array membership on JSON-array fields, substring on strings, false on NULL.
   To aggregate per member instead, use `json_each(frontmatter.<field>)` (above) -- GROUP BY on the
   raw column splits `["a","b"]` and `["b","a"]` into separate buckets.
 - Date fields are stored as written. Compare through `datetime()`, which normalizes ISO 8601
-  timezone offsets to UTC: `WHERE datetime(dateCreated) >= datetime(?)`. Bare string comparison
+  timezone offsets to UTC: `WHERE datetime(created) >= datetime(?)`. Bare string comparison
   is only safe when every note uses the same offset.
-- Never `SELECT text FROM content` — that is the whole vault into context. `SELECT * FROM
-  frontmatter` is safe; prose is not a frontmatter column. Always `LIMIT`.
+- To bound what a query puts into context: `snippet()` excerpts just the matching text,
+  `LIMIT` caps row counts, and selecting `path`/`title`/`summary` keeps rows small.
+  `SELECT text FROM content` returns the tree's entire prose (sense warns past 50 KB).
+  Aggregates (`COUNT`, `GROUP BY`) are already bounded. `SELECT * FROM frontmatter` is always
+  safe — prose is not a frontmatter column.
 
 Worked traces: [EXAMPLES.md](EXAMPLES.md).
 
@@ -83,9 +91,10 @@ Worked traces: [EXAMPLES.md](EXAMPLES.md).
 - Missing CLI: `npm install -g sensemaking`. Missing config: `sense init` at the tree root.
   Discovery walks up from cwd; `--config <path>` overrides.
 - Save a query into `sense.config.json` only when it will be reused; run ad-hoc otherwise.
-- When writing notes, give each a one-line `summary:` — it appears in every result row and is a
-  weighted search field. Write date fields as ISO 8601 (`2026-08-12`, or with time and offset) —
-  the only format SQL date comparisons understand.
+- A one-line `summary:` per note is optional and pays twice: it appears in result rows and is a
+  weighted search field. Date comparisons work for dates written as ISO 8601 (`2026-08-12`, or
+  with time and offset) — the only format `datetime()` parses. Field names in examples
+  (`status`, `tags`, `created`) are illustrative; your tree defines its own.
 - Reserved frontmatter keys (dropped with a warning): `path`, `_mtime`, `_size`, `_rank`,
   `content`, `links`, `sections`.
 - Exit codes: `0` ok, `1` error (SQLite message verbatim), `2` usage (unknown query, wrong

package/dist/cjs/commands/vault.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/commands/vault.ts"],"sourcesContent":["import type { ResolvedConfig } from '../config.ts';\nimport type { OpenResult } from '../db.ts';\nimport { open } from '../db.ts';\nimport type { Row } from '../output.ts';\nimport { printRows } from '../output.ts';\nimport type { Ctx } from './types.ts';\n\n// Shared open-query-close envelope for commands that touch the vault.\n\nexport function printWarnings(warnings: string[]): void {\n  for (const w of warnings) console.warn(w);\n}\n\nexport function withVault(ctx: Ctx, fn: (db: OpenResult['db'], cfg: ResolvedConfig) => void): void {\n  const cfg = ctx.resolveConfig();\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n  try {\n    fn(db, cfg);\n  } finally {\n    db.close();\n  }\n}\n\n// An unbound `?` silently binds NULL, so mismatched param counts fail loudly instead.\nexport function runSql(cfg: ResolvedConfig, sql: string, params: string[], format: 'table' | 'json', label: string): void {\n  const placeholderCount = (sql.match(/\\?/g) ?? []).length;\n  if (params.length !== placeholderCount) {\n    console.error(`${label} expects ${placeholderCount} parameter(s), got ${params.length}`);\n    process.exit(2);\n  }\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n  printRows(db.prepare(sql).all(...params) as Row[], format);\n  db.close();\n}\n"],"names":["printWarnings","runSql","withVault","warnings","w","console","warn","ctx","fn","cfg","resolveConfig","open","db","close","sql","params","format","label","placeholderCount","match","length","error","process","exit","printRows","prepare","all"],"mappings":";;;;;;;;;;;QASgBA;eAAAA;;QAgBAC;eAAAA;;QAZAC;eAAAA;;;oBAXK;wBAEK;;;;;;;;;;;;;;;;;;;;;;;;;;AAKnB,SAASF,cAAcG,QAAkB;QACzC,kCAAA,2BAAA;;QAAL,QAAK,YAAWA,6BAAX,SAAA,6BAAA,QAAA,yBAAA;YAAA,IAAMC,IAAN;YAAqBC,QAAQC,IAAI,CAACF;;;QAAlC;QAAA;;;iBAAA,6BAAA;gBAAA;;;gBAAA;sBAAA;;;;AACP;AAEO,SAASF,UAAUK,GAAQ,EAAEC,EAAuD;IACzF,IAAMC,MAAMF,IAAIG,aAAa;IAC7B,IAAyBC,QAAAA,IAAAA,UAAI,EAACF,MAAtBG,KAAiBD,MAAjBC,IAAIT,WAAaQ,MAAbR;IACZH,cAAcG;IACd,IAAI;QACFK,GAAGI,IAAIH;IACT,SAAU;QACRG,GAAGC,KAAK;IACV;AACF;AAGO,SAASZ,OAAOQ,GAAmB,EAAEK,GAAW,EAAEC,MAAgB,EAAEC,MAAwB,EAAEC,KAAa;QAQtGL;QAPgBE;IAA1B,IAAMI,mBAAmB,EAACJ,aAAAA,IAAIK,KAAK,CAAC,oBAAVL,wBAAAA,aAAoB,EAAE,EAAEM,MAAM;IACxD,IAAIL,OAAOK,MAAM,KAAKF,kBAAkB;QACtCb,QAAQgB,KAAK,CAAC,AAAC,GAAmBH,OAAjBD,OAAM,aAAiDF,OAAtCG,kBAAiB,uBAAmC,OAAdH,OAAOK,MAAM;QACrFE,QAAQC,IAAI,CAAC;IACf;IACA,IAAyBZ,QAAAA,IAAAA,UAAI,EAACF,MAAtBG,KAAiBD,MAAjBC,IAAIT,WAAaQ,MAAbR;IACZH,cAAcG;IACdqB,IAAAA,mBAAS,EAACZ,CAAAA,cAAAA,GAAGa,OAAO,CAACX,MAAKY,GAAG,OAAnBd,aAAoB,qBAAGG,UAAkBC;IACnDJ,GAAGC,KAAK;AACV"}

package/dist/esm/commands/vault.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/commands/vault.ts"],"sourcesContent":["import type { ResolvedConfig } from '../config.ts';\nimport type { OpenResult } from '../db.ts';\nimport { open } from '../db.ts';\nimport type { Row } from '../output.ts';\nimport { printRows } from '../output.ts';\nimport type { Ctx } from './types.ts';\n\n// Shared open-query-close envelope for commands that touch the vault.\n\nexport function printWarnings(warnings: string[]): void {\n  for (const w of warnings) console.warn(w);\n}\n\nexport function withVault(ctx: Ctx, fn: (db: OpenResult['db'], cfg: ResolvedConfig) => void): void {\n  const cfg = ctx.resolveConfig();\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n  try {\n    fn(db, cfg);\n  } finally {\n    db.close();\n  }\n}\n\n// An unbound `?` silently binds NULL, so mismatched param counts fail loudly instead.\nexport function runSql(cfg: ResolvedConfig, sql: string, params: string[], format: 'table' | 'json', label: string): void {\n  const placeholderCount = (sql.match(/\\?/g) ?? []).length;\n  if (params.length !== placeholderCount) {\n    console.error(`${label} expects ${placeholderCount} parameter(s), got ${params.length}`);\n    process.exit(2);\n  }\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n  printRows(db.prepare(sql).all(...params) as Row[], format);\n  db.close();\n}\n"],"names":["open","printRows","printWarnings","warnings","w","console","warn","withVault","ctx","fn","cfg","resolveConfig","db","close","runSql","sql","params","format","label","placeholderCount","match","length","error","process","exit","prepare","all"],"mappings":"AAEA,SAASA,IAAI,QAAQ,WAAW;AAEhC,SAASC,SAAS,QAAQ,eAAe;AAGzC,sEAAsE;AAEtE,OAAO,SAASC,cAAcC,QAAkB;IAC9C,KAAK,MAAMC,KAAKD,SAAUE,QAAQC,IAAI,CAACF;AACzC;AAEA,OAAO,SAASG,UAAUC,GAAQ,EAAEC,EAAuD;IACzF,MAAMC,MAAMF,IAAIG,aAAa;IAC7B,MAAM,EAAEC,EAAE,EAAET,QAAQ,EAAE,GAAGH,KAAKU;IAC9BR,cAAcC;IACd,IAAI;QACFM,GAAGG,IAAIF;IACT,SAAU;QACRE,GAAGC,KAAK;IACV;AACF;AAEA,sFAAsF;AACtF,OAAO,SAASC,OAAOJ,GAAmB,EAAEK,GAAW,EAAEC,MAAgB,EAAEC,MAAwB,EAAEC,KAAa;QACtFH;IAA1B,MAAMI,mBAAmB,EAACJ,aAAAA,IAAIK,KAAK,CAAC,oBAAVL,wBAAAA,aAAoB,EAAE,EAAEM,MAAM;IACxD,IAAIL,OAAOK,MAAM,KAAKF,kBAAkB;QACtCd,QAAQiB,KAAK,CAAC,GAAGJ,MAAM,SAAS,EAAEC,iBAAiB,mBAAmB,EAAEH,OAAOK,MAAM,EAAE;QACvFE,QAAQC,IAAI,CAAC;IACf;IACA,MAAM,EAAEZ,EAAE,EAAET,QAAQ,EAAE,GAAGH,KAAKU;IAC9BR,cAAcC;IACdF,UAAUW,GAAGa,OAAO,CAACV,KAAKW,GAAG,IAAIV,SAAkBC;IACnDL,GAAGC,KAAK;AACV"}