medsci-skills 4.1.0

package/skills/publish-skill/scripts/audit_skill.sh

@@ -0,0 +1,278 @@
+#!/usr/bin/env bash
+# audit_skill.sh -- PII / hardcoded-path / metadata scanner for a single
+# Claude Code skill. Standalone wrapper that mirrors the per-skill checks
+# in `medsci-skills/scripts/validate_skills.sh` so a personal skill can be
+# audited the same way before being moved into a public repo.
+#
+# Usage:
+#   audit_skill.sh <skill_directory> [extra_patterns]
+#
+# Arguments:
+#   skill_directory  Path to a single skill (must contain SKILL.md).
+#   extra_patterns   Optional `grep -E` alternation pattern of names /
+#                    institutions / collaborator handles to add. Example:
+#                      "jane doe|MIT Medical|@gmail\.com"
+#
+# Exit codes:
+#   0  Clean -- no findings
+#   1  Findings detected -- review required before publication
+#   2  Usage error
+#
+# Coverage parity with medsci-skills/scripts/validate_skills.sh:
+#   rule 6  Personal precedent (text)            yes
+#   rule 7  Absolute path leak                   yes
+#   rule 7b Real personal email                  yes
+#   rule 7c Author{Year}_ filename pattern       yes
+#   rule 8  Blockquote dated precedent           yes
+#   rule 10 Binary EXIF metadata (DOCX/PDF/PNG)  yes (skipped silently if
+#                                                exiftool not installed)
+#
+# False-positive guard: text scans use `grep --binary-files=without-match`
+# so compiled `.pyc`, raster `.png` byte-stream collisions, and `git` pack
+# files do not count as matches. `__pycache__/` is also explicitly skipped.
+
+set -u
+
+if [ $# -lt 1 ] || [ $# -gt 2 ]; then
+    cat >&2 <<USAGE
+Usage: audit_skill.sh <skill_directory> [extra_patterns]
+
+Examples:
+  audit_skill.sh ~/.claude/skills/my-skill
+  audit_skill.sh ./skills/my-skill "jane doe|Stanford|@gmail\.com"
+USAGE
+    exit 2
+fi
+
+SKILL_DIR="$1"
+EXTRA_PATTERNS="${2:-}"
+
+if [ ! -d "$SKILL_DIR" ]; then
+    echo "Error: directory not found: $SKILL_DIR" >&2
+    exit 2
+fi
+
+# Resolve to absolute path so the report shows useful locations.
+SKILL_DIR="$(cd "$SKILL_DIR" && pwd)"
+
+FOUND=0
+TOTAL=0
+
+# Color output only when stdout is a TTY.
+if [ -t 1 ]; then
+    RED=$'\033[0;31m'
+    GRN=$'\033[0;32m'
+    YEL=$'\033[1;33m'
+    NC=$'\033[0m'
+else
+    RED=""; GRN=""; YEL=""; NC=""
+fi
+
+# Files to exclude from text scans. Binary scan handles its own subset.
+TEXT_EXCLUDES=(
+    --exclude-dir=.git
+    --exclude-dir=__pycache__
+    --exclude-dir=.pytest_cache
+    --exclude-dir=.mypy_cache
+    --exclude-dir=node_modules
+    --exclude=audit_skill.sh
+    --exclude=pii-patterns.md
+    --exclude="*.pyc"
+)
+
+# ---------------------------------------------------------------------
+# Helper: scan a category of grep -E pattern over text files only.
+# `--binary-files=without-match` keeps random byte sequences inside .png
+# / .pdf / .docx / .pyc from triggering false positives.
+# ---------------------------------------------------------------------
+scan_text() {
+    local category="$1"
+    local pattern="$2"
+    local whitelist="${3:-}"   # optional grep -E pattern; matches removed before counting
+    local results
+    results=$(grep -rinE --binary-files=without-match \
+        "${TEXT_EXCLUDES[@]}" \
+        "$pattern" "$SKILL_DIR" 2>/dev/null || true)
+    if [ -n "$whitelist" ] && [ -n "$results" ]; then
+        results=$(printf '%s\n' "$results" | grep -vE "$whitelist" || true)
+    fi
+
+    if [ -n "$results" ]; then
+        local count
+        count=$(printf '%s\n' "$results" | wc -l | tr -d ' ')
+        TOTAL=$((TOTAL + count))
+        FOUND=1
+        echo
+        echo "${RED}## $category${NC} ($count match(es))"
+        printf '%s\n' "$results" | sed 's/^/  /'
+    fi
+}
+
+# ---------------------------------------------------------------------
+# Helper: filename pattern check. Catches the case where file CONTENT is
+# fine but the filename itself reveals authorship (e.g. Nam2025_KJR_Fig01.png).
+# Mirrors validate_skills.sh rule 7c.
+# ---------------------------------------------------------------------
+scan_filenames() {
+    local category="Author-style filenames (Surname{Year}_)"
+    local pattern='^[A-Z][a-zA-Z]{2,}[0-9]{4}_'
+    local allow='^(Issue|Year|Vol|Table|Figure|Sample|Example|Demo|Test|Type|Class|Group|Cohort|Study|Trial|Phase|Run|Batch|Round|Stage|Step|Item|Mode)[0-9]{4}_'
+    local hits=""
+    while IFS= read -r -d '' f; do
+        local base
+        base=$(basename "$f")
+        if [[ "$base" =~ $pattern ]] && ! [[ "$base" =~ $allow ]]; then
+            hits="${hits}${f}"$'\n'
+        fi
+    done < <(find "$SKILL_DIR" -type f \
+        -not -path '*/.git/*' \
+        -not -path '*/__pycache__/*' \
+        -print0 2>/dev/null)
+
+    if [ -n "$hits" ]; then
+        local count
+        count=$(printf '%s' "$hits" | grep -c '^' || true)
+        TOTAL=$((TOTAL + count))
+        FOUND=1
+        echo
+        echo "${RED}## $category${NC} ($count match(es))"
+        printf '%s' "$hits" | sed 's/^/  /'
+    fi
+}
+
+# ---------------------------------------------------------------------
+# Helper: optional EXIF scan via exiftool. Skipped silently if exiftool is
+# not installed (publish-skill users are not expected to have it). When
+# present, mirrors validate_skills.sh rule 10.
+# ---------------------------------------------------------------------
+scan_exif() {
+    if ! command -v exiftool >/dev/null 2>&1; then
+        echo "${YEL}## Binary EXIF metadata${NC} skipped (exiftool not installed)"
+        echo "  Install: brew install exiftool   # macOS"
+        echo "           sudo apt-get install -y libimage-exiftool-perl   # Ubuntu"
+        return 0
+    fi
+
+    local binary_files=()
+    while IFS= read -r -d '' f; do
+        binary_files+=("$f")
+    done < <(find "$SKILL_DIR" -type f \
+        \( -iname "*.png" -o -iname "*.jpg" -o -iname "*.jpeg" \
+        -o -iname "*.tif" -o -iname "*.tiff" \
+        -o -iname "*.pdf" -o -iname "*.docx" -o -iname "*.pptx" -o -iname "*.xlsx" \) \
+        -print0 2>/dev/null)
+
+    if [ ${#binary_files[@]} -eq 0 ]; then
+        return 0
+    fi
+
+    local pii_pattern='/Users/[a-zA-Z]|/home/[a-zA-Z]'
+    if [ -n "$EXTRA_PATTERNS" ]; then
+        pii_pattern="${pii_pattern}|${EXTRA_PATTERNS}"
+    fi
+
+    local exif_dump
+    exif_dump=$(exiftool -S \
+        -Author -Creator -LastModifiedBy -LastSavedBy -Copyright -Artist \
+        -Owner -OwnerName -CompanyName -Manager -HostComputer -UserComment \
+        -Subject -Title -Description -Keywords -Comment \
+        -Producer -CreatorTool -Software \
+        "${binary_files[@]}" 2>/dev/null || true)
+
+    # exiftool only prints `======== <file>` headers when given multiple files.
+    # Pre-prime current_file so single-file mode still attributes hits correctly.
+    local current_file="${binary_files[0]}"
+    local hits=""
+    while IFS= read -r line; do
+        if [[ "$line" == ========\ * ]]; then
+            current_file="${line#======== }"
+            continue
+        fi
+        [ -z "$line" ] && continue
+        [ -z "$current_file" ] && continue
+        if echo "$line" | grep -qE "$pii_pattern"; then
+            hits="${hits}${current_file}: ${line}"$'\n'
+        fi
+    done <<< "$exif_dump"
+
+    if [ -n "$hits" ]; then
+        local count
+        count=$(printf '%s' "$hits" | grep -c '^' || true)
+        TOTAL=$((TOTAL + count))
+        FOUND=1
+        echo
+        echo "${RED}## Binary EXIF metadata${NC} ($count match(es))"
+        printf '%s' "$hits" | sed 's/^/  /'
+    fi
+}
+
+echo "=========================================="
+echo "PII Audit: $SKILL_DIR"
+echo "=========================================="
+
+# --- Universal text categories -----------------------------------------
+
+# rule 7: hardcoded user-home / project paths.
+scan_text "Hardcoded Paths" \
+    '/Users/[a-zA-Z]|/home/[a-zA-Z]|~/Documents|~/Desktop|~/Downloads|~/Projects'
+
+# rule 7b: real personal email addresses. The whitelist matches common
+# placeholder / example / RFC-reserved domains so the script does not
+# flag legitimate documentation samples.
+EMAIL_WHITELIST='example\.com|example\.org|example\.net|your@email|user@host|noreply@|placeholder|<your-email>|<email>'
+scan_text "Email Addresses" \
+    '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}' \
+    "$EMAIL_WHITELIST"
+
+# Internal infrastructure leakage.
+scan_text "IP Addresses / Internal URLs" \
+    '\b[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\b|https?://[a-z0-9-]+\.(internal|local|corp)'
+
+# rule 6: institutional references. `\b` word boundaries replace the
+# `(?<!...)` lookbehind that the original grep -E silently failed on.
+scan_text "Institutional References" \
+    '\b(SNUH|AMC|SMC|KAIST|SNU|ASAN|MGH|UCSF)\b|Mayo Clinic|Johns Hopkins|Samsung Medical|Severance|Asan Medical'
+
+# rule 6 cont.: titled academic roles with adjacent surname.
+scan_text "Academic Roles with Names" \
+    'professor [A-Z][a-z]+|Prof\. [A-Z]|Dr\. [A-Z][a-z]+|PGY[0-9]|[가-힣]{2,4}[[:space:]]*(교수님|선생님|박사님)'
+
+# Language-default hardcoding.
+scan_text "Language Hardcoding" \
+    'in Korean|한국어로|Korean language|communicate in Korean|in Japanese|in Chinese'
+
+# Frequent-collision city names.
+scan_text "Location Specifics" \
+    '\b(Seoul|Busan|Daegu|Tokyo|Beijing|Shanghai|Boston|Stanford)\b|서울|부산|울산|창원|대구|대전'
+
+# rule 8: dated precedent inside blockquote (`> 2026-04-26 ...`).
+# Allow-list: meta headers like "Last updated:", "Created:", "Updated:",
+# "Date:" — these are routine version stamps, not internal review timeline.
+scan_text "Blockquote Dated Precedent" \
+    '^>.*20[2-9][0-9]-[0-1][0-9]-[0-3][0-9]' \
+    '> *(Last updated|Created|Updated|Date|Version|Released):'
+
+# rule 7c filename pattern.
+scan_filenames
+
+# rule 10 EXIF scan (optional).
+scan_exif
+
+# --- User-supplied identifiers ----------------------------------------
+if [ -n "$EXTRA_PATTERNS" ]; then
+    scan_text "User-Specified Patterns" "$EXTRA_PATTERNS"
+fi
+
+# --- Summary -----------------------------------------------------------
+echo
+echo "=========================================="
+if [ "$FOUND" -eq 0 ]; then
+    echo "${GRN}RESULT: CLEAN (0 findings)${NC}"
+    echo "=========================================="
+    exit 0
+else
+    echo "${RED}RESULT: $TOTAL FINDING(S) DETECTED${NC}"
+    echo "Review and fix all findings before publishing."
+    echo "=========================================="
+    exit 1
+fi

package/skills/publish-skill/skill.yml

@@ -0,0 +1,35 @@
+schema_version: 2
+name: publish-skill
+layer: B
+owner_domain: skill_publishing
+
+when_to_use: "Convert a personal agent skill into a distributable, OSS-ready skill: PII audit, generalization, license check, cross-platform review, packaging."
+when_NOT_to_use: "Authoring a brand-new skill from scratch (out of scope; this hardens an existing one)."
+
+inputs:
+  - "a personal skill directory"
+outputs:
+  - "PII audit report"
+  - "generalized OSS-ready skill"
+deterministic_scripts:
+  - scripts/audit_skill.sh
+side_effects:
+  - writes_skill_artifacts
+downstream_consumers:
+  - none
+forbidden_actions:
+  - publish_skill_with_unresolved_pii
+  - weaken_the_pii_blocklist_to_pass
+
+# v2.1 quality card
+purpose: "Harden a personal skill for open-source release through a PII audit, generalization, and license/portability checks."
+safety_boundaries:
+  - "Publication is gated on a passing PII audit; the blocklist is conservative and not weakened to pass."
+  - "Personal paths, names, and document metadata are scrubbed before release."
+known_limitations:
+  - "The audit catches known PII patterns; novel identifiers still need human review."
+  - "Generalization preserves behavior but a maintainer should re-read the result."
+validation_commands:
+  - "bash scripts/audit_skill.sh <skill-dir>"
+  - "bash scripts/validate_skills.sh"
+evidence_surface: bundled_script

package/skills/render-pdf-doc/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: render-pdf-doc
+description: >
+  Render academic Markdown documents (English or Korean) to publication-quality PDF via pandoc + xelatex.
+  Targets non-bibliography artifacts: research proposals, IRB cover letters, briefing
+  handouts, anchor docs (Q&A grids), and reference tables. Auto-infers pipe-table column
+  widths from content (label column shrinks to fit, data columns share remaining width).
+  CJK-aware font fallback for Korean text (Apple SD Gothic Neo on macOS, Noto Sans CJK KR on Linux).
+  NOT for: manuscripts with bibliography (use /manage-refs render_pandoc.sh), Word form
+  filling (/fill-protocol), figures (/make-figures).
+triggers: render PDF, PDF 렌더, korean PDF, 한글 PDF, anchor doc PDF, briefing PDF, proposal PDF, 연구계획서 PDF, 표 정렬 PDF, 표 폭 자동, tbl-colwidths, 학술 PDF
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: inherit
+---
+
+# Render-PDF-Doc Skill
+
+Markdown + frontmatter → publication-quality academic PDF (English or Korean).
+
+## Why This Skill Exists
+
+In real circulation cycles for academic PDFs, two recurring failure patterns appear:
+1. v1 drafts: change-history, version numbers, and PI attribution leak into the attached PDF, confusing the first recipient.
+2. v2 drafts: pandoc pipe-table dash ratios are misjudged, narrowing the first column and forcing label wrapping that hurts readability.
+
+Manual fixes work but the same pattern recurs across proposals, briefings, IRB covers, exemption applications. This skill focuses on **layout** (CJK fonts + table column widths). Bibliography and CSL are handled by `/manage-refs`.
+
+## Boundary (separation from other skills)
+
+| Task | Skill |
+|---|---|
+| Manuscript + bibliography → DOCX/PDF | `/manage-refs scripts/render_pandoc.sh` (CSL + .bib) |
+| Filling an institutional .docx form | `/fill-protocol` |
+| ICMJE COI form | `/fill-icmje-coi` |
+| Figure / PPTX | `/make-figures`, `/present-paper` |
+| **This skill**: non-bib academic markdown → PDF (proposal, briefing, anchor doc, IRB cover) | `/render-pdf-doc` |
+
+## Core Principles
+
+1. **Pipe table column widths must be inferred from content.** No equal splitting. Size the first column (label) to the longest label, and distribute the remaining width content-proportionally across the data columns.
+2. **Set the CJK font explicitly** — `mainfont` + `CJKmainfont`. The default fallback is OS-detected.
+3. **For circulation PDFs, remove change history / version numbers / PI attribution** (or split them into a supplementary). Use the frontmatter `redact_internal: true` option.
+4. **No Quarto dependency** — raw pandoc + xelatex. Quarto's `tbl-colwidths` has reported PDF regressions (issues 6089/9200).
+
+## Dependencies
+
+```bash
+# Required
+brew install pandoc                                                   # macOS
+brew install --cask mactex-no-gui          # xelatex + xeCJK (~5 GB)
+
+# Linux
+sudo apt-get install pandoc texlive-xetex texlive-lang-cjk fonts-noto-cjk
+```
+
+Detection:
+```bash
+bash scripts/check_deps.sh
+```
+
+## Workflow
+
+### Step 1 — Author markdown with frontmatter
+
+```yaml
+---
+title: "Paper 2 Calibration Anchor — Q&A Grid"
+author: "<Author Group>"
+date: "2026-05-01"
+mainfont: "Apple SD Gothic Neo"        # macOS default
+CJKmainfont: "Apple SD Gothic Neo"
+geometry: "margin=0.85in"
+fontsize: 11pt
+linestretch: 1.25
+colorlinks: true
+---
+```
+
+For Linux/CI, use `Noto Sans CJK KR` instead. The render script auto-detects.
+
+### Step 2 — Infer column widths
+
+```bash
+python scripts/infer_colwidths.py input.md > input.colwidths.md
+```
+
+The script:
+1. Finds every pipe table block.
+2. For each column, computes display width = `max(len(header), max(len(cell)))` (CJK = 2 cells, ASCII = 1).
+3. Generates dash-row separator with proportional dash counts.
+4. Writes a new file with separator rows replaced.
+
+Override per-table via attribute: `{tbl-colwidths="[20,40,40]"}` after caption — passes through unchanged.
+
+### Step 3 — Render
+
+```bash
+bash scripts/render_pdf.sh -i input.colwidths.md -o output.pdf
+```
+
+Or one-shot:
+```bash
+bash scripts/render_pdf.sh -i input.md -o output.pdf --infer-colwidths
+```
+
+### Step 4 — Visual verify
+
+Open the PDF. Check:
+- The first-column labels do not wrap and stay on a single line
+- Data columns have sufficient width
+- No broken Korean glyphs (a Times New Roman fallback means CJKmainfont was not applied)
+- No change history / internal version numbers exposed
+
+## Templates
+
+Starter markdown in `templates/` (English default; a Korean variant `*_ko.md` ships alongside each):
+- `anchor-doc.md` — Q&A grid
+- `proposal-cover.md` — research-proposal cover page
+- `briefing-handout.md` — meeting brief (1-page)
+- `reference-table.md` — comparison-table format
+
+Each template marks slots with a `<!-- TODO: -->` marker.
+
+## Anti-Patterns
+
+| Anti-pattern | Consequence |
+|---|---|
+| Equal dash split (`\|---\|---\|---\|`) | A column with only a short label gets the same width → cramped data columns |
+| `CJKmainfont` not set | Hangul falls back to Times New Roman (broken Latin glyphs or blanks) |
+| Change history / version (e.g. v3.2.2) / PI attribution exposed in a circulation PDF | Confuses the first recipient; leaks internal information |
+| Quarto `tbl-colwidths` for PDF | PDF regression in Quarto 1.4+ — trust HTML only |
+
+## Files
+
+- `scripts/render_pdf.sh` — pandoc + xelatex wrapper, OS font detection
+- `scripts/infer_colwidths.py` — auto-generates pipe-table separator dash ratios
+- `scripts/check_deps.sh` — checks for pandoc / xelatex / CJK font
+- `templates/` — 4 starters (English) + their `*_ko.md` Korean variants
+- `references/pandoc_korean_cheatsheet.md` — collection of frontmatter patterns (Korean-PDF reference)
+- `references/known_pitfalls.md` — em-dash line breaks, smart quotes, etc. (Korean-PDF reference)
+
+## Anti-Hallucination
+
+- Numerical content in tables: apply `~/.claude/rules/numerical-safety.md`. Read from CSV.
+- References: use `/manage-refs` separately — this skill does not handle bib.
+- When producing a circulation PDF, apply `~/.claude/rules/senior-mentor-circulation.md` (preserve the primary source) + `~/.claude/rules/ai-drafted-document-policy.md`.

package/skills/render-pdf-doc/references/known_pitfalls.md

@@ -0,0 +1,53 @@
+# Known Pitfalls — Korean Academic PDF via pandoc + xelatex
+
+> Locale: Korean. This reference intentionally contains Korean examples — it demonstrates Korean-PDF rendering failure modes (a locale feature of `/render-pdf-doc`). See `docs/locale_inventory.md`.
+
+## 1. 균등 분할 dash separator (`|---|---|---|`)
+
+**증상**: 첫 열에 짧은 라벨만 있어도 데이터 열과 같은 폭 → 데이터 wrap, 가독성 저하.
+
+**해결**: `scripts/infer_colwidths.py` 사용. Header + cell content 최대 display-width(CJK=2)에 비례한 dash count로 separator 행을 교체.
+
+수동 override: `{tbl-colwidths="[20,40,40]"}` 캡션 뒤에 부착 (Quarto 1.4+ HTML만; PDF는 위 스크립트 권장).
+
+## 2. CJKmainfont 미설정 → Hangul fallback
+
+**증상**: Times New Roman 등 라틴 폰트로 fallback. 한글 글자가 빈 □ 또는 깨진 글리프로 출력.
+
+**해결**: frontmatter에 `mainfont` + `CJKmainfont` 모두 명시. macOS는 `Apple SD Gothic Neo`, Linux는 `Noto Sans CJK KR`. xeCJK는 xelatex와 함께 자동 로드.
+
+## 3. CJKmainfont 설정 시 smart quotes 깨짐
+
+**증상**: pandoc issue 7509 — CJKmainfont 활성화 시 `"hello"`의 곧은 따옴표가 CJK 폰트로 렌더되어 `”hello”` 처럼 보임.
+
+**해결**: 본문에 영문 quote 많을 때만 영향. 필요 시 `--smart=off` 또는 본문 quote를 `\enquote{...}`로 명시.
+
+## 4. Em-dash 줄바꿈 깨짐
+
+**증상**: `—` 양쪽 공백 없이 사용 시 xelatex가 줄바꿈 안 함 → 우측 마진 침범.
+
+**해결**: 본문에서는 em-dash 25개 미만 권장 (`~/.claude/rules/manuscript-style-classical.md` §8). 필요 시 양쪽 공백 추가 또는 `\,—\,`.
+
+## 5. 회람 PDF에 변경이력 / 버전번호 / PI attribution 노출
+
+**증상**: 첫 수신자가 "v3.2.2" 같은 내부 버전·작성자 코멘트를 보고 혼란.
+
+**해결**: 회람용 markdown은 별도 파일로 (`anchor_circulation.md` 등). 변경이력 섹션은 supplementary로 분리. frontmatter `redact_internal: true` 옵션은 future work.
+
+## 6. xelatex 미설치 (Linux CI)
+
+```bash
+sudo apt-get install -y texlive-xetex texlive-lang-cjk fonts-noto-cjk
+```
+
+macOS는 `brew install --cask mactex-no-gui` (~5 GB) 또는 `basictex` + `tlmgr install xecjk` (경량).
+
+## 7. Pipe table 안에 ` | ` 문자
+
+**증상**: 셀 본문에 `|`가 있으면 컬럼이 잘못 분리됨.
+
+**해결**: `\|` escape, 또는 grid table (`+---+---+`) 사용. infer_colwidths.py는 pipe table만 처리.
+
+## 8. Quarto `tbl-colwidths` PDF regression
+
+Quarto 1.4+에서 PDF에서는 무시되는 케이스 보고 (issues 6089, 9200). HTML은 OK. PDF 신뢰 불가 → raw pandoc + infer_colwidths 사용.

package/skills/render-pdf-doc/references/pandoc_korean_cheatsheet.md

@@ -0,0 +1,77 @@
+# Pandoc Korean PDF Cheatsheet
+
+> Locale: Korean. This reference intentionally contains Korean examples — it documents how to render Korean academic PDFs (a locale feature of `/render-pdf-doc`). See `docs/locale_inventory.md`.
+
+## 검증된 frontmatter 패턴
+
+```yaml
+---
+title: "문서 제목"
+author: "작성자"
+date: "2026-05-01"
+mainfont: "Apple SD Gothic Neo"     # macOS / Linux: "Noto Serif CJK KR"
+CJKmainfont: "Apple SD Gothic Neo"  # macOS / Linux: "Noto Sans CJK KR"
+geometry: "margin=0.85in"            # cover/proposal: 1in / briefing: 0.75in
+fontsize: 11pt                       # briefing: 10pt
+linestretch: 1.25                    # cover: 1.5 / briefing: 1.2
+colorlinks: true
+---
+```
+
+## 명령어 (raw pandoc)
+
+```bash
+pandoc input.md \
+  --pdf-engine=xelatex \
+  -o output.pdf
+```
+
+OS-detect 자동화는 `scripts/render_pdf.sh` 참고.
+
+## 표 폭 자동 추론
+
+```bash
+# 1) 분리행 dash 비율을 content-proportional로 교체
+python3 scripts/infer_colwidths.py input.md --out input.cw.md
+
+# 2) 렌더
+pandoc input.cw.md --pdf-engine=xelatex -o output.pdf
+```
+
+또는 wrapper 한 번에:
+```bash
+bash scripts/render_pdf.sh -i input.md -o output.pdf --infer-colwidths
+```
+
+## Per-document 폰트 커스터마이즈
+
+frontmatter > `--font` CLI > OS default (낮은 우선순위).
+
+```bash
+bash scripts/render_pdf.sh -i input.md --font "Nanum Myeongjo" --cjk-font "Nanum Myeongjo"
+```
+
+## 폰트 후보 (한글 학술용)
+
+| 폰트 | 비고 |
+|------|------|
+| Apple SD Gothic Neo | macOS 기본, sans, 가장 깔끔 |
+| Noto Sans CJK KR | Linux 기본 |
+| Noto Serif CJK KR | 본문 serif |
+| Nanum Myeongjo | 명조계 (전통적) |
+| Nanum Gothic | 고딕계 sans |
+| Pretendard | 모던 sans, 별도 설치 |
+
+## 추가 옵션
+
+- `--toc` — 목차 생성 (긴 proposal에 유용)
+- `--number-sections` — 자동 섹션 번호
+- `-V documentclass=article` (default) / `report` / `book`
+- `-V papersize=a4` — A4 (default: letter)
+
+## 참고 링크
+
+- [Pandoc User Guide](https://pandoc.org/MANUAL.html)
+- [Pandoc with Chinese (CJK applies)](https://github.com/jgm/pandoc/wiki/Pandoc-with-Chinese)
+- [Quarto tbl-colwidths](https://quarto.org/docs/authoring/tables.html#column-widths) (HTML 신뢰; PDF regression 주의)
+- [Issue 7509 — CJKmainfont smart quotes](https://github.com/jgm/pandoc/issues/7509)

package/skills/render-pdf-doc/scripts/check_deps.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# check_deps.sh — verify pandoc + xelatex + CJK font availability.
+set -u
+
+ok=0
+fail=0
+
+check() {
+  local name="$1"; shift
+  if "$@" >/dev/null 2>&1; then
+    echo "[OK] $name"
+    ok=$((ok + 1))
+  else
+    echo "[MISS] $name"
+    fail=$((fail + 1))
+  fi
+}
+
+check "pandoc" command -v pandoc
+check "xelatex" command -v xelatex
+
+if [[ "$(uname)" == "Darwin" ]]; then
+  if /usr/bin/fc-list 2>/dev/null | grep -qi "Apple SD Gothic Neo" \
+     || system_profiler SPFontsDataType 2>/dev/null | grep -qi "Apple SD Gothic Neo"; then
+    echo "[OK] Apple SD Gothic Neo (macOS)"
+    ok=$((ok + 1))
+  else
+    echo "[WARN] Apple SD Gothic Neo not detected — falling back to default fontconfig"
+  fi
+else
+  if fc-list 2>/dev/null | grep -qi "Noto.*CJK.*KR"; then
+    echo "[OK] Noto Sans/Serif CJK KR"
+    ok=$((ok + 1))
+  else
+    echo "[MISS] Noto CJK KR — apt install fonts-noto-cjk"
+    fail=$((fail + 1))
+  fi
+fi
+
+echo
+echo "Summary: $ok ok, $fail fail"
+exit $fail