axmap-cli 1.2.5 → 1.3.1

package/governance/policy.example.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "voters": [
+    {
+      "id": "alice",
+      "email": "alice@example.com"
+    },
+    {
+      "id": "bob",
+      "email": "bob@example.com"
+    },
+    {
+      "id": "carol",
+      "email": "carol@example.com"
+    }
+  ],
+  "amendment": {
+    "paths": [
+      "governance/policy.json"
+    ],
+    "threshold": 3
+  },
+  "default": {
+    "threshold": 2
+  },
+  "rules": [],
+  "succession": {
+    "window_days": 90,
+    "top": 3
+  }
+}

package/mcp/README.md

@@ -11,54 +11,20 @@
 
 ## 설치
 
-한 줄이다. 저장소를 받은 뒤 **앞으로 일할 폴더에서** 실행한다.
-
-```powershell
-# Windows
-powershell -ExecutionPolicy Bypass -File "$HOME\axmap-src\axmap\mcp\install.ps1"
-```
+Node 20 이상과 git이 필요하다. Git 저장소 밖을 포함해 어느 폴더에서든 실행한다.
 
 ```bash
-# macOS / Linux
-bash "$HOME/axmap-src/axmap/mcp/install.sh"
+npm install -g axmap-cli@latest
+axmap setup
 ```
 
-설치기가 하는 일은 셋이다.
-
-1. axMap 을 **`~/.axmap/app`** 으로 복사한다 (홈 디렉터리. 어느 저장소에도 안 들어간다)
-2. 이 PC 에 있는 AI CLI 를 찾아 각자의 설정에 `axmap` 서버를 넣는다
-3. **CLI 마다 붙었는지 한 줄씩** 찍는다. 하나라도 실패하면 종료 코드가 0 이 아니다
-
-```
-등록 결과
-  OK  claude  user 범위에 등록했습니다 (~/.claude.json)
-  OK  agy     ~/.gemini/config/mcp_config.json (전역) — 이름까지 적었습니다
-  ~~  codex   이 PC 에 codex 가 없습니다 (건너뜀 — 실패가 아닙니다)
-```
+어느 폴더에서든 setup을 실행한 뒤 AI CLI를 다시 시작한다. `setup`은 PC 전역에 MCP와 명령을 설치·등록하며 repo를 초기화하거나 타겟으로 저장하지 않는다. 이후 AI CLI를 켠 repo에서 장부를 자동 준비한다. 소스 개발 환경에서는 `node bin/axmap.mjs setup`을 사용한다. 명시적 repo 준비는 `setup --repo <경로>`를 사용한다.
 
-**설치가 끝나면 AI CLI 를 완전히 껐다가 다시 켠다.** MCP 서버 목록은 CLI 가 켜질 때
-한 번만 읽힌다.
+AI에게 설치를 맡기려면 다음 공개 문서를 제공한다.
 
-### AI 에게 시키려면
+https://github.com/rl2aderjoon/axmap/blob/main/mcp/SETUP-FOR-AI.md
 
-사람이 명령을 칠 필요도 없다. 자기 AI CLI 에 이 한 줄만 던진다.
-
-```
-이 파일 읽고 axMap 붙여줘: https://lab.ssafy.com/s15-bigdata-dist-sub1/S15P21E201/-/raw/main/axmap/mcp/SETUP-FOR-AI.md
-```
-
-[SETUP-FOR-AI.md](SETUP-FOR-AI.md) 는 **에이전트가 그대로 실행하도록** 쓴 지시문이다.
-단계마다 성공을 어떻게 확인하는지와, 남의 저장소에 손대지 말라는 금지 목록이 들어 있다.
-
-### 옵션
-
-| | Windows | macOS / Linux |
-|---|---|---|
-| 이름을 직접 정한다 | `-Name "홍길동"` | `--name "홍길동"` |
-| 원본 위치를 지정한다 | `-Source <axmap 폴더>` | `--source <axmap 폴더>` |
-| 설치 위치를 바꾼다 | `-Dest <폴더>` | `--dest <폴더>` |
-
-이미 설치돼 있으면 **묻지 않고 갱신한다.** 무엇을 갱신했는지는 줄마다 찍힌다.
+기존 소스 복사 설치기는 `mcp/install.ps1`과 `mcp/install.sh`에 있다. 일반 설치와 설정은 [INSTALL.md](../docs/INSTALL.md)를 따른다.
 
 ---
 
@@ -74,7 +40,7 @@ bash "$HOME/axmap-src/axmap/mcp/install.sh"
 | `ax_renew()` | 길어지면 시간 연장 |
 | `ax_inbox(id?)` | 다른 에이전트가 나에게 보낸 쪽지를 읽는다 |
 | `ax_send(to?, subject, body)` | 다른 에이전트에게 쪽지를 보낸다 |
-| `ax_init()` | 장부가 없을 때 한 번. 이미 있으면 아무것도 바꾸지 않는다 |
+| `ax_init(remote?)` | 명시적 준비용. 조회·선점은 장부를 자동 준비하므로 먼저 부를 필요가 없다 |
 
 `ax_claim` 이 거부되면(겹침) **재시도하지 말고 다른 작업으로 옮겨야 한다.**
 같은 요청은 몇 번을 보내도 같은 답이 온다. 메시지에 점유자·작업·남은 시간이 들어
@@ -106,7 +72,7 @@ Claude Code 에서는 `/ax`, `/ax-start`, `/ax-done`, `/ax-tell` 로도 부른
 | Claude Code (`claude`) | `~/.claude.json` 의 user 범위 (**이 PC 의 모든 폴더에 적용되는 개인 설정**) | 설치기가 `claude mcp add -s user` 로 | ✅ 이 PC 에서 확인 |
 | Claude Code (`claude`) | 저장소의 `.mcp.json` | 저장소에 들어 있으면 스스로 발견 | ✅ 이 저장소가 그렇게 쓴다 |
 | Antigravity (`agy`) | `~/.gemini/config/mcp_config.json` (전역, `mcpServers`) | `tools/mcp-register.mjs` | ✅ `agy` 1.1.10 으로 확인 |
-| Codex (`codex`) | `~/.codex/config.toml` (전역, `[mcp_servers.axmap]`) | `tools/mcp-register.mjs` 가 `codex mcp add` 로 | ⚠️ 문서로만 확인, 실물 미확인 |
+| Codex (`codex`) | `~/.codex/config.toml` (전역, `[mcp_servers.axmap]`) | `tools/mcp-register.mjs`가 Codex CLI로 등록·검증 | 임시 사용자 환경에서 실제 CLI 등록과 repo별 MCP 실행 확인 |
 
 `agy` 에서 확인한 것: 전역 파일은 먹고, 저장소의 `.mcp.json` 은 **안 먹는다.**
 공식 문서의 작업 폴더용 `.agents/mcp_config.json` 도 CLI 에서는 안 먹었다(IDE 쪽으로 보인다).
@@ -167,9 +133,9 @@ CLI 를 부를 때마다 넘긴다. 앞 두 칸은 CLI 와 순서가 같아서,
 
 ### 🔴 `AXMAP_REPO` 는 비운다 — 대상은 부를 때마다 다시 정해진다
 
-서버는 도구를 부를 때마다 대상 저장소를 다시 정한다. 순서는 넷이고 위가 이긴다:
-`AXMAP_REPO` → `~/.axmap/current.json`(앱에서 [폴더 열기] 로 고른 것) → git 저장소
-루트 → 현재 폴더. 근거와 버린 대안은 [DECISIONS.md 의 D19](../docs/DECISIONS.md).
+서버는 도구를 부를 때마다 대상 저장소를 다시 정한다. 순서는 `AXMAP_REPO` → 도구의 절대 경로 `cwd` → 클라이언트 작업 폴더(roots) → 시작 폴더의 Git 루트다. 앱의 전역 `current.json`은 사용하지 않는다. 근거는 [DECISIONS.md의 D22](../docs/DECISIONS.md).
+
+장부가 없는 repo도 첫 조회·선점 때 자동으로 준비한다. 기존 원격 장부가 있으면 이어 사용하고, 원격 접근 실패는 빈 장부로 바꾸지 않는다. roots가 여러 repo를 가리켜 대상을 고를 수 없으면 도구의 `cwd`를 지정한다. roots 미지원 클라이언트에서 실행 중 폴더를 바꿀 때도 `cwd`를 전달한다. 서로 다른 MCP 세션의 타겟은 독립적이다.
 
 전역 등록인데 `AXMAP_REPO` 에 한 폴더를 박아 두면 **등록은 전역인데 대상은 한 곳으로
 굳는다.** 다른 저장소를 열어도 아무 오류 없이 엉뚱한 장부에 claim 이 쌓인다.
@@ -196,11 +162,7 @@ clone 하면 장부에는 `claude` 라는 **한 명**만 존재하고, 겹침
 3. OS 사용자 이름
 4. 호스트 이름
 
-**이름은 설치기를 켠 폴더의 git 설정에서 나온다.** git 은 저장소 안이면 그 저장소의
-`user.name` 을, 밖이면 전역 값을 답한다. 그래서 앞으로 일할 저장소 안에서 설치하는
-것이 맞다 — 그래야 MCP 가 쓰는 이름과 같은 저장소에서 손으로 `axmap` 을 칠 때의
-이름이 같아진다. 다르면 한 사람이 장부에서 둘이 되고, **자기가 잡은 것을 자기가
-반납하지 못한다**(`release` 종료 코드 5).
+**기본 전역 setup의 이름은 전역 Git 설정에서 정한다.** setup을 실행한 repo의 로컬 이름을 다른 repo에 가져가지 않는다. 명시적 프로젝트 설정에서는 해당 repo의 이름을 사용할 수 있다. 선점부터 반납까지 같은 이름·세션을 사용해야 한다.
 
 이름 검증은 설치기가 다시 짜지 않고 저장소의 `agentNameError()` 를 그대로 부른다.
 설치기가 통과시킨 이름을 서버가 거부하는 일이 없어야 하기 때문이다.
@@ -240,20 +202,11 @@ clone 하면 장부에는 `claude` 라는 **한 명**만 존재하고, 겹침
 
 ## 안 되는 것 / 아직 확인 못 한 것
 
-**Codex 는 실물로 확인하지 못했다.** 이 팀에 `codex` 가 깔린 PC 가 아직 없다.
-`~/.codex/config.toml` 형식은 공식 문서를 따른 것이고, `mcp-register` 는
-`codex mcp --help` 를 먼저 찔러 보고 그 하위 명령이 실제로 있을 때만 등록한다.
-TOML 을 직접 파싱하지도 쓰지도 않는다 — 어설픈 파서가 남의 `config.toml` 을 깨뜨리는
-것이 이 작업에서 나올 수 있는 최악의 결과다.
+**Codex CLI 등록은 임시 사용자 환경에서 실제 실행으로 확인했다.** `codex mcp list --json`으로 서버 경로·환경·시작 cwd를 확인하고 `codex mcp add`로 갱신한 뒤 다시 검증한다. TOML을 직접 파싱하거나 덮어쓰지 않는다. 모델 클라이언트별 roots 지원 여부는 별도 확인이 필요하다.
 
-**Codex 에는 이름이 안 들어간다.** `mcp-register` 가 `codex mcp add` 를 부를 때
-`AXMAP_AGENT` 를 빼고 부르고, 이미 등록돼 있으면 다시 부르지도 않는다. 그래서 설치기는
-codex 에 대해서는 **확인만 하고 이름은 손으로 넣으라고 한 줄 찍는다.** 확인 안 된
-도구의 설정을 추측으로 덮어쓰는 것보다 낫다고 봤다.
+**개인 환경값은 보존한다.** Codex의 기존 `AXMAP_AGENT` 등 개인 환경값은 유지하며, 전역 setup은 예전 서버 경로·고정 `AXMAP_REPO`·시작 cwd를 제거한다. 이름을 따로 지정하지 않았으면 MCP가 작업 repo의 Git 설정에서 정한다.
 
-**MCP `roots` 를 아직 안 만들었다.** 버린 것이 아니다. `roots` 는 클라이언트가 서버에게
-*"지금 열려 있는 작업 폴더는 여기"* 를 알려주는 규격의 표준 통로이고, D19 사다리의
-2번 자리에 들어갈 것이다. 먼저 안 한 이유는 클라이언트마다 지원 여부가 다르기 때문이다.
+**MCP `roots`는 1.3.0부터 지원한다.** 클라이언트가 지원을 선언하면 `roots/list`로 작업 폴더를 받고 변경 알림도 처리한다. 지원하지 않는 클라이언트는 시작 repo를 사용하고, 실행 중 경로 변경은 도구의 `cwd`로 전달한다. 프로토콜 회귀 테스트로 검증했으며 클라이언트별 실제 지원 여부는 별도 확인이 필요하다.
 
 **같은 이름이 두 곳에 생길 수 있다.** 이 저장소 안에서 Claude Code 를 켜면 저장소의
 `.mcp.json` 과 전역 등록이 둘 다 `axmap` 이라는 이름을 갖는다. 충돌로 깨지지는 않지만

package/mcp/SETUP-FOR-AI.md

@@ -1,186 +1,24 @@
-# AI 에이전트에게 주는 지시문 — axMap 을 이 PC 에 붙인다
+# AI 도구에 axMap 연결하기
 
-**이 문서는 사람이 읽으라고 쓴 것이 아니라 AI CLI 가 그대로 실행하라고 쓴 것이다.**
-사람은 자기 AI 도구에 이 한 줄만 던지면 된다.
+이 문서의 공개 주소: https://github.com/rl2aderjoon/axmap/blob/main/mcp/SETUP-FOR-AI.md
 
-```
-이 파일 읽고 axMap 붙여줘: https://lab.ssafy.com/s15-bigdata-dist-sub1/S15P21E201/-/raw/main/axmap/mcp/SETUP-FOR-AI.md
-```
-
----
-
-## 에이전트에게 — 먼저 읽어라
-
-axMap 은 **여러 AI 에이전트가 같은 저장소를 동시에 고칠 때 서로를 밟지 않게 하는
-선점 장치**다. 파일을 고치기 전에 "나는 이걸 건드리겠다"를 선언(claim)하고, 겹치면
-그 자리에서 거부당한다. 지금부터 하는 일은 그 장치를 **이 PC 에 한 번 설치**하는 것이다.
-
-### 🔴 이 작업에서 절대 하지 말 것
-
-| 하지 마라 | 왜 |
-|---|---|
-| 지금 열려 있는 저장소에 `ax_init` / `axmap init` 을 부르는 것 | **남의 저장소에 장부(선언 기록을 쌓아 두는 전용 브랜치와 그 브랜치를 펼쳐 두는 폴더)가 생긴다.** 설치와 아무 관계가 없다. 장부는 그 저장소의 팀이 만들기로 정했을 때 그 팀이 만든다 |
-| 지금 열려 있는 저장소 루트에 `.mcp.json` 을 만드는 것 | 남의 저장소에 우리 설정 파일을 커밋시키는 짓이다. 이 설치는 **전역**이라 그 파일이 필요 없다 |
-| `AXMAP_REPO` 환경변수나 설정을 채우는 것 | 전역 등록인데 대상이 한 폴더로 굳는다. 다른 저장소를 열어도 **아무 오류 없이 엉뚱한 장부에 claim 이 쌓인다** |
-| 지금 열려 있는 저장소 안에 파일을 만들거나 고치는 것 | 이 설치는 저장소 밖에서만 일어난다. 아래 명령이 손대는 곳은 홈 디렉터리 두 폴더(`~/axmap-src`, `~/.axmap/app`)와 이 PC 의 AI CLI 설정 파일뿐이다 |
-| 커밋·push | 설치는 커밋할 것이 없다 |
-| 실패를 숨기거나, 실패한 단계를 건너뛰고 "됐습니다" 라고 말하는 것 | 이 도구의 실패는 조용하다. 안 붙은 채로 넘어가면 사람은 선점이 도는 줄 알고 일한다. **막힌 자리를 그대로 보고해라** |
-
-### 준비물
+Node 20 이상과 git을 확인한다. npm 패키지 이름은 `axmap-cli`다.
 
-`node` 20 이상과 `git`. 둘 다 없으면 여기서 멈추고 사람에게 설치를 요청해라.
-
----
-
-## 1단계 — node 를 확인한다
-
-```
-node --version
+```bash
+npm install -g axmap-cli@latest
 ```
 
-**성공 판정:** `v20.x` 이상이 찍히고 종료 코드(**프로그램이 끝나면서 내는 숫자.
-0 이면 성공, 그 밖은 실패**)가 0.
-`v19` 이하거나 명령을 못 찾으면 **여기서 멈추고** 사람에게 "Node 20 이상이 필요하다"고 말해라.
+Git 저장소 밖을 포함해 어느 폴더에서든 다음 명령을 실행한다. setup에는 작업 repo를 지정할 필요가 없다.
 
----
-
-## 2단계 — axMap 을 홈 디렉터리에 내려받는다
-
-받는 곳은 `~/axmap-src` 다. **지금 열려 있는 저장소 안이 아니다.**
-두 명령을 순서대로 그대로 실행해라. 첫 줄은 전에 받아 둔 것이 있으면 지운다.
-
-```
-node -e "require('fs').rmSync(require('path').join(require('os').homedir(),'axmap-src'),{recursive:true,force:true})"
+```bash
+axmap setup --dry-run
+axmap setup
 ```
 
-```
-git clone --depth 1 https://lab.ssafy.com/s15-bigdata-dist-sub1/S15P21E201.git "$HOME/axmap-src"
-```
-
-**성공 판정:** 두 명령 모두 종료 코드 0. `git clone` 이 마지막에
-`Resolving deltas: 100% ... done.` 같은 줄을 찍는다.
-
-**실패했다면:** 이 저장소는 SSAFY GitLab 의 **비공개 저장소**다. `Authentication failed`
-나 `403` 이 나오면 접근 권한이 없는 것이다. 다른 방법을 찾지 말고 사람에게
-*"이 GitLab 저장소에 읽기 권한이 필요하다"* 고 말하고 멈춰라.
-
----
-
-## 3단계 — 설치기를 돌린다
-
-🔴 **이 명령은 지금 열려 있는 저장소 폴더에서 실행해라.** 설치기는 **켠 폴더의
-`git config user.name`** 을 장부에서 쓸 이름으로 삼는다. 앞으로 일할 저장소 안에서
-실행해야, MCP 가 쓰는 이름과 그 저장소에서 손으로 `axmap` 을 칠 때의 이름이 같아진다.
-
-OS 는 **네가 고르지 말고 이 명령이 판별하게 둬라.** Windows 면 `install.ps1`,
-그 밖이면 `install.sh` 를 부른다.
-
-```
-node -e "const{spawnSync}=require('child_process'),p=require('path'),o=require('os');const d=p.join(o.homedir(),'axmap-src','axmap','mcp'),w=process.platform==='win32';const r=spawnSync(w?'powershell.exe':'bash',w?['-NoProfile','-ExecutionPolicy','Bypass','-File',p.join(d,'install.ps1')]:[p.join(d,'install.sh')],{stdio:'inherit'});process.exit(r.status===null?1:r.status)"
-```
-
-설치기가 하는 일은 셋이다: axMap 을 `~/.axmap/app` 으로 복사하고, 이 PC 에 있는
-AI CLI 를 찾아 각자의 설정에 `axmap` 서버를 넣고, 붙었는지 CLI 마다 한 줄씩 찍는다.
-
-**성공 판정:** 종료 코드 0. 그리고 마지막에 이런 블록이 찍힌다.
-
-```
-등록 결과
-  OK  claude  user 범위에 등록했습니다 (~/.claude.json)
-  OK  agy     ~/.gemini/config/mcp_config.json (전역) — 이름까지 적었습니다
-  ~~  codex   이 PC 에 codex 가 없습니다 (건너뜀 — 실패가 아닙니다)
-```
-
-읽는 법은 세 가지뿐이다.
-
-| 표시 | 뜻 | 네가 할 일 |
-|---|---|---|
-| `OK` | 그 CLI 에 붙었다 | 없다 |
-| `~~` | 그 CLI 가 이 PC 에 없어서 건너뛰었다 | 없다. **실패가 아니다** |
-| `!!` | 그 CLI 가 있는데 등록에 실패했다 | 종료 코드도 0 이 아니다. **줄에 적힌 이유를 그대로 사람에게 보고하고 멈춰라** |
-
-`!!` 를 본 채로 다음 단계로 넘어가지 마라. 그 CLI 에서는 axMap 이 뜨지 않는다.
-
----
-
-## 4단계 — 설치를 검증한다
-
-지금 열려 있는 저장소 폴더에서 그대로 실행해라.
-
-```
-node "$HOME/.axmap/app/bin/axmap.mjs" doctor
-```
-
-🔴 **이 명령의 종료 코드는 0 이 아닐 수 있고, 그것이 정상이다.**
-`doctor` 는 설치만 보는 것이 아니라 **지금 이 저장소에서 선점이 실제로 도는지**까지
-본다. 아직 axMap 을 쓰기로 하지 않은 저장소라면 장부도 훅도 없는 것이 당연하다.
-
-줄마다 뜻이 다르다.
-
-| 줄 | 무엇을 말하나 | 판정 |
-|---|---|---|
-| `node` | node 버전 | **`OK` 여야 한다** |
-| `저장소` | 지금 겨누고 있는 저장소 루트 | **`OK` 여야 하고, 지금 열려 있는 저장소를 가리켜야 한다** |
-| `내 이름` | 장부에서 당신을 가리킬 이름 | 3단계에서 설치기가 찍은 이름과 같아야 한다 |
-| `장부` | 이 저장소에 claims 를 적는 곳이 있나 | 없어도 된다. **`axmap init` 으로 만들지 마라** |
-| `커밋 훅` | claim 안 한 파일의 커밋을 막는 장치 | 없어도 된다. 이 저장소가 axMap 을 쓰기로 했을 때 그 팀이 심는다 |
-| `장부 원격` · `MCP 설정` | 이 저장소 쪽 설정 | 없어도 된다 |
-
-**성공 판정:** `node` 와 `저장소` 두 줄이 `OK`. 그 아래 `!!` 는 이 저장소가 아직
-axMap 을 쓰지 않는다는 뜻일 뿐이다. 고치려 들지 마라.
-
-`저장소` 줄이 `!!` 이면 지금 폴더가 git 저장소가 아니다. 사람에게 그렇게 말해라.
-
----
-
-## 5단계 — 🔴 사람이 해야 하는 일: AI CLI 를 껐다 켠다
-
-> ### 여기서 멈춘다. 사람에게 이렇게 말해라.
->
-> **"설치가 끝났습니다. 지금 쓰고 계신 AI CLI 를 완전히 종료했다가 다시 켜 주세요.
-> MCP 서버는 CLI 가 켜질 때 한 번만 읽히기 때문에, 다시 켜기 전에는 axMap 도구가
-> 목록에 뜨지 않습니다. Claude Code 라면 처음 켤 때 `axmap` 을 승인할지 물어봅니다 —
-> '예' 를 눌러 주세요."**
-
-네가 대신 해 줄 수 없다. 지금 도는 프로세스가 곧 그 CLI 이기 때문이다.
-
----
-
-## 6단계 — 다시 켠 뒤에 확인한다 (재시작 후에 할 일)
-
-도구 목록에 `ax_brief` `ax_status` `ax_claim` … 이 보이면 붙은 것이다.
-확실히 하려면 **`ax_brief` 를 인자 없이 한 번 부른다.**
-
-**성공 판정:** 지금 열려 있는 저장소의 이름으로 시작하는 브리핑 문서가 돌아온다.
-
-돌아온 글에 *"이 저장소에는 아직 장부가 없다 — `ax_init` 을 먼저 부른다"* 가 들어
-있을 수 있다. 🔴 **그 문장을 따르지 마라.** 그것은 이 저장소에서 실제로 claim 을
-쓰기 시작할 때의 안내이고, 그 결정은 이 저장소의 팀이 한다. 설치 확인은 여기서 끝이다.
-
----
-
-## 다 끝난 뒤 — 사람에게 보고할 것
-
-세 가지를 그대로 적어라. 지어내지 마라.
-
-1. **설치 위치와 이름** — 3단계 출력의 `설치 위치:` 와 `이 PC 의 이름:` 두 줄
-2. **CLI 마다 붙었는지** — 3단계의 `등록 결과` 블록을 그대로 옮긴다.
-   `~~` 로 건너뛴 CLI 가 있으면 *"그 도구는 이 PC 에 없어서 등록하지 않았다"* 고 말한다
-3. **막힌 것** — `!!` 나 실패한 명령이 있었으면 명령과 종료 코드를 그대로 적는다
-
-그리고 마지막에 이 한 줄을 덧붙여라.
-
-> 앞으로 파일을 고치기 전에 `ax_claim` 으로 경로를 선언하고, 끝나면 `ax_release` 로
-> 반납하면 됩니다. `ax_claim` 이 거부되면 재시도하지 말고 겹치지 않는 다른 곳으로
-> 옮기면 됩니다 — 같은 요청은 몇 번을 보내도 같은 답이 옵니다.
+`setup`은 프로그램과 전역 명령을 설치하고 AI CLI의 사용자 설정에 MCP를 등록한다. repo를 초기화하거나 `AXMAP_REPO`를 특정 폴더로 고정하지 않는다. repo의 장부와 커밋 훅도 미리 준비하려면 `--repo <경로>`를 명시하고, 다른 원격을 공유하려면 `--remote <git-주소>`도 지정한다.
 
----
+1.3.0부터 다른 repo로 이동할 때 `setup`이나 `init`을 반복하지 않는다. 새 작업 repo에서 AI CLI를 실행하면 첫 조회·선점 시 장부를 자동 준비한다. MCP roots가 지원되면 작업 폴더 변경도 따라간다. 지원되지 않거나 여러 repo가 열려 있으면 도구의 `cwd`에 현재 작업 폴더 절대 경로를 전달한다. 커밋 훅을 새 repo에도 적용하려면 `axmap hook install`을 실행한다.
 
-## 나중에 다시 할 때
+명령의 종료 코드를 확인하고 실패한 단계를 보고한다. AI CLI를 완전히 종료한 뒤 다시 시작해 `ax_*` 도구를 확인한다. 설치 과정에서 커밋하거나 push할 필요는 없다. 기존 소스 폴더를 삭제하지 않는다.
 
-- **최신으로 갱신** — 2단계와 3단계를 그대로 다시 실행한다. 묻지 않고 덮어쓰며,
-  무엇을 갱신했는지 줄마다 찍는다
-- **이름을 바꿔서 설치** — 3단계 대신 설치기를 직접 부르고 이름을 준다
-  (Windows: `powershell -ExecutionPolicy Bypass -File "$HOME/axmap-src/axmap/mcp/install.ps1" -Name "홍길동"` /
-  그 밖: `bash "$HOME/axmap-src/axmap/mcp/install.sh" --name "홍길동"`)
-- **원리와 실측** — [README.md](README.md)
+소스 설치는 [개발 안내](../docs/ONBOARD-TEAM.md), 명령 사용은 [INSTALL.md](../docs/INSTALL.md)를 참고한다.

package/mcp/install.ps1

@@ -228,6 +228,7 @@ if (-not (Test-Path -LiteralPath $server)) { Fail "복사가 끝났는데 서버
 # 이미 한다. 여기서 다시 짜지 않는다.
 Say ''
 & node (Join-Path $Dest 'tools\mcp-register.mjs')
+if ($LASTEXITCODE -ne 0) { Fail 'AI CLI 전역 등록을 확인하지 못했습니다. 위 오류를 해결하고 setup을 다시 실행하세요.' }
 Say '      (위에 claude 가 ".mcp.json 이 없습니다" 로 나왔다면, 그건 "저장소 안의'
 Say '       .mcp.json" 을 찾는 검사입니다. 전역 설치에는 그 파일이 없는 것이 정상이고,'
 Say '       Claude Code 는 바로 아래에서 따로 등록합니다.)'
@@ -295,7 +296,7 @@ if (-not (Get-Command codex -ErrorAction SilentlyContinue)) {
   $listed = "$(& codex mcp list)"
   if ($listed -match 'axmap') {
     $stCodex = 'ok'
-    $whyCodex = "~/.codex/config.toml (codex mcp list 로 확인). 이름은 손으로 넣으세요: [mcp_servers.axmap.env] 아래에 AXMAP_AGENT = ""$Name"""
+    $whyCodex = '~/.codex/config.toml (codex mcp list로 확인). 작업 repo는 실행 위치에서 결정하고 이름은 git 설정을 사용합니다.'
   } else {
     $stCodex = 'fail'; $whyCodex = 'codex mcp list 에 axmap 이 없습니다 — 위 TOML 조각을 손으로 넣으세요'
   }

package/mcp/install.sh

@@ -226,7 +226,7 @@ SERVER="$DEST/mcp/server.mjs"
 # 이 PC 에 어떤 CLI 가 있는지 찾고 각자의 설정에 넣는 일은 tools/mcp-register.mjs 가
 # 이미 한다. 여기서 다시 짜지 않는다.
 say ''
-node "$DEST/tools/mcp-register.mjs"
+node "$DEST/tools/mcp-register.mjs" || fail 'AI CLI 전역 등록을 확인하지 못했습니다. 위 오류를 해결하고 setup을 다시 실행하세요.'
 say '      (위에 claude 가 ".mcp.json 이 없습니다" 로 나왔다면, 그건 "저장소 안의'
 say '       .mcp.json" 을 찾는 검사입니다. 전역 설치에는 그 파일이 없는 것이 정상이고,'
 say '       Claude Code 는 바로 아래에서 따로 등록합니다.)'
@@ -293,7 +293,7 @@ if ! command -v codex >/dev/null 2>&1; then
 else
   if codex mcp list 2>/dev/null | grep -q axmap; then
     ST_CODEX='ok'
-    WHY_CODEX="~/.codex/config.toml (codex mcp list 로 확인). 이름은 손으로 넣으세요: [mcp_servers.axmap.env] 아래에 AXMAP_AGENT = \"$NAME\""
+    WHY_CODEX='~/.codex/config.toml (codex mcp list로 확인). 작업 repo는 실행 위치에서 결정하고 이름은 git 설정을 사용합니다.'
   else
     ST_CODEX='fail'; WHY_CODEX='codex mcp list 에 axmap 이 없습니다 — 위 TOML 조각을 손으로 넣으세요'
   fi