docs(insta-lab): design_importer는 로컬 실행 권장 — NAS docker exec 시 결과 소실 함정

docker-compose의 insta-lab volume mount는 /app/data만이라 /app/app/templates는
컨테이너 ephemeral state. NAS docker exec로 design_importer 돌리면 card.html.j2가
컨테이너 안에만 생성되고 다음 webhook rebuild에 소실됨 → 렌더러가 default 폴백.

- CLAUDE.md: "실행 위치 — 로컬 권장" 경고 + 로컬 셋업 흐름 + 응급 hotfix docker cp 패턴
- design_importer.py module docstring 동일 내용 반영

PNG 사이즈 1080×1350 → 4:5 비율 권장으로 문서 일치 (이전 검증 완화 반영).

CLAUDE.md

@@ -484,16 +484,30 @@ docker compose up -d
 - `agent_config.custom_config.auto_select=True`이면 카테고리당 1위 키워드 자동 슬레이트 생성·발송
 
 **디자인 import (사용자 디자인 PNG → Claude Vision → Jinja HTML 자동 생성)**
-- `insta-lab/app/templates/<theme>/pages/*.png` (10장, 1080×1350, placeholder 텍스트 박혀있는 형태) → Claude Sonnet Vision → `templates/<theme>/card.html.j2` 자동 생성
-- CLI: `docker exec insta-lab python -m app.design_importer <theme>`
+- `insta-lab/app/templates/<theme>/pages/*.png` (10장, 4:5 비율 권장 1080×1350, placeholder 텍스트 박혀있는 형태) → Claude Sonnet Vision → `templates/<theme>/card.html.j2` 자동 생성
 - 파일명 자동 매핑: `cover`/`start`/`intro` → page 1, `cta`/`outro`/`finish`/`end` → page 10, 나머지 알파벳 순 → page 2~9
 - 매핑 override: `pages/_order.json`에 `{filename: page_no}` 명시 (10장 + page 1~10 완전 매핑일 때만 적용)
 - Vision prompt에 placeholder 마스킹 요구 포함 (2-layer: 마스킹 박스 + 동적 텍스트 layer)
 - 기존 HTML 자동 백업 (`card.html.j2.bak.YYYYMMDD-HHMMSS`)
 - Jinja 문법 깨진 응답은 `card.html.j2.error.txt`로 보존 + ValueError
-- 활성화: NAS `.env`에 `INSTA_DEFAULT_THEME=<theme>` 추가 + `docker compose restart insta-lab`
+- 활성화: `.env`에 `INSTA_DEFAULT_THEME=<theme>` 추가 + `docker compose restart insta-lab` (테마 디렉토리에 `card.html.j2` 없으면 렌더러가 default로 폴백)
 - 토큰 비용: 1회당 ~15K tokens (~$0.05 Sonnet 기준)
 
+**⚠️ 실행 위치 — 로컬 권장, NAS docker exec 금지**
+- docker-compose의 insta-lab volume은 `/app/data`만 마운트. **`/app/app/templates`는 컨테이너 ephemeral state**.
+- NAS에서 `docker exec insta-lab python -m app.design_importer <theme>`로 돌리면 `card.html.j2`가 컨테이너 안에만 생성되고 다음 image rebuild(다른 push의 webhook이라도) 때 사라짐 → 렌더러가 default로 폴백.
+- **로컬 실행** (host repo working tree에 영속화 → git push → 자동 배포):
+  ```bash
+  cd insta-lab
+  pip install anthropic Pillow jinja2  # 이미 있으면 skip
+  export ANTHROPIC_API_KEY=sk-ant-...
+  python -m app.design_importer <theme> --templates-dir ./app/templates
+  git add app/templates/<theme>/card.html.j2
+  git commit -m "feat(insta-lab): <theme> 디자인 import"
+  git push  # → Gitea webhook → NAS rebuild → 영구 활성화
+  ```
+- 응급 hotfix로 NAS에서 돌렸다면 `docker cp insta-lab:/app/app/templates/<theme>/card.html.j2 ./` 후 즉시 host repo에 commit + push 필요
+
 **insta-lab API 목록**
 
 | 메서드 | 경로 | 설명 |

insta-lab/app/design_importer.py

@@ -1,6 +1,19 @@
 """사용자 디자인 PNG 10장 → Claude Sonnet Vision → Jinja card.html.j2 자동 생성.
 
-CLI (이 phase 이후 추가): python -m app.design_importer <theme_name>
+⚠️ 실행 위치 — 로컬 권장:
+    docker-compose의 insta-lab volume은 /app/data만 마운트. /app/app/templates는
+    컨테이너 ephemeral이라 NAS docker exec로 돌리면 다음 rebuild에 결과물 소실됨.
+
+로컬:
+    cd insta-lab
+    export ANTHROPIC_API_KEY=sk-ant-...
+    python -m app.design_importer <theme> --templates-dir ./app/templates
+    git add app/templates/<theme>/card.html.j2 && git commit + push
+
+응급 hotfix만 NAS:
+    docker exec insta-lab python -m app.design_importer <theme>
+    docker cp insta-lab:/app/app/templates/<theme>/card.html.j2 ./<dst>
+    # → 즉시 host repo에 commit + push (안 그러면 다음 rebuild에 소실)
 """
 
 import base64