Skip to content

An AI skill that turns books into animated, narrated, interactive web experiences

ci: check the Skill's docs, the books and the scripts on every pull request

yzr2d20cdcc7c83
diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
new file mode 100644
index 0000000..dba71e9
--- /dev/null
+++ b/.claude/CLAUDE.md
@@ -0,0 +1 @@
+@../AGENTS.md
diff --git a/.github/scripts/check_site.py b/.github/scripts/check_site.py
new file mode 100644
index 0000000..884a201
--- /dev/null
+++ b/.github/scripts/check_site.py
@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""Checks of the published books that need no private folders, network or browser. Run from the repository root:
+
+ python3 .github/scripts/check_site.py
+
+- every book's engine copy matches engine/ (engine.py --check), so no one edited a copy instead of the source;
+- lint.py on every book (errors fail; narration is not checked, since content/ is not in the repository);
+- node --check on every script: the .js files and each inline <script> of every page, so a syntax error that
+ would stop a chapter is caught before it ships.
+
+Needs Python 3 and Node. Exits 1 if any check fails.
+"""
+import re, subprocess, sys, tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+SCRIPTS = ROOT / '.claude/skills/papermorph/scripts'
+failed = []
+
+
+def run(label, cmd):
+ r = subprocess.run(cmd, cwd=ROOT, capture_output=True, text=True)
+ if r.returncode:
+ failed.append(label)
+ print(f'FAIL {label}\n{(r.stdout + r.stderr).strip()}\n')
+ return r
+
+
+def node_check(path, label):
+ r = subprocess.run(['node', '--check', str(path)], capture_output=True, text=True)
+ if r.returncode:
+ failed.append(label)
+ print(f'FAIL {label}\n{r.stderr.strip()}\n')
+
+
+def main():
+ run('engine copies', [sys.executable, str(SCRIPTS / 'engine.py'), 'site', '--check'])
+ books = sorted(p.parent.parent for p in (ROOT / 'site').glob('*/lib/engine.js'))
+ for book in books:
+ run(f'lint {book.name}', [sys.executable, str(SCRIPTS / 'lint.py'), str(book.relative_to(ROOT))])
+
+ tracked = subprocess.run(['git', 'ls-files', 'engine', 'site', '.claude/skills/papermorph/assets'],
+ cwd=ROOT, capture_output=True, text=True, check=True).stdout.split()
+ js = [f for f in tracked if f.endswith('.js') and 'vendor/' not in f and not f.endswith('mathjax.js')]
+ pages = [f for f in tracked if f.endswith('.html')]
+ for f in js:
+ node_check(ROOT / f, f)
+ inline = 0
+ with tempfile.TemporaryDirectory() as tmp:
+ for f in pages:
+ html = (ROOT / f).read_text(errors='replace')
+ for i, (attrs, body) in enumerate(re.findall(r'<script(\s[^>]*)?>(.*?)</script>', html, flags=re.S)):
+ attrs = attrs or ''
+ if 'src=' in attrs or not body.strip() or re.search(r'type=["\']?(?!text/javascript|module)', attrs):
+ continue
+ out = Path(tmp) / f'{len(failed)}-{inline}.{"mjs" if "module" in attrs else "js"}'
+ out.write_text(body)
+ node_check(out, f'{f} <script> #{i + 1}')
+ inline += 1
+ print(f'{len(books)} books linted, {len(js)} scripts and {inline} inline scripts checked; '
+ f'{len(failed)} failed' + (': ' + ', '.join(failed) if failed else ''))
+ sys.exit(1 if failed else 0)
+
+
+if __name__ == '__main__':
+ main()
diff --git a/.github/scripts/check_skill.py b/.github/scripts/check_skill.py
new file mode 100644
index 0000000..cd76bec
--- /dev/null
+++ b/.github/scripts/check_skill.py
@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Check that the Papermorph Skill's docs agree with its files. Standard library only; run from the repository root:
+
+ python3 .github/scripts/check_skill.py
+
+- every relative link and #anchor in SKILL.md, references/ and the repository's own .md files resolves;
+- SKILL.md links every reference file directly, so none is reachable only through another;
+- every script in scripts/ is named in SKILL.md, and every script compiles;
+- a flag written next to a script (`level.py --lufs -14`) appears in that script's source;
+- a `scripts/x.py` or `assets/templates/...` path named in the docs exists.
+
+Prints each problem with its file and exits 1 if there are any.
+"""
+import re, sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+SKILL = ROOT / '.claude/skills/papermorph'
+DOCS = [SKILL / 'SKILL.md', *sorted((SKILL / 'references').rglob('*.md'))]
+REPO_DOCS = [p for p in (ROOT / 'README.md', ROOT / 'AGENTS.md', ROOT / 'engine/vendor/mathjax/README.md') if p.exists()]
+problems = []
+
+
+def say(path, msg):
+ problems.append(f'{path.relative_to(ROOT)}: {msg}')
+
+
+def slug(heading):
+ h = re.sub(r'[`*_]', '', heading.strip().lower())
+ return re.sub(r'[^\w\- ]', '', h).replace(' ', '-')
+
+
+def anchors(path):
+ out, fence = set(), False
+ for line in path.read_text().splitlines():
+ if line.startswith('```'):
+ fence = not fence
+ elif not fence and (m := re.match(r'#{1,6} (.*)', line)):
+ out.add(slug(m.group(1)))
+ return out
+
+
+def without_fences(text):
+ return re.sub(r'```.*?```', '', text, flags=re.S)
+
+
+def links():
+ for doc in DOCS + REPO_DOCS:
+ for target in re.findall(r'\]\(([^)\s]+)\)', without_fences(doc.read_text())):
+ if re.match(r'[a-z]+:', target):
+ continue
+ path, _, frag = target.partition('#')
+ dest = (doc.parent / path).resolve() if path else doc
+ if not dest.exists():
+ say(doc, f'link to a missing file: {target}')
+ elif frag and dest.suffix == '.md' and frag not in anchors(dest):
+ say(doc, f'link to a missing heading: {target}')
+
+
+def routing():
+ text = (SKILL / 'SKILL.md').read_text()
+ linked = {(SKILL / t.split('#')[0]).resolve() for t in re.findall(r'\]\((references/[^)#\s]+)', text)}
+ for ref in DOCS[1:]:
+ if ref.resolve() not in linked:
+ say(ref, 'not linked from SKILL.md')
+ for script in sorted((SKILL / 'scripts').glob('*.py')):
+ if f'`{script.name}`' not in text:
+ say(script, 'not named in SKILL.md')
+ try:
+ compile(script.read_text(), str(script), 'exec')
+ except SyntaxError as e:
+ say(script, f'does not compile: line {e.lineno}: {e.msg}')
+
+
+def code_spans(text):
+ """Inline code spans, plus each line of a fenced block as one span."""
+ spans = []
+ for block in re.findall(r'```[^\n]*\n(.*?)```', text, flags=re.S):
+ spans += block.splitlines()
+ return spans + re.findall(r'`([^`\n]+)`', without_fences(text))
+
+
+def drift():
+ for doc in DOCS:
+ for span in code_spans(doc.read_text()):
+ for p in re.findall(r'(?:^|[\s"]|SKILL/)(scripts/\w+\.py)', span):
+ if not (SKILL / p).exists():
+ say(doc, f'names a missing script: {p}')
+ for p in re.findall(r'(assets/templates/[\w./*-]+)', span):
+ if not list(SKILL.glob(p.rstrip('/.'))):
+ say(doc, f'names a missing path: {p}')
+ for name in re.findall(r'(\w+\.py)\b', span):
+ src = SKILL / 'scripts' / name
+ if not src.exists():
+ continue
+ code = src.read_text()
+ # a flag right after this script's name and before the next script or pipe belongs to it
+ tail = re.split(r'\b\w+\.py\b|\|', span.split(name, 1)[1])[0]
+ for flag in re.findall(r'(?<![\w-])(--[a-z][\w-]*)', tail):
+ if flag != '--help' and flag not in code:
+ say(doc, f'{name} has no {flag}')
+
+
+def selftest():
+ assert slug('Performance (Firefox)') == 'performance-firefox'
+ assert slug('Cover and contents (`index.html`)') == 'cover-and-contents-indexhtml'
+ assert slug('style.json') == 'stylejson'
+ assert code_spans('a `x.py --y` b\n```sh\none\ntwo\n```') == ['one', 'two', 'x.py --y']
+
+
+if __name__ == '__main__':
+ selftest()
+ links(); routing(); drift()
+ print('\n'.join(problems) or 'ok', f'\n{len(problems)} problems in {len(DOCS) + len(REPO_DOCS)} docs')
+ sys.exit(1 if problems else 0)
diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml
new file mode 100644
index 0000000..73c49c8
--- /dev/null
+++ b/.github/workflows/checks.yml
@@ -0,0 +1,28 @@
+name: Checks
+
+on:
+ pull_request:
+ push:
+ branches: [main]
+
+permissions:
+ contents: read
+
+jobs:
+ skill:
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ steps:
+ - uses: actions/checkout@v4
+ - name: Skill docs agree with its files
+ run: python3 .github/scripts/check_skill.py
+ - name: Python scripts (pyflakes errors, no unused-import noise)
+ run: pipx run ruff check --select F,E9 --ignore F401 --output-format concise .claude/skills/papermorph/scripts .github engine
+
+ site:
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ steps:
+ - uses: actions/checkout@v4
+ - name: Engine copies, lint, script syntax
+ run: python3 .github/scripts/check_site.py
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..d641830
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,33 @@
+# Working on Papermorph
+
+Papermorph is a Claude Code Skill that turns a textbook PDF, a story or an argument into a narrated, animated web book: lessons, picture books, and films (documentaries and upright shorts). This file is for an agent changing the repository; the Skill's own instructions for making books are in `.claude/skills/papermorph/SKILL.md`.
+
+## What lives where
+
+- `.claude/skills/papermorph/`: the Skill. `SKILL.md` routes by tier and links every reference directly; `references/core/` holds what every tier shares (style, publish, sound, review, team, engine), `references/lessons/`, `references/picture-books/` and `references/films/` what is each tier's own; `scripts/` the tools; `assets/templates/` the kits a new book is copied from (`scripts/new_book.py`).
+- `engine/`: the one source of the player and drawing engine. Change it here, then copy it into the books with `python3 .claude/skills/papermorph/scripts/engine.py site`; never edit a book's `lib/engine.*` copy. A book's own settings live in its `lib/book.css`, which the sync leaves alone.
+- `site/`: the published books, static files only, with no build step or backend.
+- `books/`, `content/` and `tools/` are the maintainers' private working folders and are not in the repository. Don't recreate them in a commit.
+- Don't add a copyrighted book, its PDF, or lessons made from one.
+
+## Changing the Skill
+
+The Skill is read by models making books, so what it says has to be true and has to be found. These rules come from what went wrong before:
+
+1. **The docs describe what the kits and scripts actually do.** Change the code and its docs in the same commit, and open a template before describing it. A doc once said a chapter page had map lines commented out that only another kit's page had, and an agent spent a step looking for them.
+2. **Reference films and books are built with the kit the Skill ships.** When a reference needed something the kit lacks, move it into the kit, or the reference teaches a path no one else can follow.
+3. **Tools say what they could not do.** A label pushed off frame, an unknown region name, a global that clashes with the engine: print it and name it. A silent skip looks like success to the agent running the tool.
+4. **Shared files hold only what is shared.** `references/core/` is for every tier, and `references/films/films.md` for both documentaries and shorts. A sentence true of one tier or shape goes in that tier's file.
+5. **Each step can get what it needs from the steps before it, and each target comes with the figure to reach it.** A length comes with a words-per-minute figure; a loudness comes with the level to set.
+
+Write Skill guidance as intent, reasons and examples, and give the model ways to see its own output. Avoid lists of bans: they narrow what the model tries, and the owner has turned them down before. Keep each fact in one place and link to it.
+
+## Checks
+
+CI (`.github/workflows/checks.yml`) runs these on every pull request; run them before you push:
+
+- `python3 .github/scripts/check_skill.py` checks links and anchors, that `SKILL.md` links every reference and names every script, that scripts compile, and that flags and paths named in the docs exist.
+- `python3 .github/scripts/check_site.py` (needs Node) checks that every book's engine copy matches `engine/`, runs `lint.py` on every book, and runs `node --check` on every script, inline page scripts included.
+- `pipx run ruff check --select F,E9 --ignore F401 .claude/skills/papermorph/scripts .github engine` catches undefined names and other pyflakes errors in the Python tools.
+- After an engine or page change, serve the site (`python3 .claude/skills/papermorph/scripts/serve.py 8765 site`), play the chapters you touched in a browser, and run `python3 .claude/skills/papermorph/scripts/lint.py site/<book>` and the engine's own checks (`uv run --with playwright engine/check_i18n.py`, `engine/check_latex.py`; `engine/check_volume.py` with the site served on 8767).
+- After a large change to the Skill, have a fresh agent make a short film with the Skill alone, and sort what it trips on under the rules above. If a problem fits none of them, a rule is missing.
diff --git a/README.md b/README.md
index 8d1822a..18a82df 100644
--- a/README.md
+++ b/README.md
@@ -117,7 +117,7 @@ Ticked items are in the Skill today. The Skill currently goes as far as document
## Contributing
-Fixes to the Skill and the player are welcome. Please don't open pull requests that add a copyrighted book, its PDF, or lessons made from one.
+Fixes to the Skill and the player are welcome. Please don't open pull requests that add a copyrighted book, its PDF, or lessons made from one. Agents and people changing the repository: start with [AGENTS.md](AGENTS.md).
## Try the examples locally