docs：README 補上完整安裝指南（#15）

README.md

@@ -11,12 +11,47 @@ teai 是 Gitea 的命令列（CLI）工具，以更完整、更可靠的方式
 
 ## 安裝與建置
 
-需要 Go 1.26 以上。
+### 需求
+
+- **Go 1.26 以上**（`go version` 確認；本倉庫僅用標準庫，離線可建置）
+- **git**
+- Gitea 帳號的 **API token**（設定階段使用；在 Gitea「設定 → 應用程式」產生）
+
+### 從原始碼建置
 
 ```sh
+git clone https://gitea.alterminal.com/alterminal/teai.git
+cd teai
 go build -o teai ./cmd/teai
+install -Dm755 teai ~/.local/bin/teai   # 或複製到任何 PATH 內目錄
+teai version                             # 驗證：teai version 0.1.0-dev
 ```
 
+也可以直接裝進 `GOBIN`（預設 `~/go/bin`；該目錄已在 PATH 時最省事）：
+
+```sh
+go install ./cmd/teai
+```
+
+> **注意：** `go install gitea.alterminal.com/alterminal/teai/cmd/teai@latest` 目前**不可用**——
+> module 尚未發佈任何 tag，`@latest` 會解析到任意中繼 commit（且 #21 修復前 main 建置失敗）。
+> 請在 clone 目錄內以版本控制的方式建置；發佈 tag 後再提供 `teai@<version>` 安裝路徑。
+
+### 登入設定（首次使用）
+
+teai 與 `tea` 共用同一份組態檔；若 `tea whoami` 已可正常輸出，可跳過本節。
+
+```sh
+teai login add --url https://gitea.alterminal.com
+# 未給 --token 時自 stdin 讀一行：貼上 token 後按 Enter（不會進 shell 歷史）
+teai whoami    # 驗證：應輸出 {"username":"<你的帳號>"}
+```
+
+- token 驗證失敗（HTTP 401）不會寫入組態，結束碼 3。
+- 組態檔：`--config`／`TEA_CONFIG` 指定，預設 `~/.config/tea/config.yml`；teai 採行級編輯，
+  不會改壞 tea 也在使用的欄位，檔案權限 `0600`。
+- 多站台以 `--name` 區分、`teai login default <名稱>` 切換預設；詳見下方 [`teai login`](#teai-login--管理登入) 一節。
+
 ## 指令設計
 
 > 工作流規則的唯一來源是 [`alterminal/agents`](https://gitea.alterminal.com/alterminal/agents) 的 `AGENTS.md`；

internal/cli/cli.go

@@ -150,10 +150,31 @@ var globalFlags = map[string]bool{
 	"--timeout": true,
 }
 
+// reservedFlags 回傳 dispatch 不得搶走的旗標名稱（含 -- 前綴）：這些
+// 旗標屬於目前命令（或其子命令），即使與全域選項同名也必須原樣留給
+// 命令剖析。目前唯一與全域同名的是 login add 的 --url／--token
+// （README「teai login add --url … --token …」）。其餘命令的旗標
+// （--repo、--has-work、--mine……）本來就不在 globalFlags 內，不受影響。
+func reservedFlags(name string) map[string]bool {
+	reserved := make(map[string]bool)
+	for _, f := range commandReservedFlags[name] {
+		reserved[f] = true
+	}
+	return reserved
+}
+
+// commandReservedFlags 登記每個命令「與全域選項同名」的自有旗標。
+// 命令旗標優先留給命令；新命令有同姓旗標時在這裡登記（#18）。
+var commandReservedFlags = map[string][]string{
+	"login": {"--url", "--token"},
+}
+
 // extractGlobals 從 args 中「抽取」全域選項（可出現在命令之後、與命令
 // 旗標交錯），其餘引數依原順序保留給子命令剖析。未知的選項一律留給
 // 子命令處理（可能是命令旗標，如 --has-work），不在這裡報錯。
-func extractGlobals(g *Globals, args []string) ([]string, error) {
+// reserved 是目前命令保留的旗標名稱（含 -- 前綴，見 reservedFlags）：
+// 列於其中的選項即使與全域同名也原樣留給命令，命令旗標優先（#18）。
+func extractGlobals(g *Globals, args []string, reserved map[string]bool) ([]string, error) {
 	rest := make([]string, 0, len(args))
 	applyGlobal := func(name, value string) error {
 		switch name {
@@ -197,6 +218,17 @@ func extractGlobals(g *Globals, args []string) ([]string, error) {
 			continue
 		}
 		name, inline, hasInline := strings.Cut(arg, "=")
+		if reserved[name] {
+			// 命令保留旗標：即使與全域選項同名也留給命令剖析（#18）。
+			rest = append(rest, arg)
+			if !hasInline && i+1 < len(args) {
+				// 旗標值跟在下一個引數；一併保留，不當成全域值。
+				rest = append(rest, args[i+1])
+				i++
+			}
+			i++
+			continue
+		}
 		_, ok := globalFlags[name]
 		if !ok {
 			// 不是全域選項：留給子命令（可能是 --has-work 這類命令旗標）。
@@ -293,11 +325,12 @@ func parseGlobals(g *Globals, args []string) ([]string, error) {
 // 旗標剖析交由各命令自行處理（不同命令有不同旗標，如 pulls --mine）；
 // 全域選項允許出現在命令之後（README 範例：teai next --output table），
 // dispatch 先從 args 剝離全域選項併入 Globals，其餘（含命令自己的旗標，
-// 如 --has-work）原樣交給命令，不會誤判為未知全域選項。
+// 如 --has-work）原樣交給命令，不會誤判為未知全域選項。與全域選項
+// 同名的命令旗標（登記於 commandReservedFlags）優先留給命令（#18）。
 func dispatch(env *Env, name string, args []string) int {
 	cmd := commands[name]
 	g := env.Globals
-	rest, err := extractGlobals(&g, args)
+	rest, err := extractGlobals(&g, args, reservedFlags(name))
 	if err != nil {
 		fmt.Fprintf(env.Err, "teai: %v\n\n", err)
 		printUsage(env.Err)

internal/cli/exitcode_test.go

@@ -79,7 +79,7 @@ func TestExtractGlobals(t *testing.T) {
 		"--output", "table",
 		"--timeout", "45s",
 		"next",
-	})
+	}, nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -100,7 +100,7 @@ func TestExtractGlobals(t *testing.T) {
 func TestExtractGlobalsAfterCommand(t *testing.T) {
 	// 全域選項出現在命令之後也應抽出（README：teai next --output table）。
 	g := defaultGlobals()
-	rest, err := extractGlobals(&g, []string{"version", "--output", "table"})
+	rest, err := extractGlobals(&g, []string{"version", "--output", "table"}, nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -124,7 +124,7 @@ func TestExtractGlobalsKeepsCommandFlags(t *testing.T) {
 	}
 	for _, args := range cases {
 		g := defaultGlobals()
-		rest, err := extractGlobals(&g, args)
+		rest, err := extractGlobals(&g, args, nil)
 		if err != nil {
 			t.Fatalf("extractGlobals(%v) 不應報錯：%v", args, err)
 		}
@@ -145,7 +145,7 @@ func TestExtractGlobalsKeepsCommandFlags(t *testing.T) {
 
 func TestExtractGlobalsDoubleDashStops(t *testing.T) {
 	g := defaultGlobals()
-	rest, err := extractGlobals(&g, []string{"--output", "table", "--", "--url", "x"})
+	rest, err := extractGlobals(&g, []string{"--output", "table", "--", "--url", "x"}, nil)
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -158,6 +158,56 @@ func TestExtractGlobalsDoubleDashStops(t *testing.T) {
 	}
 }
 
+// TestExtractGlobalsReservedFlags 驗證 #18：與全域同名的命令旗標
+// （登記於 commandReservedFlags）必須留給命令，其餘全域選項照常抽取。
+func TestExtractGlobalsReservedFlags(t *testing.T) {
+	g := defaultGlobals()
+	rest, err := extractGlobals(&g, []string{
+		"add",
+		"--url", "https://srv.example.com", // login add 自有旗標：保留
+		"--token=tok", // 同上（inline 形式）：保留
+		"--name", "test-site",
+		"--output", "table", // 非保留：仍是全域
+	}, reservedFlags("login"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []string{"add", "--url", "https://srv.example.com", "--token=tok", "--name", "test-site"}
+	if len(rest) != len(want) {
+		t.Fatalf("rest = %v, want %v", rest, want)
+	}
+	for i := range want {
+		if rest[i] != want[i] {
+			t.Fatalf("rest = %v, want %v", rest, want)
+		}
+	}
+	if g.Output != gitea.FormatTable {
+		t.Fatalf("output = %v, want table", g.Output)
+	}
+	if g.URL != defaultGlobals().URL || g.Token != "" {
+		t.Fatalf("reserved flags must not leak into globals: %+v", g)
+	}
+}
+
+// TestExtractGlobalsNonReservedCommand 驗證 #13 行為不回歸：未登記保留
+// 旗標的命令（如 next/members/pulls），命令後的全域選項照常抽取、
+// 命令自己的旗標（--has-work 等）原樣保留。
+func TestExtractGlobalsNonReservedCommand(t *testing.T) {
+	g := defaultGlobals()
+	rest, err := extractGlobals(&g, []string{
+		"members", "--has-work", "--output", "table",
+	}, reservedFlags("members"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(rest) != 2 || rest[0] != "members" || rest[1] != "--has-work" {
+		t.Fatalf("rest = %v, want [members --has-work]", rest)
+	}
+	if g.Output != gitea.FormatTable {
+		t.Fatalf("output = %v, want table", g.Output)
+	}
+}
+
 // errString 把字串轉成 error（測試輔助）。
 type errStr string