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). The template repos carry no release tags — each release resets them to current, so the default branch is the latest release. 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.

Procedure

  1. Branch. Create and switch to an upgrade branch (e.g. upgrade-keystone).

  2. Classify files. From the project root:

bash 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.

  • 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.

  • 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.

  • Verify and build.

bash 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.