sensemaking 0.26.0 → 0.27.0

package/README.md

@@ -36,15 +36,45 @@ pricing-decision.md  …«pricing» decision … renewal «price»…    match
 
 The row is illustrative. Actual paths, snippets and scores depend on the notes and configured search signals.
 
+## Library usage
+
+Install the package locally in your Node.js project for imports; the global CLI installation above does not provide a project dependency:
+
+```bash
+npm install sensemaking
+```
+
+Start with an existing `your-notes/sense.config.json` pointing at your Markdown tree, created with `sense init` or written as shown under [Config](#config). `build` prepares every configured capability. Your embedding configuration governs model downloads and provider requests, including any service costs; see [Providers](#providers).
+
+Save this as `search-notes.mjs` in your project and run `node search-notes.mjs`. Adjust the config path and search terms for your notes:
+
+```js
+import { loadConfig, build, open, search } from 'sensemaking';
+
+const config = loadConfig('./your-notes/sense.config.json');
+await build(config);
+const { store, cfg } = await open(config, { build: false });
+try {
+  const results = await search(store, cfg, 'pricing', { k: 5 });
+  console.log(JSON.stringify(results, null, 2));
+} finally {
+  await store.close();
+}
+```
+
+The handle uses the completed index prepared by `build`; the example awaits the search before closing it.
+
 ## What sense indexes
 
+The [Sense terminology reference](skills/sense/references/terminology.md) defines notes, snippets, sections, chunks and links. A section is a span of the note; `peek` returns its description, not its prose. The ordered section descriptions form the outline.
+
 Every file becomes rows in these tables, plus whatever an enabled feature adds of its own:
 
 | table | holds | for |
 |---|---|---|
 | `frontmatter` | one column per key, plus `path`, `_mtime`, `_size`, `_rank`, `_parse_error` | filtering |
 | `content` | `title`, `summary`, `text`, `path` | text search and ranking |
-| `links` | `src`, `target` as written, `dst` resolved (`NULL` = dead link, but see the skill: a link to an attachment can never resolve) | graph |
+| `links` | `src`, `target` as written, `dst` resolved (`NULL` = unresolved link, including attachments and targets outside the index) | graph |
 | `tags` | `path`, `tag`; frontmatter and inline `#tags` merged and deduplicated, nested tags stored full | tag filters |
 | `sections` | heading, `level`, `start_line`, `end_line`, `tokens` estimate | structure |
 | `preset_files` | `path`, `preset` | which presets cover which files; `sql --preset` binds these as a `scope` table to join, since `sql` is otherwise index-wide |
@@ -67,8 +97,8 @@ ORDER BY bm25(content, 10.0, 5.0, 1.0) LIMIT 10
 |---|---|
 | `build [--force]` | incrementally update the derived index and prepare every configured search capability; `--force` recreates only `.sense/` |
 | `map [--preset name] [--include glob] [--exclude glob] [--no-exclude] [--where "<sql>"]` | doc count, frontmatter field coverage, top hubs by link rank, recent changes; hub/recent limits use bytewise path order on ties |
-| `search "<text>" [--preset name] [--include glob] [--exclude glob] [--no-exclude] [--where "<sql>"] [--k n] [--snippet-char-limit n] [--snippet-count-limit n]` | words + links + vectors, one fused ranked list; `via` labels each row's evidence. `--k` bounds notes returned, `--snippet-char-limit` (default 80) each passage, `--snippet-count-limit` (default 1) passages per note |
-| `peek <path> [--preset name] [--include glob] [--exclude glob] [--no-exclude] [--where "<sql>"]` | frontmatter + heading outline (`[L143-162, ~380t]`) + links both ways (first 20 per list, each with its total) |
+| `search "<text>" [--preset name] [--include glob] [--exclude glob] [--no-exclude] [--where "<sql>"] [--k n] [--snippet-char-limit n] [--snippet-count-limit n] [--explain]` | words + links + vectors, one fused ranked list; `via` labels each row's evidence. `--k` bounds notes returned, `--snippet-char-limit` (default 80) each passage, `--snippet-count-limit` (default 1) passages per note. `--explain` adds each participating signal's ranking contribution |
+| `peek <path> [--preset name] [--include glob] [--exclude glob] [--no-exclude] [--where "<sql>"] [--section-count-limit n] [--link-count-limit n]` | frontmatter, section descriptions (`[L143-162, ~380t]`), outbound links, backlinks and unresolved links; `--section-count-limit` bounds section descriptions, and `--link-count-limit` bounds each link group independently (both default 20), with totals before truncation |
 | `path <a> <b> [--max-depth n] [--preset name] [--include glob] [--exclude glob] [--no-exclude] [--where "<sql>"]` | shortest link chain between two notes, or none within the bound |
 | `related <note> [--k n] [--preset name] [--include glob] [--exclude glob] [--no-exclude] [--where "<sql>"]` | notes similar in meaning that `<note>` does not yet link to; reads vectors, so semantic-search cost |
 | `sql "<statement>" [params...] [--preset name]` | ad-hoc SQL over all the tables; `?` binds positional args. Index-wide by default; `--preset` binds the preset's paths as a `scope` table the statement joins |
@@ -88,10 +118,12 @@ Explicit `sense build` and `sense watch` prepare the index regardless of the con
 
 The root `search(store, config, terms, { signal })`, `open(config, { signal })`, and `build(config, { signal })` APIs accept an `AbortSignal`. Cancellation stops supported provider I/O and is checked between phases; synchronous native SQL or CPU work and resource cleanup finish before the promise settles. Cancellation checks preserve `signal.reason`, but a cleanup failure can surface instead or be combined with it in an `AggregateError`.
 
-`search` runs one text through every engine its scope has: FTS5 word match (BM25-ranked, bare words AND-join, operators are yours on `sqlite`; on `duckdb` and `turso` the FTS5 operators are a named error, see Config), 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). Within the vector signal, candidates rank by the true cosine against the best-matching canonical chunk before `similarity` is rounded to three decimals for display; a zero-direction vector has similarity `0`, exact cosine ties use bytewise path order, and equal-scoring chunks choose the earliest authored chunk. The public search list ranks the combined word, link, and vector candidates by fused reciprocal-rank score. `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, `--where` filters on frontmatter. `--format json` on any reporting command returns structured output, and `--format csv` writes the row-returning commands one row per line, for redirecting a large result to a file instead of into context; `--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 on `sqlite`; on `duckdb` and `turso` the FTS5 operators are a named error, see Config), 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). Within the vector signal, candidates rank by the true cosine against the best-matching canonical chunk before `similarity` is rounded to three decimals for display; a zero-direction vector has similarity `0`, exact cosine ties use bytewise path order, and equal-scoring chunks choose the earliest authored chunk. The public search list ranks the combined word, link, and vector candidates by fused reciprocal-rank score. `lines` identifies a section or embedding chunk's line range in the indexed note. A `vector`-only row has vector evidence rather than a word match; it is not proof that the query words are absent. `--preset` picks a named settings bundle from the config, `--where` filters on frontmatter. `--format json` on any reporting command returns structured output, and `--format csv` writes the row-returning commands one row per line, for redirecting a large result to a file instead of into context; `--version` and `--help` do what they say.
 
 Search rows carry `snippets: string[]`. Each passage is generated around the matched words, marked with `«»`, and normally limited to 80 characters by default. A whole matched word is preserved, so a passage can exceed that limit when the word is longer. `--snippet-count-limit` returns more non-overlapping passages from a note, in document order. Link- and vector-only rows have `snippets: []`.
 
+Use `search --explain --format json` to inspect the returned notes' word, link and vector contributions without changing their ranking. Each `explanation` entry contains the signal, its one-based rank, configured weight and unrounded contribution. This explains the returned candidates, not why an absent note was excluded. Library callers use `search(store, cfg, terms, { explain: true })`. For longer or shorter note outlines and link lists, use `peek(store, cfg, path, { sectionCountLimit: 40, linkCountLimit: 10 })` or the CLI's `--section-count-limit` and `--link-count-limit`. Each limit defaults to 20, must be a positive safe integer and does not change scope.
+
 Lexical words are case- and accent-insensitive. SQLite and DuckDB use their native English stem tokenizers; Turso's native Tantivy index has no stem tokenizer in the supported release, so it applies the shared Porter normalization to a derived field before native indexing. In every store, `run`, `running`, and `runs` match the same authored notes, while authored bytes are never rewritten. Quoted phrases require adjacent words, with punctuation treated as a separator, and punctuation-only input returns no lexical rows. SQLite's native caret and `NEAR(...)` expressions over unspaced text use original FTS5 tokens rather than sidecar substring semantics; use an ordinary quoted search when substring findability matters, at the cost of positional filtering.
 
 ## Config

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

@@ -6,9 +6,9 @@ export declare const USAGE: {
     readonly status: "status [--format table|json] [--config path]";
     readonly download: "download [--config path]";
     readonly sql: "sql \"<statement>\" [params...] [--preset name] [--no-build] [--format table|json|csv] [--config path]";
-    readonly search: "search \"<terms>\" [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--k n] [--snippet-char-limit n] [--snippet-count-limit n] [--no-build] [--format table|json|csv] [--config path]";
+    readonly search: "search \"<terms>\" [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--k n] [--snippet-char-limit n] [--snippet-count-limit n] [--explain] [--no-build] [--format table|json|csv] [--config path]";
     readonly map: "map [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--no-build] [--format table|json] [--config path]";
-    readonly peek: "peek <path> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--no-build] [--format table|json] [--config path]";
+    readonly peek: "peek <path> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--section-count-limit n] [--link-count-limit n] [--no-build] [--format table|json] [--config path]";
     readonly path: "path <a> <b> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--max-depth n] [--no-build] [--format table|json] [--config path]";
     readonly related: "related <note> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--k n] [--no-build] [--format table|json|csv] [--config path]";
 };

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

@@ -6,9 +6,9 @@ export declare const USAGE: {
     readonly status: "status [--format table|json] [--config path]";
     readonly download: "download [--config path]";
     readonly sql: "sql \"<statement>\" [params...] [--preset name] [--no-build] [--format table|json|csv] [--config path]";
-    readonly search: "search \"<terms>\" [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--k n] [--snippet-char-limit n] [--snippet-count-limit n] [--no-build] [--format table|json|csv] [--config path]";
+    readonly search: "search \"<terms>\" [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--k n] [--snippet-char-limit n] [--snippet-count-limit n] [--explain] [--no-build] [--format table|json|csv] [--config path]";
     readonly map: "map [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--no-build] [--format table|json] [--config path]";
-    readonly peek: "peek <path> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--no-build] [--format table|json] [--config path]";
+    readonly peek: "peek <path> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--section-count-limit n] [--link-count-limit n] [--no-build] [--format table|json] [--config path]";
     readonly path: "path <a> <b> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--max-depth n] [--no-build] [--format table|json] [--config path]";
     readonly related: "related <note> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--k n] [--no-build] [--format table|json|csv] [--config path]";
 };

package/dist/cjs/cli/index.js

@@ -53,9 +53,9 @@ var USAGE = {
     status: 'status [--format table|json] [--config path]',
     download: 'download [--config path]',
     sql: 'sql "<statement>" [params...] [--preset name] [--no-build] [--format table|json|csv] [--config path]',
-    search: 'search "<terms>" [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where "<sql>"] [--k n] [--snippet-char-limit n] [--snippet-count-limit n] [--no-build] [--format table|json|csv] [--config path]',
+    search: 'search "<terms>" [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where "<sql>"] [--k n] [--snippet-char-limit n] [--snippet-count-limit n] [--explain] [--no-build] [--format table|json|csv] [--config path]',
     map: 'map [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where "<sql>"] [--no-build] [--format table|json] [--config path]',
-    peek: 'peek <path> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where "<sql>"] [--no-build] [--format table|json] [--config path]',
+    peek: 'peek <path> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where "<sql>"] [--section-count-limit n] [--link-count-limit n] [--no-build] [--format table|json] [--config path]',
     path: 'path <a> <b> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where "<sql>"] [--max-depth n] [--no-build] [--format table|json] [--config path]',
     related: 'related <note> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where "<sql>"] [--k n] [--no-build] [--format table|json|csv] [--config path]'
 };

package/dist/cjs/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/index.ts"],"sourcesContent":["import type { Command } from './types.ts';\n\n// Each command's usage line, minus the leading \"usage: <name> \": shared by cli.ts's\n// usage() and the command's own parse() error/--help output so there is one copy, not two.\nexport const USAGE = {\n  init: 'init [--model id-or-path] [--provider static|openai|cohere] [--url url]',\n  build: 'build [--force] [--config path]',\n  watch: 'watch [--force] [--config path]',\n  status: 'status [--format table|json] [--config path]',\n  download: 'download [--config path]',\n  sql: 'sql \"<statement>\" [params...] [--preset name] [--no-build] [--format table|json|csv] [--config path]',\n  search: 'search \"<terms>\" [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--k n] [--snippet-char-limit n] [--snippet-count-limit n] [--no-build] [--format table|json|csv] [--config path]',\n  map: 'map [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--no-build] [--format table|json] [--config path]',\n  peek: 'peek <path> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--no-build] [--format table|json] [--config path]',\n  path: 'path <a> <b> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--max-depth n] [--no-build] [--format table|json] [--config path]',\n  related: 'related <note> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--k n] [--no-build] [--format table|json|csv] [--config path]',\n} as const;\n\n// Lazy registry: a command's imports load only when it runs, so a heavy dependency in one\n// command never taxes the others (or --version/--help). These names are reserved from saved queries.\nexport const COMMANDS: Record<string, () => Promise<{ default: Command }>> = {\n  init: () => import('./init.ts'),\n  build: () => import('./build.ts'),\n  watch: () => import('./watch.ts'),\n  status: () => import('./status.ts'),\n  download: () => import('./download.ts'),\n  sql: () => import('./sql.ts'),\n  search: () => import('./search.ts'),\n  map: () => import('./map.ts'),\n  peek: () => import('./peek.ts'),\n  path: () => import('./path.ts'),\n  related: () => import('./related.ts'),\n};\n\nexport type { Command, Ctx } from './types.ts';\n"],"names":["COMMANDS","USAGE","init","build","watch","status","download","sql","search","map","peek","path","related"],"mappings":";;;;;;;;;;;QAoBaA;eAAAA;;QAhBAC;eAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAN,IAAMA,QAAQ;IACnBC,MAAM;IACNC,OAAO;IACPC,OAAO;IACPC,QAAQ;IACRC,UAAU;IACVC,KAAK;IACLC,QAAQ;IACRC,KAAK;IACLC,MAAM;IACNC,MAAM;IACNC,SAAS;AACX;AAIO,IAAMZ,WAAgE;IAC3EE,MAAM,SAANA;eAAY;2DAAA,QAAO;;;IACnBC,OAAO,SAAPA;eAAa;2DAAA,QAAO;;;IACpBC,OAAO,SAAPA;eAAa;2DAAA,QAAO;;;IACpBC,QAAQ,SAARA;eAAc;2DAAA,QAAO;;;IACrBC,UAAU,SAAVA;eAAgB;2DAAA,QAAO;;;IACvBC,KAAK,SAALA;eAAW;2DAAA,QAAO;;;IAClBC,QAAQ,SAARA;eAAc;2DAAA,QAAO;;;IACrBC,KAAK,SAALA;eAAW;2DAAA,QAAO;;;IAClBC,MAAM,SAANA;eAAY;2DAAA,QAAO;;;IACnBC,MAAM,SAANA;eAAY;2DAAA,QAAO;;;IACnBC,SAAS,SAATA;eAAe;2DAAA,QAAO;;;AACxB"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/index.ts"],"sourcesContent":["import type { Command } from './types.ts';\n\n// Each command's usage line, minus the leading \"usage: <name> \": shared by cli.ts's\n// usage() and the command's own parse() error/--help output so there is one copy, not two.\nexport const USAGE = {\n  init: 'init [--model id-or-path] [--provider static|openai|cohere] [--url url]',\n  build: 'build [--force] [--config path]',\n  watch: 'watch [--force] [--config path]',\n  status: 'status [--format table|json] [--config path]',\n  download: 'download [--config path]',\n  sql: 'sql \"<statement>\" [params...] [--preset name] [--no-build] [--format table|json|csv] [--config path]',\n  search: 'search \"<terms>\" [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--k n] [--snippet-char-limit n] [--snippet-count-limit n] [--explain] [--no-build] [--format table|json|csv] [--config path]',\n  map: 'map [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--no-build] [--format table|json] [--config path]',\n  peek: 'peek <path> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--section-count-limit n] [--link-count-limit n] [--no-build] [--format table|json] [--config path]',\n  path: 'path <a> <b> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--max-depth n] [--no-build] [--format table|json] [--config path]',\n  related: 'related <note> [--preset name] [--include glob ...] [--exclude glob ...] [--no-exclude] [--where \"<sql>\"] [--k n] [--no-build] [--format table|json|csv] [--config path]',\n} as const;\n\n// Lazy registry: a command's imports load only when it runs, so a heavy dependency in one\n// command never taxes the others (or --version/--help). These names are reserved from saved queries.\nexport const COMMANDS: Record<string, () => Promise<{ default: Command }>> = {\n  init: () => import('./init.ts'),\n  build: () => import('./build.ts'),\n  watch: () => import('./watch.ts'),\n  status: () => import('./status.ts'),\n  download: () => import('./download.ts'),\n  sql: () => import('./sql.ts'),\n  search: () => import('./search.ts'),\n  map: () => import('./map.ts'),\n  peek: () => import('./peek.ts'),\n  path: () => import('./path.ts'),\n  related: () => import('./related.ts'),\n};\n\nexport type { Command, Ctx } from './types.ts';\n"],"names":["COMMANDS","USAGE","init","build","watch","status","download","sql","search","map","peek","path","related"],"mappings":";;;;;;;;;;;QAoBaA;eAAAA;;QAhBAC;eAAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAN,IAAMA,QAAQ;IACnBC,MAAM;IACNC,OAAO;IACPC,OAAO;IACPC,QAAQ;IACRC,UAAU;IACVC,KAAK;IACLC,QAAQ;IACRC,KAAK;IACLC,MAAM;IACNC,MAAM;IACNC,SAAS;AACX;AAIO,IAAMZ,WAAgE;IAC3EE,MAAM,SAANA;eAAY;2DAAA,QAAO;;;IACnBC,OAAO,SAAPA;eAAa;2DAAA,QAAO;;;IACpBC,OAAO,SAAPA;eAAa;2DAAA,QAAO;;;IACpBC,QAAQ,SAARA;eAAc;2DAAA,QAAO;;;IACrBC,UAAU,SAAVA;eAAgB;2DAAA,QAAO;;;IACvBC,KAAK,SAALA;eAAW;2DAAA,QAAO;;;IAClBC,QAAQ,SAARA;eAAc;2DAAA,QAAO;;;IACrBC,KAAK,SAALA;eAAW;2DAAA,QAAO;;;IAClBC,MAAM,SAANA;eAAY;2DAAA,QAAO;;;IACnBC,MAAM,SAANA;eAAY;2DAAA,QAAO;;;IACnBC,SAAS,SAATA;eAAe;2DAAA,QAAO;;;AACxB"}

package/dist/cjs/cli/peek.js

@@ -99,6 +99,29 @@ function _object_spread(target) {
     }
     return target;
 }
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        if (enumerableOnly) {
+            symbols = symbols.filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(object, sym).enumerable;
+            });
+        }
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
 function _sliced_to_array(arr, i) {
     return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array(arr, i) || _non_iterable_rest();
 }
@@ -209,11 +232,26 @@ function _unsupported_iterable_to_array(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array(o, minLen);
 }
+function parseCountLimit(name, value, usageError) {
+    if (value === undefined) return undefined;
+    var parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed <= 0) usageError("--".concat(name, ' expects a positive safe integer, got "').concat(value, '"'));
+    return parsed;
+}
 var peekCmd = function peekCmd(ctx) {
     var usage = "usage: ".concat(ctx.name, " ").concat(_indexts.USAGE.peek);
-    var _parse = (0, _sharedts.parse)(ctx.argv, usage, _object_spread({}, _sharedts.SCOPE, _sharedts.NO_BUILD, _sharedts.FORMAT, _sharedts.CONFIG)), values = _parse.values, positionals = _parse.positionals;
+    var _parse = (0, _sharedts.parse)(ctx.argv, usage, _object_spread_props(_object_spread({}, _sharedts.SCOPE, _sharedts.NO_BUILD, _sharedts.FORMAT, _sharedts.CONFIG), {
+        'section-count-limit': {
+            type: 'string'
+        },
+        'link-count-limit': {
+            type: 'string'
+        }
+    })), values = _parse.values, positionals = _parse.positionals;
     var _positionals = _sliced_to_array(positionals, 1), pathArg = _positionals[0];
     if (!pathArg) ctx.usageError(usage);
+    var sectionCountLimit = parseCountLimit('section-count-limit', values['section-count-limit'], ctx.usageError);
+    var linkCountLimit = parseCountLimit('link-count-limit', values['link-count-limit'], ctx.usageError);
     var format = (0, _sharedts.formatOf)(values);
     return (0, _sharedts.withDb)(ctx, values.config, {
         noBuild: values['no-build'] === true,
@@ -226,7 +264,10 @@ var peekCmd = function peekCmd(ctx) {
             return _ts_generator(this, function(_state) {
                 switch(_state.label){
                     case 0:
-                        overrides = (0, _sharedts.scopeOf)(values);
+                        overrides = _object_spread_props(_object_spread({}, (0, _sharedts.scopeOf)(values)), {
+                            sectionCountLimit: sectionCountLimit,
+                            linkCountLimit: linkCountLimit
+                        });
                         return [
                             4,
                             (0, _peekts.peek)(store, cfg, pathArg, overrides)

package/dist/cjs/cli/peek.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/peek.ts"],"sourcesContent":["import { peek } from '../commands/peek.ts';\nimport { renderPeek, stringifyJson } from '../output/output.ts';\nimport type { BuildRequirement } from '../store/open.ts';\nimport { USAGE } from './index.ts';\nimport { CONFIG, FORMAT, formatOf, NO_BUILD, parse, SCOPE, scopeOf, withDb } from './shared.ts';\nimport type { Command } from './types.ts';\n\nconst peekCmd: Command = (ctx) => {\n  const usage = `usage: ${ctx.name} ${USAGE.peek}`;\n  const { values, positionals } = parse(ctx.argv, usage, { ...SCOPE, ...NO_BUILD, ...FORMAT, ...CONFIG });\n  const [pathArg] = positionals;\n  if (!pathArg) ctx.usageError(usage);\n  const format = formatOf(values);\n  return withDb(ctx, values.config as string | undefined, { noBuild: values['no-build'] === true, requirements: new Set<BuildRequirement>(['core']) }, async (store, cfg) => {\n    const overrides = scopeOf(values);\n    const result = await peek(store, cfg, pathArg, overrides);\n    console.log(format === 'json' ? stringifyJson(result, 2) : renderPeek(result));\n  });\n};\nexport default peekCmd;\n"],"names":["peekCmd","ctx","usage","USAGE","name","peek","parse","argv","SCOPE","NO_BUILD","FORMAT","CONFIG","values","positionals","pathArg","usageError","format","formatOf","withDb","config","noBuild","requirements","Set","store","cfg","overrides","result","scopeOf","console","log","stringifyJson","renderPeek"],"mappings":";;;;+BAmBA;;;eAAA;;;sBAnBqB;wBACqB;uBAEpB;wBAC4D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGlF,IAAMA,UAAmB,iBAACC;IACxB,IAAMC,QAAQ,AAAC,UAAqBC,OAAZF,IAAIG,IAAI,EAAC,KAAc,OAAXD,cAAK,CAACE,IAAI;IAC9C,IAAgCC,SAAAA,IAAAA,eAAK,EAACL,IAAIM,IAAI,EAAEL,OAAO,mBAAKM,eAAK,EAAKC,kBAAQ,EAAKC,gBAAM,EAAKC,gBAAM,IAA5FC,SAAwBN,OAAxBM,QAAQC,cAAgBP,OAAhBO;IAChB,IAAkBA,gCAAAA,iBAAXC,UAAWD;IAClB,IAAI,CAACC,SAASb,IAAIc,UAAU,CAACb;IAC7B,IAAMc,SAASC,IAAAA,kBAAQ,EAACL;IACxB,OAAOM,IAAAA,gBAAM,EAACjB,KAAKW,OAAOO,MAAM,EAAwB;QAAEC,SAASR,MAAM,CAAC,WAAW,KAAK;QAAMS,cAAc,IAAIC,IAAsB;YAAC;SAAO;IAAE,GAAG,SAAOC,OAAOC;;gBAC3JC,WACAC;;;;wBADAD,YAAYE,IAAAA,iBAAO,EAACf;wBACX;;4BAAMP,IAAAA,YAAI,EAACkB,OAAOC,KAAKV,SAASW;;;wBAAzCC,SAAS;wBACfE,QAAQC,GAAG,CAACb,WAAW,SAASc,IAAAA,uBAAa,EAACJ,QAAQ,KAAKK,IAAAA,oBAAU,EAACL;;;;;;QACxE;;AACF;IACA,WAAe1B"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/peek.ts"],"sourcesContent":["import { peek } from '../commands/peek.ts';\nimport { renderPeek, stringifyJson } from '../output/output.ts';\nimport type { BuildRequirement } from '../store/open.ts';\nimport { USAGE } from './index.ts';\nimport { CONFIG, FORMAT, formatOf, NO_BUILD, parse, SCOPE, scopeOf, withDb } from './shared.ts';\nimport type { Command } from './types.ts';\n\nfunction parseCountLimit(name: string, value: string | undefined, usageError: (message: string) => never): number | undefined {\n  if (value === undefined) return undefined;\n  const parsed = Number(value);\n  if (!Number.isSafeInteger(parsed) || parsed <= 0) usageError(`--${name} expects a positive safe integer, got \"${value}\"`);\n  return parsed;\n}\n\nconst peekCmd: Command = (ctx) => {\n  const usage = `usage: ${ctx.name} ${USAGE.peek}`;\n  const { values, positionals } = parse(ctx.argv, usage, { ...SCOPE, ...NO_BUILD, ...FORMAT, ...CONFIG, 'section-count-limit': { type: 'string' }, 'link-count-limit': { type: 'string' } });\n  const [pathArg] = positionals;\n  if (!pathArg) ctx.usageError(usage);\n  const sectionCountLimit = parseCountLimit('section-count-limit', values['section-count-limit'] as string | undefined, ctx.usageError);\n  const linkCountLimit = parseCountLimit('link-count-limit', values['link-count-limit'] as string | undefined, ctx.usageError);\n  const format = formatOf(values);\n  return withDb(ctx, values.config as string | undefined, { noBuild: values['no-build'] === true, requirements: new Set<BuildRequirement>(['core']) }, async (store, cfg) => {\n    const overrides = { ...scopeOf(values), sectionCountLimit, linkCountLimit };\n    const result = await peek(store, cfg, pathArg, overrides);\n    console.log(format === 'json' ? stringifyJson(result, 2) : renderPeek(result));\n  });\n};\nexport default peekCmd;\n"],"names":["parseCountLimit","name","value","usageError","undefined","parsed","Number","isSafeInteger","peekCmd","ctx","usage","USAGE","peek","parse","argv","SCOPE","NO_BUILD","FORMAT","CONFIG","type","values","positionals","pathArg","sectionCountLimit","linkCountLimit","format","formatOf","withDb","config","noBuild","requirements","Set","store","cfg","overrides","result","scopeOf","console","log","stringifyJson","renderPeek"],"mappings":";;;;+BA4BA;;;eAAA;;;sBA5BqB;wBACqB;uBAEpB;wBAC4D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGlF,SAASA,gBAAgBC,IAAY,EAAEC,KAAyB,EAAEC,UAAsC;IACtG,IAAID,UAAUE,WAAW,OAAOA;IAChC,IAAMC,SAASC,OAAOJ;IACtB,IAAI,CAACI,OAAOC,aAAa,CAACF,WAAWA,UAAU,GAAGF,WAAW,AAAC,KAAkDD,OAA9CD,MAAK,2CAA+C,OAANC,OAAM;IACtH,OAAOG;AACT;AAEA,IAAMG,UAAmB,iBAACC;IACxB,IAAMC,QAAQ,AAAC,UAAqBC,OAAZF,IAAIR,IAAI,EAAC,KAAc,OAAXU,cAAK,CAACC,IAAI;IAC9C,IAAgCC,SAAAA,IAAAA,eAAK,EAACJ,IAAIK,IAAI,EAAEJ,OAAO,wCAAKK,eAAK,EAAKC,kBAAQ,EAAKC,gBAAM,EAAKC,gBAAM;QAAE,uBAAuB;YAAEC,MAAM;QAAS;QAAG,oBAAoB;YAAEA,MAAM;QAAS;SAA9KC,SAAwBP,OAAxBO,QAAQC,cAAgBR,OAAhBQ;IAChB,IAAkBA,gCAAAA,iBAAXC,UAAWD;IAClB,IAAI,CAACC,SAASb,IAAIN,UAAU,CAACO;IAC7B,IAAMa,oBAAoBvB,gBAAgB,uBAAuBoB,MAAM,CAAC,sBAAsB,EAAwBX,IAAIN,UAAU;IACpI,IAAMqB,iBAAiBxB,gBAAgB,oBAAoBoB,MAAM,CAAC,mBAAmB,EAAwBX,IAAIN,UAAU;IAC3H,IAAMsB,SAASC,IAAAA,kBAAQ,EAACN;IACxB,OAAOO,IAAAA,gBAAM,EAAClB,KAAKW,OAAOQ,MAAM,EAAwB;QAAEC,SAAST,MAAM,CAAC,WAAW,KAAK;QAAMU,cAAc,IAAIC,IAAsB;YAAC;SAAO;IAAE,GAAG,SAAOC,OAAOC;;gBAC3JC,WACAC;;;;wBADAD,YAAY,wCAAKE,IAAAA,iBAAO,EAAChB;4BAASG,mBAAAA;4BAAmBC,gBAAAA;;wBAC5C;;4BAAMZ,IAAAA,YAAI,EAACoB,OAAOC,KAAKX,SAASY;;;wBAAzCC,SAAS;wBACfE,QAAQC,GAAG,CAACb,WAAW,SAASc,IAAAA,uBAAa,EAACJ,QAAQ,KAAKK,IAAAA,oBAAU,EAACL;;;;;;QACxE;;AACF;IACA,WAAe3B"}

package/dist/cjs/cli/search.js

@@ -102,6 +102,29 @@ function _object_spread(target) {
     }
     return target;
 }
+function ownKeys(object, enumerableOnly) {
+    var keys = Object.keys(object);
+    if (Object.getOwnPropertySymbols) {
+        var symbols = Object.getOwnPropertySymbols(object);
+        if (enumerableOnly) {
+            symbols = symbols.filter(function(sym) {
+                return Object.getOwnPropertyDescriptor(object, sym).enumerable;
+            });
+        }
+        keys.push.apply(keys, symbols);
+    }
+    return keys;
+}
+function _object_spread_props(target, source) {
+    source = source != null ? source : {};
+    if (Object.getOwnPropertyDescriptors) Object.defineProperties(target, Object.getOwnPropertyDescriptors(source));
+    else {
+        ownKeys(Object(source)).forEach(function(key) {
+            Object.defineProperty(target, key, Object.getOwnPropertyDescriptor(source, key));
+        });
+    }
+    return target;
+}
 function _sliced_to_array(arr, i) {
     return _array_with_holes(arr) || _iterable_to_array_limit(arr, i) || _unsupported_iterable_to_array(arr, i) || _non_iterable_rest();
 }
@@ -219,7 +242,11 @@ var searchCmd = function searchCmd(ctx) {
             switch(_state.label){
                 case 0:
                     usage = "usage: ".concat(ctx.name, " ").concat(_indexts1.USAGE.search);
-                    _parse = (0, _sharedts.parse)(ctx.argv, usage, _object_spread({}, _sharedts.SEARCH_FLAGS, _sharedts.NO_BUILD, _sharedts.FORMAT, _sharedts.CONFIG)), values = _parse.values, positionals = _parse.positionals;
+                    _parse = (0, _sharedts.parse)(ctx.argv, usage, _object_spread_props(_object_spread({}, _sharedts.SEARCH_FLAGS, _sharedts.NO_BUILD, _sharedts.FORMAT, _sharedts.CONFIG), {
+                        explain: {
+                            type: 'boolean'
+                        }
+                    })), values = _parse.values, positionals = _parse.positionals;
                     _positionals = _sliced_to_array(positionals, 1), terms = _positionals[0];
                     if (!terms) ctx.usageError(usage);
                     k = (0, _sharedts.parseK)(values.k, ctx.usageError);
@@ -228,6 +255,7 @@ var searchCmd = function searchCmd(ctx) {
                     format = (0, _sharedts.rowFormatOf)(values);
                     overrides = _object_spread({
                         k: k,
+                        explain: values.explain === true,
                         snippetCharLimit: snippetCharLimit,
                         snippetCountLimit: snippetCountLimit
                     }, (0, _sharedts.scopeOf)(values));
@@ -246,7 +274,7 @@ var searchCmd = function searchCmd(ctx) {
                             }
                         }, function(store, cfg, build) {
                             return _async_to_generator(function() {
-                                var _tmp;
+                                var _tmp, rows, rendered;
                                 return _ts_generator(this, function(_state) {
                                     switch(_state.label){
                                         case 0:
@@ -278,10 +306,14 @@ var searchCmd = function searchCmd(ctx) {
                                                 (0, _searchts.search)(store, cfg, terms, overrides)
                                             ];
                                         case 4:
-                                            _outputts.printRows.apply(void 0, [
-                                                _state.sent(),
-                                                format
-                                            ]);
+                                            rows = _state.sent();
+                                            // Table cells use the shared renderer's width clipping; JSON retains the complete explanation.
+                                            rendered = overrides.explain && format !== 'json' ? rows.map(function(row) {
+                                                return _object_spread_props(_object_spread({}, row), {
+                                                    explanation: JSON.stringify(row.explanation)
+                                                });
+                                            }) : rows;
+                                            (0, _outputts.printRows)(rendered, format);
                                             return [
                                                 2
                                             ];

package/dist/cjs/cli/search.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/search.ts"],"sourcesContent":["import { scopedPaths } from '../commands/scope.ts';\nimport { search } from '../commands/search.ts';\nimport { resolveSearch } from '../config/index.ts';\nimport { printRows } from '../output/output.ts';\nimport { type BuildRequirement, prepareDocumentEmbeddings } from '../store/open.ts';\nimport { USAGE } from './index.ts';\nimport { CONFIG, FORMAT, NO_BUILD, parse, parseK, parseSnippetCharLimit, parseSnippetCountLimit, rowFormatOf, SEARCH_FLAGS, scopeOf, withDb } from './shared.ts';\nimport type { Command } from './types.ts';\n\nconst searchCmd: Command = async (ctx) => {\n  const usage = `usage: ${ctx.name} ${USAGE.search}`;\n  const { values, positionals } = parse(ctx.argv, usage, { ...SEARCH_FLAGS, ...NO_BUILD, ...FORMAT, ...CONFIG });\n  const [terms] = positionals;\n  if (!terms) ctx.usageError(usage);\n  const k = parseK(values.k as string | undefined, ctx.usageError);\n  const snippetCharLimit = parseSnippetCharLimit(values['snippet-char-limit'] as string | undefined, ctx.usageError);\n  const snippetCountLimit = parseSnippetCountLimit(values['snippet-count-limit'] as string | undefined, ctx.usageError);\n  const format = rowFormatOf(values);\n  const overrides = { k, snippetCharLimit, snippetCountLimit, ...scopeOf(values) };\n  const noBuild = values['no-build'] === true;\n  await withDb(\n    ctx,\n    values.config as string | undefined,\n    {\n      noBuild,\n      requirements: (cfg) => {\n        const signals = resolveSearch(cfg, overrides).signals;\n        const requirements = new Set<BuildRequirement>(['core']);\n        if (signals.words !== undefined) requirements.add('lexical');\n        return requirements;\n      },\n    },\n    async (store, cfg, build) => {\n      if (build && resolveSearch(cfg, overrides).signals.vectors !== undefined) {\n        await prepareDocumentEmbeddings(store, cfg, await scopedPaths(store, cfg, overrides));\n      }\n      printRows(await search(store, cfg, terms, overrides), format);\n    }\n  );\n};\nexport default searchCmd;\n"],"names":["searchCmd","ctx","usage","parse","values","positionals","terms","k","snippetCharLimit","snippetCountLimit","format","overrides","noBuild","USAGE","name","search","argv","SEARCH_FLAGS","NO_BUILD","FORMAT","CONFIG","usageError","parseK","parseSnippetCharLimit","parseSnippetCountLimit","rowFormatOf","scopeOf","withDb","config","requirements","cfg","signals","resolveSearch","Set","words","undefined","add","store","build","vectors","scopedPaths","prepareDocumentEmbeddings","printRows"],"mappings":";;;;+BAwCA;;;eAAA;;;uBAxC4B;wBACL;uBACO;wBACJ;sBACuC;wBAC3C;wBAC6H;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGnJ,IAAMA,YAAqB,mBAAOC;;YAC1BC,OAC0BC,QAAxBC,QAAQC,aACAA,cAATC,OAEDC,GACAC,kBACAC,mBACAC,QACAC,WACAC;;;;oBATAV,QAAQ,AAAC,UAAqBW,OAAZZ,IAAIa,IAAI,EAAC,KAAgB,OAAbD,eAAK,CAACE,MAAM;oBAChBZ,SAAAA,IAAAA,eAAK,EAACF,IAAIe,IAAI,EAAEd,OAAO,mBAAKe,sBAAY,EAAKC,kBAAQ,EAAKC,gBAAM,EAAKC,gBAAM,IAAnGhB,SAAwBD,OAAxBC,QAAQC,cAAgBF,OAAhBE;oBACAA,gCAAAA,iBAATC,QAASD;oBAChB,IAAI,CAACC,OAAOL,IAAIoB,UAAU,CAACnB;oBACrBK,IAAIe,IAAAA,gBAAM,EAAClB,OAAOG,CAAC,EAAwBN,IAAIoB,UAAU;oBACzDb,mBAAmBe,IAAAA,+BAAqB,EAACnB,MAAM,CAAC,qBAAqB,EAAwBH,IAAIoB,UAAU;oBAC3GZ,oBAAoBe,IAAAA,gCAAsB,EAACpB,MAAM,CAAC,sBAAsB,EAAwBH,IAAIoB,UAAU;oBAC9GX,SAASe,IAAAA,qBAAW,EAACrB;oBACrBO,YAAY;wBAAEJ,GAAAA;wBAAGC,kBAAAA;wBAAkBC,mBAAAA;uBAAsBiB,IAAAA,iBAAO,EAACtB;oBACjEQ,UAAUR,MAAM,CAAC,WAAW,KAAK;oBACvC;;wBAAMuB,IAAAA,gBAAM,EACV1B,KACAG,OAAOwB,MAAM,EACb;4BACEhB,SAAAA;4BACAiB,cAAc,SAAdA,aAAeC;gCACb,IAAMC,UAAUC,IAAAA,sBAAa,EAACF,KAAKnB,WAAWoB,OAAO;gCACrD,IAAMF,eAAe,IAAII,IAAsB;oCAAC;iCAAO;gCACvD,IAAIF,QAAQG,KAAK,KAAKC,WAAWN,aAAaO,GAAG,CAAC;gCAClD,OAAOP;4BACT;wBACF,GACA,SAAOQ,OAAOP,KAAKQ;;;;;;iDACbA,CAAAA,SAASN,IAAAA,sBAAa,EAACF,KAAKnB,WAAWoB,OAAO,CAACQ,OAAO,KAAKJ,SAAQ,GAAnEG;;;;;gDAC8BD;gDAAOP;;4CAAK;;gDAAMU,IAAAA,oBAAW,EAACH,OAAOP,KAAKnB;;;4CAA1E;;gDAAM8B,iCAAyB;oDAAa;;;;4CAA5C;;;4CAEQ;;gDAAM1B,IAAAA,gBAAM,EAACsB,OAAOP,KAAKxB,OAAOK;;;4CAA1C+B,mBAAS;gDAAC;gDAA4ChC;;;;;;;4BACxD;;;;oBAjBF;;;;;;IAmBF;;IACA,WAAeV"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/cli/search.ts"],"sourcesContent":["import { scopedPaths } from '../commands/scope.ts';\nimport { search } from '../commands/search.ts';\nimport { resolveSearch } from '../config/index.ts';\nimport { printRows } from '../output/output.ts';\nimport { type BuildRequirement, prepareDocumentEmbeddings } from '../store/open.ts';\nimport { USAGE } from './index.ts';\nimport { CONFIG, FORMAT, NO_BUILD, parse, parseK, parseSnippetCharLimit, parseSnippetCountLimit, rowFormatOf, SEARCH_FLAGS, scopeOf, withDb } from './shared.ts';\nimport type { Command } from './types.ts';\n\nconst searchCmd: Command = async (ctx) => {\n  const usage = `usage: ${ctx.name} ${USAGE.search}`;\n  const { values, positionals } = parse(ctx.argv, usage, { ...SEARCH_FLAGS, ...NO_BUILD, ...FORMAT, ...CONFIG, explain: { type: 'boolean' } });\n  const [terms] = positionals;\n  if (!terms) ctx.usageError(usage);\n  const k = parseK(values.k as string | undefined, ctx.usageError);\n  const snippetCharLimit = parseSnippetCharLimit(values['snippet-char-limit'] as string | undefined, ctx.usageError);\n  const snippetCountLimit = parseSnippetCountLimit(values['snippet-count-limit'] as string | undefined, ctx.usageError);\n  const format = rowFormatOf(values);\n  const overrides = { k, explain: values.explain === true, snippetCharLimit, snippetCountLimit, ...scopeOf(values) };\n  const noBuild = values['no-build'] === true;\n  await withDb(\n    ctx,\n    values.config as string | undefined,\n    {\n      noBuild,\n      requirements: (cfg) => {\n        const signals = resolveSearch(cfg, overrides).signals;\n        const requirements = new Set<BuildRequirement>(['core']);\n        if (signals.words !== undefined) requirements.add('lexical');\n        return requirements;\n      },\n    },\n    async (store, cfg, build) => {\n      if (build && resolveSearch(cfg, overrides).signals.vectors !== undefined) {\n        await prepareDocumentEmbeddings(store, cfg, await scopedPaths(store, cfg, overrides));\n      }\n      const rows = await search(store, cfg, terms, overrides);\n      // Table cells use the shared renderer's width clipping; JSON retains the complete explanation.\n      const rendered = overrides.explain && format !== 'json' ? rows.map((row) => ({ ...row, explanation: JSON.stringify(row.explanation) })) : rows;\n      printRows(rendered, format);\n    }\n  );\n};\nexport default searchCmd;\n"],"names":["searchCmd","ctx","usage","parse","values","positionals","terms","k","snippetCharLimit","snippetCountLimit","format","overrides","noBuild","USAGE","name","search","argv","SEARCH_FLAGS","NO_BUILD","FORMAT","CONFIG","explain","type","usageError","parseK","parseSnippetCharLimit","parseSnippetCountLimit","rowFormatOf","scopeOf","withDb","config","requirements","cfg","signals","resolveSearch","Set","words","undefined","add","store","build","rows","rendered","vectors","scopedPaths","prepareDocumentEmbeddings","map","row","explanation","JSON","stringify","printRows"],"mappings":";;;;+BA2CA;;;eAAA;;;uBA3C4B;wBACL;uBACO;wBACJ;sBACuC;wBAC3C;wBAC6H;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAGnJ,IAAMA,YAAqB,mBAAOC;;YAC1BC,OAC0BC,QAAxBC,QAAQC,aACAA,cAATC,OAEDC,GACAC,kBACAC,mBACAC,QACAC,WACAC;;;;oBATAV,QAAQ,AAAC,UAAqBW,OAAZZ,IAAIa,IAAI,EAAC,KAAgB,OAAbD,eAAK,CAACE,MAAM;oBAChBZ,SAAAA,IAAAA,eAAK,EAACF,IAAIe,IAAI,EAAEd,OAAO,wCAAKe,sBAAY,EAAKC,kBAAQ,EAAKC,gBAAM,EAAKC,gBAAM;wBAAEC,SAAS;4BAAEC,MAAM;wBAAU;yBAAhIlB,SAAwBD,OAAxBC,QAAQC,cAAgBF,OAAhBE;oBACAA,gCAAAA,iBAATC,QAASD;oBAChB,IAAI,CAACC,OAAOL,IAAIsB,UAAU,CAACrB;oBACrBK,IAAIiB,IAAAA,gBAAM,EAACpB,OAAOG,CAAC,EAAwBN,IAAIsB,UAAU;oBACzDf,mBAAmBiB,IAAAA,+BAAqB,EAACrB,MAAM,CAAC,qBAAqB,EAAwBH,IAAIsB,UAAU;oBAC3Gd,oBAAoBiB,IAAAA,gCAAsB,EAACtB,MAAM,CAAC,sBAAsB,EAAwBH,IAAIsB,UAAU;oBAC9Gb,SAASiB,IAAAA,qBAAW,EAACvB;oBACrBO,YAAY;wBAAEJ,GAAAA;wBAAGc,SAASjB,OAAOiB,OAAO,KAAK;wBAAMb,kBAAAA;wBAAkBC,mBAAAA;uBAAsBmB,IAAAA,iBAAO,EAACxB;oBACnGQ,UAAUR,MAAM,CAAC,WAAW,KAAK;oBACvC;;wBAAMyB,IAAAA,gBAAM,EACV5B,KACAG,OAAO0B,MAAM,EACb;4BACElB,SAAAA;4BACAmB,cAAc,SAAdA,aAAeC;gCACb,IAAMC,UAAUC,IAAAA,sBAAa,EAACF,KAAKrB,WAAWsB,OAAO;gCACrD,IAAMF,eAAe,IAAII,IAAsB;oCAAC;iCAAO;gCACvD,IAAIF,QAAQG,KAAK,KAAKC,WAAWN,aAAaO,GAAG,CAAC;gCAClD,OAAOP;4BACT;wBACF,GACA,SAAOQ,OAAOP,KAAKQ;;0CAIXC,MAEAC;;;;iDALFF,CAAAA,SAASN,IAAAA,sBAAa,EAACF,KAAKrB,WAAWsB,OAAO,CAACU,OAAO,KAAKN,SAAQ,GAAnEG;;;;;gDAC8BD;gDAAOP;;4CAAK;;gDAAMY,IAAAA,oBAAW,EAACL,OAAOP,KAAKrB;;;4CAA1E;;gDAAMkC,iCAAyB;oDAAa;;;;4CAA5C;;;4CAEW;;gDAAM9B,IAAAA,gBAAM,EAACwB,OAAOP,KAAK1B,OAAOK;;;4CAAvC8B,OAAO;4CACb,+FAA+F;4CACzFC,WAAW/B,UAAUU,OAAO,IAAIX,WAAW,SAAS+B,KAAKK,GAAG,CAAC,SAACC;uDAAS,wCAAKA;oDAAKC,aAAaC,KAAKC,SAAS,CAACH,IAAIC,WAAW;;iDAAQP;4CAC1IU,IAAAA,mBAAS,EAACT,UAAUhC;;;;;;4BACtB;;;;oBApBF;;;;;;IAsBF;;IACA,WAAeV"}

package/dist/cjs/commands/index.d.cts

@@ -2,12 +2,12 @@ export type { TreeMap, TreeMapField, TreeMapHub, TreeMapRecent } from './map.js'
 export { mapTree } from './map.js';
 export type { PathOptions } from './path.js';
 export { findPath } from './path.js';
-export type { Peek, PeekSection } from './peek.js';
+export type { Peek, PeekOptions, PeekSection } from './peek.js';
 export { peek, resolveNote } from './peek.js';
 export type { RelatedOptions, RelatedResult } from './related.js';
 export { relatedNotes } from './related.js';
 export { scopedPaths } from './scope.js';
-export type { SearchOptions, SearchResult, SearchResultVia } from './search.js';
+export type { SearchOptions, SearchResult, SearchResultVia, SearchSignalContribution } from './search.js';
 export { search } from './search.js';
 export type { PresetCoverage } from './status.js';
 export { presetCoverage } from './status.js';

package/dist/cjs/commands/index.d.ts

@@ -2,12 +2,12 @@ export type { TreeMap, TreeMapField, TreeMapHub, TreeMapRecent } from './map.js'
 export { mapTree } from './map.js';
 export type { PathOptions } from './path.js';
 export { findPath } from './path.js';
-export type { Peek, PeekSection } from './peek.js';
+export type { Peek, PeekOptions, PeekSection } from './peek.js';
 export { peek, resolveNote } from './peek.js';
 export type { RelatedOptions, RelatedResult } from './related.js';
 export { relatedNotes } from './related.js';
 export { scopedPaths } from './scope.js';
-export type { SearchOptions, SearchResult, SearchResultVia } from './search.js';
+export type { SearchOptions, SearchResult, SearchResultVia, SearchSignalContribution } from './search.js';
 export { search } from './search.js';
 export type { PresetCoverage } from './status.js';
 export { presetCoverage } from './status.js';

package/dist/cjs/commands/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/commands/index.ts"],"sourcesContent":["// The three commands: mapTree (orient), search (locate), peek (structure).\n// Each returns data; cli.ts renders. All of them degrade when a feature is off.\n\nexport type { TreeMap, TreeMapField, TreeMapHub, TreeMapRecent } from './map.ts';\nexport { mapTree } from './map.ts';\nexport type { PathOptions } from './path.ts';\nexport { findPath } from './path.ts';\nexport type { Peek, PeekSection } from './peek.ts';\nexport { peek, resolveNote } from './peek.ts';\nexport type { RelatedOptions, RelatedResult } from './related.ts';\nexport { relatedNotes } from './related.ts';\nexport { scopedPaths } from './scope.ts';\nexport type { SearchOptions, SearchResult, SearchResultVia } from './search.ts';\nexport { search } from './search.ts';\nexport type { PresetCoverage } from './status.ts';\nexport { presetCoverage } from './status.ts';\n"],"names":["findPath","mapTree","peek","presetCoverage","relatedNotes","resolveNote","scopedPaths","search"],"mappings":"AAAA,2EAA2E;AAC3E,gFAAgF;;;;;;;;;;;;QAKvEA;eAAAA,gBAAQ;;QAFRC;eAAAA,cAAO;;QAIPC;eAAAA,YAAI;;QAOJC;eAAAA,wBAAc;;QALdC;eAAAA,uBAAY;;QAFNC;eAAAA,mBAAW;;QAGjBC;eAAAA,oBAAW;;QAEXC;eAAAA,gBAAM;;;qBATS;sBAEC;sBAES;yBAEL;uBACD;wBAEL;wBAEQ"}
+{"version":3,"sources":["/Users/kevin/Dev/OpenSource/ai/sensemaking/src/commands/index.ts"],"sourcesContent":["// The three commands: mapTree (orient), search (locate), peek (structure).\n// Each returns data; cli.ts renders. All of them degrade when a feature is off.\n\nexport type { TreeMap, TreeMapField, TreeMapHub, TreeMapRecent } from './map.ts';\nexport { mapTree } from './map.ts';\nexport type { PathOptions } from './path.ts';\nexport { findPath } from './path.ts';\nexport type { Peek, PeekOptions, PeekSection } from './peek.ts';\nexport { peek, resolveNote } from './peek.ts';\nexport type { RelatedOptions, RelatedResult } from './related.ts';\nexport { relatedNotes } from './related.ts';\nexport { scopedPaths } from './scope.ts';\nexport type { SearchOptions, SearchResult, SearchResultVia, SearchSignalContribution } from './search.ts';\nexport { search } from './search.ts';\nexport type { PresetCoverage } from './status.ts';\nexport { presetCoverage } from './status.ts';\n"],"names":["findPath","mapTree","peek","presetCoverage","relatedNotes","resolveNote","scopedPaths","search"],"mappings":"AAAA,2EAA2E;AAC3E,gFAAgF;;;;;;;;;;;;QAKvEA;eAAAA,gBAAQ;;QAFRC;eAAAA,cAAO;;QAIPC;eAAAA,YAAI;;QAOJC;eAAAA,wBAAc;;QALdC;eAAAA,uBAAY;;QAFNC;eAAAA,mBAAW;;QAGjBC;eAAAA,oBAAW;;QAEXC;eAAAA,gBAAM;;;qBATS;sBAEC;sBAES;yBAEL;uBACD;wBAEL;wBAEQ"}

package/dist/cjs/commands/peek.d.cts

@@ -21,6 +21,7 @@ export interface Peek {
     /** Disabled features whose result blocks are omitted rather than returned empty. */
     off: FeatureName[];
 }
+/** A section description, with an inclusive source line range and token estimate, not section prose. */
 export interface PeekSection {
     level: number;
     heading: string;
@@ -28,8 +29,15 @@ export interface PeekSection {
     end_line: number;
     tokens: number;
 }
+/** Options for the root {@link peek} API. */
+export interface PeekOptions extends SearchOverrides {
+    /** Maximum section descriptions. Defaults to 20; must be a positive safe integer. */
+    sectionCountLimit?: number;
+    /** Maximum entries in each link group independently. Defaults to 20; must be a positive safe integer. */
+    linkCountLimit?: number;
+}
 /**
  * Returns indexed metadata for a note in scope. Exact excluded paths fail before scoped basename
  * resolution; resolved neighbors stay in scope, while unresolved written targets remain visible.
  */
-export declare function peek(store: Store, cfg: ResolvedConfig, pathArg: string, overrides?: SearchOverrides): Promise<Peek>;
+export declare function peek(store: Store, cfg: ResolvedConfig, pathArg: string, overrides?: PeekOptions): Promise<Peek>;

package/dist/cjs/commands/peek.d.ts

@@ -21,6 +21,7 @@ export interface Peek {
     /** Disabled features whose result blocks are omitted rather than returned empty. */
     off: FeatureName[];
 }
+/** A section description, with an inclusive source line range and token estimate, not section prose. */
 export interface PeekSection {
     level: number;
     heading: string;
@@ -28,8 +29,15 @@ export interface PeekSection {
     end_line: number;
     tokens: number;
 }
+/** Options for the root {@link peek} API. */
+export interface PeekOptions extends SearchOverrides {
+    /** Maximum section descriptions. Defaults to 20; must be a positive safe integer. */
+    sectionCountLimit?: number;
+    /** Maximum entries in each link group independently. Defaults to 20; must be a positive safe integer. */
+    linkCountLimit?: number;
+}
 /**
  * Returns indexed metadata for a note in scope. Exact excluded paths fail before scoped basename
  * resolution; resolved neighbors stay in scope, while unresolved written targets remain visible.
  */
-export declare function peek(store: Store, cfg: ResolvedConfig, pathArg: string, overrides?: SearchOverrides): Promise<Peek>;
+export declare function peek(store: Store, cfg: ResolvedConfig, pathArg: string, overrides?: PeekOptions): Promise<Peek>;