docs: replace file-reference lists with module tables (batch A)

Replace trailing File Reference sections in 7 docs with 3-4 row module-level tables. Column schema: Module | Path | Purpose. Adds 1-line grep hint at end of each section. Also fixes one body .go:line citation in 05-channels-messaging.md.
2026-08-07 04:24:10 +00:00 · 2026-04-19 15:37:59 +07:00
parent d7e2883926
commit 653df6fb52
7 changed files with 55 additions and 279 deletions
@@ -460,25 +460,14 @@ flowchart TD

 ## 11. File Reference

-| File | Purpose |
-|------|---------|
-| `cmd/root.go` | Cobra CLI entry point, flag parsing |
-| `cmd/gateway.go` | Gateway startup orchestrator (`runGateway()`) |
-| `cmd/gateway_managed.go` | Database wiring (`wireManagedExtras()`, `wireManagedHTTP()`) |
-| `cmd/gateway_callbacks.go` | Shared callbacks (user seeding, context file loading) |
-| `cmd/gateway_consumer.go` | Inbound message consumer (subagent, teammate routing) |
-| `cmd/gateway_providers.go` | Provider registration (config-based + DB-based) |
-| `cmd/gateway_methods.go` | RPC method registration |
-| `internal/config/config.go` | Config struct definitions |
-| `internal/config/config_load.go` | JSON5 loading + env overlay |
-| `internal/config/config_channels.go` | Channel config structs |
-| `internal/gateway/server.go` | WS + HTTP server, CORS, rate limiter setup |
-| `internal/gateway/client.go` | WebSocket client handling, read limit (512KB) |
-| `internal/gateway/router.go` | RPC method routing |
-| `internal/scheduler/lanes.go` | Lane definitions, semaphore-based concurrency |
-| `internal/scheduler/queue.go` | Per-session queue, queue modes, debounce |
-| `internal/store/stores.go` | `Stores` container struct (all 22+ store interfaces) |
-| `internal/store/types.go` | `StoreConfig`, `BaseModel` |
+| Module | Path | Purpose |
+|---|---|---|
+| CLI & startup | `cmd/` | Cobra entry point, gateway orchestrator, DB wiring, provider registration, RPC method registration |
+| Gateway server | `internal/gateway/` | WS + HTTP server, client lifecycle, method router, rate limiter |
+| Config | `internal/config/` | JSON5 config loading, env overlay, channel config structs |
+| Store layer | `internal/store/` | `Stores` container, `BaseModel`, `StoreConfig`, `GenNewID()` |
+
+Use `grep` or your editor's symbol search for specific files.

 ---

@@ -722,36 +722,14 @@ GoClaw v3 Wave 2 adds composable request middleware, error classification, per-m

 ## 14. File Reference

-| File | Purpose |
-|------|---------|
-| `internal/providers/middleware.go` | RequestMiddleware type, ComposeMiddlewares, ApplyMiddlewares (zero-alloc fast path) |
-| `internal/providers/middleware_cache.go` | CacheMiddleware for prompt caching |
-| `internal/providers/middleware_service_tier.go` | ServiceTierMiddleware for routing hints |
-| `internal/providers/error_classify.go` | ErrorClassifier, DefaultClassifier, 9 failover reasons, context overflow detection |
-| `internal/providers/cooldown.go` | CooldownTracker: per-model:provider failure state, reason-dependent durations, probe intervals |
-| `internal/providers/failover.go` | RunWithFailover[T]: 2-tier logic, profile rotation, model fallback, candidate exhaustion |
-| `internal/providers/model_registry.go` | ModelRegistry, ModelSpec, InMemoryRegistry, forward-compat resolver, seeded defaults |
-| `internal/providers/embedding_openai.go` | OpenAI embedding provider (text-embedding-3-small, 1536 dims, batch 2048) |
-| `internal/providers/embedding_voyage.go` | Voyage AI embedding provider |
-| `internal/providers/types.go` | Provider interface, ChatRequest, ChatResponse, Message, ToolCall, Usage types |
-| `internal/providers/anthropic.go` | Anthropic provider: native HTTP + SSE, request/response marshaling |
-| `internal/providers/anthropic_request.go` | Anthropic request builder: message formatting, tool schemas, system blocks |
-| `internal/providers/anthropic_stream.go` | Anthropic SSE event parsing and response accumulation |
-| `internal/providers/openai.go` | OpenAI-compatible provider: generic HTTP client for 10+ endpoints |
-| `internal/providers/openai_types.go` | OpenAI request/response types and message formatting |
-| `internal/providers/openai_gemini.go` | Gemini-specific compatibility: empty content handling, tool schema cleaning |
-| `internal/providers/claude_cli.go` | ClaudeCLIProvider: orchestrates local claude CLI binary via stdio |
-| `internal/providers/claude_cli_chat.go` | Chat/ChatStream implementation for CLI provider |
-| `internal/providers/claude_cli_session.go` | Session management: per-session state, history, workspace |
-| `internal/providers/claude_cli_mcp.go` | MCP configuration and server bridge for CLI provider |
-| `internal/providers/codex.go` | CodexProvider: OAuth-based ChatGPT Responses API |
-| `internal/providers/codex_build.go` | Codex request builder: message formatting, phase handling |
-| `internal/providers/dashscope.go` | DashScope provider: OpenAI-compat wrapper with thinking budget, tools+streaming fallback |
-| `internal/providers/acp_provider.go` | ACPProvider: orchestrates ACP-compatible agent subprocesses |
-| `internal/providers/retry.go` | RetryDo[T] generic function, RetryConfig, IsRetryableError, backoff computation |
-| `internal/providers/schema_cleaner.go` | CleanSchemaForProvider, CleanToolSchemas, recursive schema field removal |
-| `internal/providers/registry.go` | Provider registry: registration, lookup, lifecycle management |
-| `cmd/gateway_providers.go` | Provider registration from config and database during gateway startup |
+| Module | Path | Purpose |
+|---|---|---|
+| Provider implementations | `internal/providers/` | Anthropic, OpenAI-compatible, Claude CLI, Codex, ACP, DashScope providers; retry logic; schema cleaning; model registry; embedding providers |
+| Resilience middleware | `internal/providers/` | `middleware*.go`, `error_classify.go`, `cooldown.go`, `failover.go` — request middleware, error classification, 2-tier failover |
+| Provider interface & types | `internal/providers/types.go` | `Provider` interface, `ChatRequest`, `ChatResponse`, `Message`, `ToolCall`, `Usage` |
+| Gateway wiring | `cmd/gateway_providers.go` | Provider registration from config and database at startup |
+
+Use `grep` or your editor's symbol search for specific files.

 ---

@@ -574,56 +574,11 @@ Error responses include `retryable` (boolean) and `retryAfterMs` (integer) field

 ## File Reference

-| File | Purpose |
-|------|---------|
-| `internal/gateway/server.go` | Server: WebSocket upgrade, HTTP mux, CORS check, client lifecycle |
-| `internal/gateway/client.go` | Client: connection management, read/write pumps, send buffer |
-| `internal/gateway/router.go` | MethodRouter: handler registration, permission-checked dispatch |
-| `internal/gateway/ratelimit.go` | RateLimiter: token bucket per key, cleanup loop |
-| `internal/gateway/methods/chat.go` | chat.send, chat.history, chat.abort, chat.inject handlers |
-| `internal/gateway/methods/agents.go` | agents.list, agents.create/update/delete, agents.files.* handlers |
-| `internal/gateway/methods/sessions.go` | sessions.list/preview/patch/delete/reset handlers |
-| `internal/gateway/methods/config.go` | config.get/apply/patch/schema handlers |
-| `internal/gateway/methods/skills.go` | skills.list/get/update handlers |
-| `internal/gateway/methods/cron.go` | cron.list/create/update/delete/toggle/run/runs handlers |
-| `internal/gateway/methods/teams.go` | teams.* handlers + auto-linking teammates |
-| `internal/gateway/methods/teams_workspace.go` | teams.workspace.* handlers (file management) |
-| `internal/gateway/methods/delegations.go` | delegations.list/get handlers |
-| `internal/gateway/methods/channels.go` | channels.list/status/toggle handlers |
-| `internal/gateway/methods/channel_instances.go` | channels.instances.* handlers (CRUD) |
-| `internal/gateway/methods/pairing.go` | device.pair.* and browser.pairing.* handlers |
-| `internal/gateway/methods/exec_approval.go` | exec.approval.* handlers |
-| `internal/gateway/methods/usage.go` | usage.get/summary handlers |
-| `internal/gateway/methods/api_keys.go` | api_keys.list/create/revoke handlers |
-| `internal/gateway/methods/send.go` | send handler (direct message to channel) |
-| `internal/gateway/methods/agent_links.go` | agent_links.* handlers (v3 delegation links) |
-| `internal/http/chat_completions.go` | POST /v1/chat/completions (OpenAI-compatible) |
-| `internal/http/responses.go` | POST /v1/responses (OpenResponses protocol) |
-| `internal/http/tools_invoke.go` | POST /v1/tools/invoke (direct tool execution) |
-| `internal/http/agents.go` | Agent CRUD HTTP handlers (/v1/agents, /v1/agents/{id}/sharing) |
-| `internal/http/skills.go` | Skills HTTP handlers (/v1/skills, upload, dependencies) |
-| `internal/http/traces.go` | Traces HTTP handlers (/v1/traces) |
-| `internal/http/delegations.go` | Delegation history HTTP handlers (/v1/delegations) |
-| `internal/http/channel_instances.go` | Channel instance CRUD handlers (/v1/channel-instances) |
-| `internal/http/providers.go` | LLM provider CRUD handlers (/v1/providers) |
-| `internal/http/memory.go` | Memory management handlers (/v1/memory) |
-| `internal/http/knowledge_graph.go` | Knowledge graph handlers (/v1/kg) |
-| `internal/http/files.go` | Workspace file serving handlers (/v1/files) |
-| `internal/http/storage.go` | Storage file CRUD handlers (/v1/storage) |
-| `internal/http/media_upload.go` | Media upload handlers (/v1/media/upload) |
-| `internal/http/media_serve.go` | Media serving handlers (/v1/media/{id}) |
-| `internal/http/activity.go` | Activity audit log handlers (/v1/activity) |
-| `internal/http/usage.go` | Usage analytics handlers (/v1/usage) |
-| `internal/http/api_keys.go` | API key management handlers (/v1/api-keys) |
-| `internal/http/custom_tools.go` | Custom tool CRUD handlers (/v1/tools/custom) |
-| `internal/http/mcp.go` | MCP server management handlers (/v1/mcp) |
-| `internal/http/summoner.go` | LLM-powered agent setup (XML parsing, context file generation) |
-| `internal/http/auth.go` | Bearer token authentication, timing-safe comparison |
-| `internal/http/oauth.go` | OAuth authentication endpoints (/oauth) |
-| `internal/http/docs.go` | OpenAPI documentation handlers (/docs) |
-| `internal/mcp/bridge.go` | MCP bridge for Claude CLI integration (/mcp/bridge) |
-| `internal/permissions/policy.go` | PolicyEngine: role hierarchy, method-to-role mapping |
-| `pkg/protocol/frames.go` | Frame types: RequestFrame, ResponseFrame, EventFrame, ErrorShape |
-| `pkg/protocol/methods.go` | RPC method name constants (Phase 1-3) |
-| `pkg/protocol/events.go` | WebSocket event names and event subtypes |
-| `pkg/protocol/errors.go` | Error code constants and error factories |
+| Module | Path | Purpose |
+|---|---|---|
+| Gateway core | `internal/gateway/` | WS server, HTTP mux, method router, rate limiter, client lifecycle |
+| RPC handlers | `internal/gateway/methods/` | All WS RPC handlers: chat, agents, sessions, config, skills, cron, teams, channels, pairing, exec approval, usage, API keys |
+| HTTP handlers | `internal/http/` | All REST endpoints: /v1/chat/completions, /v1/agents, /v1/skills, /v1/traces, /v1/mcp, auth, OAuth, summoner |
+| Protocol types | `pkg/protocol/` | Frame types, RPC method constants, event names, error codes |
+
+Use `grep` or your editor's symbol search for specific files.
@@ -319,7 +319,7 @@ All channel factories accept `audioMgr *audio.Manager`:
 - Feishu: `FactoryWithStoresAndAudio(..., audioMgr)`
 - WhatsApp: `FactoryWithDBAudio(..., audioMgr, builtinToolStore)`

-WhatsApp additionally accepts `builtinToolStore store.BuiltinToolStore` to fetch the per-message `whatsapp_enabled` opt-in flag. Wiring in `cmd/gateway_channels_setup.go:77` + `cmd/gateway.go:433`.
+WhatsApp additionally accepts `builtinToolStore store.BuiltinToolStore` to fetch the per-message `whatsapp_enabled` opt-in flag. Wiring is in `cmd/gateway_channels_setup.go` and `cmd/gateway.go`.

 ### Bot Commands

@@ -676,45 +676,14 @@ flowchart TD

 ## File Reference

-| File | Purpose |
-|------|---------|
-| `internal/channels/channel.go` | Channel interface, BaseChannel, extended interfaces, HandleMessage, Type() method |
-| `internal/channels/manager.go` | Manager: registration, StartAll, StopAll, channel lifecycle, webhook collection |
-| `internal/channels/dispatch.go` | Outbound message dispatcher, send error formatting |
-| `internal/channels/instance_loader.go` | DB-based channel instance loading |
-| `internal/channels/telegram/channel.go` | Telegram core: long polling, mention gating, typing indicators |
-| `internal/channels/telegram/handlers.go` | Message handling, media processing, forum topic detection |
-| `internal/channels/telegram/topic_config.go` | Per-topic config layering and resolution |
-| `internal/channels/telegram/commands.go` | Bot commands: /stop, /reset, /tasks, /addwriter, etc. |
-| `internal/channels/telegram/factory.go` | Channel factory with audio.Manager wiring |
-| `internal/channels/telegram/stream.go` | Streaming placeholder management |
-| `internal/channels/telegram/reactions.go` | Status reactions on messages |
-| `internal/channels/telegram/format.go` | Markdown → Telegram HTML pipeline, table rendering |
-| `internal/channels/feishu/feishu.go` | Feishu core: WS/Webhook modes, config, reactions |
-| `internal/channels/feishu/larkclient_messaging.go` | Streaming card create/update/close, message sending |
-| `internal/channels/feishu/media.go` | Media upload/download, type detection |
-| `internal/channels/feishu/bot_parse.go` | Mention resolution, message event parsing |
-| `internal/channels/feishu/bot.go` | Bot message handlers |
-| `internal/channels/feishu/bot_policy.go` | Policy evaluation |
-| `internal/channels/discord/discord.go` | Discord: gateway setup, session management, lifecycle |
-| `internal/channels/discord/handler.go` | Message handling, typing indicators, placeholder management |
-| `internal/channels/slack/channel.go` | Slack: Socket Mode, mention gating, thread caching, streaming |
-| `internal/channels/slack/handlers.go` | Message and event handling, pairing, group policy |
-| `internal/channels/slack/format.go` | Markdown → Slack mrkdwn pipeline |
-| `internal/channels/slack/reactions.go` | Status emoji reactions on messages |
-| `internal/channels/slack/stream.go` | Streaming message updates via placeholder editing |
-| `internal/channels/whatsapp/whatsapp.go` | WhatsApp: direct protocol client, QR auth, database persistence |
-| `internal/channels/whatsapp/factory.go` | Channel factory with audio.Manager and builtin-tool store wiring |
-| `internal/channels/whatsapp/stt.go` | Voice transcription with opt-in setting and E2E fallback |
-| `internal/channels/whatsapp/qr_methods.go` | QR code generation and authentication flow |
-| `internal/channels/whatsapp/format.go` | Message formatting (HTML-to-WhatsApp) |
-| `internal/channels/zalo/zalo.go` | Zalo OA: Bot API, long polling |
-| `internal/channels/zalo/personal/channel.go` | Zalo Personal: reverse-engineered protocol |
-| `internal/audio/manager.go` | Audio manager: providers registry, lifecycle |
-| `internal/audio/manager_stt.go` | STT chain resolution, Transcribe() entry point |
-| `internal/audio/legacy_stt_bridge.go` | Backward-compat bridge for legacy STTProxyURL configs |
-| `internal/store/pg/pairing.go` | Pairing: code generation, approval, persistence (database-backed) |
-| `cmd/gateway_consumer.go` | Message routing: prefixes, cancel interception |
+| Module | Path | Purpose |
+|---|---|---|
+| Channel core | `internal/channels/` | `Channel` interface, `BaseChannel`, `Manager` (StartAll/StopAll), outbound dispatcher, DB instance loader |
+| Platform adapters | `internal/channels/{telegram,feishu,discord,slack,whatsapp,zalo}/` | Per-platform: message handling, formatting, streaming, reactions, media, pairing |
+| Audio / STT | `internal/audio/` | Audio manager, STT chain resolution, legacy STT bridge |
+| Pairing & routing | `internal/store/pg/pairing.go`, `cmd/gateway_consumer.go` | Pairing code persistence, inbound message routing and cancel interception |
+
+Use `grep` or your editor's symbol search for specific files.

 ---

@@ -804,52 +804,11 @@ Workers subscribe on startup via `consolidation.Register()`.

 ## 18. File Reference

-| File | Purpose |
-|------|---------|
-| `internal/store/stores.go` | `Stores` container struct (all 22 store interfaces) |
-| `internal/store/types.go` | `BaseModel`, `StoreConfig`, `GenNewID()` |
-| `internal/store/context.go` | Context propagation: `WithUserID`, `WithAgentID`, `WithAgentType`, `WithSenderID`, `WithTenantID` |
-| `internal/store/session_store.go` | `SessionStore` interface, `SessionData`, `SessionInfo` |
-| `internal/store/memory_store.go` | `MemoryStore` interface, `MemorySearchResult`, `EmbeddingProvider` |
-| `internal/store/skill_store.go` | `SkillStore` interface |
-| `internal/store/agent_store.go` | `AgentStore` interface |
-| `internal/store/team_store.go` | `TeamStore` interface, `TeamData`, `TeamTaskData`, `DelegationHistoryData`, `TeamMessageData` |
-| `internal/store/provider_store.go` | `ProviderStore` interface |
-| `internal/store/tracing_store.go` | `TracingStore` interface, `TraceData`, `SpanData` |
-| `internal/store/mcp_store.go` | `MCPServerStore` interface, grant types, access request types |
-| `internal/store/channel_instance_store.go` | `ChannelInstanceStore` interface |
-| `internal/store/config_secrets_store.go` | `ConfigSecretsStore` interface |
-| `internal/store/pairing_store.go` | `PairingStore` interface |
-| `internal/store/cron_store.go` | `CronStore` interface |
-| `internal/store/custom_tool_store.go` | `CustomToolStore` interface |
-| `internal/store/builtin_tool_store.go` | `BuiltinToolStore` interface, system tool metadata |
-| `internal/store/pending_message_store.go` | `PendingMessageStore` interface, group message queue |
-| `internal/store/knowledge_graph_store.go` | `KnowledgeGraphStore` interface, entities and relations |
-| `internal/store/contact_store.go` | `ContactStore` interface, channel contact tracking |
-| `internal/store/activity_store.go` | `ActivityStore` interface, audit logs |
-| `internal/store/snapshot_store.go` | `SnapshotStore` interface, usage aggregation |
-| `internal/store/secure_cli_store.go` | `SecureCLIStore` interface, CLI credential injection |
-| `internal/store/api_key_store.go` | `APIKeyStore` interface, gateway API keys |
-| `internal/store/episodic_store.go` | `EpisodicStore` interface, episodic summary CRUD & hybrid search (v3 new) |
-| `internal/store/evolution_store.go` | `EvolutionMetricsStore`, `EvolutionSuggestionStore` interfaces (v3 new) |
-| `internal/store/vault_store.go` | `VaultStore` interface, document registry & links (v3 new) |
-| `internal/store/agent_link_store.go` | `AgentLinkStore` interface, delegation links (v3 new) |
-| `internal/store/pg/factory.go` | PG store factory: creates all PG store instances from a connection pool |
-| `internal/store/pg/sessions.go` | `PGSessionStore`: session cache, Save, GetOrCreate |
-| `internal/store/pg/agents.go` | `PGAgentStore`: CRUD, soft delete, access control |
-| `internal/store/pg/agents_context.go` | Agent and user context file operations |
-| `internal/store/pg/teams.go` | `PGTeamStore`: teams, tasks (atomic claim), messages, delegation history |
-| `internal/store/pg/memory_docs.go` | `PGMemoryStore`: document CRUD, indexing, chunking |
-| `internal/store/pg/memory_search.go` | Hybrid search: FTS, vector, ILIKE fallback, merge |
-| `internal/store/pg/skills.go` | `PGSkillStore`: skill CRUD and grants |
-| `internal/store/pg/skills_grants.go` | Skill agent and user grants |
-| `internal/store/pg/mcp_servers.go` | `PGMCPServerStore`: server CRUD, grants, access requests |
-| `internal/store/pg/channel_instances.go` | `PGChannelInstanceStore`: channel instance CRUD |
-| `internal/store/pg/config_secrets.go` | `PGConfigSecretsStore`: encrypted config secrets |
-| `internal/store/pg/custom_tools.go` | `PGCustomToolStore`: custom tool CRUD with encrypted env |
-| `internal/store/pg/providers.go` | `PGProviderStore`: provider CRUD with encrypted keys |
-| `internal/store/pg/tracing.go` | `PGTracingStore`: traces and spans with batch insert |
-| `internal/store/pg/pool.go` | Connection pool management |
-| `internal/store/pg/helpers.go` | Nullable helpers, JSON helpers, `execMapUpdate()`, `StructScan` |
-| `internal/store/validate.go` | Input validation utilities |
-| `internal/tools/context_keys.go` | Tool context keys including `WithToolWorkspace` |
+| Module | Path | Purpose |
+|---|---|---|
+| Store interfaces | `internal/store/` | All 22+ store interfaces (`SessionStore`, `AgentStore`, `TeamStore`, etc.), `Stores` container, context propagation helpers, v3 stores (episodic, vault, evolution, agent links) |
+| PostgreSQL implementations | `internal/store/pg/` | PG factory, `PGSessionStore`, `PGAgentStore`, `PGTeamStore`, `PGMemoryStore`, and all other PG-backed implementations; connection pool; helpers |
+| SQLite implementations | `internal/store/sqlitestore/` | SQLite-backed stores for desktop/Lite edition |
+| Tool context keys | `internal/tools/context_keys.go` | Tool context keys including `WithToolWorkspace` |
+
+Use `grep` or your editor's symbol search for specific files.
@@ -657,59 +657,14 @@ WHERE agent_id = $1

 ## File Reference

-### Bootstrap Files & Constants
-| File | Description |
-|------|-------------|
-| `internal/bootstrap/files.go` | File constants (AgentsFile, SoulFile, UserPredefinedFile, DelegationFile, TeamFile, AvailabilityFile, MemoryFile, etc.), loading, session filtering |
-| `internal/bootstrap/seed.go` | Workspace bootstrap seeding (EnsureWorkspaceFiles, embedded template FS) |
-| `internal/bootstrap/seed_store.go` | Store seeding (SeedToStore for agent-level, SeedUserFiles for per-user) |
-| `internal/bootstrap/load_store.go` | Load context files from DB (LoadFromStore) |
-| `internal/bootstrap/truncate.go` | Truncation pipeline (head/tail split, budget clamping) |
-| `internal/bootstrap/templates/*.md` | Embedded template files: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, USER_PREDEFINED.md, BOOTSTRAP.md, BOOTSTRAP_PREDEFINED.md |
+| Module | Path | Purpose |
+|---|---|---|
+| Bootstrap & seeding | `internal/bootstrap/` | File constants, truncation pipeline, workspace seeding, store seeding, embedded template files |
+| System prompt & agent resolver | `internal/agent/` | `BuildSystemPrompt`, section renderers, virtual file injection, context file merging, memory flush |
+| Skills | `internal/skills/` | 5-tier loader, BM25 search, fsnotify hot-reload; grant management in `internal/store/pg/skills*.go` |
+| Memory & consolidation | `internal/memory/`, `internal/consolidation/` | Auto-injector (L0), unified search (L1), consolidation workers (episodic, semantic, dedup, dreaming) |

-### System Prompt & Context Injection
-| File | Description |
-|------|-------------|
-| `internal/agent/systemprompt.go` | System prompt builder (BuildSystemPrompt, PromptFull/PromptMinimal modes) |
-| `internal/agent/systemprompt_sections.go` | Section renderers (17+ sections), virtual file handling (DELEGATION.md, TEAM.md, AVAILABILITY.md) |
-| `internal/agent/resolver.go` | Agent resolution, virtual file injection, negative context blocks |
-| `internal/agent/loop_history.go` | Context file merging (base + per-user, base-only preserved) |
-| `internal/agent/memoryflush.go` | Memory flush logic (shouldRunMemoryFlush, runMemoryFlush) |
-| `internal/http/summoner.go` | Agent summoning -- LLM-powered context file generation |
-| `internal/tools/filesystem.go` | File access interception (write_file, read_file), virtual file reminder handling |
-
-### Skills System
-| File | Description |
-|------|-------------|
-| `internal/skills/loader.go` | Skill loader (5-tier hierarchy, BuildSummary, inline/search mode decision) |
-| `internal/skills/search.go` | BM25 search index (tokenization, IDF scoring) |
-| `internal/skills/watcher.go` | fsnotify watcher (500ms debounce, hot-reload, version bumping) |
-| `internal/store/pg/skills.go` | Managed skill store (embedding search, auto-backfill) |
-| `internal/store/pg/skills_grants.go` | Skill grants (agent/user visibility, version pinning, RBAC) |
-
-### V3 Memory System (New)
-| File | Description |
-|------|-------------|
-| `internal/memory/auto_injector.go` | AutoInjector interface for L0 auto-injection into system prompt |
-| `internal/memory/auto_injector_impl.go` | AutoInjector implementation (episodic search + relevance filtering) |
-| `internal/memory/unified_search.go` | Hybrid search across episodic summaries + KG |
-| `internal/memory/l1_cache.go` | L1 cache for fast episodic lookups |
-| `internal/consolidation/workers.go` | Worker registration + event subscriptions |
-| `internal/consolidation/episodic_worker.go` | Extract summaries from sessions → episodic_summaries |
-| `internal/consolidation/semantic_worker.go` | Extract entities/relations from episodic → KG |
-| `internal/consolidation/dedup_worker.go` | Merge duplicate entities via embeddings |
-| `internal/consolidation/dreaming_worker.go` | Batch synthesis of episodic → long-term memory (10m debounce) |
-| `internal/consolidation/l0_abstract.go` | L0 abstract generation (~50 tokens) |
-
-### Memory Store
-| File | Description |
-|------|-------------|
-| `internal/store/episodic_store.go` | EpisodicStore interface (CRUD, search, promotion lifecycle) |
-| `internal/store/evolution_store.go` | EvolutionMetricsStore, EvolutionSuggestionStore interfaces |
-| `internal/store/vault_store.go` | VaultStore interface (document registry, links, search) |
-| `internal/store/pg/episodic*.go` | PG implementation of episodic store |
-| `internal/store/pg/memory_docs.go` | Memory document store (chunking, indexing, embedding, scoping) |
-| `internal/store/pg/memory_search.go` | Hybrid search (FTS + vector merge, weighted scoring, scope filtering) |
+Use `grep` or your editor's symbol search for specific files.

 ---

@@ -399,43 +399,14 @@ Both are periodic execution systems routed through the scheduler's cron lane, bu

 ## File Reference

-### Backend Core
-| File | Description |
-|------|-------------|
-| `internal/heartbeat/ticker.go` | Ticker loop, execution flow, suppression, active hours, stagger |
-| `internal/store/heartbeat_store.go` | Store interface, types (AgentHeartbeat, HeartbeatRunLog, HeartbeatEvent, DeliveryTarget), StaggerOffset |
-| `internal/store/pg/heartbeat.go` | PostgreSQL implementation (Get, Upsert, ListDue, UpdateState, InsertLog, ListLogs, ListDeliveryTargets) |
-| `internal/tools/heartbeat.go` | Agent-facing tool (8 actions, permission checks, auto-fill delivery) |
-| `internal/gateway/methods/heartbeat.go` | RPC handlers (8 methods, validation, cache invalidation, audit) |
+| Module | Path | Purpose |
+|---|---|---|
+| Heartbeat engine | `internal/heartbeat/`, `internal/store/heartbeat_store.go`, `internal/store/pg/heartbeat.go` | Ticker loop, store interface, PostgreSQL implementation (ListDue, UpdateState, logs) |
+| Gateway wiring | `cmd/gateway_heartbeat.go`, `cmd/gateway_cron.go`, `internal/gateway/methods/heartbeat.go` | Scheduler lane routing, cron wake integration, RPC handlers, cache invalidation |
+| Agent tool | `internal/tools/heartbeat.go` | 8-action agent-facing tool with permission checks and auto-fill delivery |
+| Frontend | `ui/web/src/pages/agents/` | `use-agent-heartbeat.ts` hook, config dialog, logs dialog, status card |

-### Scheduler Integration
-| File | Description |
-|------|-------------|
-| `cmd/gateway_heartbeat.go` | `makeHeartbeatRunFn` — routes heartbeat runs through scheduler cron lane |
-| `cmd/gateway.go` | Ticker initialization, event callback wiring, shutdown |
-| `cmd/gateway_methods.go` | RPC method registration |
-| `cmd/gateway_cron.go` | Cron wake integration (`WakeHeartbeat` flag) |
-
-### Database
-| File | Description |
-|------|-------------|
-| `migrations/000022_agent_heartbeats.up.sql` | Schema: `agent_heartbeats`, `heartbeat_run_logs`, `agent_config_permissions` |
-| `migrations/000022_agent_heartbeats.down.sql` | Rollback |
-
-### Protocol
-| File | Description |
-|------|-------------|
-| `pkg/protocol/methods.go` | RPC method constants (`MethodHeartbeatGet`, etc.) |
-| `pkg/protocol/events.go` | `EventHeartbeat = "heartbeat"` |
-
-### Frontend
-| File | Description |
-|------|-------------|
-| `ui/web/src/pages/agents/hooks/use-agent-heartbeat.ts` | React hook (config, polling, CRUD, logs, targets) |
-| `ui/web/src/pages/agents/agent-detail/heartbeat-config-dialog.tsx` | Settings dialog |
-| `ui/web/src/pages/agents/agent-detail/heartbeat-logs-dialog.tsx` | Run history viewer |
-| `ui/web/src/pages/agents/agent-detail/overview-sections/heartbeat-card.tsx` | Status display card |
-| `ui/web/src/api/protocol.ts` | RPC + event constants |
+Use `grep` or your editor's symbol search for specific files.

 ---