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