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.

porttyperequireddescriptionconstraint
inbaseBranchThe ref to diff against. Default origin/main.string · pattern ^[A-Za-z0-9][A-Za-z0-9._/-]*$ · A git branch name
inchaptersSlugChapter 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
inpaperSlugThe 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
inoutRepoPathOutput 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.
innotationRepoPathThe 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.
inpreloadRepoPathBun 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.
outpreviewRepoPath<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.

installnone
runtimebun, git, bash
networkno
when to choose it
whenIterating 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.
limitsA 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.
costOne paper render (about 20-40 s on a 2,900-block paper) plus one pdflatex compile per output PDF.

What it is made of

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

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev