opencode-sessions-explorer 0.1.0 → 0.1.2

package/docs/maintainers/docs-writing.md

@@ -0,0 +1,86 @@
+# Docs Writing Standard
+
+## Purpose
+
+Define consistent structure, markdown style, and explanation patterns for
+project docs.
+
+## Core Principles
+
+- Lead with user outcome, then steps, then edge cases.
+- One page should have one clear intent.
+- Prefer short concrete statements over broad prose.
+- Use stable terms (`search-text`, `unarchive-session`, `OPENCODE_SESSIONS_EXPLORER_DB`)
+  consistently.
+
+## Page Type Templates
+
+### Start Pages
+
+Use sections in this order:
+
+1. `Purpose`
+1. `Prerequisites`
+1. `Setup` or `Steps`
+1. `Validate` (how to confirm success)
+1. `Next steps`
+
+### Guides
+
+Use sections in this order:
+
+1. `Purpose`
+1. `Default behavior` or `Mental model`
+1. `Controls` or `Entry points`
+1. `Recommended flow`
+1. `Related docs`
+
+### Reference Pages
+
+Use sections in this order:
+
+1. `Scope`
+1. `Definitions/Tables`
+1. `Examples`
+1. `Related docs`
+
+### Troubleshooting Pages
+
+Use sections in this order:
+
+1. `How to use this page`
+1. `Baseline checks`
+1. Symptom blocks (`Quick checks`, `Fix`)
+1. `Related docs`
+
+## Markdown Conventions
+
+- Keep headings concise and in Title Case.
+- Use numbered lists (`1.` style) for procedures.
+- Use tables for command/option/tool inventories.
+- Wrap commands, paths, options, env vars, and tool names in backticks.
+- Prefer fenced code blocks with language identifiers.
+- End pages with a `Related Docs` section.
+
+## Explanation Pattern
+
+Use this order for each important concept:
+
+1. What it is
+1. Why it matters
+1. How to use it
+1. How to validate it
+1. Where to go next
+
+## Link Policy
+
+- Keep canonical maintainer pages under `docs/maintainers/`.
+- Use relative links between docs and back to root files (`../../README.md`).
+- Update the "Maintainer Docs" list in [`CONTRIBUTING.md`](../../CONTRIBUTING.md)
+  whenever docs paths or ownership change.
+
+## Related Docs
+
+- [Development Guide](development.md)
+- [Release Guide](release.md)
+- [Triage Guide](triage.md)

package/docs/maintainers/release.md

@@ -0,0 +1,72 @@
+# Release Guide
+
+## Purpose
+
+Define repeatable steps to cut and publish a release of
+`opencode-sessions-explorer` to npm and GitHub.
+
+## Versioning
+
+Use [SemVer](https://semver.org/spec/v2.0.0.html):
+
+- Major: breaking changes
+- Minor: new features
+- Patch: fixes and docs
+
+## Release Checklist
+
+1. Bump the version in `package.json` to the target `x.y.z`.
+1. Move the `## [Unreleased]` notes in `CHANGELOG.md` into a new
+   `## [x.y.z] - YYYY-MM-DD` section, and leave an empty `## [Unreleased]`
+   above it for the next cycle.
+1. Run the quality gates locally and confirm they pass:
+
+   ```bash
+   bun run typecheck
+   bun test
+   bun run build
+   ```
+
+1. Confirm the **CI** workflow (`.github/workflows/ci.yml`) is green on the
+   commit you intend to tag.
+1. Commit the version bump and changelog (for example
+   `chore(release): vX.Y.Z`).
+1. Create an annotated tag and push it:
+
+   ```bash
+   git tag -a vX.Y.Z -m "vX.Y.Z"
+   git push origin vX.Y.Z
+   ```
+
+Pushing a `vX.Y.Z` tag triggers `.github/workflows/publish.yml`, which publishes
+the package to npm with provenance and creates the GitHub Release from the
+changelog entry.
+
+## Publish Bootstrap (first release only)
+
+The publish workflow is configured for npm
+[Trusted Publishing (OIDC)](https://docs.npmjs.com/trusted-publishers), which
+needs the package to already exist on npm before OIDC can be linked. Bootstrap it
+once:
+
+1. Create a short-lived **automation** npm token and add it to the repository as
+   the `NPM_TOKEN` secret.
+1. Cut the first release (`v0.1.0`) so `publish.yml` publishes the initial
+   version to npm using that token.
+1. In the npm package settings, configure **Trusted Publishing** for this repo's
+   `.github/workflows/publish.yml`.
+1. **Revoke** the `NPM_TOKEN` secret and the npm token. Subsequent releases
+   authenticate via OIDC with no long-lived secret.
+
+## Post-Release
+
+- Verify the new version is live on
+  [npm](https://www.npmjs.com/package/opencode-sessions-explorer) and that the
+  GitHub Release was created.
+- Monitor issues for regressions.
+- Triage and label follow-up reports (see [Triage Guide](triage.md)).
+
+## Related Docs
+
+- [Development Guide](development.md)
+- [Triage Guide](triage.md)

package/docs/maintainers/triage.md

@@ -0,0 +1,55 @@
+# Triage Guide
+
+## Purpose
+
+Define issue intake, labeling, and follow-up policy. The canonical label
+definitions live in [`.github/labels.yml`](../../.github/labels.yml); this guide
+documents how they are applied.
+
+## Intake Flow
+
+1. Confirm issue template quality (clear repro, version, environment).
+1. Reproduce the issue when possible.
+1. Apply labels for type, status, and scope.
+
+## Label Set
+
+Issue type:
+
+- `bug` — something is not working
+- `enhancement` — new feature or request
+- `documentation` — documentation updates
+- `security` — security related issues
+- `question` — further information requested
+
+Contributor signals:
+
+- `help wanted` — extra attention is needed
+- `good first issue` — good for newcomers
+
+Implementation focus:
+
+- `tests` — test coverage or fixes
+- `refactor` — refactoring or cleanup
+- `chore` — maintenance tasks
+
+Triage status:
+
+- `triage/needs-info` — needs more information from the reporter
+- `triage/confirmed` — repro confirmed by maintainers
+- `triage/blocked` — blocked on an external dependency or upstream (e.g.
+  OpenCode or `ck`)
+- `triage/duplicate` — duplicate of an existing issue
+- `triage/wontfix` — will not be addressed
+
+## Follow-Up Policy
+
+- Close `triage/needs-info` after 14 days without a response.
+- For `triage/blocked`, document the blocker and a recheck date.
+- Close `triage/duplicate` with a link to the canonical issue.
+- Close `triage/wontfix` with a concise rationale and alternatives when possible.
+
+## Related Docs
+
+- [Development Guide](development.md)
+- [Release Guide](release.md)

package/docs/reference/architecture.md

@@ -0,0 +1,112 @@
+# Architecture Reference
+
+## Scope
+
+This page describes the four-layer pipeline that turns the OpenCode session
+database into enriched, searchable tool responses, and the single-writer exception
+to the otherwise read-only design. It is a conceptual reference; for the
+contributor-facing build and code layout, see the
+[Development Guide](../maintainers/development.md).
+
+## The Four Layers
+
+```
+L1  SQLite DB (read-only source of truth)
+      | PRAGMA query_only = 1; opened readonly
+      v
+L2  filesystem export tree (~/.local/share/opencode-sessions-explorer)
+      | by-session/<ses_id>/...  +  by-channel/<channel>/by-session/<ses_id>/...
+      | delta-synced before each search call
+      v
+L3  ck index (.ck/, BM25 + embeddings; optional)
+      | incremental; built by the ck CLI
+      v
+L4  enriched response
+      | re-fetches session/part metadata from SQLite per hit
+      v
+    { ok, data, meta, warnings } envelope
+```
+
+### L1 — SQLite Source Of Truth
+
+The OpenCode database is the authoritative source. The shared handle opens it
+read-only and sets `PRAGMA query_only = 1` as a belt-and-braces guard, so any
+accidental write through that handle throws. The live OpenCode process may be
+writing concurrently — the database runs in WAL mode and multiple readers plus a
+writer is safe, with a `busy_timeout` covering rare lock collisions. All metadata,
+counts, and message/part bodies ultimately come from here.
+
+### L2 — Filesystem Export Tree
+
+Searchable content is materialized to a filesystem tree (default
+`~/.local/share/opencode-sessions-explorer`, overridable via
+`OPENCODE_SESSIONS_EXPLORER_EXPORT_ROOT`). It has two arms:
+
+- `by-session/<ses_id>/` — the raw, lossless per-part export plus `meta.json`.
+- `by-channel/<channel>/by-session/<ses_id>/` — curated channel views derived from
+  the raw parts (see [search-surfaces.md](search-surfaces.md)).
+
+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.
+
+### L3 — ck Index (Optional)
+
+`search-text` and `grep-session` shell out to the [`ck`](https://github.com/BeaconBay/ck)
+CLI, which walks the export tree. `ck` supports plain regex with no index, a BM25
+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.
+
+### L4 — Enriched Response
+
+Search hits from `ck` carry file paths, not domain objects. The final layer parses
+the session and part ids out of each hit path and re-fetches fresh metadata from
+SQLite (session title, agent, model, part type, message role) before returning
+results. Every tool wraps its payload in a uniform `{ ok, data, meta, warnings }`
+envelope; list-shaped data inside `data` uses the compact format described in
+[response-format.md](response-format.md).
+
+## Single-Writer Exception
+
+The plugin is read-only with exactly one sanctioned write: `unarchive-session`.
+Reads never write through the shared read-only handle. The write goes through a
+separate, short-lived read-write connection that performs a single statement —
+`UPDATE session SET time_archived = NULL, time_updated = <now>` — and closes
+immediately.
+
+Both fields are updated deliberately. OpenCode loads sessions ordered by
+`time_updated DESC` with a default limit per directory, so clearing `time_archived`
+alone would leave a long-archived session buried below that window, and opening it
+would fail with "Unable to retrieve session". Refreshing `time_updated` resurfaces
+the session at the top of the list, which is also the intuitive meaning of
+"restore". OpenCode exposes no HTTP or SDK endpoint that can *clear* the archived
+flag, so the direct database write is the only mechanism.
+
+## Examples
+
+Materialize the export tree (L2), then build the optional `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
+```
+
+Verify all four layers are healthy:
+
+```bash
+bunx opencode-sessions-explorer-check-deps
+```
+
+## Related Docs
+
+- Tool catalog: [tools.md](tools.md)
+- Search surfaces and channels: [search-surfaces.md](search-surfaces.md)
+- Compact result format: [response-format.md](response-format.md)
+- Configuration and environment overrides: [configuration.md](configuration.md)
+- Export and maintenance workflow: [../guides/export-and-maintenance.md](../guides/export-and-maintenance.md)
+- Development Guide: [../maintainers/development.md](../maintainers/development.md)
+- Troubleshooting: [../support/troubleshooting.md](../support/troubleshooting.md)

package/docs/reference/configuration.md

@@ -0,0 +1,115 @@
+# Configuration Reference
+
+## Scope
+
+This page documents how to configure `opencode-sessions-explorer`: the OpenCode
+`permission` rule the plugin needs, the environment variables that override every
+filesystem path, and the opt-in switch for running the test suite against real
+session data.
+
+The plugin has no settings object of its own — it is configured entirely through
+OpenCode permissions and environment variables. All defaults work out of the box on
+macOS and Linux; Windows paths resolve via `%LOCALAPPDATA%`.
+
+## Required Permission
+
+The OpenCode session database lives outside your project workspace, so OpenCode
+must be granted access to its data directory. Add an `external_directory` allow rule
+to your OpenCode config and restart:
+
+```jsonc
+// ~/.config/opencode/opencode.json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-sessions-explorer"],
+  "permission": {
+    "external_directory": {
+      "~/.local/share/opencode/**": "allow"
+    }
+  }
+}
+```
+
+Without this rule the read-only database handle cannot open the file and tools fail
+with `DB_NOT_FOUND` or a permission error. The change takes effect only after a full
+OpenCode restart. See [Permission Denied / external_directory](../support/troubleshooting.md#permission-denied--external_directory)
+if a tool still cannot reach the database after adding the rule.
+
+The snippet above covers the common macOS/Linux default path. If `$XDG_DATA_HOME`,
+Windows `%LOCALAPPDATA%`, or `OPENCODE_SESSIONS_EXPLORER_DB` points to another
+database location, allow the actual directory that contains `opencode.db` and
+restart OpenCode. Some existing global configs may set `external_directory: "allow"`;
+that grants broad access and is useful for local power users, but the scoped path
+rule is preferred for normal installs.
+
+## Runtime Compatibility
+
+The plugin targets the OpenCode plugin host contract provided by
+`@opencode-ai/plugin >= 1.15.0`. It runs on Bun and uses `bun:sqlite`, which should
+include SQLite `json1`; the bundled health probes (`check-deps` CLI and `db-stats`
+tool) verify `json1`, schema drift, and database runtime settings for the active
+OpenCode database.
+
+## Environment Overrides
+
+Every path the plugin uses is overridable through an environment variable. These are
+the simplest way to point the plugin (or its tests) at non-default locations.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `OPENCODE_SESSIONS_EXPLORER_DB` | `$XDG_DATA_HOME/opencode/opencode.db` (macOS/Linux) or `%LOCALAPPDATA%\opencode\opencode.db` (Windows); falls back to `~/.local/share/opencode/opencode.db` | Absolute path to the OpenCode SQLite database the plugin reads. Set this when the database is not in the default OpenCode data directory. |
+| `OPENCODE_SESSIONS_EXPLORER_EXPORT_ROOT` | `~/.local/share/opencode-sessions-explorer` | Directory where searchable session content is materialized (the `by-session` and `by-channel` export trees that `ck` indexes). |
+| `OPENCODE_SESSIONS_EXPLORER_TOOL_OUTPUT_DIR` | `$XDG_DATA_HOME/opencode/tool-output` (macOS/Linux) or `%LOCALAPPDATA%\opencode\tool-output` (Windows); falls back to `~/.local/share/opencode/tool-output` | Whitelist root for `get-part` dereference. Only files resolving inside this root may be read when `dereference_output_path:true`; any other path is rejected with `PATH_TRAVERSAL`. |
+| `OPENCODE_SESSIONS_EXPLORER_CK_BIN` | `ck` discovered on `PATH` | Absolute path to the `ck` binary. Set this when `ck` is installed outside `PATH`; only `search-text` and `grep-session` use it. |
+
+### `get-part` Dereference Guard
+
+The `OPENCODE_SESSIONS_EXPLORER_TOOL_OUTPUT_DIR` whitelist is enforced before any
+externalized tool output is read. Symlinks are resolved before the path is compared
+to the root, so a symlink inside the whitelist that points outside it is also
+rejected. This is why `get-part` returns `PATH_TRAVERSAL` for any path outside the
+tool-output directory — see the troubleshooting page for the recovery steps.
+
+## Testing Override (Dev Only)
+
+`bun test` is hermetic by default and runs against a synthetic fixture database. To
+exercise the suite against real session data instead, opt in with:
+
+```bash
+OPENCODE_SESSIONS_EXPLORER_LIVE=1 bun test
+```
+
+Live runs read real `ses_`/`msg_`/`prt_` ids and minimum counts from your own
+history, so failures there reflect local data rather than a regression. This switch
+is for contributors only and has no effect on the plugin at runtime; see the
+[Development Guide](../maintainers/development.md) for the full contributor loop.
+
+## Examples
+
+Point the plugin at a database in a custom location:
+
+```bash
+export OPENCODE_SESSIONS_EXPLORER_DB="/data/opencode/opencode.db"
+```
+
+Materialize the search export to a dedicated disk:
+
+```bash
+export OPENCODE_SESSIONS_EXPLORER_EXPORT_ROOT="/fast-ssd/opencode-search"
+bunx opencode-sessions-explorer-bulk-export
+```
+
+Use a `ck` binary that is not on `PATH`:
+
+```bash
+export OPENCODE_SESSIONS_EXPLORER_CK_BIN="$HOME/.cargo/bin/ck"
+```
+
+## Related Docs
+
+- Tool catalog: [tools.md](tools.md)
+- Search surfaces and channels: [search-surfaces.md](search-surfaces.md)
+- Four-layer architecture: [architecture.md](architecture.md)
+- Data exposure and redaction policy: [../../.github/SECURITY.md](../../.github/SECURITY.md)
+- Install walkthrough: [../install.md](../install.md)
+- Troubleshooting: [../support/troubleshooting.md](../support/troubleshooting.md)

package/docs/reference/response-format.md

@@ -0,0 +1,120 @@
+# Response Format Reference
+
+## Scope
+
+This page documents the compact, lossless format that list-shaped tool results use.
+Several tools return arrays of uniform records (sessions, events, tool calls, cost
+groups, search hits). Serializing those as plain arrays-of-objects repeats every
+JSON key on every row and re-serializes the same nested values (model, directory,
+agent) again and again. To cut payload size without losing information, list results
+are encoded as a columnar table with string interning.
+
+Scalar, single-object responses (for example `get-session` or `db-stats`) are
+returned as ordinary JSON objects and are **not** encoded this way.
+
+## The Table Shape
+
+An encoded list result is an object with three keys:
+
+```json
+{
+  "cols": ["id", "title", "agent", "model"],
+  "dict": {
+    "agent": ["build", "executor-gpt"],
+    "model": [{ "id": "claude-opus", "provider": "anthropic" }]
+  },
+  "rows": [
+    ["ses_a1", "Fix retry bug", 0, 0],
+    ["ses_b2", "Cost audit", 1, 0]
+  ]
+}
+```
+
+- `cols` — the column order; each row is an array of cells in this order.
+- `dict` — interning tables for selected columns. A column listed here stores its
+  distinct values once; rows reference them by integer index. Columns absent from
+  `dict` store their literal value inline.
+- `rows` — one array per record.
+
+## Decode Rule
+
+There is a single decode rule:
+
+> A cell in a column whose name is a key in `dict` is an integer index into
+> `dict[col]`. Otherwise the cell is its literal value.
+
+Decoding the example above yields:
+
+```json
+[
+  { "id": "ses_a1", "title": "Fix retry bug", "agent": "build", "model": { "id": "claude-opus", "provider": "anthropic" } },
+  { "id": "ses_b2", "title": "Cost audit", "agent": "executor-gpt", "model": { "id": "claude-opus", "provider": "anthropic" } }
+]
+```
+
+Note that both rows reuse the same `model` object (index `0`) instead of repeating
+it — that is where the savings come from on large result sets.
+
+## Reference Decoder
+
+The plugin ships the inverse function, `decodeTable()`, in
+[`src/lib/table.ts`](../../src/lib/table.ts). It is used by the test suite and is
+safe for consumers to copy. Two behaviors make migration painless:
+
+- A plain array passed to `decodeTable()` is returned unchanged, so callers can
+  treat encoded and unencoded results uniformly.
+- An out-of-range or non-integer cell in a `dict` column is passed through as its
+  literal value rather than throwing.
+
+A minimal equivalent decoder:
+
+```ts
+function decodeTable(t) {
+  if (t == null) return []
+  if (Array.isArray(t)) return t // already plain
+  const dict = t.dict ?? {}
+  return t.rows.map((row) => {
+    const o = {}
+    t.cols.forEach((c, i) => {
+      const v = row[i]
+      const d = dict[c]
+      o[c] = d && typeof v === "number" && v >= 0 && v < d.length ? d[v] : v
+    })
+    return o
+  })
+}
+```
+
+## Examples
+
+A `list-sessions` result interns the repetitive `agent`, `model`, `directory`, and
+`project_id` columns:
+
+```json
+{
+  "sessions": {
+    "cols": ["id", "title", "agent", "model", "directory", "cost"],
+    "dict": {
+      "agent": ["build"],
+      "model": [{ "id": "claude-opus" }],
+      "directory": ["/projects/app"],
+      "project_id": []
+    },
+    "rows": [
+      ["ses_a1", "Fix retry bug", 0, 0, 0, 0.42]
+    ]
+  },
+  "has_more": false
+}
+```
+
+Apply the decode rule to recover the records, then read `cost` (a literal column)
+directly.
+
+## Related Docs
+
+- Tool catalog: [tools.md](tools.md)
+- Search surfaces and channels: [search-surfaces.md](search-surfaces.md)
+- Four-layer architecture: [architecture.md](architecture.md)
+- Configuration and environment overrides: [configuration.md](configuration.md)
+- Troubleshooting: [../support/troubleshooting.md](../support/troubleshooting.md)

package/docs/reference/search-surfaces.md

@@ -0,0 +1,106 @@
+# Search Surfaces Reference
+
+## Scope
+
+This page documents the retrieval presets (`surface`) and the underlying channels
+that `search-text` and `grep-session` use to decide *what* exported content to
+search. Raw session data always stays lossless in the database and export tree;
+channels are derived search views that let default recall search high-signal content
+first while preserving raw drill-down through part and message ids.
+
+Both tools accept a `surface` argument and an optional `channels` override. If you
+pass `channels` explicitly, it takes precedence over the surface-derived set.
+
+## Surfaces
+
+A surface is a named preset that expands to a curated set of channels. The default
+is `recall`.
+
+| Surface | Channels Searched | Use For |
+| --- | --- | --- |
+| `recall` | `conversation`, `session-summary` | Default. Session-first, high-signal recall — "where did I mention X", "find sessions about Y". |
+| `debug_trace` | `conversation`, `session-summary`, `tool-error`, `tool-input-summary` | Investigating failures and what led to them — errors, exceptions, stack traces, logs. |
+| `tool_audit` | `tool-input-summary`, `tool-error` | Auditing tool usage — bash commands, tool calls, MCP calls, and their errors. |
+| `code` | `conversation`, `session-summary`, `code-touch`, `patch-summary`, `tool-input-summary` | Tracing file and code changes — paths, diffs, edits, patches. |
+| `forensics` | `raw` | Exhaustive replay over raw exported bodies, including full tool output and reasoning. Slowest; use when curated channels miss something. |
+
+### Surface Inference
+
+When `surface` is left at its default (`recall`), the query text is inspected and
+the surface may be auto-promoted:
+
+- Error vocabulary (`error`, `exception`, `stack trace`, `failed`, `timeout`,
+  `logs`, `stderr`, `stdout`) promotes to `debug_trace`.
+- Tool vocabulary (`tool calls`, `bash`, `command`, `grep`, `read tool`,
+  `edit tool`, `apply_patch`, `mcp`, …) promotes to `tool_audit`.
+- Code vocabulary (`file`, `path`, `class`, `function`, `symbol`, `diff`, `patch`,
+  `edited`, `src/`, `.ts`, `.kt`, `.py`, …) promotes to `code`.
+
+Passing an explicit non-`recall` surface disables inference and uses that surface
+as-is.
+
+## Channels
+
+Channels are the derived views the export tree materializes under
+`by-channel/<channel>/by-session/<ses_id>/`. The raw, lossless export lives under
+`by-session/<ses_id>/` and is reachable through the `raw` channel.
+
+| Channel | Contents |
+| --- | --- |
+| `conversation` | User and assistant text, plus subtask prompts. |
+| `session-summary` | Per-session synthesized summary: title, directory, first and last user prompt. |
+| `tool-input-summary` | Compact summary of each tool invocation's inputs (command, paths, query, ids). |
+| `tool-error` | Normalized error text from failed tool calls. |
+| `code-touch` | File paths touched by file tools and patches. |
+| `tool-output` | Raw output bodies produced by tool calls. |
+| `patch-summary` | Files changed per patch, with hash and file count. |
+| `reasoning` | Assistant reasoning text. |
+| `file` | File-reference parts (filename, URL, source path). |
+| `raw` | The full-fidelity per-session export, including every searchable body. Selected by the `forensics` surface. |
+
+## Grep Defaults
+
+`grep-session` defaults to the same curated channels as the active surface
+(`recall` → `conversation`, `session-summary`) when the curated channel export is
+available. To search the raw exported bodies of a single session — including tool
+output and reasoning — set `surface:'forensics'` or pass `channels:['raw']`.
+
+If the curated channel export is only partial (not yet backfilled), both tools fall
+back to the raw `by-session` export to avoid false negatives and add a warning;
+running `opencode-sessions-explorer-bulk-export --reset` backfills the curated
+channels. See [export-and-maintenance.md](../guides/export-and-maintenance.md).
+
+## Examples
+
+Default recall search across all sessions:
+
+```text
+opencode-sessions-explorer-search-text { "q": "rate limiting" }
+```
+
+Force a raw forensic sweep with explicit channels:
+
+```text
+opencode-sessions-explorer-search-text { "q": "AKIA", "surface": "forensics" }
+```
+
+Grep one session's raw bodies (tool output included):
+
+```text
+opencode-sessions-explorer-grep-session { "session_id": "ses_…", "pattern": "ETIMEDOUT", "channels": ["raw"] }
+```
+
+Audit tool inputs and errors only:
+
+```text
+opencode-sessions-explorer-search-text { "q": "git push", "surface": "tool_audit" }
+```
+
+## Related Docs
+
+- Tool catalog: [tools.md](tools.md)
+- Compact result format: [response-format.md](response-format.md)
+- Four-layer architecture: [architecture.md](architecture.md)
+- Search and grep workflow: [../guides/search-and-grep.md](../guides/search-and-grep.md)
+- Export and maintenance workflow: [../guides/export-and-maintenance.md](../guides/export-and-maintenance.md)
+- Troubleshooting: [../support/troubleshooting.md](../support/troubleshooting.md)