Updates & Versioning

Which mode am I in?

Check .kide-version. It records "mode": "embedded" or "mode": "package", the release your project came from, and the starter template it scaffolded with ("starter", null for blank). Both modes build from the same source at the same release tag, so updates carry the same content. Only the mechanics differ.

Releases are git tags (v<version>) on the template repo with changes in CHANGELOG.md.

Updating

pnpm cms:upgrade           # to the latest release
pnpm cms:upgrade v0.14.0   # to a specific release

Both modes write an upgrade packet under .kide/upgrade/ with the plan, release notes, diffs, and backups. What happens next depends on the mode:

Package mode — the command bumps @kidecms/core in package.json and updates .kide-version. Run pnpm install, then check the packet’s careful-review.patch: template changes to files you own (a cms.config.ts API change, a script, a config) that a version bump can’t apply for you. Often it’s empty.

Embedded mode — with a clean worktree, the command also applies the managed-runtime patch (the CMS’s own code) automatically. Project-owned files are never auto-patched — they stay in careful-review.patch for review. The packet includes agent-instructions.md, so you can hand the whole thing to any coding agent:

Read .kide/upgrade/<from>-to-<to>/agent-instructions.md and complete the upgrade.

Useful flags: --packet-only (write the packet, touch nothing), --agent none, --allow-dirty --apply.

After any upgrade:

pnpm install        # if dependencies changed
pnpm cms:generate && pnpm check && pnpm test

Rolling back

pnpm cms:restore             # restore from the latest packet's backup
pnpm cms:restore --dry-run   # preview first

It refuses to overwrite files you’ve changed since the upgrade unless you pass --force.

Eject: package → embedded

pnpm exec kide eject

Copies the installed @kidecms/core source into src/cms/ and links it as a workspace package — offline, version-exact, no import changes. From then on the project behaves exactly like an embedded scaffold, release packets and all.

One-way

Ejecting is permanent — you own the runtime source afterwards. Trying embedded mode out? Run eject on a branch. Need just one small runtime tweak? pnpm patch @kidecms/core keeps you in package mode.

Security advisories

Fixes are published as GitHub Security Advisories. Compare affected releases with the ref in your .kide-version, and watch the repo for alerts.