diff --git a/README.md b/README.md
index fa082ee4..e7121bbf 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,161 @@
-This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app).
+# Q.CAST Front
 
-### Getting Started
+Q.CELLS 일본 시장 대상 태양광 패널 레이아웃 설계 · 견적 · 관리 프론트엔드. Next.js 14 App Router 기반.
 
-First, run the development server:
+자세한 작업 규약 · 비명시적 패턴 · gotcha 는 [`CLAUDE.md`](./CLAUDE.md) 와 [`docs/`](./docs) PDF 들을 참조한다.
+
+## Stack
+
+- **Framework**: Next.js 14.2.28 (App Router, `reactStrictMode: false`)
+- **Language**: JavaScript + TypeScript (`allowJs: true`, `strict: false`)
+- **Canvas**: Fabric.js 5.5.2 (커스텀 확장 — `src/components/fabric/`, `src/util/fabric-extensions.js`)
+- **State**: Recoil 0.7.7 (도메인별 atom — `src/store/`)
+- **Session/Auth**: iron-session 8 (쿠키 기반)
+- **Data fetching**: axios 1.7 + SWR 2.3
+- **i18n**: next-international (ja / ko — `src/locales/`)
+- **UI**: react-responsive-modal, react-select, react-datepicker, ag-grid-react, sweetalert2, react-icons, framer-motion, tailwindcss + sass
+- **PDF/이미지**: jimp, sharp, convertapi
+- **DB 클라이언트**: mssql (서버 사이드), sqlite/sqlite3 (로컬 캐시)
+- **AWS**: `@aws-sdk/client-s3`
+- **Geo**: `@turf/turf`, mathjs, big.js
+- **Path alias**: `@/* → ./src/*`
+
+## Getting Started
 
 ```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+yarn install
+yarn dev           # .env.localhost 사용, http://localhost:3000
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+`.env.localhost` 가 워크트리에 있어야 한다(실제 시크릿 포함). 새 머신에서는 팀에서 받아 배치할 것.
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+HTTPS 가 필요하면 `./certificates/key.pem`, `cert.pem` 을 준비한 뒤 `yarn serve` (HTTP 3000 + HTTPS 3001).
 
-This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font.
+## Scripts
 
-## Learn More
+모든 스크립트는 `env-cmd` 로 `.env.<mode>` 를 주입한다. **테스트 러너는 별도로 wiring 되어 있지 않다.**
 
-To learn more about Next.js, take a look at the following resources:
+| Script | 설명 |
+| --- | --- |
+| `yarn dev` | 로컬 개발 (`.env.localhost`) |
+| `yarn dev:log` | dev + stdout 을 `dev.log` 로 미러링 |
+| `yarn dev:local-api` | API 를 `http://localhost:8080` 으로 고정 |
+| `yarn local:dev` | `.env.local.dev` 모드 (로컬에서 dev 서버 환경 흉내) |
+| `yarn build` | 프로덕션 빌드 (`.env.production`) |
+| `yarn build:dev` | dev 빌드 (`.env.development`) |
+| `yarn build:local.dev` | local.dev 빌드 |
+| `yarn start:cluster1` | `next start -p 5000` (PM2 prd1) |
+| `yarn start:cluster2` | `next start -p 5001` (PM2 prd2) |
+| `yarn start:dev` | `next start -p 5010` (PM2 dev) |
+| `yarn serve` | `server.js` — HTTP 3000 + HTTPS 3001 (certificates 필요) |
+| `yarn lint` | `next lint` — 완료 전 필수 |
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+## Environment Variables
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome!
+각 모드별 `.env.<mode>` 파일에 정의. 키 목록(전체 값은 절대 공개 채널에 노출 금지):
 
-## Deploy on Vercel
+| Key | 용도 |
+| --- | --- |
+| `NEXT_PUBLIC_RUN_MODE` | `src/config/config.export.js` 가 어떤 config 를 로드할지 결정 (`local` / `local.dev` / `development` / `production`) |
+| `NEXT_PUBLIC_API_SERVER_PATH` | 백엔드 API base URL |
+| `NEXT_PUBLIC_HOST_URL` | 프론트엔드 호스트 (자기 자신) |
+| `NEXT_PUBLIC_API_HOST_URL` | API 호스트 |
+| `SESSION_SECRET` | iron-session 쿠키 서명 키 — **32 byte 이상 필수** |
+| `NEXT_PUBLIC_CONVERTER_DWG_API_URL` | DWG → SVG 변환 서비스 |
+| `NEXT_PUBLIC_CONVERTER_DXF_API_URL` | DXF → SVG 변환 서비스 |
+| `NEXT_PUBLIC_Q_ORDER_AUTO_LOGIN_URL` | Q-Order autoLogin 진입점 |
+| `NEXT_PUBLIC_Q_MUSUBI_AUTO_LOGIN_URL` | Q-Musubi autoLogin 진입점 |
+| `NEXT_PUBLIC_AWS_S3_BASE_URL` | S3 정적 자산 base URL |
+| `NEXT_PUBLIC_ENABLE_LOGGING` | `true` 일 때만 `src/util/logger.js` 와 `debugCapture.js` 가 실제로 출력 |
+| `AWS_REGION`, `AMPLIFY_BUCKET`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `S3_PROFILE` | S3 업로드 (서버 전용 — `.env.localhost` 등에만) |
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+`.env.*` 자체는 git 추적 대상이고 시크릿을 포함한다. 머신별 오버라이드는 `.env.*.local` (`gitignore` 됨) 에 둘 것.
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details.
+## Routes (App Router)
 
-deploy test
+```
+src/app/
+  api/                  # Next.js Route Handlers (S3, debug, 이미지 등)
+  community/            # 커뮤니티
+  floor-plan/           # 도면 캔버스 — 본 앱의 핵심
+    estimate/           # 견적 화면
+    simulator/          # 시뮬레이터
+    page.jsx            # 도면 에디터 진입점
+  join/                 # 회원가입
+  login/                # 로그인
+  management/           # 관리자
+    image/              # 이미지 관리
+    stuff/              # 자재/제품 관리
+  layout.js             # 루트 레이아웃 — 세션 체크 후 비로그인 시 /login 으로 리다이렉트
+  page.js               # 홈
+```
+
+세션이 없는 상태로 `/login` 외 경로 접근 시 루트 레이아웃이 강제 리다이렉트한다. `src/middleware.js` 는 `x-pathname` 헤더를 주입해 루트 레이아웃이 현재 경로에 따라 분기할 수 있게 한다.
+
+## Source Layout
+
+```
+src/
+  app/                  # App Router 라우트 + 글로벌 Provider 들
+  common/               # 공용 유틸 / 모듈
+  components/           # 도메인별 UI 컴포넌트
+    fabric/             # QLine, QPolygon — Fabric.js 확장 클래스
+    floor-plan/         # 캔버스 툴 모달 (roofShape, placementShape, panelBatch …)
+    estimate/, management/, simulator/, ui/, …
+  config/               # 모드별 런타임 config (config.export.js 가 분기)
+  hooks/                # 도메인별 hook (roofcover, surface, module, object, option …)
+  lib/                  # 세션, 캔버스 저장/복원, 파일/이미지 액션
+  locales/              # ja.json, ko.json
+  middleware.js         # x-pathname 주입
+  models/               # 도메인 모델
+  store/                # Recoil atom (canvas, roof, estimate, modal, menu, setting …)
+  styles/               # sass entry (includePaths)
+  util/                 # logger, debugCapture, fabric-extensions, canvas-util …
+```
+
+## Deployment (PM2)
+
+`*.ecosystem.config.js` + `startscript*.js` 조합으로 실행. `startscript` 가 `child_process.exec` 로 yarn 스크립트를 호출한다.
+
+| File | 용도 | Port |
+| --- | --- | --- |
+| `ecosystem.config.js` | 프로덕션 클러스터 (instances: 2) | — |
+| `prd1.ecosystem.config.js` | 프로덕션 #1 (fork) | 5000 |
+| `prd2.ecosystem.config.js` | 프로덕션 #2 (fork) | 5001 |
+| `dev.ecosystem.config.js` | dev 서버 | 5010 |
+| `dev.local.ecosystem.config.js` | local.dev 모드 dev 서버 | — |
+
+## Conventions
+
+상세 사항은 `CLAUDE.md` 와 `docs/Qcast coding convention.pdf`, `docs/Qcast development guilde.pdf` 참조. 핵심만 옮기면:
+
+- **Prettier**: single quote, **no semicolons**, tabWidth 2, printWidth 150, trailingComma `all`. 완료 전 `yarn lint`.
+- **No raw `alert()`** — `useSwal` / `useMessage` + `sweetalert2` 만 사용. `docs/메세지 처리 가이드.pdf`.
+- **Path alias** `@/...` 우선, `../../..` 체인 지양.
+- **로깅** — `console.log` 직접 사용 금지. `src/util/logger.js` 사용 (`NEXT_PUBLIC_ENABLE_LOGGING=true` 일 때만 출력).
+- **Commit message** — `.gitmessage.txt` 형식 (`[일감번호] : [제목]`) 또는 최근 브랜치 스타일 `[2204] <제목> — <상세>`. Prefix 만 영문, 본문은 한국어.
+- **i18n** — UI 텍스트는 `src/locales/{ja,ko}.json` 에 키 추가 후 `useI18n` 으로 접근.
+
+## Documentation
+
+| File | 내용 |
+| --- | --- |
+| `CLAUDE.md` | 에이전트(Claude / Codex) 작업 규약 + 비명시적 패턴 · gotcha |
+| `docs/Canvas Status.md` | 캔버스 기능 상태 · 타겟별 컨텍스트 메뉴 인벤토리 |
+| `docs/Qcast coding convention.pdf` | 전체 코딩 컨벤션 |
+| `docs/Qcast development guilde.pdf` | 개발 가이드 |
+| `docs/메세지 처리 가이드.pdf` | 모달 / 알럿 메시지 규칙 |
+| `docs/git commit message Convention.pdf` | 커밋 메시지 컨벤션 |
+| `docs/Nextjs 14 컴포넌트에 대해서….pdf` | App Router 서버/클라이언트 컴포넌트 노트 |
+| `docs/dictionary.txt` | 도메인 용어집 (지붕 / 패널 용어 JP/KR) |
+| `docs/diagrams/` | 아키텍처 다이어그램 |
+| `.agents/skills/{next-best-practices,vercel-react-best-practices}/` | Next/React 패턴 결정 시 우선 참조 (총 95개 룰 .md) |
+
+## Troubleshooting
+
+- **빌드 시 `Module not found: fs` / `canvas`** — `next.config.mjs` 의 webpack externals 에 추가. node-only deps 는 클라이언트 번들에서 제외해야 한다.
+- **세션이 즉시 풀림** — `SESSION_SECRET` 이 32 byte 미만이면 iron-session 이 거부한다. `.env.<mode>` 확인.
+- **플랜 로드 시 `InvalidStateError`** — `src/lib/canvas.js` / `src/util/canvas-util.js` 의 3-layer guard (entry/cache/save) 와 `SizeSetting` 의 0-area guard 로 차단된다. 가드 약화 금지 — 손상된 플랜은 정상 데이터로 교체할 것.
+- **App Router 캐시로 인한 stale plan/estimate** — `next.config.mjs` 의 `experimental.staleTimes` 가 의도적으로 모두 `0`. 다시 켜지 말 것.
+- **HTTPS dev 실패** — `./certificates/key.pem`, `cert.pem` 부재. gitignore 대상이라 팀에서 받아 배치해야 한다.
+- **dev 서버에서만 한글/일본어 폰트 깨짐** — `next/font` 캐시 문제일 가능성. `.next/` 삭제 후 재시작.