add documentation

docs-site/docs/reference/api-client.md

@@ -0,0 +1,9 @@
+# API client and OAuth
+
+**Primary paths:** `src/services/api/`, `src/services/oauth/`, `src/utils/api.ts`, `src/utils/auth.ts`
+
+`services/api/client.ts` and `claude.ts` implement HTTP and streaming calls to Anthropic APIs (including retries, errors, session ingress, files API, usage, bootstrap). Provider-specific paths (Bedrock, Vertex, Foundry) are gated through auth and endpoint configuration in `utils/aws.ts`, `utils/auth.ts`, and related modules.
+
+`services/oauth/` implements the browser-based OAuth flow (auth code listener, token exchange, crypto).
+
+**See also:** [Authentication](https://code.claude.com/docs/en/authentication), [Amazon Bedrock](https://code.claude.com/docs/en/amazon-bedrock), [Google Vertex AI](https://code.claude.com/docs/en/google-vertex-ai).

docs-site/docs/reference/cli-entry.md

@@ -0,0 +1,11 @@
+# CLI entry and parsing
+
+**Primary paths:** `src/main.tsx`, `src/cli/*`, `src/commands.ts`
+
+`main.tsx` registers the `claude` Commander program: global options (model, permissions, worktree, teammate flags, MCP, teleport, etc.), subcommands (MCP, plugins, agents, auth utilities), and a `preAction` hook that runs trust checks, settings load, telemetry initialization, prefetch (MCP URLs, referral, fast mode), and policy gates before any handler executes.
+
+Side effects at **module top** intentionally run before other imports: startup profiler, MDM subprocess reads (`utils/settings/mdm/rawRead.ts`), and macOS keychain prefetch to overlap I/O with the rest of module evaluation.
+
+Feature-gated dynamic `require()` loads `coordinator/coordinatorMode.js` when `COORDINATOR_MODE` is true in the Bun bundle, and `assistant/` when `KAIROS` is true.
+
+**See also:** [CLI reference](https://code.claude.com/docs/en/cli-reference), [Architecture](../architecture.md).

docs-site/docs/reference/compaction.md

@@ -0,0 +1,9 @@
+# Compaction and session memory
+
+**Primary paths:** `src/services/compact/`, `src/services/SessionMemory/`, `src/utils/tokenBudget.ts`
+
+Compaction reduces transcript size when approaching context limits: `compact.ts`, `autoCompact.ts`, `microCompact.ts`, `sessionMemoryCompact.ts`, grouping, prompts, and post-compact cleanup. Time-based and API microcompact paths support different strategies.
+
+Session memory modules add long-lived summaries and structured memory aligned with product behavior described under [memory](https://code.claude.com/docs/en/memory) and [context window](https://code.claude.com/docs/en/context-window).
+
+**See also:** [Context window](https://code.claude.com/docs/en/context-window), [Costs](https://code.claude.com/docs/en/costs), [Checkpointing](https://code.claude.com/docs/en/checkpointing).

docs-site/docs/reference/lsp.md

@@ -0,0 +1,9 @@
+# LSP integration
+
+**Primary paths:** `src/services/lsp/`, `src/tools/LSPTool/`
+
+`LSPServerManager.ts`, `LSPClient.ts`, and related modules manage language server processes and diagnostics. The agent invokes LSP capabilities through `LSPTool`, which bridges model tool calls to LSP requests.
+
+Passive feedback and config live alongside the manager (`passiveFeedback.ts`, `config.ts`).
+
+**See also:** [Tools reference](https://code.claude.com/docs/en/tools-reference) (LSP tool), [Architecture](../architecture.md).

docs-site/docs/reference/mcp.md

@@ -0,0 +1,11 @@
+# MCP (Model Context Protocol)
+
+**Primary paths:** `src/services/mcp/`, `src/tools/MCPTool/`, `src/tools/McpAuthTool/`, `src/services/mcp/MCPConnectionManager.tsx`
+
+The MCP subsystem parses config (files, env expansion, enterprise allowlists), establishes **stdio** and **in-process** transports, handles OAuth for MCP servers, normalizes server metadata, and exposes tools and resources to the model.
+
+Channel-related files (`channelAllowlist`, `channelNotification`, `channelPermissions`) implement **push** notifications into a session, matching the [Channels](https://code.claude.com/docs/en/channels) documentation.
+
+The React `MCPConnectionManager` wraps interactive sessions so the REPL can connect/disconnect servers and reflect status in the UI.
+
+**See also:** [MCP](https://code.claude.com/docs/en/mcp), [Channels reference](https://code.claude.com/docs/en/channels-reference).

docs-site/docs/reference/permissions.md

@@ -0,0 +1,9 @@
+# Permissions and modes
+
+**Primary paths:** `src/utils/permissions/`, `src/utils/permissions/permissionSetup.ts`, `src/utils/permissions/PermissionMode.ts`
+
+Permission modes (manual, auto with classifiers, plan-only, etc.) are parsed from CLI flags and settings, then stored in `toolPermissionContext` on app state. Tool execution consults this context before running bash, file writes, MCP calls, etc.
+
+`permissionSetup.ts` and related modules implement gates for auto mode, dangerous permission stripping, and advisor integration.
+
+**See also:** [Permissions](https://code.claude.com/docs/en/permissions), [Permission modes](https://code.claude.com/docs/en/permission-modes), [Sandboxing](https://code.claude.com/docs/en/sandboxing).

docs-site/docs/reference/plugins-skills.md

@@ -0,0 +1,9 @@
+# Plugins and skills
+
+**Primary paths:** `src/plugins/`, `src/skills/`, `src/utils/plugins/`, `src/utils/skills/`, `src/tools/SkillTool/`, `src/services/plugins/`
+
+Bundled plugins ship under `plugins/bundled/`; `PluginInstallationManager` and CLI commands under `services/plugins/` support install/update scopes. Skills load from project and user directories; `skillChangeDetector` watches for changes.
+
+`SkillTool` exposes skill invocation to the model. Hooks and commands defined by plugins align with [Plugins](https://code.claude.com/docs/en/plugins) and [Skills](https://code.claude.com/docs/en/skills).
+
+**See also:** [Plugins reference](https://code.claude.com/docs/en/plugins-reference), [Discover plugins](https://code.claude.com/docs/en/discover-plugins).

docs-site/docs/reference/print-sdk.md

@@ -0,0 +1,11 @@
+# Print mode, stream-json, and SDK control
+
+**Primary paths:** `src/cli/print.ts`, `src/cli/structuredIO.ts`, `src/cli/transports/*`, `src/QueryEngine.ts`
+
+`print.ts` implements non-interactive execution: structured stdin lines, streaming stdout (including partial messages), tool permission prompts bridged over the protocol, and verbose/debug modes.
+
+`structuredIO.ts` parses and validates incoming events; transports (`WebSocketTransport`, `SSETransport`, `HybridTransport`, etc.) support remote SDK and CCR-style integrations.
+
+This corresponds to [Headless](https://code.claude.com/docs/en/headless) and Agent SDK usage documented on the Anthropic platform.
+
+**See also:** [Workflows](../workflows.md), [Query loop](query-engine.md).

docs-site/docs/reference/query-engine.md

@@ -0,0 +1,11 @@
+# Query loop and streaming
+
+**Primary paths:** `src/query.ts`, `src/QueryEngine.ts`, `src/utils/processUserInput/`
+
+`query.ts` defines `queryLoop`, the async generator that drives a single conversation turn: streams assistant content, handles tool calls, merges tool results back into context, and coordinates with compaction and permission checks.
+
+`QueryEngine.ts` exposes `submitMessage` for **non-interactive** flows: it prepares `processUserInputContext` with `isNonInteractiveSession: true`, runs skill/plugin caches, and streams SDK-style messages—used from headless and SDK control transports.
+
+Shared input processing (slash commands embedded in prompts, tool permission context updates) lives under `utils/processUserInput/` and related modules.
+
+**See also:** [How Claude Code works](https://code.claude.com/docs/en/how-claude-code-works), [Headless](https://code.claude.com/docs/en/headless).

docs-site/docs/reference/remote-bridge.md

@@ -0,0 +1,13 @@
+# Remote sessions, teleport, IDE bridge, Chrome
+
+**Primary paths:** `src/remote/`, `src/utils/teleport/`, `src/utils/deepLink/`, `src/bridge/`, `src/utils/claudeInChrome/`, `src/hooks/useDiffInIDE.ts`
+
+**Remote / teleport:** `teleport/` handles session bundles, environment selection, and API calls to resume or hand off sessions—aligned with [Remote control](https://code.claude.com/docs/en/remote-control) and web/desktop flows.
+
+**Deep links:** `deepLink/protocolHandler.ts` parses `claude-cli://` URIs and launches the binary in a terminal with the right cwd/repo context.
+
+**IDE bridge:** `bridge/` communicates with VS Code and JetBrains extensions (diffs, context). Hooks like `useDiffInIDE.ts` open IDE-native diff UIs when available.
+
+**Chrome:** `claudeInChrome/` implements native messaging and MCP servers for the [Chrome](https://code.claude.com/docs/en/chrome) beta workflow.
+
+**See also:** [VS Code](https://code.claude.com/docs/en/vs-code), [JetBrains](https://code.claude.com/docs/en/jetbrains), [Desktop](https://code.claude.com/docs/en/desktop).

docs-site/docs/reference/repl-ui.md

@@ -0,0 +1,11 @@
+# REPL and terminal UI
+
+**Primary paths:** `src/screens/REPL.tsx`, `src/components/`, `src/ink/`, `src/replLauncher.tsx`, `src/interactiveHelpers.tsx`
+
+The interactive session is a **React + Ink** application. `replLauncher.tsx` mounts the Ink root and wraps the tree with providers for app state, keybindings, MCP connections, and plugin context.
+
+`REPL.tsx` is large and central: it manages the transcript, loading state, `onQuery` invocations, tool use UI, permission prompts, teammate inbox polling, mailbox bridge, voice integration when `VOICE_MODE` is compiled in, scheduled cron integration, and queue processing between turns.
+
+`ink/` contains layout primitives, terminal I/O helpers, and event wiring specific to the TUI. `components/` holds feature UI (modals, tool output, plan mode, etc.).
+
+**See also:** [Interactive mode](https://code.claude.com/docs/en/interactive-mode), [Fullscreen](https://code.claude.com/docs/en/fullscreen), [Workflows](../workflows.md).

docs-site/docs/reference/settings-policy.md

@@ -0,0 +1,11 @@
+# Settings, policy, and remote management
+
+**Primary paths:** `src/utils/settings/`, `src/services/policyLimits/`, `src/services/remoteManagedSettings/`, `src/schemas/`, `src/migrations/`
+
+`settings.ts` and `settingsCache.ts` load merged global and project settings. `mdm/` contains macOS managed-device reads. `validation.ts` enforces schema and tool allowlists.
+
+`policyLimits/` loads enterprise caps (models, spend, features). `remoteManagedSettings/` syncs server-delivered configuration described in [Server-managed settings](https://code.claude.com/docs/en/server-managed-settings).
+
+`migrations/` upgrades on-disk settings between versions.
+
+**See also:** [Settings](https://code.claude.com/docs/en/settings), [Environment variables](https://code.claude.com/docs/en/env-vars).

docs-site/docs/reference/telemetry.md

@@ -0,0 +1,7 @@
+# Analytics and telemetry
+
+**Primary paths:** `src/services/analytics/`, `src/utils/telemetry/`
+
+Event logging, GrowthBook/feature flags, Datadog and first-party exporters, session tracing (including Perfetto-oriented paths), and plugin/skill load telemetry live here. Analytics respects disable flags and trust gating initialized after user consent.
+
+**See also:** [Analytics](https://code.claude.com/docs/en/analytics), [Monitoring](https://code.claude.com/docs/en/monitoring-usage).

docs-site/docs/reference/tools.md

@@ -0,0 +1,11 @@
+# Tools registry and execution
+
+**Primary paths:** `src/tools.ts`, `src/Tool.ts`, `src/tools/*`, `src/services/tools/`
+
+`tools.ts` exposes `getTools(permissionContext)` and helpers to merge **built-in** tools with **MCP-derived** tools. Built-ins live as one package per directory under `tools/` (e.g. `BashTool`, `FileReadTool`, `GlobTool`, `WebSearchTool`, `AgentTool`).
+
+`services/tools/` contains orchestration: `toolExecution.ts`, `StreamingToolExecutor.ts`, `toolHooks.ts`, hooking tool lifecycle into analytics and permission systems.
+
+Tool schemas and permission requirements align with the public [Tools reference](https://code.claude.com/docs/en/tools-reference); this tree is the implementation of those capabilities.
+
+**See also:** [Tools reference](https://code.claude.com/docs/en/tools-reference), [Appendix: tool packages](../appendix/tool-packages.md).

docs-site/docs/reference/voice-vim-output.md

@@ -0,0 +1,11 @@
+# Voice, Vim, and output styles
+
+**Primary paths:** `src/voice/`, `src/vim/`, `src/outputStyles/`, `src/screens/REPL.tsx` (voice hook)
+
+Voice dictation integrates through `useVoiceIntegration` in `REPL.tsx` when the bundle includes `VOICE_MODE`. `voice/` contains mode and streaming helpers.
+
+`vim/` implements modal editing for the prompt (motions, operators, text objects) consistent with [Interactive mode](https://code.claude.com/docs/en/interactive-mode) keyboard behavior.
+
+`outputStyles/` adapts presentation for non-default “output styles” described in the [Output styles](https://code.claude.com/docs/en/output-styles) doc.
+
+**See also:** [Voice dictation](https://code.claude.com/docs/en/voice-dictation), [Keybindings](https://code.claude.com/docs/en/keybindings).