Coupled / headless / decoupled
Deployment mode decides which files the scaffold gave you, not how the engine behaves — headless and decoupled get an identical file set.
Mode is answered once, at scaffold time, and it decides exactly one thing: which files create-kywi-app writes into your project. Nothing about it is a runtime switch, and no config value changes what the engine does with a request based on mode.
What every mode gets: the same file set
package.json, kywi.config.ts, tsconfig.json, types/css.d.ts, next.config.mjs, .env.example, .gitignore, README.md, AGENTS.md and CLAUDE.md plus the four Claude Code project skills, lib/kywi.ts, lib/modules.tsx, kywi.layers.ts plus the layer folders it names, middleware.ts, app/layout.tsx, app/icon.svg, the admin catch-all (app/admin/[[...admin]]/page.tsx — the full admin, every surface), the API catch-all (app/api/v1/[...kywi]/route.ts), and the four Agent Experience root routes — llms.txt, llms-full.txt, sitemap.xml, robots.txt. Headless does not mean "no admin," and it does not mean "no agent surfaces." Every mode ships the same complete admin and the same machine-facing routes; what differs is only whether there is also a public site to render.
Same file set is not the same bytes, though. kywi.config.ts records the mode you chose in its own config object, and README.md and AGENTS.md each carry a sentence that names the mode — so a diff between two scaffolds run with different modes is never empty, even where the file list matches exactly.
What only coupled adds
Public rendering: app/(site)/layout.tsx, app/(site)/site.css, components/site-nav.tsx, app/(site)/[[...slug]]/page.tsx, and a scripts/sync-kywi-admin-css.mjs step wired into predev/prebuild. The theme layer file each site gets is also coupled-only in substance: its templates export carries a nav entry in coupled mode and is empty everywhere else — the registry file that names it, kywi.layers.ts, is unaffected by mode, but what it points at is not.
Choosing later
There's no command that converts a project between modes. What does happen automatically: create-kywi-app agents re-reads the mode from kywi.config.ts with a regex when it refreshes agent guidance, and create-kywi-app upgrade regenerates the layer registry and layer files from the project's own config. Neither one rewrites the render-path files that make coupled mode public — that's a decision you make once, at scaffold time.
The consequences of the choice — where each mode actually renders, why core sends no CORS headers, and what a coupled render path does per request — are documented once, on Surface 6 and 7, not repeated here: The three deployment modes, Topologies that work, and the cross-origin wall, and Rendering a page in coupled mode.