opencode-anthropic-fix 0.0.14

package/.planning/codebase/INTEGRATIONS.md

@@ -0,0 +1,215 @@
+# External Integrations
+
+**Analysis Date:** 2026-02-07
+
+## APIs & External Services
+
+**Anthropic OAuth (Primary Integration):**
+
+- **Purpose:** OAuth 2.0 authentication for Claude Pro/Max subscriptions and API key creation
+- **SDK/Client:** Native `fetch()` — no SDK wrapper
+- **Auth:** OAuth 2.0 with PKCE (Authorization Code flow)
+- **Client ID:** `9d1c250a-e61b-44d9-88ed-5944d1962f5e` (hardcoded in `lib/config.mjs:71`)
+- **PKCE Library:** `@openauthjs/openauth/pkce` — `generatePKCE()` function
+
+**Anthropic OAuth Endpoints (used in `index.mjs` and `cli.mjs`):**
+
+| Endpoint                                                        | Method        | Purpose                               | Used In                                        |
+| --------------------------------------------------------------- | ------------- | ------------------------------------- | ---------------------------------------------- |
+| `https://claude.ai/oauth/authorize`                             | GET (browser) | OAuth authorization (Max plan)        | `index.mjs:21`                                 |
+| `https://console.anthropic.com/oauth/authorize`                 | GET (browser) | OAuth authorization (Console/API key) | `index.mjs:21`                                 |
+| `https://console.anthropic.com/v1/oauth/token`                  | POST          | Token exchange & refresh              | `index.mjs:42`, `index.mjs:536`, `cli.mjs:140` |
+| `https://api.anthropic.com/api/oauth/claude_cli/create_api_key` | POST          | Create API key from OAuth token       | `index.mjs:1028`                               |
+| `https://api.anthropic.com/api/oauth/usage`                     | GET           | Fetch per-account usage quotas        | `cli.mjs:168`                                  |
+
+**Anthropic Messages API (Proxied):**
+
+- **Purpose:** The plugin intercepts and transforms requests to the Anthropic Messages API
+- **Endpoint:** `/v1/messages` — detected via URL pathname matching
+- **Transforms applied:**
+  - Adds `?beta=true` query parameter (`index.mjs:296`)
+  - Sets `Authorization: Bearer {access_token}` header
+  - Adds `anthropic-beta: oauth-2025-04-20,interleaved-thinking-2025-05-14` header
+  - Sets `user-agent: claude-cli/2.1.2 (external, cli)`
+  - Removes `x-api-key` header
+  - Prefixes tool names with `mcp_` in request body
+  - Strips `mcp_` prefix from tool names in response stream
+  - Rewrites `OpenCode` → `Claude Code` and `opencode` → `Claude` in system prompts
+
+**OAuth Flow Parameters:**
+
+- Redirect URI: `https://console.anthropic.com/oauth/code/callback`
+- Scopes: `org:create_api_key user:profile user:inference`
+- PKCE: S256 challenge method
+- Grant types: `authorization_code` (initial), `refresh_token` (renewal)
+
+## Data Storage
+
+**Databases:**
+
+- None — All storage is local filesystem JSON files
+
+**File Storage (Local):**
+
+- `~/.config/opencode/anthropic-accounts.json` — Multi-account OAuth token storage
+  - Written by: `lib/storage.mjs` (`saveAccounts()`)
+  - Read by: `lib/storage.mjs` (`loadAccounts()`)
+  - Format: JSON with version, accounts array, activeIndex
+  - Security: File mode `0o600` (owner read/write only)
+  - Write strategy: Atomic (temp file + rename via `randomBytes(6)` suffix)
+  - Auto-deduplication by refresh token on load
+  - Auto `.gitignore` maintained in config directory
+
+- `~/.config/opencode/anthropic-auth.json` — Plugin configuration
+  - Written by: `lib/config.mjs` (`saveConfig()`)
+  - Read by: `lib/config.mjs` (`loadConfig()`)
+  - Format: JSON with strategy, health scores, token bucket settings
+  - Security: File mode `0o600`
+  - Write strategy: Atomic (temp file + rename via PID suffix)
+
+**Caching:**
+
+- In-memory only — Health scores (`HealthScoreTracker`), token buckets (`TokenBucketTracker`), and stats deltas (`Map<string, StatsDelta>`) are held in memory during the process lifetime
+- No external cache service
+
+## Authentication & Identity
+
+**Auth Provider:** Anthropic OAuth 2.0 (custom implementation)
+
+**Implementation:**
+
+- PKCE Authorization Code flow for initial login
+- Refresh token rotation for session maintenance
+- Multi-account support (up to 10 accounts, `MAX_ACCOUNTS` in `lib/accounts.mjs:35`)
+- Single-flight refresh protection (prevents concurrent refresh races in `index.mjs:659`)
+- Automatic account switching on auth failure, rate limit, or quota exhaustion
+
+**Token Lifecycle:**
+
+1. User visits authorization URL in browser
+2. User pastes authorization code back to CLI
+3. Plugin exchanges code for access + refresh tokens
+4. Access token used for API requests (short-lived)
+5. Refresh token used to obtain new access tokens when expired
+6. Plugin persists tokens to `anthropic-accounts.json`
+7. Also syncs primary account to OpenCode's `auth.json` for compatibility
+
+**Account Selection Strategies (configurable in `lib/rotation.mjs`):**
+
+- `sticky` — Stay on current account until it fails (default)
+- `round-robin` — Rotate through accounts on every request
+- `hybrid` — Score-based selection using health scores + token buckets + freshness
+
+## OpenCode Plugin SDK Integration
+
+**SDK:** `@opencode-ai/plugin` ^0.4.45 (via `@opencode-ai/sdk` 0.4.19)
+
+**Plugin hooks used:**
+
+- `auth.loader(getAuth, provider)` — Custom auth loader that intercepts fetch requests
+- `auth.methods[]` — Three auth methods (OAuth Max, OAuth Console/API Key, Manual API Key)
+- `experimental.chat.system.transform` — Prepends Claude Code identity to system prompts
+
+**SDK Client API used:**
+
+- `client.auth.set()` — Persist OAuth tokens to OpenCode's auth store (`index.mjs:580`)
+- `client.tui?.showToast()` — Display notifications in OpenCode TUI (`index.mjs:638`)
+
+## Monitoring & Observability
+
+**Error Tracking:**
+
+- None — No external error tracking service
+
+**Logs:**
+
+- Debug logging to `stderr` via `console.error()` when `config.debug` is enabled
+- Prefix: `[opencode-anthropic-auth]`
+- Controlled by: `OPENCODE_ANTHROPIC_DEBUG=1` env var or `debug: true` in config file
+
+**TUI Toasts:**
+
+- Account usage notifications (which account is active)
+- Account switch notifications (when switching due to rate limit/failure)
+- Error toasts (disabled accounts, auth failures)
+- Configurable: `toasts.quiet` suppresses non-error toasts, `toasts.debounce_seconds` rate-limits toast frequency
+
+## CI/CD & Deployment
+
+**Hosting:**
+
+- npm registry (`opencode-anthropic-auth` package, currently v0.0.13)
+- Self-installed to user machine (not a hosted service)
+
+**CI Pipeline:**
+
+- GitHub Actions: `.github/workflows/publish.yml`
+- Trigger: Manual (`workflow_dispatch`) with optional version bump type
+- Steps: Checkout → Node.js 24 → `npm install` → `npm publish --access public`
+- Auth: `NPM_TOKEN` secret
+
+**Publishing Flow:**
+
+1. Run `bun script/publish.ts [patch|minor|major]` locally
+2. Bumps version in `package.json`, commits, pushes
+3. Triggers GitHub Actions workflow via `gh workflow run`
+4. CI publishes to npm
+
+## Environment Configuration
+
+**Required env vars:**
+
+- None required for runtime (config file is optional, defaults are sane)
+
+**Optional env vars (runtime):**
+
+- `OPENCODE_ANTHROPIC_STRATEGY` — Override account selection strategy
+- `OPENCODE_ANTHROPIC_DEBUG` — Toggle debug logging
+- `OPENCODE_ANTHROPIC_QUIET` — Suppress non-error toasts
+- `XDG_CONFIG_HOME` — Override config/storage directory base
+- `NO_COLOR` — Disable ANSI colors in CLI output
+
+**CI/CD env vars:**
+
+- `NPM_TOKEN` — npm authentication for publishing (GitHub Actions secret)
+- `NODE_AUTH_TOKEN` — Mapped from `NPM_TOKEN` in workflow
+
+**Secrets location:**
+
+- OAuth tokens stored in `~/.config/opencode/anthropic-accounts.json` (file mode 0o600)
+- `.gitignore` auto-maintained in config directory to prevent accidental commits
+- No secrets in repository
+
+## Webhooks & Callbacks
+
+**Incoming:**
+
+- OAuth callback URL: `https://console.anthropic.com/oauth/code/callback` (handled by Anthropic's servers; user pastes the returned code manually)
+
+**Outgoing:**
+
+- None
+
+## SSE Stream Processing
+
+**The plugin processes Server-Sent Events (SSE) streams from the Anthropic API:**
+
+- Strips `mcp_` prefix from tool names in response stream (`index.mjs:489`)
+- Extracts token usage from `message_start` and `message_delta` events (`index.mjs:317-341`)
+- Detects mid-stream account errors for proactive switching (`index.mjs:368-392`)
+- Implemented via `ReadableStream` wrapping of response body (`index.mjs:465-492`)
+
+## Rate Limit & Backoff System
+
+**The plugin implements sophisticated rate limit handling across accounts:**
+
+- Categorizes errors: `AUTH_FAILED`, `QUOTA_EXHAUSTED`, `RATE_LIMIT_EXCEEDED` (`lib/backoff.mjs`)
+- Respects `Retry-After` headers (both seconds and HTTP-date formats)
+- Escalating backoffs for quota exhaustion: 1m → 5m → 30m → 2h
+- Fixed backoffs: Auth failure 5s, Rate limit 30s
+- Health scoring with passive recovery (configurable in `lib/rotation.mjs`)
+- Token bucket for request gating (`lib/rotation.mjs`)
+
+---
+
+_Integration audit: 2026-02-07_

package/.planning/codebase/STACK.md

@@ -0,0 +1,160 @@
+# Technology Stack
+
+**Analysis Date:** 2026-02-07
+
+## Languages
+
+**Primary:**
+
+- JavaScript (ESM / `.mjs`) — All application code, no TypeScript compilation step
+
+**Secondary:**
+
+- TypeScript — Single publish script only (`script/publish.ts`, run via Bun)
+- Python — MITM proxy debugging tool (`.mitm/dump_anthropic.py`, not part of core)
+
+**Key Decision:** Pure JavaScript with JSDoc type annotations throughout. No `.ts` source files in the main codebase — types are expressed via `@typedef` and `@param` JSDoc comments. This avoids a TypeScript compilation step while still providing IDE type checking.
+
+## Runtime
+
+**Environment:**
+
+- Node.js ≥ 20 (build target: `node20` in `scripts/build.mjs`)
+- Development machine: Node.js v25.4.0
+
+**Package Manager:**
+
+- npm 11.7.0
+- Lockfile: `package-lock.json` (present via `node_modules/`)
+
+## Frameworks
+
+**Core:**
+
+- `@opencode-ai/plugin` ^0.4.45 (devDependency) — OpenCode plugin SDK; defines the `Plugin` interface the project exports
+- `@openauthjs/openauth` ^0.4.3 (runtime dependency) — PKCE code generation for OAuth flows (`generatePKCE`)
+
+**Testing:**
+
+- Vitest ^4.0.18 — Test runner and assertion library
+- Config: implicit (no `vitest.config.*` found; uses defaults with `*.test.mjs` pattern)
+
+**Build/Dev:**
+
+- esbuild ^0.27.3 — Bundles plugin + CLI into self-contained single files in `dist/`
+- Husky ^9.1.7 — Git hooks (pre-commit, pre-push)
+- lint-staged ^16.2.7 — Run lint/format on staged files only
+- ESLint ^10.0.0 — Linting (flat config at `eslint.config.mjs`)
+- Prettier ^3.8.1 — Formatting (config at `.prettierrc`)
+
+## Key Dependencies
+
+**Critical (runtime):**
+
+- `@openauthjs/openauth` 0.4.3 — Only runtime dependency; provides `generatePKCE` for OAuth PKCE flow. Everything else is Node.js built-ins.
+
+**Critical (dev/build):**
+
+- `@opencode-ai/plugin` 0.4.45 — Defines the `Plugin` type interface. Transitive dependency: `@opencode-ai/sdk` 0.4.19 (provides `createOpencodeClient`)
+- `esbuild` 0.27.3 — Bundles both entry points into zero-dependency single files
+
+**Infrastructure:**
+
+- `husky` 9.1.7 — Git hooks
+- `lint-staged` 16.2.7 — Pre-commit quality gates
+
+## Configuration
+
+**Environment Variables (runtime):**
+
+- `OPENCODE_ANTHROPIC_STRATEGY` — Override account selection strategy (`sticky`, `round-robin`, `hybrid`)
+- `OPENCODE_ANTHROPIC_DEBUG` — Enable debug logging (`1`/`true` or `0`/`false`)
+- `OPENCODE_ANTHROPIC_QUIET` — Suppress non-error toasts (`1`/`true` or `0`/`false`)
+- `XDG_CONFIG_HOME` — Override config directory (default: `~/.config`)
+- `NO_COLOR` — Disable ANSI color output in CLI
+
+**Config Files (user-facing, not in repo):**
+
+- `~/.config/opencode/anthropic-auth.json` — Plugin configuration (strategy, health scores, token bucket, etc.)
+- `~/.config/opencode/anthropic-accounts.json` — Multi-account storage (OAuth tokens, stats, rate limit state)
+
+**Build Config:**
+
+- `eslint.config.mjs` — ESLint flat config (ECMAScript 2025, Node.js globals, vitest test globals)
+- `.prettierrc` — Prettier (120 char width, double quotes, trailing commas, 2-space indent)
+- `scripts/build.mjs` — esbuild config (ESM format, node20 target, node:\* external)
+
+**Git Hooks:**
+
+- `.husky/pre-commit` — Runs `npm test` then `npx lint-staged`
+- `.husky/pre-push` — Runs `npm test`, `npx prettier --check .`, `npx eslint .`
+
+## Build System
+
+**Build command:** `npm run build` → `node scripts/build.mjs`
+
+**Outputs:**
+
+- `dist/opencode-anthropic-auth-plugin.js` — Bundled plugin (60KB, single file, no deps)
+- `dist/opencode-anthropic-auth-cli.mjs` — Bundled CLI (37KB, single file, no deps)
+
+**Build characteristics:**
+
+- ESM format (`"format": "esm"`)
+- All dependencies bundled except `node:*` builtins
+- Target: Node.js 20+
+- Both outputs are self-contained — no `node_modules` needed at runtime
+
+**Install modes:**
+
+- `npm run install:link` — Symlinks source files for development (live editing)
+- `npm run install:copy` — Copies built artifacts for stable deployment
+- `npm run uninstall` — Removes both plugin and CLI
+
+**Install targets:**
+
+- Plugin → `~/.config/opencode/plugin/opencode-anthropic-auth-plugin.js`
+- CLI → `~/.local/bin/opencode-anthropic-auth`
+
+## NPM Scripts
+
+| Script         | Command                                          | Purpose                          |
+| -------------- | ------------------------------------------------ | -------------------------------- |
+| `build`        | `node scripts/build.mjs`                         | Bundle plugin + CLI with esbuild |
+| `test`         | `vitest run`                                     | Run all tests once               |
+| `test:watch`   | `vitest`                                         | Run tests in watch mode          |
+| `lint`         | `eslint .`                                       | Lint all files                   |
+| `lint:fix`     | `eslint --fix .`                                 | Lint and auto-fix                |
+| `format`       | `prettier --write .`                             | Format all files                 |
+| `format:check` | `prettier --check .`                             | Check formatting                 |
+| `install:link` | `node scripts/install.mjs link`                  | Dev install (symlinks)           |
+| `install:copy` | `npm run build && node scripts/install.mjs copy` | Production install (copy)        |
+| `uninstall`    | `node scripts/install.mjs uninstall`             | Remove installed files           |
+| `prepare`      | `husky`                                          | Set up git hooks                 |
+
+## Platform Requirements
+
+**Development:**
+
+- Node.js ≥ 20
+- npm (for dependency management)
+- macOS/Linux (install scripts use Unix paths and symlinks)
+- Optional: Bun (for `script/publish.ts` only)
+
+**Production/Runtime:**
+
+- Node.js ≥ 20
+- OpenCode installed and configured
+- No external dependencies at runtime (everything is bundled)
+
+**Publishing:**
+
+- GitHub Actions (`.github/workflows/publish.yml`)
+- npm registry (`npm publish --access public`)
+- Node.js 24 in CI
+- Bun for version bump script (`script/publish.ts`)
+- GitHub CLI (`gh`) for triggering workflow
+
+---
+
+_Stack analysis: 2026-02-07_

package/.planning/codebase/STRUCTURE.md

@@ -0,0 +1,244 @@
+# Codebase Structure
+
+**Analysis Date:** 2026-02-07
+
+## Directory Layout
+
+```
+opencode-anthropic-auth/
+├── index.mjs                  # Plugin entry point (AnthropicAuthPlugin)
+├── index.test.mjs             # Plugin tests
+├── cli.mjs                    # CLI entry point (standalone account management)
+├── cli.test.mjs               # CLI tests
+├── package.json               # Package manifest (v0.0.13)
+├── package-lock.json          # Lockfile
+├── eslint.config.mjs          # ESLint configuration
+├── .gitignore                 # Git ignore rules
+├── lib/                       # Shared library modules
+│   ├── accounts.mjs           # AccountManager class (runtime coordinator)
+│   ├── accounts.test.mjs      # AccountManager tests
+│   ├── backoff.mjs            # Error classification and backoff calculation
+│   ├── backoff.test.mjs       # Backoff tests
+│   ├── config.mjs             # Configuration loading, validation, defaults
+│   ├── config.test.mjs        # Config tests
+│   ├── rotation.mjs           # Selection algorithms (sticky/round-robin/hybrid)
+│   ├── rotation.test.mjs      # Rotation tests
+│   ├── storage.mjs            # Disk persistence (atomic JSON read/write)
+│   └── storage.test.mjs       # Storage tests
+├── scripts/                   # Build and install tooling
+│   ├── build.mjs              # esbuild bundler (→ dist/)
+│   └── install.mjs            # Plugin/CLI installer (link/copy/uninstall)
+├── script/                    # Release automation
+│   └── publish.ts             # Bun script: version bump + trigger GitHub workflow
+├── dist/                      # Build output (gitignored)
+│   ├── opencode-anthropic-auth-plugin.js   # Bundled plugin (single file)
+│   └── opencode-anthropic-auth-cli.mjs     # Bundled CLI (single file)
+├── .github/
+│   └── workflows/
+│       └── publish.yml        # GitHub Actions: npm publish on manual trigger
+├── .husky/                    # Git hooks
+│   ├── pre-commit             # Runs lint-staged
+│   └── pre-push               # Runs tests
+├── .mitm/                     # mitmproxy debugging tools (gitignored)
+│   ├── dump_anthropic.py      # Proxy script for capturing API traffic
+│   ├── capture.jsonl          # Captured request/response data
+│   ├── flows                  # mitmproxy flow data
+│   └── mitmdump.log           # Proxy logs
+└── .planning/                 # GSD planning documents
+    └── codebase/              # Architecture analysis (this directory)
+```
+
+## Directory Purposes
+
+**Root (`/`):**
+
+- Purpose: Entry points and project configuration
+- Contains: Two main entry points (`index.mjs`, `cli.mjs`), their co-located tests, and standard Node.js config files
+- Key files: `index.mjs` (plugin), `cli.mjs` (CLI), `package.json`
+
+**`lib/`:**
+
+- Purpose: Shared library modules used by both plugin and CLI
+- Contains: Five module pairs (source + test), each with a single clear responsibility
+- Key files: `accounts.mjs` (core runtime), `config.mjs` (configuration), `storage.mjs` (persistence), `rotation.mjs` (algorithms), `backoff.mjs` (error handling)
+
+**`scripts/`:**
+
+- Purpose: Build and installation tooling
+- Contains: `build.mjs` (esbuild bundler), `install.mjs` (symlink/copy installer)
+- Key files: `build.mjs` produces single-file bundles in `dist/`
+
+**`script/`:**
+
+- Purpose: Release automation
+- Contains: `publish.ts` — Bun-based version bump and GitHub workflow trigger
+- Note: Uses Bun APIs (not Node.js), separate from `scripts/` directory
+
+**`dist/`:**
+
+- Purpose: Built artifacts (gitignored)
+- Contains: Two self-contained bundled files (plugin + CLI) with all dependencies except Node.js builtins
+- Generated: `npm run build`
+- Committed: No
+
+**`.github/workflows/`:**
+
+- Purpose: CI/CD automation
+- Contains: `publish.yml` — manual-trigger npm publish workflow
+- Note: No CI testing workflow; tests run locally via pre-push hook
+
+**`.husky/`:**
+
+- Purpose: Git hooks via husky
+- Contains: `pre-commit` (lint-staged), `pre-push` (test runner)
+
+**`.mitm/`:**
+
+- Purpose: Development debugging tools for API traffic inspection
+- Contains: mitmproxy scripts and captured traffic data
+- Committed: No (gitignored)
+
+## Key File Locations
+
+**Entry Points:**
+
+- `index.mjs`: Plugin entry — exports `AnthropicAuthPlugin` function
+- `cli.mjs`: CLI entry — exports `main()` and individual command functions, self-executes when run directly
+
+**Configuration:**
+
+- `package.json`: Package manifest, scripts, dependencies
+- `eslint.config.mjs`: ESLint flat config with Node.js globals
+- `lib/config.mjs`: Runtime config loading from `~/.config/opencode/anthropic-auth.json`
+
+**Core Logic:**
+
+- `lib/accounts.mjs`: `AccountManager` class — central account coordinator
+- `lib/rotation.mjs`: `HealthScoreTracker`, `TokenBucketTracker`, `selectAccount()` — selection algorithms
+- `lib/backoff.mjs`: `isAccountSpecificError()`, `parseRateLimitReason()`, `calculateBackoffMs()` — error classification
+- `lib/storage.mjs`: `loadAccounts()`, `saveAccounts()` — atomic JSON persistence
+
+**Testing:**
+
+- `index.test.mjs`: Plugin integration tests
+- `cli.test.mjs`: CLI command tests
+- `lib/accounts.test.mjs`: AccountManager unit tests
+- `lib/rotation.test.mjs`: Selection algorithm tests
+- `lib/backoff.test.mjs`: Error classification/backoff tests
+- `lib/config.test.mjs`: Config loading tests
+- `lib/storage.test.mjs`: Storage persistence tests
+
+**Build & Deploy:**
+
+- `scripts/build.mjs`: esbuild bundler producing `dist/` artifacts
+- `scripts/install.mjs`: Plugin/CLI installer (link for dev, copy for prod)
+- `script/publish.ts`: Release script (version bump + publish trigger)
+
+## Naming Conventions
+
+**Files:**
+
+- Source modules: `kebab-case.mjs` (e.g., `storage.mjs`, `config.mjs`)
+- Test files: `<module>.test.mjs` co-located with source (e.g., `lib/storage.test.mjs`)
+- Entry points: `index.mjs` (plugin), `cli.mjs` (CLI)
+- Build artifacts: `opencode-anthropic-auth-{plugin,cli}.{js,mjs}`
+
+**Directories:**
+
+- `lib/`: Shared library modules (lowercase)
+- `scripts/`: Build/install tooling (plural)
+- `script/`: Release automation (singular — legacy Bun convention)
+- `dist/`: Build output (standard)
+
+**Exports:**
+
+- Classes: PascalCase (`AccountManager`, `HealthScoreTracker`, `TokenBucketTracker`)
+- Functions: camelCase (`loadConfig`, `saveAccounts`, `selectAccount`, `calculateBackoffMs`)
+- Constants: SCREAMING_SNAKE_CASE (`DEFAULT_CONFIG`, `CLIENT_ID`, `VALID_STRATEGIES`, `RATE_LIMIT_KEY`)
+- Types (JSDoc): PascalCase (`ManagedAccount`, `AccountStorage`, `RateLimitReason`)
+
+## Where to Add New Code
+
+**New Library Module:**
+
+- Implementation: `lib/<module-name>.mjs`
+- Tests: `lib/<module-name>.test.mjs`
+- Import from entry points or other lib modules as needed
+
+**New CLI Command:**
+
+- Add command function in `cli.mjs` (exported, named `cmd<Name>`)
+- Add routing in the `switch` statement within `main()` function
+- Add to help text in `cmdHelp()`
+
+**New Plugin Hook:**
+
+- Add in the returned object from `AnthropicAuthPlugin()` in `index.mjs`
+- Follow OpenCode plugin API types from `@opencode-ai/plugin`
+
+**New Account Selection Strategy:**
+
+- Add strategy name to `VALID_STRATEGIES` in `lib/config.mjs`
+- Add case to `selectAccount()` switch in `lib/rotation.mjs`
+- Update `AccountSelectionStrategy` typedef
+
+**Utilities/Helpers:**
+
+- If used by multiple modules: create new file in `lib/`
+- If used by single module: add as local function in that module
+- CLI-only helpers: keep in `cli.mjs`
+- Plugin-only helpers: keep in `index.mjs`
+
+## Special Directories
+
+**`dist/`:**
+
+- Purpose: Self-contained bundled artifacts (plugin + CLI)
+- Generated: Yes (`npm run build` via esbuild)
+- Committed: No (gitignored)
+- Consumers: `scripts/install.mjs copy` deploys these to user's system
+
+**`.mitm/`:**
+
+- Purpose: mitmproxy debugging for inspecting API traffic between plugin and Anthropic
+- Generated: Manually (development tool)
+- Committed: No (gitignored)
+
+**`node_modules/`:**
+
+- Purpose: npm dependencies
+- Generated: Yes (`npm install`)
+- Committed: No (gitignored)
+
+**`.planning/`:**
+
+- Purpose: GSD codebase analysis documents
+- Generated: By analysis tooling
+- Committed: Yes (intended to be tracked)
+
+## Import Dependency Graph
+
+```
+index.mjs (plugin)
+  ├── lib/accounts.mjs
+  │     ├── lib/storage.mjs
+  │     │     └── lib/config.mjs
+  │     ├── lib/rotation.mjs
+  │     │     └── lib/config.mjs
+  │     └── lib/backoff.mjs
+  ├── lib/config.mjs
+  ├── lib/storage.mjs
+  ├── lib/backoff.mjs
+  └── @openauthjs/openauth (external)
+
+cli.mjs (CLI)
+  ├── lib/storage.mjs
+  │     └── lib/config.mjs
+  └── lib/config.mjs
+```
+
+Note: `cli.mjs` does NOT depend on `lib/accounts.mjs` — it operates directly on the storage layer. The `AccountManager` class is plugin-only (in-memory runtime state). The CLI reads/writes the shared JSON file directly.
+
+---
+
+_Structure analysis: 2026-02-07_