Upgrading core inside your project
Bump the packages, then run the upgrade command: a per-file hash decides what is replaced, refused or kept, and the refusals are the interesting ones.
Two steps, in this order. Bump the packages first — the generated files target the CLI's version, and generating them against an older installed core produces an advisory rather than a working project.
pnpm
pnpm add @kywi-software/core@latest @kywi-software/js@latest @kywi-software/cli@latest @kywi-software/mcp@latestnpm
npm install @kywi-software/core@latest @kywi-software/js@latest @kywi-software/cli@latest @kywi-software/mcp@latestyarn
yarn add @kywi-software/core@latest @kywi-software/js@latest @kywi-software/cli@latest @kywi-software/mcp@latestbun
bun add @kywi-software/core@latest @kywi-software/js@latest @kywi-software/cli@latest @kywi-software/mcp@latestThen npx create-kywi-app@<version> upgrade --dry-run. The dry run is not a separate code path: it plans, applies, reports and computes the exit code exactly as the real run does, with the writes suppressed. Its report and its exit code are therefore the real ones, which is what makes "dry run clean before merging" a rule worth having.
The stamp decides everything
Every generated render file opens with // kywi-render v2 (create-kywi-app 0.23.0) sha256:…, hashing the bytes below that line with no normalisation — no whitespace forgiveness, no line-ending forgiveness. So the command never guesses whether a file is still its own output.
The report words
| Name | Type | Default | Description |
|---|---|---|---|
current | nothing written | — | The file already equals the new emission. |
replaced | overwritten, no backup | — | The stamp is intact — or the file is unstamped but its whole-file hash matches a known historical emission, which is the same proof. Either way it holds no work of yours. |
REFUSED (edited) | left alone | — | Stamped, hash differs. Someone changed it. Exit code 2. |
REFUSED (unstamped) | left alone | — | No stamp and no known-emission match: hand-written, or from a scaffold too old to stamp. Exit code 2. |
created / kept | layer files | — | A |
REFUSED (legacy) / removed | deleted under --force | — | One of six pre-layered glue files whose contents now live in core. A stale copy shadows the real thing, so these are removed rather than replaced. |
There is a third, coarser non-zero exit that never reaches this per-file table at all. When the config scan that regenerates the registry reports a problem — or the project cannot be read as a create-kywi-app project in the first place — the command writes nothing anywhere and exits 1, before a single file is decided. Exit 2 means "some files need your attention"; exit 1 means "the run never started."
A project that has stopped keeping a private copy of core's render path reports nothing but current and kept, and exits 0:
$ npx create-kywi-app@0.21.0 upgrade --dry-run
Upgrading kywi-marketing-v3 (coupled mode)…
(dry run — nothing will be written)
current: lib/kywi.ts
current: middleware.ts
current: app/(site)/layout.tsx
current: app/(site)/[[...slug]]/page.tsx
current: kywi.layers.ts
current: app/api/v1/[...kywi]/route.ts
current: app/llms.txt/route.ts
current: app/llms-full.txt/route.ts
current: app/sitemap.xml/route.ts
current: app/robots.txt/route.ts
current: app/admin/[[...admin]]/page.tsx
kept: sites/default/index.ts
kept: sites/default/themes/default/index.tsx
kept: sites/northwind-analytics-demo/index.ts
kept: sites/northwind-analytics-demo/themes/default/index.tsx
note: AGENTS.md guidance is from create-kywi-app 0.15.1; run `create-kywi-app agents --force` to refresh.
✔ 0 created, 0 replaced, 11 current, 4 kept, 0 refused.What --force does, and what it does not
--force converts refusals into writes, and copies every original into .kywi-upgrade/<timestamp>/ first. Nothing is destroyed, including the six legacy files it deletes. Files replaced without a refusal get no backup line — they were provably unmodified emissions. Add .kywi-upgrade/ to .gitignore; TypeScript already ignores it, because include globs skip dot-prefixed directories.
Three advisories, none of which change the exit code
An ejected artifact whose stamped core version has drifted from the installed one; an installed core on an older minor than the files being generated; and a stale AGENTS.md guidance stamp. All three are notes, so a clean exit code does not mean there is nothing to read.
Taking a component over: eject, not copy
Four of core's client components can become the project's: nav, frontEdit, personalizationRuntime and jsLoader. create-kywi-app eject <artifact> copies one into sites/<site>/themes/<theme>/ and wires it into that layer's templates, so the layer chain renders your copy. Built-in module renderers are not on the list, and an ejected file still carries comments written for core's internals. From the moment you eject, that file stops following core upgrades — which is the point and also the price.
Doing this against a deployed site — the migration, the ordering against a running database, the rollback — is Upgrading between minor versions. What the scaffold owns and what you own is What the scaffold generates.