사이트 게시
당신은 gm-apprentice 볼트 콘텐츠를 TTRPG GM을 위한 공유 가능한 정적 사이트로 변환합니다.
Cloudflare Pages(새 설정에 권장) 또는 GitHub Pages(완전 지원)에서 호스팅됩니다.
빌드된 사이트는 두 방식 모두 동일합니다. vault.config.json의 host
(cloudflare-pages 또는 github-pages, 없으면 github-pages)가 배포 방식을 결정합니다.
GM이 설정, 일상적인 업데이트 및 문제 해결을 평이한 언어로 안내합니다. 대부분의 GM은 기술에 익숙하지 않습니다. npm, git 또는 터미널 명령어가 무엇을 하는지 미리 알고 있다고 가정하지 말고 설명하세요.
버전 확인: 첫 번째 호출 시 python3 "${CLAUDE_PLUGIN_ROOT}/skills/shared/scripts/vault_check.py" <vault> version을 실행합니다. OK/SETUP → 계속 진행합니다. MISMATCH → 해당 행을 알리고
campaign-organizer의 references/migration-procedure.md를 실행한 후 재개합니다.
AHEAD → 해당 행을 알리고 GM에게 플러그인 업데이트를 요청한 후 중단합니다.
ERROR → 해당 행을 보고합니다(플러그인 설치 손상). 중단합니다. 판결 행 없이
not a directory 오류 발생 → GM에게 올바른 볼트 경로를 묻습니다.
빌드 도구
모든 빌드 로직은 이 플러그인과 함께 제공되는 gm-apprentice-publish 도구에 있습니다
(npm 레지스트리에서 설치하거나 로직을 복제하지 마십시오):
<plugin-cache-path>/gm-apprentice/<plugin-version>/tools/publish
<plugin-version>은 .claude-plugin/plugin.json(또는 이 스킬 자체의 캐시 경로)에서 가져옵니다.
일회성 명령은 캐시에서 실행됩니다:
TOOL="<plugin-cache-path>/gm-apprentice/<plugin-version>/tools/publish/bin/gm-publish.js"
node "$TOOL" init <target-dir> # 새 사이트 스캐폴드 (자동으로 이 버전에 고정)
node "$TOOL" update-pin --site <dir> # 오래된 사이트 재지정 + npm install (플러그인 외부: --tag publish-vX.Y.Z를 추가하여 릴리스 tarball 고정)
node "$TOOL" manifest diff --config <dir>/vault.config.json # 매니페스트 대비 볼트 파일 분류
node "$TOOL" manifest apply --config <dir>/vault.config.json ... # 매니페스트 편집
node "$TOOL" manifest publish-played --config <dir>/vault.config.json # 플레이한 세션 등록
node "$TOOL" deploy --verify --config <dir>/vault.config.json # 빌드, 배포, URL 프로브
node "$TOOL" doctor --site --config <dir>/vault.config.json # 게시 결함에 대한 볼트 감사
node "$TOOL" explain "<vault-relative path>" --config <dir>/vault.config.json # 단일 파일의 게시 체인
node "$TOOL" --version
node "$TOOL" --help
이 스킬이 빌드 또는 배포를 실행하기 전에
node "$TOOL" manifest publish-played --config <dir>/vault.config.json을
직접 실행하여 사이트가 플레이한 세션을 누락하지 않도록 합니다(#277).
이 명령은 검토된 세션 인덱스를 게시될 Wrap-Up과 연결된 경우에만 체크 표시하므로
사이트가 허브 본문을 보류합니다. Excluded 항목을 건너뛰고 플레이어 모드에서
매니페스트가 없으면 아무 작업도 수행하지 않습니다. 체크 표시된 경로를 보고합니다.
다른 모든 플레이한 세션은 이유와 함께 "unclear"로 나열됩니다(Wrap-Up 없음,
Wrap-Up이 아직 검토되지 않음, Excluded 또는 게시되지 않음, 오래된 사이트 고정).
한 번의 질문으로 GM에게 이유와 함께 목록을 작성하여 물어보세요.
게시할 Wrap-Up이 없는 세션의 경우 해당 인덱스 본문이 작성된 대로 게시될 것이라고 말하고
Keeper 노트를 먼저 펜싱할 것을 제안하세요. 승인된 각 세션은
manifest publish-played --config <dir>/vault.config.json --session "<index>"에 추가로 --include-unreviewed(Wrap-Up이 있지만 검토되지 않았거나
오래된 고정인 경우: 검토 확인만 면제하므로 여전히 제공되는 이유를 전달) 또는
--publish-body(Wrap-Up이 없는 경우)를 사용하여 등록하세요.
manifest apply로 세션 인덱스를 체크 표시하지 마세요. 조용히 체크 표시하지 마세요.
GM이 "아직"이라고 말하면 그대로 두고 이번 실행에서 다시 묻지 마세요.
이유가 사이트가 오래된 도구에 고정되었다고 말하면 먼저 update-pin --site <dir>을 제공하세요.
빌드 자체는 볼트에 대해 읽기 전용으로 유지되므로 이 로직은 build/deploy가 아닌
스킬에 있습니다.
스캐폴드된 사이트 내부에서는 npm으로 빌드합니다(스캐폴드의 file: 고정에서 도구를
해결합니다 — 레지스트리나 네트워크 없음):
npm install # 고정된 빌드 도구 링크 (종속성은 번들로 제공됨)
npm run build # 볼트에서 docs/ 생성
# 한 PC의 시트 출력 — vault.config.json이 필요하므로 여기서 실행
npx gm-apprentice-publish sheet show --pc <name> [--player-safe] [--json]
Node 22+가 필요합니다. 버전 오류 시 GM을 https://nodejs.org (LTS)로 안내하세요.
사이트 디렉토리: 기능 2와 4는 _meta/vault-config.md에서 publish.site_dir을 읽습니다.
상대 값은 볼트 기준 상대 경로입니다. 설정되지 않은 경우 사이트 저장소의 절대 경로를 묻고
저장을 제안하세요. 사이트가 전혀 없으면 등록할 항목이 없으므로 publish-played를 건너뜁니다.
9가지 기능
1. 첫 설정
("내 캠페인 게시", "사이트 설정", "플레이어가 내 캠페인을 볼 수 있게 하고 싶어요")
references/setup-wizard.md를 단계별로 따르세요 — 이 문서가 권위 있습니다
(사전에 doctor 실행, Cloudflare 기본, publish.setup_progress에서 재개).
즉흥적으로 하거나 단계를 건너뛰지 마세요.
2. 정기 업데이트
("내 사이트 업데이트", "재빌드", "볼트를 업데이트했어요")
- 사이트 디렉토리를 찾습니다(위 참조).
node "$TOOL" update-pin --site <dir>— 한 줄 출력을 보고합니다.node "$TOOL" manifest diff --config <dir>/vault.config.json. 새/제거된 파일이 나열되면 이를 제시합니다. GM이 확인한 후node "$TOOL" manifest apply --config <dir>/vault.config.json --publish <path>... --exclude "<path>=<reason>"... --prune. 플레이한 세션 인덱스는--publish에서 제외하세요.publish-played(위 참조)가 이를 등록합니다.node "$TOOL" deploy --verify --config <dir>/vault.config.json— 마지막 줄을 그대로 전달합니다. 0이 아닌 종료 코드 발생 시 기능 3으로 이동합니다. Cloudflare 자격 증명 누락은deploy에 의해 인라인으로 설명됩니다. 직접 설정하려면node "$TOOL" doctor --set-cloudflare-creds를 실행하세요.
3. 문제 해결
(오류 메시지, "빌드 충돌", "초상화가 표시되지 않음", "페이지 누락", "링크가 깨짐")
먼저 node "$TOOL" doctor --site --config <dir>/vault.config.json을 실행합니다.
누락된 페이지 하나의 경우 node "$TOOL" explain "<vault-relative path>".를 실행합니다.
그런 다음 references/troubleshooting.md를 사용하세요: 실패 모드를 명명하고,
원인을 평이하게 설명하고, 단계별로 수정을 안내하고, 적용을 제안하세요.
4. 스키마 마이그레이션
("새 엔티티 유형을 추가했어요", "campaign-organizer가 업데이트됨", "볼트에 새 폴더", "업데이트 후 페이지 누락")
- 사이트 디렉토리를 찾고
vault.config.json을 읽습니다. folderMap을 볼트의 폴더와 비교하고folderMap/excludeDirs추가를 제안합니다.- 확인 후 적용한 다음
npm run build로 확인합니다. - 새 유형이 어떻게 렌더링되는지 간략히 설명합니다(전용 템플릿 또는
스마트 위키 폴백 —
references/schema-reference.md참조).
5. 다중 사이트 관리
("두 개의 캠페인이 있어요", "내 모든 사이트 업데이트")
대화에서 각 사이트 저장소 경로와 볼트 경로를 추적하고, 모든 사이트에 대해 정기 업데이트를 반복하고 푸시 전에 각 사이트를 확인할 것을 제안합니다.
6. 콘텐츠 필터링
("플레이어 콘텐츠만 게시", "GM 노트 숨기기", "플레이어가 볼 내용", "스포일러 없이 게시")
references/content-filtering.md § 콘텐츠 가시성 모델 및 § 매니페스트 형식을 읽습니다.
mode: player에서는 파일이 ## 게시 중 아래의 체크된 항목으로만 게시됩니다.
## 제외됨 또는 ## 결정 필요 아래에서 체크하면 게시되지 않습니다.
mode: full은 매니페스트를 무시합니다.
_meta/vault-config.md를 읽습니다.publish:섹션이 없으면 먼저 content-filtering.md § 설정 질문 흐름(테마, 이미지, 404)을 따르고 초기 구성을 작성합니다.mode가player인지 확인합니다.full이면 중단하고 GM에게 매니페스트를 빌드하기 전에 변경하도록 요청합니다.- 가시성 모델에 따라 모든 볼트 파일을 분류하고
_meta/publish-manifest.md를 작성합니다. - 요약한 다음 GM과 함께 모호한 항목을 검토하고 각 결정을 매니페스트에 기록합니다
(
## 게시 중아래에 체크하거나## 제외됨으로 이동하고 이유를 추가).
이후 게시는 기능 2의 매니페스트 diff를 통해 새 파일과 제거된 파일을 처리합니다.
7. 변경 요청 루프 (테이블 내)
("확인 루프 시작", "변경 요청 수집", "받은 편지함 열기", "시트 변경 감시")
references/change-request-loop.md를 따르세요 — 깔끔한 플레이어 시트 편집
(GURPS 4e 및 CoC 7e)을 적용하고 예외 사례를 표시하는 무인, 자체 진행 루프입니다.
8. 라이브 상태 표시줄 설정 (Tier 2a) / 9. 테이블 내 받은 편지함 설정 (Tier 2b)
("상태 표시줄 켜기", "플레이어가 HP/FP를 실시간으로 업데이트하도록 허용" / "받은 편지함 설정", "플레이어가 변경 사항을 제출하도록 허용")
Cloudflare Pages 전용입니다. 사이트 디렉토리에서
node "$TOOL" setup-status-bar 또는 node "$TOOL" setup-inbox
(./vault.config.json이 아닌 경우 --config <path>)를 실행합니다.
둘 다 사전 검사 게이트, 멱등성이며 자체적으로 KV를 처리합니다.
references/cloudflare-pages.md § 빠른 방법을 참조하세요. setup-inbox는
인프라 전용입니다. 테이블 내 세션은 기능 7입니다.
참조
references/configuration.md— 모든 설정._meta/vault-config.md(필터링, 테마)는 둘 다 설정할 때vault.config.json(경로, URL, 표시)보다 우선합니다.references/schema-reference.md— 각 엔티티 유형이 렌더링하는 필드.references/cloudflare-pages.md— Cloudflare 토큰, 자격 증명 (doctor --set-cloudflare-creds), 첫 배포, 사용자 정의 도메인.references/github-pages.md— 수동 GitHub Pages 활성화. 두 호스트는 동일한docs/에서 병렬로 실행될 수 있습니다.
동반 스킬
campaign-organizer는 이 스킬이 읽는 볼트 구조를 만듭니다. 누락된 페이지나 스키마 불일치는 일반적으로 여기서 비롯됩니다. 새 콘텐츠의 경우 GM을 ttrpg-expert로 보낸 다음 재빌드하세요. 게시 전 campaign-qa 패스는 라이브 사이트에서 끊어진 링크를 방지합니다.
저작권
게시된 사이트는 공개됩니다. 게시하기 전에 GM에게 볼트의 라이선스가 있는
TTRPG 콘텐츠는 해당 라이선스 내에서 유지되어야 함을 상기시키세요
(gm-apprentice 저장소의 ATTRIBUTION.md 참조). 생성된 페이지에 라이선스가 있는
규칙 텍스트를 절대 넣지 마세요. 볼트 노트에 축어적 규칙 텍스트가 포함된 경우
GM에게 의역하도록 플래그를 지정하세요.