axmap-cli 0.0.1

package/mcp/README.md

@@ -0,0 +1,254 @@
+# axMap MCP 서버
+
+**MCP**(*Model Context Protocol* — **AI 도구가 바깥 프로그램을 "도구" 로 불러 쓸 수
+있게 하는 규격**)로 axMap 을 AI CLI 에 붙인다.
+
+- 붙이면 AI 도구가 **"나는 이 파일들을 건드리겠다"를 선언**하게 된다. 겹치면 그 자리에서 거부당한다
+- 코드 충돌이 나기 전에 **의도 충돌**을 먼저 터뜨리는 것이고, 뷰어는 그 선언을 읽어 화면을 그린다
+- **한 번 설치하면 아무 저장소에서나 붙는다.** 작업할 저장소에는 파일을 하나도 남기지 않는다
+
+---
+
+## 설치
+
+한 줄이다. 저장소를 받은 뒤 **앞으로 일할 폴더에서** 실행한다.
+
+```powershell
+# Windows
+powershell -ExecutionPolicy Bypass -File "$HOME\axmap-src\axmap\mcp\install.ps1"
+```
+
+```bash
+# macOS / Linux
+bash "$HOME/axmap-src/axmap/mcp/install.sh"
+```
+
+설치기가 하는 일은 셋이다.
+
+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 가 없습니다 (건너뜀 — 실패가 아닙니다)
+```
+
+**설치가 끝나면 AI CLI 를 완전히 껐다가 다시 켠다.** MCP 서버 목록은 CLI 가 켜질 때
+한 번만 읽힌다.
+
+### AI 에게 시키려면
+
+사람이 명령을 칠 필요도 없다. 자기 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 <폴더>` |
+
+이미 설치돼 있으면 **묻지 않고 갱신한다.** 무엇을 갱신했는지는 줄마다 찍힌다.
+
+---
+
+## 도구
+
+| 도구 | 언제 |
+|---|---|
+| `ax_brief()` | 이 저장소에서 처음 일할 때 **가장 먼저** |
+| `ax_status()` | 지금 누가 어디를 잡고 있나 |
+| `ax_check(paths)` | 내가 건드릴 곳이 비었나 — **선언은 안 한다.** 계획 세울 때 |
+| `ax_claim(paths, intent, task?)` | **파일을 고치기 전에 반드시.** intent 는 사람이 화면에서 읽는다 |
+| `ax_release(paths?)` | 끝나면 즉시. 생략하면 전부 반납 |
+| `ax_renew()` | 길어지면 시간 연장 |
+| `ax_inbox(id?)` | 다른 에이전트가 나에게 보낸 쪽지를 읽는다 |
+| `ax_send(to?, subject, body)` | 다른 에이전트에게 쪽지를 보낸다 |
+| `ax_init()` | 장부가 없을 때 한 번. 이미 있으면 아무것도 바꾸지 않는다 |
+
+`ax_claim` 이 거부되면(겹침) **재시도하지 말고 다른 작업으로 옮겨야 한다.**
+같은 요청은 몇 번을 보내도 같은 답이 온다. 메시지에 점유자·작업·남은 시간이 들어
+있으니 그걸 읽고 비어 있는 다른 곳으로 간다. 도구 설명에도 그렇게 적어두었다.
+
+Claude Code 에서는 `/ax`, `/ax-start`, `/ax-done`, `/ax-tell` 로도 부른다 —
+다만 그 슬래시 명령은 이 저장소의 `.claude/commands/` 에 들어 있어서 **이 저장소를
+열었을 때만** 뜬다. 다른 저장소에서는 위 도구 이름을 문장으로 부르면 된다.
+
+에이전트에게 줄 지시문은 이 셋이면 충분하다.
+
+```
+파일을 수정하기 전에 ax_claim 으로 건드릴 경로를 선언하라.
+거부되면 재시도하지 말고 겹치지 않는 다른 작업으로 옮겨라.
+작업이 끝나면 ax_release 를 호출하라.
+```
+
+---
+
+## 원리와 실측
+
+### 어느 CLI 에 어떻게 붙나
+
+전송이 표준(stdio + 줄바꿈 JSON-RPC 2.0)이라 **MCP 를 지원하는 클라이언트면 무엇이든
+붙는다.** 갈리는 것은 "자동으로 붙느냐" 뿐이다.
+
+| CLI | 설정 파일 | 누가 넣나 | 확인했나 |
+|---|---|---|---|
+| 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` 로 | ⚠️ 문서로만 확인, 실물 미확인 |
+
+`agy` 에서 확인한 것: 전역 파일은 먹고, 저장소의 `.mcp.json` 은 **안 먹는다.**
+공식 문서의 작업 폴더용 `.agents/mcp_config.json` 도 CLI 에서는 안 먹었다(IDE 쪽으로 보인다).
+일부러 없는 파일을 가리키면 도구가 사라지는 것까지 확인했다 — 위 결과가 캐시가 아님을
+보인 대조군이다.
+
+**CLI 를 찾고 각자의 설정에 넣는 일은 [`../tools/mcp-register.mjs`](../tools/mcp-register.mjs)
+가 한다.** 설치기는 그것을 부를 뿐 다시 구현하지 않는다. 그 위에 설치기가 얹는 것은 둘이다.
+
+- **Claude Code 의 전역 등록.** `mcp-register` 는 Claude Code 에 아무것도 등록하지
+  않는다 — 저장소의 `.mcp.json` 이 알아서 발견되는 것에 기대기 때문이다. 전역 설치에는
+  그 파일이 없으므로 설치기가 user 범위로 직접 넣는다
+- **CLI 마다 한 줄씩 찍는 최종 보고.** `mcp-register` 의 안내는 `if (!any)` 라서
+  **셋 중 하나라도 찾으면** 아무 말이 없다. Claude Code 만 깔린 PC 에서 Codex 로
+  일하는 사람은 `OK claude` 만 보고 자기 도구는 안 붙은 채 넘어간다
+
+### 손으로 넣을 때
+
+```json
+{
+  "mcpServers": {
+    "axmap": {
+      "command": "node",
+      "args": ["<홈>/.axmap/app/mcp/server.mjs"],
+      "env": {
+        "AXMAP_AGENT": "홍길동",
+        "AXMAP_ACTOR": "agent",
+        "AXMAP_TTL": "45m"
+      }
+    }
+  }
+}
+```
+
+| 환경변수 | 뜻 |
+|---|---|
+| `AXMAP_REPO` | 대상 저장소를 **한 곳으로 고정**한다. 전역 설치에서는 **비운다** (아래) |
+| `AXMAP_AGENT` | 이 에이전트의 이름. 여럿 붙을 때 서로 달라야 한다 |
+| `AXMAP_ACTOR` | `agent`(대화형) / `background`(백그라운드) / `human` / `team` — 화면 색이 갈린다 |
+| `AXMAP_TTL` | 기본 선점 시간 (기본 45m) |
+
+### 🔴 `AXMAP_REPO` 는 비운다 — 대상은 부를 때마다 다시 정해진다
+
+서버는 도구를 부를 때마다 대상 저장소를 다시 정한다. 순서는 넷이고 위가 이긴다:
+`AXMAP_REPO` → `~/.axmap/current.json`(앱에서 [폴더 열기] 로 고른 것) → git 저장소
+루트 → 현재 폴더. 근거와 버린 대안은 [DECISIONS.md 의 D19](../docs/DECISIONS.md).
+
+전역 등록인데 `AXMAP_REPO` 에 한 폴더를 박아 두면 **등록은 전역인데 대상은 한 곳으로
+굳는다.** 다른 저장소를 열어도 아무 오류 없이 엉뚱한 장부에 claim 이 쌓인다.
+그래서 설치기도 `mcp-register` 도 이 값을 **일부러 안 적는다.**
+
+### 🔴 `AXMAP_AGENT` 는 반대로 반드시 적는다 — 다만 개인 설정에만
+
+**저장소에 커밋되는 `.mcp.json` 에는 `AXMAP_AGENT` 를 적지 않는다.**
+적는 순간 그 값이 clone 한 모두의 이름이 된다.
+
+예전 이 저장소의 `.mcp.json` 은 이름이 없으면 모두에게 `claude` 를 줬다. 팀원 다섯이
+clone 하면 장부에는 `claude` 라는 **한 명**만 존재하고, 겹침 판정은 자기 claim 을
+겹침으로 보지 않으므로 다섯이 서로의 영역을 아무 경고 없이 덮어쓴다.
+락이 조용히 다섯 명에게 발급된 것이고, 이 프로젝트가 fail-closed 로 막겠다고 한
+바로 그 실패다. 그래서 그 줄을 지웠고 **기본 이름도 없앴다.**
+
+전역 설치는 사정이 다르다. 쓰는 곳이 **홈 디렉터리 아래의 개인 설정**이라 커밋되지
+않고, 팀 저장소가 아닌 폴더에서도 서버가 뜨는데 그런 폴더에는 `git config user.name`
+이 없을 수 있다. 그러면 서버는 이름을 정하지 못하고 그냥 죽는다. 그래서 설치기가
+**사람마다 다른 값**을 한 번 박아 둔다. 후보 순서는 이렇다.
+
+1. `-Name` / `--name` 으로 준 값
+2. `git config user.name`
+3. OS 사용자 이름
+4. 호스트 이름
+
+**이름은 설치기를 켠 폴더의 git 설정에서 나온다.** git 은 저장소 안이면 그 저장소의
+`user.name` 을, 밖이면 전역 값을 답한다. 그래서 앞으로 일할 저장소 안에서 설치하는
+것이 맞다 — 그래야 MCP 가 쓰는 이름과 같은 저장소에서 손으로 `axmap` 을 칠 때의
+이름이 같아진다. 다르면 한 사람이 장부에서 둘이 되고, **자기가 잡은 것을 자기가
+반납하지 못한다**(`release` 종료 코드 5).
+
+이름 검증은 설치기가 다시 짜지 않고 저장소의 `agentNameError()` 를 그대로 부른다.
+설치기가 통과시킨 이름을 서버가 거부하는 일이 없어야 하기 때문이다.
+규격은 [SPEC.md](../docs/SPEC.md) 의 "에이전트 이름을 정하는 순서" 절에 있다.
+
+### 남의 저장소에 붙일 때 — 프로그램은 여기, 데이터는 거기
+
+전역 설치는 이 구분이 **정상 사용**이다. 무엇을 어디에서 잡느냐가 이 서버에서 가장
+자주 틀리는 곳이고, 실제로 세 군데가 동시에 틀려 있었다.
+
+| | 어디 | 왜 |
+|---|---|---|
+| `bin/axmap.mjs`, `tools/bus.mjs` | **`~/.axmap/app` (axMap 쪽)** | 실행할 프로그램이다. 대상 저장소에는 없다 |
+| 장부 `.axmap/`, 쪽지함 `docs/bus/` | **대상 저장소 쪽** | 그 팀의 데이터다. 그 팀 저장소에 남아야 한다 |
+| `ax_brief` 가 읽는 문서 | **대상 저장소 쪽** | 대상을 설명해야 한다 |
+
+`ax_brief` 는 대상 저장소의 `CLAUDE.md`·`README.md`·`docs/` 만 읽고, 없으면
+**없다고 말한다.** axMap 자신의 문서로 대신 채우지 않는다 — 낡은 지도는 없는 지도보다
+나쁘고, 남의 지도를 자기 지도인 양 주는 것은 그보다 한 단계 더 나쁘다.
+
+이 조합(`AXMAP_REPO ≠ axMap`)은 `test/mcp.test.mjs` 가 고정한다.
+**자기 자신을 겨눠 놓고 시험하면 이 경로는 한 번도 안 돈다.**
+
+### 설계
+
+판정 로직을 여기서 다시 구현하지 않고 **`bin/axmap.mjs` 를 그대로 호출한다.**
+두 경로가 갈라지면 장부를 믿을 수 없게 되기 때문이다.
+관문 1(push CAS — **"내가 읽은 뒤로 바뀐 게 없을 때만 쓴다"**. git push 가 원래
+이렇게 동작한다)과 관문 2(겹침 판정)가 CLI 와 완전히 동일하게 적용된다.
+
+전송은 stdio + 줄바꿈 구분 JSON-RPC 2.0 이다. SDK 의존성 없이 직접 구현했다 —
+폐쇄망에서 npm 설치 없이 돌아야 한다는 제약이 여기에도 적용된다.
+설치기가 `bin` `src` `mcp` `tools` `app` `package.json` `LICENSE` 만 복사하고
+`desktop/`(Electron 껍데기)을 빼는 것도 같은 이유다. 받아야 할 것이 없다.
+
+---
+
+## 안 되는 것 / 아직 확인 못 한 것
+
+**Codex 는 실물로 확인하지 못했다.** 이 팀에 `codex` 가 깔린 PC 가 아직 없다.
+`~/.codex/config.toml` 형식은 공식 문서를 따른 것이고, `mcp-register` 는
+`codex mcp --help` 를 먼저 찔러 보고 그 하위 명령이 실제로 있을 때만 등록한다.
+TOML 을 직접 파싱하지도 쓰지도 않는다 — 어설픈 파서가 남의 `config.toml` 을 깨뜨리는
+것이 이 작업에서 나올 수 있는 최악의 결과다.
+
+**Codex 에는 이름이 안 들어간다.** `mcp-register` 가 `codex mcp add` 를 부를 때
+`AXMAP_AGENT` 를 빼고 부르고, 이미 등록돼 있으면 다시 부르지도 않는다. 그래서 설치기는
+codex 에 대해서는 **확인만 하고 이름은 손으로 넣으라고 한 줄 찍는다.** 확인 안 된
+도구의 설정을 추측으로 덮어쓰는 것보다 낫다고 봤다.
+
+**MCP `roots` 를 아직 안 만들었다.** 버린 것이 아니다. `roots` 는 클라이언트가 서버에게
+*"지금 열려 있는 작업 폴더는 여기"* 를 알려주는 규격의 표준 통로이고, D19 사다리의
+2번 자리에 들어갈 것이다. 먼저 안 한 이유는 클라이언트마다 지원 여부가 다르기 때문이다.
+
+**같은 이름이 두 곳에 생길 수 있다.** 이 저장소 안에서 Claude Code 를 켜면 저장소의
+`.mcp.json` 과 전역 등록이 둘 다 `axmap` 이라는 이름을 갖는다. 충돌로 깨지지는 않지만
+**켠 위치에 따라 다른 정의가 뜬다** — 하나는 저장소 안의 `axmap/mcp/server.mjs` 를,
+하나는 `~/.axmap/app/mcp/server.mjs` 를 가리킨다. 둘 다 도는 코드라 결과는 같지만
+같은 코드는 아니다.
+
+**팀 저장소의 `setup.ps1`/`setup.sh` 를 다시 돌리면 `agy` 등록이 되돌아간다.**
+그 스크립트도 `mcp-register` 를 부르는데, 그쪽은 서버 경로를 그 저장소 안의 것으로
+적고 이름을 지운다. 이 설치기를 다시 돌리면 원래대로 돌아온다.
+
+**`doctor` 는 전역 등록을 검사하지 않는다.** 저장소의 `.mcp.json` 만 본다. 그래서
+전역으로 설치한 PC 에서 `MCP 설정` 줄이 `~~` 로 뜨는 것은 정상이다 — 무게가 전역
+등록으로 옮겨간 지금 그 줄은 거짓 보고에 가깝다. 배경은
+[docs/HANDOVER.md](../../docs/HANDOVER.md) 4.4 절과 4.5 절에 있다.

package/mcp/SETUP-FOR-AI.md

@@ -0,0 +1,186 @@
+# AI 에이전트에게 주는 지시문 — axMap 을 이 PC 에 붙인다
+
+**이 문서는 사람이 읽으라고 쓴 것이 아니라 AI CLI 가 그대로 실행하라고 쓴 것이다.**
+사람은 자기 AI 도구에 이 한 줄만 던지면 된다.
+
+```
+이 파일 읽고 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`. 둘 다 없으면 여기서 멈추고 사람에게 설치를 요청해라.
+
+---
+
+## 1단계 — node 를 확인한다
+
+```
+node --version
+```
+
+**성공 판정:** `v20.x` 이상이 찍히고 종료 코드(**프로그램이 끝나면서 내는 숫자.
+0 이면 성공, 그 밖은 실패**)가 0.
+`v19` 이하거나 명령을 못 찾으면 **여기서 멈추고** 사람에게 "Node 20 이상이 필요하다"고 말해라.
+
+---
+
+## 2단계 — axMap 을 홈 디렉터리에 내려받는다
+
+받는 곳은 `~/axmap-src` 다. **지금 열려 있는 저장소 안이 아니다.**
+두 명령을 순서대로 그대로 실행해라. 첫 줄은 전에 받아 둔 것이 있으면 지운다.
+
+```
+node -e "require('fs').rmSync(require('path').join(require('os').homedir(),'axmap-src'),{recursive:true,force:true})"
+```
+
+```
+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` 이 거부되면 재시도하지 말고 겹치지 않는 다른 곳으로
+> 옮기면 됩니다 — 같은 요청은 몇 번을 보내도 같은 답이 옵니다.
+
+---
+
+## 나중에 다시 할 때
+
+- **최신으로 갱신** — 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)