Add template file manifest to enable cleanup of leftover files during template switch

[lex57ukr]

Goal

Enable safe cleanup of leftover template files when switching between templates by introducing a manifest that tracks template-owned files.

Scope

• Define a TemplateFiles property (or similar) in the template's sync metadata to store a list of relative paths for template-owned files
• Templates are responsible for declaring their own manifest; the CLI reads it but does not generate it
• Implement manifest comparison logic during SwitchTemplateAsync to identify files that exist in the old template but not in the new one
• Add an opt-in flag (e.g., --clean-leftovers or --clean) to the switch template command to enable deletion of orphaned template files
• Respect existing EntryModelPolicies to ensure user content directories are never deleted
• Gracefully handle templates without a manifest (older versions): cleanup is not possible, warn the user

Outcome

Users who switch templates will have the option to get a clean result without manually hunting down and removing obsolete files from the previous template. The default behavior remains safe (no deletion), preserving backward compatibility.

Notes

• The manifest is template-owned: each template declares which files belong to it
• If either the old or new template lacks a manifest, cleanup cannot be performed safely and the CLI should inform the user
• Consider whether the manifest should track file hashes to detect user modifications to template files (future enhancement)
• Related code: ProjectService.SwitchTemplateAsync, KeystoneSyncModel, EntryModelPolicies.ExcludeUserContent

[lex57ukr]

The upstream manifest is now implemented and shipping with all Keystone template variants (since v1.8.1, trust model refined in v1.8.2).

What's available

Every assembled template includes a .keystone/ directory with:

File	Purpose
checksums.txt	SHA-256 checksums for every file in the template (GNU coreutils format)
checksums.txt.sig	GPG detached signature over checksums.txt
sync.json	Sync metadata (source commit, timestamp, variant repo)

The public key is not bundled in templates — that would be circular trust (a bundled key verifying its own bundle). Instead, the key is distributed independently via the org verification guide.

Manifest format

checksums.txt uses GNU coreutils format — checksum first, compatible with sha256sum -c:

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855  .editorconfig
a1b2c3d4...  Makefile
...

Paths are relative to the template root. The manifest itself and its signature are excluded from the checksums.

What the CLI can use this for

• File inventory: checksums.txt is the authoritative list of template-owned files — parse the second column for relative paths
• Modification detection: compare stored checksums against current file hashes to identify user-modified template files
• Switch cleanup: diff the old template's manifest against the new one to find orphaned files for --clean
• Integrity verification: validate checksums before acting on a template download

Verifying signature integrity

The manifest is GPG-signed. The CLI (or users) can verify the signature to confirm the template hasn't been tampered with since assembly.

Import the public key from the org verification guide, then:

gpg --verify .keystone/checksums.txt.sig .keystone/checksums.txt

macOS:

shasum -a 256 -c .keystone/checksums.txt

Linux:

sha256sum -c .keystone/checksums.txt

References

• Manifest implementation: knight-owl-dev/keystone#106
• Trust model refinement: knight-owl-dev/keystone#108