sensemaking 0.7.1 → 0.8.0

package/README.md

@@ -29,7 +29,7 @@ sense query "SELECT path FROM frontmatter WHERE has(tags, ?)" urgent
 
 ## Model
 
-Every file becomes rows in four tables:
+Every file becomes rows in these tables, plus whatever an enabled feature adds of its own:
 
 | table | holds | for |
 |---|---|---|
@@ -43,8 +43,9 @@ afterward through the filesystem, scoped to the line ranges `peek` returns. This
 [just-in-time context pattern](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents):
 the agent holds lightweight identifiers and loads payloads only when needed.
 
-Measured costs: a `find` row is ~20–40 tokens, a `peek` is ~17% of reading the file, and the
-section it points at is a direct `Read` range.
+Output size is a contract, measured per release ([BENCHMARKING.md](BENCHMARKING.md)): `map` is
+fixed-size, a `find` row is tens of tokens, and a `peek` stays flat however large the note is —
+so what it saves over reading grows with the file, and a small note is cheaper read whole.
 
 ```sql
 -- filter and search compose in one query
@@ -54,22 +55,29 @@ WHERE f.status = 'active' AND content MATCH 'revenue'
 ORDER BY bm25(content, 10.0, 5.0, 1.0) LIMIT 10
 ```
 
-## Verbs
+## Commands
 
-| verb | does |
+| command | does |
 |---|---|
 | `map` | doc count, frontmatter field coverage, top hubs by link rank, recent changes |
 | `find "<terms>" [--where "<sql>"] [--k n] [--semantic]` | BM25 + link-graph expansion, fused; `via` marks each row `match`, `link`, or `match+link` |
-| `peek <path>` | frontmatter + heading outline (`[L143-162, ~380t]`) + links both ways, capped at 20 per list |
-| `query "<sql>" [params...]` | ad-hoc SQL over all four tables; `?` binds positional args |
+| `peek <path>` | frontmatter + heading outline (`[L143-162, ~380t]`) + links both ways — first 20 per list, each with its total; the `links` table has the rest |
+| `query "<sql>" [params...]` | ad-hoc SQL over all the tables; `?` binds positional args |
+| `<name> [params...]` | run a query saved in the config; `--list` names them |
+| `init` | write a starter `sense.config.json` |
+| `status` | index location, doc count, feature state, watcher heartbeat |
+| `check` | prepare and run the saved queries, so a broken one fails here instead of mid-task |
+| `rebuild` | delete the cache and re-crawl |
+| `watch` | keep the index warm in the background (optional; see [WATCH.md](WATCH.md)) |
 
 `find` seeds a personalized-PageRank walk with the BM25 matches, so a note that never contains
 the terms but is linked from ones that do still surfaces. Terms pass verbatim to FTS5 `MATCH`
-(bare words AND-join; operators are yours to write). `--where` takes a frontmatter condition
-against alias `f`. On trees with the `embed` feature, `--semantic` additionally expands by
-meaning — explicit per query, never silent; rows it adds are labeled `via: vector` and carry a
-`lines` column pointing at the best-matching section.
-`--format json` on any verb returns structured output.
+(bare words AND-join; operators are yours to write). `--where` takes any SQL condition against
+frontmatter alias `f`. On trees with the `embed` feature, `--semantic` additionally expands by
+meaning — explicit per query, never silent; rows it adds are labeled `via: vector` and carry
+`similarity` (cosine against the best-matching chunk). A `lines` column points at the section
+that earned a row — a direct read range. `--format json` on any command returns structured
+output; `--version` and `--help` do what they say.
 
 ## Config
 
@@ -82,46 +90,55 @@ meaning — explicit per query, never silent; rows it adds are labeled `via: vec
   "version": 2,
   "scan": { "include": ["**/*.md"] },
   "features": { "links": true, "sections": true, "rank": true },
+  "defaults": { "find": { "where": "f.type != 'generated'" } },
   "queries": {
-    "by-tag": "SELECT path, title FROM frontmatter WHERE has(tags, ?) ORDER BY path"
-  }
+    "dead-links": "SELECT src, target FROM links WHERE dst IS NULL",
+    "by-tag": "SELECT path, title FROM frontmatter WHERE has(tags, ?) ORDER BY path",
+    "hot": { "find": "pricing OR billing", "k": 20 }
+  },
+  "checks": { "dead-links": "empty" }
 }
 ```
 
-Features toggle independently; disabling one degrades its verb instead of failing it (`find`
+A query entry is a SQL string, or a saved `find` with its settings baked in — `sense hot`
+then needs no flags. `defaults.find.where` scopes `find` tree-wide (an explicit `--where`
+replaces it, so `--where "1=1"` always reaches everything). `checks` turns a saved query
+into an assertion: `sense check` fails when a query marked `empty` returns rows. Every key
+is documented in [schema.json](schema.json), which editors read for autocomplete.
+
+Features toggle independently; disabling one degrades its command instead of failing it (`find`
 goes BM25-only without `links`, `map` drops hubs without `rank`, `peek` drops the outline
 without `sections`). Toggling rebuilds the cache. Older config versions auto-migrate on load,
 noted on stderr.
 
-`embed` is the one opt-in feature (absent = off; most trees don't need vectors): `"embed": true`
-uses the built-in static model (downloaded to `~/.cache/sensemaking` on first use, never in the
-package), or `{ "model", "type": "static"|"api", "url", "key" }` points at any Model2Vec model,
+`embed` is opt-in — the only feature off by default, since most trees don't need vectors.
+`"embed": true` uses the built-in static model (downloaded to `~/.cache/sensemaking` on first
+use, never in the package), or `{ "model", "type": "static"|"api", "url", "key" }` points at any Model2Vec model,
 local path, or OpenAI-compatible endpoint (Ollama, LM Studio, hosted). With it on, vectors stay
 fresh at reconcile and `find --semantic` uses them; default `find` results are unchanged.
 
-## Reference
-
-- `has(field, value)` — the one custom SQL function: array membership on JSON-array fields,
-  substring on strings (so `has(f.status, 'active')` also matches `inactive`), false on missing
-  keys. Exact matches: `=` for scalars, `EXISTS (SELECT 1 FROM json_each(f.tags) WHERE value = ?)`
-  for array members.
-- Reserved frontmatter keys (dropped with a warning): `path`, `_mtime`, `_size`, `_rank`,
-  `content`, `links`, `sections`.
-- FTS5 syntax in `MATCH`: `a OR b`, `"phrase"`, `pref*`, `NEAR(a b, 5)`, `summary: term`.
-  Stemmed; markdown is stripped at index time. `bm25(content, 10.0, 5.0, 1.0)` weights title
-  over summary over body.
-- A one-line `summary:` in frontmatter is both a selectable column and a weighted search field.
-- Exit codes: `0` ok, `1` error (SQLite message verbatim), `2` usage.
-- Frontmatter parsing is lenient: syntax errors (an alias starting with `@`, say) are per-file
-  warnings and the values are still indexed.
+`has(field, value)` is the one custom SQL function: array membership on JSON-array fields,
+substring on strings, false on missing keys. Frontmatter parsing is lenient — syntax errors are
+per-file warnings and the values are still indexed, so one bad note never costs you the crawl.
 
 ## Scale
 
 Every query starts with a freshness check against the cache in `.sense/`; only changed files are
-re-parsed. Measured per release in [BENCHMARKING.md](BENCHMARKING.md) — at 6,566 notes: full
-crawl ~5 s, warm query ~100 ms, one-file change ~200 ms. `sense watch` (optional) moves
-re-parsing into the background — see [WATCH.md](WATCH.md). `sense rebuild` deletes the cache and
-re-crawls.
+re-parsed. What to expect as a tree grows:
+
+- **Work is linear in note count** — crawl, reconcile, and the freshness check every invocation
+  pays. That check is the floor cost of a query and the first thing to watch on a large tree.
+- **Output is flat.** `map`, `peek`, and a `find` row cost the same on a small tree as a large
+  one: context cost is bounded by what you ask for, not by how much there is.
+- **Bulk changes are paid by whoever queries next.** `sense watch` moves that re-parse into the
+  background ([WATCH.md](WATCH.md)) — it changes latency, never answers, since every query
+  reconciles for itself. `sense rebuild` starts the cache over.
+
+These are release gates rather than hopes: every release regenerates the numbers on pinned
+corpora spanning a 4x range in note count plus a stress tree that packs the worst measured
+shapes into one place — a megabyte-scale note, heading-dense outlines, dense link graphs,
+hundreds of frontmatter fields. A row that grows faster than linearly, or a token count
+that grows at all, blocks the release. Current figures: [BENCHMARKING.md](BENCHMARKING.md).
 
 ## For AI agents
 
@@ -129,14 +146,15 @@ re-crawls.
 npx skills add kmalakoff/sensemaking   # -g for global, -a claude-code to target
 ```
 
-The skill teaches the descent: `map` to orient, `find` to locate, `peek` before reading,
-`Read` line ranges instead of files.
+Two skills: `sense` for querying a tree — what each command is for, FTS5 syntax, reading the
+`via`/`score`/`similarity` columns, worked examples — and `sense-setup` for making one, where
+features, frontmatter conventions, and note size are decisions with consequences either way.
 
 ## Prior art
 
 - [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
   (Anthropic): agents should hold lightweight identifiers — file paths, links — and load payloads
-  just in time, because context is a finite resource. The four verbs implement that pattern as a CLI.
+  just in time, because context is a finite resource. The commands implement that pattern as a CLI.
 - [llm-wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) (Karpathy): an
   agent-maintained wiki navigated by an `index.md` and links, which he notes needs real search
   infrastructure past a few hundred pages. `sense map` derives that index from the notes instead of
@@ -154,7 +172,9 @@ The skill teaches the descent: `map` to orient, `find` to locate, `peek` before
 
 Dependencies: [yaml](https://github.com/eemeli/yaml),
 [remove-markdown](https://github.com/zuchka/remove-markdown),
-[fast-glob](https://github.com/mrmlnc/fast-glob), and Node's built-in SQLite. No native builds.
+[fast-glob](https://github.com/mrmlnc/fast-glob),
+[@huggingface/tokenizers](https://github.com/huggingface/tokenizers.js) (pure JS), and Node's
+built-in SQLite. No native builds.
 
 ## License
 

package/dist/cjs/cli/check.js

@@ -0,0 +1,386 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "default", {
+    enumerable: true,
+    get: function() {
+        return _default;
+    }
+});
+var _commandsts = require("../commands.js");
+var _configts = require("../config.js");
+var _dbts = require("../db.js");
+var _outputts = require("../output.js");
+var _sharedts = require("./shared.js");
+function _array_like_to_array(arr, len) {
+    if (len == null || len > arr.length) len = arr.length;
+    for(var i = 0, arr2 = new Array(len); i < len; i++)arr2[i] = arr[i];
+    return arr2;
+}
+function _array_with_holes(arr) {
+    if (Array.isArray(arr)) return arr;
+}
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _iterable_to_array_limit(arr, i) {
+    var _i = arr == null ? null : typeof Symbol !== "undefined" && arr[Symbol.iterator] || arr["@@iterator"];
+    if (_i == null) return;
+    var _arr = [];
+    var _n = true;
+    var _d = false;
+    var _s, _e;
+    try {
+        for(_i = _i.call(arr); !(_n = (_s = _i.next()).done); _n = true){
+            _arr.push(_s.value);
+            if (i && _arr.length === i) break;
+        }
+    } catch (err) {
+        _d = true;
+        _e = err;
+    } finally{
+        try {
+            if (!_n && _i["return"] != null) _i["return"]();
+        } finally{
+            if (_d) throw _e;
+        }
+    }
+    return _arr;
+}
+function _non_iterable_rest() {
+    throw new TypeError("Invalid attempt to destructure non-iterable instance.\\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method.");
+}
+function _sliced_to_array(arr, i) {
+    return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array(arr, i) || _non_iterable_rest();
+}
+function _unsupported_iterable_to_array(o, minLen) {
+    if (!o) return;
+    if (typeof o === "string") return _array_like_to_array(o, minLen);
+    var n = Object.prototype.toString.call(o).slice(8, -1);
+    if (n === "Object" && o.constructor) n = o.constructor.name;
+    if (n === "Map" || n === "Set") return Array.from(n);
+    if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+// A saved query that returns zero rows looks identical to a true empty result, so a broken
+// one can sit unnoticed -- one field report had `WHERE flag = 'true'` against a numeric
+// column reading as "nothing tagged yet" for hours. Preparing each query catches syntax and
+// unknown-column errors without executing it; queries that take no parameters are also run
+// for a row count. Parameterised queries are validated but not counted: inventing arguments
+// would report a count for a query nobody ran. Saved finds run lexically with k=1 -- that
+// validates the `where` fragment and the FTS5 terms against the real schema, the same
+// breakage class prepare() catches for SQL strings -- but never semantically (a --semantic
+// pass costs model time and, on api trees, network); `semantic: true` is only checked for
+// a features.embed to run against.
+var check = function check(ctx) {
+    return _async_to_generator(function() {
+        var _cfg_queries, cfg, _open, db, warnings, rows, failed, _iteratorNormalCompletion, _didIteratorError, _iteratorError, _iterator, _step, _step_value, name, entry, _sql_match, _cfg_checks, count, err, sql, params, expectEmpty, statement, count1, err1;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    cfg = ctx.resolveConfig();
+                    _open = (0, _dbts.open)(cfg), db = _open.db, warnings = _open.warnings;
+                    (0, _sharedts.printWarnings)(warnings);
+                    rows = [];
+                    failed = 0;
+                    _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;
+                    _state.label = 1;
+                case 1:
+                    _state.trys.push([
+                        1,
+                        10,
+                        11,
+                        12
+                    ]);
+                    _iterator = Object.entries((_cfg_queries = cfg.queries) !== null && _cfg_queries !== void 0 ? _cfg_queries : {})[Symbol.iterator]();
+                    _state.label = 2;
+                case 2:
+                    if (!!(_iteratorNormalCompletion = (_step = _iterator.next()).done)) return [
+                        3,
+                        9
+                    ];
+                    _step_value = _sliced_to_array(_step.value, 2), name = _step_value[0], entry = _step_value[1];
+                    if (!(typeof entry !== 'string')) return [
+                        3,
+                        7
+                    ];
+                    if (entry.semantic && !(0, _configts.featureEnabled)(cfg, 'embed')) {
+                        failed++;
+                        rows.push({
+                            query: name,
+                            params: '—',
+                            rows: '—',
+                            status: 'FAILED: semantic requested but features.embed is off'
+                        });
+                        return [
+                            3,
+                            8
+                        ];
+                    }
+                    _state.label = 3;
+                case 3:
+                    _state.trys.push([
+                        3,
+                        5,
+                        ,
+                        6
+                    ]);
+                    return [
+                        4,
+                        (0, _commandsts.find)(db, cfg, entry.find, {
+                            k: 1,
+                            where: entry.where
+                        })
+                    ];
+                case 4:
+                    count = _state.sent().length;
+                    rows.push({
+                        query: name,
+                        params: '—',
+                        rows: '—',
+                        status: count === 0 ? 'ok, but matches 0 notes (lexical probe)' : entry.semantic ? 'ok (lexical probe; semantic not run)' : 'ok (probe run with k=1)'
+                    });
+                    return [
+                        3,
+                        6
+                    ];
+                case 5:
+                    err = _state.sent();
+                    failed++;
+                    rows.push({
+                        query: name,
+                        params: '—',
+                        rows: '—',
+                        status: "FAILED: ".concat(err.message)
+                    });
+                    return [
+                        3,
+                        6
+                    ];
+                case 6:
+                    return [
+                        3,
+                        8
+                    ];
+                case 7:
+                    sql = entry;
+                    params = ((_sql_match = sql.match(/\?/g)) !== null && _sql_match !== void 0 ? _sql_match : []).length;
+                    expectEmpty = ((_cfg_checks = cfg.checks) === null || _cfg_checks === void 0 ? void 0 : _cfg_checks[name]) === 'empty';
+                    try {
+                        statement = db.prepare(sql);
+                        if (params > 0) {
+                            rows.push({
+                                query: name,
+                                params: params,
+                                rows: '—',
+                                status: 'ok (not run: needs parameters)'
+                            });
+                            return [
+                                3,
+                                8
+                            ];
+                        }
+                        count1 = statement.all().length;
+                        if (expectEmpty) {
+                            // An invariant query: rows are violations, so 0 is the pass, anything else fails.
+                            if (count1 > 0) failed++;
+                            rows.push({
+                                query: name,
+                                params: params,
+                                rows: count1,
+                                status: count1 === 0 ? 'ok (empty, as asserted)' : "FAILED: expected empty, returned ".concat(count1, " row(s)")
+                            });
+                        } else {
+                            rows.push({
+                                query: name,
+                                params: params,
+                                rows: count1,
+                                status: count1 === 0 ? 'ok, but returns 0 rows' : 'ok'
+                            });
+                        }
+                    } catch (err) {
+                        failed++;
+                        rows.push({
+                            query: name,
+                            params: params,
+                            rows: '—',
+                            status: "FAILED: ".concat(err.message)
+                        });
+                    }
+                    _state.label = 8;
+                case 8:
+                    _iteratorNormalCompletion = true;
+                    return [
+                        3,
+                        2
+                    ];
+                case 9:
+                    return [
+                        3,
+                        12
+                    ];
+                case 10:
+                    err1 = _state.sent();
+                    _didIteratorError = true;
+                    _iteratorError = err1;
+                    return [
+                        3,
+                        12
+                    ];
+                case 11:
+                    try {
+                        if (!_iteratorNormalCompletion && _iterator.return != null) {
+                            _iterator.return();
+                        }
+                    } finally{
+                        if (_didIteratorError) {
+                            throw _iteratorError;
+                        }
+                    }
+                    return [
+                        7
+                    ];
+                case 12:
+                    db.close();
+                    if (rows.length === 0) {
+                        console.log('no saved queries in config');
+                        return [
+                            2
+                        ];
+                    }
+                    (0, _outputts.printRows)(rows, ctx.format);
+                    if (failed > 0) process.exit(1);
+                    return [
+                        2
+                    ];
+            }
+        });
+    })();
+};
+var _default = check;
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/cli/check.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/check.ts"],"sourcesContent":["import { find } from '../commands.ts';\nimport { featureEnabled } from '../config.ts';\nimport { open } from '../db.ts';\nimport type { Row } from '../output.ts';\nimport { printRows } from '../output.ts';\nimport { printWarnings } from './shared.ts';\nimport type { Command } from './types.ts';\n\n// A saved query that returns zero rows looks identical to a true empty result, so a broken\n// one can sit unnoticed -- one field report had `WHERE flag = 'true'` against a numeric\n// column reading as \"nothing tagged yet\" for hours. Preparing each query catches syntax and\n// unknown-column errors without executing it; queries that take no parameters are also run\n// for a row count. Parameterised queries are validated but not counted: inventing arguments\n// would report a count for a query nobody ran. Saved finds run lexically with k=1 -- that\n// validates the `where` fragment and the FTS5 terms against the real schema, the same\n// breakage class prepare() catches for SQL strings -- but never semantically (a --semantic\n// pass costs model time and, on api trees, network); `semantic: true` is only checked for\n// a features.embed to run against.\nconst check: Command = async (ctx) => {\n  const cfg = ctx.resolveConfig();\n  const { db, warnings } = open(cfg);\n  printWarnings(warnings);\n\n  const rows: Row[] = [];\n  let failed = 0;\n  for (const [name, entry] of Object.entries(cfg.queries ?? {})) {\n    if (typeof entry !== 'string') {\n      if (entry.semantic && !featureEnabled(cfg, 'embed')) {\n        failed++;\n        rows.push({ query: name, params: '—', rows: '—', status: 'FAILED: semantic requested but features.embed is off' });\n        continue;\n      }\n      try {\n        const count = (await find(db, cfg, entry.find, { k: 1, where: entry.where })).length;\n        rows.push({ query: name, params: '—', rows: '—', status: count === 0 ? 'ok, but matches 0 notes (lexical probe)' : entry.semantic ? 'ok (lexical probe; semantic not run)' : 'ok (probe run with k=1)' });\n      } catch (err) {\n        failed++;\n        rows.push({ query: name, params: '—', rows: '—', status: `FAILED: ${(err as Error).message}` });\n      }\n      continue;\n    }\n    const sql = entry;\n    const params = (sql.match(/\\?/g) ?? []).length;\n    const expectEmpty = cfg.checks?.[name] === 'empty';\n    try {\n      const statement = db.prepare(sql);\n      if (params > 0) {\n        rows.push({ query: name, params, rows: '—', status: 'ok (not run: needs parameters)' });\n        continue;\n      }\n      const count = (statement.all() as unknown[]).length;\n      if (expectEmpty) {\n        // An invariant query: rows are violations, so 0 is the pass, anything else fails.\n        if (count > 0) failed++;\n        rows.push({ query: name, params, rows: count, status: count === 0 ? 'ok (empty, as asserted)' : `FAILED: expected empty, returned ${count} row(s)` });\n      } else {\n        rows.push({ query: name, params, rows: count, status: count === 0 ? 'ok, but returns 0 rows' : 'ok' });\n      }\n    } catch (err) {\n      failed++;\n      rows.push({ query: name, params, rows: '—', status: `FAILED: ${(err as Error).message}` });\n    }\n  }\n\n  db.close();\n  if (rows.length === 0) {\n    console.log('no saved queries in config');\n    return;\n  }\n  printRows(rows, ctx.format);\n  if (failed > 0) process.exit(1);\n};\nexport default check;\n"],"names":["check","ctx","cfg","open","db","warnings","rows","failed","name","entry","sql","count","err","params","expectEmpty","statement","resolveConfig","printWarnings","Object","entries","queries","semantic","featureEnabled","push","query","status","find","k","where","length","message","match","checks","prepare","all","close","console","log","printRows","format","process","exit"],"mappings":";;;;+BAwEA;;;eAAA;;;0BAxEqB;wBACU;oBACV;wBAEK;wBACI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAG9B,2FAA2F;AAC3F,wFAAwF;AACxF,4FAA4F;AAC5F,2FAA2F;AAC3F,4FAA4F;AAC5F,0FAA0F;AAC1F,sFAAsF;AACtF,2FAA2F;AAC3F,0FAA0F;AAC1F,mCAAmC;AACnC,IAAMA,QAAiB,eAAOC;;YAOeC,cANrCA,KACmBC,OAAjBC,IAAIC,UAGNC,MACFC,QACC,2BAAA,mBAAA,gBAAA,WAAA,oBAAOC,MAAMC,OAiBAC,YACIR,aAVVS,OAECC,KAMLF,KACAG,QACAC,aAEEC,WAKAJ;;;;oBA/BJT,MAAMD,IAAIe,aAAa;oBACJb,QAAAA,IAAAA,UAAI,EAACD,MAAtBE,KAAiBD,MAAjBC,IAAIC,WAAaF,MAAbE;oBACZY,IAAAA,uBAAa,EAACZ;oBAERC;oBACFC,SAAS;oBACR,kCAAA,2BAAA;;;;;;;;;oBAAA,YAAuBW,OAAOC,OAAO,EAACjB,eAAAA,IAAIkB,OAAO,cAAXlB,0BAAAA,eAAe,CAAC;;;2BAAtD,6BAAA,QAAA;;;;mDAAA,iBAAOM,uBAAMC;yBACZ,CAAA,OAAOA,UAAU,QAAO,GAAxB;;;;oBACF,IAAIA,MAAMY,QAAQ,IAAI,CAACC,IAAAA,wBAAc,EAACpB,KAAK,UAAU;wBACnDK;wBACAD,KAAKiB,IAAI,CAAC;4BAAEC,OAAOhB;4BAAMK,QAAQ;4BAAKP,MAAM;4BAAKmB,QAAQ;wBAAuD;wBAChH;;;;oBACF;;;;;;;;;oBAEiB;;wBAAMC,IAAAA,gBAAI,EAACtB,IAAIF,KAAKO,MAAMiB,IAAI,EAAE;4BAAEC,GAAG;4BAAGC,OAAOnB,MAAMmB,KAAK;wBAAC;;;oBAApEjB,QAAQ,AAAC,cAA+DkB,MAAM;oBACpFvB,KAAKiB,IAAI,CAAC;wBAAEC,OAAOhB;wBAAMK,QAAQ;wBAAKP,MAAM;wBAAKmB,QAAQd,UAAU,IAAI,4CAA4CF,MAAMY,QAAQ,GAAG,yCAAyC;oBAA0B;;;;;;oBAChMT;oBACPL;oBACAD,KAAKiB,IAAI,CAAC;wBAAEC,OAAOhB;wBAAMK,QAAQ;wBAAKP,MAAM;wBAAKmB,QAAQ,AAAC,WAAiC,OAAvB,AAACb,IAAckB,OAAO;oBAAG;;;;;;oBAE/F;;;;;oBAEIpB,MAAMD;oBACNI,SAAS,EAACH,aAAAA,IAAIqB,KAAK,CAAC,oBAAVrB,wBAAAA,iBAAwBmB,MAAM;oBACxCf,cAAcZ,EAAAA,cAAAA,IAAI8B,MAAM,cAAV9B,kCAAAA,WAAY,CAACM,KAAK,MAAK;oBAC3C,IAAI;wBACIO,YAAYX,GAAG6B,OAAO,CAACvB;wBAC7B,IAAIG,SAAS,GAAG;4BACdP,KAAKiB,IAAI,CAAC;gCAAEC,OAAOhB;gCAAMK,QAAAA;gCAAQP,MAAM;gCAAKmB,QAAQ;4BAAiC;4BACrF;;;;wBACF;wBACMd,SAAQ,AAACI,UAAUmB,GAAG,GAAiBL,MAAM;wBACnD,IAAIf,aAAa;4BACf,kFAAkF;4BAClF,IAAIH,SAAQ,GAAGJ;4BACfD,KAAKiB,IAAI,CAAC;gCAAEC,OAAOhB;gCAAMK,QAAAA;gCAAQP,MAAMK;gCAAOc,QAAQd,WAAU,IAAI,4BAA4B,AAAC,oCAAyC,OAANA,QAAM;4BAAS;wBACrJ,OAAO;4BACLL,KAAKiB,IAAI,CAAC;gCAAEC,OAAOhB;gCAAMK,QAAAA;gCAAQP,MAAMK;gCAAOc,QAAQd,WAAU,IAAI,2BAA2B;4BAAK;wBACtG;oBACF,EAAE,OAAOC,KAAK;wBACZL;wBACAD,KAAKiB,IAAI,CAAC;4BAAEC,OAAOhB;4BAAMK,QAAAA;4BAAQP,MAAM;4BAAKmB,QAAQ,AAAC,WAAiC,OAAvB,AAACb,IAAckB,OAAO;wBAAG;oBAC1F;;;oBApCG;;;;;;;;;;;;oBAAA;oBAAA;;;;;;;6BAAA,6BAAA;4BAAA;;;4BAAA;kCAAA;;;;;;;oBAuCL1B,GAAG+B,KAAK;oBACR,IAAI7B,KAAKuB,MAAM,KAAK,GAAG;wBACrBO,QAAQC,GAAG,CAAC;wBACZ;;;oBACF;oBACAC,IAAAA,mBAAS,EAAChC,MAAML,IAAIsC,MAAM;oBAC1B,IAAIhC,SAAS,GAAGiC,QAAQC,IAAI,CAAC;;;;;;IAC/B;;IACA,WAAezC"}

package/dist/cjs/{commands → cli}/find.js

@@ -8,8 +8,8 @@ Object.defineProperty(exports, "default", {
         return _default;
     }
 });
+var _commandsts = require("../commands.js");
 var _outputts = require("../output.js");
-var _verbsts = require("../verbs.js");
 var _sharedts = require("./shared.js");
 function _array_like_to_array(arr, len) {
     if (len == null || len > arr.length) len = arr.length;
@@ -193,8 +193,7 @@ var findCmd = function findCmd(ctx) {
                 case 0:
                     _ctx_rest = _sliced_to_array(ctx.rest, 1), terms = _ctx_rest[0];
                     if (!terms) ctx.usageError("usage: ".concat(ctx.name, ' find "<terms>" [--where "<sql>"] [--k n] [--semantic]'));
-                    k = ctx.values.k === undefined ? undefined : Number.parseInt(ctx.values.k, 10);
-                    if (ctx.values.k !== undefined && !Number.isInteger(k)) ctx.usageError('--k expects an integer, got "'.concat(ctx.values.k, '"'));
+                    k = (0, _sharedts.parseK)(ctx);
                     return [
                         4,
                         (0, _sharedts.withDb)(ctx, function(db, cfg) {
@@ -204,7 +203,7 @@ var findCmd = function findCmd(ctx) {
                                         case 0:
                                             return [
                                                 4,
-                                                (0, _verbsts.find)(db, cfg, terms, {
+                                                (0, _commandsts.find)(db, cfg, terms, {
                                                     k: k,
                                                     where: ctx.values.where,
                                                     semantic: ctx.values.semantic

package/dist/cjs/cli/find.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/find.ts"],"sourcesContent":["import { find } from '../commands.ts';\nimport { printRows } from '../output.ts';\nimport { parseK, withDb } from './shared.ts';\nimport type { Command } from './types.ts';\n\nconst findCmd: Command = async (ctx) => {\n  const [terms] = ctx.rest;\n  if (!terms) ctx.usageError(`usage: ${ctx.name} find \"<terms>\" [--where \"<sql>\"] [--k n] [--semantic]`);\n  const k = parseK(ctx);\n  await withDb(ctx, async (db, cfg) => printRows(await find(db, cfg, terms, { k, where: ctx.values.where, semantic: ctx.values.semantic }), ctx.format));\n};\nexport default findCmd;\n"],"names":["findCmd","ctx","terms","k","rest","usageError","name","parseK","withDb","db","cfg","find","where","values","semantic","printRows","format"],"mappings":";;;;+BAWA;;;eAAA;;;0BAXqB;wBACK;wBACK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAG/B,IAAMA,UAAmB,iBAAOC;;YACdA,WAATC,OAEDC;;;;oBAFUF,6BAAAA,IAAIG,IAAI,MAAjBF,QAASD;oBAChB,IAAI,CAACC,OAAOD,IAAII,UAAU,CAAC,AAAC,UAAkB,OAATJ,IAAIK,IAAI,EAAC;oBACxCH,IAAII,IAAAA,gBAAM,EAACN;oBACjB;;wBAAMO,IAAAA,gBAAM,EAACP,KAAK,SAAOQ,IAAIC;;;;;4CAAkB;;gDAAMC,IAAAA,gBAAI,EAACF,IAAIC,KAAKR,OAAO;oDAAEC,GAAAA;oDAAGS,OAAOX,IAAIY,MAAM,CAACD,KAAK;oDAAEE,UAAUb,IAAIY,MAAM,CAACC,QAAQ;gDAAC;;;;;gDAAjGC,mBAAS;oDAAC;oDAA2Fd,IAAIe,MAAM;;;;;;;;;oBAApJ;;;;;;IACF;;IACA,WAAehB"}

package/dist/cjs/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/index.ts"],"sourcesContent":["import type { Command } from './types.ts';\n\n// Lazy registry: a command's imports load only when it runs, so a heavy dependency in one\n// command never taxes the others (or --version/--help). These names are reserved: a named\n// query in config can never shadow them.\nexport const COMMANDS: Record<string, () => Promise<{ default: Command }>> = {\n  init: () => import('./init.ts'),\n  watch: () => import('./watch.ts'),\n  status: () => import('./status.ts'),\n  check: () => import('./check.ts'),\n  rebuild: () => import('./rebuild.ts'),\n  query: () => import('./query.ts'),\n  find: () => import('./find.ts'),\n  map: () => import('./map.ts'),\n  peek: () => import('./peek.ts'),\n};\n\nexport type { Command, Ctx } from './types.ts';\n"],"names":["COMMANDS","init","watch","status","check","rebuild","query","find","map","peek"],"mappings":";;;;+BAKaA;;;eAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAN,IAAMA,WAAgE;IAC3EC,MAAM,SAANA;eAAY;2DAAA,QAAO;;;IACnBC,OAAO,SAAPA;eAAa;2DAAA,QAAO;;;IACpBC,QAAQ,SAARA;eAAc;2DAAA,QAAO;;;IACrBC,OAAO,SAAPA;eAAa;2DAAA,QAAO;;;IACpBC,SAAS,SAATA;eAAe;2DAAA,QAAO;;;IACtBC,OAAO,SAAPA;eAAa;2DAAA,QAAO;;;IACpBC,MAAM,SAANA;eAAY;2DAAA,QAAO;;;IACnBC,KAAK,SAALA;eAAW;2DAAA,QAAO;;;IAClBC,MAAM,SAANA;eAAY;2DAAA,QAAO;;;AACrB"}

package/dist/cjs/{commands → cli}/init.js

@@ -13,6 +13,9 @@ var init = function init(ctx) {
     var configPath = (0, _configts.initConfig)(process.cwd());
     console.log("created ".concat(configPath));
     console.log("query away: ".concat(ctx.name, ' query "SELECT path FROM frontmatter LIMIT 10"'));
+    // The decisions a new tree faces -- features, frontmatter conventions, note size -- are not
+    // in this output; name both places that hold them, since an agent may have neither.
+    console.log('features and tree design: the sense-setup skill, or schema.json');
 };
 var _default = init;
 /* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/cli/init.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/init.ts"],"sourcesContent":["import { initConfig } from '../config.ts';\nimport type { Command } from './types.ts';\n\nconst init: Command = (ctx) => {\n  const configPath = initConfig(process.cwd());\n  console.log(`created ${configPath}`);\n  console.log(`query away: ${ctx.name} query \"SELECT path FROM frontmatter LIMIT 10\"`);\n  // The decisions a new tree faces -- features, frontmatter conventions, note size -- are not\n  // in this output; name both places that hold them, since an agent may have neither.\n  console.log('features and tree design: the sense-setup skill, or schema.json');\n};\nexport default init;\n"],"names":["init","ctx","configPath","initConfig","process","cwd","console","log","name"],"mappings":";;;;+BAWA;;;eAAA;;;wBAX2B;AAG3B,IAAMA,OAAgB,cAACC;IACrB,IAAMC,aAAaC,IAAAA,oBAAU,EAACC,QAAQC,GAAG;IACzCC,QAAQC,GAAG,CAAC,AAAC,WAAqB,OAAXL;IACvBI,QAAQC,GAAG,CAAC,AAAC,eAAuB,OAATN,IAAIO,IAAI,EAAC;IACpC,4FAA4F;IAC5F,oFAAoF;IACpFF,QAAQC,GAAG,CAAC;AACd;IACA,WAAeP"}

package/dist/cjs/{commands → cli}/map.js

@@ -8,12 +8,12 @@ Object.defineProperty(exports, "default", {
         return _default;
     }
 });
+var _commandsts = require("../commands.js");
 var _outputts = require("../output.js");
-var _verbsts = require("../verbs.js");
 var _sharedts = require("./shared.js");
 var map = function map(ctx) {
     return (0, _sharedts.withDb)(ctx, function(db, cfg) {
-        var result = (0, _verbsts.mapTree)(db, cfg);
+        var result = (0, _commandsts.mapTree)(db, cfg);
         console.log(ctx.format === 'json' ? JSON.stringify(result, null, 2) : (0, _outputts.renderMap)(result));
     });
 };

package/dist/cjs/cli/map.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/map.ts"],"sourcesContent":["import { mapTree } from '../commands.ts';\nimport { renderMap } from '../output.ts';\nimport { withDb } from './shared.ts';\nimport type { Command } from './types.ts';\n\nconst map: Command = (ctx) =>\n  withDb(ctx, (db, cfg) => {\n    const result = mapTree(db, cfg);\n    console.log(ctx.format === 'json' ? JSON.stringify(result, null, 2) : renderMap(result));\n  });\nexport default map;\n"],"names":["map","ctx","withDb","db","cfg","result","mapTree","console","log","format","JSON","stringify","renderMap"],"mappings":";;;;+BAUA;;;eAAA;;;0BAVwB;wBACE;wBACH;AAGvB,IAAMA,MAAe,aAACC;WACpBC,IAAAA,gBAAM,EAACD,KAAK,SAACE,IAAIC;QACf,IAAMC,SAASC,IAAAA,mBAAO,EAACH,IAAIC;QAC3BG,QAAQC,GAAG,CAACP,IAAIQ,MAAM,KAAK,SAASC,KAAKC,SAAS,CAACN,QAAQ,MAAM,KAAKO,IAAAA,mBAAS,EAACP;IAClF;;IACF,WAAeL"}

package/dist/cjs/{commands → cli}/named.d.cts

@@ -1,2 +1,2 @@
 import type { Ctx } from './types.js';
-export default function named(ctx: Ctx, queryName: string, params: string[]): void;
+export default function named(ctx: Ctx, queryName: string, params: string[]): Promise<void>;