sensemaking 0.9.4 → 0.9.5

package/README.md

@@ -1,18 +1,12 @@
 # sensemaking
 
-Query and search a tree of markdown notes: SQL over frontmatter and links, ranked search over
-the prose — words, links, and meaning fused. A CLI that starts, answers, and exits — no
-server, no build step.
+Query and search your markdown notes with context-aware progressive disclosure: SQL over frontmatter, links, and text, plus semantic search and link-graph ranking. No server, no build step.
 
 ## Problem
 
-Working with AI agents produces piles of small notes. Past a few dozen, finding the right ones
-means grepping or reading whole folders into context. The structure that makes notes navigable —
-frontmatter, wikilinks, headings — is exactly what an agent needs, but nothing exposes it as a
-query surface.
+Markdown notes accumulate: research, decisions, meeting notes, agent output. Past a few dozen, finding the ones relevant to what you're doing means grepping or reading whole folders into context. The structure that makes notes navigable (frontmatter, wikilinks, headings) is exactly what a query needs, but nothing exposes it as a query surface.
 
-`sense` indexes all of it into SQLite and reconciles against file timestamps on every query, so
-results are never stale and nothing has to be running.
+`sense` indexes all of it into SQLite and reconciles against file timestamps on every query, so results are never stale and nothing has to be running.
 
 ## Quick start
 
@@ -21,8 +15,7 @@ npm install -g sensemaking
 cd your-notes && sense init
 ```
 
-Needs Node 22.16 or newer: that is the first release whose built-in SQLite carries FTS5, which
-`sense search` indexes prose with.
+Needs Node 22.16 or newer: that is the first release whose built-in SQLite carries FTS5, which `sense search` indexes prose with.
 
 ```bash
 sense map                                        # orient: fields, hub notes, recent changes
@@ -42,14 +35,9 @@ Every file becomes rows in these tables, plus whatever an enabled feature adds o
 | `links` | `src`, `target` as written, `dst` resolved (`NULL` = dead link) | graph |
 | `sections` | heading, `level`, `start_line`, `end_line`, `tokens` estimate | structure |
 
-Results are references — path, title, summary, excerpt — never file contents. Reading happens
-afterward through the filesystem, scoped to the line ranges `peek` returns. This is the
-[just-in-time context pattern](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents):
-the agent holds lightweight identifiers and loads payloads only when needed.
+Results are references (path, title, summary, excerpt), never file contents. Reading happens afterward through the filesystem, scoped to the line ranges `peek` returns. This is the [just-in-time context pattern](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents): the agent holds lightweight identifiers and loads payloads only when needed.
 
-Output size is a contract, measured per release ([BENCHMARKING.md](BENCHMARKING.md)): `map` is
-fixed-size, a `find` row is tens of tokens, and a `peek` stays flat however large the note is —
-so what it saves over reading grows with the file, and a small note is cheaper read whole.
+Output size is a contract, measured per release ([BENCHMARKING.md](BENCHMARKING.md)): `map` is fixed-size, a `find` row is tens of tokens, and a `peek` stays flat however large the note is. What it saves over reading grows with the file; a small note is cheaper to read whole.
 
 ```sql
 -- filter and search compose in one query
@@ -65,7 +53,7 @@ ORDER BY bm25(content, 10.0, 5.0, 1.0) LIMIT 10
 |---|---|
 | `map` | doc count, frontmatter field coverage, top hubs by link rank, recent changes |
 | `search "<text>" [--preset name] [--include glob] [--where "<sql>"] [--k n] [--lexical]` | words + links + vectors, one fused ranked list; `via` labels each row's evidence |
-| `peek <path>` | frontmatter + heading outline (`[L143-162, ~380t]`) + links both ways — first 20 per list, each with its total; the `links` table has the rest |
+| `peek <path>` | frontmatter + heading outline (`[L143-162, ~380t]`) + links both ways: first 20 per list, each with its total; the `links` table has the rest |
 | `query "<sql>" [params...]` | ad-hoc SQL over all the tables; `?` binds positional args |
 | `<name> [params...]` | run a query saved in the config; `--list` names them |
 | `init` | write a starter `sense.config.json` |
@@ -74,21 +62,11 @@ ORDER BY bm25(content, 10.0, 5.0, 1.0) LIMIT 10
 | `rebuild` | delete the cache and re-crawl |
 | `watch` | keep the index warm in the background (optional; see [WATCH.md](WATCH.md)) |
 
-`search` runs one text through every engine its scope has — FTS5 word match (BM25-ranked,
-bare words AND-join, operators are yours), a personalized-PageRank walk over the link graph,
-and vector similarity — fused into one list. `via` labels each row's evidence (`match`,
-`link`, `vector`, combinations); `similarity` is the cosine against the best-matching chunk;
-`lines` points at the section that earned the row — a direct read range. Rows that only
-vectors produced are the "these words aren't in the tree, this is what's near in meaning"
-signal. `--preset` picks a named settings bundle from the config, `--lexical` skips vectors
-for one command, `--where` filters on frontmatter. `--format json` on any reporting command returns
-structured output; `--version` and `--help` do what they say.
+`search` runs one text through every engine its scope has: FTS5 word match (BM25-ranked, bare words AND-join, operators are yours), a personalized-PageRank walk over the link graph, and vector similarity, fused into one list. `via` labels each row's evidence (`match`, `link`, `vector`, combinations); `similarity` is the cosine against the best-matching chunk; `lines` points at the section that earned the row (a direct read range). A `vector`-only row means the search words don't appear in that note; it showed up because the model judged it semantically related. `--preset` picks a named settings bundle from the config, `--lexical` skips vectors for one command, `--where` filters on frontmatter. `--format json` on any reporting command returns structured output; `--version` and `--help` do what they say.
 
 ## Config
 
-`sense init` writes `sense.config.json`; discovery walks up from cwd like git
-(`--config <path>` overrides). Three keys: **presets** (named, self-contained setting
-bundles), **queries** (saved commands), and the version.
+`sense init` writes `sense.config.json`; discovery walks up from cwd like git (`--config <path>` overrides).
 
 ```json
 {
@@ -106,46 +84,27 @@ bundles), **queries** (saved commands), and the version.
 }
 ```
 
-A preset bundles `include`/`exclude` globs (which files), `k` (result count), `semantic`
-(vectors, on unless `false`), and `where` (a standing SQL filter). Bare commands use
-`default`; `--preset` names another; flags override single fields. **Indexing derives from
-the presets**: a file is indexed if any preset includes it, and embedded if any covering
-preset has semantic on — so a `semantic: false` preset's files cost no vectors, and
-`status` shows each preset's coverage. Editing a preset rebuilds the cache and says which
-preset caused it.
+| key | holds |
+|---|---|
+| `presets` | named bundles of `include`/`exclude` globs, `k` (result count), `semantic` (vectors, on unless `false`), `where` (a standing SQL filter). A file is indexed if any preset includes it, embedded if any covering preset has `semantic` on. A `semantic: false` preset's files cost no vectors, and `status` shows each preset's coverage. |
+| `queries` | a SQL string (`?` binds positional args) or a saved search with its settings baked in: `sense hot` needs no flags. `sense check` runs them all, so a typo'd column fails at check time instead of mid-task. |
+| `version` | schema version; older configs auto-migrate on load, noted on stderr. |
 
-A query entry is a SQL string (`?` binds positional args) or a saved search with its
-settings baked in — `sense hot` needs no flags. `sense check` runs them all, so a typo'd
-column fails at check time instead of mid-task. Older config versions auto-migrate on
-load, noted on stderr.
+Bare commands use the `default` preset; `--preset` names another; flags override single fields. Editing a preset rebuilds the cache and says which preset caused it.
 
-Vectors use the built-in static model (downloaded to `~/.cache/sensemaking` on first use,
-never in the package); an optional top-level `"embed": { "model", "type", "url", "key" }`
-block points at any Model2Vec model, local path, or OpenAI-compatible endpoint (Ollama,
-LM Studio, hosted). Embedding happens on the first semantic search, with progress.
+Vectors use the built-in static model (downloaded to `~/.cache/sensemaking` on first use, never in the package); an optional top-level `"embed": { "model", "type", "url", "key" }` block points at any Model2Vec model, local path, or OpenAI-compatible endpoint (Ollama, LM Studio, hosted). Embedding happens on the first semantic search, with progress.
 
-`has(field, value)` is the one custom SQL function: array membership on JSON-array fields,
-substring on strings, false on missing keys. Frontmatter parsing is lenient — syntax errors are
-per-file warnings and the values are still indexed, so one bad note never costs you the crawl.
+`has(field, value)` is the one custom SQL function: array membership on JSON-array fields, substring on strings, false on missing keys. Frontmatter parsing is lenient: syntax errors are per-file warnings, and the values are still indexed, so one bad note never costs you the crawl.
 
 ## Scale
 
-Every query starts with a freshness check against the cache in `.sense/`; only changed files are
-re-parsed. What to expect as a tree grows:
+Every query starts with a freshness check against the cache in `.sense/`; only changed files are re-parsed. What to expect as a tree grows:
 
-- **Work is linear in note count** — crawl, reconcile, and the freshness check every invocation
-  pays. That check is the floor cost of a query and the first thing to watch on a large tree.
-- **Output is flat.** `map`, `peek`, and a `find` row cost the same on a small tree as a large
-  one: context cost is bounded by what you ask for, not by how much there is.
-- **Bulk changes are paid by whoever queries next.** `sense watch` moves that re-parse into the
-  background ([WATCH.md](WATCH.md)) — it changes latency, never answers, since every query
-  reconciles for itself. `sense rebuild` starts the cache over.
+- **Work is linear in note count.** Crawl, reconcile, and the freshness check are what every invocation pays; that check is the floor cost of a query and the first thing to watch on a large tree.
+- **Output is flat.** `map`, `peek`, and a search row cost the same on a small tree as a large one: context cost is bounded by what you ask for, not by how much there is.
+- **Bulk changes are paid by whoever queries next.** `sense watch` moves that re-parse into the background ([WATCH.md](WATCH.md)): it changes latency, never answers, since every query reconciles for itself. `sense rebuild` starts the cache over.
 
-These are release gates rather than hopes: every release regenerates the numbers on pinned
-corpora spanning a 4x range in note count plus a stress tree that packs the worst measured
-shapes into one place — a megabyte-scale note, heading-dense outlines, dense link graphs,
-hundreds of frontmatter fields. A row that grows faster than linearly, or a token count
-that grows at all, blocks the release. Current figures: [BENCHMARKING.md](BENCHMARKING.md).
+These are release gates rather than hopes: every release regenerates the numbers on pinned corpora spanning a 4x range in note count plus a stress tree that packs the worst measured shapes into one place: a megabyte-scale note, heading-dense outlines, dense link graphs, hundreds of frontmatter fields. A row that grows faster than linearly, or a token count that grows at all, blocks the release. Current figures: [BENCHMARKING.md](BENCHMARKING.md).
 
 ## For AI agents
 
@@ -153,40 +112,25 @@ that grows at all, blocks the release. Current figures: [BENCHMARKING.md](BENCHM
 npx skills add kmalakoff/sensemaking   # -g for global, -a claude-code to target
 ```
 
-Two skills: `sense` for querying a tree — what each command is for, FTS5 syntax, reading the
-`via`/`score`/`similarity` columns, worked examples — and `sense-setup` for making one, where
-features, frontmatter conventions, and note size are decisions with consequences either way.
+Two skills: `sense` for querying a tree (what each command is for, FTS5 syntax, reading the `via`/`score`/`similarity` columns, worked examples) and `sense-setup` for making one, where features, frontmatter conventions, and note size are decisions with consequences either way.
 
 ## Prior art
 
-- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
-  (Anthropic): agents should hold lightweight identifiers — file paths, links — and load payloads
-  just in time, because context is a finite resource. The commands implement that pattern as a CLI.
-- [llm-wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) (Karpathy): an
-  agent-maintained wiki navigated by an `index.md` and links, which he notes needs real search
-  infrastructure past a few hundred pages. `sense map` derives that index from the notes instead of
-  maintaining it; `find` is the hybrid local search it calls for.
-- Agent memory patterns — llm-wiki's raw/wiki split, Claude Code's dreaming-style nightly
-  consolidation — are trees of small notes with metadata, links, and layers of differing
-  authority. sense is the query layer such patterns need (filter by metadata and age, scope
-  by layer, surface near-duplicates semantically), not an implementation of any one of them.
+- [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents) (Anthropic): agents should hold lightweight identifiers (file paths, links) and load payloads just in time, because context is a finite resource. The commands implement that pattern as a CLI.
+- [llm-wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) (Karpathy): an agent-maintained wiki navigated by an `index.md` and links, which he notes needs real search infrastructure past a few hundred pages. `sense map` derives that index from the notes instead of maintaining it; `find` is the hybrid local search it calls for.
+- Agent memory patterns (llm-wiki's raw/wiki split, Claude Code's dreaming-style nightly consolidation) are trees of small notes with metadata, links, and layers of differing authority. sense is the query layer such patterns need: filter by metadata and age, scope by layer, surface near-duplicates semantically. It isn't an implementation of any one of them.
 
 ## Alternatives
 
-- **Obsidian Bases/Dataview** — same filters, but only inside the running app; agents can't
-  query it headless.
-- **Index-on-build tools (MarkdownDB)** — query a snapshot; `sense` reconciles on every query.
-- **Note CLIs (zk)** — fixed schema; `sense` filters on arbitrary frontmatter.
-- **RAG / vector stores** — similarity can't express `WHERE status = 'active'`. Here vectors
-  are one signal inside `search`: same SQLite file, filters compose, every row labels its
-  evidence (`via`), and a preset turns vectors off per layer of the tree — no second store,
-  no daemon, no native builds.
-
-Dependencies: [yaml](https://github.com/eemeli/yaml),
-[remove-markdown](https://github.com/zuchka/remove-markdown),
-[fast-glob](https://github.com/mrmlnc/fast-glob),
-[@huggingface/tokenizers](https://github.com/huggingface/tokenizers.js) (pure JS), and
-Node's built-in SQLite. No native builds.
+- **Obsidian Bases/Dataview:** same filters, but only inside the running app; agents can't query it headless.
+- **Index-on-build tools (MarkdownDB):** query a snapshot; `sense` reconciles on every query.
+- **Note CLIs (zk):** fixed schema; `sense` filters on arbitrary frontmatter.
+- **Graph/LSP tools (IWE):** structural queries over a markdown graph via LSP/CLI/MCP, retrieval by structure rather than similarity; no SQL, no vector search.
+- **Markdown vector stores (markdown-vdb):** hybrid BM25 + vector search over markdown files, no frontmatter filtering; `sense` treats vectors as one signal alongside SQL, not the whole store.
+- **RAG / vector stores:** similarity can't express `WHERE status = 'active'`. Here vectors are one signal inside `search`: same SQLite file, filters compose, every row labels its evidence (`via`), and a preset turns vectors off per layer of the tree. No second store, no daemon, no native builds.
+- **Document-OS apps (Anytype, Logseq, SilverBullet, Capacities):** full applications with their own UI and storage. `sense` is headless: your files stay files, there's no app to run.
+
+Dependencies: [yaml](https://github.com/eemeli/yaml), [remove-markdown](https://github.com/zuchka/remove-markdown), [fast-glob](https://github.com/mrmlnc/fast-glob), [@huggingface/tokenizers](https://github.com/huggingface/tokenizers.js) (pure JS), and Node's built-in SQLite. No native builds.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sensemaking",
-  "version": "0.9.4",
-  "description": "Query and search a tree of markdown notes: SQL over frontmatter and links, ranked search over the prose — words, links, and meaning fused",
+  "version": "0.9.5",
+  "description": "Query and search your markdown notes with context-aware progressive disclosure: SQL over frontmatter, links, and text, plus semantic search and link-graph ranking. No server, no build step",
   "keywords": [
     "markdown",
     "frontmatter",
@@ -11,10 +11,19 @@
     "query",
     "search",
     "semantic-search",
+    "hybrid-search",
     "knowledge-base",
     "rag",
-    "obsidian",
+    "markdown-database",
+    "document-os",
     "notes",
+    "obsidian",
+    "markdowndb",
+    "iwe",
+    "silverbullet",
+    "logseq",
+    "anytype",
+    "zk",
     "agent",
     "agent-memory",
     "memory-consolidation",

package/skills/sense/EXAMPLES.md

@@ -1,7 +1,6 @@
 # sense: worked examples
 
-Outputs below are illustrative. Every result is a reference; reading happens afterward, through
-the filesystem, on the paths that earned it.
+Outputs below are illustrative. Every result is a reference; reading happens afterward, through the filesystem, on the paths that earned it.
 
 ## A. "Do the notes say anything about X?"
 
@@ -18,9 +17,7 @@ sense search "pricing OR billing OR invoicing" --k 10 --format json
 ]
 ```
 
-Tens of tokens per row; often the `summary` answers the question with no read at all. A row with
-`via: "link"` never contained the terms — it is linked from notes that did. `lines`, when
-set, is the section that earned the row, a direct `Read` range.
+Tens of tokens per row; often the `summary` answers the question with no read at all. A row with `via: "link"` never contained the terms. It is linked from notes that did. `lines`, when set, is the section that earned the row, a direct `Read` range.
 
 ## B. Known-field filtering (no search)
 
@@ -28,11 +25,9 @@ set, is the section that earned the row, a direct `Read` range.
 sense query "SELECT path, title, status FROM frontmatter WHERE status = 'active' AND has(tags, ?)" pricing --format json
 ```
 
-Plain SQL on discovered columns. Combine with search by joining `content` and adding
-`AND content MATCH ?` — filter and rank in one query.
+Plain SQL on discovered columns. Combine with search by joining `content` and adding `AND content MATCH ?`: filter and rank in one query.
 
-Per-member counts on an array field (GROUP BY on the raw column would split `["a","b"]` from
-`["b","a"]`):
+Per-member counts on an array field (GROUP BY on the raw column would split `["a","b"]` from `["b","a"]`):
 
 ```
 sense query "SELECT j.value AS tag, COUNT(*) n FROM frontmatter, json_each(frontmatter.tags) j GROUP BY j.value ORDER BY n DESC"
@@ -55,8 +50,7 @@ links out (7): notes/pricing-model.md, ...
 backlinks (2): notes/_index.md, notes/roadmap.md
 ```
 
-The note is ~4,400 tokens; the peek is ~500. If only one section matters, `Read` its line range
-(~400 tokens) — a tenth of the file.
+The note is ~4,400 tokens; the peek is ~500. If only one section matters, `Read` its line range (~400 tokens), a tenth of the file.
 
 ## D. The graph
 
@@ -89,10 +83,7 @@ sense search "children dying from poor nutrition" --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. 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.
+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. 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
 

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.