opencode-sessions-explorer 0.1.2 → 0.1.4

package/docs/getting-started.md

@@ -54,13 +54,14 @@ history, then branch into the right workflow guide.
    bunx opencode-sessions-explorer-bulk-export
    ```
 
-1. (Optional) Build the semantic index to enable `mode:'sem'` and `mode:'hybrid'`
-   search. This is a slow, one-time pass. Run it in the export root, not in the
-   repository checkout:
+1. (Optional) Prewarm the `ck` index. Normal `mode:'lex'`, `mode:'sem'`, and
+   `mode:'hybrid'` searches let `ck` lazily build or refresh indexes during the
+   search; prewarming only avoids first-search latency or helps troubleshooting.
+   Run it in the export root, not in the repository checkout:
 
    ```bash
    cd ~/.local/share/opencode-sessions-explorer
-   ck --index .  # run in the export root, not the repo root
+   ck --index .  # optional prewarm in the export root
    ```
 
 1. Run the install health probe again and confirm there are no hard failures:

package/docs/guides/export-and-maintenance.md

@@ -54,13 +54,16 @@ maintenance.
    bunx opencode-sessions-explorer-bulk-export --reset
    ```
 
-1. (Optional) Build the semantic index to unlock `sem` and `hybrid` search modes.
-   This is slow and only needs to run once. Run `ck --index .` from the export root,
+1. (Optional) Prewarm the `ck` index. Normal `lex`, `sem`, and `hybrid` searches
+   invoke `ck` in the requested mode so `ck` can lazily build or refresh indexes
+   during the search. Run these commands only to avoid first-search latency or to
+   troubleshoot stale/partial coverage warnings, and run them from the export root,
    not from the repository checkout:
 
    ```bash
    cd ~/.local/share/opencode-sessions-explorer
-   ck --index .  # run in the export root, not the repo root
+   ck --index .  # optional prewarm in the export root
+   ck --reindex .  # optional troubleshooting refresh
    ```
 
 1. Verify everything is wired up, and re-run after any OpenCode upgrade:

package/docs/guides/search-and-grep.md

@@ -25,9 +25,12 @@ known session, and audit individual tool invocations by name, status, or substri
 
 `search-text` and `grep-session` shell out to the optional [`ck`](https://github.com/BeaconBay/ck)
 CLI over the filesystem export tree. If `ck` is not installed, both return
-`CK_NOT_FOUND` cleanly; the other 16 tools keep working without it. Semantic modes
-additionally require a one-time `ck --index .` inside the export root — without it,
-`sem`/`hybrid` fall back to `regex` with a warning. See
+`CK_NOT_FOUND` cleanly; the other 16 tools keep working without it. Normal `lex`,
+`sem`, and `hybrid` searches invoke `ck` in that mode so `ck` can lazily build or
+refresh its own indexes during the search. Explicit `ck --index .` or
+`ck --reindex .` runs from the export root are optional prewarm/troubleshooting
+steps, not required before first use. If an index is missing, stale, or partially
+verified, the tools warn that the first/lazy-refresh run may be slow or partial. See
 [search surfaces](../reference/search-surfaces.md) for the surface/channel model.
 
 ## Controls

package/docs/reference/architecture.md

@@ -48,9 +48,11 @@ Searchable content is materialized to a filesystem tree (default
 
 The tree is built once by `opencode-sessions-explorer-bulk-export` and then
 delta-synced automatically before each `search-text` / `grep-session` call, so new
-parts become searchable without a manual re-export. Sync is cursor-based on
-`(time_updated, id)`, which also re-exports parts whose status mutated since the last
-pass.
+parts become searchable without a manual re-export. Budgeted sync uses an id-cursor
+insert fast path for newly appended parts, plus session-dirty scans keyed by
+`session.time_updated` to re-export sessions whose part status or metadata changed.
+Short search-triggered syncs also schedule a throttled background reconcile, while
+unbudgeted bulk exports perform full tombstone cleanup inline.
 
 ### L3 — ck Index (Optional)
 
@@ -59,6 +61,9 @@ CLI, which walks the export tree. `ck` supports plain regex with no index, a BM2
 full-text index, and semantic embeddings; the index lives under `.ck/` in the export
 root and is incremental. `ck` is optional: when it is absent these two tools return
 `CK_NOT_FOUND` cleanly and the other 16 tools are unaffected.
+The plugin invokes normal `lex`, `sem`, and `hybrid` `ck` searches and lets `ck`
+perform its lazy index build/refresh; explicit index commands are optional prewarm
+or troubleshooting steps, not a prerequisite for first use.
 
 ### L4 — Enriched Response
 
@@ -87,12 +92,12 @@ flag, so the direct database write is the only mechanism.
 
 ## Examples
 
-Materialize the export tree (L2), then build the optional `ck` index (L3):
+Materialize the export tree (L2), then optionally prewarm the `ck` index (L3):
 
 ```bash
 bunx opencode-sessions-explorer-bulk-export
 cd ~/.local/share/opencode-sessions-explorer
-ck --index .   # run in the export root, not the repository checkout
+ck --index .   # optional prewarm from the export root
 ```
 
 Verify all four layers are healthy:

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "opencode-sessions-explorer",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "OpenCode plugin for recall and analysis of past OpenCode sessions: search, grep, and cost/usage insights across your session history via 18 LLM tools (17 read-only plus one write, unarchive-session).",
   "keywords": [
     "opencode",
@@ -45,7 +45,7 @@
     "opencode-sessions-explorer-check-deps": "./dist/bin/check-deps.js"
   },
   "scripts": {
-    "build": "bun run clean && bun build src/plugin.ts --target=bun --format=esm --outdir=dist && bun build src/bin/bulk-export.ts src/bin/dedupe-export.ts src/bin/check-deps.ts --target=bun --format=esm --outdir=dist/bin",
+    "build": "bun run clean && bun build src/plugin.ts src/lib/export-reconcile-worker.ts --target=bun --format=esm --outdir=dist && bun build src/bin/bulk-export.ts src/bin/dedupe-export.ts src/bin/check-deps.ts --target=bun --format=esm --outdir=dist/bin",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "bun test tests/",
     "test:live": "OPENCODE_SESSIONS_EXPLORER_LIVE=1 bun test tests/",