opencode-manager 0.3.1 → 0.4.1

package/PROJECT-SUMMARY.md

@@ -5,15 +5,47 @@ Overview
 --------
 - Purpose: Inspect, filter, and clean OpenCode metadata stored on disk.
 - Scope: Lists projects and sessions from local storage; supports filtering, search, interactive selection and deletion, and quick navigation between views.
-- UI: Terminal UI built with @opentui/react.
+- Dual interface: Terminal UI (TUI) built with @opentui/react for interactive use, plus a Commander-based CLI for scripting and automation.
 
 Architecture
 ------------
-- Entry: `opencode/src/opencode-tui.tsx` — main TUI app and panels.
-- Data layer: `opencode/src/lib/opencode-data.ts` — reads/writes metadata JSON, computes derived fields, formatting helpers.
-- Scripts: `opencode/package.json` → `bun run tui` runs the app.
-- CLI wrapper: `opencode/manage_opencode_projects.py` preserves the legacy entry point, resolves Bun (`--bun` overrides PATH), sets `--root` (defaults to `~/.local/share/opencode`), and forwards any extra args after `--` directly to the TUI.
-- Spec diff script: `opencode/opencode-gen.sh` shells out to `opencode generate`, saves the JSON spec under `~/repos/research/opencode/opencode-<version>-spec.json`, and diffs it against the previous snapshot (prefers `delta`, falls back to `diff`).
+The codebase follows a dual-mode architecture with shared libraries:
+
+### Entry Points
+- `src/bin/opencode-manager.ts` — Main entrypoint; routes to CLI or TUI based on subcommand.
+  - CLI subcommands: `projects`, `sessions`, `chat`, `tokens` → dynamic import of CLI module
+  - TUI mode: no subcommand, or explicit `tui` subcommand → dynamic import of TUI module
+
+### CLI Module (`src/cli/`)
+- `index.ts` — Commander program with global options (`--root`, `--format`, `--limit`, `--sort`, `--yes`, `--dry-run`, `--quiet`, `--clipboard`, `--backup-dir`); exports `runCLI(args)`.
+- `commands/` — Subcommand implementations:
+  - `projects.ts` — `list`, `delete` with dry-run/backup support
+  - `sessions.ts` — `list`, `delete`, `rename`, `move`, `copy` 
+  - `chat.ts` — `list`, `show`, `search` with clipboard support
+  - `tokens.ts` — `session`, `project`, `global` token summaries
+  - `tui.ts` — Launches TUI from CLI context
+- `formatters/` — Output formatters:
+  - `json.ts` — JSON with envelope (`{ok, data, meta}`)
+  - `ndjson.ts` — Newline-delimited JSON for streaming
+  - `table.ts` — Column-aligned tables with truncation
+- `output.ts` — Format selector routing by `--format` flag
+- `errors.ts` — Exit codes (0-4), error classes, validation helpers
+- `resolvers.ts` — ID resolution with exact/prefix matching
+- `backup.ts` — Pre-deletion backup to timestamped directories
+
+### TUI Module (`src/tui/`)
+- `app.tsx` — Main TUI app with Projects, Sessions, Chat panels
+- `index.tsx` — Exports `launchTUI(options)`, `bootstrap(args)`
+- `args.ts` — TUI-specific arg parsing (`--root`, `--help`)
+
+### Shared Libraries (`src/lib/`)
+- `opencode-data.ts` — Data layer: load/save metadata, compute tokens, filtering, formatting
+- `search.ts` — Fuzzy search via fast-fuzzy (sessions) and tokenized search (projects)
+- `clipboard.ts` — Cross-platform clipboard (`pbcopy`/`xclip`)
+
+### Other Files
+- `manage_opencode_projects.py` — Legacy wrapper; routes CLI/TUI via `src/bin/opencode-manager.ts`
+- `opencode-gen.sh` — Spec diff script for OpenCode JSON specs
 
 Metadata Layout & Helpers
 -------------------------
@@ -37,6 +69,8 @@ Key Features
   - Rename sessions inline (Shift+R) with validation.
   - Move sessions to another project (M) with project selector.
   - Copy sessions to another project (P) with new session ID generation.
+  - View chat history (V) with message navigation and clipboard support.
+  - Search chat content (F) across sessions with fuzzy matching.
 - Projects ↔ Sessions workflow
   - Pressing Enter on a project jumps to the Sessions tab with the project filter set; status text confirms the active filter.
   - `C` clears the filter (and notifies the user) so global searches go back to all sessions.
@@ -53,6 +87,7 @@ Key Features
 
 Work Completed
 --------------
+### TUI Features
 - Switched Projects list labels to show path instead of project ID; kept ID in the details panel.
 - Sessions list uses session title prominently; added title to details; updated onSelect/Enter status lines to show title and ID.
 - Redesigned Help screen into two columns with color-coded sections and key chips; removed wall-of-text effect.
@@ -69,36 +104,79 @@ Work Completed
 - Added session move feature (M): select target project, relocate session JSON, update projectID field.
 - Added session copy feature (P): select target project, create new session with generated ID, preserve original.
 
+### CLI Implementation (Phase 1-4)
+- Created Commander-based CLI with global options and subcommand routing.
+- Refactored entrypoint to route CLI vs TUI via dynamic imports.
+- Extracted shared libraries (`clipboard.ts`, `search.ts`) from TUI for CLI reuse.
+- Implemented output formatters: JSON with envelope, NDJSON for streaming, table with truncation.
+- Projects commands: `list` (with `--missing-only`, `--search`), `delete` (with `--dry-run`, `--backup-dir`).
+- Sessions commands: `list` (with `--project`, `--search`, fuzzy matching), `delete`, `rename`, `move`, `copy`.
+- Chat commands: `list` (with `--include-parts`), `show` (by `--message` or `--index`, with `--clipboard`), `search`.
+- Tokens commands: `session`, `project`, `global` summaries with breakdown tables.
+- Error handling with typed exit codes (0-4) and consistent error formatting.
+- ID resolution helpers with exact and prefix matching.
+- Pre-deletion backup to timestamped directories.
+- Comprehensive test suite: 350+ tests covering formatters, commands, resolvers, errors, exit codes.
+
 How To Run
 ----------
-- Zero-install via npm: `bunx opencode-manager [--root /path/to/storage]` (preferred).
-- Local dev: `bun run tui [-- --root /path/to/storage]`.
-- Legacy launcher: `./manage_opencode_projects.py [--root PATH] [--bun /path/to/bun] [-- ...extra TUI args]` keeps older automation working while delegating to Bun.
-- Keys:
-  - Global: `Tab`/`1`/`2` switch tabs, `/` search, `X` clear search, `R` reload, `Q` quit, `?` help
-  - Projects: `Space` select, `A` select all, `M` toggle missing, `D` delete, `Enter` view sessions
-  - Sessions: `Space` select, `S` sort, `D` delete, `Y` copy ID, `Shift+R` rename, `M` move, `P` copy, `C` clear filter
-- Optional tmux usage (when permitted): `tmux new -s opencode-tui 'bun run tui'`
-- CLI help: `bun run tui -- --help` (or `bunx opencode-manager -- --help`, or `manage_opencode_projects.py -- --help`) prints the built-in usage block with key bindings.
+### TUI Mode (Interactive)
+- Zero-install: `bunx opencode-manager [--root /path/to/storage]` (preferred)
+- Local dev: `bun run tui [-- --root /path/to/storage]`
+- Legacy launcher: `./manage_opencode_projects.py [--bun /path/to/bun]`
+- TUI help: `bunx opencode-manager --help` shows key bindings
+
+### CLI Mode (Scripting)
+- Projects: `bunx opencode-manager projects list --format json`
+- Sessions: `bunx opencode-manager sessions list --project <id> --limit 10`
+- Chat: `bunx opencode-manager chat search --query "fix bug" --format ndjson`
+- Tokens: `bunx opencode-manager tokens global --format table`
+- Delete with backup: `bunx opencode-manager sessions delete --session <id> --yes --backup-dir ./backups`
+- Dry run: `bunx opencode-manager projects delete --id <id> --dry-run`
+
+### Global CLI Options
+- `--root <path>` — Metadata store root (default: `~/.local/share/opencode`)
+- `--format <json|ndjson|table>` — Output format (default: `table`)
+- `--limit <n>` — Max records (default: 200)
+- `--sort <updated|created>` — Sort order (default: `updated`)
+- `--yes` — Skip confirmation for destructive ops
+- `--dry-run` — Preview changes without executing
+- `--quiet` — Suppress non-essential output
+- `--clipboard` — Copy output to clipboard
+- `--backup-dir <path>` — Backup before deletion
+
+### Exit Codes
+- 0: Success
+- 1: Internal error
+- 2: Usage/validation error (missing `--yes`, bad args)
+- 3: Resource not found (invalid project/session/message ID)
+- 4: File operation error (backup/delete failure)
+
+### TUI Keys
+- Global: `Tab`/`1`/`2` switch tabs, `/` search, `X` clear search, `R` reload, `Q` quit, `?/H` help
+- Projects: `Space` select, `A` select all, `M` toggle missing, `D` delete, `Enter` view sessions, `Esc` clear selection
+- Sessions: `Space` select, `A` select all, `S` sort, `V` view chat, `F` search chats, `Shift+R` rename, `M` move, `P` copy, `Y` copy ID, `C` clear filter, `D` delete, `Enter` details, `Esc` clear selection
+
+### Optional
+- tmux: `tmux new -s opencode-manager 'bun run tui'`
 
 Packaging & Publish Checklist
 -----------------------------
-1. Install dependencies with `bun install` (Bun v1.1+ only).
+1. Install dependencies with `bun install` (Bun v1.3+ only).
 2. Type-check via `bun run typecheck` (runs `tsc --noEmit`).
 3. Update the version in `package.json` as needed.
 4. Run `npm publish` (package exposes the Bun-native `opencode-manager` bin with public access).
 
 Outstanding Recommendations (Not Yet Implemented)
 -------------------------------------------------
-- UI polish
+- TUI polish
   - Colorize project state in list labels (e.g., green for present, red for missing, gray for unknown).
   - Show a small timestamp snippet for Projects rows (created).
   - Add tiny icons or color accents to distinguish created vs updated descriptions in Sessions.
   - Add per-view mini legends with colored key chips under the panels (Projects/Sessions), consistent with the Help styling.
-  - Show filtered counts (e.g., “Showing X of Y”).
+  - Show filtered counts (e.g., "Showing X of Y").
 - Search enhancements
-  - Optional fuzzy matching; toggle to include/exclude `directory` in Sessions/Projects search for more control.
-  - Persist search and sort preferences per tab (and optionally per project filter) during the app run.
+  - Optional fuzzy matching toggle in TUI; persist search and sort preferences per tab.
   - Save last-used search/sort to a small state file and restore on next launch.
 - Accessibility & layout
   - Ensure all active/inactive/focused states have adequate contrast and consistent highlight styles.
@@ -106,10 +184,12 @@ Outstanding Recommendations (Not Yet Implemented)
 - Performance
   - Debounce UI reactions to large search queries; short-circuit expensive filters when query is empty.
 - Testing
-  - Add unit coverage for opencode-data helpers (formatting, parsing, sorting).
-  - Add basic snapshot/E2E tests for rendering key panels and Help using a headless renderer (if available for @opentui).
-- Packaging/Docs
-  - Add a README section specific to the TUI tool, with a short demo, common actions, and troubleshooting.
+  - Add integration tests for CLI commands with real fixture data.
+  - Add basic snapshot/E2E tests for TUI rendering (if headless renderer available for @opentui).
+- CLI enhancements
+  - Shell completion scripts (bash/zsh/fish).
+  - `--json-lines` alias for `--format ndjson` compatibility.
+  - Template/profile support for common option combinations.
 
 Notes
 -----

package/README.md

@@ -3,33 +3,48 @@
 
 # OpenCode Metadata Manager
 
-Terminal UI for inspecting, filtering, and pruning OpenCode metadata stored on disk. The app is written in TypeScript, runs on Bun, and renders with [`@opentui/react`](https://github.com/open-tui/opentui).
+Terminal UI for inspecting, filtering, and pruning OpenCode metadata stored on disk. The app is written in TypeScript, runs on Bun, and renders with [`@opentui/react`](https://github.com/sst/opentui).
 
 ## Screenshots
 
 <p align="center">
-  <img src="home-screen.png" alt="OpenCode Metadata Manager home screen showing projects and sessions" width="85%" />
+  <img src="oc-manager.png" alt="OpenCode Metadata Manager home screen showing projects and sessions" width="85%" />
   <br />
   <em>Main workspace with Projects (left) and Sessions (right) panels.</em>
 </p>
 
 <p align="center">
-  <img src="help-screen.png" alt="OpenCode Metadata Manager help overlay" width="85%" />
+  <img src="oc-manager-home.png" alt="OpenCode Metadata Manager home screen alternate view" width="85%" />
   <br />
-  <em>Contextual help overlay with key bindings and tips.</em>
+  <em>Alternate home view with project/session context.</em>
+</p>
+
+<p align="center">
+  <img src="oc-manager-search.png" alt="OpenCode Metadata Manager search view" width="85%" />
+  <br />
+  <em>Fuzzy search across sessions with ranked results.</em>
+</p>
+
+<p align="center">
+  <img src="oc-manager-cli.png" alt="OpenCode Metadata Manager CLI output" width="85%" />
+  <br />
+  <em>Scriptable CLI output for listing projects and sessions.</em>
 </p>
 
 ## Features
 - List both OpenCode projects and sessions from a local metadata root.
 - Filter by "missing only", bulk-select, and delete metadata safely.
 - Jump from a project directly to its sessions and keep contextual filters.
-- Global search bar (`/` to focus, `Enter` to apply, `Esc` or `X` to clear).
+- **Fuzzy search** across session titles and metadata (`/` to focus, results ranked by relevance).
+- **View session chat history** with full conversation context (`V` to open viewer).
+- **Search across all chat content** in sessions within a project (`F` to search).
 - Rename sessions inline (`Shift+R`) with title validation.
 - Move sessions between projects (`M`) preserving session ID.
 - Copy sessions to other projects (`P`) with new session ID generation.
 - Rich help overlay with live key hints (`?` or `H`).
 - Zero-install via `bunx` so even CI shells can run it without cloning.
 - **Token counting**: View token usage per session, per project, and globally.
+- **Experimental SQLite backend**: Faster queries for large stores via `--experimental-sqlite`.
 
 ## Token Counting
 
@@ -56,7 +71,7 @@ The TUI displays token telemetry from OpenCode's stored message data at three le
 - Large datasets are handled with lazy computation to avoid UI freezes.
 
 ## Requirements
-- [Bun](https://bun.sh) **1.1.0+** (developed/tested on 1.2.x).
+- [Bun](https://bun.sh) **1.3.0+** (developed/tested on 1.3.x).
 - A node-compatible terminal (truecolor improves readability but is optional).
 
 ## Installation
@@ -73,6 +88,13 @@ bunx opencode-manager --help
 The repository ships with a focused `.gitignore`, keeping `node_modules/`, caches, and logs out of Git history.
 
 ## Usage
+
+The manager provides both a Terminal UI (TUI) and a scriptable CLI interface.
+
+### Terminal UI (TUI)
+
+The TUI is the default interface when no subcommand is provided:
+
 ```bash
 # Preferred: zero-install command
 bunx opencode-manager --root ~/.local/share/opencode
@@ -85,9 +107,363 @@ bun run tui -- --root ~/.local/share/opencode
 ```
 
 Keyboard reference:
-- **Global**: `Tab`/`1`/`2` switch tabs, `/` search, `X` clear search, `R` reload, `Q` quit, `?` help.
-- **Projects**: `Space` toggle selection, `A` select all, `M` missing-only filter, `D` delete, `Enter` jump to Sessions.
-- **Sessions**: `Space` select, `S` toggle sort, `D` delete, `Y` copy ID, `Shift+R` rename, `M` move to project, `P` copy to project, `C` clear filter.
+- **Global**: `Tab`/`1`/`2` switch tabs, `/` search (fuzzy), `X` clear search, `R` reload, `Q` quit, `?/H` help.
+- **Projects**: `Space` toggle selection, `A` select all, `M` missing-only filter, `D` delete, `Enter` jump to Sessions, `Esc` clear selection.
+- **Sessions**: `Space` select, `A` select all, `S` toggle sort, `V` view chat, `F` search chats, `D` delete, `Y` copy ID, `Shift+R` rename, `M` move, `P` copy, `C` clear filter, `Enter` details, `Esc` clear selection.
+- **Chat Search**: Type query + `Enter` to search, `Up/Down` navigate, `Enter` opens result, `Esc` close.
+- **Chat Viewer**: `Esc` close, `Up/Down` navigate, `PgUp/PgDn` jump 10, `Home/End` first/last, `Y` copy message.
+
+### Command Line Interface (CLI)
+
+The CLI provides scriptable access to all management operations. Use subcommands to list, search, and modify metadata.
+
+#### Global Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `-r, --root <path>` | `~/.local/share/opencode` | Root path to OpenCode metadata store |
+| `-f, --format <fmt>` | `table` | Output format: `json`, `ndjson`, or `table` |
+| `-l, --limit <n>` | `200` | Maximum number of records to return |
+| `--sort <order>` | `updated` | Sort order: `updated` or `created` |
+| `-y, --yes` | `false` | Skip confirmation prompts for destructive operations |
+| `-n, --dry-run` | `false` | Preview changes without executing |
+| `-q, --quiet` | `false` | Suppress non-essential output |
+| `-c, --clipboard` | `false` | Copy output to clipboard |
+| `--backup-dir <path>` | — | Directory for backup copies before deletion |
+| `--experimental-sqlite` | `false` | Use SQLite database instead of JSONL files (experimental) |
+| `--db <path>` | `~/.local/share/opencode/opencode.db` | Path to SQLite database (implies `--experimental-sqlite`) |
+| `--sqlite-strict` | `false` | Fail on any SQLite warning or malformed data |
+| `--force-write` | `false` | Wait for SQLite write locks to clear before failing |
+
+#### Experimental SQLite Support
+
+OpenCode can store metadata in SQLite databases. The CLI supports this mode with `--experimental-sqlite` or by pointing directly at a database with `--db <path>`.
+
+Key behaviors:
+- Read operations open SQLite in readonly mode by default.
+- Write operations may fail if OpenCode has the database locked. Use `--force-write` to wait for the lock to clear.
+- When malformed rows are encountered, the CLI logs a warning and returns partial results. Use `--sqlite-strict` to fail fast.
+
+When to use SQLite vs JSONL:
+- Use SQLite when your OpenCode installation no longer writes JSONL files or when you want faster list/search operations on large stores.
+- Use JSONL when you need maximal compatibility with older OpenCode versions or when you want to avoid SQLite locking.
+
+Known limitations and differences:
+- Schema changes in OpenCode may break compatibility. The CLI validates required tables/columns and warns if the schema is incomplete.
+- SQLite records use virtual file paths (e.g., `sqlite:project:proj_123`) instead of JSON file paths.
+- Results may differ slightly from JSONL when extra SQLite-only rows exist.
+
+Examples:
+```bash
+# List projects using the default SQLite database
+opencode-manager projects list --experimental-sqlite
+
+# List sessions using an explicit SQLite database path
+opencode-manager sessions list --db ~/.local/share/opencode/opencode.db
+
+# Fail fast on malformed SQLite data
+opencode-manager projects list --db ~/.local/share/opencode/opencode.db --sqlite-strict
+
+# Wait for locks before destructive operations
+opencode-manager projects delete --id proj_missing --db ~/.local/share/opencode/opencode.db --yes --force-write
+```
+
+#### Commands Overview
+
+```
+opencode-manager
+├── projects
+│   ├── list      List projects (--missing-only, --search)
+│   └── delete    Delete project metadata (--id, --yes, --dry-run, --backup-dir)
+├── sessions
+│   ├── list      List sessions (--project, --search)
+│   ├── delete    Delete session metadata (--session, --yes, --dry-run, --backup-dir)
+│   ├── rename    Rename a session (--session, --title)
+│   ├── move      Move session to another project (--session, --to)
+│   └── copy      Copy session to another project (--session, --to)
+├── chat
+│   ├── list      List messages in a session (--session, --include-parts)
+│   ├── show      Show a specific message (--session, --message or --index, --clipboard)
+│   └── search    Search chat content across sessions (--query, --project)
+├── tokens
+│   ├── session   Show token usage for a session (--session)
+│   ├── project   Show token usage for a project (--project)
+│   └── global    Show global token usage
+└── tui           Launch the Terminal UI
+```
+
+#### TUI Subcommand
+
+The `tui` subcommand explicitly launches the Terminal UI. This is equivalent to running `opencode-manager` with no subcommand:
+
+```bash
+# These are equivalent:
+opencode-manager
+opencode-manager tui
+opencode-manager tui --root ~/.local/share/opencode
+```
+
+Use the explicit `tui` subcommand when you want to be clear about intent in scripts or when combining with other options. Note that `tui --help` shows the TUI help screen (key bindings), not Commander CLI help.
+
+#### Help System
+
+The manager uses a dual help system depending on context:
+
+| Command | Help Type | Content |
+|---------|-----------|---------|
+| `opencode-manager --help` | TUI help | Key bindings and TUI usage |
+| `opencode-manager -h` | TUI help | Same as `--help` |
+| `opencode-manager tui --help` | TUI help | Key bindings (routes to TUI help) |
+| `opencode-manager projects --help` | CLI help | Commander subcommand help |
+| `opencode-manager sessions --help` | CLI help | Commander subcommand help |
+| `opencode-manager chat --help` | CLI help | Commander subcommand help |
+| `opencode-manager tokens --help` | CLI help | Commander subcommand help |
+
+**Why?** The root command defaults to launching the TUI, so `--help` shows TUI-relevant information (key bindings). CLI subcommands use standard Commander.js help showing options and usage.
+
+To see all CLI subcommands, use any subcommand with `--help`:
+
+```bash
+# Shows TUI key bindings
+opencode-manager --help
+
+# Shows CLI subcommand help with options
+opencode-manager projects --help
+opencode-manager projects list --help
+```
+
+#### Output Format Examples
+
+The CLI supports three output formats via `--format`:
+
+**Table (default)** — Human-readable columnar output:
+
+```bash
+$ bunx opencode-manager projects list --limit 3
+
+   #  State  Path                                                Project ID                Created
+----  -----  --------------------------------------------------  ------------------------  ----------------
+   1    ✓    /home/user/repos/my-app                             a1b2c3d4e5f6g7h8i9j0k1l2  2026-01-04 09:20
+   2    ✓    /home/user/repos/api-server                         b2c3d4e5f6g7h8i9j0k1l2m3  2026-01-03 14:15
+   3    ✗    /home/user/repos/deleted-project                    c3d4e5f6g7h8i9j0k1l2m3n4  2025-12-28 10:30
+```
+
+**JSON** — Structured output with metadata envelope:
+
+```bash
+$ bunx opencode-manager sessions list --project prj_abc123 --format json --limit 2
+
+{
+  "ok": true,
+  "data": [
+    {
+      "index": 1,
+      "sessionId": "sess_xyz789",
+      "projectId": "prj_abc123",
+      "directory": "/home/user/repos/my-app",
+      "title": "Refactor auth module",
+      "version": "1.1.4",
+      "updatedAt": "2026-01-05T14:32:00.000Z",
+      "createdAt": "2026-01-03T09:15:00.000Z"
+    },
+    {
+      "index": 2,
+      "sessionId": "sess_uvw456",
+      "projectId": "prj_abc123",
+      "directory": "/home/user/repos/my-app",
+      "title": "Add unit tests",
+      "version": "1.1.4",
+      "updatedAt": "2026-01-04T16:45:00.000Z",
+      "createdAt": "2026-01-02T11:20:00.000Z"
+    }
+  ],
+  "meta": {
+    "count": 2,
+    "limit": 2
+  }
+}
+```
+
+JSON output auto-detects your terminal: pretty-printed with indentation when output goes to a TTY, compact single-line when piped to another command.
+
+The `meta` object contains:
+- `count` — Number of items in the `data` array
+- `limit` — The limit that was applied (if `--limit` was specified)
+
+**NDJSON** — Newline-delimited JSON for streaming/piping:
+
+```bash
+$ bunx opencode-manager sessions list --format ndjson --limit 2
+
+{"index":1,"sessionId":"ses_abc123","projectId":"prj_xyz789","title":"Feature implementation","createdAt":"2026-01-06T10:30:00.000Z"}
+{"index":2,"sessionId":"ses_def456","projectId":"prj_xyz789","title":"Bug fix session","createdAt":"2026-01-06T11:15:00.000Z"}
+```
+
+Each line is a complete JSON object, ideal for piping to `jq` or line-by-line processing. For single-record commands like `tokens global`, NDJSON outputs one line with the same structure as the JSON `data` field.
+
+**Piping examples:**
+
+```bash
+# Count sessions per project
+bunx opencode-manager sessions list --format ndjson | jq -s 'group_by(.projectId) | map({project: .[0].projectId, count: length})'
+
+# Get all session IDs as plain text
+bunx opencode-manager sessions list --format json | jq -r '.data[].sessionId'
+
+# Export chat history to file
+bunx opencode-manager chat list --session sess_xyz789 --include-parts --format json > chat-export.json
+
+# Dry-run delete to preview affected files
+bunx opencode-manager projects delete --id prj_old --dry-run --format json
+```
+
+#### Token Output Format
+
+Token commands (`tokens session`, `tokens project`, `tokens global`) return structured summaries of token usage.
+
+**Session tokens** — Single session summary with `kind` discriminator:
+
+```bash
+$ bunx opencode-manager tokens session --session sess_xyz789 --format json
+
+# When token data is available (kind: "known"):
+{
+  "ok": true,
+  "data": {
+    "kind": "known",
+    "tokens": {
+      "input": 12500,
+      "output": 8750,
+      "reasoning": 2100,
+      "cacheRead": 4200,
+      "cacheWrite": 950,
+      "total": 28500
+    }
+  }
+}
+
+# When token data is unavailable (kind: "unknown"):
+{
+  "ok": true,
+  "data": {
+    "kind": "unknown",
+    "reason": "no_messages"
+  }
+}
+```
+
+The `reason` field indicates why tokens are unavailable:
+- `"missing"` — Session metadata file not found
+- `"parse_error"` — Token data couldn't be parsed
+- `"no_messages"` — Session has no messages with token data
+
+**Project/Global tokens** — Aggregate summary across multiple sessions:
+
+```bash
+$ bunx opencode-manager tokens project --project prj_abc123 --format json
+
+{
+  "ok": true,
+  "data": {
+    "total": {
+      "kind": "known",
+      "tokens": { "input": 125000, "output": 98000, "reasoning": 32000, "cacheRead": 15000, "cacheWrite": 6500, "total": 276500 }
+    },
+    "knownOnly": { "input": 125000, "output": 98000, "reasoning": 32000, "cacheRead": 15000, "cacheWrite": 6500, "total": 276500 },
+    "unknownSessions": 2
+  }
+}
+```
+
+Aggregate summary fields:
+- `total` — Combined `TokenSummary` (same structure as session tokens)
+- `knownOnly` — Token breakdown from sessions with available data only (omitted if all unknown)
+- `unknownSessions` — Count of sessions where token data was unavailable
+
+**Note:** The `tokens` commands require exact IDs (no prefix matching). Use full session/project IDs as shown in `sessions list` or `projects list` output.
+
+#### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Usage error (missing required options, invalid arguments) |
+| 3 | Resource not found (invalid project/session/message ID) |
+| 4 | File operation error (backup or delete failure) |
+
+#### ID Resolution
+
+Most commands accept ID prefixes for convenience. The CLI will match the prefix to a unique ID:
+
+```bash
+# Full ID
+opencode-manager sessions delete --session sess_01JGNPE16DT1JX1YA8KTPMDRW3
+
+# Prefix match (if unique)
+opencode-manager sessions delete --session sess_01JGN
+
+# Ambiguous prefix (fails with error listing matches)
+opencode-manager sessions delete --session sess_01
+# Error: Multiple sessions match prefix 'sess_01': sess_01JGN..., sess_01ABC...
+```
+
+**Commands supporting prefix matching:**
+- `projects delete --id`
+- `sessions delete --session`, `sessions rename --session`, `sessions move --session`, `sessions copy --session`
+- `sessions move --to`, `sessions copy --to` (project ID)
+- `chat list --session`, `chat show --session`
+- `chat show --message` (also supports 1-based `--index`)
+
+**Commands requiring exact IDs:**
+- `tokens session --session` — requires full session ID
+- `tokens project --project` — requires full project ID
+
+#### Clipboard Support
+
+The `--clipboard` flag (or `Y` key in the TUI) copies content to the system clipboard. Platform support:
+
+| Platform | Tool Required | Notes |
+|----------|---------------|-------|
+| **macOS** | None | Uses built-in `pbcopy` |
+| **Linux** | `xclip` | Install via `apt install xclip` or equivalent |
+| **Windows** | — | Not currently supported |
+
+On Linux, if `xclip` is not installed, clipboard operations will fail silently in the TUI or show an error message in the CLI.
+
+#### Delete Semantics
+
+Delete commands (`projects delete`, `sessions delete`) remove **metadata files only**:
+
+| Command | Deletes | Preserves |
+|---------|---------|-----------|
+| `projects delete` | Project metadata (`storage/project/<id>.json`) | Sessions, messages, parts |
+| `sessions delete` | Session metadata (`storage/sessions/<projectId>.json` entry) | Message and part files |
+
+**Safety features:**
+
+- **Confirmation required** — Destructive operations require `--yes` flag or interactive confirmation:
+  ```bash
+  # Will prompt for confirmation (interactive)
+  opencode-manager projects delete --id prj_abc123
+  
+  # Skip confirmation (scripts)
+  opencode-manager projects delete --id prj_abc123 --yes
+  ```
+
+- **Dry-run preview** — Use `--dry-run` to see what would be deleted without making changes:
+  ```bash
+  opencode-manager sessions delete --session sess_xyz789 --dry-run
+  # Output shows files that would be affected
+  ```
+
+- **Backup before delete** — Use `--backup-dir` to copy files before deletion:
+  ```bash
+  opencode-manager projects delete --id prj_abc123 --backup-dir ./backups --yes
+  # Creates backup, then deletes original
+  ```
+
+**Note:** Session deletion leaves associated chat message files intact. To fully remove a session's data, you would need to manually delete the message files from `storage/message/<sessionId>/`.
 
 ## Development Workflow
 1. Install dependencies with `bun install`.
@@ -98,11 +474,24 @@ Keyboard reference:
 ### Project Structure
 ```
 src/
-  bin/opencode-manager.ts   # Bun-native CLI shim exposed as the bin entry
-  opencode-tui.tsx          # Main TUI implementation (panels, search, help)
-manage_opencode_projects.py # Legacy Python launcher for backwards compatibility
-opencode-gen.sh             # Spec snapshot helper script
-PROJECT-SUMMARY.md          # Extended design notes & roadmap
+  bin/opencode-manager.ts       # Bun-native CLI shim exposed as the bin entry
+  cli/
+    index.ts                    # Commander program with global options
+    commands/                   # Subcommand implementations (projects, sessions, chat, tokens)
+    resolvers.ts                # ID prefix resolution helpers
+  lib/
+    opencode-data.ts            # JSONL file-based data access
+    opencode-data-sqlite.ts     # SQLite backend (experimental)
+    opencode-data-provider.ts   # Unified DataProvider abstraction
+  tui/
+    app.tsx                     # Main TUI implementation (panels, search, help)
+    index.tsx                   # TUI entrypoint with launchTUI(), parseArgs(), bootstrap()
+tests/
+  fixtures/                     # Test data (JSONL and SQLite fixtures)
+  lib/                          # Unit tests for data modules
+  cli/                          # CLI integration tests
+manage_opencode_projects.py     # Legacy Python launcher for backwards compatibility
+PROJECT-SUMMARY.md              # Extended design notes & roadmap
 ```
 
 ## Packaging & Publish