Paper feature build (changed chapters + latexdiff)
Quick preview of a paper folio’s branch: render the paper with the sci print template (plus the folio’s notation fragment when it has one), then compile ONLY the chapters changed against a base ref, and a colored and a plain latexdiff of each. A preview, never a publish build. Run from the folio.
Skills it satisfies
A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.
latex-build-cache
LaTeX build performance. What works is the iterative loop: a static preflight with no TeX, Tool tex-install for an engine, Tool paper-feature-build for quick changed-chapter builds with latexdiff, then the full build. Both standard preamble/diagram caching mechanisms failed on this toolchain, so there is no cache; read the negative results before attempting one.
Source: folio-assistant-sci/skills/content/folio-paper-adapter/latex-build-cache.md.
Also satisfied by: latex-image, tex-install.
The skill declares no I/O contract (schemas/skills/latex-build-cache/{input,output}.schema.json).
Inputs and outputs
Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | base | Branch | The ref to diff against. Default origin/main. | string · pattern ^[A-Za-z0-9][A-Za-z0-9._/-]*$ · A git branch name | |
| in | chapters | Slug | Chapter slugs, comma-separated. Default: the chapters whose sources changed against base. | string · pattern ^[a-z0-9][a-z0-9-]*$ · A folio slug, e.g. quantum-observable-universe | |
| in | paper | Slug | The paper’s slug. Default: the folio’s only paper; with several, the tool refuses and names them. | string · pattern ^[a-z0-9][a-z0-9-]*$ · A folio slug, e.g. quantum-observable-universe | |
| in | out | RepoPath | Output directory, which the folio should gitignore. Default build-feature. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | notation | RepoPath | The folio’s notation fragment, appended after the template. Default <paper dir>/latex/notation-preamble.tex when present. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | preload | RepoPath | Bun preload that configures the platform’s injected registries (values, Lean packages). Default scripts/preload-registry.ts when present. It must import the same platform checkout as this tool. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| out | preview | RepoPath | <out>/changed.pdf, <out>/<chapter>.diff-color.pdf and .diff-plain.pdf, with the logs and <out>/build.log beside them. The render also rewrites the folio’s chapters/ and main.tex. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
Processes and tasks
No process step names a skill this Tool satisfies.
How it is deployed and reached
- Command line. From the repository root:
bash folio-assistant-sci/adapters/paper/latex/feature-build.sh. - GitHub Actions. No workflow in this checkout runs its command.
As an API: its operation in the OpenAPI document and the MCP tool list of its layer.
| install | none |
| runtime | bun, git, bash |
| network | no |
| when to choose it | |
|---|---|
| when | Iterating on a paper’s prose or mathematics, before a full build: you want to see the changed chapters typeset, and what changed, in a minute or so instead of compiling the whole paper. |
| limits | A preview: cross-references outside the build show ‘??’, margin notes are off by default (FAST_PREVIEW=1, about 2x faster), and a chapter’s base latexdiff degrades to ‘all added’ when the base ref has no committed chapter .tex. Needs pdflatex/latexmk for the PDFs and latexdiff for the diffs; without them only the render runs. |
| cost | One paper render (about 20-40 s on a 2,900-block paper) plus one pdflatex compile per output PDF. |
What it is made of
| role | file | |
|---|---|---|
| definition | folio-assistant-sci/tools/paper-feature-build/paper-feature-build.ts | |
| script | folio-assistant-sci/adapters/paper/latex/feature-build.sh |
Linked data
The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/folio-assistant-sci/tools/paper-feature-build.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.
{
"@context": "https://litlfred.github.io/folio-assistant/folio-assistant-sci/folio-assistant-sci.context.jsonld",
"@id": "https://litlfred.github.io/folio-assistant/folio-assistant-sci/tools/paper-feature-build.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/folio-assistant-sci/folio-assistant-sci.jsonld",
"name": "paper-feature-build",
"title": "Paper feature build (changed chapters + latexdiff)",
"description": "Quick preview of a paper folio's branch: render the paper with the sci print template (plus the folio's notation fragment when it has one), then compile ONLY the chapters changed against a base ref, and a colored and a plain latexdiff of each. A preview, never a publish build. Run from the folio.",
"install": {
"none": true
},
"invoke": {
"shell": "bash folio-assistant-sci/adapters/paper/latex/feature-build.sh"
},
"io": {
"inputs": [
{
"name": "base",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Branch",
"description": "The ref to diff against. Default `origin/main`.",
"required": false,
"arg": {
"flag": "--base"
}
},
{
"name": "chapters",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Slug",
"description": "Chapter slugs, comma-separated. Default: the chapters whose sources changed against `base`.",
"required": false,
"arg": {
"flag": "--chapters"
}
},
{
"name": "paper",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Slug",
"description": "The paper's slug. Default: the folio's only paper; with several, the tool refuses and names them.",
"required": false,
"arg": {
"flag": "--paper"
}
},
{
"name": "out",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Output directory, which the folio should gitignore. Default `build-feature`.",
"required": false,
"arg": {
"flag": "--out"
}
},
{
"name": "notation",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The folio's notation fragment, appended after the template. Default `<paper dir>/latex/notation-preamble.tex` when present.",
"required": false,
"arg": {
"flag": "--notation"
}
},
{
"name": "preload",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Bun preload that configures the platform's injected registries (values, Lean packages). Default `scripts/preload-registry.ts` when present. It must import the same platform checkout as this tool.",
"required": false,
"arg": {
"flag": "--preload"
}
}
],
"outputs": [
{
"name": "preview",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "`<out>/changed.pdf`, `<out>/<chapter>.diff-color.pdf` and `.diff-plain.pdf`, with the logs and `<out>/build.log` beside them. The render also rewrites the folio's `chapters/` and `main.tex`."
}
]
},
"satisfies": [
"latex-build-cache"
],
"requirements": {
"runtime": [
"bun",
"git",
"bash"
],
"network": false
},
"selection": {
"when": "Iterating on a paper's prose or mathematics, before a full build: you want to see the changed chapters typeset, and what changed, in a minute or so instead of compiling the whole paper.",
"limits": "A preview: cross-references outside the build show '??', margin notes are off by default (`FAST_PREVIEW=1`, about 2x faster), and a chapter's base latexdiff degrades to 'all added' when the base ref has no committed chapter .tex. Needs pdflatex/latexmk for the PDFs and latexdiff for the diffs; without them only the render runs.",
"cost": "One paper render (about 20-40 s on a 2,900-block paper) plus one pdflatex compile per output PDF."
}
}