Skip to content

AI-assisted upgrade: core-slim

This page is a procedure an AI assistant can follow to upgrade a core-slim project to a newer Keystone release. Point your assistant at this page and your project directory and ask it to perform the upgrade. It is written to be deterministic and safe — follow it step by step, and stop if anything is ambiguous.

For the human-readable version of what's happening here, 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. These are not part of the template.
  • Preserve the author's configured values. When a config file gains new options, add them; never overwrite a value the author already set.
  • Build at the end to prove the upgrade works. If the build fails or any step is unclear, stop and report rather than guessing.

Inputs

  • Current version — read .keystone/sync.json (version, template).
  • Target template — the current core-slim template from its public repository (https://github.com/knight-owl-dev/keystone-template-core-slim). 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, a SHA-256 manifest of every file as the current template shipped.
  • 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 (e.g. upgrade-keystone).

  2. Classify files. From the project root:

    sha256sum -c .keystone/checksums.txt     # Linux
shasum -a 256 -c .keystone/checksums.txt # macOS
    • OK — unchanged since assembly; belongs to the template.
    • FAILED — the author changed it; handle it in step 4.
    • Files not listed are author-added content; leave them alone.

  3. Re-sync template-owned files. Copy every OK file from the target template over the project's copy, wholesale. This includes .keystone/ itself (so sync.json and checksums.txt now describe the new release), .docker/ (so the pinned image tag updates with it), the Makefile, the README, and any new files the release adds. After this step, every non-authored file matches the target template.

  4. Reconcile the author's files (the FAILED ones). They split in two:

    • pandoc.yaml, project.conf (and .docker/docker-compose.yaml if the author changed it) — the template owns their structure. Start from the target template's version, which carries any new keys in their correct positions with their inline doc comments, and port the author's existing values into it. New options arrive documented; the author's choices are preserved; keep any keys the author added. The new template's compose file already points at the new release's image tag — keep it.
    • shortcuts.yaml, publish.txt, fonts/fonts-registry.yaml — the author's own content. Keep them as-is; do not overwrite the author's entries.

  5. Verify and build.

    make verify   # optional — confirm the new image signature
make all      # prove the project builds against the new release

Report

Summarize for the author: the version moved from → to, which files were reconciled and what new options arrived, the build result, and anything needing their attention. Leave the changes on the branch for review.