render-derivatives

name	render-derivatives
description	From a populated categorized.json for a version, render by-type.md, by-cat.md, combined.md, and a Typst-compiled combined.pdf with the version in the footer and page numbers. Use after editing categorized.json (summary + items + categories) to produce the human-facing artifacts.

render-derivatives

Reads derivatives/X/Y/Z/categorized.json (the source of truth) and writes:

• by-type.md — items split into Additions, Fixes, Other
• by-cat.md — items grouped by category (UI/UX, Skills, MCP, Hooks, SDK, Permissions, Bash, VSCode, Performance, Auth, Plugins, Telemetry, …); known categories sorted in a stable order, anything else alphabetical, Uncategorized last
• combined.md — by-type.md followed by by-cat.md (single document)
• combined.typ — Typst source generated from the same JSON
• combined.pdf — Typst render of combined.typ with a page break between the by-type and by-category sections, version number bolded in the footer, and page numbers (current / total)

Pipeline

change.md  →  categorized.json  →  { by-type.md, by-cat.md, combined.md, combined.pdf }
                  ^                              ^
                  |                              |
            scaffolded by                  rendered by
       sync-latest-change /             render-derivatives
            pull-change

categorized.json is the only file you edit by hand. The four output files are regenerated from it on each render — do not edit them directly; they will be overwritten.

How to run

python3 scripts/render_derivatives.py 2.1.121

Errors out if categorized.json is missing for that version.

Requirements

• typst on PATH (already present at /usr/local/bin/typst). If absent, the script still writes the markdown files and combined.typ, then warns and skips the PDF.