axmap-cli 1.3.0 → 1.3.1

package/.claude/commands/ax-setup.md

@@ -1,20 +1,18 @@
 ---
-description: axMap — 이 저장소에 axMap 을 붙인다 (내 git 주소를 넣어 초기화)
+description: axMap — 어느 폴더에서든 이 PC에 전역 설치·등록한다
 ---
 
-이 저장소에서 axMap 선점을 쓸 수 있게 만들어줘.
-장부(누가 무엇을 잡고 있는지 적는 곳)를 둘 git 주소: $ARGUMENTS
+이 PC에서 axMap을 전역으로 사용할 수 있게 설정해줘.
+추가 setup 옵션: $ARGUMENTS
 
-1. 지금 폴더가 git 저장소인지 먼저 본다. 아니면 **여기서 멈추고** 사람에게 알린다.
-   axMap 의 장부와 쪽지는 git 의 고아 브랜치로 오간다 — 저장소가 없으면 claim 이
-   아무에게도 안 가면서 조용히 성공한다.
+1. 지금 폴더가 Git 저장소가 아니어도 진행한다. setup은 PC 전역 설치이며 작업 repo는 나중에 CLI를 켠 위치에서 결정한다.
 
 2. Bash 로 아래를 실행한다.
 
-       npx -y axmap-cli@latest setup --remote $ARGUMENTS
+       npx -y axmap-cli@latest setup $ARGUMENTS
 
-   주소를 안 줬으면 `--remote` 째로 빼고 부른다. 그러면 이 저장소의 원격을
-   그대로 쓴다 (하나면 그것, `origin` 이 있으면 `origin`).
+   추가 옵션이 없으면 setup만 실행한다. repo를 지정하거나 현재 폴더를 타겟으로 저장하지 않는다.
+   사용자가 특정 repo의 장부와 커밋 훅까지 미리 준비하길 요청한 경우에만 `--repo <경로>`를 지정한다.
 
    먼저 무엇이 바뀔지만 보고 싶으면 `--dry-run` 을 붙인다. 아무것도 쓰지 않는다.
 
@@ -25,7 +23,6 @@ description: axMap — 이 저장소에 axMap 을 붙인다 (내 git 주소를
    - AI CLI 를 **완전히 껐다가 다시 켜야** MCP 도구(`ax_*`)가 뜬다
    - 그 뒤 `/ax-start` 로 시작하면 된다
 
-이미 붙어 있는 저장소라면 `setup` 을 다시 부르지 않고 `ax_status` 로 확인만 한다 —
-`setup` 은 몇 번 돌려도 안전하지만, 이미 되는 것을 다시 설치하는 것은 시간 낭비다.
+설치·업데이트 때 setup을 한 번 실행한다. 이후 repo를 옮길 때는 setup이나 init을 반복하지 않고 그 repo에서 `ax_status` 또는 `ax_claim`을 호출한다.
 
-같은 주소를 넣은 사람끼리 서로의 선점이 보인다. 그게 이 명령이 하는 일의 전부다.
+각 repo의 장부는 첫 조회·선점 때 자동 준비하며, 같은 원격 장부를 공유하는 세션끼리 서로의 선점이 보인다.

package/README.ko.md

@@ -13,22 +13,20 @@ npm 패키지 이름은 `axmap-cli`, 실행 명령은 `axmap`이다.
 
 ## 설치
 
-사용할 git 저장소에서 실행한다.
+Git 저장소 밖을 포함해 어느 폴더에서든 실행한다.
 
 ```bash
 npm install -g axmap-cli@latest
-cd <프로젝트-저장소>
 axmap setup
-axmap doctor
 ```
 
-`setup`은 저장소의 선점 장부와 커밋 훅을 준비하고, AI 도구의 사용자 설정에 MCP를 등록한다.
+`setup`은 이 PC에 axMap을 설치하고 AI 도구의 사용자 설정에 MCP를 등록한다. 실행한 폴더에 타겟을 고정하거나 repo를 초기화하지 않는다.
 MCP를 사용하려면 설정 후 AI 도구를 다시 시작한다.
 함께 작업하는 사람과 에이전트는 같은 원격 장부를 사용해야 서로의 선점을 볼 수 있다.
 
 자세한 설치·설정은 [docs/INSTALL.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INSTALL.md)를 참고한다.
 
-## 1.3.0: repo를 옮겨도 init 없이 사용
+## 1.3.1: 어느 폴더에서든 setup 한 번, 이후 repo 자동 연결
 
 axMap을 한 번 설정하면 다른 Git 저장소에서도 Codex 등 AI CLI를 열어 바로 사용할 수 있다. 세션의 작업 repo를 자동으로 선택하고, 첫 조회·선점 때 장부를 준비하므로 매번 `axmap init`을 실행하지 않아도 된다.
 
@@ -36,14 +34,14 @@ axMap을 한 번 설정하면 다른 Git 저장소에서도 Codex 등 AI CLI를
 
 MCP는 클라이언트가 알려주는 작업 폴더(roots)를 따라간다. 미지원 클라이언트는 시작 폴더를 사용하며, 도중에 폴더를 바꾸면 도구의 `cwd`에 작업 폴더 절대 경로를 전달한다. 커밋 훅을 적용할 새 repo에서는 `axmap hook install`을 실행한다.
 
-기존 설치를 업그레이드할 때는 작업 repo에서 아래 명령을 한 번 실행하고 AI CLI를 다시 시작한다.
+기존 설치를 업그레이드할 때도 어느 폴더에서든 아래 명령을 한 번 실행하고 AI CLI를 다시 시작한다.
 
 ```bash
 npm install -g axmap-cli@latest
 axmap setup
 ```
 
-`setup`은 MCP와 훅이 사용하는 설치 사본 및 등록을 갱신한다. 이후 repo를 옮길 때는 setup이나 init을 반복하지 않는다.
+`setup`은 MCP와 공유 훅 실행 사본 및 등록을 갱신한다. 이후 repo를 옮길 때는 setup이나 init을 반복하지 않는다. 특정 repo의 장부와 커밋 훅까지 미리 준비하려면 `axmap setup --repo <경로>`를 명시한다.
 
 ## 작업 흐름
 

package/README.md

@@ -13,22 +13,20 @@ The npm package is `axmap-cli`; the command is `axmap`.
 
 ## Installation
 
-Run these commands in the Git repository you want to work on.
+Run these commands from any folder, including outside a Git repository.
 
 ```bash
 npm install -g axmap-cli@latest
-cd <your-project-repository>
 axmap setup
-axmap doctor
 ```
 
-`setup` prepares the repository's claim ledger and commit hooks, and registers MCP in your AI tool's user settings.
+`setup` installs axMap and registers MCP in your AI tool's user settings. It does not bind the installation to the current folder or initialize a repository.
 Restart your AI tool after setup to use MCP.
 People and agents working together must share the same remote ledger to see each other's claims.
 
 See [docs/INSTALL.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INSTALL.md) for installation and configuration details (Korean).
 
-## Automatic repository setup in 1.3.0
+## Global setup and automatic repositories in 1.3.1
 
 Set up axMap once, then open Codex or another AI CLI in any Git repository. axMap selects that session's repository and prepares its ledger on the first status or claim request. There is no per-repository `axmap init` step.
 
@@ -36,14 +34,14 @@ Existing remote ledgers are reused. Linked worktrees share one ledger, and simul
 
 MCP follows workspace roots supplied by the client. When roots are unsupported, it uses the launch directory; pass the absolute working directory through the tool's `cwd` argument for later directory changes. Run `axmap hook install` in each repository where you want commit enforcement.
 
-To upgrade an existing installation, run this once from a working repository, then restart your AI CLI:
+To upgrade an existing installation, run this once from any folder, then restart your AI CLI:
 
 ```bash
 npm install -g axmap-cli@latest
 axmap setup
 ```
 
-`setup` refreshes the installed MCP and hook copy as well as its registration. Subsequent repository changes do not require another setup or init.
+`setup` refreshes the installed MCP and shared hook runner as well as its registration. Subsequent repository changes do not require another setup or init. To explicitly prepare one repository and its commit hook during setup, use `axmap setup --repo <path>`.
 
 ## Workflow
 

package/bin/axmap.mjs

@@ -2778,7 +2778,7 @@ function warnIfStale() {
 
 const HELP = `axmap - AI 에이전트 작업 선점 프로토콜
 
-  axmap setup                        이 PC 와 이 저장소에 axMap 을 붙인다 (첫 한 번)
+  axmap setup                        어느 폴더에서든 이 PC에 전역 설치·등록한다 (첫 한 번)
                                         [--remote <이름|git 주소>] [--name] [--dry-run]
   axmap init                         장부(고아 브랜치 + worktree)를 준비한다
   axmap bus-repair                   쪽지함만 준비한다 (장부는 안 건드린다)

package/mcp/README.md

@@ -11,15 +11,14 @@
 
 ## 설치
 
-Node 20 이상과 git이 필요하다. 사용하려는 git 저장소에서 실행한다.
+Node 20 이상과 git이 필요하다. Git 저장소 밖을 포함해 어느 폴더에서든 실행한다.
 
 ```bash
 npm install -g axmap-cli@latest
 axmap setup
-axmap doctor
 ```
 
-설정 후 AI CLI를 다시 시작한다. `setup`은 AI CLI의 사용자 설정에 MCP를 등록하고 대상 저장소의 장부와 커밋 훅을 준비한다. 소스 개발 환경에서는 `node bin/axmap.mjs setup`을 사용한다.
+어느 폴더에서든 setup을 실행한 뒤 AI CLI를 다시 시작한다. `setup`은 PC 전역에 MCP와 명령을 설치·등록하며 repo를 초기화하거나 타겟으로 저장하지 않는다. 이후 AI CLI를 켠 repo에서 장부를 자동 준비한다. 소스 개발 환경에서는 `node bin/axmap.mjs setup`을 사용한다. 명시적 repo 준비는 `setup --repo <경로>`를 사용한다.
 
 AI에게 설치를 맡기려면 다음 공개 문서를 제공한다.
 
@@ -73,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 쪽으로 보인다).
@@ -163,11 +162,7 @@ clone 하면 장부에는 `claude` 라는 **한 명**만 존재하고, 겹침
 3. OS 사용자 이름
 4. 호스트 이름
 
-**이름은 설치기를 켠 폴더의 git 설정에서 나온다.** git 은 저장소 안이면 그 저장소의
-`user.name` 을, 밖이면 전역 값을 답한다. 그래서 앞으로 일할 저장소 안에서 설치하는
-것이 맞다 — 그래야 MCP 가 쓰는 이름과 같은 저장소에서 손으로 `axmap` 을 칠 때의
-이름이 같아진다. 다르면 한 사람이 장부에서 둘이 되고, **자기가 잡은 것을 자기가
-반납하지 못한다**(`release` 종료 코드 5).
+**기본 전역 setup의 이름은 전역 Git 설정에서 정한다.** setup을 실행한 repo의 로컬 이름을 다른 repo에 가져가지 않는다. 명시적 프로젝트 설정에서는 해당 repo의 이름을 사용할 수 있다. 선점부터 반납까지 같은 이름·세션을 사용해야 한다.
 
 이름 검증은 설치기가 다시 짜지 않고 저장소의 `agentNameError()` 를 그대로 부른다.
 설치기가 통과시킨 이름을 서버가 거부하는 일이 없어야 하기 때문이다.
@@ -207,16 +202,9 @@ 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`는 1.3.0부터 지원한다.** 클라이언트가 지원을 선언하면 `roots/list`로 작업 폴더를 받고 변경 알림도 처리한다. 지원하지 않는 클라이언트는 시작 repo를 사용하고, 실행 중 경로 변경은 도구의 `cwd`로 전달한다. 프로토콜 회귀 테스트로 검증했으며 클라이언트별 실제 지원 여부는 별도 확인이 필요하다.
 

package/mcp/SETUP-FOR-AI.md

@@ -8,15 +8,14 @@ Node 20 이상과 git을 확인한다. npm 패키지 이름은 `axmap-cli`다.
 npm install -g axmap-cli@latest
 ```
 
-사용자가 지정한 git 저장소에서 다음 명령을 실행한다. 대상 저장소가 불분명하면 먼저 확인한다.
+Git 저장소 밖을 포함해 어느 폴더에서든 다음 명령을 실행한다. setup에는 작업 repo를 지정할 필요가 없다.
 
 ```bash
 axmap setup --dry-run
 axmap setup
-axmap doctor
 ```
 
-`setup`은 AI CLI의 사용자 설정에 MCP를 등록하고 대상 저장소에 장부와 훅을 만든다. 전역 MCP 등록에 `AXMAP_REPO`를 특정 폴더로 고정하지 않는다. 다른 원격을 공유하려면 `--remote <git-주소>`를 명시한다.
+`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`을 실행한다.
 

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "//name": "🔴 npm 의 'axmap' 은 2022년부터 남이 쓰고 있는 다른 꾸러미다(leozin_ 의 Map 라이브러리, 1.1.2). 그래서 `npx axmap` 은 우리 것이 아니고, 누구에게도 그렇게 안내하면 안 된다. 2026-08-28 에 axmap-cli 로 정했다 — 스코프(@사용자/이름)를 쓰지 않는 이유는 스코프가 npm 계정 이름에 묶여서 나중에 팀이나 조직으로 옮길 때 이름이 통째로 바뀌기 때문이다. 사람이 치는 **명령** 이름은 그대로 axmap 이다 (아래 bin) — 꾸러미 이름과 명령 이름은 달라도 된다.",
   "name": "axmap-cli",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "//private": "🔴 여기 있던 \"private\": true 를 2026-08-28 에 지웠다. 그 줄이 있는 동안 npm publish 는 거부됐다. 되돌리려면 다시 넣으면 되지만, 이미 올라간 버전은 그래도 안 사라진다 — npm 은 같은 번호를 덮어쓰지 못하고 삭제도 72시간 안에만 된다. 즉 이 줄을 되살리는 것은 '앞으로 안 올린다' 는 뜻이지 '올린 것을 없앤다' 는 뜻이 아니다.",
   "//publishConfig": "axmap-cli 는 스코프가 없어서 기본이 이미 공개다. 즉 지금은 없어도 된다. 그래도 남겨 두는 이유: 나중에 @조직/axmap 처럼 스코프를 붙이는 날 이 줄이 없으면 publish 가 '유료 플랜이 필요하다'는 엉뚱한 말로 실패한다.",
   "publishConfig": {

package/tools/mcp-register.mjs

@@ -105,6 +105,7 @@ const same = (a, b) => JSON.stringify(a) === JSON.stringify(b)
  */
 const sameEntry = (cur, want) =>
   !!cur && cur.command === want.command &&
+  !cur.cwd && !Object.hasOwn(cur.env ?? {}, 'AXMAP_REPO') &&
   JSON.stringify(cur.args || []) === JSON.stringify(want.args) &&
   Object.entries(want.env).every(([k, v]) => ((cur.env || {})[k] === v))
 
@@ -118,6 +119,8 @@ function doClaude(bin, repo) {
     snippetClaude()
     return
   }
+  want.env = { ...(cur?.env ?? {}), ...want.env }
+  delete want.env.AXMAP_REPO
   if (sameEntry(cur, want)) { ok('claude', '이미 등록돼 있습니다 (user 범위)'); return }
 
   // 문서에 있다고 믿고 부르지 않는다 — 먼저 물어본다. doCodex 와 같다.
@@ -133,7 +136,7 @@ function doClaude(bin, repo) {
     '--', want.command, ...want.args]
 
   if (DRY) {
-    hm('claude', `(dry-run) ${cur ? 'claude mcp remove axmap -s user 뒤 ' : ''}claude ${add.join(' ')}`)
+    hm('claude', '(dry-run) Claude 사용자 설정의 axmap 서버 경로·환경을 갱신합니다')
     return
   }
 
@@ -220,6 +223,8 @@ function mergeJson(label, file) {
   }
 
   const servers = cfg.mcpServers ?? {}
+  want.env = { ...(servers.axmap?.env ?? {}), ...want.env }
+  delete want.env.AXMAP_REPO
   if (same(servers.axmap, want)) { ok(label, `이미 등록돼 있습니다: ${file}`); return }
 
   const had = servers.axmap !== undefined
@@ -261,31 +266,56 @@ function snippetJson() {
 // 🔴 TOML 을 직접 파싱하지 않는다. 파서를 새로 짜는 것은 이 저장소의 "의존성 없음" 과
 //    "판정을 복잡하게 만들지 않는다" 에 둘 다 어긋나고, 어설픈 파서가 남의 config.toml 을
 //    깨뜨리는 것이 이 작업에서 나올 수 있는 최악의 결과다. 쓰는 일은 codex 자신에게 맡긴다.
-function doCodex(bin) {
-  const run = (args) => spawnSync(bin, args, { encoding: 'utf8', windowsHide: true })
+export function doCodex(bin, { run: injectedRun, dry = DRY } = {}) {
+  const run = injectedRun ?? ((args) => spawnSync(bin, args, { cwd: os.homedir(), encoding: 'utf8', windowsHide: true }))
 
   const help = run(['mcp', '--help'])
   if (help.status !== 0 || !/\badd\b/.test(`${help.stdout}${help.stderr}`)) {
     hm('codex', "'codex mcp add' 를 확인하지 못했습니다 — 손으로 넣으세요")
     snippetToml()
-    return
+    return false
   }
 
-  // 이미 들어 있으면 다시 넣지 않는다. setup 은 몇 번을 돌려도 안전해야 한다.
-  const list = run(['mcp', 'list'])
-  if (list.status === 0 && /\baxmap\b/.test(`${list.stdout}`)) {
-    ok('codex', `이미 등록돼 있습니다 (codex mcp list)`)
-    return
+  // Check the actual command and environment, not just the server name. An old
+  // registration may still point at a temporary install or pin AXMAP_REPO.
+  const list = run(['mcp', 'list', '--json'])
+  let servers
+  try { servers = JSON.parse(list.stdout) } catch { /* reported below */ }
+  if (list.status !== 0 || !Array.isArray(servers)) {
+    no('codex', '기존 MCP 설정을 확인하지 못했습니다 — 설정을 덮어쓰지 않았습니다')
+    return false
+  }
+  const current = servers.find((s) => s.name === 'axmap')
+  const transport = current?.transport
+  const want = entry()
+  const wantedEnv = { ...(transport?.env ?? {}), ...want.env }
+  delete wantedEnv.AXMAP_REPO
+  if (transport?.type === 'stdio' && sameEntry(transport, { ...want, env: wantedEnv }) &&
+      !transport.cwd && !Object.hasOwn(transport.env ?? {}, 'AXMAP_REPO') && current.enabled !== false) {
+    ok('codex', '전역 등록이 최신입니다 — 실행 위치의 repo를 사용합니다')
+    return true
   }
 
-  const add = ['mcp', 'add', 'axmap', '--env', 'AXMAP_ACTOR=agent', '--env', 'AXMAP_TTL=45m', '--', 'node', SERVER]
-  if (DRY) { hm('codex', `(dry-run) codex ${add.join(' ')}`); return }
+  const add = ['mcp', 'add', 'axmap', ...Object.entries(wantedEnv).flatMap(([k, v]) => ['--env', `${k}=${v}`]), '--', want.command, ...want.args]
+  if (dry) { hm('codex', '(dry-run) codex mcp add로 전역 axmap 서버 경로·환경을 갱신합니다'); return true }
 
   const r = run(add)
-  if (r.status === 0) ok('codex', 'codex mcp add 로 등록했습니다')
+  if (r.status === 0) {
+    const check = run(['mcp', 'list', '--json'])
+    let saved
+    try { saved = JSON.parse(check.stdout)?.find((s) => s.name === 'axmap') } catch { /* below */ }
+    if (check.status === 0 && sameEntry(saved?.transport, { ...want, env: wantedEnv }) &&
+        !saved.transport.cwd && !Object.hasOwn(saved.transport.env ?? {}, 'AXMAP_REPO')) {
+      ok('codex', '전역 등록을 갱신했습니다 — 실행 위치의 repo를 사용합니다')
+      return true
+    }
+    no('codex', '등록 후 서버 경로·작업 폴더 설정이 일치하지 않습니다')
+    return false
+  }
   else {
     no('codex', `codex mcp add 가 실패했습니다 (${(r.stderr || r.stdout || '').trim().split('\n')[0] || `exit ${r.status}`})`)
     snippetToml()
+    return false
   }
 }
 
@@ -339,7 +369,7 @@ function main() {
     any = true
     if (a.id === 'claude') doClaude(bin, root)
     else if (a.id === 'agy') doAgy()
-    else if (a.id === 'codex') doCodex(bin)
+    else if (a.id === 'codex' && !doCodex(bin)) return 1
   }
 
   if (!any) hm('CLI', '이 PC 에서 AI CLI 를 찾지 못했습니다 — 나중에 다시 실행하세요')
@@ -350,4 +380,4 @@ function main() {
   return 0
 }
 
-process.exit(main())
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) process.exit(main())

package/tools/setup.mjs

@@ -1,43 +1,9 @@
 #!/usr/bin/env node
 /**
- * `npx axmap setup` 의 본체 — **저장소를 clone 하지 않고** 이 PC 와 이 저장소에
- * axMap 을 붙인다.
- *
- *   npx -y axmap-cli@latest setup
- *   npx -y axmap-cli@latest setup --remote https://lab.ssafy.com/우리팀/우리저장소.git
- *
- * ── 이 파일이 메우는 구멍 ───────────────────────────────────────────────────
- *
- * `mcp/install.sh` · `mcp/install.ps1` 은 이미 "홈에 복사하고 이 PC 의 AI CLI 에
- * 등록한다" 를 한다. 다만 **axMap 파일이 이미 손에 있어야** 시작할 수 있다 —
- * 스크립트만 따로 내려받으면 대놓고 거절한다. 그래서 지금까지 설치의 첫 단계는
- * 언제나 "저장소를 통째로 clone" 이었다.
- *
- * npm 꾸러미가 그 첫 단계를 대신한다. `npx` 가 꾸러미를 받아 풀어 주므로,
- * 이 파일이 도는 시점에는 axMap 원본이 이미 옆에 있다. 여기서는 그 뒤를 잇는다.
- *
- *   1. 이 PC 에 프로그램을 둔다      → mcp/install.{sh,ps1} 에 맡긴다 (다시 안 짠다)
- *   2. 이 PC 의 AI CLI 에 등록한다   → 위와 같음
- *   3. 대상 저장소에 장부를 만든다   → axmap init
- *   4. 커밋 훅을 심는다              → axmap hook install
- *   5. 슬래시 명령을 놓는다          → ~/.claude/commands/ (또는 저장소 안)
- *
- * ── 🔴 git 을 떼어내지 않는다 ───────────────────────────────────────────────
- *
- * 없앤 것은 **"axMap 코드를 받는 수단으로서의 git"**(clone·벤더링·git pull)이지
- * **"협업 백엔드로서의 git"** 이 아니다. 장부와 쪽지는 그대로 고아 브랜치
- * (`axmap/claims` · `axmap/bus`)로 오간다. git push 의 ref CAS(Compare-And-Swap —
- * "내가 읽은 뒤로 바뀐 게 없을 때만 쓴다") 가 직렬화를 공짜로 주기 때문이고,
- * 그것을 버리면 락 서버를 따로 세워야 한다. 그건 다른 제품이다.
- *
- * 그래서 대상이 git 저장소가 아니면 **여기서 멈춘다.** 반쯤 되는 상태로 두면
- * claim 이 아무에게도 안 가면서 조용히 성공한다 — 이 도구에서 제일 나쁜 실패다.
- *
- * ── 종료 코드 ───────────────────────────────────────────────────────────────
- *
- *   0  다 됐다
- *   1  시작할 수 없다 (node 가 낮다 · git 저장소가 아니다 · 이름을 못 정했다)
- *   2  일부가 안 됐다. 무엇이 안 됐는지 !! 줄에 있다
+ * Install axMap globally from any directory. Installation is machine state;
+ * repository ledgers are prepared at runtime in the caller's working repo.
+ * Only explicit project options (--repo / --remote / --commands project)
+ * select a repository during setup. Commit enforcement remains opt-in.
  */
 
 import { spawnSync } from 'node:child_process'
@@ -84,21 +50,21 @@ const has = (n) => argv.includes(n)
 
 if (has('-h') || has('--help')) {
   say(`
-axmap setup — 이 PC 와 이 저장소에 axMap 을 붙인다 (clone 하지 않는다)
+axmap setup — 어느 폴더에서든 이 PC에 axMap을 전역 설치·등록한다
 
   npx -y axmap-cli@latest setup
   npx -y axmap-cli@latest setup --remote <이름 또는 git 주소>
 
-  --repo <경로>        선점을 걸 저장소 (기본: 지금 폴더의 git 루트)
+  --repo <경로>        선택 사항: 이 저장소의 장부·커밋 훅도 명시적으로 준비한다
   --remote <이름|URL>  장부를 둘 원격. git 주소를 주면, 그 주소를 가리키는 원격이
                        없을 때 'axmap' 이라는 이름으로 하나 더한다
-  --name <이름>        장부에 찍힐 내 이름 (기본: git config user.name)
+  --name <이름>        내 이름 (기본: 전역 git config user.name, 명시적 repo는 로컬 값)
   --dest <경로>        프로그램을 둘 자리 (기본: ~/.axmap/app)
   --commands <곳>      슬래시 명령을 둘 자리: global(기본) · project · none
   --hook               프롬프트마다 쪽지를 받는 하네스 훅을 settings.json 에 더한다
                        (기본은 안 더한다 — 매 턴 도는 명령이라 사람이 고를 일이다)
   --no-register        이 PC 의 AI CLI 등록을 건너뛴다
-  --no-ledger          장부·훅을 건드리지 않는다 (프로그램 설치만)
+  --no-ledger          --repo를 지정했어도 장부·커밋 훅을 건드리지 않는다
   --dry-run            아무것도 쓰지 않고 무엇을 할지만 찍는다
 
 종료 코드: 0 성공 · 1 시작 불가 · 2 일부 실패
@@ -132,24 +98,19 @@ ok('node', `v${process.versions.node}`)
 
 // ── 2. 대상 저장소 ──────────────────────────────────────────────────────────
 //
-// 🔴 여기서 멈추는 것이 맞다. 위의 "git 을 떼어내지 않는다" 를 보라.
-const where = path.resolve(flag('--repo') ?? process.cwd())
-if (!fs.existsSync(where)) die(`그런 폴더가 없습니다: ${where}`)
-
-const top = git(['rev-parse', '--show-toplevel'], where)
-if (top.code !== 0) {
-  die(
-    `git 저장소가 아닙니다: ${where}\n\n` +
-      `  axMap 의 장부와 쪽지는 git 의 고아 브랜치로 오갑니다. git push 의 CAS\n` +
-      `  (내가 읽은 뒤로 바뀐 게 없을 때만 쓴다)가 여러 사람의 동시 선점을 줄 세워\n` +
-      `  주기 때문입니다. 저장소가 없으면 그 줄이 없어, claim 이 아무에게도 가지\n` +
-      `  않으면서 조용히 성공합니다.\n\n` +
-      `  먼저 작업할 저장소 안으로 들어간 뒤 다시 실행하세요:\n` +
-      `    cd <저장소>  &&  npx -y axmap-cli@latest setup`,
-  )
+// Installation has no working repository. Only explicit project options use one.
+const projectRequested = has('--repo') || has('--remote') || commandsWhere === 'project'
+if (has('--repo') && !flag('--repo')) die('--repo 뒤에 저장소 경로를 지정하세요.')
+let REPO = null
+if (projectRequested) {
+  const where = path.resolve(flag('--repo') ?? process.cwd())
+  const top = git(['rev-parse', '--show-toplevel'], where)
+  if (top.code !== 0) die(`프로젝트 옵션의 대상이 Git 저장소가 아닙니다: ${where}\n전역 설치만 하려면 --repo, --remote, --commands project 없이 axmap setup을 실행하세요.`)
+  REPO = path.resolve(top.out)
+  ok('저장소', `${REPO}  (명시적 프로젝트 설정)`)
+} else {
+  ok('설치 범위', '이 PC 전체 — 작업 repo는 이후 CLI·MCP 실행 위치에서 결정합니다')
 }
-const REPO = path.resolve(top.out)
-ok('저장소', REPO)
 
 // ── 3. 이름 ─────────────────────────────────────────────────────────────────
 //
@@ -159,8 +120,8 @@ ok('저장소', REPO)
 let name = flag('--name')
 let nameFrom = '--name'
 if (!name) {
-  const g = git(['config', 'user.name'], REPO)
-  if (g.code === 0 && g.out) { name = g.out; nameFrom = 'git config user.name' }
+  const g = git(REPO ? ['config', 'user.name'] : ['config', '--global', 'user.name'], REPO ?? os.homedir())
+  if (g.code === 0 && g.out) { name = g.out; nameFrom = REPO ? 'git config user.name' : 'git config --global user.name' }
 }
 if (!name) {
   try { name = os.userInfo().username; nameFrom = 'OS 사용자 이름' } catch { /* 아래 */ }
@@ -230,7 +191,7 @@ function configureRemote(spec) {
   else ok('장부 원격', `git config axmap.remote = ${picked}`)
 }
 
-configureRemote(flag('--remote'))
+if (REPO) configureRemote(flag('--remote'))
 
 // ── 5. 프로그램을 이 PC 에 둔다 + AI CLI 에 등록한다 ────────────────────────
 //
@@ -250,8 +211,8 @@ function installAndRegister() {
 
   say('')
   const r = win
-    ? spawnSync('powershell', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', script, '-Source', SOURCE_ROOT, '-Dest', DEST, '-Name', name], { stdio: 'inherit', windowsHide: true })
-    : spawnSync('bash', [script, '--source', SOURCE_ROOT, '--dest', DEST, '--name', name], { stdio: 'inherit' })
+    ? spawnSync('powershell', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', script, '-Source', SOURCE_ROOT, '-Dest', DEST, '-Name', name], { cwd: os.homedir(), stdio: 'inherit', windowsHide: true })
+    : spawnSync('bash', [script, '--source', SOURCE_ROOT, '--dest', DEST, '--name', name], { cwd: os.homedir(), stdio: 'inherit' })
   say('')
 
   if (r.status === 0) ok('설치·등록', DEST)
@@ -266,6 +227,7 @@ installAndRegister()
 //    부르면 `hook install` 이 그 임시 경로를 훅에 박고, npx 캐시가 비워지는 순간
 //    훅이 없는 파일을 가리킨다 — 커밋할 때마다 오류가 나는데 원인은 안 보인다.
 function ledgerAndHook() {
+  if (!REPO) { hm('장부·커밋 훅', '작업 repo의 장부는 첫 사용 때 자동 준비합니다. 커밋 훅은 axmap hook install로 선택합니다.'); return }
   if (has('--no-ledger')) { hm('장부', '--no-ledger — 건너뜁니다'); return }
 
   const installed = path.join(DEST, 'bin', 'axmap.mjs')
@@ -482,9 +444,10 @@ say('설치가 끝났습니다.')
 say('')
 say('다음:')
 say('  1. AI CLI 를 완전히 껐다가 다시 켭니다')
-say(`  2. ${REPO} 에서 "/ax-start 로 시작해줘" 또는 "ax_status 로 지금 누가 뭘 잡고 있는지 보여줘"`)
+say('  2. 원하는 Git repo에서 AI CLI를 실행합니다. 실행한 repo에 자동으로 연결됩니다.')
+say('  3. "ax_status로 지금 누가 뭘 잡고 있는지 보여줘"로 시작합니다. repo마다 setup이나 init을 반복하지 않습니다.')
 say('')
 say(`${C.d}  파일을 고치기 전에 claim → 끝나면 release. 그게 전부입니다.${C.x}`)
-say(`${C.d}  점검:  npx -y axmap-cli@latest doctor${C.x}`)
+say(`${C.d}  조회: 원하는 Git repo에서 axmap status${C.x}`)
 say('')
 process.exit(EXIT.OK)