From f5c68ada806a19f79f8eb9aa74cda689afc95d1b Mon Sep 17 00:00:00 2001
From: hyunho <hyunho@local>
Date: Thu, 2 Apr 2026 11:22:52 +0900
Subject: [PATCH] Polish onboarding and reference asset layout

---
 CONTRIBUTING.md                              | 11 ++++++-----
 README.md                                    |  2 ++
 docs/TEAM_GUIDE.md                           |  5 +++++
 docs/architecture/8081_SERVING_MAP.md        |  4 ++--
 incoming-files/README.md                     |  2 ++
 incoming-files/{ => reference}/omh.html      |  0
 incoming-files/{ => reference}/opayment.html |  0
 scripts/prepare_dev_worktree.sh              |  4 ++++
 8 files changed, 21 insertions(+), 7 deletions(-)
 rename incoming-files/{ => reference}/omh.html (100%)
 rename incoming-files/{ => reference}/opayment.html (100%)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cb67845..4650081 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -24,11 +24,12 @@
 
 1. `main` 최신 상태를 받습니다.
 2. 작업 브랜치를 만듭니다.
-3. 필요한 경우 `./scripts/prepare_dev_worktree.sh`로 격리된 개발 워크스페이스를 준비합니다.
-4. `8081`에서 수정과 검증을 진행합니다.
-5. 관련 publish 스크립트가 있는 화면은 publish 후 실제 런타임 파일까지 확인합니다.
-6. `docs/REGRESSION_CHECKLIST.md` 기준으로 필요한 시나리오를 점검합니다.
-7. 커밋 후 PR을 생성합니다.
+3. `.env.example`을 `.env`로 복사합니다.
+4. 필요한 경우 `./scripts/prepare_dev_worktree.sh`로 격리된 개발 워크스페이스를 준비합니다.
+5. `8081`에서 수정과 검증을 진행합니다.
+6. 관련 publish 스크립트가 있는 화면은 publish 후 실제 런타임 파일까지 확인합니다.
+7. `docs/REGRESSION_CHECKLIST.md` 기준으로 필요한 시나리오를 점검합니다.
+8. 커밋 후 PR을 생성합니다.
 
 ## PR 규칙
 
diff --git a/README.md b/README.md
index e08769e..cd93f4a 100644
--- a/README.md
+++ b/README.md
@@ -39,12 +39,14 @@
 기본 공개 환경:
 
 ```bash
+cp .env.example .env
 docker compose up -d --build
 ```
 
 격리된 `8081` 개발 환경:
 
 ```bash
+cp .env.example .env
 ./scripts/prepare_dev_worktree.sh
 cd .dev-worktree-8081
 docker compose -p mh-dashboard-organization-dev --env-file .env -f docker-compose.8081.yml up -d --build
diff --git a/docs/TEAM_GUIDE.md b/docs/TEAM_GUIDE.md
index 6289208..c565794 100644
--- a/docs/TEAM_GUIDE.md
+++ b/docs/TEAM_GUIDE.md
@@ -56,6 +56,11 @@
 5. 필요한 DB 동기화 범위를 결정한다.
 6. 수정 후 관련 시나리오를 검증한다.
 
+환경 준비:
+
+- 최초 실행 전 `.env.example`을 `.env`로 복사한다.
+- `./scripts/prepare_dev_worktree.sh`는 dev worktree에 `.env`가 없으면 `.env.example`로 기본 파일을 만든다.
+
 핵심 질문:
 
 - 지금 고치는 파일이 실제 source-of-truth가 맞는가?
diff --git a/docs/architecture/8081_SERVING_MAP.md b/docs/architecture/8081_SERVING_MAP.md
index 7e2124d..01b6d23 100644
--- a/docs/architecture/8081_SERVING_MAP.md
+++ b/docs/architecture/8081_SERVING_MAP.md
@@ -94,8 +94,8 @@
 
 - `260320.html`
 - `sample style.css`
-- `opayment.html`
-- `omh.html`
+- `reference/opayment.html`
+- `reference/omh.html`
 - `reference/ledger/MH 통합 대시보드_260320.html`
 - `reference/ledger/MH 통합 대시보드_260320.css`
 - 원본 xlsx/csv
diff --git a/incoming-files/README.md b/incoming-files/README.md
index cc21610..13baa06 100644
--- a/incoming-files/README.md
+++ b/incoming-files/README.md
@@ -29,6 +29,8 @@
 - 샘플 스타일 파일
 - 원본/백업 HTML
 - 디자인 비교용 파일
+- `reference/omh.html`
+- `reference/opayment.html`
 - `reference/ledger/MH 통합 대시보드_260320.html`
 - `reference/ledger/MH 통합 대시보드_260320.css`
 - `reference/ledger/사업관리대장-1.xlsx`
diff --git a/incoming-files/omh.html b/incoming-files/reference/omh.html
similarity index 100%
rename from incoming-files/omh.html
rename to incoming-files/reference/omh.html
diff --git a/incoming-files/opayment.html b/incoming-files/reference/opayment.html
similarity index 100%
rename from incoming-files/opayment.html
rename to incoming-files/reference/opayment.html
diff --git a/scripts/prepare_dev_worktree.sh b/scripts/prepare_dev_worktree.sh
index c3b961b..ed97980 100755
--- a/scripts/prepare_dev_worktree.sh
+++ b/scripts/prepare_dev_worktree.sh
@@ -38,6 +38,10 @@ fi
 
 echo "[4/6] Copying local runtime env when available"
 copy_optional_path ".env"
+if [[ ! -f "${DEV_DIR}/.env" && -f "${DEV_DIR}/.env.example" ]]; then
+  cp "${DEV_DIR}/.env.example" "${DEV_DIR}/.env"
+  echo "Created ${DEV_DIR}/.env from .env.example"
+fi
 
 echo "[5/6] Copying local-only incoming design assets when available"
 copy_optional_path "incoming-files/1.png"