Updates & Versioning

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

Which mode am I in?

If .kide-version exists, the project is embedded (scaffolded embedded, or converted with kide eject). Package-mode projects have no .kide-version and get the runtime from the @kidecms/core dependency.

Package vs embedded

Both modes run the same source. The difference is where the managed runtime directories live and how updates arrive:

	Package mode	Embedded mode
Runtime location	node_modules/@kidecms/core	src/cms/{core,admin,routes,middleware,client,platform,internals}
Update	pnpm add @kidecms/core@latest	pnpm cms:upgrade (patch packet)
Version stamp	none	.kide-version
Switch	pnpm exec kide eject → embedded (one-way)	—

Project-owned files (cms.config.ts, collections/, adapters/, …) are the same in both modes, and no update changes them without your review.

Package mode

pnpm add @kidecms/core@latest

Then read the release notes. They flag two things the dependency bump cannot deliver: schema changes (below) and the rare change to project-owned files, which you apply by hand. Running pnpm exec kide upgrade in a package-mode project prints this guidance instead of starting a patch flow.

Embedded mode

cms:upgrade exists for embedded projects only — the runtime source is vendored in src/cms/, so updates arrive as patches.

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

The command reads the current release from .kide-version, fetches the template repo, and writes an upgrade packet under .kide/upgrade/ with the plan, release notes, diffs, and backups. With a clean worktree it applies the managed-runtime patch (the CMS’s own code) automatically with git apply --3way. 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.

Flag	Effect
--packet-only	Write the packet; change no project files
--apply	Force applying the managed patch (by default it applies only in a clean git worktree)
--allow-dirty	Required with --apply when the worktree has uncommitted changes
--from <ref>	Override the source release read from .kide-version
--repo <url|path>	Override the upstream template repo (default: mhernesniemi/kide-cms)
--core-path <path>	Managed CMS path in this project (default src/cms)
--agent <name>	auto (default), none, claude, codex, or cursor — which agent handoff to print

Start with plan.md in the packet. It says what was applied and what needs review. Files that failed to apply are listed in conflicts.json, and backup/ holds the pre-upgrade copies cms:restore uses. Changes to files outside src/cms/ that aren’t project config (for example src/components/) are only in full-release.patch, for reference.

After an upgrade:

pnpm cms:generate && pnpm check && pnpm test

Then commit together with the updated .kide-version.

.kide-version records the release the embedded runtime is based on (ref, e.g. "v0.27.2"). cms:upgrade reads it and rewrites it on success; don’t edit it by hand.

Rolling back

pnpm cms:restore                                  # restore from the latest packet's backup
pnpm cms:restore --dry-run                        # preview first
pnpm cms:restore .kide/upgrade/v0.26.0-to-v0.27.2 # restore from a specific packet

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

Schema changes

Code ships via the update; the database is a separate file that must be brought to the same shape. Release notes flag every schema change. How it applies:

• Dev — pnpm dev pushes schema changes on boot. Additive changes (new columns, new indexes) apply silently; you do nothing.

• Destructive changes — anything that requires rebuilding a table (e.g. loosening a NOT NULL constraint) is refused by the auto-push, which prints the planned statements instead. Review them, stop the dev server, then run:

  pnpm cms:push --allow-data-loss

  The rebuild copies all rows into the new table — the flag acknowledges the drop-and-recreate, it does not mean data is lost. Back up data/cms.db first regardless.

• Production (Cloudflare D1) — nothing is automatic. Generate migrations (pnpm db:generate) and apply them at deploy time; see the Deploy page.

Eject: package → embedded

pnpm exec kide eject                 # refuses to run on a dirty worktree
pnpm exec kide eject --allow-dirty   # eject anyway

Copies the runtime from the installed @kidecms/core into src/cms/, links it as a workspace package, writes .kide-version, and adds the cms:upgrade and cms:restore scripts. Imports stay the same. From then on the project updates like an embedded scaffold.

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 your installed @kidecms/core version (embedded: the ref in .kide-version), and watch the repo for alerts.