Skip to content

AI-assisted upgrade: core

This page is a procedure an AI assistant can follow to upgrade a core project to a newer Keystone release. Point your assistant at this page and your project directory and ask it to perform the upgrade. Follow it step by step, and stop if anything is ambiguous.

core ships the engine source and builds the image locally, so an upgrade can be as simple as a core-slim one — unless you've customized the engine, in which case this procedure stops and hands back to you. For the human-readable background, see Upgrading your project.

Guardrails

  • Work on a new git branch; never commit to the default branch directly.
  • Never modify the author's content — manuscript/, assets/, and any files the author added.
  • Preserve the author's configured values. Add new config options; never overwrite a value the author already set.
  • Do not auto-merge the engine. If the author has modified the runtime, stop and report (step 3).
  • Build at the end. If it fails or any step is unclear, stop and report.

Inputs

  • Current version — read .keystone/sync.json (version, template).
  • Target template — the current core template from its public repository (https://github.com/knight-owl-dev/keystone-template-core). Each release advances the default branch, so it is the latest release; per-release vX.Y.Z tags preserve past snapshots, but upgrade to the branch head, not a tag. Its own .keystone/sync.json names the Keystone version it carries; confirm that's newer than the project's before proceeding.
  • Change map — .keystone/checksums.txt.
  • Upstream diff (optional) — if the project's version is tagged on the template repo, git diff v<version> origin/main gives the exact file-level delta this upgrade applies (a tree comparison — releases aren't a linear history). Versions released before tagging began have no tag.

Procedure

  1. Branch. Create and switch to an upgrade branch.

  2. Classify files. From the project root:

    sha256sum -c .keystone/checksums.txt     # Linux
shasum -a 256 -c .keystone/checksums.txt # macOS

    OK = template-owned and untouched. FAILED = author-changed. Unlisted = author-added content (leave alone).

  3. Check the engine — stop if it was customized. Look at whether any runtime file is FAILED — anything under .pandoc/, the Dockerfile, or .docker/.

    • Any runtime file FAILED → the author has forked the engine. Stop here. Report the list of modified runtime files and explain that merging engine changes is a manual judgment call (see Customizing). Do not proceed.
    • No runtime file FAILED → the engine is stock; continue.

  4. Re-sync template-owned files. Copy every OK file from the target template over the project's copy, wholesale — the engine source under .pandoc/, the Dockerfile, .docker/, .keystone/ (re-baselining sync.json and checksums.txt to the new release), the Makefile, the README, and any new files the release adds.

  5. Reconcile the author's config (the FAILED ones):

    • pandoc.yaml, project.conf — start from the target template's version (new keys in their correct positions, with their inline doc comments) and port the author's existing values in. New options arrive documented; the author's choices are preserved; keep any keys the author added.
    • shortcuts.yaml, publish.txt, fonts/fonts-registry.yaml — author content; keep as-is.

  6. Rebuild and verify.

    make image    # rebuild the engine image from the new source
make all      # prove the project builds against the new release

Report

Summarize for the author: the version moved from → to, which files were reconciled, the build result, and anything needing attention. If you stopped at step 3, list the customized runtime files and what the author must merge by hand. Leave the changes on the branch for review.