sensemaking 0.28.0 → 0.28.1

package/skills/sense-bases/EXAMPLES.md

@@ -1,103 +0,0 @@
-# sense-bases: worked translations
-
-Two real `.base` shapes translated end to end. Field names are illustrative; your tree
-defines its own.
-
-## A. Filtered, sorted table with formulas
-
-The base: notes categorized as Movies, excluding templates, with a "To-watch" view of unseen
-entries sorted by score.
-
-```yaml
-filters:
-  and:
-    - categories.contains(link("Movies"))
-    - '!file.name.contains("Template")'
-views:
-  - type: table
-    name: To-watch
-    filters:
-      and:
-        - last.isEmpty()
-        - rating.isEmpty()
-    order: [file.name, year, scoreImdb, runtime, director]
-    sort:
-      - { property: scoreImdb, direction: DESC }
-      - { property: file.name, direction: ASC }
-```
-
-One view, one query. Base filters AND view filters; `order` is the SELECT list; `sort` the
-ORDER BY. The link comparison is the literal written text (`[[Movies]]`), the name test uses
-`basename` so a folder named Templates does not false-positive:
-
-```sql
-SELECT basename(f.path, '.md') AS name, f.year, f.scoreImdb, f.runtime, f.director
-FROM frontmatter f
-WHERE EXISTS (SELECT 1 FROM json_each(f.categories) WHERE value = '[[Movies]]')
-  AND instr(basename(f.path), 'Template') = 0
-  AND (f.last IS NULL OR f.last IN ('', '[]', '[null]'))
-  AND (f.rating IS NULL OR f.rating IN ('', '[]', '[null]'))
-ORDER BY f.scoreImdb DESC, name ASC
-```
-
-Saved in `sense.config.json` under `queries` as e.g. `to-watch`, it runs as `sense to-watch`.
-
-## B. `this`-relative: the Related pattern
-
-The base: for the current note, every other note ranked by shared outgoing links, including
-anything it links or that links to it.
-
-```yaml
-filters:
-  and:
-    - file.path != this.file.path
-formulas:
-  Related: list(this.file.links).filter(list(file.links).containsAny(value)).unique()
-  LinksOverlap: formula.Related.length
-views:
-  - type: table
-    name: Related
-    filters:
-      or:
-        - formula.LinksOverlap > 2
-        - file.hasLink(this)
-        - this.file.hasLink(file)
-    sort:
-      - { property: formula.LinksOverlap, direction: DESC }
-    limit: 20
-```
-
-`this` becomes one bound path. The chained list formula (`filter(...containsAny).unique()`)
-is set intersection, which SQL states as an IN-filtered count; the `Related` list itself is
-the same rows through `GROUP_CONCAT`:
-
-```sql
-WITH me AS (SELECT ? AS p),
-mine AS (SELECT DISTINCT dst FROM links, me WHERE src = me.p AND dst IS NOT NULL),
-scored AS (
-  SELECT f.path,
-    (SELECT COUNT(DISTINCT l.dst) FROM links l
-      WHERE l.src = f.path AND l.dst IN (SELECT dst FROM mine)) AS overlap,
-    EXISTS (SELECT 1 FROM links, me WHERE src = f.path AND dst = me.p) AS links_to_me,
-    EXISTS (SELECT 1 FROM links, me WHERE src = me.p AND dst = f.path) AS linked_by_me,
-    (SELECT GROUP_CONCAT(DISTINCT l.dst) FROM links l
-      WHERE l.src = f.path AND l.dst IN (SELECT dst FROM mine)) AS shared_links
-  FROM frontmatter f, me WHERE f.path != me.p)
-SELECT path, overlap, shared_links FROM scored
-WHERE overlap > 2 OR links_to_me OR linked_by_me
-ORDER BY overlap DESC
-LIMIT 20
-```
-
-Run as `sense sql "..." current-note.md`, or saved with the `?` in place and the path passed
-as the parameter. The `or:` block reproduces Obsidian's semantics exactly: rows qualify by
-overlap, by linking to the note, or by being linked from it, so leaf notes the current note
-links to appear even at zero overlap, as they do in Obsidian.
-
-## Notes that recur across translations
-
-- Multiple views over the same base share the base-level filter; write it once per query
-  rather than factoring it out. Saved queries are self-contained by design.
-- `sort` keys referencing formulas sort by the SELECT alias.
-- A `groupBy` view keeps its rows; see the window-function shape in SKILL.md. Only a
-  deliberately collapsed report wants `GROUP BY`.

package/skills/sense-bases/SKILL.md

@@ -1,147 +0,0 @@
----
-name: sense-bases
-description: "Translate an Obsidian Bases .base file into sense SQL that returns the same rows. Use when asked to convert, import, or reproduce a .base file (or a Bases view, filter, or formula) with sense, or when a markdown tree contains .base files whose views someone wants queryable outside Obsidian."
----
-
-# sense-bases
-
-A `.base` file is YAML: filters selecting notes, formulas computing values, and views ordering
-and grouping them. Obsidian evaluates it against its own metadata cache; sense holds the same
-data in SQL tables. Every Bases construct that selects or computes rows has a SQL equivalent.
-What has none is presentation (`columnSize`, card layout), those change pixels, not rows, so
-a translation loses nothing by ignoring them.
-
-Translate one view to one query: base-level `filters` AND the view's `filters`, the view's
-`order`/`sort`/`limit` as the SELECT list, ORDER BY, and LIMIT. A base with four views becomes
-four queries; saving them under the base's name in `sense.config.json`'s `queries` block keeps
-them runnable as `sense <name>`. The general query surface is the `sense` skill; this one only
-maps Bases constructs onto it.
-
-## Properties
-
-| Bases | sense | notes |
-|---|---|---|
-| `note.field` / bare `field` | `f.<field>` | frontmatter column, same name |
-| `file.name` | `basename(f.path, '.md')` | the Name column: no directory, no extension |
-| a name with extension | `basename(f.path)` | the suffix arg is Unix basename's: present, stripped |
-| `file.folder` | `f.path LIKE 'Folder/%'` | for `inFolder("Folder")` |
-| `file.ext` | `'md'` | sense indexes only markdown |
-| `file.size` | `f._size` | bytes |
-| `file.mtime` | `datetime(f._mtime / 1000, 'unixepoch')` | stored as ms |
-| `file.ctime` | `datetime(f._ctime / 1000, 'unixepoch')` | see the caveat below |
-| `file.tags` | the `tags` table | frontmatter + inline `#tags`, deduplicated, Obsidian's grain |
-| `file.links` | `links WHERE embed = 0` | one row per distinct written target |
-| `file.embeds` | `links WHERE embed = 1` | |
-| `file.backlinks` | `links WHERE dst = f.path` | |
-| `this` | a bound `?` | see below |
-
-`file.ctime` is the filesystem's creation time. A `git clone` or a copy resets it, so on a
-tree that arrived as a checkout, every ctime is the checkout date and age formulas are wrong
-about authorship without being wrong about the filesystem. `map` warns when modification
-times have this shape; creation times share it.
-
-## Predicates
-
-| Bases | sense |
-|---|---|
-| `==` `!=` `>` `<` `>=` `<=` | same |
-| `&&` `\|\|` `!` | `AND` `OR` `NOT` |
-| `and:` / `or:` / `not:` filter blocks | parenthesized `AND` / `OR` / `NOT` |
-| `field.isEmpty()` | `(f.field IS NULL OR f.field IN ('', '[]', '[null]'))` |
-| `file.hasTag("book")` | `EXISTS (SELECT 1 FROM tags WHERE tags.path = f.path AND (tag = 'book' OR tag LIKE 'book/%'))` |
-| `file.hasLink("Note")` | `EXISTS (SELECT 1 FROM links WHERE src = f.path AND dst = 'Note.md')` |
-| `list.contains(x)` | `EXISTS (SELECT 1 FROM json_each(f.list) WHERE value = x)` |
-| `string.contains(x)` | `instr(f.string, x) > 0` |
-| `list.containsAny(...)` | the `json_each` EXISTS with `value IN (...)` |
-| `/regex/.matches(x)` | no SQLite regex; `LIKE`/`GLOB` cover anchored and wildcard shapes |
-| `value.isType("object")` | `json_each`'s own `type` column: `... FROM json_each(f.field) j WHERE j.type = 'object'` |
-
-A field no note in the tree declares has no column at all, so a filter naming it errors with
-`no such column` instead of treating every row as empty. Obsidian's evaluator returns empty
-for unknown properties; SQL does not. Dropping the clause states the same thing the error
-did, and `SELECT name FROM pragma_table_info('frontmatter')` lists what exists.
-
-`isEmpty()` has four true cases because empty is stored three ways: NULL (key absent), `''`
-(empty string value), `'[]'` (a list written `[]`), and `'[null]'` (a list key above a bare
-`-`). Obsidian's `isEmpty()` is true for all of them; `IS NULL` alone finds only the first.
-The IN list is the whole test. `json_array_length()` is not: it reads `'[null]'` as length
-1 and throws on plain strings. The same trap inside a list: `json_each` hands a string member
-to `value` as plain text, so `json_type(value)` throws `malformed JSON` on it; the scan's own
-`type` column is the discriminator.
-
-`contains(link("Movies"))` compares against a link value. In frontmatter, a list of links
-holds the written text, so the `json_each` comparison value is the literal `[[Movies]]`.
-`hasLink` compares resolved paths: `links.dst` is the resolved target (`NULL` for dead
-links), so the comparison value is the target's path, not its display name.
-
-sense's own `has(field, x)` is looser than both `contains` variants: exact membership on JSON
-arrays but substring on strings, so `has(f.status, 'active')` also matches `inactive`. It
-reads shorter when the field is known to be a list; the `json_each` form is the exact
-translation.
-
-## Formulas
-
-Formulas are SELECT expressions. The Bases functions map onto SQLite's:
-
-| Bases | sense |
-|---|---|
-| `if(c, a, b)` | `iif(c, a, b)` or `CASE WHEN` |
-| `now()` / `today()` | `datetime('now')` / `date('now')` |
-| `date(x)` | `datetime(x)` |
-| `(date1 - date2).days` | `julianday(date1) - julianday(date2)` |
-| `(now() - acquired).months` | `(julianday('now') - julianday(f.acquired)) / 30.44` |
-| `x.round(n)` / `x.toFixed(n)` | `round(x, n)` / `printf('%.2f', x)` |
-| `d.format("YYYY-MM-DD")` | `strftime('%Y-%m-%d', d)` |
-| `x.toString()` | `CAST(x AS TEXT)` |
-| `list.length` | `json_array_length(f.list)` on a JSON column, a COUNT subquery on a table |
-| `list(a).filter(list(b).containsAny(value)).unique()` | an EXISTS-joined subquery; worked example in EXAMPLES.md |
-
-Bases durations are typed; SQL date arithmetic is julianday day-fractions. A formula chaining
-duration fields (`.days.round()`) flattens to arithmetic on the julianday difference.
-
-A formula referencing another formula becomes a CTE layer: SQL cannot read a SELECT alias in
-the same SELECT list, so each dependency level computes its formulas as columns and the next
-level reads them (`WITH t AS (SELECT ..., <level-1 formulas> FROM frontmatter) SELECT ...,
-<level-2 formulas> FROM t`). A five-formula chain is however many *levels* it has, not five
-CTEs. Formulas that only read base columns share one layer.
-
-## Views
-
-- `sort:` (multi-key, each with direction) -> `ORDER BY a DESC, b ASC`. `limit:` -> `LIMIT`.
-- `groupBy` does not collapse rows. Obsidian shows every row bucketed under headers with
-  per-group summaries. The SQL producing the same rows and numbers is ordering plus window
-  functions, not GROUP BY:
-
-  ```sql
-  SELECT f.path, f.status, f.days,
-         AVG(f.days)  OVER (PARTITION BY f.status) AS group_avg,
-         COUNT(*)     OVER (PARTITION BY f.status) AS group_n
-  FROM frontmatter f WHERE f.days IS NOT NULL
-  ORDER BY f.status, f.days DESC
-  ```
-
-  A collapsed one-row-per-group report is plain `GROUP BY`. That is a different result than
-  the Bases view shows.
-- View `summaries` (Sum, Average, Median via ordering, Unique, Filled, Checked) are the
-  matching aggregates, windowed as above to keep the rows, or a separate aggregate query.
-
-## `this`
-
-`this` is the note the base is evaluated against: the embedding note, or Obsidian's active
-pane. sense has no pane, so the caller supplies the path as a bound parameter: `sense sql
-"..." <path>`, or a saved query run as `sense <name> <path>`. A CTE keeps it single-bind:
-
-```sql
-WITH me AS (SELECT ? AS p)
-```
-
-and every `this.file.*` expression joins `me`. The full Related.base translation in
-EXAMPLES.md is the worked case: link overlap, mutual-link filters, and the shared-target list
-via `GROUP_CONCAT`, all from one bound path.
-
-## Not translatable, and why it costs nothing
-
-- `columnSize`, card/table/list/map chrome: pixel layout over the same rows.
-- Obsidian choosing `this` from the active pane: there is no pane; the path parameter is the
-  resolution.
-- Live re-evaluation as files change: default CLI queries incrementally prepare the needed capabilities; `--no-build` reads the last completed generation and requires its requested readiness without scanning live files. Nothing re-renders on its own.

package/skills/sense-setup/EXAMPLES.md

@@ -1,129 +0,0 @@
-# sense-setup: worked configurations
-
-Four tree shapes, each with its config and the commands an agent actually runs. Field names and folder names are illustrative; your tree defines its own.
-
-## A. Compiled wiki over immutable sources (the llm-wiki pattern)
-
-`raw/` holds ingested sources: big, never hand-edited. `wiki/` holds agent-compiled pages: linked, curated. The human drops sources and asks questions; the agent compiles and cites.
-
-```json
-{
-  "version": 5,
-  "presets": {
-    "default": { "include": ["wiki/**/*.md"], "k": 10 },
-    "raw":     { "include": ["raw/**/*.md"], "k": 5 }
-  },
-  "embed": { "model": "minishlab/potion-retrieval-32M", "provider": "static" },
-  "queries": {
-    "uncompiled": { "sql": "SELECT path, _mtime FROM frontmatter WHERE path LIKE 'raw/%' AND path NOT IN (SELECT dst FROM links WHERE dst IS NOT NULL) ORDER BY _mtime DESC" },
-    "stubs":      { "sql": "SELECT path, _size FROM frontmatter WHERE path LIKE 'wiki/%' AND _size < 500 ORDER BY _size" },
-    "dead-links": { "sql": "SELECT src, target FROM links WHERE dst IS NULL ORDER BY src" }
-  }
-}
-```
-
-```
-sense uncompiled                                # compile queue: raw files nothing cites yet
-sense search "how does attention scale"         # wiki only (default preset)
-sense search "rotary embeddings" --preset raw   # cite from sources, k=5
-sense dead-links                                # rows are broken citations to fix
-```
-
-What the shape buys: bare search never ranks raw noise above compiled pages; the compile queue, stub list, and citation integrity are one saved query each. The maintenance loop is `uncompiled` → write the wiki page citing its sources → `dead-links` stays empty.
-
-## B. Nightly agent memory, consolidated (the dreaming pattern)
-
-`memory/` accumulates small notes written at session end, each with `project`, `created`, and `kind` (observation / steer / decision) frontmatter. A consolidation agent runs periodically: prune, merge, surface contradictions for the human. Retired notes move to `archive/`: still queryable under their own preset, out of the default scope.
-
-```json
-{
-  "version": 5,
-  "presets": {
-    "default": { "include": ["memory/**/*.md"], "k": 10 },
-    "archive": { "include": ["archive/**/*.md"], "k": 10 }
-  },
-  "embed": { "model": "minishlab/potion-retrieval-32M", "provider": "static" },
-  "queries": {
-    "project":    { "sql": "SELECT path, kind, created, title FROM frontmatter WHERE project = ? ORDER BY created DESC" },
-    "steers":     { "sql": "SELECT path, created, title FROM frontmatter WHERE kind = 'steer' AND project = ? ORDER BY created" },
-    "retirement": { "sql": "SELECT path, project, created FROM frontmatter WHERE datetime(created) < datetime('now','-90 day') AND path NOT IN (SELECT dst FROM links WHERE dst IS NOT NULL)" },
-    "today":      { "sql": "SELECT path, title FROM frontmatter WHERE date(created) = date('now','localtime') ORDER BY created" },
-    "unfiled":    { "sql": "SELECT path FROM frontmatter WHERE project IS NULL" }
-  }
-}
-```
-
-```
-sense project acme-app                          # one project's notes, newest first
-sense today                                     # `now` is UTC: a query whose boundary is a day needs 'localtime'
-                                                # `retirement` above is a 90-day window, so it does not
-sense search "prefers terse commit messages" --k 5
-  → memory/acme-app/2026-08-02-commits.md   via: match
-  → memory/acme-app/2026-06-11-style.md     via: vector  similarity: 0.71   # near-duplicate → merge candidate
-sense steers acme-app                           # oldest first: does a new steer override an old one?
-sense retirement                                # old + uncited → move to archive/
-sense unfiled                                   # rows are notes missing a project. File them
-```
-
-Presets are structural (live vs archived); per-project filtering is metadata (`project = ?`). One tree serves every project. Semantic search over the memory preset is the near-duplicate detector: search a new note's own summary and read `similarity` within the results. Whether an old steer was overridden is a question for the human, found by search, never decided by it.
-
-## C. Evidence corpus: claims trace to sources
-
-`sources/` (immutable imports), `notes/` (one reading note per source), `reviews/` (synthesis whose claims must cite notes). The same shape fits incident reports and postmortems, user research and findings, due diligence and memos.
-
-```json
-{
-  "version": 5,
-  "presets": {
-    "default": { "include": ["reviews/**/*.md", "notes/**/*.md"], "k": 10 },
-    "source":  { "include": ["sources/**/*.md"], "k": 5 }
-  },
-  "embed": { "model": "minishlab/potion-retrieval-32M", "provider": "static" },
-  "queries": {
-    "unsupported": { "sql": "SELECT path, title FROM frontmatter WHERE path LIKE 'reviews/%' AND path NOT IN (SELECT src FROM links WHERE dst LIKE 'notes/%')" },
-    "unread":      { "sql": "SELECT path FROM frontmatter WHERE path LIKE 'sources/%' AND path NOT IN (SELECT dst FROM links WHERE dst IS NOT NULL)" },
-    "by-topic":    { "sql": "SELECT path, title FROM frontmatter WHERE path NOT LIKE 'sources/%' AND has(topics, ?) ORDER BY path" }
-  }
-}
-```
-
-```
-sense search "replication failures in priming studies"     # reviews + notes; sources never dilute
-sense search "the claim's exact phrasing" --preset source  # citation pull on demand
-sense unsupported                               # rows are synthesis claims with no note behind them
-sense unread                                    # the reading queue: sources no note cites
-```
-
-## D. A plain vault: zero configuration
-
-Someone else's Obsidian vault, heterogeneous with no structure worth declaring. The `sense init` starter is left untouched. The workflow is discovery:
-
-```
-sense map                                       # fields in use, hub notes, recent changes
-sense search "dataview queries"                 # words + links + meaning, one ranked list
-sense sql "SELECT j.value AS tag, COUNT(*) n FROM frontmatter, json_each(frontmatter.tags) j GROUP BY j.value ORDER BY n DESC LIMIT 20"
-sense peek "Plugins/dataview.md"                # outline + links before reading
-```
-
-Presets earn their place only when a tree has parts deserving different treatment; a tree that is one kind of thing needs none of the vocabulary above. On a big vault, raise `default`'s `k` and read `lines` ranges instead of whole files, or start from the starter's `large` preset.
-
-## E. One vault, separate consumers
-
-Keep each consumer's configuration and cache under its own configuration directory while indexing one shared vault. `root` is relative to this config file, so saved SQL continues to use stable vault-relative paths.
-
-`~/.config/obsidian/tasks/sense.config.json`:
-
-```json
-{
-  "version": 5,
-  "root": "../../../.obsidian",
-  "presets": {
-    "default": { "include": ["vault/tasks/**/*.md"], "k": 20 }
-  },
-  "queries": {
-    "active": { "sql": "SELECT path, title FROM frontmatter WHERE path LIKE 'vault/tasks/%' AND status = 'active' ORDER BY path" }
-  }
-}
-```
-
-The database is `~/.config/obsidian/tasks/.sense/cache.db`; the indexed row remains `vault/tasks/...`, never a path back out through the configuration directory. A `general/` sibling can point at the same root with different presets and a separate `.sense/` cache.

package/skills/sense-setup/SKILL.md

@@ -1,112 +0,0 @@
----
-name: sense-setup
-description: "Set up the sense CLI on a markdown tree and make the decisions that shape its index: run sense init, choose sqlite, duckdb, or turso, define presets and search signals, configure embeddings, and design queryable note conventions. Use when creating or restructuring a markdown knowledge base, editing sense.config.json, choosing a store or embedding model, or deciding how agents should write notes for later retrieval."
----
-
-# sense setup and tree design
-
-Use this skill to create or change a sense configuration. Querying an existing tree belongs to the `sense` skill. Worked configurations for common tree shapes are in [EXAMPLES.md](EXAMPLES.md).
-
-## Set up the tree
-
-Install the CLI and initialize it at the markdown root:
-
-```sh
-npm install -g sensemaking
-cd path/to/notes
-sense init
-sense status
-```
-
-`sense init` writes `sense.config.json`. Config discovery walks upward from the current directory. `--config <path>` selects another file.
-
-By default, the config indexes its own directory. A top-level `root` can point at another markdown tree. Relative roots resolve from the config directory, and `.sense/` remains beside the config. Use this when separate consumers need their own presets, saved queries, or caches over one tree.
-
-Globs and indexed paths are relative to the selected root. Run `sense status` and `sense map` after changing the config to confirm preset coverage and the selected store. A change that affects indexed content rebuilds the relevant cache and reports the reason. A build-enabled command replaces an incompatible derived cache format and repairs incomplete feature state; config `"build": false` or `--no-build` reports the required build without rebuilding or repairing the Sense index.
-
-## Choose the store
-
-Choose from the intended use of the cache. Start with `sqlite` when no surrounding workflow favors
-another engine, then consider interoperability, SQL, connection behavior, and representative Sense
-measurements. A current timing result does not define an engine's long-term suitability.
-
-| Store | Choose it when | Main trade-off |
-|---|---|---|
-| `sqlite` | The tree needs the smallest setup, advanced FTS5 search syntax, or concurrent Sense commands | Included with Node; raw SQL is SQLite |
-| `duckdb` | The cache belongs in DuckDB analytical work over large datasets or in a local/cloud workflow, or needs DuckDB types and SQL | Experimental Sense adapter, large native install, one open connection at a time |
-| `turso` | The tree benefits from the embedded Rust engine or Tantivy index, or is evaluating the engine as its adapter evolves | Experimental Sense adapter, restricted search grammar, one open connection at a time |
-
-Read the matching selection guide before recommending or configuring a non-default store:
-
-- [SQLite selection guide](references/stores/sqlite.md)
-- [DuckDB selection guide](references/stores/duckdb.md)
-- [Turso selection guide](references/stores/turso.md)
-
-Read the [current store benchmark summary](references/store-benchmarks.md) only when performance could change the choice. The release assessment generates that shipped summary from the latest accepted all-store run.
-
-Each store uses a separate cache file. Changing `store` rebuilds the index instead of migrating the old cache. Commands and public tables are shared, while raw SQL and advanced word-search syntax follow the selected engine.
-
-## Design presets
-
-A preset is a named, self-contained scope. The required `default` preset serves bare commands. Other presets are selected by name.
-
-| Field | Meaning | Default |
-|---|---|---|
-| `include` and `exclude` | Files covered by the preset | `include` is required |
-| `k` | Search result count | 10 |
-| `signals` | Enabled search signals and their reciprocal-rank weights | Every available signal at weight 1 |
-| `where` | Standing frontmatter filter | None |
-
-A file is indexed when any preset includes it. Presets can overlap. Files outside every preset do not enter the index.
-
-Use paths for stable layers such as `raw/`, `notes/`, and `archive/`. Use frontmatter filters for changing state such as `status`, `project`, and dates. A preset controls indexing, so its coverage must be computable from paths before frontmatter queries run.
-
-Use separate presets when parts of the tree need different search signals or result counts. A single-purpose tree does not need extra preset vocabulary.
-
-## Configure vectors
-
-Vectors require two choices. The top-level `embed` block names the model and provider. Each preset's `signals` decides whether that scope uses vectors.
-
-```json
-{
-  "embed": {
-    "model": "minishlab/potion-retrieval-32M",
-    "provider": "static"
-  },
-  "presets": {
-    "default": {
-      "include": ["notes/**/*.md"],
-      "signals": { "words": 1, "links": 1, "vectors": 1 }
-    },
-    "raw": {
-      "include": ["raw/**/*.md"],
-      "signals": { "words": 1, "links": 1 }
-    }
-  }
-}
-```
-
-The config's `"build": true` default lets CLI queries prepare their needed capabilities. Set `"build": false` for manual-build or watch workflows. The first build-enabled vector search downloads a named static model and embeds its eligible scope. `sense build` and `sense watch` prepare all configured capabilities regardless of this setting; `sense download` fetches the model earlier when CI, offline work, or timing makes that useful. A config change that alters the provider, model, effective endpoint, vector coverage, or chunking can invalidate or rebuild vectors. Config `"build": false` or `--no-build` requires the requested vector scope to be ready and does not read newer live files.
-
-Read [embedding setup](references/embeddings.md) when choosing a provider or model, supporting a non-English tree, changing chunk size, or tuning signal weights.
-
-## Design queryable notes
-
-Sense accepts heterogeneous markdown. These choices decide which queries will be reliable:
-
-- Consistent frontmatter fields make exact filters and saved reports possible. Inspect actual coverage and types with `sense map`.
-- ISO 8601 dates can be compared by the selected store's date functions. Mixed date formats can still be stored, but do not make a dependable time range.
-- A one-line `summary` appears in results and receives more lexical weight than body text. Its cost is keeping it current.
-- Folders are the natural unit for preset coverage. Frontmatter is the natural unit for status and ownership.
-- Small notes give precise hits and cheap whole-file reads. Large notes still work because `peek`, `sections`, and search `lines` point at ranges, and vector chunking splits long sections.
-- Save recurring questions under `queries`. Use `{ "sql": "..." }` for deterministic filters and reports, and `{ "search": "..." }` for ranked retrieval.
-
-Field names in examples are illustrative. The tree defines its own schema. Reserved frontmatter keys are `path`, `_mtime`, `_ctime`, `_size`, `_rank`, `_parse_error`, `content`, `links`, and `sections`; sense drops them with a warning.
-
-## Validate the result
-
-Run `sense status` to confirm the store, cache, document count, embedding state, watcher state, and preset coverage. Run `sense map` to confirm the discovered fields and their observed types.
-
-Run every saved query after editing it. A parameterized SQL query can use any value because preparing the statement validates its columns and syntax before the parameter changes the result.
-
-Record choices that should outlive the setup conversation in the tree's maintained agent guidance or in an authored note. The sense config should contain executable settings and reusable queries, not prose policy.

package/skills/sense-setup/references/embeddings.md

@@ -1,51 +0,0 @@
-# Embedding setup
-
-Read this guide when choosing an embedding provider or model, supporting a non-English tree, changing chunk size, or tuning signal weights.
-
-## Provider choice
-
-`static` loads a local Model2Vec model in JavaScript. The default model is `minishlab/potion-retrieval-32M`. A Hugging Face model id downloads into `~/.sense/models` on first vector use. A filesystem path points at a directory that already contains `model.safetensors` and `tokenizer.json`.
-
-`openai` calls an OpenAI-compatible `/embeddings` endpoint. Local Ollama and LM Studio servers use this protocol. A hosted endpoint sends note text to that service.
-
-`cohere` calls Cohere's native embedding endpoint. The `key` setting names the environment variable that contains the credential. Note text leaves the machine.
-
-## Model choice
-
-The default static model is English-only. For another language, choose a model whose published card declares that language. A static Model2Vec model must have compatible safetensors and tokenizer files with supported floating-point weights.
-
-Sense checks declared model languages against the indexed tree. A clear mismatch raises `EMBED_MODEL_MISMATCH`. A model card with no language declaration cannot be checked, so confirm it before indexing.
-
-For a static model, inspect current Model2Vec models and their cards rather than relying on a fixed list in this skill. For a local HTTP provider, inspect the model catalog exposed by the chosen runtime. Model availability and model cards change independently of sense releases.
-
-## Download and rebuild behavior
-
-Naming a remote static model in the config authorizes its download. `sense download` performs that fetch before a query. A default vector query embeds its eligible scope; `sense build` and `sense watch` prepare all configured vector capabilities, while `--no-build` requires the requested scope to be ready.
-
-Changing the provider, model, or effective endpoint invalidates stored vector values while preserving the indexed chunks. Changing `embed.chunkTokens` rebuilds affected embedding rows, and changing preset coverage can add, remove, or rebuild them. A build-enabled command performs this work; config `"build": false` or `--no-build` reports incompatible or unprepared state without rebuilding or repairing the Sense index. Settle the broad scope before embedding a large tree.
-
-## Chunk size
-
-`embed.chunkTokens` sets the estimated token ceiling for chunks. The default is 500. Sense splits at headings and then applies the ceiling to long sections. Lower it for an embedding model with a smaller useful context window. Raising it trades fewer vectors for less precise line ranges and more text per vector.
-
-## Signal weights
-
-A preset includes a signal by naming it:
-
-```json
-"signals": { "words": 1, "links": 1, "vectors": 1 }
-```
-
-The number is the signal's reciprocal-rank weight. It is not a boolean. Weight 1 gives equal contribution. A higher vector weight can help a strong encoder on some corpora and hurt another tree whose exact vocabulary carries the answer.
-
-Test representative questions from the actual tree before changing weights. Compare returned paths and evidence labels, not only the fused score.
-
-## Layers without vectors
-
-An `embed` block makes vectors available to the tree. A preset can still omit the vector signal:
-
-```json
-"signals": { "words": 1, "links": 1 }
-```
-
-Use that for layers where exact wording matters more than paraphrase, such as raw sources, archives, generated logs, or citation corpora. Those files can remain indexed without paying the embedding cost for that preset's scope.

package/skills/sense-setup/references/store-benchmarks.md

@@ -1,16 +0,0 @@
-<!-- sense-store-benchmark release=0.27.0 -->
-# Current store benchmark summary
-
-The release assessment generated this file for store selection. Release `0.27.0` passed on 2026-10-03, measured on Apple M1 Pro with Node v26.10.0.
-
-The timing rows ran on the same 6,566-note tree. They include CLI startup and each store's complete selected path. Ranked candidates and downstream work can differ by store, so these are current operating measurements rather than an isolated database-engine contest.
-
-| Store | Cold index | Warm count | Lexical search | Semantic search | Portable semantic nDCG@10 |
-|---|---|---|---|---|---|
-| sqlite | 2,254 ms | 260 ms | 350 ms | 576 ms | 0.3306 |
-| duckdb | 3,026 ms | 319 ms | 510 ms | 695 ms | 0.3282 |
-| turso | 3,273 ms | 279 ms | 412 ms | 1,081 ms | 0.3299 |
-
-Cold index measures core index creation and a count query, excluding document embeddings. Warm count is a no-change `COUNT(*)` query. Lexical and semantic search are steady-state `sense search` commands. Lower timing is faster. Higher nDCG@10 is better; that quality column uses the same NFCorpus queries, judgments, result count, and model on every store.
-
-Choose from the intended workflow, capabilities, and SQL compatibility. These numbers describe the current Sense implementations, not a permanent ranking of the engines. Treat small timing or relevance differences as diagnostic unless a representative workload for the target tree reproduces them.

package/skills/sense-setup/references/stores/duckdb.md

@@ -1,28 +0,0 @@
-# Choose DuckDB
-
-Choose DuckDB when the cache file is an analytical artifact that another DuckDB tool will query, when saved SQL needs DuckDB's types and functions, or when the cache belongs beside large local or cloud datasets.
-
-DuckDB is designed for analytical SQL and supports larger-than-memory work by spilling to disk. Its SQL closely follows PostgreSQL while keeping documented differences and extensions. See the official [DuckDB performance guide](https://duckdb.org/docs/current/guides/performance/how_to_tune_workloads) and [SQL introduction](https://duckdb.org/docs/current/sql/introduction).
-
-Sense's [store benchmark summary](../store-benchmarks.md) measures the current adapter paths on a named markdown tree. It does not measure DuckDB's general analytical ceiling. Use it when current Sense latency matters to the choice.
-
-## What the choice gives you
-
-- A standard `.sense/cache.duckdb` database that DuckDB tools can open.
-- Frontmatter in `VARIANT` columns, so lists, maps, booleans, numbers, and strings retain useful native shapes.
-- Embeddings in native fixed-width float arrays.
-- DuckDB SQL for downstream analysis.
-- Compatibility with external DuckDB workflows. MotherDuck supports hybrid queries over local and cloud data, although Sense does not connect, upload, or replicate the cache for you. See [MotherDuck's hybrid execution overview](https://motherduck.com/research/motherduck-duckdb-in-the-cloud-and-in-the-client/).
-
-## Current Sense adapter boundaries
-
-- DuckDB support is experimental.
-- The first open installs the newest `@duckdb/node-api` in the range sensemaking's `peerDependencies` declares, a native download of about 110 MB. An already-installed version is used, and one outside that range is reported. A build after the version changes rebuilds the cache.
-- Under DuckDB's [concurrency model](https://duckdb.org/docs/current/connect/concurrency), Sense opens an existing cache for no-build observation in read-only mode, so several independent reader processes can coexist. A build-enabled command or watcher opens it read-write and excludes every other process until it closes. Contenders wait within Sense's bounded lock budget, then fail with `STORE_BUSY`. This cross-process rule does not promise writer/reader coexistence or unrestricted sharing by independently configured DuckDB instances in one process.
-- `sense search` accepts bare words and quoted phrases. It rejects FTS5 boolean, prefix, `NEAR`, initial-token, grouping, and column-filter syntax.
-- SQLite's raw `MATCH`, `snippet()`, and `bm25()` queries do not port.
-- Mixed-type `VARIANT` fields can require explicit casts in predicates.
-
-Commands, public tables, `has()`, `basename()`, `segment()`, vectors, and `sense watch` remain available. Read the [DuckDB query guide](../../../sense/references/stores/duckdb.md) before translating saved SQL or advanced searches.
-
-Changing to DuckDB builds its separate cache. It does not migrate the SQLite or Turso cache.

package/skills/sense-setup/references/stores/sqlite.md

@@ -1,21 +0,0 @@
-# Choose SQLite
-
-SQLite is the default recommendation for a sense tree.
-
-Choose it when the tree has no engine-specific requirement, when saved searches use FTS5 operators, or when people and agents may run sense commands at the same time.
-
-## What the choice gives you
-
-- No optional store package. Sense uses Node's built-in SQLite.
-- The full documented word-search grammar, including boolean, prefix, `NEAR`, initial-token, grouping, and column-filter expressions.
-- Raw FTS5 SQL through `MATCH`, `bm25()`, and `snippet()`.
-- The sense SQL functions `has()`, `basename()`, and `segment()`.
-- WAL-backed concurrent sense commands.
-
-The cache is `.sense/cache.db`. It is derived data and can be rebuilt from the markdown files. It records the bundled SQLite version that built it, so a Node upgrade that changes that version rebuilds it on the next build.
-
-## When another store fits the workflow
-
-Use DuckDB when downstream DuckDB tools need to query the cache, the tree needs DuckDB's analytical SQL and native types, or the cache belongs beside large datasets or in a local/cloud workflow. Use Turso when its embedded Rust engine or Tantivy index fits the intended integration. Compare current measurements in [the store benchmark summary](../store-benchmarks.md) when Sense performance affects the decision.
-
-If existing queries use FTS5 syntax, moving away from SQLite requires rewriting those queries. Read the selected engine's query guide under the `sense` skill before changing the config.

package/skills/sense-setup/references/stores/turso.md

@@ -1,25 +0,0 @@
-# Choose Turso
-
-Choose Turso when the tree benefits from the embedded Turso Database engine or its Tantivy text index, or when evaluating the engine as the Sense adapter evolves. The Sense adapter is experimental; the engine is a fast-moving Rust rewrite of SQLite whose trade-offs can change between releases.
-
-Upstream Turso offers async I/O and concurrent writes in its local engine, plus sync through a separate SDK. Sense currently opens one local cache through `@tursodatabase/database` and serializes Sense commands against that file. It does not configure sync, remote access, or encryption. Read [Turso's current SDK guide](https://docs.turso.tech/sdk/introduction) to distinguish engine capabilities from the adapter features Sense exposes.
-
-## What the choice gives you
-
-- A `.sense/cache.turso.db` file using the embedded Turso engine.
-- Tantivy-backed lexical ranking with shared stemming and n-gram support for unspaced scripts.
-- The asynchronous JavaScript database client used by sense's store adapter.
-- Native vector storage and search.
-
-## Current Sense adapter boundaries
-
-- Turso support is experimental.
-- The first open installs the optional native package.
-- Turso holds the cache file for the life of a connection. Concurrent sense commands wait for the current command or watcher cycle to close it.
-- `sense search` accepts bare words and quoted phrases. It rejects FTS5 boolean, prefix, `NEAR`, initial-token, grouping, and column-filter syntax.
-- SQLite's raw `MATCH`, `snippet()`, and `bm25()` queries do not port.
-- `has()` and `basename()` work through SQL rewriting. `segment()` is unavailable.
-
-Commands, public tables, vectors, and `sense watch` remain available. Read the [Turso query guide](../../../sense/references/stores/turso.md) before translating saved SQL or advanced searches.
-
-Changing to Turso builds its separate cache. It does not migrate the SQLite or DuckDB cache. Review the shipped [store benchmark summary](../store-benchmarks.md) if performance affects the choice.