axmap-cli 1.2.5 → 1.3.0

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

@@ -11,5 +11,6 @@ description: axMap — 이 저장소에서 일을 시작한다 (브리핑 →
    그 일에 필요한 경로를 **좁게** 골라 `ax_claim` 한다.
    `intent` 에는 사람이 읽을 한 문장을 적는다 — 팀원이 화면에서 그걸 본다.
 
-장부가 없다고 하면 `ax_init` 을 먼저 부른다.
+장부는 조회·선점 때 자동으로 준비한다. 별도 `ax_init` 호출은 필요 없다.
+작업 repo가 다르거나 여러 repo가 열려 있다면 도구의 `cwd`에 현재 작업 폴더 절대 경로를 전달한다.
 claim 이 거부되면(겹침) 재시도하지 말고 겹치지 않는 다른 작업을 제안한다.

package/CLAUDE.md

@@ -1,83 +1,30 @@
-# axMap 작업 규칙 — 색인 한 장
+# axMap 작업 규칙
 
-이 문서는 **axMap 자체를 고칠 때** 지키는 규칙의 **입구**다. 사람도 AI 에이전트도 읽는다.
-규칙 본문은 **[`rule/`](rule/) 폴더**에 갈래별로 나뉘어 있다. **필요할 때 그 파일을 연다.**
+axMap은 여러 AI 에이전트의 작업 경로를 선점하고 충돌을 예방하는 CLI 도구다. 현재 개발 범위는 CLI와 MCP를 통한 협업 기능이다. 코드 분석·지도·코퍼스 기준 도구로의 확장은 보류한다. 범위 결정은 `docs/DECISIONS.md`의 D21을 따른다. 산문은 `axMap`, 식별자와 명령은 `axmap`, npm 패키지는 `axmap-cli`를 쓴다.
 
-> 🔴 **2026-09-11 에 이렇게 바뀌었다.** 전에는 이 파일 하나에 전부(764줄) 들어 있었고,
-> Claude Code 는 **세션을 켤 때마다 그걸 통째로 읽는다.** 한 번도 안 쓰는 규칙까지
-> 매번 값을 치렀다. 지금은 이 색인만 항상 읽히고, 본문은 **찾아갈 때만** 읽는다.
-> 내용은 지우지 않았다 — 자리만 옮겼다.
+개발 기준은 `main`이다. 이 저장소의 소스 확인에는 `node bin/axmap.mjs`를 사용한다. PATH의 `axmap`은 npm 설치본일 수 있다.
 
-**이 문서가 기준이 되게 하려면 `claude` 를 이 폴더에서 켠다.** Claude Code 는 **켠 폴더**를
-기준으로 `CLAUDE.md` 를 읽는다. 팀 저장소 폴더에서 켜고 axMap 파일만 고치면, 읽히는 것은
-팀 규칙이지 이 문서가 아니다.
+## 작업 절차
 
-```bash
-cd C:/Users/SSAFY/Desktop/axMap
-claude
-```
-
-axMap 은 **AI Experience(ax) 의 지도**다 — 에이전트가 코드베이스에서 길을 찾고 서로를
-피해 가는 경험을 만든다. 팀에서는 여행 서비스를 만드는 **도구**로 쓰인다.
-
-> **산문에서는 `axMap`, 식별자·명령·경로·패키지 이름에서는 `axmap`.**
-> 다만 **MCP 도구 이름만 `ax_` 접두사**를 쓴다 (`ax_claim`, `ax_status` …).
-> 환경변수 접두사는 `AXMAP_`, 장부 브랜치는 `axmap/claims` 다.
-
-> 🔴 **팀 규칙은 여기 없다.** axMap 은 독립 저장소이고 팀은 npm 꾸러미 `axmap-cli` 로
-> 받아 쓴다. 팀 규칙은 그 저장소의 `CONTRIBUTING.md` 에 있다 —
-> `https://lab.ssafy.com/s15-bigdata-dist-sub1/S15P21E201`.
-> 상대경로(`../CLAUDE.md`)로 걸지 않는다. 폴더가 옮겨지면 조용히 거짓말이 된다.
-
----
-
-## 시작하기 전에 세 줄
+1. `docs/DECISIONS.md`, `docs/THREADS.md`, `docs/SPEC.md`, `docs/INVARIANTS.md`에서 관련 결정과 규격을 읽는다.
+2. 세션마다 고유한 `AXMAP_AGENT`와 `AXMAP_SESSION`을 정한다. 변경 전에 `node bin/axmap.mjs claim <경로> --task <작업> --intent "목적"`으로 선점한다.
+3. 선점이 겹치면 다른 영역으로 옮긴다. 필요한 경로만 잡고, 끝나면 `node bin/axmap.mjs release`로 반납한다.
+4. 선점 없는 커밋을 만들거나 `git commit --no-verify`로 훅을 우회하지 않는다. push 대상 원격과 브랜치를 확인한다.
 
-| | |
-|---|---|
-| **개발선** | `team-sync` 다. `main` 이 아니다 → [rule/01](rule/01-이-저장소의-함정.md) |
-| **고치기 전에** | `node bin/axmap.mjs claim <경로> --task … --intent …` → [rule/02](rule/02-선점-작업-반납.md) |
-| **고친 코드를 돌리려면** | `node bin/axmap.mjs …`. 그냥 `axmap` 은 **다른 판**이 돈다 → [rule/01](rule/01-이-저장소의-함정.md) |
-| **싸게 물어볼 일** | `agy --model gemini-3.8-flash-low -p='…'`. 🔴 `-p=` 는 **등호로 붙여** 쓴다 → [rule/08](rule/08-agy-외부-모델.md) |
+## 구현 기준
 
----
+루트 CLI는 Node 20+와 git만으로 동작한다. 새 의존성은 추가 전에 사용자와 논의한다. 데스크톱 셸의 기존 의존성은 `desktop/package.json`을 따른다.
 
-## 🔴 하지 말 것 — 한눈에
+없는 데이터와 읽지 못한 데이터를 구별한다. 판정을 못 하면 통과시키지 않는다. 주석에는 구현 이유를 쓰고, 수치에는 측정 조건과 근거를 붙인다. 테스트 개수나 미측정 성능을 문서에 쓰지 않는다.
 
-이 표만은 항상 읽힌다. 나머지는 찾아본다.
+## 검증
 
-| | 왜 |
-|---|---|
-| `git commit --no-verify` | 장부에 없는 변경이 생기고, `audit` 이 나중에 불변식 위반으로 잡는다 |
-| 아무 생각 없이 `git push` | 대상이 `origin`(팀 저장소)일 수 있다. axMap 은 **`personal team-sync`** |
-| `git merge` 로 다른 갈래 가져오기 | 공통 조상이 없어 거부당한다. `git checkout <브랜치> -- <경로>` |
-| `git merge-base` 결과를 파이프로 잇기 | 실패해도 조용하다. 종료 코드를 따로 본다 |
-| 테스트 **개수**를 문서에 적기 | 늘릴 때마다 낡는다. 판정은 종료 코드다 |
-| 실측 안 한 숫자 적기 | 확실하지 않으면 **"확인 못 함"** 이라고 쓴다 |
-| 낡은 실측 지우기 | 정정한 날짜와 함께 **둘 다** 남긴다 |
-| 선점이 방금 풀린 자리에 바로 들어가기 | 선점은 "지금" 만 막는다. 남은 결과물은 안 막는다 |
-| 새 의존성 추가 | 추가하기 전에 **사람에게 묻는다** |
-| 세기·고르기를 모델에게 시키기 | 스크립트가 토큰 0으로 **더 정확히** 한다 → [rule/08](rule/08-agy-외부-모델.md) |
-| `setx` 로 PATH 고치기 | 1024자에서 **자른다.** 잘린 줄은 경고 없이 사라진다 → [rule/08](rule/08-agy-외부-모델.md) |
-
----
-
-## 규칙 본문 — 이럴 때 이 파일을 연다
-
-문서 안에서 **"2절"** 이라고 하면 **`rule/02-…`** 를 말한다. 번호는 그대로 남겼다.
-
-| 파일 | 언제 여나 |
-|---|---|
-| [00 — 백그라운드 에이전트](rule/00-백그라운드-에이전트.md) | 일을 대화에서 직접 할지 넘길지 가를 때. 프롬프트에 무엇을 박아야 하나 |
-| [01 — 이 저장소의 함정](rule/01-이-저장소의-함정.md) | git 이 이상하게 굴 때. remote 이름·개발선·무관한 역사·`partOf()`·어느 `axmap` 이 도나 |
-| [02 — 선점 → 작업 → 반납](rule/02-선점-작업-반납.md) | 파일을 고치기 전. 거부당했을 때. 커밋 훅이 막을 때. 쪽지 주고받기 |
-| [03 — 검증](rule/03-검증.md) | 끝내기 전. 무엇을 돌려야 끝난 것인가. 화면 코드를 건드렸을 때 |
-| [04 — 코드 규칙](rule/04-코드-규칙.md) | 코드를 쓸 때. 의존성·순수 로직·fail-closed·SPEC·불변식·버전 |
-| [05 — 코드를 쓰기 전에](rule/05-코드를-쓰기-전에.md) | 무엇을 만들지 아직 안 정했을 때. 단순함·외과적 변경·선택지로 확인받기 |
-| [06 — 답변과 문서](rule/06-답변과-문서.md) | 사람에게 답할 때. 터미널에 전부·두 가지까지·기호로만 부르지 않기·용어 풀기 |
-| [07 — NotebookLM 자료 폴더](rule/07-notebooklm-자료폴더.md) | *"LM 에 넣게 자료 만들어줘"* 라는 말을 들었을 때 |
-| [08 — `agy` 로 바깥 모델 부르기](rule/08-agy-외부-모델.md) | 토큰을 아끼고 싶을 때. **부르기 전에 "모델이 정말 필요한가" 부터** |
-| [09 — 거버넌스와 권한](rule/09-거버넌스와-권한.md) | 머지 권한·봇·장부 브랜치를 건드릴 때. **왜 사람이 아니라 봇이 누르는가** |
+```bash
+npm test
+npm run demo
+npm run demo:compare
+npm run demo:chaos
+npm run smoke
+```
 
-고칠 것이 있으면 **`rule/` 안의 그 파일**을 고친다. 여기에 본문을 되돌려 놓지 않는다 —
-두 벌이 되는 순간 어느 쪽이 진짜인지 아무도 모르게 된다.
+프로토콜 변경은 회귀 테스트와 경합 데모로 검증하고, 화면 변경은 브라우저 스모크를 돌린다. 데스크톱 변경은 설치된 Electron으로 `npm run desktop:smoke`를 추가한다. 성공 여부는 종료 코드로 판단한다. 필요한 실행 환경이 없으면 검증 제한을 보고한다.

package/README.ko.md

@@ -0,0 +1,124 @@
+# axMap
+
+[![English](https://raw.githubusercontent.com/rl2aderjoon/axmap/main/docs/assets/readme-en.svg)](https://github.com/rl2aderjoon/axmap/blob/main/README.md) [![한국어](https://raw.githubusercontent.com/rl2aderjoon/axmap/main/docs/assets/readme-ko.svg)](https://github.com/rl2aderjoon/axmap/blob/main/README.ko.md)
+
+**여러 AI 에이전트가 같은 git 저장소에서 작업할 때, 수정할 경로를 먼저 선점해 충돌을 예방하는 CLI 도구.**
+
+누가 어디를 고치는지 장부에 기록하고, 겹치는 경로의 선점을 거부한다.
+커밋 훅으로 선점 범위를 확인하고, 작업이 끝나면 반납한다.
+AI 도구에서는 MCP로 같은 기능을 사용할 수 있다.
+
+Node 20+와 git이 필요하다. CLI의 런타임 의존성은 없다.
+npm 패키지 이름은 `axmap-cli`, 실행 명령은 `axmap`이다.
+
+## 설치
+
+사용할 git 저장소에서 실행한다.
+
+```bash
+npm install -g axmap-cli@latest
+cd <프로젝트-저장소>
+axmap setup
+axmap doctor
+```
+
+`setup`은 저장소의 선점 장부와 커밋 훅을 준비하고, AI 도구의 사용자 설정에 MCP를 등록한다.
+MCP를 사용하려면 설정 후 AI 도구를 다시 시작한다.
+함께 작업하는 사람과 에이전트는 같은 원격 장부를 사용해야 서로의 선점을 볼 수 있다.
+
+자세한 설치·설정은 [docs/INSTALL.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INSTALL.md)를 참고한다.
+
+## 1.3.0: repo를 옮겨도 init 없이 사용
+
+axMap을 한 번 설정하면 다른 Git 저장소에서도 Codex 등 AI CLI를 열어 바로 사용할 수 있다. 세션의 작업 repo를 자동으로 선택하고, 첫 조회·선점 때 장부를 준비하므로 매번 `axmap init`을 실행하지 않아도 된다.
+
+기존 원격 장부가 있으면 이어 쓰고, 같은 repo의 worktree는 장부 하나를 공유한다. 서로 다른 repo의 동시 세션은 독립적으로 동작한다. 원격 접근 실패를 장부 없음으로 판단해 별도 장부를 만들지 않는다.
+
+MCP는 클라이언트가 알려주는 작업 폴더(roots)를 따라간다. 미지원 클라이언트는 시작 폴더를 사용하며, 도중에 폴더를 바꾸면 도구의 `cwd`에 작업 폴더 절대 경로를 전달한다. 커밋 훅을 적용할 새 repo에서는 `axmap hook install`을 실행한다.
+
+기존 설치를 업그레이드할 때는 작업 repo에서 아래 명령을 한 번 실행하고 AI CLI를 다시 시작한다.
+
+```bash
+npm install -g axmap-cli@latest
+axmap setup
+```
+
+`setup`은 MCP와 훅이 사용하는 설치 사본 및 등록을 갱신한다. 이후 repo를 옮길 때는 setup이나 init을 반복하지 않는다.
+
+## 작업 흐름
+
+```bash
+# 지금 누가 무엇을 잡고 있는지 확인
+axmap status
+
+# 수정 전에 경로와 목적을 선언
+axmap claim src/auth --agent my-agent --session my-session --task T-12 --intent "토큰 만료 처리"
+
+# 파일을 수정한 뒤 커밋할 변경을 준비하고 선점 범위를 확인
+git add src/auth
+axmap verify --agent my-agent --session my-session
+
+# 작업이 끝나면 반납
+axmap release --agent my-agent --session my-session
+```
+
+에이전트 이름과 세션은 각 작업 세션마다 고유하게 정하고, 선점부터 반납까지 같은 값을 쓴다.
+커밋 훅에서도 같은 식별자를 사용하도록 `AXMAP_AGENT`와 `AXMAP_SESSION` 환경변수를 설정한다.
+선점이 거절되면 메시지의 점유자·작업·남은 시간을 확인하고 겹치지 않는 영역을 선택한다.
+필요한 경로만 잡고, 작업이 길어지면 `axmap renew`에 같은 agent와 session을 지정해 갱신한다.
+
+`git worktree`로 나눈 작업 폴더도 같은 장부를 사용한다.
+`release`는 현재 세션이 잡은 경로를 반납한다.
+
+## 동작 방식
+
+git은 변경을 합칠 때 텍스트 충돌을 발견한다.
+axMap은 수정 전에 경로를 선점해, 여러 에이전트가 같은 영역을 동시에 고치는 상황을 먼저 막는다.
+
+선점 장부는 전용 git 브랜치에 저장한다. 원격의 최신 장부를 확인하고,
+git ref의 원자적 갱신과 경로 겹침 판정으로 선점한다.
+커밋 훅은 실제 수정 경로와 선점 범위를 대조한다.
+`axmap audit`은 장부 이력을 재생해 규칙 위반을 검사한다.
+
+상태를 읽지 못하면 그 이유를 알리고, 판정할 수 없는 상태를 성공으로 처리하지 않는다.
+프로토콜은 [docs/SPEC.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/SPEC.md), 지켜야 할 성질은 [docs/INVARIANTS.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INVARIANTS.md)에 있다.
+
+## AI 도구에서 사용
+
+MCP를 연결하면 `ax_claim`, `ax_status`, `ax_release` 등의 도구를 AI가 호출할 수 있다.
+에이전트에게 다음 작업 규칙을 전달한다.
+
+```text
+파일을 수정하기 전에 ax_claim으로 경로와 목적을 선언한다.
+선점이 거절되면 점유자를 확인하고 겹치지 않는 다른 작업을 선택한다.
+작업이 끝나면 ax_release로 반납한다.
+```
+
+연결 방법과 도구 목록은 [mcp/README.md](https://github.com/rl2aderjoon/axmap/blob/main/mcp/README.md)를 참고한다.
+
+## 개발과 검증
+
+```bash
+git clone https://github.com/rl2aderjoon/axmap.git
+cd axmap
+node bin/axmap.mjs --version
+npm test
+npm run demo
+npm run demo:compare
+npm run demo:chaos
+```
+
+루트 CLI를 실행하기 위한 `npm install`은 필요 없다. 데모는 bash 환경에서 실행한다.
+소스 확인에는 `node bin/axmap.mjs`를 사용한다.
+
+| 문서 | 내용 |
+|---|---|
+| [CLAUDE.md](https://github.com/rl2aderjoon/axmap/blob/main/CLAUDE.md) | 소스 작업 규칙 |
+| [docs/INSTALL.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INSTALL.md) | 설치와 사용 |
+| [docs/SPEC.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/SPEC.md) | 명령과 선점 프로토콜 |
+| [docs/INVARIANTS.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INVARIANTS.md) | 불변식과 검증 기준 |
+| [docs/DECISIONS.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/DECISIONS.md) | 제품 범위와 설계 결정 |
+
+## 라이선스
+
+[MIT](https://github.com/rl2aderjoon/axmap/blob/main/LICENSE)

package/README.md

@@ -1,219 +1,126 @@
 # axMap
 
-**여러 AI 에이전트가 한 저장소에서 동시에 일할 때,
-사람이 그 작업을 이해하고 통제할 수 있게 하는 도구.**
+[![English](https://raw.githubusercontent.com/rl2aderjoon/axmap/main/docs/assets/readme-en.svg)](https://github.com/rl2aderjoon/axmap/blob/main/README.md) [![한국어](https://raw.githubusercontent.com/rl2aderjoon/axmap/main/docs/assets/readme-ko.svg)](https://github.com/rl2aderjoon/axmap/blob/main/README.ko.md)
 
-이름 그대로 **AI Experience(ax) 의 지도**다 — 에이전트가 코드베이스에서 길을 찾고
-서로를 피해 가는 경험을 만들고, 동시에 개발 환경의 **AI Transformation**,
-즉 사람 혼자 쓰던 저장소를 여러 에이전트가 함께 쓰는 곳으로 바꾸는 일을 함의한다.
+**A CLI tool that helps AI agents avoid conflicting edits by claiming paths before working in the same Git repository.**
 
-의존성 0. Node 20+ 와 git 만 있으면 돈다.
+axMap records who is editing which paths and rejects overlapping claims.
+Commit hooks check changes against claimed paths, and agents release their claims when work is done.
+AI tools can use the same workflow through MCP.
 
-> 산문에서는 `axMap`, 명령·경로·패키지 이름에서는 `axmap` 을 쓴다.
+Requires Node.js 20+ and Git. The CLI has no npm runtime dependencies.
+The npm package is `axmap-cli`; the command is `axmap`.
 
----
+## Installation
 
-## 무엇을 푸는가
-
-AI 에게 코드를 시키면 두 가지가 동시에 어려워진다.
-
-| | 공포 | 언제 |
-|---|---|---|
-| **F1** | 내가 이해 못 하는 코드가 계속 쌓인다 | 작업 **전** |
-| **F2** | AI 가 뭘 망가뜨렸는지 모른다 | 작업 **후** |
-| **F3** | 내가 잘 하고 있는지 모른다 | 계속 |
-
-axMap 은 셋에 각각 답한다 — 처음 보는 코드베이스를 따라갈 **순서**,
-변경이 어디까지 번졌는지 보는 **PR 화면**, 그리고 수천 개 저장소에서 학습한 **기준**.
-
-그리고 그 밑에, 여러 에이전트가 같은 코드를 동시에 고치지 않게 하는
-**git 위의 선점 프로토콜**이 있다.
-
----
-
-## 5분 안에 써보기
+Run these commands in the Git repository you want to work on.
 
 ```bash
-git clone <이 저장소> && cd axmap
-
-# 아무 저장소나 열어본다 — git 주소를 그대로 줘도 된다
-node app/server.mjs https://github.com/pallets/flask 7777
+npm install -g axmap-cli@latest
+cd <your-project-repository>
+axmap setup
+axmap doctor
 ```
 
-`http://127.0.0.1:7777` 을 열면 다섯 걸음이 나온다.
+`setup` prepares the repository's claim ledger and commit hooks, and registers MCP in your AI tool's user settings.
+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).
 
-**남의 저장소에서 쓰려면** → [docs/INSTALL.md](docs/INSTALL.md) (npm 두 줄이면 끝난다)
+## Automatic repository setup in 1.3.0
 
-**axMap 자체를 고치려면** → [docs/ONBOARD-TEAM.md](docs/ONBOARD-TEAM.md) (3줄이면 붙는다)
+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.
 
----
+Existing remote ledgers are reused. Linked worktrees share one ledger, and simultaneous sessions in different repositories keep independent targets. Remote access failures stop the request instead of creating a separate ledger.
 
-## 두 개의 층
+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.
 
-### 1. 지도 — 코드가 실제로 어떻게 엮여 있나
-
-정적 `import` 그래프와 **git 공변경**(함께 바뀐 이력)을 겹쳐 본다.
-겹치지 않는 부분이 사고가 나는 자리다.
-
-```
-둘 다          import 있고 함께 바뀜        예상대로
-숨은 결합      import 없는데 함께 바뀜      🔴 코드를 읽어서는 못 찾는다
-안정된 경계    import 하지만 따로 바뀜
-판정 보류      히스토리가 부족하다
-```
-
-**엣지마다 출처가 붙는다.** 어떻게 알아냈는지 모르는 선은 긋지 않는다.
-
-### 2. 장부 — 지금 누가 어디를 잡고 있나
+To upgrade an existing installation, run this once from a working repository, then restart your AI CLI:
 
 ```bash
-export AXMAP_AGENT=<자기이름>
-node bin/axmap.mjs hook install
-
-node bin/axmap.mjs claim src/auth --task T-12 --intent "토큰 만료 처리"
-node bin/axmap.mjs status      # 누가 무엇을
-node bin/axmap.mjs release     # 끝나면 즉시
+npm install -g axmap-cli@latest
+axmap setup
 ```
 
-이름은 **세션마다 다르게** 준다. 같은 PC 에서 AI 도구 세션을 둘 띄우고 둘 다
-이름을 안 주면 `git config user.name` 으로 떨어져 장부에서 한 사람이 된다.
-그러면 서로를 하나도 못 막는다. 이름이 같아도 **세션마다 레코드가 따로 적히므로**
-서로 덮지는 않고, `release` 는 그 세션이 잡은 것만 푼다 (다른 창이 두고 간 것까지
-풀려면 `release --all-sessions`) — 자세한 것은 [docs/SPEC.md](docs/SPEC.md) 3절.
-
-`git worktree add` 로 만든 폴더 안에서도 그대로 쓴다. 장부는 메인 체크아웃에
-하나뿐이고, 링크된 worktree 는 그것을 본다. 거기에 장부를 또 만들지 않는다.
+`setup` refreshes the installed MCP and hook copy as well as its registration. Subsequent repository changes do not require another setup or init.
 
-git 은 **같은 줄**을 고쳐야 충돌을 안다. 그런데 더 위험한 것은
-같은 기능을 앞에서부터·뒤에서부터 만드는 두 사람이다 — 경로가 안 겹쳐도 어긋난다.
-장부는 그것을 코드를 쓰기 **전에** 터뜨린다.
+## Workflow
 
-두 개의 관문으로 지킨다 — git ref 의 원자적 갱신(CAS)과 순수 함수 판정.
-불변식은 [docs/INVARIANTS.md](docs/INVARIANTS.md) 에 있고,
-모델 검증기·카오스 테스트·`axmap audit` 이 **같은 검사기**를 공유한다.
-
----
-
-## 🔴 이 저장소가 지키는 규칙
-
-이게 이 프로젝트의 성격을 가장 잘 말한다.
-
-### 없는 것과 못 읽은 것을 같은 값으로 말하지 않는다
-
-```
-claims: []      ← "아무도 안 잡고 있다" 로 읽힌다
-claims: null    ← "모른다" 다
-```
-
-맥락 없는 신입 에이전트에게 도구만 주고 저장소를 이해시키는 실험을 반복하는데,
-**발견된 버그가 거의 전부 이 한 가지 모양이었다.** 코드는 대개 맞았고
-*말하지 않은 것*이 문제였다. 한 신입은 `[]` 를 읽고 "부딪힐 사람 없음" 이라고
-확신 있게 틀렸다.
-
-### 애매하면 거부한다 (fail-closed)
+```bash
+# Check who has claimed which paths
+axmap status
 
-같은 꼬리를 가진 파일이 둘이면 잇지 않는다. 표본이 모자라면 기준을 내지 않는다.
-**틀리게 잇는 것보다 안 잇는 것이 낫다.**
+# Declare your paths and purpose before editing
+axmap claim src/auth --agent my-agent --session my-session --task T-12 --intent "Handle token expiration"
 
-### 지침에는 적용 조건이 붙는다
+# After editing, stage your changes and check their claimed scope
+git add src/auth
+axmap verify --agent my-agent --session my-session
 
-```
-❌  함수는 20줄을 넘기지 마세요
-✅  커밋 1,500~6,000 · Python 저장소 34개에서 관찰 (스냅샷 v418)
+# Release your claims when work is done
+axmap release --agent my-agent --session my-session
 ```
 
-적용 조건 없는 지침은 점성술이다.
+Use a unique agent name and session for each work session, and keep them consistent from claim to release.
+Set the `AXMAP_AGENT` and `AXMAP_SESSION` environment variables so commit hooks use the same identity.
+If a claim is rejected, check its owner, purpose, and remaining time, then choose a different area.
+Claim only the paths you need. For longer tasks, run `axmap renew` with the same agent and session.
 
-### 주석은 "왜" 를 쓴다
+Work folders created with `git worktree` share the same ledger.
+`release` releases paths claimed by the current session.
 
-무엇은 코드가 이미 말한다. 이 저장소의 주석 대부분은 **그렇게 하지 않았을 때
-실제로 무엇이 깨졌는지**를 적고 있다.
+## How it works
 
----
+Git detects text conflicts when changes are merged.
+axMap claims paths before edits to prevent agents from working on the same area at the same time.
 
-## 기준 (SSOT) — 우리 숫자에 근거를 붙인다
+The claim ledger lives on a dedicated Git branch. axMap checks the latest remote ledger,
+then uses atomic Git ref updates and path overlap checks to acquire claims.
+Commit hooks compare staged changes with claimed paths.
+`axmap audit` replays the ledger history to check for rule violations.
 
-도구의 임계값이 전부 사람이 눈으로 고른 상수였다. 그래서 공개 저장소를
-돌면서 그 상수를 **분포**로 바꾼다.
+axMap reports unreadable state and refuses operations it cannot safely evaluate.
+The protocol is documented in [docs/SPEC.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/SPEC.md), and its invariants in [docs/INVARIANTS.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INVARIANTS.md) (Korean).
 
-🔴 **"인기 있는 걸 따라해라" 가 아니다.** 별 개수는 품질의 증거가 아니고,
-저장소 7,107개로 실제로 확인했다 —
-
-| 별 | 재수정률 |
-|---|---|
-| 0~2,000 | 0.081 |
-| 2,000~6,000 | 0.150 |
-| 6,000~20,000 | 0.103 |
-| 20,000~ | 0.149 |
+## Using AI tools
 
-단조 관계가 없다. 그래서 인기 대신 **결과**를 센다 — *그 파일이 나중에
-얼마나 고쳐졌나*. 그리고 관계가 없으면 **지침을 내지 않는다.**
+With MCP connected, AI agents can call tools such as `ax_claim`, `ax_status`, and `ax_release`.
+Give your agents these working rules.
 
-자세히 → [docs/WHY-CORPUS.md](docs/WHY-CORPUS.md)
+```text
+Before editing files, declare the paths and purpose with ax_claim.
+If a claim is rejected, check its owner and choose another task with no overlapping paths.
+Release your claims with ax_release when work is done.
+```
 
----
+See [mcp/README.md](https://github.com/rl2aderjoon/axmap/blob/main/mcp/README.md) for connection instructions and the tool list (Korean).
 
-## 검증
+## Development and verification
 
 ```bash
-npm test              # 순수 로직 + 모델 검증기
-npm run demo          # 에이전트 9명 동시 작업
-npm run demo:compare  # git 텍스트 충돌 vs 파서 판정
-npm run demo:chaos    # 진짜 경합 (무작위 순서)
-npm run smoke         # 🔴 화면이 실제로 뜨는지 헤드리스 크롬으로
+git clone https://github.com/rl2aderjoon/axmap.git
+cd axmap
+node bin/axmap.mjs --version
+npm test
+npm run demo
+npm run demo:compare
+npm run demo:chaos
 ```
 
-`smoke` 가 따로 있는 이유 — 문법이 멀쩡하고 테스트가 전부 초록인데
-브라우저에서는 아무것도 안 뜬 적이 두 번 있었다.
-**되는 길만 보면 안 되는 길은 영원히 안 보인다.**
-
----
+The root CLI runs without `npm install`. The demos require Bash.
+Use `node bin/axmap.mjs` to run the source version.
 
-## 문서
+The following supporting documents are currently in Korean.
 
-| | |
+| Document | Contents |
 |---|---|
-| [CLAUDE.md](CLAUDE.md) | 작업 규칙 (사람에게도 AI 에게도 같다) |
-| [docs/INSTALL.md](docs/INSTALL.md) | **팀원이 읽을 것 하나** — npm 으로 깔고 쓰는 법 |
-| [docs/ONBOARD-TEAM.md](docs/ONBOARD-TEAM.md) | axMap 자체를 고칠 사람용 5분 안내 |
-| [docs/DECISIONS.md](docs/DECISIONS.md) | 제품 결정 D1~D15 와 **아직 못 정한 것들** |
-| [docs/WHY-CORPUS.md](docs/WHY-CORPUS.md) | 코퍼스가 왜 필요한가 |
-| [docs/PERSONA-LOOP.md](docs/PERSONA-LOOP.md) | 시각화가 실제로 일하는지 재는 법과 결과 |
-| [docs/SPEC.md](docs/SPEC.md) | 프로토콜 규격 |
-| [docs/INVARIANTS.md](docs/INVARIANTS.md) | 지키기로 한 성질 |
-
----
-
-## 아직 안 된 것 (숨기지 않는다)
-
-- **시각화 형식이 미정이다.** 두 번의 벤치마크가 "지금 그래프는 값을 못 한다" 로
-  나왔다 — 신입들이 그림이 아니라 옆에 적힌 글을 읽고 답했다. 2차원 트리·활동 지도
-  같은 후보를 같은 방식으로 재서 정할 것이다.
-- **파서가 14개 언어를 읽는다** — 5개에서 늘렸다. 어느 언어를 먼저 할지는
-  코퍼스가 정했다(커버리지 4~12% 인 것부터). 마지막이 swift 였고, 그것이
-  새 구멍을 하나 드러냈다 — **모듈이 상한보다 크면 선을 안 그린다.**
-  안 그리는 것은 맞지만 안 그렸다고 **말하지 않으면** 화면이 "결합 없음" 으로
-  읽힌다. 지금은 말한다. 같은 구멍이 다른 언어에도 있는지는 아직 안 봤다.
-- **기준을 떼어놓고 검증(held-out)** 한 적이 없다. 그게 있어야 "관찰" 이
-  "검증된 지침" 이 된다.
-- **상관이지 인과가 아니다.** *"긴 파일이 버그를 만든다"* 가 아니라
-  *"긴 파일이 더 자주 고쳐졌다"* 다.
-
----
-
-## 라이선스
-
-MIT. 마음대로 쓰고 고치고 팔아도 된다 — 저작권 표시만 남기면 된다.
-[LICENSE](LICENSE)
-
----
-
-<sub>SSAFY 프로젝트로 시작했다. 한국어로 쓰고 한국어로 생각한다.</sub>
+| [CLAUDE.md](https://github.com/rl2aderjoon/axmap/blob/main/CLAUDE.md) | Rules for working on the source |
+| [docs/INSTALL.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INSTALL.md) | Installation and usage |
+| [docs/SPEC.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/SPEC.md) | Commands and the claim protocol |
+| [docs/INVARIANTS.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/INVARIANTS.md) | Invariants and verification criteria |
+| [docs/DECISIONS.md](https://github.com/rl2aderjoon/axmap/blob/main/docs/DECISIONS.md) | Product scope and design decisions |
+
+## License
+
+[MIT](https://github.com/rl2aderjoon/axmap/blob/main/LICENSE)

package/app/lib/ssot.mjs

@@ -178,7 +178,7 @@ const LANG_BY_EXT = {
 // 받아오기 — 여기서부터는 부수효과다
 // ---------------------------------------------------------------------------
 
-export const SSOT_URL = process.env.AXMAP_SSOT_URL ?? 'https://i15e101.p.ssafy.io/ssot/baseline'
+export const SSOT_URL = process.env.AXMAP_SSOT_URL ?? 'http://127.0.0.1:7902/baseline'
 
 /** 저장소를 더럽히지 않게 OS 임시 디렉터리에 둔다. 지워져도 다시 받으면 그만이다. */
 export const CACHE_PATH = path.join(os.tmpdir(), 'axmap-ssot-baseline.json')