<div align="right">
**English** · [中文](./README.zh.md)
</div>
<br />
<div align="center">
# paper-deck-reveal
**A paper, staged as a projection-ready reveal.js deck.**
<br/>
Built natively for Claude Code; runs in Codex and any agent that loads the SKILL.md format.
<br/>
Faithful in-slide experiment walkthroughs · paper-grade correctness gate · speaker dual-screen · plays from file://, zero network.
<br/>
<a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-Apache_2.0-000?style=flat-square" alt="Apache 2.0"/></a>
<a href="SKILL.md"><img src="https://img.shields.io/badge/agent-Skill-000?style=flat-square" alt="Agent Skill"/></a>
<img src="https://img.shields.io/badge/Node-18+_·_Playwright-000?style=flat-square" alt="Node 18+ · Playwright"/>
<img src="https://img.shields.io/badge/Python-3.10+_·_Pillow-000?style=flat-square" alt="Python 3.10+ · Pillow"/>
<img src="https://img.shields.io/badge/version-1.2.0-000?style=flat-square" alt="v1.2.0"/>
</div>
<br/>
<div align="center">
**[→ Live demo (a real deck, plays in your browser — arrow keys, or `S` for the speaker view)](https://o0000-code.github.io/paper-deck-reveal/)**
</div>
<br/>
## What it does
You hand your agent a paper. This Skill reads it on two tracks — *what is this paper's core tension*, and *what genre and structure does it have* — and writes a per-page Markdown script. It then assembles that script into a reveal.js deck against a tuned quiet-luxury design system — every slide a `<section>` in one `index.html`, no build step — rebuilds the paper's experiment as a step-through your audience can actually do, and writes the speaker notes into the deck.
The result is one folder: double-click `index.html` and present, with the wifi off. No API keys anywhere — your agent is the LLM. The validated path is a Chinese deck reporting an English-language paper, because the methodology in [`references/`](references/) is written in Chinese — see [Honest boundaries](#honest-boundaries) for what an English deck does not get.
```text
In your agent's chat, after install:
Turn this paper into a deck for our journal club. On the experiment
slide, let the audience actually do the task the participants did.
```
<br/>
## What makes it different
Four design decisions separate this from "ask the model to turn this PDF into slides."
**1 · The experiment is embedded, not described — and it never leaks the result.**
The experiment slide carries a step-through reconstruction of what the participant actually saw and did: instructions, practice, the task, the debrief. `faithful` is a contract, not a label — first person only, no narrator, no room description, no "the experimenter stood behind you." And **no result ever enters the program**: no means, no coefficients, no "you answered like the 40-year-olds." Results live on the results slides, where the paper put them. Your audience can do the task and still learn nothing about the outcome until you tell them. This is checked, not trusted: render-QA walks every interaction state and greps it for result-leak signals.
**2 · Three gates, and the design review can send it back.**
Delivery runs through design review (*beautiful / fitting?*), render-QA (*broken / overflowing / dead?*), and the correctness gate (*statistics / citations / real figures?*). Only the middle one is automatable, and it is the one every tool ships. The design review is the gate that separates "it runs" from "it's finished" — it goes page by page with a designer's eye and has the standing to send a page back to be redone. Shipping on render-QA plus correctness alone delivers a first draft as if it were final, which this Skill defines as the failure state.
**3 · Correctness means what an empiricist advisor checks, line by line.**
Five gates, not a proofread. Statistics italics are decided **per token** — Latin single-letter statistics italic, Greek χ² and abbreviations like ACME upright, digits upright — never a block-level class that silently italicizes the numbers too, which is a real bug this earned the hard way. Then: in-text APA citation judgment, content-attribution checked against the original PDF, DOI verification for every reference, and a figure audit. The Skill **never draws a data figure itself** — figures come out of the paper, stitched from the published panels with provenance kept. A bad figure in the paper becomes a bad figure with a read-aid line, not a prettier lie.
**4 · Offline is the delivery contract, not a feature.**
reveal.js and the deck's two font families are copied out of [`assets/`](assets/) into every deck; assembly never emits an external URL. Measured, not asserted — walking all 26 slides of the demo deck from `file://`, including the interaction: **0 HTTP requests, 0 failed requests, 0 console errors**, fonts resolving locally. This pays off twice: conference-room wifi is where talks die, and a deck with no external dependency still renders in three years, when the CDN has moved on.
<br/>
## Use cases
The genre gate runs *before* decomposition, because a theory paper has no method block and no results block — forcing the empirical four-part template onto it manufactures four fake sections.
| Scenario | Genre branch | What the deck gets |
|---|---|---|
| Journal club on an empirical paper | **Empirical** — first-class | Structure tree → per-study four-part pages, participant funnel, results in three layers, the task itself embedded |
| Reading group on a theory or modelling paper | Theoretical | Definitions → propositions → intuition; main theorem up front, no suspense |
| Presenting a review or meta-analysis | Review | Inclusion flow, per-theme evidence, effect sizes transcribed verbatim |
| Walking a lab through a methods / benchmark paper | Methods | Dataset description in place of the participant funnel; metric → result → threshold |
| A position or philosophy paper | Position | Claim → argument → appraisal; the claim leads |
| You already wrote the per-page script | *second entrance* | Decomposition is skipped; assembly → notes → the three gates run unchanged |
<br/>
## Install
Clone into your agent's Skills directory. The target path varies by agent — pick the one matching what you use:
```bash
# Pick ONE target directory, depending on your agent:
# ~/.claude/skills/paper-deck-reveal # Claude Code
# ~/.codex/skills/paper-deck-reveal # Codex CLI
# ~/.cursor/skills/paper-deck-reveal # Cursor
# ~/.config/goose/skills/paper-deck-reveal # Goose
# ~/.roo/skills/paper-deck-reveal # Roo Code
# ./.claude/skills/paper-deck-reveal # project-local (Claude Code)
# Other agents: `npx skills add` below knows each one's path — or check your agent's docs.
git clone https://github.com/O0000-code/paper-deck-reveal.git \
~/.claude/skills/paper-deck-reveal # change to your chosen path
```
Or one line, agent-agnostic: `npx skills add O0000-code/paper-deck-reveal`
| Requirement | Drives | Install | Without it |
|---|---|---|---|
| **Node 18+ · Playwright** | `scripts/render_qa.mjs` — the render-QA gate | `npm i playwright && npx playwright install chromium`, **in the deck directory or its parent** (elsewhere, point `--playwright <root>` at it) | The gate cannot run and stays fail-closed. "Not installed" is never a reason to skip QA |
| **Python 3.10+ · Pillow** | panel stitching, figure triage, stimulus fetch | `pip install Pillow` | Figures fall back to a manual eyes-on audit. Do not substitute ImageMagick — its font config breaks on macOS |
| **MCP servers** *(optional)* | DOI lookup, figure sourcing | per provider | DOI verification's main route is plain public HTTP; figure sourcing has its own fallback table |
<br/>
## What the deck looks like
Every image below is the demo deck in this repo — one paper, run through the whole pipeline.
<table>
<tr>
<td width="50%" valign="top">
<a href="docs/screenshots/funnel.png"><img src="docs/screenshots/funnel.png" alt="Participant funnel slide: recruited N = 976 → excluded −59 → analysed N = 917"/></a>
<br/>
<sub><strong>Participant funnel</strong> — recruitment to analysed sample, exclusions and their reasons, and an explicit note on what the paper never reported.</sub>
</td>
<td width="50%" valign="top">
<a href="docs/screenshots/forest.png"><img src="docs/screenshots/forest.png" alt="Per-language results slide: the paper's own Figure 4, above it a read-aid line and four key figures, below it a conclusion band"/></a>
<br/>
<sub><strong>Results, in three layers</strong> — the paper's own figure, a read-aid line telling the room how to read it, and the claim landing last.</sub>
</td>
</tr>
<tr>
<td valign="top">
<a href="docs/screenshots/interactive.png"><img src="docs/screenshots/interactive.png" alt="Interactive slide: the participant's task embedded in the deck — play the sound, pick one of two shapes, trial 2 of 2"/></a>
<br/>
<sub><strong>The experiment, embedded</strong> — the participant's own screen, running inside the slide. Zero results, and honestly labelled where the stimuli are substitutes.</sub>
</td>
<td valign="top">
<a href="docs/screenshots/speaker.png"><img src="docs/screenshots/speaker.png" alt="Speaker view: current slide, next slide, timers, and nested speaker notes"/></a>
<br/>
<sub><strong>Speaker dual-screen</strong> — current and upcoming slide, timers, and notes written to be spoken, not read aloud.</sub>
</td>
</tr>
<tr>
<td colspan="2" valign="top">
<a href="docs/screenshots/presets.png"><img src="docs/screenshots/presets.png" alt="Eight accent presets applied to the same slide of the same deck"/></a>
<br/>
<sub><strong>Eight accent presets</strong> — reskinning is three lines in <code>tokens.css</code>. Name your institution instead and a 23-entry lookup table resolves it; hand it a raw hex and an admission band checks contrast and lightness, then returns a correction rather than a refusal. See <a href="references/accent_presets.md"><code>references/accent_presets.md</code></a>.</sub>
</td>
</tr>
</table>
<br/>
## The pipeline
Serial trunk, one three-way fork. The order is load-bearing, not decorative: content is written before form, and every gate downstream reads the artifact the one before it produced.
```text
paper ──┬──▶ design track: what is THIS paper's core tension?
│ (no layout starts before that sentence exists)
└──▶ content track: which genre? empirical → how many studies?
│
▼
per-page Markdown script content before form — a lock, not a taste
│
┌───────────────┼───────────────────────────┐
▼ ▼ ▼
assemble HTML interactive slides increment / node table
copy-fill from stimuli file→file; keyed to page order
templates, no faithful = participant
build step view, zero results
│
▼
render-QA #1 ── overflow · console · dead links · CDN grep · leak scan
│
▼
speaker notes ── path A (drafted for you to edit) or path B (you wrote it,
│ installed verbatim — the script never rewrites your prose)
▼
render-QA #2 ── + speaker view · dual-screen sync · arrow-key focus
│
▼
┌─ three gates, all three required ───────────────────────────────┐
│ design review beautiful / fitting? ← can send it back │
│ render-QA broken / overflowing / dead? │
│ correctness statistics / citations / real figures? │
└─────────────────────────────────────────────────────────────────┘
│
▼
offline, projection-ready deck
```
The routing table in [`SKILL.md`](SKILL.md) says which of the 18 documents in [`references/`](references/) to open at each step; 10 scripts in [`scripts/`](scripts/) do the deterministic work.
<br/>
## Also in this repo: `deck-craft` (the pptx sibling)
The repo also ships [`deck-craft/`](deck-craft/) — the pptx-track counterpart to this skill. Same design philosophy and pipeline, different medium: it turns source material into a projection-ready, content-dense **`.pptx`** report deck (via python-pptx), where `paper-deck-reveal` produces interactive, offline **HTML**. It is a self-contained sibling skill — **not a dependency of this one** — so this README does not narrate it further. A full `git clone` brings it along; to install it on its own:
```bash
npx skills add https://github.com/O0000-code/paper-deck-reveal/tree/main/deck-craft
```
Routing: interactive offline HTML → `paper-deck-reveal`; a content-dense `.pptx` report → `deck-craft`; a light one-off `.pptx` → the public `pptx` skill.
<br/>
## Companion skills, and what happens without them
Companion skills are wired into the chain, and none is bundled here. Each has a written degrade contract — the Skill runs without any of them, and the gates stay shut. Distribution tiers for every dependency are in [`docs/DEPENDENCY-MATRIX.md`](docs/DEPENDENCY-MATRIX.md).
- **`academic-ref-check`** drives the DOI-verification gate. It lives in [`O0000-code/meta-analysis-skill`](https://github.com/O0000-code/meta-analysis-skill) at `skills/academic-ref-check/` and is deliberately **not bundled here**: its noncommercial terms (PolyForm-NC-1.0.0 + CC-BY-NC-SA-4.0) travel with it, and vendoring them into an Apache-2.0 repo would quietly transfer that restriction to you. Without it, the gate falls back to MCP or manual per-reference verification — it does not open either way.
- **`humanizer-zh`** is the write-after AI-tells sweep on speaker notes. It is **op7418's public MIT skill** (chain: [`blader/humanizer`](https://github.com/blader/humanizer) © Siqi Chen → [`op7418/Humanizer-zh`](https://github.com/op7418/Humanizer-zh) → `hardikpandya/stop-slop`). It is **not bundled**; when the notes de-AI step needs it and it is not installed, the running agent installs it on demand — `npx skills add op7418/Humanizer-zh`, or `git clone` it into your skills directory — then uses it. If that is not possible (offline/sandbox), the sweep degrades to `scripts/check_notes_voice.py`, which ships here and enforces the two hard taboos. This repo is only a user of humanizer-zh; its attribution chain is preserved. For English decks, its English upstream [`blader/humanizer`](https://github.com/blader/humanizer) (MIT) applies.
- **`academic-voice-zh`** is the write-before writing-philosophy pass. It is **the author's own and not yet public**, so it cannot be auto-installed; without it, that step falls back to the writing discipline written into [`references/speaker_notes_method.md`](references/speaker_notes_method.md) §1–§4 plus the same hard taboos.
<br/>
## Honest boundaries
The Skill runs a correctness gate over every claim a deck makes about its paper — this section is that gate, pointed at the repo.
- **Chinese journal-club decks are the validated path.** The methodology documents are written in Chinese, and the deck the Skill produces defaults to reporting an English-language paper in Chinese — including the convention of keeping each load-bearing construct's original English next to it. English decks get the full craft, engineering, and correctness layers; what they do not get is a validated de-AI pass, because the two Chinese skills above have no English counterpart shipped here. No English taboo patterns were invented for v1: there is no measured baseline for them, and a guessed one would be worse than saying this.
- **Empirical psychology is the first-class citizen; four other genres are skeleton-level.** The structure tree, per-study pages, participant funnel, faithful interaction, and the full depth of the correctness gate all sit on the empirical branch, and were re-worked against real empirical papers until they held. Everything else gets a skeleton and the free layers. It also means conventions that look universal are marked as what they are — "don't spoil the result" is an *empirical default*, not a rule: economics asks for a preview of results, and mathematics puts the main theorem up front.
- **macOS is the first-class platform.** Development, the render-QA gate, the CI runner, and every screenshot here are macOS. Chinese text renders through the system PingFang; `"Microsoft YaHei"` and `"Noto Sans CJK SC"` follow it in every font stack, so Windows and Linux degrade rather than break — but render-QA's pixel-level overflow assertions were tuned on PingFang metrics and can fire differently on other font stacks. That is why CI pins `macos-latest` instead of a cheaper runner.
- **The worldview subsystem is experimental.** The default quiet-luxury look is the stable, exercised path. Alternate worldviews are opt-in behind a single appearance decision point and inherit the same frozen scientific invariants — but they have far fewer miles on them, and there is currently one.
- **A deck is not a talk.** The Skill will not decide what your paper means, what to cut for a 20-minute slot, or whether you agree with the authors. It gets you to a finished artifact that survives a line-by-line reading; the judgment and the delivery stay yours.
<br/>
## The demo deck
Everything above is one real deck, built with this Skill and shipped at [`examples/cwiek-2022-bouba-kiki/`](examples/cwiek-2022-bouba-kiki/), where it doubles as the CI fixture. What ships is a folder, not a file: `index.html` beside `theme.css` and `tokens.css`, then `assets/` for the fonts and the interaction template, `reveal/`, `figures/` for the paper's panels with `provenance/` kept next to them, and `interactive/` for the experiment itself. The pipeline's inputs are in there too — `_deck_md.md`, the per-page script, and `_notes_draft.md`, the speaker notes — so what went in is as inspectable as what came out.
> Ćwiek, A., Fuchs, S., Draxler, C., Asu, E. L., Dediu, D., Hiovain, K., Kawahara, S., Koutalidis, S., Krifka, M., Lippus, P., Lupyan, G., Oh, G. E., Paul, J., Petrone, C., Ridouane, R., Reiter, S., Schümchen, N., Szalontai, Á., Ünal-Logacev, Ö., … Winter, B. (2022). The bouba/kiki effect is robust across cultures and writing systems. *Philosophical Transactions of the Royal Society B*, 377(1841), 20200390. <https://doi.org/10.1098/rstb.2020.0390>
Published by the Royal Society under **CC BY 4.0**; Figures 2–6 are the authors' own, reproduced unmodified with attribution. The shapes on the phenomenon slide and inside the interaction are **original drawings, not the paper's** — its Fig. 1 shapes were themselves adapted from Bremner et al. (2013), so this deck draws its own rather than redistribute third-party-derived artwork, and labels them as illustrative wherever they appear. The audio clips are self-made substitutes, labelled as such in the audience layer. Full provenance: [`CREDITS.md`](examples/cwiek-2022-bouba-kiki/CREDITS.md).
<br/>
## License
Apache License 2.0 — see [`LICENSE.txt`](LICENSE.txt). The bundled reveal.js (MIT) and the Inter · Fraunces · IBM Plex · Spectral font families (SIL OFL 1.1) keep their own terms; each license copy travels with the assets it covers, and [`THIRD_PARTY.md`](THIRD_PARTY.md) lists every one with its upstream source.