refactor(cli): remove start alias and update CLI help text

- remove `start` as an alias of `serve`
- refresh docs and install script to use `serve`
- update CLI help text for IM room/user commands

Author: RussellLuo

Makefile

@@ -55,7 +55,7 @@ build: boxlite-setup
 	env GOCACHE=$(GOCACHE) $(GO) build -ldflags "$(LDFLAGS)" -o $(BIN) ./cmd/csgclaw
 
 run: boxlite-setup
-	env GOCACHE=$(GOCACHE) $(GO) run -ldflags "$(LDFLAGS)" ./cmd/csgclaw start
+	env GOCACHE=$(GOCACHE) $(GO) run -ldflags "$(LDFLAGS)" ./cmd/csgclaw serve
 
 onboard: boxlite-setup
 	env GOCACHE=$(GOCACHE) $(GO) run -ldflags "$(LDFLAGS)" ./cmd/csgclaw onboard \

cli/app.go

@@ -56,7 +56,7 @@ func (a *App) Execute(ctx context.Context, args []string) error {
 	switch rest[0] {
 	case "onboard":
 		return a.runOnboard(rest[1:], globals)
-	case "serve", "start":
+	case "serve":
 		if a.serveFunc != nil {
 			return a.serveFunc(ctx, rest[1:], globals)
 		}
@@ -147,11 +147,10 @@ func (a *App) usage() {
 	fmt.Fprintln(a.stderr, "Available Commands:")
 	fmt.Fprintln(a.stderr, "  onboard  Initialize local config and bootstrap state")
 	fmt.Fprintln(a.stderr, "  serve    Start the local HTTP server")
-	fmt.Fprintln(a.stderr, "  start    Alias for serve")
 	fmt.Fprintln(a.stderr, "  stop     Stop the local HTTP server")
 	fmt.Fprintln(a.stderr, "  agent    Manage agents")
-	fmt.Fprintln(a.stderr, "  room     Manage rooms")
-	fmt.Fprintln(a.stderr, "  user     Manage users")
+	fmt.Fprintln(a.stderr, "  room     Manage IM rooms")
+	fmt.Fprintln(a.stderr, "  user     Manage IM users")
 	fmt.Fprintln(a.stderr)
 	fmt.Fprintln(a.stderr, "Examples:")
 	fmt.Fprintln(a.stderr, "  csgclaw -h")

cli/app_test.go

@@ -359,8 +359,8 @@ func TestUsageIncludesTopLevelCommandIndex(t *testing.T) {
 	for _, want := range []string{
 		"Available Commands:",
 		"agent    Manage agents",
-		"room     Manage rooms",
-		"user     Manage users",
+		"room     Manage IM rooms",
+		"user     Manage IM users",
 	} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("usage = %q, want substring %q", got, want)
@@ -385,8 +385,8 @@ func TestRootHelpIncludesAvailableCommands(t *testing.T) {
 	for _, want := range []string{
 		"Available Commands:",
 		"agent    Manage agents",
-		"room     Manage rooms",
-		"user     Manage users",
+		"room     Manage IM rooms",
+		"user     Manage IM users",
 	} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("help = %q, want substring %q", got, want)
@@ -488,29 +488,23 @@ func TestAgentSubcommandHelpIncludesUsageAndFlags(t *testing.T) {
 	}
 }
 
-func TestExecuteStartRemainsServeAlias(t *testing.T) {
-	called := false
+func TestExecuteStartIsRejected(t *testing.T) {
+	var stderr bytes.Buffer
 	app := &App{
 		stdout:     &bytes.Buffer{},
-		stderr:     &bytes.Buffer{},
+		stderr:     &stderr,
 		httpClient: roundTripFunc(func(req *http.Request) (*http.Response, error) { return nil, nil }),
-		serveFunc: func(_ context.Context, args []string, globals GlobalOptions) error {
-			called = true
-			if len(args) != 0 {
-				t.Fatalf("args = %v, want empty", args)
-			}
-			if globals.Config != "/tmp/test.toml" {
-				t.Fatalf("globals.Config = %q, want /tmp/test.toml", globals.Config)
-			}
-			return nil
-		},
 	}
 
-	if err := app.Execute(context.Background(), []string{"--config", "/tmp/test.toml", "start"}); err != nil {
-		t.Fatalf("Execute() error = %v", err)
+	err := app.Execute(context.Background(), []string{"--config", "/tmp/test.toml", "start"})
+	if err == nil {
+		t.Fatal("Execute() error = nil, want unknown command")
+	}
+	if !strings.Contains(err.Error(), `unknown command "start"`) {
+		t.Fatalf("Execute() error = %v, want unknown command start", err)
 	}
-	if !called {
-		t.Fatal("serveFunc was not called for start alias")
+	if !strings.Contains(stderr.String(), "  serve    Start the local HTTP server") {
+		t.Fatalf("stderr = %q, want serve command in usage", stderr.String())
 	}
 }
 

cli/room.go

@@ -11,15 +11,15 @@ import (
 
 func (a *App) runRoom(ctx context.Context, args []string, globals GlobalOptions) error {
 	if len(args) == 0 {
-		a.usageCommandGroup("room", "Manage rooms.", "csgclaw room <subcommand> [flags]", []string{
+		a.usageCommandGroup("room", "Manage IM rooms.", "csgclaw room <subcommand> [flags]", []string{
 			"list               List rooms",
 			"create             Create a room",
 			"delete <id>        Delete a room",
 		})
 		return flag.ErrHelp
 	}
 	if isHelpArg(args[0]) {
-		a.usageCommandGroup("room", "Manage rooms.", "csgclaw room <subcommand> [flags]", []string{
+		a.usageCommandGroup("room", "Manage IM rooms.", "csgclaw room <subcommand> [flags]", []string{
 			"list               List rooms",
 			"create             Create a room",
 			"delete <id>        Delete a room",
@@ -35,7 +35,7 @@ func (a *App) runRoom(ctx context.Context, args []string, globals GlobalOptions)
 	case "delete":
 		return a.runRoomDelete(ctx, args[1:], globals)
 	default:
-		a.usageCommandGroup("room", "Manage rooms.", "csgclaw room <subcommand> [flags]", []string{
+		a.usageCommandGroup("room", "Manage IM rooms.", "csgclaw room <subcommand> [flags]", []string{
 			"list               List rooms",
 			"create             Create a room",
 			"delete <id>        Delete a room",

cli/user.go

@@ -10,14 +10,14 @@ import (
 
 func (a *App) runUser(ctx context.Context, args []string, globals GlobalOptions) error {
 	if len(args) == 0 {
-		a.usageCommandGroup("user", "Manage users.", "csgclaw user <subcommand> [flags]", []string{
+		a.usageCommandGroup("user", "Manage IM users.", "csgclaw user <subcommand> [flags]", []string{
 			"list               List users",
 			"kick <id>          Remove a user",
 		})
 		return flag.ErrHelp
 	}
 	if isHelpArg(args[0]) {
-		a.usageCommandGroup("user", "Manage users.", "csgclaw user <subcommand> [flags]", []string{
+		a.usageCommandGroup("user", "Manage IM users.", "csgclaw user <subcommand> [flags]", []string{
 			"list               List users",
 			"kick <id>          Remove a user",
 		})
@@ -30,7 +30,7 @@ func (a *App) runUser(ctx context.Context, args []string, globals GlobalOptions)
 	case "kick":
 		return a.runUserKick(ctx, args[1:], globals)
 	default:
-		a.usageCommandGroup("user", "Manage users.", "csgclaw user <subcommand> [flags]", []string{
+		a.usageCommandGroup("user", "Manage IM users.", "csgclaw user <subcommand> [flags]", []string{
 			"list               List users",
 			"kick <id>          Remove a user",
 		})

docs/README.go.md

@@ -3,7 +3,7 @@
 This repository now includes a minimal Go implementation for:
 
 - `csgclaw onboard`
-- `csgclaw start`
+- `csgclaw serve`
 - `POST /api/v1/workers`
 
 Notes:

docs/architecture.md

@@ -27,7 +27,7 @@ Both capabilities are exposed through a unified HTTP server and a single CLI bin
           ┌──────────▼──────┐  ┌────────▼──────────┐
           │  Agent Manager  │  │     IM System      │
           │                 │  │                    │
-          │  start / stop   │  │  rooms / users     │
+          │  serve / stop   │  │  rooms / users     │
           │  status / logs  │  │  messaging / push  │
           └──────┬──────────┘  └────────┬───────────┘
                  │                      │
@@ -392,4 +392,4 @@ User A sends message (WebSocket)
 | Sandbox | Boxlite | Fixed choice; called directly, no abstraction layer needed |
 | Storage | Filesystem | Simple, zero dependencies, sufficient for project scale |
 | WebSocket | `gorilla/websocket` or stdlib | Managed in `hub.go`; one goroutine per connection |
-| Frontend | Framework of choice | Served as static assets by the HTTP server |
+| Frontend | Framework of choice | Served as static assets by the HTTP server |

docs/design/cli.md

@@ -5,7 +5,7 @@
 1. Server: 支持通过REST API创建一个Agent，一个Agent包括name, image等必要参数
 2. CLI: 支持两个子命令
     - csgclaw onboard: 初始化 ~/.csgclaw/config.toml（里面最基本可以配置llm model的base_url、api_key和model_id）
-    - csgclaw start: 以daemon形式启动上述Server
+    - csgclaw serve: 启动上述 Server（可通过 `-d` 以 daemon 形式运行）
 
 ## Go SDK用法
 

docs/design/progress.md

@@ -12,7 +12,7 @@
 
 - [x] 明确首期目标是建设一个标准 Go 项目，同时覆盖 Server 与 CLI 两部分能力。
 - [x] 明确 Server 侧核心职责：通过 REST API 创建 Agent，并支持 `name`、`image` 等必要参数。
-- [x] 定义 CLI 主流程，包括 `onboard`、`start`、`create` 三个子命令，分别对应本地配置初始化、守护进程启动和 Agent 创建。
+- [x] 定义 CLI 主流程，包括 `onboard`、`serve`、`create` 三个子命令，分别对应本地配置初始化、服务启动和 Agent 创建。
 - [x] 初步确定配置方案，`~/.csgclaw/config.toml` 用于承载模型接入所需的 `base_url`、`api_key` 和 `model_id` 等基础参数。
 - [x] 完成 BoxLite Go SDK 与 Python SDK 的技术调研，并确认 vendored SDK、`go generate`、运行时创建 box、端口映射、数据卷挂载等关键集成点。
 - [x] 沉淀容器化运行 OpenClaw / Agent Gateway 的配置与启动样例，可作为后续 Server daemon 化和本地开发联调的实现参考。

docs/progress.md

@@ -13,7 +13,7 @@
 
 当前项目已经具备一个最小闭环，但与 `docs/architecture.md` 的目标架构相比，仍然更接近“单二进制 + 内嵌服务对象 + 面向当前 IM/PicoClaw 场景的专用 API”：
 
-- CLI 入口集中在 `cmd/csgclaw/main.go`，当前只有 `onboard`、`start`、`_serve` 三类命令。
+- CLI 入口集中在 `cmd/csgclaw/main.go`，当前对外入口以 `onboard`、`serve`、`stop` 与资源型子命令为主，内部仍保留 `_serve` 作为守护进程子进程入口。
 - HTTP 路由与 handler 已拆到 `internal/api/`，`internal/server/` 主要负责 server lifecycle、mux 装配与 UI 托管。
 - Agent 能力目前以 `worker` 为中心暴露，核心入口是 `GET/POST /api/v1/workers`。
 - IM 能力目前以 `/api/v1/im/*` 命名空间和 SSE 为主，不是目标文档里的扁平 REST + WebSocket 结构。
@@ -34,7 +34,7 @@
 - `现状`：[`cmd/csgclaw/main.go`](/Users/russellluo/Projects/work/opencsg/projects/csgclaw/cmd/csgclaw/main.go) 已切到 `cli.New().Execute(...)`；[`cli/`](/Users/russellluo/Projects/work/opencsg/projects/csgclaw/cli) 中已经补齐 `agent create/delete/status`、`room list/create/delete`、`user list/kick`，`message` 命令树和 `agent logs` 仍未实现。
 - `影响`：CLI 和服务端生命周期耦合，后续很难平滑过渡到“远程可调用”的命令模型。
 - `推荐增量步骤`：
-  - [x] A01-1 新增 `serve` 命令，内部先复用当前 `start` 逻辑，保留 `start` 作为兼容别名。
+  - [x] A01-1 新增 `serve` 命令并承接服务启动入口；后续已移除 `start` 兼容别名。
   - [x] A01-2 新增 `stop` 命令，先基于当前后台进程管理方式落地，哪怕暂时仍沿用现有状态目录。
   - [x] A01-3 引入 `cli/` 目录并抽出 root/serve/stop 的命令注册，`main.go` 只保留启动装配。
   - [x] A01-4 为后续资源型命令准备统一 HTTP client 和全局 flag 骨架。