sensemaking 0.9.3 → 0.9.5

package/skills/sense/SKILL.md

@@ -1,48 +1,23 @@
 ---
 name: sense
-description: Query a markdown tree with the sense CLI — filter notes by frontmatter, full-text search the prose, follow wikilinks/backlinks, and read note outlines. Use when the user wants to query, filter, count, search, or report on a folder of markdown notes, when you need to find which notes discuss a topic before reading them, when you want a note's backlinks or structure, when a directory has a sense.config.json, or when asked to add a named query to one.
+description: Query a markdown tree with the sense CLI: filter notes by frontmatter, full-text search the prose, follow wikilinks/backlinks, and read note outlines. Use when the user wants to query, filter, count, search, or report on a folder of markdown notes, when you need to find which notes discuss a topic before reading them, when you want a note's backlinks or structure, when a directory has a sense.config.json, or when asked to add a named query to one.
 ---
 
 # sense
 
-SQL over a markdown tree, kept fresh by a filesystem check on every query. Every file becomes
-rows in `frontmatter` (one column per key, plus `path`/`_mtime`/`_size`/`_rank`), `content`
-(FTS5: `title`, `summary`, `text`), `links` (`src`, `target`, `dst` — `NULL` dst = dead link),
-and `sections` (heading outline with line ranges and token estimates). Features add their own
-storage; `map` and `status` report which are on.
+SQL over a markdown tree, kept fresh by a filesystem check on every query. Every file becomes rows in `frontmatter` (one column per key, plus `path`/`_mtime`/`_size`/`_rank`), `content` (FTS5: `title`, `summary`, `text`), `links` (`src`, `target`, `dst`; `NULL` dst = dead link), and `sections` (heading outline with line ranges and token estimates). Features add their own 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 `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 `search --where`. Enumerates every match;
-  same result regardless of phrasing.
-- 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]`
-  ranges, links both ways. Every list shows its first 20 with the true total; the
-  `sections` and `links` tables hold the rest, so a peek costs a few hundred tokens on any
-  note — heading-dense monsters included.
-- When you know the file and need its contents, `Read` it — sense adds nothing there. On
-  large files peek's ranges let you read just one section; small files are often cheaper
-  whole.
-
-Output defaults to a table, built for humans; `--format json` returns the same rows
-machine-parseable. That also makes a saved query usable as a CI/hook gate with zero added
-mechanism: `[ "$(sense <query> --format json)" = "[]" ]` is true exactly when the query
-returned no rows.
+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 `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 `search --where`. Enumerates every match; same result regardless of phrasing.
+- 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. A `vector`-only row means the search words don't appear in that note; it showed up because the model judged it semantically related. 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]` ranges, links both ways. Every list shows its first 20 with the true total; the `sections` and `links` tables hold the rest, so a peek costs a few hundred tokens on any note, heading-dense monsters included.
+- When you know the file and need its contents, `Read` it. sense adds nothing there. On large files peek's ranges let you read just one section; small files are often cheaper whole.
+
+Output defaults to a table, built for humans; `--format json` returns the same rows machine-parseable. That also makes a saved query usable as a CI/hook gate with zero added mechanism: `[ "$(sense <query> --format json)" = "[]" ]` is true exactly when the query returned no rows.
 
 ## Commands
 
@@ -56,54 +31,15 @@ sense <name> [params...]                        # named query or saved search fr
 sense --list | status | rebuild | check
 ```
 
-- Terms pass verbatim to FTS5 MATCH. Bare words AND-join — one absent word means zero rows —
-  so write `OR` yourself when you want any-word matching; double-quote punctuated terms
-  (`"customer-facing"`, `"founder's"`); invalid syntax is an error, not a rewrite. The same
-  rules apply to search commands you write into subagent briefs.
-- When a search misses, the recall levers are: OR-in synonyms and concrete instances (the
-  index only knows the words in the files — a note about a specific tool rarely names its
-  category), 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.
-- 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
-  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.
-- 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.
+- Terms pass verbatim to FTS5 MATCH. Bare words AND-join (one absent word means zero rows), so write `OR` yourself when you want any-word matching; double-quote punctuated terms (`"customer-facing"`, `"founder's"`); invalid syntax is an error, not a rewrite. The same rules apply to search commands you write into subagent briefs.
+- When a search misses, the recall levers are: OR-in synonyms and concrete instances (the index only knows the words in the files; a note about a specific tool rarely names its category), 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.
+- 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 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.
+- 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
 
@@ -119,55 +55,22 @@ sense query "SELECT heading, start_line, tokens FROM sections WHERE path = ?" a.
 sense query "SELECT j.value, COUNT(*) n FROM frontmatter, json_each(frontmatter.tags) j GROUP BY j.value ORDER BY n DESC"   # count per array member
 ```
 
-- `content MATCH` takes FTS5 syntax: `a OR b`, `"phrase"`, `pref*`, `NEAR(a b, 5)`,
-  `summary: term`. Stemmed; markdown stripped at index time. Double-quote any term with
-  punctuation — bare `customer-facing` errors (`-` reads as a column filter), bare
-  apostrophes are syntax errors: write `"customer-facing"`, `"founder's"`.
-- 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. `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
-  `f.title`/`f.summary` (discovered columns — error on trees that never declare them).
-- Frontmatter values keep their YAML type: strings are TEXT, whole numbers and booleans are
-  INTEGER (`true` stores as 1, so `WHERE flag = 1` matches and `WHERE flag = 'true'` matches
-  nothing), fractions are REAL, lists and maps are JSON text. `map` prints the observed type
-  per field, and a field showing two types (`integer,text`) has drifted across notes.
-- `has(field, value)`: array membership on JSON-array fields, substring on strings, false on NULL
-  — the `includes()` convention. Substring means `has(f.status, 'active')` also matches
-  `inactive`; exact scalar match is `f.status = ?`, deliberate substring is `LIKE`, exact array
-  membership is `EXISTS (SELECT 1 FROM json_each(f.tags) WHERE value = ?)`.
-  To aggregate per member instead, use `json_each(frontmatter.<field>)` (above) -- GROUP BY on the
-  raw column splits `["a","b"]` and `["b","a"]` into separate buckets.
-- Date fields are stored as written. Compare through `datetime()`, which normalizes ISO 8601
-  timezone offsets to UTC: `WHERE datetime(created) >= datetime(?)`. Bare string comparison
-  is only safe when every note uses the same offset.
-- To bound what a query puts into context: `snippet()` excerpts just the matching text,
-  `LIMIT` caps row counts, and selecting `path`/`title`/`summary` keeps rows small.
-  `SELECT text FROM content` returns the tree's entire prose (sense warns past 50 KB).
-  Aggregates (`COUNT`, `GROUP BY`) are already bounded. `SELECT * FROM frontmatter` is always
-  safe — prose is not a frontmatter column.
+- `content MATCH` takes FTS5 syntax: `a OR b`, `"phrase"`, `pref*`, `NEAR(a b, 5)`, `summary: term`. Stemmed; markdown stripped at index time. Double-quote any term with punctuation. Bare `customer-facing` errors (`-` reads as a column filter), bare apostrophes are syntax errors: write `"customer-facing"`, `"founder's"`.
+- 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. `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 `f.title`/`f.summary` (discovered columns; error on trees that never declare them).
+- Frontmatter values keep their YAML type: strings are TEXT, whole numbers and booleans are INTEGER (`true` stores as 1, so `WHERE flag = 1` matches and `WHERE flag = 'true'` matches nothing), fractions are REAL, lists and maps are JSON text. `map` prints the observed type per field, and a field showing two types (`integer,text`) has drifted across notes.
+- `has(field, value)`: array membership on JSON-array fields, substring on strings, false on NULL. This is the `includes()` convention. Substring means `has(f.status, 'active')` also matches `inactive`; exact scalar match is `f.status = ?`, deliberate substring is `LIKE`, exact array membership is `EXISTS (SELECT 1 FROM json_each(f.tags) WHERE value = ?)`. To aggregate per member instead, use `json_each(frontmatter.<field>)` (above) -- GROUP BY on the raw column splits `["a","b"]` and `["b","a"]` into separate buckets.
+- Date fields are stored as written. Compare through `datetime()`, which normalizes ISO 8601 timezone offsets to UTC: `WHERE datetime(created) >= datetime(?)`. Bare string comparison is only safe when every note uses the same offset.
+- To bound what a query puts into context: `snippet()` excerpts just the matching text, `LIMIT` caps row counts, and selecting `path`/`title`/`summary` keeps rows small. `SELECT text FROM content` returns the tree's entire prose (sense warns past 50 KB). Aggregates (`COUNT`, `GROUP BY`) are already bounded. `SELECT * FROM frontmatter` is always safe: prose is not a frontmatter column.
 
 Worked traces: [EXAMPLES.md](EXAMPLES.md).
 
 ## Setup and upkeep
 
-- 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 (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`.
+- 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 (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
-  with time and offset) — the only format `datetime()` parses. Field names in examples
-  (`status`, `tags`, `created`) are illustrative; your tree defines its own.
-- Reserved frontmatter keys (dropped with a warning): `path`, `_mtime`, `_size`, `_rank`,
-  `content`, `links`, `sections`.
-- Exit codes: `0` ok, `1` error (SQLite message verbatim), `2` usage (unknown query, wrong
-  param count).
-- Doubted cache: `sense rebuild`. Rarely needed — every query reconciles first.
+- A one-line `summary:` per note is optional and pays twice: it appears in result rows and is a weighted search field. Date comparisons work for dates written as ISO 8601 (`2026-08-12`, or with time and offset), the only format `datetime()` parses. Field names in examples (`status`, `tags`, `created`) are illustrative; your tree defines its own.
+- Reserved frontmatter keys (dropped with a warning): `path`, `_mtime`, `_size`, `_rank`, `content`, `links`, `sections`.
+- Exit codes: `0` ok, `1` error (SQLite message verbatim), `2` usage (unknown query, wrong param count).
+- Doubted cache: `sense rebuild`. Rarely needed; every query reconciles first.

package/skills/sense-setup/EXAMPLES.md

@@ -1,13 +1,10 @@
 # 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.
+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.
+`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
 {
@@ -31,17 +28,11 @@ sense search "rotary embeddings" --preset raw   # cite from sources; lexical, k=
 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.
+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.
+`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
 {
@@ -69,17 +60,11 @@ sense retirement                                # old + uncited → move to arch
 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.
+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.
+`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
 {
@@ -105,8 +90,7 @@ sense unread                                    # the reading queue: sources no
 
 ## 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:
+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
@@ -115,7 +99,4 @@ sense query "SELECT j.value AS tag, COUNT(*) n FROM frontmatter, json_each(front
 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.
+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.

package/skills/sense-setup/SKILL.md

@@ -1,32 +1,21 @@
 ---
 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, vectors on or off), 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, 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, vectors on or off), 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, configuring search scope or vectors, or deciding how notes should be written for an agent to query later.
 ---
 
 # sense: setup and tree design
 
-Querying an existing tree is the `sense` skill. This one covers making a tree:
-installing, writing presets, and the design decisions a tree owner faces.
-Worked configurations for common tree shapes: [EXAMPLES.md](EXAMPLES.md).
+Querying an existing tree is the `sense` skill. This one covers making a tree: installing, writing presets, and the design decisions a tree owner faces. Worked configurations for common tree shapes: [EXAMPLES.md](EXAMPLES.md).
 
 ## 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
-  vault tunes), everything on. Config discovery walks up from cwd;
-  `--config <path>` overrides.
+- `npm install -g sensemaking`, then `sense init` at the tree root writes `sense.config.json`: two presets (`default`, and `large` showing what a big vault tunes), everything on. Config discovery walks up from cwd; `--config <path>` overrides.
 - 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.
+- `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.
 
 ## Presets
 
-A preset is a named, self-contained bundle of settings. `default` (required) is
-what bare commands use; every other preset is addressed by name
-(`sense search "..." --preset raw`, or `"preset": "raw"` in a saved search).
-No inheritance: what a preset states is all it does.
+A preset is a named, self-contained bundle of settings. `default` (required) is what bare commands use; every other preset is addressed by name (`sense search "..." --preset raw`, or `"preset": "raw"` in a saved search). No inheritance: what a preset states is all it does.
 
 | field | means | default |
 |---|---|---|
@@ -35,76 +24,26 @@ No inheritance: what a preset states is all it does.
 | `semantic` | vectors for this preset's files and searches | on; only ever written as `false` |
 | `where` | a standing SQL filter on frontmatter | none |
 
-**Indexing derives from presets.** A file is indexed if any preset includes it;
-it is embedded if any covering preset has semantic on. Consequences worth
-designing around:
+**Indexing derives from presets.** A file is indexed if any preset includes it; it is embedded if any covering preset has semantic on. Consequences worth designing around:
 
-- A layer of the tree covered only by a `semantic: false` preset (raw sources,
-  archives, generated output) is fully searchable lexically and by SQL but
-  costs no vector work — the main scale lever.
+- A layer of the tree covered only by a `semantic: false` preset (raw sources, archives, generated output) is fully searchable lexically and by SQL but costs no vector work. This is the main scale lever.
 - Files no preset includes are not indexed at all.
 - Presets may overlap; they are views, not partitions.
-- The first semantic search embeds everything covered (progress on stderr;
-  minutes on tens of thousands of notes, seconds on small trees). Vectors use
-  the built-in static model unless a top-level
-  `"embed": { "model", "type": "static"|"api", "url", "key" }` block points at
-  a Model2Vec model, local path, or OpenAI-compatible endpoint. `static`
-  handles paraphrase and reworded concepts; tight domain jargon ("heart
-  attack" for "myocardial infarction") is where an `api` transformer model
-  tends to do better — measured in BENCHMARKING.md, "Retrieval quality".
-- Global `features` (`links`, `sections`, `rank`) still toggle tree-wide;
-  most trees never touch them.
+- The first semantic search embeds everything covered (progress on stderr; minutes on tens of thousands of notes, seconds on small trees). Vectors use the built-in static model unless a top-level `"embed": { "model", "type": "static"|"api", "url", "key" }` block points at a Model2Vec model, local path, or OpenAI-compatible endpoint. `static` handles paraphrase and reworded concepts; tight domain jargon ("heart attack" for "myocardial infarction") is where an `api` transformer model tends to do better, measured in BENCHMARKING.md, "Retrieval quality".
+- Global `features` (`links`, `sections`, `rank`) still toggle tree-wide; most trees never touch them.
 
-**Large vaults**: everything except the vector build is measured linear to
-100k notes with no tuning (BENCHMARKING.md). The knobs that matter are `k`
-(more, smaller results — rows carry `lines` section ranges, so agents read
-sections, not files) and `semantic: false` on the layers that don't earn
-vectors.
+**Large vaults**: everything except the vector build is measured linear to 100k notes with no tuning (BENCHMARKING.md). The knobs that matter are `k` (more, smaller results; rows carry `lines` section ranges, so agents read sections, not files) and `semantic: false` on the layers that don't earn vectors.
 
 ## Tree design decisions
 
-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 named queries possible (`WHERE status = 'active'`). SQLite's compiled
-  column limit (2,000; sqlite.org/limits.html) bounds distinct keys per tree —
-  the crawl stops with an error naming the count and the levers. Reserved keys
-  (dropped with a warning): `path`, `_mtime`, `_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.
-- **Summaries.** A one-line `summary:` is optional and pays twice: it shows in
-  every result row (often answering a question with no file read) and is a
-  weighted search field ranked above body text. The cost is writing and
-  maintaining the line as notes change.
-- **Folder shape.** Globs find the files, paths are queryable text, links
-  resolve by basename at any depth — but presets make folders meaningful:
-  a folder is the natural unit that gets its own coverage and settings.
-- **Note size.** Many small notes: precise search hits, whole-file reads stay
-  cheap, more links to maintain. Fewer large notes: `sections`, `peek`, and
-  the `lines` column carry the cost down to line-range reads. Both work.
-- **Recurring questions.** Save a scenario an agent will repeat: a SQL string
-  for filters and reports, or a saved search
-  (`"hot": { "search": "...", "preset": "raw", "k": 5 }`). Either runs as
-  `sense <name>`, and `sense check` validates both kinds against the real
-  tree, so a broken saved scenario fails at check time, not mid-task.
-- **Where decisions live.** Choices that should outlive one conversation can
-  be recorded in the agent's own instruction or skill files, or in a note in
-  the tree itself; a one-off search over an existing corpus needs none of
-  that.
+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 named queries possible (`WHERE status = 'active'`). SQLite's compiled column limit (2,000; sqlite.org/limits.html) bounds distinct keys per tree. The crawl stops with an error naming the count and the levers. Reserved keys (dropped with a warning): `path`, `_mtime`, `_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.
+- **Summaries.** A one-line `summary:` is optional and pays twice: it shows in every result row (often answering a question with no file read) and is a weighted search field ranked above body text. The cost is writing and maintaining the line as notes change.
+- **Folder shape.** Globs find the files, paths are queryable text, links resolve by basename at any depth, but presets make folders meaningful: a folder is the natural unit that gets its own coverage and settings.
+- **Note size.** Many small notes: precise search hits, whole-file reads stay cheap, more links to maintain. Fewer large notes: `sections`, `peek`, and the `lines` column carry the cost down to line-range reads. Both work.
+- **Recurring questions.** Save a scenario an agent will repeat: a SQL string for filters and reports, or a saved search (`"hot": { "search": "...", "preset": "raw", "k": 5 }`). Either runs as `sense <name>`, and `sense check` validates both kinds against the real tree, so a broken saved scenario fails at check time, not mid-task.
+- **Where decisions live.** Choices that should outlive one conversation can be recorded in the agent's own instruction or skill files, or in a note in the tree itself; a one-off search over an existing corpus needs none of that.

package/dist/cjs/cli/exit.d.cts

@@ -1,5 +0,0 @@
-export declare class ExitError extends Error {
-    readonly code: number;
-    constructor(code: number);
-}
-export declare function usageError(message: string, usage?: string): never;

package/dist/cjs/cli/exit.d.ts

@@ -1,5 +0,0 @@
-export declare class ExitError extends Error {
-    readonly code: number;
-    constructor(code: number);
-}
-export declare function usageError(message: string, usage?: string): never;

package/dist/cjs/cli/exit.js

@@ -1,147 +0,0 @@
-// Commands never end the process themselves: they throw this, and cli.ts -- the one place
-// that owns the exit -- drains stdio through exit-compat and returns. Neither alternative
-// works here: a direct process.exit() races a pending write, and a bare return would let a
-// command body run on after --help had already printed its usage.
-"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 ExitError () {
-        return ExitError;
-    },
-    get usageError () {
-        return usageError;
-    }
-});
-function _assert_this_initialized(self) {
-    if (self === void 0) {
-        throw new ReferenceError("this hasn't been initialised - super() hasn't been called");
-    }
-    return self;
-}
-function _call_super(_this, derived, args) {
-    derived = _get_prototype_of(derived);
-    return _possible_constructor_return(_this, _is_native_reflect_construct() ? Reflect.construct(derived, args || [], _get_prototype_of(_this).constructor) : derived.apply(_this, args));
-}
-function _class_call_check(instance, Constructor) {
-    if (!(instance instanceof Constructor)) {
-        throw new TypeError("Cannot call a class as a function");
-    }
-}
-function _construct(Parent, args, Class) {
-    if (_is_native_reflect_construct()) {
-        _construct = Reflect.construct;
-    } else {
-        _construct = function construct(Parent, args, Class) {
-            var a = [
-                null
-            ];
-            a.push.apply(a, args);
-            var Constructor = Function.bind.apply(Parent, a);
-            var instance = new Constructor();
-            if (Class) _set_prototype_of(instance, Class.prototype);
-            return instance;
-        };
-    }
-    return _construct.apply(null, arguments);
-}
-function _get_prototype_of(o) {
-    _get_prototype_of = Object.setPrototypeOf ? Object.getPrototypeOf : function getPrototypeOf(o) {
-        return o.__proto__ || Object.getPrototypeOf(o);
-    };
-    return _get_prototype_of(o);
-}
-function _inherits(subClass, superClass) {
-    if (typeof superClass !== "function" && superClass !== null) {
-        throw new TypeError("Super expression must either be null or a function");
-    }
-    subClass.prototype = Object.create(superClass && superClass.prototype, {
-        constructor: {
-            value: subClass,
-            writable: true,
-            configurable: true
-        }
-    });
-    if (superClass) _set_prototype_of(subClass, superClass);
-}
-function _is_native_function(fn) {
-    return Function.toString.call(fn).indexOf("[native code]") !== -1;
-}
-function _possible_constructor_return(self, call) {
-    if (call && (_type_of(call) === "object" || typeof call === "function")) {
-        return call;
-    }
-    return _assert_this_initialized(self);
-}
-function _set_prototype_of(o, p) {
-    _set_prototype_of = Object.setPrototypeOf || function setPrototypeOf(o, p) {
-        o.__proto__ = p;
-        return o;
-    };
-    return _set_prototype_of(o, p);
-}
-function _type_of(obj) {
-    "@swc/helpers - typeof";
-    return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
-}
-function _wrap_native_super(Class) {
-    var _cache = typeof Map === "function" ? new Map() : undefined;
-    _wrap_native_super = function wrapNativeSuper(Class) {
-        if (Class === null || !_is_native_function(Class)) return Class;
-        if (typeof Class !== "function") {
-            throw new TypeError("Super expression must either be null or a function");
-        }
-        if (typeof _cache !== "undefined") {
-            if (_cache.has(Class)) return _cache.get(Class);
-            _cache.set(Class, Wrapper);
-        }
-        function Wrapper() {
-            return _construct(Class, arguments, _get_prototype_of(this).constructor);
-        }
-        Wrapper.prototype = Object.create(Class.prototype, {
-            constructor: {
-                value: Wrapper,
-                enumerable: false,
-                writable: true,
-                configurable: true
-            }
-        });
-        return _set_prototype_of(Wrapper, Class);
-    };
-    return _wrap_native_super(Class);
-}
-function _is_native_reflect_construct() {
-    try {
-        var result = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function() {}));
-    } catch (_) {}
-    return (_is_native_reflect_construct = function() {
-        return !!result;
-    })();
-}
-var ExitError = /*#__PURE__*/ function(Error1) {
-    "use strict";
-    _inherits(ExitError, Error1);
-    function ExitError(code) {
-        _class_call_check(this, ExitError);
-        var _this;
-        _this = _call_super(this, ExitError, [
-            "exit ".concat(code)
-        ]);
-        _this.code = code;
-        return _this;
-    }
-    return ExitError;
-}(_wrap_native_super(Error));
-function usageError(message, usage) {
-    console.error(message);
-    if (usage !== undefined) console.error(usage);
-    throw new ExitError(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/cli/exit.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/exit.ts"],"sourcesContent":["// Commands never end the process themselves: they throw this, and cli.ts -- the one place\n// that owns the exit -- drains stdio through exit-compat and returns. Neither alternative\n// works here: a direct process.exit() races a pending write, and a bare return would let a\n// command body run on after --help had already printed its usage.\nexport class ExitError extends Error {\n  readonly code: number;\n  constructor(code: number) {\n    super(`exit ${code}`);\n    this.code = code;\n  }\n}\n\nexport function usageError(message: string, usage?: string): never {\n  console.error(message);\n  if (usage !== undefined) console.error(usage);\n  throw new ExitError(2);\n}\n"],"names":["ExitError","usageError","code","Error","message","usage","console","error","undefined"],"mappings":"AAAA,0FAA0F;AAC1F,0FAA0F;AAC1F,2FAA2F;AAC3F,kEAAkE;;;;;;;;;;;;QACrDA;eAAAA;;QAQGC;eAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AART,IAAA,AAAMD,0BAAN;;cAAMA;aAAAA,UAECE,IAAY;gCAFbF;;gBAGT,kBAHSA;YAGF,QAAY,OAALE;;QACd,MAAKA,IAAI,GAAGA;;;WAJHF;qBAAkBG;AAQxB,SAASF,WAAWG,OAAe,EAAEC,KAAc;IACxDC,QAAQC,KAAK,CAACH;IACd,IAAIC,UAAUG,WAAWF,QAAQC,KAAK,CAACF;IACvC,MAAM,IAAIL,UAAU;AACtB"}

package/dist/esm/cli/exit.d.ts

@@ -1,5 +0,0 @@
-export declare class ExitError extends Error {
-    readonly code: number;
-    constructor(code: number);
-}
-export declare function usageError(message: string, usage?: string): never;

package/dist/esm/cli/exit.js

@@ -1,15 +0,0 @@
-// Commands never end the process themselves: they throw this, and cli.ts -- the one place
-// that owns the exit -- drains stdio through exit-compat and returns. Neither alternative
-// works here: a direct process.exit() races a pending write, and a bare return would let a
-// command body run on after --help had already printed its usage.
-export class ExitError extends Error {
-    constructor(code){
-        super(`exit ${code}`);
-        this.code = code;
-    }
-}
-export function usageError(message, usage) {
-    console.error(message);
-    if (usage !== undefined) console.error(usage);
-    throw new ExitError(2);
-}

package/dist/esm/cli/exit.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/exit.ts"],"sourcesContent":["// Commands never end the process themselves: they throw this, and cli.ts -- the one place\n// that owns the exit -- drains stdio through exit-compat and returns. Neither alternative\n// works here: a direct process.exit() races a pending write, and a bare return would let a\n// command body run on after --help had already printed its usage.\nexport class ExitError extends Error {\n  readonly code: number;\n  constructor(code: number) {\n    super(`exit ${code}`);\n    this.code = code;\n  }\n}\n\nexport function usageError(message: string, usage?: string): never {\n  console.error(message);\n  if (usage !== undefined) console.error(usage);\n  throw new ExitError(2);\n}\n"],"names":["ExitError","Error","code","usageError","message","usage","console","error","undefined"],"mappings":"AAAA,0FAA0F;AAC1F,0FAA0F;AAC1F,2FAA2F;AAC3F,kEAAkE;AAClE,OAAO,MAAMA,kBAAkBC;IAE7B,YAAYC,IAAY,CAAE;QACxB,KAAK,CAAC,CAAC,KAAK,EAAEA,MAAM;QACpB,IAAI,CAACA,IAAI,GAAGA;IACd;AACF;AAEA,OAAO,SAASC,WAAWC,OAAe,EAAEC,KAAc;IACxDC,QAAQC,KAAK,CAACH;IACd,IAAIC,UAAUG,WAAWF,QAAQC,KAAK,CAACF;IACvC,MAAM,IAAIL,UAAU;AACtB"}