opencode-sessions-explorer 0.1.0 → 0.1.2

package/docs/guides/cost-and-usage-analysis.md

@@ -0,0 +1,75 @@
+# Cost And Usage Analysis Guide
+
+## Purpose
+
+Quantify OpenCode spend and token usage across your session history, and surface
+recurring failures and repeated prompts.
+
+## Mental Model
+
+All four tools aggregate the `session` and `part` tables directly — no export tree
+or `ck` index required. Pick the tool by the shape of the answer you want:
+
+- **Spend by dimension** — `cost-by-project` groups by project, directory, agent, or
+  model.
+- **Spend over time** — `cost-by-period` buckets the same data by day, week, or month.
+- **Failure signal** — `list-tool-failures` aggregates errored tool calls.
+- **Repetition signal** — `list-repeated-prompts` clusters sessions by their first
+  user prompt.
+
+### The `cost_known` Flag
+
+Sessions created before OpenCode's `session_usage` migration store `cost = 0` even
+though they were not actually free. `cost-by-project` reports `cost_known: false` for
+any group whose sessions are all pre-migration, and `cost-by-period` hides
+zero-valued buckets unless you pass `include_zero_buckets: true`. Treat a zero with
+`cost_known: false` as "unknown", not "$0".
+
+## Controls
+
+| Tool | Use It For | Key Args |
+| --- | --- | --- |
+| `cost-by-project` | "Spend by project / agent / model", "which directory burned the most tokens" | `group_by` (`project_id`/`directory`/`agent`/`model`), `since_ms`/`until_ms`, `archived`, `min_cost`, `min_tokens`, `top` |
+| `cost-by-period` | "Daily/weekly/monthly spend", "cost trend over time" | `bucket` (`day`/`week`/`month`), `since_ms`/`until_ms`, `project_id`, `agent`, `tz_offset_min`, `min_cost`, `include_zero_buckets`, `max_buckets` |
+| `list-tool-failures` | "Which tool fails most", "what errors keep recurring", "sessions with the most failures" | `group_by` (`tool`/`error`/`session`), `tool`, `error_like`, `since_ms`/`until_ms`, `archived`, `limit`, `error_prefix_chars` |
+| `list-repeated-prompts` | "Have I asked this before", "my most repeated prompts" | `min_count`, `prefix_chars`, `since_ms`/`until_ms`, `archived`, `limit`, `sample_per_group` |
+
+## Recommended Flow
+
+1. Start broad with a spend breakdown by project:
+
+   ```json
+   { "group_by": "project_id", "top": 20 }
+   ```
+
+1. Compare models or agents by switching `group_by`:
+
+   ```json
+   { "group_by": "model" }
+   ```
+
+1. Look at the trend over time, shifting bucket boundaries to your local day if
+   needed (`tz_offset_min` is positive when ahead of UTC):
+
+   ```json
+   { "bucket": "day", "tz_offset_min": 120 }
+   ```
+
+1. Find what breaks most often, then expand a group with `search-tool-calls`:
+
+   ```json
+   { "group_by": "tool", "limit": 20 }
+   ```
+
+1. Detect duplicated work by clustering opening prompts:
+
+   ```json
+   { "min_count": 3, "prefix_chars": 80 }
+   ```
+
+## Related Docs
+
+- [Recall and navigation](recall-and-navigation.md)
+- [Search and grep](search-and-grep.md)
+- [Tool reference](../reference/tools.md)
+- [Response format](../reference/response-format.md)

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

@@ -0,0 +1,85 @@
+# Export And Maintenance Guide
+
+## Purpose
+
+Understand the searchable export tree that content search depends on, and keep it
+healthy with the bundled command-line tools.
+
+## Mental Model
+
+Content search does not run against the database directly. The plugin maintains a
+four-layer pipeline:
+
+```text
+SQLite DB (read-only source of truth)
+  -> filesystem export tree (~/.local/share/opencode-sessions-explorer; by-session + by-channel)
+  -> ck index (.ck/, BM25 + embeddings; optional)
+  -> enriched response (re-fetches session/part metadata from SQLite per hit)
+```
+
+The export tree materializes each searchable part as a small text file under
+`by-session/<ses_…>/` plus curated `by-channel/` views (such as conversation and
+session-summary). `ck` searches these files; the plugin then re-reads session and
+part metadata from SQLite to enrich each hit. The export root is overridable via
+`OPENCODE_SESSIONS_EXPLORER_EXPORT_ROOT`.
+
+### Auto-Sync
+
+`search-text` and `grep-session` delta-sync new parts into the export tree before
+each call (a few-second best-effort budget), so day-to-day search stays current
+without manual steps. The CLIs below are for the initial backfill and occasional
+maintenance.
+
+## Controls
+
+| Command / Tool | Use It For | Notes |
+| --- | --- | --- |
+| `opencode-sessions-explorer-bulk-export` | Build or resume the export tree | Idempotent and resumable via `.last_sync`; `--reset` starts from scratch and rebuilds curated `by-channel/` views; `--root <path>` targets a non-default export root |
+| `opencode-sessions-explorer-dedupe-export` | Remove duplicate part files from an older cursor-migration bug | Dry-run by default (reports only); pass `--apply` to actually delete, keeping the lowest-seq file per part |
+| `opencode-sessions-explorer-check-deps` | Probe install health | Checks DB, schema/drift, SQLite `json1`, `busy_timeout`, export tree, channel views, `ck` CLI, `ck` index, and tool-output dir; `--json` for machine output; exit codes `0` ok, `1` soft warning, `2` hard fail |
+| `db-stats` (tool) | Inspect database health from inside OpenCode | Returns migration head, table counts, json1 status, `busy_timeout`, and schema-drift warnings |
+
+## Recommended Flow
+
+1. Run the one-time backfill so search has content to scan:
+
+   ```bash
+   bunx opencode-sessions-explorer-bulk-export
+   ```
+
+1. If curated channel views are reported as partial (for example by
+   `check-deps`), rebuild them once:
+
+   ```bash
+   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,
+   not from the repository checkout:
+
+   ```bash
+   cd ~/.local/share/opencode-sessions-explorer
+   ck --index .  # run in the export root, not the repo root
+   ```
+
+1. Verify everything is wired up, and re-run after any OpenCode upgrade:
+
+   ```bash
+   bunx opencode-sessions-explorer-check-deps
+   ```
+
+1. If an older export shows duplicate part files, preview then apply a cleanup:
+
+   ```bash
+   bunx opencode-sessions-explorer-dedupe-export
+   bunx opencode-sessions-explorer-dedupe-export --apply
+   ```
+
+## Related Docs
+
+- [Search and grep](search-and-grep.md)
+- [Architecture](../reference/architecture.md)
+- [Search surfaces](../reference/search-surfaces.md)
+- [Configuration reference](../reference/configuration.md)
+- [Troubleshooting](../support/troubleshooting.md)

package/docs/guides/manage-archived-sessions.md

@@ -0,0 +1,70 @@
+# Manage Archived Sessions Guide
+
+## Purpose
+
+Restore a previously archived OpenCode session so it can be opened and prompted
+again, using the one tool in this plugin that writes to the database.
+
+## Mental Model
+
+`unarchive-session` is the only write surface in an otherwise read-only plugin. It
+does two things in a single isolated write:
+
+1. **Clears `time_archived`** so the session is no longer marked archived.
+2. **Refreshes `time_updated`** so the session resurfaces at the top of OpenCode's
+   recency-ordered list.
+
+The `time_updated` bump is required, not cosmetic. OpenCode loads sessions ordered
+by `time_updated DESC` with a default limit of ~100 per directory. Clearing
+`time_archived` alone leaves a long-archived session buried below that window, so the
+app still fails to retrieve it with "Unable to retrieve session". Refreshing
+`time_updated` is also the intuitive meaning of "restore". Because it always
+restores to a usable state, the tool also resurfaces an already-active-but-buried
+session and is idempotent in effect (active and at the top).
+
+### Why A Direct Database Write Is Required
+
+OpenCode exposes no archive/unarchive endpoint that can clear the flag: the HTTP
+`UpdatePayload` types `time.archived` as a finite number and the handler ignores
+`undefined`, so a clear cannot be sent over the wire. The `opencode session` CLI
+only offers list and delete. A direct database write is therefore the only
+mechanism. Reads still go through the shared read-only handle; the write goes through
+a separate, short-lived read-write connection used only by this tool.
+
+## Controls
+
+| Tool | Use It For | Key Args |
+| --- | --- | --- |
+| `unarchive-session` | "Unarchive `ses_…`", "restore an archived session so I can continue it" | `session_id` (must be an existing session; returns `NOT_FOUND` otherwise) |
+| `list-sessions` / `search-sessions-meta` | Find archived sessions to restore | `archived: 'only'` |
+
+## Recommended Flow
+
+1. Find the archived session you want back:
+
+   ```json
+   { "archived": "only", "limit": 20 }
+   ```
+
+1. Restore it by id:
+
+   ```json
+   { "session_id": "ses_XYZ" }
+   ```
+
+   The response reports `was_archived`, the new `now_active` and `resurfaced`
+   state, the session `directory`, and before/after `time_updated` values.
+
+1. Make the restored session visible in the app. Because the write happens outside
+   OpenCode, it emits no `session.updated` event:
+
+   1. Reload or restart the OpenCode window.
+   1. Open OpenCode in the session's own `directory` — it is restored under that
+      directory and now sorts to the top of the recency-ordered list.
+
+## Related Docs
+
+- [Recall and navigation](recall-and-navigation.md)
+- [Tool reference](../reference/tools.md)
+- [Architecture](../reference/architecture.md)
+- [Security policy](../../.github/SECURITY.md)

package/docs/guides/recall-and-navigation.md

@@ -0,0 +1,90 @@
+# Recall And Navigation Guide
+
+## Purpose
+
+Find a past OpenCode session, understand what it contains, and drill from a
+high-level overview down to a single message or part — including the parent/child
+chains created by subagent dispatch.
+
+## Mental Model
+
+Orient first, then drill down; walk the tree to follow subagent and
+pair-execution chains.
+
+- **Orient.** `current-session` tells the assistant which session it is running in
+  (id, agent, model, directory, counts, and useful filesystem paths). It is the
+  natural first call because the model has no native way to know its own session id.
+- **Find and browse.** `list-sessions` and `search-sessions-meta` locate sessions by
+  recency or structured metadata (agent, directory, title, cost, tokens). Neither
+  returns message bodies.
+- **Overview.** `get-session` returns one session's metadata and aggregate counts;
+  `session-summary` returns a human-readable overview (first/last prompt, top files
+  touched, top tools, errors, duration, cost).
+- **Reconstruct.** `session-timeline` returns a chronological event stream (one
+  short line per part) without raw bodies.
+- **Drill into detail.** `get-message` fetches one turn and its parts (bodies
+  capped); `get-part` fetches a single part and can dereference externalized
+  tool-output files.
+- **Trace relationships.** `session-genealogy` walks the `parent_id` chain up to
+  ancestors and down to descendants — the graph that subagent dispatches create.
+
+## Entry Points
+
+| Tool | Answers | Key Args |
+| --- | --- | --- |
+| `current-session` | "What session am I in?", "where am I?", self-orientation | `detail` (`compact`/`full`), `include_suggestions` |
+| `list-sessions` | "List my recent sessions", "sessions from last week", "sessions using agent X" | `limit`, `cursor`, `project_id`, `agent`, `model_id`, `directory_prefix`, `archived`, `since_ms`/`until_ms`, `title_like` |
+| `search-sessions-meta` | "Sessions costing more than $5", "sessions with > 100K input tokens", "most expensive session" | `title_like`, `directory_like`, `project_id`, `agent`, `model_id`, `min_cost`, `min_tokens_input`, `since_ms`/`until_ms`, `archived` |
+| `get-session` | "Metadata for `ses_X`", "how many messages/parts in `ses_Y`", "who is the parent of `ses_X`" | `session_id` |
+| `session-summary` | "Summarize `ses_X`", "what files did I touch", "what tools did I use" | `session_id`, `max_prompt_bytes` |
+| `session-timeline` | "Walk `ses_X` step by step", "show only the tool calls in order" | `session_id`, `types`, `granularity`, `from_ts`/`until_ts`, `limit`, `cursor` |
+| `get-message` | "Fetch message `msg_X` with its parts" | `message_id`, `include_part_data`, `part_types`, `max_part_bytes` |
+| `get-part` | "Show part `prt_X`", "dereference the externalized output of `prt_Z`" | `part_id`, `max_bytes`, `dereference_output_path` |
+| `session-genealogy` | "Parent chain of `ses_X`", "what subagents did `ses_Y` spawn" | `session_id`, `direction` (`ancestors`/`descendants`/`both`), `max_depth`, `include_archived` |
+
+## Recommended Flow
+
+1. Start with `current-session` to capture your own `session_id` and context.
+
+   ```json
+   { "detail": "full" }
+   ```
+
+1. If you do not yet know the session, narrow with `list-sessions` (recency) or
+   `search-sessions-meta` (cost/token/title thresholds).
+
+   ```json
+   { "agent": "build", "since_ms": 1717200000000, "limit": 20 }
+   ```
+
+1. Get the gist with `session-summary`, or raw counts with `get-session`.
+
+   ```json
+   { "session_id": "ses_XYZ", "max_prompt_bytes": 2048 }
+   ```
+
+1. Reconstruct the flow with `session-timeline`, filtering `types` to keep it tight.
+
+   ```json
+   { "session_id": "ses_XYZ", "types": ["tool", "patch"], "limit": 100 }
+   ```
+
+1. Expand a specific event with `get-message` (whole turn) or `get-part` (one part).
+   For tool output that was externalized to a file, set `dereference_output_path`:
+
+   ```json
+   { "part_id": "prt_ABC", "dereference_output_path": true }
+   ```
+
+1. Trace dispatch chains with `session-genealogy` when a session spawned subagents.
+
+   ```json
+   { "session_id": "ses_XYZ", "direction": "both", "max_depth": 5 }
+   ```
+
+## Related Docs
+
+- [Search and grep](search-and-grep.md)
+- [Tool reference](../reference/tools.md)
+- [Response format](../reference/response-format.md)
+- [Getting Started](../getting-started.md)

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

@@ -0,0 +1,87 @@
+# Search And Grep Guide
+
+## Purpose
+
+Search across the bodies of your entire OpenCode session history, grep inside one
+known session, and audit individual tool invocations by name, status, or substring.
+
+## Default Behavior
+
+- `search-text` is the canonical "where in my history did X happen?" tool. Its
+  default surface is `recall`: session-first, channel-aware, and evidence-limited,
+  searching high-signal conversation and session-summary views before raw replay.
+- The default `mode` is `regex` (a drop-in grep that needs no index and always
+  works). `lex` adds BM25 phrase search (auto-builds a Tantivy index), while `sem`
+  and `hybrid` add semantic embeddings.
+- The default `role` is `any`. Natural-language questions like "where did I mention
+  X" or "have I discussed Y" ask about appearances anywhere in the corpus — only set
+  `role:'user'` when the question is explicitly about prompts you authored.
+- For unscoped recall, results default to one row per matching session
+  (`group_by_session`); scoped, single-session searches default to flat per-part hits.
+- Snippets redact common secret shapes by default. Pass `redact:false` only for
+  local forensics.
+
+### The `ck` Dependency
+
+`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
+[search surfaces](../reference/search-surfaces.md) for the surface/channel model.
+
+## Controls
+
+| Tool | Use It For | Key Args |
+| --- | --- | --- |
+| `search-text` | Cross-session content search across all bodies (prompts, responses, tool I/O, reasoning, patches) | `q`, `mode` (`regex`/`lex`/`sem`/`hybrid`), `surface`, `channels`, `group_by_session`, `role`, `session_ids`, `project_id`, `agent`, `since_ms`/`until_ms`, `archived`, `limit`, `redact` |
+| `grep-session` | Fast regex/lex grep inside one known session | `session_id`, `pattern`, `surface`, `channels`, `mode` (`regex`/`lex`), `fixed_string`, `case_sensitive`, `whole_word`, `context_lines`, `limit`, `redact` |
+| `search-tool-calls` | Find tool invocations by name, status, or input/output/error substring | `tool` (exact or `LIKE` wildcard), `status`, `input_like`, `output_like`, `error_like`, `session_id`, `project_id`, `since_ms`/`until_ms`, `archived`, `limit`, `cursor` |
+
+## Recommended Flow
+
+1. For a broad recall question, start with `search-text` and let the default
+   `recall` surface curate results:
+
+   ```json
+   { "q": "export codec", "limit": 20 }
+   ```
+
+1. Speed up cross-session search by pre-filtering scope. Unscoped full-corpus search
+   can take 10-30 seconds; scoped searches return in under a second:
+
+   ```json
+   { "q": "retry backoff", "project_id": "global", "since_ms": 1717200000000 }
+   ```
+
+1. For exhaustive raw replay over tool output, reasoning, and patches, switch the
+   surface:
+
+   ```json
+   { "q": "SQLITE_BUSY", "surface": "forensics" }
+   ```
+
+1. Once you know the session, grep inside it with `grep-session` (faster, narrower):
+
+   ```json
+   { "session_id": "ses_XYZ", "pattern": "TODO", "context_lines": 2 }
+   ```
+
+1. To audit commands rather than prose, use `search-tool-calls` — for example every
+   failed `read`, or every Jira MCP call via a `LIKE` wildcard:
+
+   ```json
+   { "tool": "read", "status": "error", "limit": 20 }
+   ```
+
+   ```json
+   { "tool": "mcp-atlassian_jira_%", "limit": 20 }
+   ```
+
+## Related Docs
+
+- [Search surfaces](../reference/search-surfaces.md)
+- [Recall and navigation](recall-and-navigation.md)
+- [Export and maintenance](export-and-maintenance.md)
+- [Tool reference](../reference/tools.md)
+- [Troubleshooting](../support/troubleshooting.md)

package/docs/install.md

@@ -0,0 +1,140 @@
+# Install
+
+## Purpose
+
+Register `opencode-sessions-explorer` in OpenCode, optionally pin a version, and
+grant the one permission it needs to read the OpenCode session database.
+
+## Prerequisites
+
+| Area | Requirement |
+| --- | --- |
+| OpenCode | A working OpenCode install with plugin host compatibility for `@opencode-ai/plugin >= 1.15.0` |
+| Bun | `>= 1.0`; bundled with OpenCode, needed standalone only to run the CLIs directly. The plugin uses `bun:sqlite`, which should include SQLite `json1`; `check-deps` / `db-stats` verify it. |
+| `ck` (optional) | `>= 0.7`, only for `search-text` and `grep-session` |
+
+## Steps
+
+1. Add the plugin to the `plugin` array in `~/.config/opencode/opencode.json`:
+
+   ```jsonc
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "plugin": ["opencode-sessions-explorer"]
+   }
+   ```
+
+   OpenCode auto-installs npm plugins with Bun on startup and caches them under
+   `~/.cache/opencode/node_modules`, so there is no separate install command.
+
+1. (Optional) Pin a version to avoid surprise upgrades by appending the version to
+   the package spec (for example, the current latest):
+
+   ```jsonc
+   {
+     "plugin": ["opencode-sessions-explorer@0.1.1"]
+   }
+   ```
+
+1. Grant access to the OpenCode data directory. This is required because the
+   database lives outside your project workspace:
+
+   ```jsonc
+   {
+     "permission": {
+       "external_directory": {
+         "~/.local/share/opencode/**": "allow"
+       }
+     }
+   }
+   ```
+
+   This default snippet covers the common macOS/Linux path. If `$XDG_DATA_HOME`,
+   Windows `%LOCALAPPDATA%`, or `OPENCODE_SESSIONS_EXPLORER_DB` points elsewhere,
+   allow the actual containing directory and restart OpenCode. Some current global
+   configs may use `external_directory: "allow"`; that works, but the scoped path
+   rule above is preferred for normal users.
+
+1. Quit and restart OpenCode. All 18 tools auto-register on the next launch.
+
+### From Source (Dev)
+
+To run a local checkout instead of the published package, install dependencies in
+the checkout first:
+
+```bash
+bun install --frozen-lockfile
+```
+
+Then choose one source-dev mode.
+
+#### Option A: Source TypeScript For Iteration
+
+Point the `plugin` array at the source entrypoint using an absolute path:
+
+```jsonc
+{
+  "plugin": ["/absolute/path/to/opencode-sessions-explorer/src/plugin.ts"]
+}
+```
+
+This is the fastest iteration path because there is no `dist/` rebuild step, but a
+full OpenCode restart is still required after config or code changes. Do not assume
+hot reload.
+
+#### Option B: Built JavaScript
+
+Build the bundle, then point OpenCode at the built entrypoint:
+
+```bash
+bun run build
+```
+
+```jsonc
+{
+  "plugin": ["/absolute/path/to/opencode-sessions-explorer/dist/plugin.js"]
+}
+```
+
+When using `dist/`, rebuild and fully restart OpenCode after code changes. There is
+no hot reload guarantee for local plugin paths.
+
+For contributor commands, quality gates, and source-dev maintenance pointers, see
+the [Development Guide](maintainers/development.md).
+
+## Validate
+
+Confirm the install resolved and the database is reachable:
+
+```bash
+bunx opencode-sessions-explorer-check-deps
+```
+
+For source checkouts, run local checkout commands instead of `bunx` while iterating:
+
+```bash
+bun src/bin/check-deps.ts
+bun src/bin/bulk-export.ts
+```
+
+If you selected the built-JS option and have already run `bun run build`, you can
+also validate the built CLI:
+
+```bash
+bun dist/bin/check-deps.js
+```
+
+A `0` exit code is all green; `1` flags optional pieces (such as a missing export
+tree or `ck`); `2` means a hard failure that must be fixed before the tools work.
+
+## Next Steps
+
+Continue with [getting-started.md](getting-started.md) to materialize the search
+export and run a first query.
+
+## Related Docs
+
+- [Getting Started](getting-started.md)
+- [Configuration reference](reference/configuration.md)
+- [Development Guide](maintainers/development.md)
+- [Troubleshooting](support/troubleshooting.md)

package/docs/maintainers/development.md

@@ -0,0 +1,140 @@
+# Development Guide
+
+## Purpose
+
+Define the local contributor workflow, quality gates, and project-specific
+gotchas for `opencode-sessions-explorer`.
+
+## Prerequisites
+
+- [Bun](https://bun.sh) >= 1.0. OpenCode ships Bun; install it standalone only if
+  you run the bundled CLIs directly. The runtime is Bun, not Node — the plugin
+  uses `bun:sqlite`, which should include SQLite `json1`; `check-deps` / `db-stats`
+  verify it.
+- An OpenCode plugin host compatible with `@opencode-ai/plugin >= 1.15.0`.
+- [`ck`](https://github.com/BeaconBay/ck) >= 0.7 — required only when working on
+  `search-text` / `grep-session`; the other 16 tools work without it.
+- A populated OpenCode SQLite DB at `~/.local/share/opencode/opencode.db` —
+  required only for live testing and the end-to-end verifier.
+
+## Local Setup
+
+```bash
+bun install --frozen-lockfile
+```
+
+Load the plugin into a running OpenCode while iterating by pointing the config at
+your local checkout. Use the source TypeScript or built JavaScript options in
+[Install: From Source (Dev)](../install.md#from-source-dev); that page is the
+authoritative source-dev registration flow, including the full-restart requirement.
+
+## Local Dev Loop
+
+```bash
+bun run typecheck   # tsc --noEmit (strict mode)
+bun test            # hermetic by default
+bun run build       # bundle to dist/
+```
+
+For changes that affect tool output, also run the end-to-end verifier, which
+compares each tool against ground-truth SQL (this one needs a live DB):
+
+```bash
+bun tests/verify-end-to-end.ts
+```
+
+Check install health any time:
+
+```bash
+bun src/bin/check-deps.ts
+```
+
+For source-dev first-run validation, use the local checkout CLIs from
+[Install](../install.md#validate) (`bun src/bin/check-deps.ts`,
+`bun src/bin/bulk-export.ts`, or `bun dist/bin/check-deps.js` after a build) rather
+than `bunx`, which exercises the published npm package.
+
+## Architecture (pointer)
+
+The plugin is a 4-layer pipeline:
+
+```
+SQLite DB (read-only source of truth)
+  -> filesystem export tree (~/.local/share/opencode-sessions-explorer; by-session + by-channel)
+  -> ck index (.ck/; BM25 + embeddings; optional)
+  -> enriched response (re-fetches session/part metadata from SQLite per hit)
+```
+
+See the [Architecture Reference](../reference/architecture.md) for the full layer
+diagram and read-only / single-writer invariants, and the
+[Export And Maintenance Guide](../guides/export-and-maintenance.md) for export/index
+operations. `AGENTS.md` holds the authoritative per-tool contract.
+
+## Environment Overrides
+
+All paths are env-overridable, which is the easiest way to point tests or a dev
+session at non-default locations:
+
+| Env var | Purpose |
+| --- | --- |
+| `OPENCODE_SESSIONS_EXPLORER_DB` | Path to the OpenCode SQLite DB |
+| `OPENCODE_SESSIONS_EXPLORER_EXPORT_ROOT` | Where searchable session content is materialized |
+| `OPENCODE_SESSIONS_EXPLORER_TOOL_OUTPUT_DIR` | Whitelist root for `get-part` dereference |
+| `OPENCODE_SESSIONS_EXPLORER_CK_BIN` | Override the `ck` binary location |
+
+## Tests: Hermetic vs Live
+
+- `bun test` is **hermetic by default** — it runs against a synthetic fixture DB
+  and does not need your real history. This is what CI runs.
+- To exercise the suite against your real `~/.local/share/opencode/opencode.db`,
+  opt in:
+
+  ```bash
+  OPENCODE_SESSIONS_EXPLORER_LIVE=1 bun test
+  # or
+  bun run test:live
+  ```
+
+  Live runs read real `ses_/msg_/prt_` IDs and minimum counts from your OpenCode
+  database; failures there reflect your own data, not necessarily a regression.
+
+## The `.js`-Import Gotcha (do not "fix" it)
+
+Inside `src/`, sibling imports use a **`.js`** extension even though the files are
+`.ts`:
+
+```ts
+import { stmt } from "../lib/db.js"; // the file is db.ts — this is correct
+```
+
+This is required by `tsc` (`moduleResolution: bundler`) and `bun build`. Rewriting
+these to `.ts` will break typecheck and the build. Files under `tests/` import
+`src` with `.ts`; that is fine, because Bun runs them unbuilt.
+
+## Adding or Editing a Tool
+
+- One tool per file in `src/tools/`, exported as a **named const** (not default).
+- Register it in `src/tools/index.ts` under the
+  `opencode-sessions-explorer-<name>` key and the re-export block.
+- Wrap the body in `runWithEnvelope("<fn_name>", capKb, async (ctx) => { … })`.
+- Raise recoverable errors via `fail(code, msg, hint)` using a code from
+  `src/lib/errors.ts`; do not invent ad-hoc error shapes.
+- Wrap list-shaped results in `table(records, { dict: [...] })` (lossless
+  columnar + interning).
+
+See `AGENTS.md` for the authoritative, fully detailed version of this contract.
+
+## Change Checklist
+
+- Run `bun run typecheck`, `bun test`, and `bun run build` locally.
+- For tool-output changes, run `bun tests/verify-end-to-end.ts`.
+- Update [`README.md`](../../README.md) for any user-facing change.
+- Add a note under `## [Unreleased]` in [`CHANGELOG.md`](../../CHANGELOG.md).
+- Keep commit scope focused.
+
+## Related Docs
+
+- [Docs Writing Standard](docs-writing.md)
+- [Install Guide](../install.md)
+- [Release Guide](release.md)
+- [Triage Guide](triage.md)