sns-auto-builder 1.0.3 → 1.0.4

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # insta-carousel-builder — Claude Code 지시서
 
 > 이 프로젝트는 Claude Code에서 직접 실행하는 인스타 캐러셀 자동 제작 도구입니다.
-> 팀원이 "이 주제로 캐러셀 만들어줘"라고 요청하면 **리서치 → 9장 설계 → 생성(HTML 또는 ChatGPT 웹) → 품질 검증**까지 수행합니다.
+> 팀원이 "이 주제로 캐러셀 만들어줘"라고 요청하면 **리서치 → 시나리오 설계 → 사람 승인 → 생성(HTML 또는 ChatGPT 웹) → 품질 검증**까지 수행합니다.
 
 ---
 
@@ -37,7 +37,7 @@
 
 ```
 Phase 3a (HTML — 기본):
-  # 1. carousel-html-writer 가 output/<topic>/slides/slide-01~09.html 작성
+  # 1. carousel-html-writer 가 output/<topic>/slides/slide-01~NN.html 작성
   # 2. node scripts/html-carousel-gen.js --topic <keyword>
 
 Phase 3b (ChatGPT 웹 — 슬라이드 전체를 이미지로):
@@ -56,30 +56,30 @@ Phase 3c (ChatGPT 웹 — 배경만 뽑고 한글은 HTML 로 얹기):
 
 ---
 
-## 기본 산출물 — 9장 풀세트
+## 기본 산출물 — 장수는 요청에서 온다
 
-**모든 캐러셀 요청은 기본적으로 9장 세트를 생산합니다:**
-- Cover 1장 + 본문 7장 (예: TIP 01~07) + Outro 1장
-- 각 슬라이드는 `templates/slides.*.json` 의 프롬프트로 정의
+**빌더가 "장수: N장" 을 명시하면 그 수를 정확히 따른다.** 그게 최우선이다.
+명시가 없을 때만 9장을 기본으로 한다. (빌더에서 3~12장 중 고를 수 있다.)
 
-9장이 아닌 개수 지정은 사용자가 명시한 경우만 수용.
+- 구성: Cover 1장 + 본문 (N-2)장 + Outro 1장
+- 각 슬라이드는 `templates/slides.*.json` 의 프롬프트로 정의
 
 ---
 
-## 품질 킬라인 (9장 각각에 적용)
+## 품질 킬라인 (모든 장에 적용)
 
 | # | 기준 | 허용 범위 |
 |:---:|:---|:---|
-| 1 | **해상도** | 1080×1350 의 **정수배** (4:5 인스타 권장). HTML 트랙 기본은 2x = 2160×2700. 9장 배율 통일 필수 |
-| 2 | **한글 렌더링** | 오타 없어야 함 (`duplicate-check.js` 로 체크) |
-| 3 | **디자인 DNA 일관성** | 9장 배경색/폰트/액센트 컬러 통일 |
+| 1 | **해상도** | 1080×1350 의 **정수배** (4:5 인스타 권장). 기본은 2x = 2160×2700. 전 장 배율 통일 필수 |
+| 2 | **한글 렌더링** | 오타 없어야 함. **자동 검출 수단이 없다 — 반드시 육안 확인** |
+| 3 | **디자인 DNA 일관성** | 전 장 배경색/폰트/액센트 컬러 통일 |
 | 4 | **Cover 후킹** | 3초 내 스크롤 멈춤 가능한 헤드라인 |
 | 5 | **1장당 정보 밀도** | 한 슬라이드 = 한 포인트 (여러 개 = 혼란) |
 | 6 | **CTA 슬라이드** | Outro 에 저장/공유/팔로우 중 **1개만** |
 | 7 | **금칙어** | `knowledge/banned-words.json` 참조 |
 | 8 | **톤** | 친근한 전문가. "안녕하세요 오늘은" 같은 filler 금지 |
 
-→ `scripts/quality-check.js` 가 생성 직후 자동 검사. 한글 오타 감지 시 해당 슬라이드만 재생성.
+→ `scripts/quality-check.js` 가 해상도·배율·장수를 검사한다. **한글 오타는 못 잡는다** (픽셀 안을 못 본다).
 
 ---
 
@@ -87,9 +87,9 @@ Phase 3c (ChatGPT 웹 — 배경만 뽑고 한글은 HTML 로 얹기):
 
 **매 작업마다**:
 1. `knowledge/brand-facts.md` — 수치/브랜드 SSOT (이 파일 외 숫자 금지)
-2. `knowledge/patterns/carousel-structure.md` — 9장 구조 공식
+2. `knowledge/patterns/carousel-structure.md` — 구조 공식 (9장 기준. 장수가 다르면 비례 조정)
 3. `templates/slides.example.json` — 프롬프트 템플릿
-4. `output/_index.json` — 최근 패턴 → 의도적으로 다른 구조 선택
+4. `output/` 의 최근 결과 폴더 — 직전 캐러셀과 **의도적으로 다른 구조**를 고른다 (없으면 넘어간다)
 
 **상황별 추가 Read**:
 - 주제 리서치: `knowledge/reference/` (있다면)
@@ -97,18 +97,19 @@ Phase 3c (ChatGPT 웹 — 배경만 뽑고 한글은 HTML 로 얹기):
 
 ---
 
-## 3-Phase Pipeline (carousel-new 풀 파이프라인)
+## 파이프라인 (carousel-new 풀 파이프라인)
 
 ```
 Phase 1 [리서치/기획]  → carousel-researcher 서브에이전트 dispatch
-                          주제 요약, 9장 구조 초안, hook 후보 생성
+                          주제 요약, N장 구조 초안, hook 후보 생성
 Phase 2 [프롬프트 설계] → carousel-prompt-writer 서브에이전트 dispatch
-                          9장 프롬프트 JSON 작성 (templates/slides.{topic}.json)
+                          N장 프롬프트 JSON 작성 (templates/slides.{topic}.json)
 Phase 3 [이미지 생성]  → node scripts/chatgpt-image-gen.js 실행
-                          로그인된 Chrome 으로 ChatGPT 를 몰아 9장 PNG 생성 (API 키 불필요)
-Phase 4 [품질 검증]    → scripts/quality-check.js 자동 실행
-                          → carousel-reviewer 서브에이전트 10항목 정성 채점
-                          오타 감지 시 해당 슬라이드만 재생성
+                          로그인된 Chrome 으로 ChatGPT 를 몰아 N장 PNG 생성 (API 키 불필요)
+Phase 4 [품질 검증]    → scripts/quality-check.js 실행 (해상도·배율·장수)
+Phase 5 [정성 리뷰]    → carousel-reviewer 가 review.md 작성
+                          **결과를 사람에게 보여준 뒤 따로 돈다.** 빌더가 별도로 부르므로
+                          생성 단계에서 미리 호출하지 마라. 리뷰어는 지적만 하고 고치지 않는다
 ```
 
 **서브에이전트 원칙**:
@@ -122,10 +123,12 @@ Phase 4 [품질 검증]    → scripts/quality-check.js 자동 실행
 
 ```
 output/{topic}/
-├── slide-01.png ~ slide-09.png   # 1080×1350 PNG 9장
-├── prompts.json                  # 사용된 프롬프트 (재현용)
-├── metadata.json                 # 생성 시간/비용/품질 리포트
-└── README.md                     # 주제 요약 + 사용 가이드
+├── slide-01.png ~ slide-NN.png   # 2160×2700 PNG (1080×1350 의 2배)
+├── brief.json                    # 리서치 결과 = 사람이 승인한 시나리오
+├── gen.json                      # 실행 조건 (엔진·장수·레퍼런스) — 재생성에 쓰인다
+├── caption.md                    # 인스타 본문 캡션
+├── quality-report.json           # 기계 검사 결과
+└── review.md                     # 정성 채점 (결과를 보여준 뒤 따로 생성)
 ```
 
 **명명 규칙**: `{YYYY-MM-DD}_{주제압축}` (공백 제거, 특수문자 금지)
@@ -135,8 +138,8 @@ output/{topic}/
 ## Zero-Inference 원칙
 
 - 수치는 반드시 `brand-facts.md` 에서만 인용
-- 이미지 생성 결과의 한글 오타 판정은 **스크립트가 수행** (LLM 판단 금지)
-- 스크립트 경고 발생 시 무시하지 말고 재생성
+- 한글 오타는 **자동 판정 수단이 없다.** 사람이 눈으로 본다
+- `quality-check.js` 가 FAIL 이면 원인을 고치고 다시 만든다 (해상도·장수는 기계가 잡는다)
 
 ---
 
@@ -147,7 +150,7 @@ ChatGPT 구독 계정을 쓴다. `.env` 에 키가 있든 없든 이 트랙과
 
 `.env` 파일 (git 추적 금지):
 ```
-ANTHROPIC_API_KEY=              # (옵션) reviewer 서브에이전트 API 호출용
+# 글·이미지 생성 모두 키가 필요 없다. 이 파일은 비어 있어도 된다.
 ```
 
 ### 의존성
@@ -167,7 +170,7 @@ npm install   # puppeteer 자동 설치 — 이것만 하면 된다
 - 생성된 이미지는 **반드시 육안 검토 후 업로드** — AI 이미지 특유의 미세 왜곡 가능
 - 자동 업로드 없음 (의도적 배제 — 인스타 알고리즘 패턴 탐지 회피)
 - 하루 1~2 캐러셀 권장 (과도한 업로드 역효과)
-- 이미지 트랙은 9장 중 오타가 나올 수 있음 → `--only N` 으로 해당 슬라이드만 재생성
+- 이미지 트랙은 오타가 나올 수 있음. **에이전트가 임의로 다시 뽑지 마라** — 몇 번 장이 왜 이상한지 보고만 하고, 다시 뽑을 장은 사람이 결과 화면 버튼으로 고른다
 - 한 장이 실패(응답 없음)해도 스크립트는 `ERR` 로 찍고 다음 장으로 넘어간다 → 나중에 `--only N`
 
 ---

package/README.md

@@ -1,23 +1,38 @@
 # sns-auto-builder
 
-카드뉴스(인스타 캐러셀 9장) / 쓰레드(Threads) 생성 도구.
-**글 생성에는 API 키가 필요 없습니다** — Claude Code CLI(`claude -p`)를 호출해 구독 계정으로 돌아갑니다.
-이미지 생성만 키가 듭니다.
+카드뉴스(인스타 캐러셀) / 쓰레드(Threads) 생성 도구.
+
+**API 키가 필요 없습니다.** 글은 Claude Code CLI(`claude -p`), 이미지는 로그인된 Chrome 으로
+ChatGPT 웹을 몰아 만듭니다 — 둘 다 **본인 구독 계정**으로 돕니다.
 
 구조는 [insta-carousel-builder](https://github.com/shdsjh123-cpu/insta-carousel-builder) 하네스를
-**원본 그대로** 가져왔습니다 (`brand-facts.md` 의 브랜드명 한 줄만 교체). 부족한 부분은 원본을 고치지 않고 별도 파일로 추가했습니다.
+가져왔습니다. 원본 파일은 최대한 두고 부족한 부분을 별도 파일로 추가했습니다.
 
 ---
 
-## 진입점 2개 — 같은 하네스를 쓴다
+## 쓰는 법
+
+### 배포판 (팀원용)
+
+`dist/` 의 파일 **4개를 같은 폴더에** 두고 씁니다:
+
+1. **설치.bat** — 처음 한 번. Node · Claude Code 설치 + 로그인 2번(Claude, ChatGPT)
+2. **실행.bat** — 매번. 더블클릭하면 브라우저가 열립니다
+3. **config.bat** — 설정. **두 bat 이 이것을 읽습니다**
+4. **사용법.txt** — 안내
 
-**웹 UI**
+`실행.bat` 은 `npx sns-auto-builder@latest` 를 부릅니다. **켤 때마다 최신 버전을 받으므로
+업데이트는 자동**입니다 (`npm publish` 하면 팀원은 다음 실행부터 새 버전).
+
+단 `.bat` 자체는 패키지에 없어서 자동 갱신이 안 됩니다. 고치면 다시 보내야 합니다.
+
+### 개발 (이 레포에서)
 
 ```bash
 node server.mjs      # → http://127.0.0.1:8787
 ```
 
-**슬래시 커맨드** (Claude Code 안에서)
+Claude Code 안에서는 슬래시 커맨드도 됩니다:
 
 ```
 /carousel-new 클로드 코드 생산성 꿀팁
@@ -25,134 +40,195 @@ node server.mjs      # → http://127.0.0.1:8787
 ```
 
 웹 서버는 파이프라인을 복제하지 않고 `claude -p` 로 **같은 서브에이전트를 호출**합니다.
-`CLAUDE.md` 가 단일 출처입니다.
+`CLAUDE.md` 가 단일 출처입니다. 포트 충돌 시 `PORT=8788 node server.mjs`.
+
+### 데이터가 쌓이는 곳
+
+배포판은 패키지 밖 **워크스페이스**에 사용자 데이터를 둡니다. 그래서 업데이트해도
+브랜드 설정 · ChatGPT 로그인 · 결과물이 그대로 남습니다.
+
+```
+%LOCALAPPDATA%\sns-auto-builder\        ← 기본
+├── workspace 파일들 (output, knowledge, .chrome-profile, logs …)
+├── browser\      puppeteer 크로미움 (약 2.6GB)
+└── npm-cache\    npx 캐시 (수 GB)
+```
+
+C: 여유가 부족하면 **`config.bat`** 의 `set "DATA_DRIVE="` 를 `set "DATA_DRIVE=D:"` 처럼
+바꾸면 됩니다. 기존 워크스페이스는 최초 1회 자동으로 옮겨집니다.
+**USB·외장 드라이브는 쓰지 마세요** — 빼는 순간 로그인과 결과물이 사라집니다.
+
+> **경로는 한 곳에서만 계산합니다.** 예전에는 `실행.bat` · `설치.bat` · 스크립트가
+> 각자 경로를 계산했고, 한쪽만 바뀌자 **ChatGPT 로그인이 빌더가 안 보는 폴더에 저장**됐습니다.
+> 지금은 두 bat 이 `config.bat` 을 읽고, 크롬 창은 빌더 자신이 엽니다.
 
-포트 충돌 시 `PORT=8788 node server.mjs`.
+```bash
+npx sns-auto-builder --where    # 실제 워크스페이스·프로필·크롬 경로 출력
+npx sns-auto-builder --login    # 빌더가 읽는 그 프로필로 ChatGPT 로그인 창 열기
+```
+
+`--login` 은 **디버깅 포트를 붙여** 크롬을 엽니다. 포트 없이 뜬 창이 그 프로필을 잡고 있으면
+Chrome 은 인스턴스를 하나만 허용하므로 빌더가 영영 포트를 못 엽니다.
 
 ---
 
 ## 카드뉴스 엔진 3개
 
-웹에서 카드뉴스를 고르면 엔진을 묻습니다. 한글 정확도와 비용이 여기서 갈립니다.
+카드뉴스를 고르면 엔진을 묻습니다. 한글 정확도가 여기서 갈립니다. **셋 다 키는 불필요**합니다.
 
-| 엔진 | 한글 | 비용 | 키 | 어울리는 곳 |
-|:--|:--|:--|:--|:--|
-| **HTML만** | **100% 결정적** | 0원 | 불필요 | 세법·법무·정보성. 한 글자만 고쳐 재캡처 가능 |
-| **이미지 + HTML** | **100% 결정적** | 구독 | 불필요 (ChatGPT 로그인) | 분위기가 필요한 브랜드·감성 주제 |
-| **이미지만** | 비결정적 ⚠️ | 구독 | 불필요 (ChatGPT 로그인) | 글자가 적은 비주얼 위주 |
+| 엔진 | 한글 | 어울리는 곳 |
+|:--|:--|:--|
+| **HTML만** | **100% 결정적** | 세법·법무·정보성. 한 글자만 고쳐 재캡처 가능 |
+| **이미지 + HTML** | **100% 결정적** | 배경만 이미지로 뽑고 글자는 HTML. 분위기가 필요한 주제 |
+| **이미지만** | 비결정적 ⚠️ | 글자가 적은 비주얼 위주 |
 
 **이미지만 모드는 한글이 이미지 안에 들어가 매번 달라집니다.** 스크립트가 오타를 못 잡으니
-9장을 눈으로 확인하고 깨진 장만 `--only N` 으로 다시 뽑으세요. 글자가 중요하면 다른 두 엔진을 쓰세요.
+눈으로 확인하고, 깨진 장은 결과 화면의 **다시 만들기** 버튼으로 그 장만 다시 뽑으세요.
 
-쓰레드는 글만 뽑으므로 엔진 선택이 없습니다.
+장수는 **3~12장** 중 고를 수 있고, 고르지 않으면 9장입니다.
+쓰레드는 글만 뽑으므로 엔진·장수 선택이 없습니다.
 
 ---
 
 ## 파이프라인
 
 ```
-리서치        carousel-researcher      → brief.json (검증 사실 / 불확실 분리)
-   ↓
-배경(선택)    chatgpt-image-gen.js --mode bg → bg/bg-NN.png  ← 이미지+HTML 만
-   ↓
-작성          carousel-html-writer     → slides/slide-NN.html
-   또는       carousel-prompt-writer   → templates/slides.<topic>.json  ← 이미지만
-   ↓
-생성          html-carousel-gen.js     → slide-NN.png (2160×2700)
-   또는       chatgpt-image-gen.js     → slide-NN.png (2160×2700)
-   ↓
-검사          quality-check.js --dir   → 해상도·배율·장수 (기계)
-              carousel-reviewer        → 10항목 채점 (정성)
+1. 리서치      carousel-researcher   → brief.json (검증 사실 / 불확실 분리)
+                                        ↓
+2. 사람이 승인  "이렇게 만들까요?"      문구를 직접 고치거나 AI 추천을 받아 교체
+                                        ↓
+3. 생성        carousel-html-writer  → slides/slide-NN.html → html-carousel-gen.js
+    또는       carousel-prompt-writer → templates/slides.<topic>.json → chatgpt-image-gen.js
+               (배경만 뽑을 땐 chatgpt-image-gen.js --mode bg)
+                                        ↓
+4. 검사        quality-check.js      → 해상도·배율·장수 (기계, 즉시)
+                                        ↓
+   결과 화면을 먼저 보여준 뒤
+5. 리뷰        carousel-reviewer     → review.md (10항목 채점, 백그라운드)
 ```
 
-작성자와 검증자를 분리한 게 핵심입니다. 실제로 리뷰어가 작성자의 사실 오류를 잡아냅니다.
+**2번에서 한 번 멈춥니다.** 이미지에 시간·쿼터를 쓰기 전에 시나리오를 확인·수정하는 자리입니다.
 
----
+**5번은 결과를 보여준 뒤 뒤에서 돕니다.** 이미지를 눈으로 훑는 작업이라 10분 넘게 걸리는데,
+그걸 기다리느라 결과 화면이 늦어지면 안 됩니다. 끝나면 결과 화면에 점수와 함께 접혀서 붙습니다.
 
-## 구조
-
-```
-sns-auto-builder/
-├── CLAUDE.md                  # 에이전트 진입점 (원본)
-├── .claude/
-│   ├── agents/                # carousel-researcher / -html-writer / -prompt-writer / -reviewer (원본)
-│   └── commands/              # /carousel-new, /carousel-quality (원본)
-├── knowledge/                 # ★ 프롬프트 단일 출처
-│   ├── brand-facts.md         # 브랜드·톤·수치·디자인 DNA (원본 + 브랜드명만 교체)
-│   ├── banned-words.json      # 금칙어 (원본)
-│   └── patterns/
-│       ├── carousel-structure.md        # 9장 공식 (원본)
-│       ├── carousel-output-format.md    # 텍스트 출력 형식 (추가)
-│       └── thread-structure.md          # 스레드 공식 (추가 — 원본엔 쓰레드가 없음)
-├── scripts/
-│   ├── quality-check.js       # JSON 스키마 + PNG 해상도/배율 (원본 + 해상도 검사 추가)
-│   ├── quality-check-text.js  # 카피 금칙어·글자수·구조 (추가)
-│   ├── html-carousel-gen.js   # HTML → PNG 캡처 (원본)
-│   ├── chatgpt-image-gen.js   # ChatGPT 웹 배경/슬라이드 — API 키 불필요 (추가)
-│   ├── openai-image-gen.js    # OpenAI API 배경/슬라이드 (추가, 빌더는 더 이상 안 씀)
-│   └── nanobanana-gen.py      # Gemini 슬라이드 (원본, Python 필요)
-├── templates/
-├── output/                    # 생성 결과 (gitignored)
-├── server.mjs · index.html    # 웹 UI (추가)
-└── test.mjs
-```
+리뷰어는 **지적만** 합니다. 어느 장을 다시 뽑을지는 사람이 버튼으로 정합니다.
 
 ---
 
 ## 웹 UI
 
-1. **카드뉴스** 또는 **쓰레드**
-2. (카드뉴스) 엔진 선택
-3. 주제 입력 — `⌘/Ctrl + Enter` 로도 시작
-4. (선택) **참고 자료** 이미지 첨부 — 끌어다 놓기 / `⌘/Ctrl + V` / 눌러서 고르기
-5. 진행 단계가 실시간 표시 → 끝나면 슬라이드 미리보기 + 개별 다운로드
+1. **⚙ 브랜드 컨셉 설정** (처음 한 번) — 브랜드명만 필수, 나머지는 비워도 됩니다
+2. **카드뉴스** 또는 **쓰레드**
+3. (카드뉴스) 엔진 선택 — 여기서 **📁 결과물 보기** 로 지난 작업을 열람·삭제
+4. 장수 선택 · 참고 자료 · 로고 · 주제 입력 (`⌘/Ctrl + Enter` 로도 시작)
+5. **"이렇게 만들까요?"** — 문구 수정 / ✨ AI 추천 / 장수 바꿔 다시
+6. 생성 — 완성되는 대로 **한 장씩 실시간**으로 뜹니다
+7. 결과 — 인스타 목업 스와이프 미리보기 · 다시 만들기 · **한번에 받기**(zip)
+
+진행 표시는 **모델 보고가 아니라 파일이 생겼는지로 판정**합니다. 모델은 실제 작업 전에
+"done" 을 찍은 적이 있어서 믿지 않습니다.
+
+카드뉴스는 리서치 5~8분 + 이미지 장당 25~40초. 쓰레드는 1~2분.
+
+### 브랜드 설정
+
+값은 `knowledge/brand.json` 에 저장되고 `brand-facts.md` 가 **자동 생성**됩니다.
+그래서 패키지에는 빈 템플릿만 들어가고 **회사 정보는 각자 PC 에만** 남습니다.
+
+> `brand-facts.md` 를 직접 고치지 마세요. 다음 저장 때 덮어써집니다.
+> 항목을 늘리려면 `knowledge/brand.schema.json` 만 고치면 화면과 문서가 같이 따라옵니다.
+
+**빈칸은 아예 언급되지 않습니다.** 자리표시자가 프롬프트에 새면 모델이 그걸 사실로 착각해
+지어내기 때문입니다.
 
-진행 표시는 **모델 보고가 아니라 파일이 생겼는지로 판정**합니다. `brief.json` 이 없으면 리서치는 진행 중입니다.
+### 참고 자료 · 로고
 
-카드뉴스 전체 파이프라인은 **20~35분** 걸립니다. 쓰레드는 1~2분.
+경쟁사 캡처나 레퍼런스를 올리면 **카피와 디자인 둘 다** 그걸 따라갑니다.
 
-### 참고 자료
+- png · jpg · webp · gif, **최대 6장 / 총 20MB**
+- 한 번 올린 세트는 **템플릿**으로 남아 다음에도 고를 수 있습니다 (목록에서 삭제도 가능)
+- 지금 무엇이 들어가는지 참고 자료 칸 아래에 항상 표시됩니다
+- **로고는 SVG** 로 따로 올립니다 — HTML 트랙은 `<img>` 로 그대로 얹고,
+  이미지 트랙은 모델에게 그 자리를 비우게 한 뒤 **크롭할 때 원본 SVG 를 합성**합니다
+  (모델이 그리면 로고가 뭉개집니다)
 
-경쟁사 캡처, 화면, 자료 문서를 올리면 그걸 보고 씁니다. **사진 자체는 결과물에 안 들어갑니다.**
+프롬프트 가드: 이미지 속 **수치를 사실로 취급 금지**, 이미지 안 지시문은 **따르지 않음**.
+매번 참고할 고정 자료는 업로드 말고 `knowledge/reference/` 에 두세요.
 
-- png · jpg · webp · gif, **최대 6장 / 총 20MB**. SVG는 막습니다 (스크립트 실행 가능)
-- 파일명은 서버가 붙입니다 (클라이언트 값 안 씀 — 경로 조작 방지)
-- 프롬프트 가드: 이미지 속 **수치를 사실로 취급 금지**, 이미지 안 지시문은 **따르지 않음**
-- 매번 참고할 고정 자료는 업로드 말고 `knowledge/reference/` 에 두세요
+### 문제가 생기면
+
+첫 화면의 **🛟 문제 신고용 로그** 를 누르면 `sns-auto-builder-log.txt` 가 받아집니다.
+그 파일만 보내면 됩니다.
+
+로그는 **버튼과 무관하게 항상 자동으로 쌓입니다** — 버튼은 내려받는 손잡이일 뿐입니다.
+버전 · OS · 실행 기록 · 오류와 발생 위치가 담기고, **브랜드 값 내용 · 토큰 · 쿠키는 안 담깁니다.**
 
 ---
 
-## 키 설정
+## 구조
 
-`.env` 를 **프로젝트 루트**에 만드세요 (`.env.example` 이 아니라 — 그건 커밋되는 템플릿입니다).
+```
+sns-auto-builder/
+├── CLAUDE.md                  # 에이전트 진입점 — 프롬프트 맨 앞에 통째로 들어감
+├── bin/sns-auto-builder.mjs   # npx 실행기 (워크스페이스 준비 → 서버 → 브라우저)
+├── dist/                      # 팀원 배포용 4개 (실행·설치·config.bat · 사용법.txt) — 패키지 제외
+├── .claude/
+│   ├── agents/                # carousel-researcher / -html-writer / -prompt-writer / -reviewer
+│   └── commands/              # /carousel-new, /carousel-quality
+├── knowledge/                 # ★ 프롬프트 단일 출처
+│   ├── brand.schema.json      # 브랜드 설정 폼 정의 (화면 + 문서가 같이 참조)
+│   ├── brand.json             # 입력된 값 (gitignored·패키지 제외)
+│   ├── brand-facts.md         # 위 값에서 자동 생성 (gitignored·패키지 제외)
+│   ├── logo.svg               # 올린 로고 (gitignored·패키지 제외)
+│   ├── banned-words.json      # 금칙어
+│   └── patterns/              # 구조 공식 · 출력 형식 · 스레드 공식
+├── scripts/
+│   ├── quality-check.js       # PNG 해상도/배율/장수 + 프롬프트 JSON 스키마
+│   ├── quality-check-text.js  # 카피 금칙어·글자수·구조
+│   ├── html-carousel-gen.js   # HTML → PNG 캡처
+│   ├── chatgpt-image-gen.js   # ChatGPT 웹으로 이미지 생성 (키 불필요)
+│   ├── openai-image-gen.js    # OpenAI API 트랙. 빌더는 안 쓰고 cropTo45 만 재사용
+│   └── nanobanana-gen.py      # 업스트림 잔재. 이 환경에서는 쓰지 않음
+├── templates/                 # *.example.json 만 패키지에 포함
+├── output/                    # 결과물 · _refs (gitignored·패키지 제외)
+├── logs/                      # 실행·오류 기록 (gitignored·패키지 제외)
+├── server.mjs · index.html    # 웹 UI
+└── test.mjs
+```
+
+---
+
+## 배포
 
 ```bash
-cp .env.example .env
+npm version patch          # 버전 올리기
+npm pack --dry-run         # 나갈 파일 눈으로 확인 ★
+npm publish
 ```
 
-| 키 | 언제 필요 | 발급 |
-|:--|:--|:--|
-| `GEMINI_API_KEY` | 나노바나나 트랙 (Python 필요) | aistudio.google.com/apikey |
-| `OPENAI_API_KEY` | `openai-image-gen.js` 를 직접 쓸 때만 | platform.openai.com/api-keys |
+`package.json` 의 `files` 는 **넣을 것만 적는 화이트리스트**입니다. 새 폴더가 생겨도
+실수로 안 나갑니다. 그래도 퍼블리시 전에는 `--dry-run` 으로 확인하세요 —
+`brand.json` · `logo.svg` · `output/` · `.chrome-profile` · `logs/` 가 목록에 없어야 합니다.
 
-빌더의 **이미지+HTML / 이미지만** 트랙은 키가 필요 없습니다. `chatgpt-image-gen.js` 가
-로그인된 Chrome 프로필(`.chrome-profile`)로 chatgpt.com 을 몰아 구독 계정으로 생성합니다.
-그 프로필에 **한 번 로그인해두면** 이후로는 그대로 재사용됩니다.
+`.bat` 은 패키지에 없어서 **자동 업데이트가 안 됩니다.** 고치면 팀원에게 4개를 다시 보내야 합니다.
 
-`.env` 는 gitignored 입니다. **키를 `.env.example` 에 넣지 마세요.**
+> `.bat` 은 **ASCII 로만** 쓰세요. cmd 는 콘솔 코드페이지로 파일을 읽는데 그 값이 PC 마다
+> 달라서, 한글 바이트가 명령어를 갉아먹습니다 (`echo.` 가 `ech` + `o.` 로 쪼개진 적 있음).
+> 한글 안내는 `사용법.txt` 와 Node 출력이 담당합니다.
 
 ---
 
-## 커스터마이즈
+## 키 설정 — 대부분 필요 없습니다
 
-| 파일 | 뭘 고치나 |
+빌더의 세 엔진 모두 키 없이 돕니다. `.env` 는 아래 경우에만 씁니다.
+
+| 키 | 언제 |
 |:--|:--|
-| `knowledge/brand-facts.md` | 브랜드·타겟·수치·디자인 DNA — **여기부터 채우세요** |
-| `knowledge/banned-words.json` | 금칙어. 브랜드 금지어는 `brand_specific` 에 |
-| `knowledge/patterns/*.md` | 구조 공식, 글자수, 출력 형식 |
-| `scripts/html-carousel-gen.js` | `CONFIG.deviceScaleFactor` — 배율 (기본 2x) |
+| `OPENAI_API_KEY` | `openai-image-gen.js` 를 직접 호출할 때만 |
+| `GEMINI_API_KEY` | `nanobanana-gen.py` (이 환경에서는 안 씀) |
 
-`brand-facts.md` 에 `<채우세요>` 가 남아 있으면 그 항목은 **언급되지 않습니다** (지어내지 않습니다).
+`.env` 는 gitignored 입니다. **키를 `.env.example` 에 넣지 마세요.**
 
 ---
 
@@ -162,17 +238,21 @@ cp .env.example .env
 node test.mjs                                          # 조립·검증 로직
 node scripts/quality-check.js --dir output/<topic>     # PNG 해상도·배율·장수
 node scripts/quality-check.js --prompt templates/slides.<topic>.json
-node scripts/quality-check-text.js --file output/<topic>/copy.md
 node scripts/chatgpt-image-gen.js --topic t --slides templates/slides.example.json --dry-run
 ```
 
-**해상도**: `1080×1350` 의 정수배만 통과합니다. HTML 트랙 기본이 2x(`2160×2700`)이고,
+**해상도**: `1080×1350` 의 정수배만 통과합니다. 기본이 2x(`2160×2700`)이고,
 인스타는 업로드 시 가로 1080으로 줄이므로 2x가 손해가 아닙니다.
 
+`quality-check.js` 의 기대 장수는 `--count` 또는 결과 폴더의 `gen.json` 에서 읽습니다.
+
 ---
 
 ## 안 하는 것
 
 - **자동 업로드** — 의도적 배제 (알고리즘 패턴 탐지 회피)
-- **한글 오타 자동 검출** — 이미지만 모드는 육안 검수가 필수입니다
-- 툴 UI의 크림/Jua 배색은 **툴 자체 컨셉**입니다. 카드뉴스 디자인은 `brand-facts.md` 의 디자인 DNA를 따릅니다
+- **한글 오타 자동 검출** — 이미지 트랙은 육안 검수가 필수입니다
+- **에이전트가 알아서 재생성** — 확인 못 한 상태로 덮어쓰면 멀쩡한 장을 잃습니다.
+  다시 뽑을 장은 사람이 버튼으로 고릅니다
+- 툴 UI의 크림/Jua 배색은 **툴 자체 컨셉**입니다. 카드뉴스 디자인은
+  레퍼런스 > 브랜드 설정 > 기본값 순으로 정해집니다

package/bin/sns-auto-builder.mjs

@@ -94,7 +94,52 @@ const open = (url) => {
   spawn(cmd[0], cmd[1], { stdio: 'ignore', detached: true }).on('error', () => {}).unref();
 };
 
+// 설치된 Chrome. puppeteer 번들(구버전)은 프로필 버전이 안 맞아 바로 죽는다.
+function findChrome() {
+  const c = [
+    process.env.PROGRAMFILES && join(process.env.PROGRAMFILES, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    process.env['PROGRAMFILES(X86)'] && join(process.env['PROGRAMFILES(X86)'], 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    process.env.LOCALAPPDATA && join(process.env.LOCALAPPDATA, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/usr/bin/google-chrome',
+  ].filter(Boolean);
+  return c.find((p) => existsSync(p)) || null;
+}
+
 const ws = workspaceDir();
+
+// --where / --login 은 **경로 계산을 여기 한 곳으로 모으기 위한** 진입점이다.
+// .bat 이 경로를 따로 계산하면 한쪽만 바뀌었을 때 로그인이 빌더가 안 보는 폴더에 저장된다
+// (실제로 그 사고가 났다). .bat 은 이제 이 명령에 물어본다.
+const argv = process.argv.slice(2);
+if (argv.includes('--where')) {
+  console.log(`workspace : ${ws}`);
+  console.log(`profile   : ${join(ws, '.chrome-profile')}`);
+  console.log(`chrome    : ${findChrome() || '(찾지 못함)'}`);
+  process.exit(0);
+}
+if (argv.includes('--login')) {
+  const profile = join(ws, '.chrome-profile');
+  mkdirSync(profile, { recursive: true });
+  const exe = findChrome();
+  if (!exe) {
+    console.error('Chrome 을 찾지 못했습니다. Chrome 을 설치한 뒤 다시 실행하세요.');
+    process.exit(1);
+  }
+  console.log(`\n  ChatGPT 로그인 창을 엽니다.`);
+  console.log(`  프로필: ${profile}`);
+  console.log(`  로그인만 하고 창은 그대로 두거나 닫으면 됩니다.\n`);
+  // 포트를 반드시 붙인다. Chrome 은 user-data-dir 당 인스턴스 하나만 띄우므로,
+  // 포트 없이 뜬 창이 남으면 빌더가 그 프로필로 포트를 못 연다.
+  spawn(exe, [
+    '--remote-debugging-port=9222',
+    `--user-data-dir=${profile}`,
+    '--no-first-run', '--no-default-browser-check',
+    'https://chatgpt.com',
+  ], { detached: true, stdio: 'ignore' }).unref();
+  process.exit(0);
+}
+
 mkdirSync(ws, { recursive: true });
 syncTools(ws);
 linkModules(ws);

package/index.html

@@ -245,6 +245,8 @@ button.go:focus-visible, button.quiet:focus-visible, .copy:focus-visible { outli
 }
 .sug-opt:hover { border-color:var(--accent); color:var(--accent); }
 .sug-opt:focus-visible { outline:2px solid var(--accent); outline-offset:2px; }
+.scenario .ed-role { font-size:11.5px; font-weight:700; color:var(--accent); letter-spacing:.03em; margin:2px 0 8px 8px; }
+.scenario .ed-cap { font-size:11.5px; font-weight:600; color:var(--ink-2); margin:8px 0 2px 8px; }
 .scenario .ed-sub { font-size:13.5px; color:var(--ink-2); line-height:1.5; margin-top:2px; }
 .scenario textarea::placeholder { color:#9a8b7a; }
 
@@ -1080,13 +1082,50 @@ function renderPlan(p) {
     return row;
   };
 
+  // 리서처가 쓰는 키 이름이 브리프마다 다르다 (headline/sub, subcopy, core_message,
+  // card_items …). 키를 고정해 찾으면 실제 카피가 화면에 안 뜨고 수정도 못 한다.
+  // 그래서 **그 슬라이드가 실제로 가진 글자 필드**를 그대로 그린다.
+  const SKIP = new Set(['n', 'role', 'source', 'notes', 'type']);
+  const LABEL = {
+    headline: '헤드라인', core_message: '핵심 문구', title: '제목', hook: '훅',
+    sub: '설명', subcopy: '설명', label: '라벨',
+    body_points: '본문 포인트 (한 줄에 하나)', card_items: '카드 항목 (한 줄에 하나)',
+    cta: 'CTA', verse_text: '인용문', verse_ref: '출처',
+  };
+  const isBig = (k) => /headline|core_message|title|hook/i.test(k);
+
   p.slides.forEach((s) => {
     const li = document.createElement('li');
-    const head = field(s.headline || s.role || '', 'ed-head', '헤드라인', 'headline', s.n);
-    li.append(head, suggestRow(head, s.n, 'headline'));
-    // sub 가 없는 브리프도 있다. 그래도 칸은 준다 — 넣고 싶을 수 있다.
-    const sub = field(s.sub ?? s.subcopy ?? '', 'ed-sub', '설명 (비워도 됩니다)', 'sub', s.n);
-    li.append(sub, suggestRow(sub, s.n, 'sub'));
+
+    const keys = Object.keys(s).filter((k) => !SKIP.has(k)
+      && (typeof s[k] === 'string' || (Array.isArray(s[k]) && s[k].every((v) => typeof v === 'string'))));
+
+    // 글자 필드가 하나도 없으면 최소한 역할이라도 보여준다 (빈 카드 방지)
+    if (!keys.length) {
+      const only = document.createElement('div');
+      only.className = 'fine';
+      only.textContent = `${s.role || ''} — 수정할 문구가 없습니다`;
+      li.append(only);
+      host.append(li);
+      return;
+    }
+
+    if (s.role) {
+      const role = document.createElement('div');
+      role.className = 'ed-role';
+      role.textContent = s.role;
+      li.append(role);
+    }
+
+    for (const k of keys) {
+      const cap = document.createElement('label');
+      cap.className = 'ed-cap';
+      cap.textContent = LABEL[k] || k;
+      li.append(cap);
+      const val = Array.isArray(s[k]) ? s[k].join('\n') : s[k];
+      const box = field(val, isBig(k) ? 'ed-head' : 'ed-sub', '', k, s.n);
+      li.append(box, suggestRow(box, s.n, k));
+    }
     host.append(li);
   });
 
@@ -1101,8 +1140,9 @@ async function savePlanEdits() {
   const byN = new Map();
   $('scenario').querySelectorAll('textarea').forEach((t) => {
     const n = Number(t.dataset.n);
-    if (!byN.has(n)) byN.set(n, { n });
-    byN.get(n)[t.dataset.key] = t.value.trim();
+    if (!byN.has(n)) byN.set(n, { n, fields: {} });
+    // 키 이름은 브리프에서 온 그대로 되돌려준다. 서버가 원래 있던 키에만 되쓴다.
+    byN.get(n).fields[t.dataset.key] = t.value.trim();
   });
   const res = await fetch('/plan', {
     method: 'POST',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sns-auto-builder",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "인스타 카드뉴스 자동 제작 빌더. Claude Code + ChatGPT 웹을 그대로 써서 API 키 없이 돌아갑니다.",
   "type": "module",
   "bin": {

package/scripts/chatgpt-image-gen.js

@@ -117,7 +117,31 @@ async function spawnDetachedChrome(exe) {
     } catch { /* 아직 안 떴다 */ }
     await new Promise((r) => setTimeout(r, 500));
   }
-  throw new Error(`Chrome 이 30초 안에 ${DEBUG_URL} 를 열지 못했습니다`);
+
+  // Chrome 은 user-data-dir 하나당 인스턴스 하나만 띄운다. 이미 그 프로필로 떠 있는 창이
+  // 있으면 우리가 포트를 붙여 실행해도 **기존 창에 넘기고 종료**한다 → 포트가 안 열린다.
+  // 이게 압도적으로 흔한 원인이라, 추측이 아니라 실제로 확인해서 알려준다.
+  const blocker = await profileHolders();
+  if (blocker.length) {
+    throw new Error(
+      `이 프로필로 Chrome 이 이미 떠 있어서 디버깅 포트를 열 수 없습니다 (pid ${blocker.join(', ')}).\n`
+      + `        그 Chrome 창을 모두 닫고 다시 실행하세요.\n`
+      + `        프로필: ${PROFILE}`);
+  }
+  throw new Error(`Chrome 이 30초 안에 ${DEBUG_URL} 를 열지 못했습니다 (프로필: ${PROFILE})`);
+}
+
+// 이 프로필을 붙잡고 있는 chrome.exe 를 찾는다. 원인을 눈으로 확인시켜 주기 위한 것.
+async function profileHolders() {
+  if (process.platform !== 'win32') return [];
+  try {
+    const { execFileSync } = await import('node:child_process');
+    const out = execFileSync('powershell', ['-NoProfile', '-Command',
+      `Get-CimInstance Win32_Process -Filter "Name='chrome.exe'" | `
+      + `Where-Object { $_.CommandLine -like '*${PROFILE.replace(/\\/g, '\\\\')}*' } | `
+      + `Select-Object -ExpandProperty ProcessId`], { encoding: 'utf8', timeout: 15_000 });
+    return out.split(/\r?\n/).map((s) => s.trim()).filter(Boolean).slice(0, 8);
+  } catch { return []; }
 }
 
 async function waitForComposer(page) {

package/server.mjs

@@ -774,13 +774,20 @@ const server = createServer(async (req, res) => {
       let changed = 0;
       for (const slide of brief.slides || []) {
         const edit = byN.get(Number(slide.n));
-        if (!edit) continue;
-        // 리서처가 쓰는 키 이름이 브리프마다 다르다(sub / subcopy). 있는 키만 건드린다.
-        for (const [uiKey, val] of [['headline', edit.headline], ['sub', edit.sub]]) {
-          if (val == null) continue;
-          const key = uiKey === 'sub' && slide.subcopy !== undefined ? 'subcopy' : uiKey;
-          if (slide[key] === undefined || String(slide[key]) === String(val)) continue;
-          slide[key] = String(val).slice(0, 500);
+        if (!edit?.fields) continue;
+        // 키 이름을 고정하지 않는다. 리서처가 브리프마다 다르게 쓴다
+        // (headline/sub, subcopy, core_message, card_items …).
+        // **원래 있던 키에만** 되쓴다 — 없는 키를 새로 만들면 스키마가 오염된다.
+        for (const [key, val] of Object.entries(edit.fields)) {
+          if (!(key in slide) || val == null) continue;
+          if (Array.isArray(slide[key])) {
+            const arr = String(val).split(/\r?\n/).map((x) => x.trim()).filter(Boolean);
+            if (JSON.stringify(arr) === JSON.stringify(slide[key])) continue;
+            slide[key] = arr;
+          } else {
+            if (typeof slide[key] !== 'string' || slide[key] === String(val)) continue;
+            slide[key] = String(val).slice(0, 1000);
+          }
           changed++;
         }
       }
@@ -798,7 +805,13 @@ const server = createServer(async (req, res) => {
       }
       const brief = JSON.parse(readFileSync(join(abs, 'brief.json'), 'utf8'));
       const slide = (brief.slides || []).find((s) => Number(s.n) === Number(n)) || {};
-      const isHead = key === 'headline';
+      // 어느 칸을 고치는지는 키 이름으로 판단한다 (headline/core_message = 큰 문구).
+      const isHead = /headline|core_message|title|hook/i.test(String(key || ''));
+      // 같은 장의 나머지 문구를 맥락으로 준다 — 키 이름이 뭐든.
+      const context = Object.entries(slide)
+        .filter(([k, v]) => k !== key && k !== 'n' && (typeof v === 'string' || Array.isArray(v)))
+        .map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(' / ') : v}`)
+        .join('\n');
       ensureBrandFacts();
       const banned = JSON.parse(read('banned-words.json'));
       const bannedList = Object.entries(banned).filter(([k]) => !k.startsWith('_'))
@@ -814,7 +827,8 @@ ${bannedList}
 인스타 카드뉴스 **${n}번째 장**(${slide.role || '본문'})의 ${isHead ? '헤드라인' : '설명 문구'}을 다시 써라.
 
 전체 주제: ${brief.topic || ''}
-이 장의 ${isHead ? '설명' : '헤드라인'}: ${(isHead ? (slide.sub ?? slide.subcopy) : slide.headline) || '(없음)'}
+이 장의 다른 문구:
+${context || '(없음)'}
 현재 문구: ${String(text || '(비어 있음)')}
 
 **대안 3개**를 제안해라. 뜻은 유지하되 표현을 바꾼다.