docs: update CLAUDE.md, deployment, and conversations docs

CLAUDE.md: updated source layout with orchestrator, grpc, code_index,
breadcrumbs modules. Deployment: added gRPC service, startup flowchart,
new secrets and troubleshooting. Conversations: updated lifecycle to
show orchestrator path and gRPC session keys.

CLAUDE.md

@@ -4,10 +4,16 @@
 
 ```sh
 cargo build --release                              # debug: cargo build
-cargo test                                         # 102 unit tests, no external services needed
+cargo test                                         # unit tests, no external services needed
 cargo build --release --target x86_64-unknown-linux-gnu  # cross-compile for production
 ```
 
+Integration tests (require `.env` with `SOL_MISTRAL_API_KEY`):
+
+```sh
+cargo test --test integration_test
+```
+
 Docker (multi-stage, vendored deps):
 
 ```sh
@@ -37,10 +43,12 @@ This updates the vendored sources. Commit `vendor/` changes alongside `Cargo.loc
 ## Key Architecture Notes
 
 - **`chat_blocking()` workaround**: The Mistral client's `chat_async` holds a `std::sync::MutexGuard` across `.await`, making the future `!Send`. All chat calls use `chat_blocking()` which runs `client.chat()` via `tokio::task::spawn_blocking`.
-- **Two response paths**: Controlled by `agents.use_conversations_api` config toggle.
-  - Legacy: manual `Vec<ChatMessage>` assembly, chat completions, tool iteration loop.
-  - Conversations API: `ConversationRegistry` with persistent state (SQLite-backed), agents, function call loop.
+- **Transport-agnostic orchestrator**: The `orchestrator` module emits `OrchestratorEvent`s via broadcast channel. It has no knowledge of Matrix or gRPC. Transport bridges subscribe to events and translate to their protocol.
+- **Two input paths**: Matrix sync loop and gRPC `CodeAgent` service. Both feed `GenerateRequest` into the orchestrator.
+- **Tool dispatch routing**: `ToolSide::Server` tools execute locally in Sol. `ToolSide::Client` tools are relayed to the gRPC client (sunbeam code TUI) via oneshot channels.
+- **Conversations API**: `ConversationRegistry` with persistent state (SQLite-backed), agents, function call loop. Enabled via `agents.use_conversations_api`.
 - **deno_core sandbox**: `run_script` tool spins up a fresh V8 isolate per invocation with `sol.*` host API bindings. Timeout via V8 isolate termination. Output truncated to 4096 chars.
+- **Code indexing**: Tree-sitter symbol extraction (Rust, Python, TypeScript, Go, Java) from Gitea repos and `sunbeam code` IndexSymbols. Stored in OpenSearch `sol_code` index.
 
 ## K8s Context
 
@@ -55,17 +63,23 @@ This updates the vendored sources. Commit `vendor/` changes alongside `Cargo.loc
 
 ## Source Layout
 
-- `src/main.rs` — startup, component wiring, backfill, agent recreation + sneeze
+- `src/main.rs` — startup, component wiring, gRPC server, backfill, agent recreation + sneeze
 - `src/sync.rs` — Matrix event handlers, context hint injection for new conversations
-- `src/config.rs` — TOML config with serde defaults (6 sections: matrix, opensearch, mistral, behavior, agents, services, vault)
+- `src/config.rs` — TOML config with serde defaults (8 sections: matrix, opensearch, mistral, behavior, agents, services, vault, grpc)
 - `src/context.rs` — `ResponseContext`, `derive_user_id`, `localpart`
 - `src/conversations.rs` — `ConversationRegistry` (room→conversation mapping, SQLite-backed, reset_all)
 - `src/persistence.rs` — SQLite store (WAL mode, 3 tables: `conversations`, `agents`, `service_users`)
-- `src/agent_ux.rs` — `AgentProgress` (reaction lifecycle + thread posting)
-- `src/matrix_utils.rs` — message extraction, image download, reactions
-- `src/brain/` — evaluator (full system prompt context), responder (per-message context headers + memory), personality, conversation manager
-- `src/agents/` — registry (instructions hash + automatic recreation), definitions (dynamic delegation)
-- `src/sdk/` — vault client (K8s auth), token store (Vault-backed), gitea client (PAT auto-provisioning)
+- `src/matrix_utils.rs` — message extraction, reply/edit/thread detection, image download
+- `src/time_context.rs` — time utilities
+- `src/tokenizer.rs` — token counting
+- `src/orchestrator/` — transport-agnostic event-driven pipeline (engine, events, tool dispatch)
+- `src/grpc/` — gRPC CodeAgent service (server, session, auth, bridge to orchestrator events)
+- `src/brain/` — evaluator (engagement decision), responder (response generation), personality, conversation manager
+- `src/agents/` — registry (instructions hash + automatic recreation), definitions (orchestrator + domain agents)
+- `src/sdk/` — vault client (K8s auth), token store (Vault-backed), gitea client (PAT auto-provisioning), kratos client
 - `src/memory/` — schema, store, extractor
-- `src/tools/` — registry (12 tools), search, room_history, room_info, script, devtools (gitea), bridge
+- `src/tools/` — registry + dispatch, search, code_search, room_history, room_info, script, devtools (gitea), identity (kratos), web_search (searxng), research (parallel micro-agents), bridge
+- `src/code_index/` — schema, gitea repo walker, tree-sitter symbol extraction, OpenSearch indexer
+- `src/breadcrumbs/` — adaptive code context injection (project outline + hybrid search)
 - `src/archive/` — schema, indexer
+- `proto/code.proto` — gRPC service definition (CodeAgent: Session + ReindexCode)