sensemaking 0.18.4 → 0.19.1

package/skills/sense-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sense-setup
-description: "Set up the sense CLI on a markdown tree and make the tree-design decisions that shape it: sense init, presets (which files, which settings, whether the scope searches by meaning), the embed block that names the model, and the trade-offs of frontmatter conventions, summaries, folder layout, and note size. Use when creating or restructuring a markdown knowledge base, running sense init, editing sense.config.json, choosing the backing store (sqlite or duckdb), configuring search scope or vectors, or deciding how notes should be written for an agent to query later."
+description: "Set up the sense CLI on a markdown tree and make the tree-design decisions that shape it: sense init, presets (which files, which settings, whether the scope searches by meaning), the embed block that names the model, and the trade-offs of frontmatter conventions, summaries, folder layout, and note size. Use when creating or restructuring a markdown knowledge base, running sense init, editing sense.config.json, choosing the backing store (sqlite, duckdb or turso), configuring search scope or vectors, or deciding how notes should be written for an agent to query later."
 ---
 
 # sense: setup and tree design
@@ -10,7 +10,7 @@ Querying an existing tree is the `sense` skill. This one covers making a tree: i
 ## Setup
 
 - `npm install -g sensemaking`, then `sense init` at the tree root writes `sense.config.json`: two presets (`default`, and `large` showing what a big tree tunes) and an `embed` block naming the model. The model fetches once per machine at the first vector search (progress on stderr); `sense download` prefetches it instead where that timing matters (CI, air-gapped setup). Config discovery walks up from cwd; `--config <path>` overrides.
-- **Backing store.** The config's `store` key: `sqlite` (default, zero-dependency, Node's built-in SQLite) or `duckdb` (experimental; the first command that opens a duckdb tree installs `@duckdb/node-api` on its own, a one-time native download of about 110 MB). The same commands, tables, and `has`/`basename`/`segment` functions run on both. The difference is FTS5: under `duckdb`, `search` text and raw `MATCH` reject FTS5's prefix, boolean, `NEAR`, initial-token, and column-filter operators with a named error, and sqlite's FTS5 SQL (`MATCH`, `snippet()`, `bm25()`) does not run, so saved queries written in that syntax are sqlite dialect. A tree whose saved queries or search vocabulary depend on FTS5 operators is a tree that stays on `sqlite`. `sense watch` is the other store-bound command: under `duckdb` it is a named error, because the store locks its cache file for the watcher's connection, which would block every other command on the tree for the watch's lifetime. Each store keeps its own cache file (`.sense/cache.db`, `.sense/cache.duckdb`); switching stores is a rebuild, not a migration.
+- **Backing store.** The config's `store` key: `sqlite` (default, zero-dependency, Node's built-in SQLite), or the experimental `duckdb` and `turso`, whose engine package the first command that opens such a tree installs on its own (`@duckdb/node-api`, a one-time native download of about 110 MB; `@tursodatabase/database`, much smaller). The same commands and tables run on all three. Three things do not port, and each one decides a tree. **FTS5 syntax:** under `duckdb` and `turso`, `search` text and raw `MATCH` reject FTS5's prefix, boolean, `NEAR`, initial-token and column-filter operators with a named error, and sqlite's FTS5 SQL (`MATCH`, `snippet()`, `bm25()`) does not run, so saved queries written in that syntax are sqlite dialect; a tree whose saved queries or search vocabulary depend on FTS5 operators stays on `sqlite`. **SQL functions:** `has`/`basename`/`segment` are registered on `sqlite` and `duckdb` but not `turso`, whose client cannot register them at all, so a tree whose queries call them stays off `turso`. **`sense watch`:** sqlite only; under `duckdb` and `turso` it is a named error, because those stores lock their cache file for the watcher's connection, which would block every other command on the tree for the watch's lifetime. Each store keeps its own cache file (`.sense/cache.db`, `.sense/cache.duckdb`, `.sense/cache.turso.db`); switching stores is a rebuild, not a migration.
 - Globs resolve relative to the config file, never the cwd.
 - `sense status` and `sense map` show each preset's coverage (files matched, embedded count), so what a config actually indexes is always visible in output. A config edit that changes coverage rebuilds the cache and names the preset that caused it on stderr.
 
@@ -41,7 +41,7 @@ A preset is a named, self-contained bundle of settings. `default` (required) is
 
 These belong to the tree's owner. sense works with any of them and reads no instruction files of its own; each choice only changes what queries can do.
 
-- **Frontmatter fields.** Columns are discovered per tree: whatever keys notes declare become queryable. Consistent fields across notes make SQL filters and saved queries possible (`WHERE status = 'active'`). The store's column limit bounds distinct keys per tree: sqlite's compiled 2,000 (sqlite.org/limits.html), duckdb's 10,000 sanity fence (it has no compile-time cap). The crawl stops with an error naming the count and the levers. Reserved keys (dropped with a warning): `path`, `_mtime`, `_ctime`, `_size`, `_rank`, `content`, `links`, `sections`. Values keep their YAML type: strings TEXT, whole numbers and booleans INTEGER (`true` is 1), fractions REAL, lists and maps JSON text; `map` prints the observed type per field.
+- **Frontmatter fields.** Columns are discovered per tree: whatever keys notes declare become queryable. Consistent fields across notes make SQL filters and saved queries possible (`WHERE status = 'active'`). The store's column limit bounds distinct keys per tree: sqlite's compiled 2,000 (sqlite.org/limits.html), turso's 2,000 result-set column limit, duckdb's 10,000 sanity fence (it has no compile-time cap). The crawl stops with an error naming the count and the levers. Reserved keys (dropped with a warning): `path`, `_mtime`, `_ctime`, `_size`, `_rank`, `content`, `links`, `sections`. Values keep their YAML type: strings TEXT, whole numbers and booleans INTEGER (`true` is 1), fractions REAL, lists and maps JSON text; `map` prints the observed type per field.
 - **Presets are path-shaped; frontmatter is state-shaped.** A preset's coverage must be computable from the path alone (it decides indexing, baked into the cache). Volatile state (`status`, `project`, dates) lives in frontmatter and filters at query time (`where`, `has()`, `datetime()`). A state worth different *indexing* (retired memory, superseded sources) is a state worth moving the file: the archive-folder pattern in EXAMPLES.md.
 - **What a note omits is also a filter.** A layer that deliberately carries none of the fields the saved views filter on is excluded from all of them without any view naming the layer. Sparse fields cut both ways: less of the tree filters when you want breadth, and exactly this separation when layers differ in authority.
 - **Dates.** `datetime()` comparisons work for dates written as ISO 8601, the only format it parses. A tree that mixes date formats can store them, but can't compare them in SQL.

package/dist/cjs/store/meta.d.cts

@@ -1,3 +0,0 @@
-import type { Store } from './types.js';
-export declare function getMeta(store: Store, key: string): Promise<string | null>;
-export declare function setMeta(store: Store, key: string, value: string | null): Promise<void>;

package/dist/cjs/store/meta.d.ts

@@ -1,3 +0,0 @@
-import type { Store } from './types.js';
-export declare function getMeta(store: Store, key: string): Promise<string | null>;
-export declare function setMeta(store: Store, key: string, value: string | null): Promise<void>;

package/dist/cjs/store/meta.js

@@ -1,215 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", {
-    value: true
-});
-function _export(target, all) {
-    for(var name in all)Object.defineProperty(target, name, {
-        enumerable: true,
-        get: Object.getOwnPropertyDescriptor(all, name).get
-    });
-}
-_export(exports, {
-    get getMeta () {
-        return getMeta;
-    },
-    get setMeta () {
-        return setMeta;
-    }
-});
-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 _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
-        };
-    }
-}
-function getMeta(store, key) {
-    return _async_to_generator(function() {
-        var stmt, row;
-        return _ts_generator(this, function(_state) {
-            switch(_state.label){
-                case 0:
-                    return [
-                        4,
-                        store.prepare('SELECT value FROM meta WHERE key = ?')
-                    ];
-                case 1:
-                    stmt = _state.sent();
-                    return [
-                        4,
-                        stmt.get(key)
-                    ];
-                case 2:
-                    row = _state.sent();
-                    return [
-                        2,
-                        row ? row.value : null
-                    ];
-            }
-        });
-    })();
-}
-function setMeta(store, key, value) {
-    return _async_to_generator(function() {
-        var stmt, stmt1;
-        return _ts_generator(this, function(_state) {
-            switch(_state.label){
-                case 0:
-                    if (!(value === null)) return [
-                        3,
-                        3
-                    ];
-                    return [
-                        4,
-                        store.prepare('DELETE FROM meta WHERE key = ?')
-                    ];
-                case 1:
-                    stmt = _state.sent();
-                    return [
-                        4,
-                        stmt.run(key)
-                    ];
-                case 2:
-                    _state.sent();
-                    return [
-                        2
-                    ];
-                case 3:
-                    return [
-                        4,
-                        store.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value')
-                    ];
-                case 4:
-                    stmt1 = _state.sent();
-                    return [
-                        4,
-                        stmt1.run(key, value)
-                    ];
-                case 5:
-                    _state.sent();
-                    return [
-                        2
-                    ];
-            }
-        });
-    })();
-}
-/* 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/store/meta.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/store/meta.ts"],"sourcesContent":["import type { Store } from './types.ts';\n\n// Portable meta key/value reads for external callers (watch.ts, cli/status.ts) coarse enough\n// to cross the async boundary per call; reconcile/open's own hot-path meta access stays\n// inside store/shared.ts.\n\nexport async function getMeta(store: Store, key: string): Promise<string | null> {\n  const stmt = await store.prepare('SELECT value FROM meta WHERE key = ?');\n  const row = (await stmt.get(key)) as { value: string } | undefined;\n  return row ? row.value : null;\n}\n\nexport async function setMeta(store: Store, key: string, value: string | null): Promise<void> {\n  if (value === null) {\n    const stmt = await store.prepare('DELETE FROM meta WHERE key = ?');\n    await stmt.run(key);\n    return;\n  }\n  const stmt = await store.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value');\n  await stmt.run(key, value);\n}\n"],"names":["getMeta","setMeta","store","key","stmt","row","prepare","get","value","run"],"mappings":";;;;;;;;;;;QAMsBA;eAAAA;;QAMAC;eAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AANf,SAAeD,QAAQE,KAAY,EAAEC,GAAW;;YAC/CC,MACAC;;;;oBADO;;wBAAMH,MAAMI,OAAO,CAAC;;;oBAA3BF,OAAO;oBACA;;wBAAMA,KAAKG,GAAG,CAACJ;;;oBAAtBE,MAAO;oBACb;;wBAAOA,MAAMA,IAAIG,KAAK,GAAG;;;;IAC3B;;AAEO,SAAeP,QAAQC,KAAY,EAAEC,GAAW,EAAEK,KAAoB;;YAEnEJ,MAIFA;;;;yBALFI,CAAAA,UAAU,IAAG,GAAbA;;;;oBACW;;wBAAMN,MAAMI,OAAO,CAAC;;;oBAA3BF,OAAO;oBACb;;wBAAMA,KAAKK,GAAG,CAACN;;;oBAAf;oBACA;;;;oBAEW;;wBAAMD,MAAMI,OAAO,CAAC;;;oBAA3BF,QAAO;oBACb;;wBAAMA,MAAKK,GAAG,CAACN,KAAKK;;;oBAApB;;;;;;IACF"}

package/dist/esm/store/meta.d.ts

@@ -1,3 +0,0 @@
-import type { Store } from './types.js';
-export declare function getMeta(store: Store, key: string): Promise<string | null>;
-export declare function setMeta(store: Store, key: string, value: string | null): Promise<void>;

package/dist/esm/store/meta.js

@@ -1,17 +0,0 @@
-// Portable meta key/value reads for external callers (watch.ts, cli/status.ts) coarse enough
-// to cross the async boundary per call; reconcile/open's own hot-path meta access stays
-// inside store/shared.ts.
-export async function getMeta(store, key) {
-    const stmt = await store.prepare('SELECT value FROM meta WHERE key = ?');
-    const row = await stmt.get(key);
-    return row ? row.value : null;
-}
-export async function setMeta(store, key, value) {
-    if (value === null) {
-        const stmt = await store.prepare('DELETE FROM meta WHERE key = ?');
-        await stmt.run(key);
-        return;
-    }
-    const stmt = await store.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value');
-    await stmt.run(key, value);
-}

package/dist/esm/store/meta.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/store/meta.ts"],"sourcesContent":["import type { Store } from './types.ts';\n\n// Portable meta key/value reads for external callers (watch.ts, cli/status.ts) coarse enough\n// to cross the async boundary per call; reconcile/open's own hot-path meta access stays\n// inside store/shared.ts.\n\nexport async function getMeta(store: Store, key: string): Promise<string | null> {\n  const stmt = await store.prepare('SELECT value FROM meta WHERE key = ?');\n  const row = (await stmt.get(key)) as { value: string } | undefined;\n  return row ? row.value : null;\n}\n\nexport async function setMeta(store: Store, key: string, value: string | null): Promise<void> {\n  if (value === null) {\n    const stmt = await store.prepare('DELETE FROM meta WHERE key = ?');\n    await stmt.run(key);\n    return;\n  }\n  const stmt = await store.prepare('INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value');\n  await stmt.run(key, value);\n}\n"],"names":["getMeta","store","key","stmt","prepare","row","get","value","setMeta","run"],"mappings":"AAEA,6FAA6F;AAC7F,wFAAwF;AACxF,0BAA0B;AAE1B,OAAO,eAAeA,QAAQC,KAAY,EAAEC,GAAW;IACrD,MAAMC,OAAO,MAAMF,MAAMG,OAAO,CAAC;IACjC,MAAMC,MAAO,MAAMF,KAAKG,GAAG,CAACJ;IAC5B,OAAOG,MAAMA,IAAIE,KAAK,GAAG;AAC3B;AAEA,OAAO,eAAeC,QAAQP,KAAY,EAAEC,GAAW,EAAEK,KAAoB;IAC3E,IAAIA,UAAU,MAAM;QAClB,MAAMJ,OAAO,MAAMF,MAAMG,OAAO,CAAC;QACjC,MAAMD,KAAKM,GAAG,CAACP;QACf;IACF;IACA,MAAMC,OAAO,MAAMF,MAAMG,OAAO,CAAC;IACjC,MAAMD,KAAKM,GAAG,CAACP,KAAKK;AACtB"}