opencode-sessions-explorer 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -7,6 +7,24 @@ 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
+- Documentation restructure: organized the `docs/` tree (getting started, install, guides,
+  reference, support, maintainers) and reworked `README.md` into a concise entry point that
+  links out to the new docs.
+- Generalized the product descriptions and wording across `package.json`, `README.md`, and
+  the docs tree so they are non-parochial (removed machine- and author-specific phrasing).
+  No runtime or API changes.
+
 ## [0.1.0] - 2026-06-13
 
 Initial public release on npm.

package/README.md

@@ -1,62 +1,46 @@
 # opencode-sessions-explorer
 
-> Access to every prior OpenCode session on your machine — recall, search/grep, and historical analysis via 18 LLM-discoverable tools (17 read-only + one explicit unarchive write).
-
 [![CI](https://github.com/iamironz/opencode-sessions-explorer/actions/workflows/ci.yml/badge.svg)](https://github.com/iamironz/opencode-sessions-explorer/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/opencode-sessions-explorer.svg)](https://www.npmjs.com/package/opencode-sessions-explorer)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-`opencode-sessions-explorer` is an [OpenCode](https://opencode.ai) plugin that exposes your local SQLite session history (`~/.local/share/opencode/opencode.db`) to the running LLM as a set of named tools. Ask in natural language — *"Where in my history did I mention X?"*, *"How much did I spend on Claude this month?"*, *"Which tool fails most for me?"* — and the LLM picks the right tool automatically.
-
----
+Recall, search, and analyze every past [OpenCode](https://opencode.ai) session —
+18 LLM-discoverable tools over the OpenCode SQLite database.
 
-## Install
+`opencode-sessions-explorer` is an OpenCode plugin that exposes your OpenCode
+session history (`~/.local/share/opencode/opencode.db`) to the running model as a
+set of named tools — 17 read-only (recall, search/grep, cost/usage analysis) plus
+one explicit `unarchive-session` write. Ask in natural language and the model picks
+the right tool automatically; nothing leaves your device.
 
-This is published on npm as
-[`opencode-sessions-explorer`](https://www.npmjs.com/package/opencode-sessions-explorer).
-Add it to the `plugin` array in your OpenCode config — OpenCode auto-installs npm
-plugins with Bun on startup (cached under `~/.cache/opencode/node_modules/`), so
-there is no separate `npm install` step:
+Example questions it answers:
 
-```jsonc
-// ~/.config/opencode/opencode.json
-{
-  "$schema": "https://opencode.ai/config.json",
-
-  "plugin": [
-    "opencode-sessions-explorer"
-  ],
-
-  "permission": {
-    "external_directory": {
-      "~/.local/share/opencode/**": "allow"
-    }
-  }
-}
+```text
+Where in my history did I mention the export codec?
+Summarize session ses_… and list the files it touched.
+How much did I spend on Claude this month, by project?
+Which tool fails most for me, and what errors keep recurring?
+Unarchive session ses_… so I can open it again.
 ```
 
-To pin a version, use `"opencode-sessions-explorer@0.1.0"`.
+## Compatibility
 
-Then **quit and restart OpenCode**. All 18 tools auto-register.
+| Area | Support | Notes |
+| --- | --- | --- |
+| 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%` |
 
-The `external_directory` permission is required because the OpenCode DB lives
-outside your project workspace; you grant read+write to it explicitly (the lone
-write is `unarchive-session` — see [Writes](#writes)).
+## Quick Start
 
-### From source (dev)
-
-To run a local checkout, point the `plugin` entry at the built file instead of
-the npm package:
+1. Add the plugin and grant access to the OpenCode data directory:
 
 ```jsonc
 // ~/.config/opencode/opencode.json
 {
   "$schema": "https://opencode.ai/config.json",
-
-  "plugin": [
-    "file:///absolute/path/to/opencode-sessions-explorer/dist/plugin.js"
-  ],
-
+  "plugin": ["opencode-sessions-explorer"],
   "permission": {
     "external_directory": {
       "~/.local/share/opencode/**": "allow"
@@ -65,239 +49,128 @@ the npm package:
 }
 ```
 
-Run `bun run build` first to produce `dist/plugin.js`. For active development you
-can point at `src/plugin.ts` directly — Bun loads TS without a build step. Then
-**quit and restart OpenCode**.
+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.
 
----
-
-## First run
-
-The text-search tools (`search-text`, `grep-session`) need a filesystem export of your session content (used by `ck` for indexed search). The export contains both raw replay files and derived channel views used for cleaner default recall:
-
-```bash
-# One-time, ~30-60s for typical histories
-bunx opencode-sessions-explorer-bulk-export
-
-# After upgrading from pre-channel versions, backfill curated recall views
-bunx opencode-sessions-explorer-bulk-export --reset
-
-# Optional: build the semantic search index (~5 h for ~150k parts; resumable)
-cd ~/.local/share/opencode-sessions-explorer && ck --index .
-```
-
-After the first export, the plugin auto-syncs new parts on every search call (3-4s budget).
-
-Run the health check anytime:
+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. 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
 ```
 
----
-
-## External dependencies
-
-| Dependency       | Required for                                                   | Install                                                                                            |
-| ---------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| **Bun ≥ 1.0**        | Everything (the plugin uses `bun:sqlite`)                        | OpenCode ships Bun. If running CLIs standalone: <https://bun.sh>                                     |
-| **OpenCode DB**      | Everything (the source of truth)                               | Auto-created at `~/.local/share/opencode/opencode.db` by OpenCode. Override path via `$OPENCODE_SESSIONS_EXPLORER_DB` |
-| **`ck` CLI ≥ 0.7**     | `search-text` + `grep-session` (the other 16 tools work without)   | `cargo install ck-search` — see <https://github.com/BeaconBay/ck>                                       |
-
-If `ck` is missing, `search-text`/`grep-session` cleanly return `CK_NOT_FOUND`; the other 16 tools work fine.
-
----
-
-## The 18 tools
-
-### Recall
-
-| Tool                                | Answers                                                                |
-| ----------------------------------- | ---------------------------------------------------------------------- |
-| `opencode-sessions-explorer-current-session`   | *"What session am I in / who am I / where am I"*                         |
-| `opencode-sessions-explorer-get-session`       | *"Tell me about session ses_…"* (metadata + counts + children)             |
-| `opencode-sessions-explorer-session-summary`   | *"Summarize session ses_…"* (prompts, files, tools, errors, cost)          |
-| `opencode-sessions-explorer-session-timeline`  | *"Walk through session ses_… chronologically"*                             |
-| `opencode-sessions-explorer-get-message`       | *"Fetch message msg_… with its parts"*                                     |
-| `opencode-sessions-explorer-get-part`          | *"Show me part prt_…"* (+ optional tool-output dereference)                |
-| `opencode-sessions-explorer-session-genealogy` | *"Parent chain / subagents spawned from ses_…"*                            |
-
-### Browse / filter
-
-| Tool                                   | Answers                                                                         |
-| -------------------------------------- | ------------------------------------------------------------------------------- |
-| `opencode-sessions-explorer-list-sessions`        | *"List my recent sessions / sessions using agent X / sessions in directory Y"*    |
-| `opencode-sessions-explorer-search-sessions-meta` | *"Find sessions costing more than $5 / title matching X / under directory Y"*     |
-
-### Content search
-
-| Tool                                | Answers                                                                                          |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------ |
-| `opencode-sessions-explorer-search-text`       | *"Where in my history did I mention X?"* (curated session-first recall by default; `surface:'forensics'` for raw replay) |
-| `opencode-sessions-explorer-grep-session`      | *"Inside session ses_…, grep for X"* (curated channels by default; raw via `surface:'forensics'`)                   |
-| `opencode-sessions-explorer-search-tool-calls` | *"Every time I ran git push / every read that errored / all my Jira MCP calls"*                    |
-
-### Analysis
-
-| Tool                                    | Answers                                                |
-| --------------------------------------- | ------------------------------------------------------ |
-| `opencode-sessions-explorer-cost-by-project`       | *"Cost by project / directory / agent / model"*          |
-| `opencode-sessions-explorer-cost-by-period`        | *"OpenCode spend per day / week / month"*                |
-| `opencode-sessions-explorer-list-tool-failures`    | *"Which tool fails most / what errors keep recurring"*   |
-| `opencode-sessions-explorer-list-repeated-prompts` | *"Have I asked this question before / repeated prompts"* |
-
-### Health
-
-| Tool                       | Answers                                              |
-| -------------------------- | ---------------------------------------------------- |
-| `opencode-sessions-explorer-db-stats` | *"Is the local OpenCode DB healthy / any schema drift"* |
-
-### Mutate (the one write tool)
+1. Materialize the search export once:
 
-| Tool                                       | Answers                                                                   |
-| ------------------------------------------ | ------------------------------------------------------------------------- |
-| `opencode-sessions-explorer-unarchive-session` | *"Unarchive / restore an archived session ses_…"* (clears `time_archived` + resurfaces) |
-
-This is the **only** tool that writes to `opencode.db`; see [Writes](#writes) below.
-
-### Search Surfaces
-
-`search-text` and `grep-session` are curated by default. They preserve raw recall by reference instead of dumping every matching byte.
-
-| Surface | Default channels | Use when |
-| ------- | ---------------- | -------- |
-| `recall` | `conversation`, `session-summary` | normal "have I discussed X?" memory questions |
-| `debug_trace` | `conversation`, `session-summary`, `tool-error`, `tool-input-summary` | errors, stack traces, failed commands, logs |
-| `tool_audit` | `tool-input-summary`, `tool-error` | tool invocation history |
-| `code` | `conversation`, `session-summary`, `code-touch`, `patch-summary`, `tool-input-summary` | files, symbols, diffs, code paths |
-| `forensics` | `raw` | exhaustive raw replay, including tool output and reasoning |
-
----
-
-## Compact result format (columnar + interning)
-
-List-shaped results (`list-sessions`, `search-sessions-meta`, `search-tool-calls`, `session-timeline`, `cost-by-project`, `cost-by-period`, `list-tool-failures`, `list-repeated-prompts`, `search-text`, `grep-session`, `session-genealogy` ancestors) are returned as a **lossless columnar table** instead of an array-of-objects. This removes per-row key repetition and interns high-repetition values (model, directory, agent, project, channel, event type) into a small dictionary — measured **−33% to −56%** payload size with no information removed.
-
-```jsonc
-"sessions": {
-  "cols": ["id","title","agent","model","directory", "...", "archived"],
-  "dict": { "agent": ["build","executor-gpt"], "model": [{"id":"gpt-5.5-fast", "...": "..."}], "directory": ["/Users/you"] },
-  "rows": [ ["ses_…","Title…",0,0,0, "…", true] ]
-}
-```
-
-**Decode rule (single):** a cell in a column whose name is a key in `dict` is an integer index into `dict[col]`; otherwise it is the literal value. Scalars next to the table (`has_more`, `mode`, `suppressed`, …) are unchanged. A reference decoder ships as `decodeTable()` in `src/lib/table.ts`. The envelope (`ok`/`data`/`meta`/`warnings`) is unchanged.
-
----
-
-## Architecture (4 layers)
-
-```
-L1  SQLite DB                  ← source of truth (read-only access)
-    ↓ (delta sync, runs before every search call)
-L2  opencode-sessions-explorer/ tree      ← raw by-session replay + derived by-channel views
-    ↓                             (conversation, session-summary, tool-error,
-    ↓                             code-touch, tool-output, reasoning, etc.)
-L3  .ck/ index                 ← BM25 (Tantivy) + embeddings (bge-small),
-    ↓                             auto-incremental via blake3 chunk hash
-L4  enriched response          ← every hit re-fetches session/part metadata
-                                  from SQLite for accuracy
+```bash
+bunx opencode-sessions-explorer-bulk-export
 ```
 
-All **reads** go through a shared `bun:sqlite` handle opened `readonly: true` + `PRAGMA query_only = 1`; any accidental write on that path throws. The single exception is the `unarchive-session` tool — see [Writes](#writes).
-
----
-
-## Writes
-
-17 of the 18 tools are strictly read-only. The lone exception is **`unarchive-session`**, which restores an archived session so it can be opened and prompted again.
-
-- **Why a direct DB write?** OpenCode exposes no archive/unarchive endpoint that can *clear* the flag: its HTTP `UpdatePayload` types `time.archived` as a finite number and the handler ignores `undefined`, so a clear/`null` can't be sent over the wire (verified against v1.15.12 source). `opencode session` only offers `list`/`delete`. A direct DB write is the only mechanism.
-- **What it writes.** It clears `time_archived` **and** refreshes `time_updated` to now, in one `UPDATE`, via a separate short-lived read-write connection (`src/lib/db-write.ts`); the shared read handle stays read-only. It **always restores to a usable state** — including an already-active-but-buried session (e.g. one unarchived by an older build that didn't refresh `time_updated`) — so it is not a silent no-op on active sessions; it is idempotent in effect (active + at the top). Only a non-existent id is rejected (`NOT_FOUND`).
-- **Why bump `time_updated`?** OpenCode's app/server load the session list ordered by `time_updated DESC` with a default `LIMIT 100` **per directory**. A long-archived session keeps an old `time_updated`, so merely clearing `time_archived` leaves it buried below that window — the app never loads it and prompting fails with *"Unable to retrieve session"*. Refreshing `time_updated` resurfaces the restored session at the top, where the app loads it (this is also the intuitive meaning of "restore").
-- **Permission.** No extra permission is needed: the existing `external_directory: { "~/.local/share/opencode/**": "allow" }` rule already covers read+write access to the DB file.
-- **After restoring.** An external write emits no `session.updated` event, so an already-open OpenCode window won't update live. **Reload/restart the window** and open OpenCode in the session's **directory** (sessions are listed per directory). Because `time_updated` is refreshed, the restored session then appears at the top of the list.
-
----
-
-## Configuration
-
-All paths are env-overridable:
-
-| Env var                                | Default                                                          | Purpose                                          |
-| -------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------ |
-| `OPENCODE_SESSIONS_EXPLORER_DB`                   | `$XDG_DATA_HOME/opencode/opencode.db` (Linux/Mac) / `%LOCALAPPDATA%/opencode/opencode.db` (Win) | Path to the OpenCode SQLite DB                   |
-| `OPENCODE_SESSIONS_EXPLORER_EXPORT_ROOT`          | `$XDG_DATA_HOME/opencode-sessions-explorer`                          | Where to materialize searchable session content  |
-| `OPENCODE_SESSIONS_EXPLORER_TOOL_OUTPUT_DIR`      | `$XDG_DATA_HOME/opencode/tool-output`                              | Whitelist root for `get-part` dereference         |
-| `OPENCODE_SESSIONS_EXPLORER_CK_BIN`               | `ck` (via $PATH)                                                 | Override `ck` binary location                      |
-
----
-
-## Privacy
-
-The plugin exposes **all your prior OpenCode conversations** to the LLM — including tool inputs/outputs that may contain credentials, API tokens, file contents, and other sensitive material. Consider:
-
-- The `search-text` and `grep-session` tools redact common secret shapes (`AKIA…`, `ghp_…`, `sk-…`, JWTs, bearer tokens, etc.) in returned snippets by default. Pass `redact:false` only for explicit local forensics.
-- All access is **local read-only** — no data leaves your machine via this plugin.
-- The `external_directory` permission rule is required because the DB lives outside your project workspace; you grant it explicitly.
-
----
-
-## Development
+1. (Optional) Build the `ck` index from the export root, not the repo root:
 
 ```bash
-# Install
-bun install
-
-# Typecheck
-bun run typecheck
-
-# Build to dist/
-bun run build
-
-# Run the rehearsal harness (hermetic by default; live DB via OPENCODE_SESSIONS_EXPLORER_LIVE=1)
-bun test
-
-# End-to-end verifier (compares tool output vs ground-truth SQL; needs a live DB)
-bun tests/verify-end-to-end.ts
-
-# Plugin invocation (sanity)
-bun src/plugin.ts
+cd ~/.local/share/opencode-sessions-explorer
+ck --index .  # run in the export root, not the repo root
 ```
 
-### Repo layout
+1. Run the health probe again to confirm the export and optional index state:
 
+```bash
+bunx opencode-sessions-explorer-check-deps
 ```
-src/
-├── plugin.ts                  default Plugin export — registers all 18 tools
-├── tools/
-│   ├── index.ts               registry { "opencode-sessions-explorer-…": toolDefinition, … }
-│   ├── current-session.ts     1 per tool — named const, not default export
-│   ├── unarchive-session.ts   the only write tool (clears time_archived + resurfaces)
-│   └── (16 more)
-├── lib/                       shared internals (db, db-write, ck, export, decode, …)
-└── bin/
-    ├── bulk-export.ts         materializes session content for ck
-    ├── dedupe-export.ts       maintenance
-    └── check-deps.ts          install health probe
-
-tests/
-├── rehearsal.test.ts          read-only probes (hermetic fixture by default; live DB opt-in)
-├── unarchive.test.ts          write-path probes (run against a throwaway DB copy)
-├── helpers.ts
-├── fixtures.json              session IDs used by the rehearsal probes
-└── verify-end-to-end.ts       smoke verifier — runs every tool + compares vs SQL
-```
-
----
-
-## Status
 
-- 18 tools registered (17 read-only + 1 unarchive write)
-- Published on npm as [`opencode-sessions-explorer`](https://www.npmjs.com/package/opencode-sessions-explorer)
-- Test suite passing **hermetically by default** against a synthetic fixture DB (live-DB probes opt-in via `OPENCODE_SESSIONS_EXPLORER_LIVE=1`; unarchive write-path probes run against a throwaway DB copy)
-- 17/17 end-to-end tool verification passing (unarchive probed via the zero-mutation NOT_FOUND path)
-- Local and npm plugin installs verified end-to-end
+The `external_directory` permission is required because the OpenCode database lives
+outside your project workspace. For installing from source, version pinning, and the
+full first-run walkthrough, see [docs/install.md](docs/install.md) and
+[docs/getting-started.md](docs/getting-started.md).
+
+## Features
+
+### Recall and Navigation
+
+- **Find your bearings.** `current-session`, `get-session`, and `session-summary`
+  report where you are and what a session contains.
+- **Walk a session.** `session-timeline` and `session-genealogy` trace the
+  chronology and the parent/subagent chain.
+- **Drill into detail.** `get-message` and `get-part` fetch individual messages and
+  parts, with optional tool-output dereference.
+- **Browse and filter.** `list-sessions` and `search-sessions-meta` find sessions by
+  recency, agent, directory, title, or cost.
+- See [docs/guides/recall-and-navigation.md](docs/guides/recall-and-navigation.md).
+
+### Content Search and Grep
+
+- **Search across history.** `search-text` answers "where did I mention X?" with
+  curated session-first recall by default.
+- **Grep one session.** `grep-session` scans a single session's curated channels,
+  with raw replay via `surface:'forensics'`.
+- **Audit tool calls.** `search-tool-calls` finds every invocation of a command,
+  every read that errored, or all calls to a given MCP.
+- See [docs/guides/search-and-grep.md](docs/guides/search-and-grep.md).
+
+### Cost and Usage Analysis
+
+- **Spend by dimension.** `cost-by-project` breaks cost down by project, directory,
+  agent, or model.
+- **Spend over time.** `cost-by-period` reports OpenCode spend per day, week, or month.
+- **Failure and repetition signals.** `list-tool-failures` and
+  `list-repeated-prompts` surface recurring errors and duplicated questions.
+- See [docs/guides/cost-and-usage-analysis.md](docs/guides/cost-and-usage-analysis.md).
+
+### Export and Maintenance
+
+- **One-time export.** `bulk-export` materializes searchable session content for `ck`.
+- **Stay current.** The plugin auto-syncs new parts before each search call; rebuild
+  the optional semantic index when you want embeddings.
+- **Health probe.** `check-deps` and the `db-stats` tool report dependency and schema
+  health.
+- See [docs/guides/export-and-maintenance.md](docs/guides/export-and-maintenance.md).
+
+### Archived Session Recovery
+
+- **Restore a buried session.** `unarchive-session` is the one write tool — it clears
+  `time_archived` **and** refreshes `time_updated` so the session resurfaces at the
+  top of the per-directory list and can be opened again.
+- See [docs/guides/manage-archived-sessions.md](docs/guides/manage-archived-sessions.md).
+
+### Privacy and Safety
+
+- **Local and read-only by default.** 17 of 18 tools never write; no data leaves your
+  device through this plugin.
+- **Secret redaction.** `search-text` / `grep-session` redact common secret shapes in
+  snippets by default; `get-part` dereference is path-guarded to a whitelist root.
+- See [docs/reference/configuration.md](docs/reference/configuration.md) and
+  [.github/SECURITY.md](.github/SECURITY.md).
+
+## Documentation
+
+Docs home: [docs/README.md](docs/README.md)
+
+| Goal | Doc |
+| --- | --- |
+| Install and first run | [docs/install.md](docs/install.md), [docs/getting-started.md](docs/getting-started.md) |
+| Recall and navigation | [docs/guides/recall-and-navigation.md](docs/guides/recall-and-navigation.md) |
+| Search and grep | [docs/guides/search-and-grep.md](docs/guides/search-and-grep.md) |
+| Cost and usage analysis | [docs/guides/cost-and-usage-analysis.md](docs/guides/cost-and-usage-analysis.md) |
+| Export and maintenance | [docs/guides/export-and-maintenance.md](docs/guides/export-and-maintenance.md) |
+| Archived session recovery | [docs/guides/manage-archived-sessions.md](docs/guides/manage-archived-sessions.md) |
+| Tool reference | [docs/reference/tools.md](docs/reference/tools.md) |
+| Configuration | [docs/reference/configuration.md](docs/reference/configuration.md) |
+| Search surfaces | [docs/reference/search-surfaces.md](docs/reference/search-surfaces.md) |
+| Response format | [docs/reference/response-format.md](docs/reference/response-format.md) |
+| Architecture | [docs/reference/architecture.md](docs/reference/architecture.md) |
+| Troubleshooting | [docs/support/troubleshooting.md](docs/support/troubleshooting.md) |
+| Maintainer and release | [docs/maintainers/development.md](docs/maintainers/development.md), [docs/maintainers/release.md](docs/maintainers/release.md) |
+| Change log | [CHANGELOG.md](CHANGELOG.md) |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

package/dist/plugin.js

@@ -13633,7 +13633,7 @@ function safe(fn) {
 
 // src/tools/db-stats.ts
 var dbStats = tool({
-  description: "opencode-sessions-explorer: health probe for the local OpenCode SQLite database (~/.local/share/opencode/opencode.db). " + "Returns migration head, table counts (session/message/part), json1 extension status, busy_timeout, and any schema-drift warnings. " + "Run this when troubleshooting: any opencode-sessions-explorer-* tool returning SCHEMA_DRIFT, after an OpenCode upgrade, when verifying the DB is reachable, or when answering 'is opencode.db healthy / what schema is it on / how many sessions are stored'.",
+  description: "opencode-sessions-explorer: health probe for the OpenCode SQLite database (~/.local/share/opencode/opencode.db). " + "Returns migration head, table counts (session/message/part), json1 extension status, busy_timeout, and any schema-drift warnings. " + "Run this when troubleshooting: any opencode-sessions-explorer-* tool returning SCHEMA_DRIFT, after an OpenCode upgrade, when verifying the DB is reachable, or when answering 'is opencode.db healthy / what schema is it on / how many sessions are stored'.",
   args: {},
   async execute() {
     return runWithEnvelope("db_stats", 8, async () => {

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)