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

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. 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. vX.Y.Z tags preserve past releases; where a template takes image-pin refreshes, vX.Y.Z.N tags preserve those published between them. Upgrade to the branch head, not a tag. Its own .keystone/sync.json names the Keystone version it carries. Proceed when that is newer than the project's, or when the two match and commit differs — the same engine with refreshed image digests. Stop only when both fields agree.
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 a file-level delta (a tree comparison — releases aren't a linear history). Treat it as a hint, not the map: a project assembled from a pin refresh sits at a vX.Y.Z.N tag its sync.json does not name, so the diff against v<version> reports digests it already carries. 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 (e.g. upgrade-keystone).
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 5.
- Files not listed are author-added content, except under .keystone/ — the manifest cannot list itself or its signature. Leave the rest alone.
Re-sync template-owned files. Copy every OK file from the target template over the project's copy, wholesale. This includes all of .keystone/ (so sync.json, checksums.txt and its .sig now describe the target template), .docker/ (so the pinned image tag updates with it), the Makefile, the README, and any new files the release adds. The manifest and its signature move together, or verification fails afterwards.

A release can drop a file too: one the project's manifest lists and the target template's does not. Delete those, 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. 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.

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.