docs(readme): P1~P12 구현 현황·향후 개선 계획 갱신

- 구현 기능 표 전면 갱신 (클래스/전직·버프/디버프·절차 맵·유물/물약·승천·모션)
- 디렉토리 구조 갱신 (potions.json·rogue-map·gitea-pr·RULES.md, map.json 제거 반영)
- 스크립트 호출 예시·향후 개선 계획 10항목·RULES.md 셋업 안내

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

README.md

@@ -43,10 +43,10 @@ git pull
 ```
 slaymaple/
 ├── data/                       # 게임 데이터 단일 소스 (생성기가 읽어 주입)
-│   ├── cards.json              # 카드 정의 + 시작 덱
-│   ├── enemies.json            # 적 정의(슬라임/정예/보스) + activeEnemy
-│   ├── map.json                # 분기 맵 DAG (노드 type/enemy/row/col/next)
-│   └── relics.json             # 유물 정의 + 시작 유물 + 풀
+│   ├── cards.json              # 카드 32종(클래스·직업별) + 클래스별 시작 덱
+│   ├── enemies.json            # 적 정의(일반/정예/보스, 디버프 인텐트 포함)
+│   ├── potions.json            # 물약 6종 + 드랍률·슬롯·상점가
+│   └── relics.json             # 유물 19종(StS 효과 × 메이플 장비) + 시작 유물 + 풀
 ├── Global/                     # 월드 전역 설정 · 공용 모델 · 게임로직
 │   ├── common.gamelogic        # SlayDeckController 부착 지점 (카드 UI 전투)
 │   ├── DefaultPlayer.model     # 플레이어 모델 (턴전투용 이동 정지 freeze 적용)
@@ -64,15 +64,18 @@ slaymaple/
 │   └── map01.map ~ map11.map    # 맵 11종 (공식 배경 + STS풍 우측 배치)
 ├── tools/                       # 결정적 생성기·도구 (주체별 폴더, 단일 소스)
 │   ├── deck/                    # gen-slaydeck.mjs(★게임 전체 생성: 카드/덱·맵·상점·유물·메인메뉴 UI+SlayDeckController+common) · gen-cardhand.mjs(손패 초기 생성)
-│   ├── map/                     # gen-maps.mjs(맵 생성)
+│   ├── map/                     # gen-maps.mjs(맵 생성) · gen-map-encounters.mjs(맵별 인카운터) · rogue-map.mjs(절차 생성 JS 미러+테스트)
 │   ├── camera/                  # gen-camera.mjs(맵별 고정 카메라 codeblock)
 │   ├── player/                  # freeze-turn-player.mjs(이동 정지) · gen-player-lock.mjs(입력 차단·시선 고정 codeblock)
 │   ├── monster/                 # freeze-turn-monsters.mjs(필드 몬스터 AI/이동 정지)
-│   └── balance/                 # sim-balance.mjs(밸런스 시뮬·몬테카를로) · sim-balance.test.mjs
+│   ├── balance/                 # sim-balance.mjs(밸런스 시뮬·몬테카를로) · sim-balance.test.mjs
+│   └── git/                     # gitea-pr.mjs(UTF-8 안전 PR 생성/수정/머지 — RULES.md 참조)
 ├── ui/                         # UI 그룹 (Default / Popup / Toast)
 ├── docs/
 │   ├── slaymaple_basic_framework.md   # 전투 프레임워크 설계 문서
 │   └── superpowers/specs|plans/       # 각 기능 설계·구현 계획 문서
+├── RULES.md                    # 협업·AI 에이전트 하네스 규칙 (토큰 가드·PR 절차)
+├── CLAUDE.md                   # Claude Code 자동 로드 (RULES.md 임포트)
 └── README.md
 ```
 
@@ -82,35 +85,40 @@ slaymaple/
 
 ## 게임 프레임워크 현황
 
-**STS풍 덱빌더 런이 end-to-end로 완성**됐습니다 — 메인 메뉴 → 분기 맵 → 전투/엘리트/상점/휴식 → 카드 보상·덱 성장 → 유물 → 보스 → 다음 막 → 런 클리어. 게임 전체는 `/common` 엔티티에 부착된 **`SlayDeckController` 단일 컴포넌트**로 동작하며, 모든 산출물(`ui/DefaultGroup.ui` · `SlayDeckController.codeblock` · `common.gamelogic`)은 **`tools/deck/gen-slaydeck.mjs` 단일 소스에서 생성**됩니다(직접 편집 금지, 결정적 출력). 게임 데이터는 **`data/*.json`** 가 단일 소스.
+**StS2풍 덱빌더 로그라이크가 end-to-end로 완성**됐습니다 — 메인 메뉴(승천 선택) → 캐릭터 선택(전사/마법사) → 절차 생성 맵 → 전투/엘리트/상점/휴식/유물 방 → 보상·전직·덱 성장 → 보스 → 다음 막 → 런 클리어(승천 해금). 게임 전체는 `/common` 엔티티에 부착된 **`SlayDeckController` 단일 컴포넌트**로 동작하며, 모든 산출물(`ui/DefaultGroup.ui` · `SlayDeckController.codeblock` · `common.gamelogic`)은 **`tools/deck/gen-slaydeck.mjs` 단일 소스에서 생성**됩니다(직접 편집 금지, 결정적 출력 — `RULES.md` 참조). 게임 데이터는 **`data/*.json`** 가 단일 소스.
 
-### 구현된 기능
+### 구현된 기능 (배포 퀄리티 P1~P12, PR #34~#47)
 
 | 영역 | 내용 |
 |---|---|
-| **메인 메뉴** | "슬레이 메이플" 타이틀 + "새 게임" → 런 시작 (`OnBeginPlay`→`ShowMainMenu`) |
-| **카드 전투** | 에너지 3·매 턴 5장 드로우·버림/재셔플·카드 클릭 사용. 카드 3종(타격/방어/강타, `damage`/`block` 수치). 적 HP/방어/의도(결정적 사이클·다음 행동 미리 표시). 데미지는 방어 우선 차감. 승/패·입력 잠금 |
-| **런 영속** | HP·골드·`RunDeck`(보유 카드)가 전투 간 유지. 시작 덱 10장 |
-| **전투 보상** | 승리 시 카드 3중 1택(덱 추가)·골드, 또는 건너뛰기 |
-| **분기 맵** | 작성된 DAG(`data/map.json`)에서 다음 노드 선택. 노드 타입 전투/엘리트/보스(적 데이터 차등), 상점/휴식. 도달 가능 노드만 선택 |
-| **상점/휴식** | 상점=골드로 카드·유물 구매. 휴식=HP 회복 |
-| **유물** | 훅 패시브(`combatStart`/`turnStart`/`cardPlayed`/`combatReward`). 획득 3경로(시작·엘리트 승리·상점). 유물 4종 |
-| **멀티 act** | 보스 클리어→다음 막(적 스케일 `1+(막-1)*0.6`), 최종 막 보스에서 런 클리어. 막 수 3 |
-| **밸런스 시뮬** | `tools/balance/sim-balance.mjs` — 몬테카를로 N회 전투로 승률·턴·OP 카드 리포트 |
-| **턴전투 freeze** | 카드 전투 중 필드 몬스터/플레이어 이동·AI 정지(`freeze-turn-*.mjs`) |
+| **캐릭터·전직** | 시작 시 **전사(HP80)/마법사(HP70)** 선택, 클래스별 시작 덱. 보스 클리어 시 [유물] vs [**2차 전직**] — 전사→파이터/페이지/스피어맨, 법사→위자드(불·독)/위자드(썬·콜)/클레릭. 전용 카드는 해당 클래스만 획득(보상·상점 풀 필터) |
+| **카드 전투** | 에너지 3·5장 드로우·**드래그 사용**(공격=적에 드롭, 스킬=위로 스윕). 카드 32종 — kind **Attack/Skill/Power**(파워: 소멸·매턴 지속 효과). 메커니즘: 다단히트·방어 무시·자가 디버프·드로·회복·**전체 공격(AoE)**·**독(DoT)** |
+| **버프/디버프** | StS 표준 — **힘**(+N 영구)·**약화**(주는 피해 −25%)·**취약**(받는 피해 +50%)·**독**(매 행동 틱). 양방향(적 디버프 인텐트 포함), 인텐트는 최종 예상치 표시 |
+| **전투 연출** | 공격 이펙트·데미지 팝업·적 개별 차례·**공격/피격/독뎀 모션**(아바타 상태 전이·몬스터 hit 클립·런지/넉백) |
+| **절차 생성 맵** | 막 시작마다 **8층×4열 StS식 경로 생성**(런마다 다름). 층 규칙: 1~2층 전투만 → 3층~ 상점/휴식 → 4층~ 엘리트/**유물 방** → 7층 휴식 가중 → 8층 보스. 점선 경로·상태 4단(현재/방문/도달/잠김)·층 카운터 |
+| **유물 방(보물)** | 상자 클릭 → 흔들림 → 열림 연출 → 유물 + 메소 획득 |
+| **유물 19종** | StS 효과 × 메이플 장비 외형. TopBar **아이콘 행 + 마우스오버 툴팁**. 훅: combatStart/turnStart/cardPlayed/combatEnd/combatReward/onPlayerDamaged/attackCalc/passive. **장인의 벨트**=물약 슬롯 3→5칸 |
+| **물약 6종** | 승리 40% 드랍·상점 판매·슬롯 클릭 → 사용(전투 중)/버리기 메뉴·툴팁 |
+| **상점/휴식** | 카드 3종·유물·물약 판매(메소), 휴식=HP 회복 |
+| **승천(Ascension)** | A1~A10 누적 모디파이어(적 강화·시작 HP 감소·보상 감소). **UserDataStorage로 유저별 영구 저장**(서버 RPC), 런 클리어 시 다음 단계 해금 |
+| **멀티 act** | 보스 클리어→다음 막 텔레포트(맵·인카운터 변경, 적 스케일 `1+(막-1)*0.6`), 3막 클리어 시 런 종료→메뉴 복귀 |
+| **밸런스 시뮬** | `tools/balance/sim-balance.mjs` — 전투 규칙 JS 미러(몬테카를로) + `tools/map/rogue-map.mjs`(맵 생성 미러). **테스트 40건** |
 
-> ⚠️ 플레이어 HP(80)·적 수치·골드/카드값(15/30/유물60)·막 배율 등은 **밸런싱 미조정 placeholder**입니다. 추후 카드·적은 **메이플스토리 IP**에 맞춰 디벨롭 예정이며, 밸런싱은 `sim-balance.mjs`로 검증합니다.
+> ⚠️ 수치(적 스탯·경제·승천 배율)는 1차 조정 상태입니다. 정밀 밸런싱은 `sim-balance.mjs`로 검증하며 진행합니다.
 
 ### 유용한 스크립트 호출
 `/common` 엔티티(또는 Play Test 컨텍스트)에서:
 ```lua
 local c = _EntityService:GetEntityByPath("/common").SlayDeckController
-c:StartNewGame()     -- 메뉴 → 런 시작
-c:PickNode("A")      -- 맵 노드 선택 → 전투/상점/휴식
+c:SelectClass("warrior")  -- 또는 "magician"
+c:StartNewGame()          -- 캐릭터 선택 → 런 시작
+c:PickNode("r1c2")        -- 맵 노드 선택 (절차 생성 그리드 id) / "boss"
 c:PlayCard(1)             -- 손패 slot 카드 사용
 c:EndPlayerTurn()         -- 턴 종료 → 적 턴 → 다음 턴
 c:PickReward(1)           -- 보상 카드 1택(0=건너뛰기)
-c:BuyCard(1) / c:BuyRelic()  -- 상점 구매
+c:BuyCard(1) / c:BuyRelic() / c:BuyPotion()  -- 상점 구매
+c:SetJob("fighter")       -- 전직 (보스 보상 선택 화면에서)
+c:AdjustAscension(1)      -- 메뉴에서 승천 단계 +1
 ```
 
 밸런스 검증: `node tools/balance/sim-balance.mjs [N] [--seed S]` · 테스트: `node --test tools/balance/sim-balance.test.mjs`.
@@ -124,13 +132,17 @@ c:BuyCard(1) / c:BuyRelic()  -- 상점 구매
 
 ---
 
-## 다음 구현 단계 (후속 후보)
-- [x] 단일 전투 루프 · 데이터 외부화 · 밸런스 시뮬 · 런 루프 · 분기 맵 · 상점/휴식 · 유물 · 멀티 act **(완료)**
-- [ ] 저장/불러오기(런 영속 직렬화) — MSW 저장 API 필요
-- [ ] 카드 제거(상점) — 덱 전체 보기 UI 필요
-- [ ] 경제 밸런싱 튜닝(골드/승리 15 < 카드값 30 < 유물 60) — `sim-balance.mjs` 활용
-- [ ] 메이플스토리 IP 기반 카드·적·배경 콘텐츠 확장
-- [ ] 막별 다른 맵 디자인·이벤트 노드
+## 향후 개선 계획 (후속 후보)
+- [x] 전투 루프 · 런 루프 · 절차 생성 맵 · 상점/휴식/유물 방 · 유물 19종 · 물약 · 버프/디버프 · Power · 전직(전사/법사 2차) · 승천+개인 저장 · 전투 모션 **(P1~P12 완료)**
+- [ ] **런 이어하기** — 진행 중 런 직렬화 저장(승천에서 도입한 UserDataStorage 확장, 메뉴의 "이어하기" 활성화)
+- [ ] **카드 제거/업그레이드** — 상점 카드 제거 슬롯, 휴식 노드에서 카드 강화(StS 스타일 +수치)
+- [ ] **이벤트 노드(?)** — 랜덤 텍스트 이벤트(선택지·리스크/리워드)
+- [ ] **3차 전직** — 2막 보스 보상으로 확장(크루세이더/나이트/버서커, 메이지 3차 등)
+- [ ] **도적·궁수 클래스** — 캐릭터 선택 슬롯 확장(도적 잠금 해제), 클래스별 카드 풀
+- [ ] **정밀 밸런싱** — 첫 인카운터 승률 100% 완화, 직업별 카드 효율 튜닝(`sim-balance.mjs` 리포트 기반)
+- [ ] **상점 보장 규칙** — 막당 상점 최소 1회 등장(현재 가중 랜덤이라 미등장 가능)
+- [ ] **연출 보강** — 사운드(타격·획득), EndTurn 버튼 적 턴 중 시각 비활성화, 맵 화면에 유물/물약 표시
+- [ ] **승천 확장** — A10 초과 단계, 승천별 기록(클리어 횟수) 표시
 
 ---
 
@@ -142,3 +154,4 @@ c:BuyCard(1) / c:BuyRelic()  -- 상점 구매
 2. MSW Maker에서 이 폴더를 **로컬 워크스페이스 경로**로 지정해 월드 열기
 3. `.mcp.json` / `.codex/` 는 git에 없으므로, 본인 토큰으로 직접 생성 (MCP·Codex 사용 시)
 4. 작업 전 항상 `git pull`, 작업 후 `git add/commit/push`
+5. **AI 에이전트(Claude Code 등)로 작업한다면 [`RULES.md`](RULES.md) 필독** — 생성 산출물 접근 금지(토큰 가드)·검증 절차·PR 도구(`tools/git/gitea-pr.mjs`) 규칙. Claude Code는 `CLAUDE.md`가 자동 적용