git:20260929.ed1b2b2 to git:20260930.913abeb

- 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).

- **Windows / Git Bash note.** MiKTeX's binary directory

- (`%LOCALAPPDATA%\Programs\MiKTeX\miktex\bin\x64`) is often not on the Git Bash `PATH`,

- so `xelatex` can read as `[MISS]` even after install. Both `check_deps.sh` and

- `render_pdf.sh` now auto-probe that location; if `xelatex` still isn't found, add the

- directory to your `PATH` (or run from the *MiKTeX Console → Settings*-configured shell).

- The Windows CJK/main font default is **Malgun Gothic** (preinstalled); override per document

- via frontmatter, or set fallbacks with `--font` / `--cjk-font`.

- For Linux/CI, use `Noto Sans CJK KR`; on Windows, use `Malgun Gothic`. The render script auto-detects the default per OS.

- 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.

- It groups the risky glyphs by class (advisory), or — with `--font` + `fonttools`

- — reports which are absent from one face's preferred Unicode cmap. It never

- combines coverage across collection faces. The report includes the selected

- face index and PostScript name; choose the face that matches the rendered font.

- A missing dependency, unreadable font, missing face selection or invalid index

- is reported as `font_checked: false` with a reason in `font_check`.

- An empty `missing_in_font` list then means **unverified**, not full coverage.

- The default mode remains advisory (exit 0); `--strict` exits 1 when risky glyphs

- are unverified or missing. ASCII-only input still exits 0 with an unavailable

- font, with `font_checked: false` visible.

- This checks only the listed risky character classes and the selected cmap;

- it does not verify shaping, fallback fonts, math fonts or final PDF glyphs.

- If risky glyphs are

- present, ensure `mainfont`/`CJKmainfont` cover them (a CJK-capable font such as

- *Apple SD Gothic Neo* / *Noto Sans CJK* usually covers arrows + Hangul but can

- still miss the true-minus `−` U+2212 and `★`). **The DOCX is authoritative; the

- PDF is a convenience copy** — never let a PDF render drop a glyph the document

- needs.

- 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 missing scientific symbols (arrows, −, ≤, ±, √) — the Step 3.5 scan flags candidates

- - No change history / internal version numbers exposed

- Starter markdown in `templates/` (English default; a Korean variant `*_ko.md` ships alongside each):

-

- 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: read every value from the source CSV or analysis output. Do not

- retype a number from prose, and do not carry one forward from an earlier draft — a table that

- was correct in v3 is not evidence it is correct in v4.

- - References: use `/manage-refs` separately — this skill does not handle bib.

- - When producing a circulation PDF, keep the received primary source (the `.docx` or `.eml` a

- co-author sent) unmodified as its own artifact. The PDF is a derivative, not a replacement, and

- the next round is diffed against that source. If the source was itself AI-drafted by a

- collaborator, treat every number, denominator, and author-year in it as unverified: re-derive

- each from the underlying paper or analysis output before it reaches the PDF.

-

- ## Global-rule references

-

- Some passages in this skill cite a path of the form `~/.claude/rules/<name>.md`. Those are the

- maintainer's personal global rules, kept outside this repository. They are **not shipped with

- this skill** and will not exist on your machine; they appear only as provenance for where a

- convention came from. If one of them looks like it is standing in for an instruction you actually

- need, that is a bug — please open an issue, because the instruction belongs here.