diff --git a/README.md b/README.md
index 6d608520..d1c1e38f 100644
--- a/README.md
+++ b/README.md
@@ -135,7 +135,7 @@ Install the CLI:
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/mainline-org/mainline/main/install.sh | bash
-mainline doctor --setup
+mainline version
 ```
 
 You can also install with Go:
@@ -147,6 +147,10 @@ go install github.com/mainline-org/mainline@latest
 Downloadable release archives and checksums are published on
 [GitHub Releases](https://github.com/mainline-org/mainline/releases/latest).
 
+`mainline version` only verifies that the CLI is installed and on your `PATH`.
+`mainline doctor --setup` is a per-repository wiring check and expects to run
+inside a Git repository.
+
 Initialize each repo once:
 
 ```bash
diff --git a/README.zh.md b/README.zh.md
index 9d883202..2ed5336e 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -114,7 +114,7 @@ mainline seal --submit --json < .ml-cache/seal.json
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/mainline-org/mainline/main/install.sh | bash
-mainline doctor --setup
+mainline version
 ```
 
 也可以用 Go 安装：
@@ -126,6 +126,9 @@ go install github.com/mainline-org/mainline@latest
 预编译 archive 和 checksums 在
 [GitHub Releases](https://github.com/mainline-org/mainline/releases/latest)。
 
+`mainline version` 只验证 CLI 已安装并且在 `PATH` 中。`mainline doctor --setup`
+是每个 repo 内的配置检查，需要在 Git 仓库里运行。
+
 每个 repo 初始化一次：
 
 ```bash
diff --git a/docs/reference.md b/docs/reference.md
index cee8c8df..c8e6e9a2 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -68,10 +68,10 @@ cd mainline
 go build -o mainline .
 ```
 
-Verify setup at any time:
+Verify the installed binary after any install method:
 
 ```bash
-mainline doctor --setup
+mainline version
 ```
 
 ## Getting Started With An Agent
@@ -82,6 +82,12 @@ One-time setup per repository:
 mainline init --actor-name "<your name>"
 ```
 
+Verify repository wiring from inside that Git repository:
+
+```bash
+mainline doctor --setup
+```
+
 `mainline init` does three things:
 
 1. Writes `.mainline/config.toml` and configures Git refspecs.
@@ -435,7 +441,7 @@ Reviewer and maintainer extras:
 | `mainline followups add` | Add explicit deferred work. |
 | `mainline check --prepare` | Prepare a phase-2 conflict review task package. |
 | `mainline check --submit` | Submit phase-2 judgment. |
-| `mainline doctor --setup` | Verify installation, refspecs, identity, `.gitignore`, and optional policy state. |
+| `mainline doctor --setup` | Verify repository wiring: refspecs, identity, `.gitignore`, and optional policy state. |
 | `mainline init --rewire` | Re-apply refspec config, notes display refs, and `.gitignore` entries. |
 
 All commands accept `--json`. The persistent `--no-sync` flag opts a command out
diff --git a/docs/reference.zh.md b/docs/reference.zh.md
index 810656a7..2ddeabba 100644
--- a/docs/reference.zh.md
+++ b/docs/reference.zh.md
@@ -62,10 +62,10 @@ cd mainline
 go build -o mainline .
 ```
 
-随时检查本机配置：
+用任意方式安装后，可以这样确认二进制已安装：
 
 ```bash
-mainline doctor --setup
+mainline version
 ```
 
 ## 让 Agent 用起来
@@ -76,6 +76,12 @@ mainline doctor --setup
 mainline init --actor-name "<你的名字>"
 ```
 
+在这个 Git 仓库里检查仓库配置：
+
+```bash
+mainline doctor --setup
+```
+
 `mainline init` 做三件事：
 
 1. 写入 `.mainline/config.toml` 并配置 Git refspecs。
@@ -394,7 +400,7 @@ Reviewer / maintainer 额外命令：
 | `mainline followups add` | 添加 explicit deferred work。 |
 | `mainline check --prepare` | 准备 phase-2 conflict review task package。 |
 | `mainline check --submit` | 提交 phase-2 judgment。 |
-| `mainline doctor --setup` | 检查安装、refspecs、identity、`.gitignore` 和 policy state。 |
+| `mainline doctor --setup` | 检查仓库配置：refspecs、identity、`.gitignore` 和 policy state。 |
 | `mainline init --rewire` | 重新应用 refspec config、notes display refs 和 `.gitignore` 条目。 |
 
 所有命令都支持 `--json`。`--no-sync` 可以跳过 auto-sync wrapper。
diff --git a/internal/cli/doctor.go b/internal/cli/doctor.go
index 24d42ed0..e7305306 100644
--- a/internal/cli/doctor.go
+++ b/internal/cli/doctor.go
@@ -1,11 +1,13 @@
 package cli
 
 import (
+	"errors"
 	"fmt"
 	"time"
 
 	"github.com/spf13/cobra"
 
+	"github.com/mainline-org/mainline/internal/domain"
 	"github.com/mainline-org/mainline/internal/engine"
 )
 
@@ -24,7 +26,7 @@ var doctorCmd = &cobra.Command{
 	Long: `Default mode: scans local drafts for orphans (referencing missing
 git branches) and stale ones; --fix deletes orphans.
 
---setup mode: runs install / wiring sanity checks — verifies the git
+--setup mode: runs repository wiring sanity checks — verifies the git
 remote refspec configuration, identity file, and .gitignore.
 Combined with --fix, missing remote refspec entries
 are rewired in place. Use this as the first step when 'mainline sync'
@@ -39,6 +41,19 @@ or force-pushes. It is read-only; use migrate notes for repairs.`,
 	Run: func(cmd *cobra.Command, args []string) {
 		svc, err := getService()
 		if err != nil {
+			if doctorSetup {
+				var mlErr *domain.MainlineError
+				if errors.As(err, &mlErr) && mlErr.Code == domain.ErrNotInGitRepo {
+					outputError(domain.NewRecoverableError(
+						domain.ErrNotInGitRepo,
+						"doctor --setup must run inside a Git repository",
+						"`mainline version` verifies that the CLI is installed",
+						"`cd <repo>` to an existing Git repository, or run `git init` first",
+						"then run `mainline init --actor-name \"<your name>\"` before `mainline doctor --setup`",
+					))
+					return
+				}
+			}
 			outputError(err)
 			return
 		}
@@ -251,7 +266,7 @@ func renderSetupReport(r *engine.DoctorSetupReport, fixed bool) {
 func init() {
 	doctorCmd.Flags().BoolVar(&doctorFix, "fix", false, "delete orphan local draft files (default mode), or rewire refspecs (with --setup)")
 	doctorCmd.Flags().DurationVar(&doctorStaleAfter, "stale-after", 24*time.Hour, "mark drafting intents stale after this duration")
-	doctorCmd.Flags().BoolVar(&doctorSetup, "setup", false, "run install / wiring sanity checks (refspec, identity, .gitignore)")
+	doctorCmd.Flags().BoolVar(&doctorSetup, "setup", false, "run repository wiring sanity checks (refspec, identity, .gitignore)")
 	doctorCmd.Flags().BoolVar(&doctorProposals, "proposals", false, "diagnose proposed intents that may need cleanup")
 	doctorCmd.Flags().DurationVar(&doctorStaleProposedAfter, "stale-proposed-after", engine.DefaultStaleProposedAfter, "mark proposed intents suspicious after this duration")
 	doctorCmd.Flags().BoolVar(&doctorNotes, "notes", false, "diagnose git-notes rewrite drift after history rewrites")