diff --git a/README.md b/README.md
new file mode 100644
index 0000000..62a79b1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,52 @@
+# Nekoban Map Generator
+
+역탐색 기반으로 소코반 맵을 생성하는 .NET 7 콘솔 툴입니다. 마스크(외곽 형태)를 지정하고, 목표에 박스를 놓은 상태에서 박스를 “pull”하여 시작 상태를 만들기 때문에 항상 풀 수 있는 맵만 출력합니다. 외벽은 `#`, 바깥은 `0`, 바닥은 `.`, 목표/박스/플레이어는 `G/$/@`로 표시합니다.
+
+## 요구사항
+- .NET 7 SDK
+
+## 사용 방법
+```bash
+dotnet build
+dotnet run -- <seed> [startId] [endId] > output.json
+```
+- 예: `dotnet run -- 12345 3 20 > stage.json`
+- `seed`가 없으면 기본값(12345)을 사용합니다.
+- `startId/endId`가 없으면 `levelbalance.json`에 정의된 밴드 범위를 사용합니다.
+- 진행 상태는 stderr에 한 줄로 갱신됩니다(벽 생성중/박스 배치중/검증중/생성완료).
+
+## 설정
+- `levelbalance.json`: 레벨 밴드 설정(레벨 범위, 박스 수, 최소 푸시/턴/브랜칭, 사용할 마스크 개수). 이 파일을 수정해 난이도/범위를 조정합니다.
+- `mask_library.cs`: Microban/Novoban 스타일의 외곽 마스크 모음. 회전/반전/스케일 변형과 소규모 벽 지터가 자동 적용됩니다. 마스크를 추가해 형태 다양성을 늘릴 수 있습니다.
+- `Program.cs`: 생성 튜닝(`GenerationTuning`)에 시도 횟수, 시간 한도, 역탐색 깊이/폭, 외벽 정규화 등이 정의되어 있습니다.
+
+## 출력 형식
+`output.json`은 다음 형태의 배열입니다.
+```json
+[
+  {
+    "id": 3,
+    "grid": [
+      "000000000",
+      "00#####00",
+      "00#...#00",
+      "0##.$.##0",
+      "0#@$.G.#0",
+      "0##...##0",
+      "00#.G.#00",
+      "00#####00",
+      "000000000"
+    ],
+    "lowestPush": 5,
+    "pushLimit": 7
+  }
+]
+```
+- `grid`: 문자열 배열(행). `0`은 외부 void, `#`는 벽, `.`은 바닥, `G/$/@`는 목표/박스/플레이어.
+- `lowestPush`: 솔버가 계산한 최소 푸시 수.
+- `pushLimit`: 최소 푸시에 여유 패딩을 더한 제한 값.
+
+## 메모
+- 외벽은 항상 `#`로 둘러지며, `0`은 외부에서만 사용됩니다.
+- 중복 레이아웃은 제거됩니다.
+- 더 느리게 돌려야 하면 `GenerationTuning`의 시도/시간 한도를 조정하세요.