refactor: modularize runtime and refresh docs

Author: rexleimo

README.md

@@ -16,6 +16,8 @@ LoopForge  is a **personal AI engineer** for software delivery: long-running wor
 - (If the custom domain isn’t configured yet) GitHub Pages: https://rexleimo.github.io/LoopForge/
 - 5-minute outcomes: `docs-site/tutorials/five-minute-outcomes.md`
 - Positioning: `docs-site/explanation/why-loopforge.md`
+- Runtime architecture: `docs-site/explanation/runtime-architecture.md`
+- Internal maintainer map: `docs/internal/runtime-module-map.md`
 
 ## Status
 

README.zh-CN.md

@@ -16,6 +16,8 @@ LoopForge是一个面向软件交付的 **个人研发助理（Personal AI Engin
 - （如自定义域名未配置）GitHub Pages：https://rexleimo.github.io/LoopForge/
 - 5 分钟可见结果：`docs-site/tutorials/five-minute-outcomes.md`
 - 产品定位说明：`docs-site/explanation/why-loopforge.md`
+- 运行时架构说明：`docs-site/explanation/runtime-architecture.md`
+- 仓库内部维护者地图：`docs/internal/runtime-module-map.md`
 
 ## 状态
 

crates/loopforge-cli/src/cli.rs

@@ -0,0 +1,9 @@
+mod commands;
+
+#[cfg(test)]
+mod tests;
+
+pub(crate) use commands::{
+    AcpCommand, AgentCommand, AgentKind, ChannelCommand, Cli, Command, ConfigCommand,
+    DaemonCommand, HarnessCommand, ReleaseCommand, SkillsCommand,
+};

crates/loopforge-cli/src/cli/commands.rs

@@ -0,0 +1,109 @@
+mod acp;
+mod agent;
+mod channel;
+mod config;
+mod daemon;
+mod harness;
+mod release;
+mod skills;
+
+use clap::Parser;
+use std::path::PathBuf;
+
+use crate::onboard::OnboardStarter;
+
+pub(crate) use acp::AcpCommand;
+pub(crate) use agent::{AgentCommand, AgentKind};
+pub(crate) use channel::ChannelCommand;
+pub(crate) use config::ConfigCommand;
+pub(crate) use daemon::DaemonCommand;
+pub(crate) use harness::HarnessCommand;
+pub(crate) use release::ReleaseCommand;
+pub(crate) use skills::SkillsCommand;
+
+#[derive(Debug, Parser)]
+#[command(name = "loopforge")]
+#[command(
+    about = "LoopForge: long-running agent operating system",
+    long_about = None
+)]
+pub(crate) struct Cli {
+    #[command(subcommand)]
+    pub(crate) command: Command,
+}
+
+#[derive(Debug, clap::Subcommand)]
+pub(crate) enum Command {
+    /// Initialize ~/.loopforge (config + database)
+    Init,
+    /// One-command onboarding check (init + config + doctor + optional first task)
+    Onboard {
+        /// Workspace directory for the first verification run
+        #[arg(long, default_value = "loopforge-onboard-demo")]
+        workspace: PathBuf,
+        /// Optional explicit prompt for the first verification run
+        #[arg(long)]
+        prompt: Option<String>,
+        /// Starter profile used when `--prompt` is not provided
+        #[arg(long, value_enum, default_value_t = OnboardStarter::Hello)]
+        starter: OnboardStarter,
+        /// Skip running the first agent task and only run setup checks
+        #[arg(long)]
+        skip_agent: bool,
+        /// Timeout for doctor probes (milliseconds)
+        #[arg(long, default_value_t = 1500)]
+        timeout_ms: u64,
+    },
+    /// Diagnose common setup issues (config, providers, browser, tooling)
+    Doctor {
+        /// Print JSON output (machine-readable)
+        #[arg(long)]
+        json: bool,
+        /// Exit non-zero if any warnings are detected
+        #[arg(long)]
+        strict: bool,
+        /// Timeout for network probes (milliseconds)
+        #[arg(long, default_value_t = 1500)]
+        timeout_ms: u64,
+    },
+    /// Run an agent session (LLM + tools + memory)
+    Agent {
+        #[command(subcommand)]
+        command: AgentCommand,
+    },
+    /// Outbound channels (outbox + dispatcher)
+    Channel {
+        #[command(subcommand)]
+        command: ChannelCommand,
+    },
+    /// ACP event/checkpoint inspection helpers
+    Acp {
+        #[command(subcommand)]
+        command: AcpCommand,
+    },
+    /// Config helpers
+    Config {
+        #[command(subcommand)]
+        command: ConfigCommand,
+    },
+    /// Skills discovery, doctor and execution helpers
+    Skills {
+        #[command(subcommand)]
+        command: SkillsCommand,
+    },
+    /// Long-running harness helpers (initializer + sessions)
+    Harness {
+        #[command(subcommand)]
+        command: HarnessCommand,
+    },
+    /// Run LoopForge daemon (HTTP API)
+    Daemon {
+        #[command(subcommand)]
+        command: DaemonCommand,
+    },
+    /// Release assistants (metadata + preflight checks)
+    Release {
+        #[command(subcommand)]
+        command: ReleaseCommand,
+    },
+}

crates/loopforge-cli/src/cli/commands/acp.rs

@@ -0,0 +1,24 @@
+#[derive(Debug, clap::Subcommand)]
+pub(crate) enum AcpCommand {
+    /// List recent ACP events
+    Events {
+        /// Optional session id filter
+        #[arg(long)]
+        session: Option<String>,
+        /// Max events to print
+        #[arg(long, default_value_t = 100)]
+        limit: usize,
+        /// Print JSON output (machine-readable)
+        #[arg(long)]
+        json: bool,
+    },
+    /// Show ACP delivery checkpoints for one session
+    Checkpoints {
+        /// Session id
+        #[arg(long)]
+        session: String,
+        /// Print JSON output (machine-readable)
+        #[arg(long)]
+        json: bool,
+    },
+}

crates/loopforge-cli/src/cli/commands/agent.rs

@@ -0,0 +1,43 @@
+use std::path::PathBuf;
+
+#[derive(Debug, clap::Subcommand)]
+pub(crate) enum AgentCommand {
+    /// Run a single agent session in a workspace
+    Run {
+        /// Workspace root directory (tools are sandboxed to this path)
+        #[arg(long)]
+        workspace: PathBuf,
+        /// User instruction for this run
+        #[arg(long)]
+        prompt: String,
+        /// Optional system prompt (string)
+        #[arg(long)]
+        system: Option<String>,
+        /// Optional session id (generated if omitted)
+        #[arg(long)]
+        session: Option<String>,
+        /// Task kind for model routing
+        #[arg(long, value_enum, default_value_t = AgentKind::Coding)]
+        kind: AgentKind,
+        /// Comma-separated allowed tool names for this session (session-level whitelist)
+        #[arg(long, value_delimiter = ',')]
+        allowed_tools: Vec<String>,
+    },
+}
+
+#[derive(Debug, Clone, Copy, clap::ValueEnum)]
+pub(crate) enum AgentKind {
+    Planning,
+    Coding,
+    Summary,
+}
+
+impl From<AgentKind> for rexos::router::TaskKind {
+    fn from(value: AgentKind) -> Self {
+        match value {
+            AgentKind::Planning => rexos::router::TaskKind::Planning,
+            AgentKind::Coding => rexos::router::TaskKind::Coding,
+            AgentKind::Summary => rexos::router::TaskKind::Summary,
+        }
+    }
+}

crates/loopforge-cli/src/cli/commands/channel.rs

@@ -0,0 +1,18 @@
+#[derive(Debug, clap::Subcommand)]
+pub(crate) enum ChannelCommand {
+    /// Drain queued outbox messages once
+    Drain {
+        /// Max messages to attempt in one run
+        #[arg(long, default_value_t = 50)]
+        limit: usize,
+    },
+    /// Run a long-lived worker that periodically drains the outbox
+    Worker {
+        /// Seconds between drain attempts
+        #[arg(long, default_value_t = 5)]
+        interval_secs: u64,
+        /// Max messages to attempt per drain cycle
+        #[arg(long, default_value_t = 50)]
+        limit: usize,
+    },
+}

crates/loopforge-cli/src/cli/commands/config.rs

@@ -0,0 +1,9 @@
+#[derive(Debug, clap::Subcommand)]
+pub(crate) enum ConfigCommand {
+    /// Validate ~/.loopforge/config.toml and exit non-zero when invalid
+    Validate {
+        /// Print JSON output (machine-readable)
+        #[arg(long)]
+        json: bool,
+    },
+}

crates/loopforge-cli/src/cli/commands/daemon.rs

@@ -0,0 +1,9 @@
+#[derive(Debug, clap::Subcommand)]
+pub(crate) enum DaemonCommand {
+    /// Start the daemon HTTP server
+    Start {
+        /// Listen address, e.g. 127.0.0.1:8787
+        #[arg(long, default_value = "127.0.0.1:8787")]
+        addr: String,
+    },
+}

crates/loopforge-cli/src/cli/commands/harness.rs

@@ -0,0 +1,28 @@
+use std::path::PathBuf;
+
+#[derive(Debug, clap::Subcommand)]
+pub(crate) enum HarnessCommand {
+    /// Initialize a workspace directory for long-running agent sessions
+    Init {
+        dir: PathBuf,
+        /// Optional initializer prompt (generates a comprehensive features.json)
+        #[arg(long)]
+        prompt: Option<String>,
+        /// Override session id (default: persisted per-workspace)
+        #[arg(long)]
+        session: Option<String>,
+    },
+    /// Run a harness session (preflight + agent run)
+    Run {
+        dir: PathBuf,
+        /// User instruction for this session (if omitted, only runs preflight)
+        #[arg(long)]
+        prompt: Option<String>,
+        /// Override session id (default: derived UUID per run)
+        #[arg(long)]
+        session: Option<String>,
+        /// Max attempts when init.sh fails (default 3)
+        #[arg(long, default_value_t = 3)]
+        max_attempts: usize,
+    },
+}