bookforge

name	bookforge
description	Generate commercial-book-quality Korean ebook PDFs from a topic or a finished manuscript. Six design styles (practical, insight, academic, essay, business, magazine) with real book anatomy — cover, TOC with page numbers, chapter openers, running heads, QC gates. Use when the user wants an ebook, a PDF book or report, book typesetting, or mentions 전자책, PDF 책, 책 조판, 북포지, bookforge.

bookforge — 상업도서급 전자책 PDF 공장

주제 한 줄 또는 완성 원고를 받아, 실제 단행본 해부 구조(표지·차례·장 도비라·러닝 시스템·판권면)를 갖춘 PDF를 만든다. 콘텐츠는 마크다운으로만 쓰고, 조판은 스타일 팩과 스크립트가 전담한다. 품질은 QC 게이트가 물리적으로 강제한다 — 게이트를 통과하지 못한 PDF는 final/에 존재할 수 없다.

이 파일의 경로가 <SKILL>이다. 모든 명령은 <SKILL>을 이 스킬 폴더의 절대 경로로 치환해 실행한다.

실행 전 점검

typst --version        # 0.14.x 필요 (Typst 트랙 — 내장 폰트가 버전에 묶이므로 0.14 계열 고정)
python3 -c "import pymupdf, markdown_it"   # PyMuPDF + markdown-it-py (QC·변환)
# HTML 트랙(insight·magazine) + 도해 프리렌더: 전역 playwright + Chromium 실물이 전제다.
# (스크립트가 `npm root -g`에서 playwright를 해석한다 — 프로젝트 로컬 설치로는 안 잡힌다)
npm root -g >/dev/null                                       # npm 자체
node -e "require(require('child_process').execSync('npm root -g').toString().trim()+'/playwright')" \
  || npm i -g playwright                                     # 전역 playwright
npx playwright install chromium                              # Chromium 바이너리 (없으면 pass1에서 죽는다)
# 도해(diagrams/)를 쓰는 책: 렌더러는 커밋된 벤더 번들(vendor/antv-ssr.bundle.mjs)을
# 쓴다 — npm ci 불필요, 레지스트리 소멸에도 재현. 번들 유실 시에만 복구:
ls <SKILL>/vendor/antv-ssr.bundle.mjs \
  || (cd <SKILL> && npm ci && node vendor/build-bundle.mjs)

없는 것이 있으면 사용자에게 설치를 요청하고 중단한다. HTML 트랙·도해 없이 Typst 4스타일만 쓸 거라면 playwright·Chromium·npm ci는 생략 가능.

파이프라인 (체크리스트를 복사해 진행하며 체크)

[ ] P0 계약: 모드·스타일·분량 확정 → 책 프로젝트 스캐폴드
[ ] P1 콘텐츠: outline.json + chapters/ch-NN.md 완성
[ ] P1.5 도해(선택): diagrams/fig-NN.json 작성 → build.py가 자동 프리렌더 (계약: references/diagrams.md)
[ ] P2-3 빌드: build.py → draft/book.pdf
[ ] P4 게이트: qc_gate.py PASS → final/ 생성 확인
[ ] P5 시각 검수: contact_sheet.py → 표지·차례·도비라·본문 4면 이상 눈으로 확인

P0 — 계약

1. 모드 감지: 사용자가 원고 파일(md/txt/docx)을 줬으면 manuscript 모드 → modes/manuscript.md를 읽고 따른다. 주제·아이디어만 줬으면 topic 모드 → modes/topic.md를 읽고 따른다.
2. 스타일 선택: 사용자가 지정하지 않았으면 아래 표에서 내용 성격에 맞는 것을 골라 진행한다(질문하지 않는다).

스타일	성격	판형	엔진
practical	IT·실용 활용서, 단계별 가이드, 용어집	153×225	typst
insight	기술 동향·인사이트 리포트, 데이터 브리핑	182×257	html
academic	학술 단행본, 연구 개론, 이론서	153×225	typst
essay	산문집, 회고, 문학적 글	128×188	typst
business	컨설팅 리포트, 시장 분석, 전략 백서	200×280	typst
magazine	트렌드북, 큐레이션, 룩북	200×265	html

3. 스캐폴드 (책 프로젝트는 스킬 폴더 밖 작업 디렉토리에 만든다):

python3 <SKILL>/scripts/scaffold.py <book_dir> --style practical \
  --title "제목" --subtitle "부제" --length short --author "저자" --date "2026-08"

--length: short/standard/long — 쪽수 범위의 정본은 각 스타일 tokens.json의 length_pages(short는 스타일별 22~70쪽 대역, INV-1에 따라 산출물 쪽수는 WARN만). --brand "#hex"로 브랜드색 교체, --images vector|generated|none으로 이미지 정책(벡터만·생성 아트 포함·없음) 지정.

P1 — 콘텐츠 계약

outline.json의 각 장에 file·title·summary(도비라에 실리는 1~2문장)를 채우고, chapters/ch-NN.md를 아래 문법만으로 쓴다:

• # 장제목(파일당 1개, outline의 title과 일치) / ## 절 / ### 소제목
• 문단, **볼드**, 리스트, > 인용, GFM 표, ``` 코드블록
• 이미지: ![캡션](../assets/파일.png "출처: 어디") — 파일을 <book_dir>/assets/에 먼저 넣고, 반드시 ../assets/ 경로 + 이미지 단독 문단으로 쓴다(텍스트가 섞이면 조판에서 조용히 증발)
• 벡터 도해 2트랙: ① 요점 시각화는 diagrams/fig-NN.json(AntV DSL 사이드카) ② 기술도해(시퀀스·상태머신·ER·스위밍레인·간트 등)는 SVG를 직접 그려 diagrams/fig-NN.svg + 사이드카 {"kind":"authored"}. 빌드가 정규화해 assets/fig-NN.svg로 산출. 본문 참조는 ![캡션](../assets/fig-NN.svg "출처: …"). 작성 계약·타입 라우팅·커넥터 규칙·복잡도 예산은 references/diagrams.md가 정본
• 콜아웃(줄 단위 디렉티브):

::: tip 제목
내용 (stat은 첫 줄=수치, 둘째 줄=설명)
:::

종류 info|tip|warn|quote|stat|pull(pull은 magazine 풀퀘트 — 본문에 실재하는 문장만, 없는 인용은 G10 하드 실패).

• 표 캡션: 표 바로 앞 문단에 [표] 제목 | 자료: 출처 한 줄 — 이 줄을 준 표만 번호 라벨이 붙는다. 캡션 없는 표는 라벨 없이 렌더된다(자동 필러 캡션은 존재하지 않는다).
• stat의 수치는 같은 장 본문에 실재해야 한다(G10) — 박스에만 있는 숫자는 날조로 판정된다.

표지·도비라용 생성 아트를 쓸 경우 references/art-policy.md를 읽고 따른다(무텍스트 원칙).

완료 기준: outline의 모든 장 파일이 존재하고, 각 파일 첫 줄이 # {title}이며, 분량 프리셋에 맞는 총 글자수(short 기준 본문 1.0만2.1만 자 = 장 57개 × 2,000~3,000자 — modes/topic.md와 동일 기준)를 갖춘다. 각 장의 toc_line(목차 전용 완결 카피 한 줄)을 채운다 — 없으면 summary 앞 40자가 잘려 실린다.

P2-4 — 빌드와 게이트

python3 <SKILL>/scripts/build.py <book_dir>          # → draft/book.pdf
python3 <SKILL>/scripts/qc_gate.py <book_dir>        # PASS 시에만 final/<slug>.pdf 생성

게이트: G10 인용·수치 실재(렌더 전) / G0 도해 SVG 소스(렌더 전 — foreignObject·외부참조·단독문단·아이콘 탈락) / G1 렌더·판형(tokens trim_mm 대조)·본문 급수(tokens body_pt ±0.3pt — 전역 축소 차단)·분량범위(WARN — --strict-pages만 HARD) / G2 폰트 임베드+Type3 0 / G3 면 기하 3축(OVERFLOW 재단 밖 bbox 0 · COLLIDE 텍스트 라인 교차 0 · FIT 앞부속 텍스트가 tokens front_frame_mm 안) / G4 목차·북마크 정합 / G7 밀도(백면·꼬리 채움·판면 드리프트) / G8 공기 채움 / G9 제목 고립·widow / G11 사유 코드 무결성 / G12 필러 백면 / G13 도해 라벨 PDF 실재 / G17 도해 면 정합(figure가 한 면 안 — 면 분단·판면 초과·diagram.maxHeightMm 대조) / G14 목차·디자인 정합(인쇄 목차 쪽번호↔폴리오·목차↔도비라 색 계열·텍스트 대비 하한) / G16-TOKENS 스타일 팩 토큰 계약 3축(SYNC 색·수치 계약 정합 — palette_roles·front_frame_mm 선언값 타당성 포함 / CONTRAST 선언 페어의 WCAG 대비 / BRAND 브랜드 입력 사전 검증) / G16-LINT contrast_contract ↔ theme.css·렌더 DOM 실물 대조(html 엔진 한정 — pt 정합·값 커버리지는 HARD, 완전성은 WARN). 기준 수치와 대응법은 references/pagination.md가 정본이다.

실패 시 gate-report.json의 원인 항목만 고치고 재실행한다. 예외 — G16-TOKENS: 이 축만 build.py가 렌더 전에 그 자리에서 중단시키므로 그 시점엔 gate-report.json이 아직 없다(있다면 이전 실행의 낡은 파일이다). stderr에 찍힌 축·사유를 읽고 styles/<style>/tokens.json을 고칠 것 — 게이트 리포트를 찾지 말 것. 금지 대응: 분량 미달을 부록·용어집 추가로 메우기, 절별 강제 개면, 빈 줄·행간 확대로 면 채우기 — 전부 게이트가 다시 잡는다. 올바른 대응: G7 꼬리 미달은 python3 <SKILL>/scripts/refit.py <book_dir>(자간 미세조정 자동 탐색) → 해 없으면 문단 1~2개 국소 증감 또는 pageroles.json 사유 코드(의도된 여백 선언, G11이 진위 검증). 같은 게이트 3회 연속 실패면 원인을 사용자에게 보고한다.

P5 — 시각 검수 (필수, 생략 금지)

python3 <SKILL>/scripts/contact_sheet.py <book_dir>/final/*.pdf <book_dir>/qc --dpi 90 --pages 1,2,3,4,5
# 게이트 실패를 진단할 때는 final/ 대신 draft/book.pdf 를 같은 방식으로 렌더해 본다

표지·차례·도비라·본문 펼침면 PNG를 직접 열어 보고 판단한다: 글자 겹침 없음, 목차 쪽번호=실제 쪽, 도비라 스타일 성립, 본문 여백 리듬 정상. 이상이 있으면 콘텐츠(md)나 book.json을 고쳐 P2-4를 재실행한다. 파일이 생성되었다는 것은 완료가 아니다 — 눈으로 본 것만 완료다.

더 읽을 것 (필요할 때만)

• modes/topic.md — 주제만 받았을 때: 조사→목차→집필 절차
• modes/manuscript.md — 원고를 받았을 때: 인제스트·장 분할 절차
• references/pagination.md — 배치 규칙서(정본): 채움/비움의 사유, 레버 사다리, 밀도 게이트 수치, 사유 코드
• references/art-policy.md — 생성 아트(표지·도비라) 규칙: 무텍스트 원칙, 스타일별 사용처
• references/orchestration.md — (Claude Code 전용, 선택) 장별 집필을 codex 스웜·서브에이전트로 병렬화하는 법
• references/extending.md — 새 스타일 팩 추가·테마 수정 가이드
• styles/<이름>/STYLE.md — 각 스타일의 전체 디자인 규칙서(집필 시 톤·구성 참고)