Merge branch 'main' of https://git.terraphim.cloud/terraphim/terraphim-ai

Author: Alex

.docs/summary-crates-terraphim_orchestrator-src-lib.rs.md

@@ -0,0 +1,49 @@
+# Summary: terraphim_orchestrator/src/lib.rs
+
+**Purpose:** Multi-agent orchestration with scheduling, budgeting, and compound review for the "dark factory" pattern.
+
+**Core Components:**
+- **AgentOrchestrator**: Main orchestrator running dark factory pattern
+- **DualModeOrchestrator**: Real-time and batch processing with fairness scheduling
+- **CompoundReviewWorkflow**: Multi-agent review swarm with persona-based specialization
+- **Scheduler**: Time-based and event-driven task scheduling
+- **HandoffBuffer**: Inter-agent state transfer with TTL management
+- **CostTracker**: Budget enforcement and spending monitoring
+- **NightwatchMonitor**: Drift detection and rate limiting
+- **MetaCoordinator**: Cross-project issue-driven agent dispatch with PageRank prioritisation
+
+**Key Modules:**
+- `adf_commands`: ADF-specific command handling
+- `compound`: Compound review workflow with swarm config
+- `control_plane`: Routing and fleet management
+- `cost_tracker`: Metrics, verdicts, budget tracking
+- `dispatcher`: Task dispatch with stats
+- `evolution`: Agent evolution with memory snapshots
+- `handoff`: Inter-agent state transfer
+- `kg_router`: Knowledge graph-based routing
+- `pr_dispatch`, `pr_gate`, `pr_review`: PR lifecycle management
+- `provider_probe`: LLM provider health monitoring
+
+**Key Exports:**
+- `AgentRunRecord`, `ExitClass`, `ExitClassification`
+- `CompoundReviewResult`, `SwarmConfig`
+- `DualModeOrchestrator`
+- `CostTracker`, `AgentMetrics`, `BudgetVerdict`
+- `Dispatcher`, `DispatchTask`
+- `HandoffBuffer`, `HandoffContext`
+- `MentionTracker`, `MentionChainTracker`
+- `OrchestratorConfig`, `AgentDefinition`, `AgentLayer`
+
+**Configuration:**
+- OrchestratorConfig for main settings
+- AgentDefinition with evolution, model, capabilities
+- CompoundReviewConfig for review workflows
+- NightwatchConfig for rate limiting
+- WebhookConfig for output posting
+
+**Features:**
+- PageRank-based issue prioritisation
+- Token budget tracking with time limits
+- Agent learning capture and evolution
+- Multi-provider LLM routing (kimi, opencode-go, minimax, claude, etc.)
+- Quickwit integration for log search

.docs/summary-crates-terraphim_rlm-src-lib.rs.md

@@ -0,0 +1,49 @@
+# Summary: terraphim_rlm/src/lib.rs
+
+**Purpose:** Recursive Language Model (RLM) orchestration with isolated Firecracker VM execution, sub-500ms allocation, and knowledge graph validation.
+
+**Architecture:**
+```
+TerraphimRlm (public API)
+    ├── SessionManager (VM affinity, context, snapshots, extensions)
+    ├── QueryLoop (command parsing, execution, result handling)
+    ├── BudgetTracker (token counting, time tracking, depth limits)
+    └── KnowledgeGraphValidator (term matching, retry, strictness)
+
+ExecutionEnvironment trait
+    ├── FirecrackerExecutor (primary, full isolation)
+    ├── DockerExecutor (fallback, gVisor/runc)
+    └── E2bExecutor (cloud option)
+```
+
+**Core Modules:**
+- `config`: BackendType, KgStrictness, RlmConfig, SessionModel
+- `executor`: Execution environment abstraction
+- `budget`: BudgetTracker for token/time limits
+- `session`: Session management with VM affinity
+- `llm_bridge`: LLM invocation from within VMs
+- `parser`: Command parsing
+- `query_loop`: Query execution loop
+- `rlm`: Main RLM orchestration
+- `logger`: Trajectory logging
+
+**Key Types:**
+- `RlmConfig`: Configuration with timeout, model, strictness settings
+- `RlmError`: Error types
+- `ExecutionResult`: Command/code execution result
+- `SnapshotId`: VM snapshot identifier
+- `ValidationResult`: KG validation result
+- `QueryRequest`, `QueryResponse`: LLM bridge types
+- `TrajectoryEvent`: Logging event
+
+**Features:**
+- Firecracker microVM isolation with sub-500ms boot
+- Dual budget system (tokens + time)
+- VM snapshots and resume
+- SSH executor for remote execution
+- Knowledge graph command validation
+- Trajectory logging for audit
+
+**Cargo Features:**
+- `kg-validation`: Enable KG validation
+- `mcp`: MCP tools support

.docs/summary-crates-terraphim_symphony-src-lib.rs.md

@@ -0,0 +1,34 @@
+# Summary: terraphim_symphony/src/lib.rs
+
+**Purpose:** Long-running orchestration service that reads from issue trackers, creates per-issue workspaces, and runs coding agent sessions.
+
+**Core Components:**
+- **OrchestratorRuntimeState**: Runtime state management
+- **SymphonyOrchestrator**: Main orchestrator
+- **WorkspaceManager**: Per-issue workspace lifecycle
+- **IssueTracker**: Issue tracking integration (Gitea)
+- **Worker**: Agent execution with outcome tracking
+
+**Key Modules:**
+- `api`: HTTP API endpoints
+- `config`: Configuration management
+- `error`: Error types
+- `orchestrator`: Main orchestration logic
+- `runner`: Agent execution with CodexSession
+- `tracker`: Issue tracking (Gitea)
+- `workspace`: Workspace lifecycle
+
+**Key Exports:**
+- `SymphonyOrchestrator`, `OrchestratorRuntimeState`, `StateSnapshot`
+- `WorkerOutcome`, `AgentEvent`, `CodexSession`
+- `ReviewAgentOutput`, `ReviewFinding`, `FindingCategory`, `FindingSeverity`
+- `TokenCounts`, `TokenTotals`
+- `Issue`, `IssueTracker`
+- `WorkspaceManager`
+
+**Features:**
+- Isolated per-issue workspaces
+- Agent session management (Codex)
+- Finding deduplication
+- Token tracking and budgets
+- Gitea issue integration

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **terraphim_rlm CLI binary** with 6 commands (code, bash, query, context, snapshot, status) for stateless RLM execution (Refs #RLM-CLI, 2026-05-18)
+- **MCP server RLM integration** via process spawning — 6 new tools exposed without linking terraphim_rlm (avoids static init hang) (Refs #RLM-CLI, 2026-05-18)
 - **Session search capability** enabled in `terraphim_agent` binary (2026-05-17)
 - **Evolution integration** `terraphim_agent_evolution` wired into ADF orchestrator (Refs #1487, 2026-05-15)
 - **Ranking regression gate** Kendall-tau snapshot tests added to prevent ranking regressions (Refs #1454, 2026-05-16)