sensemaking 0.27.1 → 0.28.1

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

@@ -1,66 +0,0 @@
-# SQLite query guide
-
-Read this guide when `store` is `sqlite` or omitted.
-
-SQLite is the default store. It uses Node's built-in SQLite, keeps the cache at `.sense/cache.db`, supports concurrent sense commands through WAL, and implements the full search grammar documented here.
-
-## `sense search` grammar
-
-Search text uses FTS5 syntax:
-
-- Bare words are joined with AND. If one word is absent, the lexical signal returns no row.
-- `a OR b` matches either word.
-- `pref*` matches a token prefix.
-- `"exact phrase"` requires adjacent tokens.
-- `NEAR(a b, 5)` limits token distance.
-- `^term` requires the token at the start of a column.
-- `title:term` and `summary:term` filter by indexed column.
-- Parentheses group expressions.
-
-Double-quote terms containing punctuation. Bare `customer-facing` treats the hyphen as syntax, and a bare apostrophe is invalid.
-
-## Raw text search
-
-`content` is an FTS5 virtual table. Refer to it by its table name in `MATCH`, even when the `FROM` clause has an alias:
-
-```sql
-SELECT content.path, content.title
-FROM content
-WHERE content MATCH ?
-ORDER BY bm25(content, 10.0, 5.0, 1.0)
-LIMIT 20;
-```
-
-The three BM25 weights rank title above summary above body. For queries that can match the machine-written unspaced-script sidecars, use all eight weights so the sidecars receive the same field weighting:
-
-```sql
-ORDER BY bm25(content, 10.0, 5.0, 1.0, 0, 10.0, 5.0, 1.0)
-```
-
-Raw `snippet(content, 2, '«', '»', '…', 10)` targets the authored body column. Avoid `-1` because it may choose a machine-written sidecar. SQLite's `snippet()` tokenizes the matched text again, so prefer `sense search` for large notes. Sense builds its own bounded passages on every store.
-
-## Functions and unspaced scripts
-
-`has()`, `basename()`, and `segment()` are registered SQL functions. `sense search` handles Chinese, Japanese, Thai, Khmer, Lao, and Burmese automatically. Hand-written `MATCH` cannot be rewritten, so pass such terms through `segment()`:
-
-```sql
-SELECT path FROM content WHERE content MATCH segment(?);
-```
-
-`segment()` leaves other text unchanged.
-
-## Dates and values
-
-Use SQLite's `datetime()` to compare ISO 8601 values with different offsets:
-
-```sql
-WHERE datetime(created) >= datetime(?)
-```
-
-SQLite's `now` is UTC. A calendar-day query in the machine's local timezone needs `localtime`:
-
-```sql
-WHERE date(created) = date('now', 'localtime')
-```
-
-Frontmatter values use SQLite storage classes. Booleans are integers, so compare true with 1. Lists and maps are JSON text and can be expanded with `json_each()`.

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

@@ -1,36 +0,0 @@
-# Turso query guide
-
-Read this guide when `store` is `turso`.
-
-Sense stores the cache at `.sense/cache.turso.db` and uses `@tursodatabase/database` with Tantivy full-text indexes. Use this experimental adapter when the tree benefits from the embedded Turso engine or its text-index behavior.
-
-The first open installs the native package if needed. Turso holds the cache file for the connection's lifetime, so another Sense command waits for the current command or watcher cycle to close it. The upstream engine supports more deployment and concurrency options than this adapter currently exposes. Sense opens a local file and does not configure sync, remote access, concurrent writers, or encryption.
-
-## `sense search` grammar
-
-Bare words and quoted phrases work. Sense applies shared stemming and joins bare words with AND. It verifies phrases against authored text and uses n-gram sidecars for unspaced scripts.
-
-The portable search command does not accept FTS5 prefix, boolean, `NEAR`, initial-token or boost, column-filter, or grouping operators. Examples include `foo*`, `a OR b`, `NEAR(a b)`, `^term`, `title:term`, and `(a b)`. Sense raises `STORE_CAPABILITY_MISSING` instead of passing those forms to Tantivy.
-
-To express alternatives, run separate bounded searches and combine the paths, or use a frontmatter filter when the distinction is structured.
-
-## Raw text search
-
-`content` is a regular table with store-owned stem and n-gram columns. SQLite's `content MATCH`, `snippet()`, and `bm25()` do not run here. Use `sense search` for ranked text retrieval.
-
-Turso exposes native `fts_match()` and `fts_score()`, but their valid scoring forms depend on the exact index projection. Sense owns those calls so that scores do not silently flatten. Saved queries should not call the store-owned text indexes.
-
-## Functions and types
-
-`has()` and `basename()` work in raw SQL. Sense rewrites them into portable SQL because the client cannot register user-defined functions. Nested calls and placeholders are supported.
-
-`segment()` is unavailable. A query that calls it raises `STORE_CAPABILITY_MISSING`. `sense search` still handles unspaced scripts without it.
-
-Turso follows SQLite syntax for common date and JSON operations. Use `datetime()` for ISO 8601 comparisons and add `localtime` when a calendar-day query means the machine's local day:
-
-```sql
-WHERE datetime(created) >= datetime(?)
-WHERE date(created) = date('now', 'localtime')
-```
-
-Frontmatter lists and maps are stored as JSON text and can be expanded with `json_each()`.

package/skills/sense/references/terminology.md

@@ -1,32 +0,0 @@
-# Sense terminology
-
-This is the shared vocabulary for Sense's README, command help, API documentation and skills. Use these names when describing results and output controls.
-
-| Term | Meaning |
-|---|---|
-| Note | One Markdown file. A document is the same unit; SQL and some status fields use that name. |
-| Tree | The directory of notes configured as Sense's root. |
-| Frontmatter | The YAML metadata at the beginning of a note, such as its title, tags or status. |
-| Search result | One matching note, returned with its path, ranking information and any snippets. A result is not a section or a chunk. |
-| Snippet | A short passage selected around matching words, marked with `«»`. A note can return multiple snippets. A snippet need not contain a whole section. |
-| Heading | A Markdown heading such as `## Installation`. Its level is its depth, from 1 to 6. |
-| Section | A heading and the content following it until the next heading of any level, or the end of the note. Text before the first heading is not a section in the `sections` table. A parent section does not include subsequent subsections. |
-| Section description | The heading text, level, start and end lines, and estimated token count returned by `peek`. It does not contain the section's prose. |
-| Outline | The section descriptions in document order. It is a view of the note's structure, not another stored type of content. |
-| Chunk | A span of note content prepared for embedding. Chunking follows document structure and a token budget; a chunk is not necessarily one section or one snippet. |
-| Line range | Inclusive, one-based lines in the indexed source note, such as `L12-28`. Search can point to a section or an embedding chunk. A null range provides no narrower location. |
-| Outbound link | A link from the current note to another indexed note. `peek.outbound` returns distinct destination paths. |
-| Backlink | A link from another indexed note to the current note. `peek.backlinks` returns distinct source paths. |
-| Unresolved link | A written link target that did not resolve to an indexed note. This does not establish that the link is broken: attachments and notes outside the index can also be unresolved. `peek.unresolved` returns written targets. |
-| Scope | The indexed notes selected for an operation by its preset and filters. Scope is not an access-control boundary. |
-| Search signal | One source of ranking evidence: word matches, link relationships or vector similarity. A signal's rank is a candidate's position within that signal, not the final combined position. |
-
-## Reading a section description
-
-The illustrative entry `## Installation [L12-28, ~90t]` describes a section headed “Installation”, starting at line 12 and ending at line 28, with an estimated 90 tokens. `peek` returns that description. Reading the indicated lines retrieves the content. With nested headings, the description ends before the next heading, even when that heading is deeper.
-
-## Naming output controls
-
-Name the object and the unit: a snippet count is how many passages are returned; a snippet character limit controls passage length; a section count is how many section descriptions are returned; a link count controls link entries. A count limit is not pagination. An offset, when supported by an operation, skips entries before returning the requested count. Raw SQL supports `LIMIT` and `OFFSET`; search and peek do not currently expose offset options.
-
-Peek count limits request prefixes of the ordered section and link lists. Each search or peek reads one committed index snapshot; separately issued operations can observe later commits. See [finite retrieval and paging](search.md#finite-retrieval-and-paging) for search budgets and paging retained results.

package/skills/sense-bases/EXAMPLES.md

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

package/skills/sense-bases/SKILL.md

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

package/skills/sense-setup/EXAMPLES.md

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

package/skills/sense-setup/SKILL.md

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