sensemaking 0.8.0 → 0.9.0

package/schema.json

@@ -4,7 +4,7 @@
   "description": "Config for sense -- SQL over the frontmatter, content, links, and structure of a markdown tree.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["scan", "queries"],
+  "required": ["presets", "queries"],
   "properties": {
     "$schema": {
       "type": "string",
@@ -12,31 +12,54 @@
     },
     "version": {
       "type": "integer",
-      "enum": [1, 2],
+      "enum": [1, 2, 3],
       "description": "Config format version. Older versions are auto-migrated (and the file rewritten) on load; a version newer than this sense build supports makes it exit with an error rather than misinterpret the file. Omit to default to 1."
     },
-    "scan": {
+    "presets": {
       "type": "object",
-      "additionalProperties": false,
-      "required": ["include"],
-      "description": "Which files become rows in the `frontmatter` table.",
-      "properties": {
-        "include": {
-          "type": "array",
-          "items": { "type": "string" },
-          "minItems": 1,
-          "description": "Glob patterns (globby syntax), resolved relative to this config file's own directory -- never the invocation cwd."
+      "description": "File selection, index-time, and named search defaults. A preset is self-contained: no inheritance between presets, and no ordering -- presets may overlap freely (they are views, not partitions), and a preset whose globs match nothing is valid. A file is indexed iff any preset's include/exclude covers it (union across presets); it is embedded iff any covering preset has semantic on. `default` is used when a command names no preset, and must be declared. `sense init` generates `default` plus one `large` example.",
+      "minProperties": 1,
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["include"],
+        "properties": {
+          "include": {
+            "type": "array",
+            "items": { "type": "string" },
+            "minItems": 1,
+            "description": "Glob patterns (globby syntax), resolved relative to this config file's own directory -- never the invocation cwd. Required for every preset, including `default`."
+          },
+          "exclude": {
+            "type": "array",
+            "items": { "type": "string" },
+            "minItems": 1,
+            "description": "Glob patterns excluded from this preset's `include`, tsconfig-standard semantics."
+          },
+          "k": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Default result count for `search` when this preset is in effect (named, or `default` when none is). A --k on the invocation, or a saved search's own `k`, overrides it. Defaults to 10 when the preset omits it too."
+          },
+          "semantic": {
+            "type": "boolean",
+            "description": "Vector participation for files this preset covers. Absent or true means on (the default); only ever meaningfully written as false. A file covered only by semantic-false presets is indexed but never embedded, so it searches lexically automatically -- no error, just fewer signals."
+          },
+          "where": {
+            "type": "string",
+            "description": "Standing SQL condition against frontmatter alias `f`, applied when `search` runs under this preset without an explicit --where. An explicit --where (or a saved search's own `where`) replaces it rather than ANDing with it, so a caller can always widen back to the preset's whole scope."
+          }
         }
       }
     },
     "features": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Independently toggleable features. Absent block or key means enabled; set false to disable. Toggling a feature rebuilds the cache. Commands degrade rather than fail: `find` without links is BM25-only, `map` without rank omits hubs, `peek` without sections omits the outline.",
+      "description": "Global feature defaults. Absent block or key means enabled. `embed` is not a member of this block -- vector participation is controlled per preset by `semantic` (see \"presets\" and the top-level \"embed\" block for provider settings). Toggling a feature rebuilds the cache. Commands degrade rather than fail: `search` without links is BM25-only, `map` without rank omits hubs, `peek` without sections omits the outline.",
       "properties": {
         "links": {
           "type": "boolean",
-          "description": "Extract wikilinks and relative markdown links into the `links` table (src, target as written, dst resolved path or NULL for dead links; an ambiguous basename resolves to the lexicographically first match). Powers backlinks, graph expansion in `find`, and `peek`'s link lists."
+          "description": "Extract wikilinks and relative markdown links into the `links` table (src, target as written, dst resolved path or NULL for dead links; an ambiguous basename resolves to the lexicographically first match). Powers backlinks, graph expansion in `search`, and `peek`'s link lists."
         },
         "sections": {
           "type": "boolean",
@@ -45,63 +68,60 @@
         "rank": {
           "type": "boolean",
           "description": "PageRank over resolved links into `frontmatter._rank` at reconcile -- a static importance prior. Powers `map`'s hub list; usable in any ORDER BY. Requires `links`."
-        },
-        "embed": {
-          "description": "Semantic vectors, opt-in (absent = off; most trees don't need them). When on, vectors are computed and kept fresh at reconcile; expansion runs only on `find --semantic` invocations -- default `find` results are unchanged. `true` = defaults (static type, minishlab/potion-retrieval-32M, downloaded to ~/.cache/sensemaking on first use). Object form: `model` (Hugging Face id or local path), `type` (`static` = built-in pure-JS Model2Vec loader; `api` = OpenAI-compatible POST /embeddings), `url` (api base, e.g. http://localhost:11434/v1), `key` (name of the env var holding the bearer token). Changing model or type rebuilds the cache like a feature toggle.",
-          "oneOf": [
-            { "type": "boolean" },
-            {
-              "type": "object",
-              "additionalProperties": false,
-              "properties": {
-                "model": { "type": "string" },
-                "type": { "type": "string", "enum": ["static", "api"] },
-                "url": { "type": "string" },
-                "key": { "type": "string" }
-              }
-            }
-          ]
         }
       }
     },
-    "defaults": {
+    "embed": {
       "type": "object",
       "additionalProperties": false,
-      "description": "Tree-declared defaults for the commands.",
+      "description": "Embed provider settings only -- presence alone does not enable embedding. Vector participation is decided per preset by that preset's `semantic` field; this block only says which model/provider to use when at least one preset wants vectors. `model` (Hugging Face id or local path, default minishlab/potion-retrieval-32M), `type` (`static` = built-in pure-JS Model2Vec loader, default; `api` = OpenAI-compatible POST /embeddings), `url` (api base, e.g. http://localhost:11434/v1), `key` (name of the env var holding the bearer token). Changing model or type rebuilds the cache like a feature toggle.",
       "properties": {
-        "find": {
-          "type": "object",
-          "additionalProperties": false,
-          "description": "Default scope for `find`. Use when a tree holds a layer that should stay queryable but out of ordinary search -- generated output, or unverified source extractions that must not be cited as conclusions.",
-          "properties": {
-            "where": {
-              "type": "string",
-              "description": "SQL condition against frontmatter alias `f`, e.g. \"f.type != 'raw'\". Applied when `find` runs without --where; an explicit --where replaces it (so `--where \"1=1\"` searches the whole tree). Reported by `sense status`."
-            }
-          }
-        }
+        "model": { "type": "string" },
+        "type": { "type": "string", "enum": ["static", "api"] },
+        "url": { "type": "string" },
+        "key": { "type": "string" }
       }
     },
-    "checks": {
-      "type": "object",
-      "description": "Assertions over saved queries, for trees whose queries encode invariants: `\"checks\": { \"dead-links\": \"empty\" }` makes `sense check` fail (exit 1) when that query returns rows. Without an entry, `check` reports zero-row queries as `ok, but returns 0 rows` -- informational, since an ordinary query returning nothing is sometimes a bug and sometimes just an empty result. Keys must name saved queries.",
-      "additionalProperties": { "type": "string", "enum": ["empty"] }
-    },
     "queries": {
       "type": "object",
-      "description": "Named queries runnable as `sense <name> [params...]`, either a SQL string or a saved find. SQL string: `?` placeholders bind to CLI positional args in order. Tables: `frontmatter` (one row per file, one column per discovered frontmatter key, plus `path`/`_mtime`/`_size`/`_rank`), `content` (FTS5: `title`, `summary`, `text`, `path`), `links` (`src`, `target`, `dst`), and `sections` (`path`, `idx`, `level`, `heading`, `start_line`, `end_line`, `tokens`). `has(field, value)`: array membership on a JSON-array field, substring match on a string (so has(f.status, 'active') also matches 'inactive'), false on NULL. Exact matches: `=` for scalars, `EXISTS (SELECT 1 FROM json_each(f.tags) WHERE value = ?)` for array members. Canonical query: `SELECT f.path, content.title, content.summary, CASE WHEN length(content.text) <= 16384 THEN snippet(content, -1, '«', '»', '…', 10) END AS hit FROM frontmatter f JOIN content ON content.path = f.path WHERE content MATCH ? ORDER BY bm25(content, 10.0, 5.0, 1.0) LIMIT 10`. The CASE bounds snippet(), which re-tokenizes each matched document and costs seconds per query once a tree holds a megabyte-scale note; `find` applies the same bound internally. Saved find object: `sense <name>` behaves like `sense find <find> [--k] [--where] [--semantic]` with zero flags; it takes no positional parameters. Reserved frontmatter keys: `path`, `_mtime`, `_size`, `_rank`, `content`, `links`, `sections`. Reserved query names (unreachable as subcommands, either form): `init`, `query`, `find`, `map`, `peek`, `watch`, `status`, `rebuild`, `check`.",
+      "description": "Named queries runnable as `sense <name> [params...]`, one of three shapes: a raw SQL string, `{ sql }`, or a saved search. SQL (string or `{ sql }`): `?` placeholders bind to CLI positional args in order; deterministic and enumerating, including raw FTS5 `MATCH` for word search under your own SQL -- \"0 rows = not in the tree\" lives here. Tables: `frontmatter` (one row per file, one column per discovered frontmatter key, plus `path`/`_mtime`/`_size`/`_rank`), `content` (FTS5: `title`, `summary`, `text`, `path`), `links` (`src`, `target`, `dst`), `sections` (`path`, `idx`, `level`, `heading`, `start_line`, `end_line`, `tokens`), and `preset_files` (`preset`, `path`) -- which presets cover which files. `has(field, value)`: array membership on a JSON-array field, substring match on a string (so has(f.status, 'active') also matches 'inactive'), false on NULL. Exact matches: `=` for scalars, `EXISTS (SELECT 1 FROM json_each(f.tags) WHERE value = ?)` for array members. Canonical query: `SELECT f.path, content.title, content.summary, CASE WHEN length(content.text) <= 16384 THEN snippet(content, -1, '«', '»', '…', 10) END AS hit FROM frontmatter f JOIN content ON content.path = f.path WHERE content MATCH ? ORDER BY bm25(content, 10.0, 5.0, 1.0) LIMIT 10`. The CASE bounds snippet(), which re-tokenizes each matched document and costs seconds per query once a tree holds a megabyte-scale note; `search` applies the same bound internally. Saved search object: one text driving every engine the scoped preset has -- word match, links, vectors -- fused into one ranked list, `via` labeling which engine produced each row; `search` text must be non-empty (a saved query saves a question -- a scope without one is just flags). `preset` names one declared preset (defaults to `default`); `include` is an ad hoc glob scope that replaces the preset's include/exclude entirely, same as `search --include`; `where` and `k` behave like the `search` command's flags. `semantic: false` opts a query down to lexical only -- the rare precision opt-out, not a gate (semantic participation otherwise follows the scoped preset's `semantic` automatically). `sense <name>` behaves like `sense search <search> [--preset] [--include] [--where] [--k] [--lexical]` with zero flags; it takes no positional parameters. `sense check` probes every saved query/search (lexically, k=1 for searches) so a broken one fails loudly at check time -- it makes no assertion about the result itself; a returned row set is the reader's judgment. Reserved frontmatter keys: `path`, `_mtime`, `_size`, `_rank`, `content`, `links`, `sections`. Reserved query names (unreachable as subcommands, any shape): `init`, `query`, `search`, `find`, `map`, `peek`, `watch`, `status`, `rebuild`, `check`.",
       "additionalProperties": {
         "oneOf": [
           { "type": "string" },
           {
             "type": "object",
             "additionalProperties": false,
-            "required": ["find"],
+            "required": ["sql"],
             "properties": {
-              "find": { "type": "string", "description": "FTS5 MATCH terms, verbatim -- same syntax as `sense find \"<terms>\"`." },
-              "k": { "type": "integer", "minimum": 1, "description": "Result count, same as `find --k`. Defaults to 10. A --k on the invocation overrides this." },
-              "where": { "type": "string", "description": "SQL condition against frontmatter alias `f`, same as `find --where`. A --where on the invocation replaces this rather than ANDing with it." },
-              "semantic": { "type": "boolean", "description": "Adds vector expansion, same as `find --semantic`. Requires features.embed; `sense check` reports a saved find with semantic true as failed when embed is off, without running it." }
+              "sql": { "type": "string", "description": "Raw SQL, same as the string shape -- `?` placeholders bind to CLI positional args in order." }
+            }
+          },
+          {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["search"],
+            "properties": {
+              "search": {
+                "type": "string",
+                "minLength": 1,
+                "description": "One text driving every engine the scoped preset has -- word match, links, vectors -- fused into one ranked list. Same syntax as `sense search \"<text>\"`. Must be non-empty."
+              },
+              "preset": {
+                "type": "string",
+                "description": "Preset name to search under. Defaults to `default`. An unknown name is an error listing declared presets."
+              },
+              "include": {
+                "type": "array",
+                "items": { "type": "string" },
+                "minItems": 1,
+                "description": "Ad hoc glob scope, same as `search --include`. Replaces the preset's include/exclude entirely rather than layering on top of it."
+              },
+              "k": { "type": "integer", "minimum": 1, "description": "Result count, same as `search --k`. Defaults to the preset's own `k`, then 10. A --k on the invocation overrides this." },
+              "where": { "type": "string", "description": "SQL condition against frontmatter alias `f`, same as `search --where`. A --where on the invocation replaces this rather than ANDing with it." },
+              "semantic": {
+                "type": "boolean",
+                "description": "false opts this query down to lexical-only, same as `search --lexical` -- the rare precision opt-out. Semantic participation otherwise follows the scoped preset's `semantic` automatically, so true is redundant with the default."
+              }
             }
           }
         ]

package/skills/sense/EXAMPLES.md

@@ -6,7 +6,7 @@ the filesystem, on the paths that earned it.
 ## A. "Do the notes say anything about X?"
 
 ```
-sense find "pricing OR billing OR invoicing" --k 10 --format json
+sense search "pricing OR billing OR invoicing" --k 10 --format json
 ```
 
 ```json
@@ -79,7 +79,7 @@ sense query "SELECT DISTINCT type FROM frontmatter"    # what a field's values a
 ## F. "The notes say it in different words"
 
 ```
-sense find "children dying from poor nutrition" --semantic --k 3 --format json
+sense search "children dying from poor nutrition" --k 3 --format json
 ```
 
 ```json
@@ -90,7 +90,9 @@ sense find "children dying from poor nutrition" --semantic --k 3 --format json
 ```
 
 A `via: "vector"` row never contained the terms — it is semantically near them; `similarity` is
-the cosine against the chunk `lines` names, a direct `Read` range. Only on trees whose config enables `features.embed`.
+the cosine against the chunk `lines` names, a direct `Read` range. Vector rows appear whenever
+the scope's preset has semantic on (the default); a result of only vector rows means the words
+themselves are nowhere in the scope.
 
 ## Consequences
 
@@ -98,9 +100,9 @@ the cosine against the chunk `lines` names, a direct `Read` range. Only on trees
 |---|---|---|
 | `SELECT text FROM content` | returns the tree's entire prose | `snippet(content, -1, '«', '»', '…', 10)` excerpts the match |
 | `snippet()` on a tree holding a megabyte-scale note | re-tokenizes the whole document per matched row: seconds per query | bound it: `CASE WHEN length(content.text) <= 16384 THEN snippet(...) END`, or select `summary` instead |
-| `sense find "pricing"` | matches only that word's stem | OR-in synonyms and instances: `"pricing OR billing OR invoicing"` |
-| `sense find "pricing model details"` | bare words AND-join; one absent word = zero rows | OR the words, or quote an exact phrase |
-| `sense find "customer-facing OR on-site"` | bare punctuation is FTS5 syntax (`-` reads as a column filter) | double-quote: `"customer-facing" OR "on-site"` |
+| `sense search "pricing"` | lexically matches only that word's stem (vector rows still widen by meaning) | OR-in synonyms and instances: `"pricing OR billing OR invoicing"` |
+| `sense search "pricing model details"` | bare words AND-join; one absent word = zero lexical rows | OR the words, or quote an exact phrase |
+| `sense search "customer-facing OR on-site"` | bare punctuation is FTS5 syntax (`-` reads as a column filter) | double-quote: `"customer-facing" OR "on-site"` |
 | `Read` of a large file for one section | costs the whole file | `peek`, then `Read` the line range |
 | row queries without `LIMIT` | unbounded output (aggregates are already bounded) | `LIMIT n` |
 | saving one-off queries to config | config churn | ad-hoc `sense query`; save reusable views |

package/skills/sense/SKILL.md

@@ -14,20 +14,21 @@ storage; `map` and `status` report which are on.
 ## What each tool is for
 
 Every result is a reference (path, metadata, excerpt), never file contents; prose enters
-context only when you Read it. Costs: `map` is fixed-size, a `find` row is tens of tokens,
+context only when you Read it. Costs: `map` is fixed-size, a `search` row is tens of tokens,
 and a `peek` stays flat however large the note is. Which tool fits is a property of the
 question:
 
 - A deterministic, factual answer over known fields — counts, filters, "which notes have
-  X" — is SQL: `sense query`, a named query, or `find --where`. Enumerates every match;
+  X" — is SQL: `sense query`, a named query, or `search --where`. Enumerates every match;
   same result regardless of phrasing.
-- Locating notes by words in their prose is `find` — ranked lexical match. Results shift as
-  phrasing shifts, and bare words AND-join (one absent word = zero rows): write
-  `a OR b OR c` for any-word matching.
-- A conceptual question the notes phrase in different words is `find --semantic` (exists only
-  on trees whose config enables `embed`): adds meaning-based candidates labeled `via: vector`.
-  Conceptual similarity, not typo-tolerance; false positives are expected, labeled, and
-  bounded by `--k`.
+- Locating notes about something is `search` — one text through every engine the scope
+  has: word match (bare words AND-join — one absent word = zero lexical rows; write
+  `a OR b OR c` for any-word), link-graph expansion, and vector similarity, fused into one
+  ranked list. Read `via` per row: `match` rows contained your words; `vector`-only rows
+  did not — they are the "these words aren't in the tree; this is what's near in meaning"
+  signal. Vector rows are conceptual similarity, not typo-tolerance; false positives are
+  expected, labeled, and bounded by `--k`. `--lexical` skips vectors for one command when
+  word-presence is the question.
 - `map` answers "what is this tree" — fields, hub notes, recent changes — when the tree is
   unfamiliar.
 - `peek <path>` prices a file before you pay for it: outline with `[L143-162, ~380t]`
@@ -44,11 +45,12 @@ machine-parseable.
 ## Commands
 
 ```
-sense find "pricing OR billing OR invoicing" --where "f.status = 'active'" --k 10
+sense search "pricing OR billing OR invoicing" --where "f.status = 'active'" --k 10
+sense search "sourcing quotes" --preset raw     # a named settings bundle from the config
 sense peek notes/pricing-model.md               # a unique basename also works
 sense map
 sense query "<sql>" [params...]                 # ad-hoc SQL; ? binds positional args, count-checked
-sense <name> [params...]                        # named query or saved find from sense.config.json
+sense <name> [params...]                        # named query or saved search from sense.config.json
 sense --list | status | rebuild | check
 ```
 
@@ -58,48 +60,48 @@ sense --list | status | rebuild | check
   rules apply to search commands you write into subagent briefs.
 - When a search misses, the recall levers are: OR-in synonyms and concrete instances (the
   index only knows the words in the files — a note about a specific tool rarely names its
-  category), raise `--k` (a row costs tens of tokens), and on embed-enabled trees `--semantic`
-  (matches meaning where term overlap fails). Each widening adds candidates and dilutes
-  ranking, so the noise trade-off runs both ways.
+  category), raise `--k` (a row costs tens of tokens), and widen the scope (`--preset`, or
+  `--include` for an ad-hoc glob). Vector rows already cover the meaning-over-words gap by
+  default. Each widening adds candidates and dilutes ranking, so the noise trade-off runs
+  both ways.
 - A frontmatter query enumerates its matches deterministically; search ranks by term overlap,
   so results shift as phrasing shifts. Trade-off: a query needs a known field, search doesn't.
-- `find` fuses BM25 with link-graph expansion; the `via` column says what produced each row —
-  `match` (terms hit), `link` (connected to notes that hit), `match+link` (both). With
-  `--semantic`, `vector` joins the composition. The `lines` column, when set, points at the
-  section that earned the row — the best-matching chunk on vector rows, the term cluster's
-  section on large lexical notes — and is a direct `Read` range; null means the whole note
-  is the reference.
-- `--where` takes any SQL condition against frontmatter alias `f` — not only field equality:
-  `"f.status = 'active' AND has(f.tags, 'x')"`, `"f.path NOT LIKE 'generated/%'"`,
-  `"f.created >= datetime(?)"`. A tree can declare a default scope in `sense.config.json`
-  (`defaults.find.where`); an explicit `--where` replaces it, so `--where "1=1"` searches
-  everything. `sense status` prints the active default.
+- The `via` column says what produced each row — `match` (words hit), `link` (connected to
+  notes that hit), `vector` (near in meaning), and combinations. The `lines` column, when
+  set, points at the section that earned the row — the best-matching chunk on vector rows,
+  the term cluster's section on large lexical notes — and is a direct `Read` range; null
+  means the whole note is the reference.
+- Scope comes from presets: bare `search` uses the config's `default` preset; `--preset
+  <name>` picks another (unknown names error, listing what's declared); `--include <glob>`
+  is an ad-hoc scope that replaces the preset's globs for one command. `--where` takes any
+  SQL condition against frontmatter alias `f` — not only field equality:
+  `"f.status = 'active' AND has(f.tags, 'x')"`, `"datetime(f.created) >= datetime(?)"` —
+  and filters within the scope. `sense status` shows every preset with its coverage.
 - `score` is a rank-fusion value: it ranks rows within one result set and is not comparable
   across queries, not a relevance magnitude — it encodes how many signals fired and at what
   rank, so a perfect lexical hit and a weak vector-only hit can read the same number. With
-  `--semantic`, rows carry `similarity`: the cosine (-1 to 1) of the query against that
+  vectors active, rows carry `similarity`: the cosine (-1 to 1) of the query against that
   file's best-matching chunk — the same chunk the `lines` range points at. It orders vector
   evidence within a result set; the range it spans depends on the corpus and the embedding
   model, and compresses on small trees, where even a nonsense query has a moderately near
   neighbour somewhere. Compare similarities within a result set rather than against a fixed
   cutoff carried between trees.
-- Lexical `find` returns 0 rows when nothing matches, so it answers "is this in the tree at
-  all". `--semantic` always returns up to `k` rows — nearest-neighbour search has a nearest
-  neighbour for any input — so absence is a lexical question; `similarity` and the snippet
-  are the evidence for judging whether a vector row is a real hit.
-- Besides SQL strings, a config entry can save a whole `find` invocation:
-  `"hot": { "find": "pricing OR billing", "k": 20, "where": "...", "semantic": true }` runs
-  as `sense hot` — the scenario's settings ride along with the name, so repeat runs need no
-  flags. An invocation-level `--k`, `--where`, or `--semantic` overrides the saved value;
-  `--list` marks these entries `(find)`.
-- `sense check` prepares every saved query (catching syntax and unknown-column errors), runs
-  the ones taking no parameters, and prints row counts: a saved query returning 0 rows looks
-  the same as a true empty result until something distinguishes them. Saved finds are probed
-  lexically with k=1 (a bad `where` column or FTS5 syntax fails here, not mid-task); their
-  semantic pass is never run by `check`, only checked against `features.embed`. For queries
-  that encode invariants (a dead-link list, an unsupported-claims list — rows are
-  violations), `checks: { "<name>": "empty" }` in the config inverts the meaning: `check`
-  fails when the query returns rows, making it usable as a test suite rather than a linter.
+- Absence evidence lives in the labels: `search --lexical` (or a semantic-off scope)
+  returns 0 rows when the words are nowhere in the tree. Default `search` always returns
+  up to `k` rows — nearest-neighbour search has a nearest neighbour for any input — so a
+  result of only `via: vector` rows IS the absence signal for the words themselves;
+  `similarity` and the snippet are the evidence for judging whether a vector row is a real
+  conceptual hit.
+- Besides SQL strings, a config entry can save a whole search:
+  `"hot": { "search": "pricing OR billing", "preset": "raw", "k": 20 }` runs as
+  `sense hot` — the scenario's settings ride along with the name, so repeat runs need no
+  flags. An invocation-level `--preset`, `--k`, `--where`, or `--lexical` overrides the
+  saved value; `--list` marks these entries `(search)`.
+- `sense check` prepares every saved query and probes every saved search lexically with
+  k=1, so a typo'd column, stale SQL, bad FTS5 syntax, or unknown preset fails at check
+  time instead of silently mid-task. It reports row counts; whether an empty result is
+  good or bad is the reader's judgment — a dead-link query returning rows means broken
+  citations to fix, and the agent reads that directly.
 
 ## SQL
 
@@ -122,7 +124,7 @@ sense query "SELECT j.value, COUNT(*) n FROM frontmatter, json_each(frontmatter.
 - Rank with `ORDER BY bm25(content, 10.0, 5.0, 1.0)` (title > summary > body); excerpt with
   `snippet(content, -1, '«', '»', '…', 10)`. snippet() re-tokenizes each matched doc and its
   cost grows superlinearly with doc size — measured ~10 s per query on a tree holding one
-  1 MB note. `find` bounds this itself (docs past 16 KB get an equivalent excerpt another
+  1 MB note. `search` bounds this itself (docs past 16 KB get an equivalent excerpt another
   way); in hand-written SQL, guard it: `CASE WHEN length(text) <= 16384 THEN snippet(...)
   END`, or select `title`/`summary` instead of an excerpt.
 - Select `content.title`/`content.summary` (always exist, empty when absent) rather than
@@ -152,10 +154,11 @@ Worked traces: [EXAMPLES.md](EXAMPLES.md).
 
 - Missing CLI: `npm install -g sensemaking`. Missing config: `sense init` at the tree root.
   Discovery walks up from cwd; `--config <path>` overrides. Setting up or restructuring a
-  tree (features, frontmatter conventions, note design) is the `sense-setup` skill.
-- `map` and `status` report feature state (`features: links, sections, rank · off: embed
-  (features.embed)`). Invoking a capability whose feature is off is an error naming the
-  config key to enable — nothing silently falls back.
+  tree (presets, frontmatter conventions, note design) is the `sense-setup` skill.
+- `map` and `status` report each preset's coverage (files matched, embedded count) —
+  indexing derives from presets, so the coverage numbers are how you see what a config
+  actually indexes and embeds. A scope with fewer signals just uses fewer (a semantic-off
+  preset searches lexically); a saved search naming an unknown preset errors at `check`.
 - Save a query into `sense.config.json` only when it will be reused; run ad-hoc otherwise.
 - A one-line `summary:` per note is optional and pays twice: it appears in result rows and is a
   weighted search field. Date comparisons work for dates written as ISO 8601 (`2026-08-12`, or

package/skills/sense-setup/EXAMPLES.md

@@ -0,0 +1,121 @@
+# 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": 3,
+  "presets": {
+    "default": { "include": ["wiki/**/*.md"], "k": 10 },
+    "raw":     { "include": ["raw/**/*.md"], "k": 5, "semantic": false }
+  },
+  "queries": {
+    "uncompiled": "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":      "SELECT path, _size FROM frontmatter WHERE path LIKE 'wiki/%' AND _size < 500 ORDER BY _size",
+    "dead-links": "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), vectors on
+sense search "rotary embeddings" --preset raw   # cite from sources; lexical, k=5
+sense dead-links                                # rows are broken citations to fix
+```
+
+What the shape buys: bare search never ranks raw noise above compiled pages; raw pays no
+vector/link cost; 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, no longer embedded or ranked.
+
+```json
+{
+  "version": 3,
+  "presets": {
+    "default": { "include": ["memory/**/*.md"], "k": 10 },
+    "archive": { "include": ["archive/**/*.md"], "k": 10, "semantic": false }
+  },
+  "queries": {
+    "project":    "SELECT path, kind, created, title FROM frontmatter WHERE project = ? ORDER BY created DESC",
+    "steers":     "SELECT path, created, title FROM frontmatter WHERE kind = 'steer' AND project = ? ORDER BY created",
+    "retirement": "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)",
+    "unfiled":    "SELECT path FROM frontmatter WHERE project IS NULL"
+  }
+}
+```
+
+```
+sense project acme-app                          # one project's notes, newest first
+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": 3,
+  "presets": {
+    "default": { "include": ["reviews/**/*.md", "notes/**/*.md"], "k": 10 },
+    "source":  { "include": ["sources/**/*.md"], "k": 5, "semantic": false }
+  },
+  "queries": {
+    "unsupported": "SELECT path, title FROM frontmatter WHERE path LIKE 'reviews/%' AND path NOT IN (SELECT src FROM links WHERE dst LIKE 'notes/%')",
+    "unread":      "SELECT path FROM frontmatter WHERE path LIKE 'sources/%' AND path NOT IN (SELECT dst FROM links WHERE dst IS NOT NULL)",
+    "by-topic":    "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, no structure worth declaring — the
+`sense init` starter 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 query "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.