opencode-sessions-explorer 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-06-13
+
+### Changed
+- Clarified installation, source-dev, and first-run docs, including plugin
+  registration troubleshooting, platform-specific database paths, and export/index
+  setup; shipped `docs/` in the npm package so README guide links resolve for
+  package consumers.
+
 ## [0.1.1] - 2026-06-13
 
 ### Changed

package/README.md

@@ -27,14 +27,14 @@ Unarchive session ses_… so I can open it again.
 
 | Area | Support | Notes |
 | --- | --- | --- |
-| OpenCode | Plugin host | Loads the plugin and owns the source database |
-| Bun | `>= 1.0` | Runtime; the plugin uses `bun:sqlite` (OpenCode ships Bun) |
+| OpenCode | Plugin host compatible with `@opencode-ai/plugin >= 1.15.0` | Loads the plugin and owns the source database |
+| Bun | `>= 1.0` | Runtime; the plugin uses `bun:sqlite` (OpenCode ships Bun), which should include SQLite `json1`; `check-deps` / `db-stats` verify it |
 | `ck` | `>= 0.7`, optional | Only `search-text` / `grep-session` need it; the other 16 tools work without it |
 | OS | macOS / Linux | Windows paths resolve via `%LOCALAPPDATA%` |
 
 ## Quick Start
 
-1. Add the plugin and grant access to the OpenCode data directory, then restart:
+1. Add the plugin and grant access to the OpenCode data directory:
 
 ```jsonc
 // ~/.config/opencode/opencode.json
@@ -49,12 +49,38 @@ Unarchive session ses_… so I can open it again.
 }
 ```
 
+The `external_directory` snippet covers the common macOS/Linux default path. If
+`$XDG_DATA_HOME`, Windows `%LOCALAPPDATA%`, or
+`OPENCODE_SESSIONS_EXPLORER_DB` points elsewhere, allow the actual containing
+directory and restart OpenCode. Some existing global configs use
+`external_directory: "allow"`; that also permits access, but the scoped path rule
+above is preferred for normal users.
+
 1. **Quit and restart OpenCode.** All 18 tools auto-register. OpenCode auto-installs
    npm plugins with Bun on startup, so there is no separate `npm install` step.
-1. Materialize the search export once, then verify the install:
+1. Run the health probe once. Warnings for the missing export tree, missing `ck`, or
+   missing `ck` index are okay at this stage:
+
+```bash
+bunx opencode-sessions-explorer-check-deps
+```
+
+1. Materialize the search export once:
 
 ```bash
 bunx opencode-sessions-explorer-bulk-export
+```
+
+1. (Optional) Build the `ck` index from the export root, not the repo root:
+
+```bash
+cd ~/.local/share/opencode-sessions-explorer
+ck --index .  # run in the export root, not the repo root
+```
+
+1. Run the health probe again to confirm the export and optional index state:
+
+```bash
 bunx opencode-sessions-explorer-check-deps
 ```
 

package/docs/README.md

@@ -0,0 +1,45 @@
+# Documentation
+
+This documentation is organized by intent so you can find the shortest path from
+a question about your OpenCode session history to the tool or command that answers it.
+
+## How To Navigate This Docs Set
+
+- Start pages help with install and the first successful query.
+- Guides explain workflows and decision points across the 18 tools and 3 CLIs.
+- Reference pages define stable tools, options, search surfaces, and response shapes.
+- Support pages diagnose failures.
+- Maintainer pages describe contributor and release operations.
+
+## Start Here
+
+- [Getting Started](getting-started.md): prerequisites, setup, and first successful query.
+- [Install](install.md): plugin registration, version pinning, and from-source setup.
+
+## Find By Task
+
+| If You Need To... | Read |
+| --- | --- |
+| Install the plugin and run a first query | [getting-started.md](getting-started.md), [install.md](install.md) |
+| Recall a session and drill into its content | [guides/recall-and-navigation.md](guides/recall-and-navigation.md) |
+| Search across your whole session history | [guides/search-and-grep.md](guides/search-and-grep.md) |
+| Grep inside one known session | [guides/search-and-grep.md](guides/search-and-grep.md) |
+| Analyze cost and usage | [guides/cost-and-usage-analysis.md](guides/cost-and-usage-analysis.md) |
+| Export and maintain the search tree | [guides/export-and-maintenance.md](guides/export-and-maintenance.md) |
+| Recover an archived session | [guides/manage-archived-sessions.md](guides/manage-archived-sessions.md) |
+| Read the full tool reference | [reference/tools.md](reference/tools.md) |
+| Configure paths, env vars, and behavior | [reference/configuration.md](reference/configuration.md) |
+| Understand the response/envelope format | [reference/response-format.md](reference/response-format.md) |
+| Understand the architecture | [reference/architecture.md](reference/architecture.md) |
+| Diagnose an environment or workflow failure | [support/troubleshooting.md](support/troubleshooting.md) |
+
+## Maintainers
+
+- [Development Guide](maintainers/development.md)
+- [Release Guide](maintainers/release.md)
+- [Triage Guide](maintainers/triage.md)
+- [Docs Writing Standard](maintainers/docs-writing.md)
+
+## Roadmap
+
+- [Changelog](../CHANGELOG.md)

package/docs/getting-started.md

@@ -0,0 +1,96 @@
+# Getting Started
+
+## Purpose
+
+Get from a fresh install to a first successful query against your OpenCode session
+history, then branch into the right workflow guide.
+
+## Prerequisites
+
+| Area | Requirement |
+| --- | --- |
+| OpenCode | A working OpenCode install that has run at least once (it owns the source database) and a plugin host compatible with `@opencode-ai/plugin >= 1.15.0` |
+| Bun | `>= 1.0` runtime; the plugin uses `bun:sqlite`, which should include SQLite `json1`. OpenCode ships Bun, so a standalone install is only needed to run the bundled CLIs directly. `check-deps` / `db-stats` verify it. |
+| `ck` (optional) | [`ck`](https://github.com/BeaconBay/ck) `>= 0.7`, required only by `search-text` and `grep-session`; the other 16 tools work without it |
+
+## Steps
+
+1. Register the plugin and grant access to the OpenCode data directory in
+   `~/.config/opencode/opencode.json`:
+
+   ```jsonc
+   {
+     "$schema": "https://opencode.ai/config.json",
+     "plugin": ["opencode-sessions-explorer"],
+     "permission": {
+       "external_directory": {
+         "~/.local/share/opencode/**": "allow"
+       }
+     }
+   }
+   ```
+
+   The `external_directory` allow rule is required because the OpenCode database
+   lives outside your project workspace. This snippet covers the common macOS/Linux
+   default path. If `$XDG_DATA_HOME`, Windows `%LOCALAPPDATA%`, or
+   `OPENCODE_SESSIONS_EXPLORER_DB` points elsewhere, allow the actual containing
+   directory and restart OpenCode. Some global configs use
+   `external_directory: "allow"`; that also permits access, but the scoped path rule
+   is preferred for normal users.
+
+1. Quit and restart OpenCode. It auto-installs npm plugins with Bun on startup, so
+   there is no separate `npm install` step, and all 18 tools auto-register.
+
+1. Run the install health probe before exporting. Warnings for a missing export
+   tree, missing `ck`, or missing `ck` index are expected on a fresh install:
+
+   ```bash
+   bunx opencode-sessions-explorer-check-deps
+   ```
+
+1. Materialize the searchable export tree once so content search has data to scan:
+
+   ```bash
+   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:
+
+   ```bash
+   cd ~/.local/share/opencode-sessions-explorer
+   ck --index .  # run in the export root, not the repo root
+   ```
+
+1. Run the install health probe again and confirm there are no hard failures:
+
+   ```bash
+   bunx opencode-sessions-explorer-check-deps
+   ```
+
+## Validate
+
+1. Read the final `check-deps` output. It reports database reachability, schema and
+   drift, SQLite `json1`, `busy_timeout`, export tree, channel views, `ck` CLI,
+   `ck` index, and tool-output directory status. Exit code `0` means all green, `1`
+   means optional pieces are missing, and `2` means the plugin cannot work yet.
+
+1. In OpenCode, ask an orientation question such as "what session am I in?" — the
+   model routes to `current-session` and returns this session's id, agent, model,
+   directory, and useful paths.
+
+## Next Steps
+
+- Recall and navigation: [guides/recall-and-navigation.md](guides/recall-and-navigation.md)
+- Search and grep: [guides/search-and-grep.md](guides/search-and-grep.md)
+- Cost and usage analysis: [guides/cost-and-usage-analysis.md](guides/cost-and-usage-analysis.md)
+- Export and maintenance: [guides/export-and-maintenance.md](guides/export-and-maintenance.md)
+- Manage archived sessions: [guides/manage-archived-sessions.md](guides/manage-archived-sessions.md)
+
+## Related Docs
+
+- [Install](install.md)
+- [Tool reference](reference/tools.md)
+- [Configuration reference](reference/configuration.md)
+- [Troubleshooting](support/troubleshooting.md)

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)