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

Never upgrade a running project (step 1). Stopping it is the author's call, not yours.
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 4).
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 releases, 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

Stop the project. A wired hook runs between builds. If the new release no longer declares its service, an upgrade leaves the container orphaned.
```
make ps
```
Anything listed: stop and ask the author before running make down; if they decline, stop and report. Nothing listed: continue.
Branch. Create and switch to an upgrade branch.
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).

Compare the two manifests as well — the project's and the target template's. A file the project's lists and the target's does not is one the release removed.
Check the engine — stop if it was customized. Look at whether any runtime file is FAILED — anything under .pandoc/, the Dockerfile, or .docker/, except .docker/docker-compose.yaml. That one is the project's own wiring: a hook service or a mount the author added there is configuration, and step 6 reconciles it.
- 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.
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. Delete the removed ones, leaving any that came back FAILED — the author changed a file with nowhere upstream to merge into, so report those rather than dropping their work.
Reconcile the author's config (the FAILED ones):
- pandoc.yaml, project.conf, .docker/docker-compose.yaml — 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, and carry over any service they wired.
- shortcuts.yaml, publish.txt, fonts/fonts-registry.yaml — author content; keep as-is.

Rebuild and verify.

make image    # rebuild the runtime 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 4, list the customized runtime files and what the author must merge by hand. Leave the changes on the branch for review.