# Upgrading core inside your project

URL: https://kywi-docs-production.up.railway.app/developing/upgrading-core-inside-your-project
Type: docPage

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.

{pm} add @kywi-software/core@latest @kywi-software/js@latest @kywi-software/cli@latest @kywi-software/mcp@latest

Then `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

What each line of an upgrade report means for one file. Of these six per-file outcomes, only the two refusals — edited and unstamped — leave a file untouched and exit non-zero (2), and those are the two that need a decision from you.

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.

## the shape to aim for

## A release that changed nothing still reports “replaced”

The comparison includes the generator's version label, not only the body hash. On a release where every stamped file's content hash is identical in both emissions, the report still says `11 replaced` and a real run rewrites all eleven — changing only the version inside each header line. Read the diff before assuming a release touched your render path.

## 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.

## Grep for the six retired files before you force

`upgrade` knows which landmark files it is deleting. It has no idea which of *your* files import them, so a non-landmark module importing `lib/site.ts` or `lib/config.ts` compiles right up until the moment they are gone. This project hit it twice on the same migration, in an API route and in a feed helper. Grep for imports of all six names first, repoint them at `@kywi-software/core/next`, and force after that.

## 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.

## agents --force rewrites guidance files whole

The third advisory tells you to run `create-kywi-app agents --force`. Without `--force` an existing file is skipped; with it, each guidance file is overwritten outright — no merge, no backup. Anything hand-maintained inside `AGENTS.md` is gone. Keep project-specific guidance in a clearly-marked section, recover it with `git log -p -- AGENTS.md`, and restore it in the same commit as the refresh.

## 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](/operating/upgrading-between-minor-versions/). What the scaffold owns and what you own is [What the scaffold generates](/developing/what-the-scaffold-generates--and-what-it-deliberately-doesnt/).
