docs/contract/beatcard_guide.md

# 비트카드 작성 가이드 — 화면이 되는 글

> 대상: 비트카드 MD 작성(대표님) · E07~E15 집필 참고.
> 배경: 엔진은 카드를 "화면"으로 만든다. 카드의 글자 수·블록 구성이 그대로
> 독자의 페이지 경험이 된다. 검증은 `python -m engine.schemas.validate content/`가
> 경고 리포트로 알려준다 (실패 아님 — 판단은 대표님 몫).

## 1. 카드 한 장 = 의미 있는 화면 하나

- **권장 지문 분량: 카드당 200~700자.**
  - 200자 미만 → 화면이 빈약해진다 (validate가 경고). 예: E05-05(96자), E06-10C(154자)
  - 700자 초과 → 엔진이 알아서 나누지만, 700자 안쪽이면 의도한 단위로 보여진다
- 선택지·채팅(앵커)·연출 컷 카드는 **항상 단독 화면**이 된다 — 이 카드들이 특히
  분량·구성의 영향을 크게 받는다

## 2. 인터랙션 카드의 3막 패턴 (구조가 연출이 된다)

채팅·선택지 카드는 대개 이런 구조이고, 엔진이 이를 화면 연출로 해석한다:

```
[리드인]  짧은 도입 산문 (140자 이하)   → 초상 화면 상단에 얹힘
[앵커]    캐릭터 발화 (LLM 변주 기준)    → 초상 스테이지의 대사
[여파]    반응 산문 + 선택지            → 다음 화면, 선택지와 함께
```

- **발화 직전의 140자 이하 산문은 자동으로 리드인**으로 처리된다
  (엔진 유도 규칙 — YAML `role: lead_in`으로 명시 지정도 가능)
- 리드인이 140자를 넘으면 독립 문단으로 취급된다 — 도입을 이미지에 얹히게
  하려면 짧게, 별도 문단으로 읽히게 하려면 길게

## 3. 화자 표기

- 지문 속 인물 대사는 `인물명: "대사"` 형식이 아닌 **발화 블록**(변환기가
  character_dialogue로 인식하는 형식)으로 — 그래야 화자명·초상 연출이 붙는다
- 초상이 있는 인물: 카르밀라·아버지·마드모아젤·마담 (추가 시 개발팀에 전달)

## 4. 장소 태그가 배경을 결정한다

- `#장소/X` 태그의 첫 항목이 그 카드의 배경 이미지를 고른다
  (현재 매핑: 침실·만찬홀·숲길·해자·폐허·예배당 — 정원·화랑·서재는 배경 이미지 대기 중)
- 장소가 바뀌는 카드에는 태그를 꼭 갱신할 것 — 없으면 직전 배경이 이어진다