# Coupled / headless / decoupled

URL: https://kywi-docs-production.up.railway.app/start/coupled--headless--decoupled
Type: docPage

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.

## Headless and decoupled get an identical file set

Both fall into the same branch of the scaffold's file-building logic, which writes exactly one file beyond the shared set — a placeholder home page, `app/page.tsx`. That file's own text still names the mode ("HEADLESS" or "DECOUPLED" in its comment and its not-found note), the same way `kywi.config.ts`, `README.md` and `AGENTS.md` do — so the file list is identical between the two, the file contents are not. Nothing in core branches on `config.mode` at request time; it's read back only to display in the admin's Settings panel. Choosing "headless" over "decoupled" names an intention for how you plan to consume the API — from inside this same app later, or from a separate frontend now — not a runtime behavior. See [The three deployment modes](/integrating/the-three-deployment-modes/) for the runtime half of this.

## 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](/integrating/the-three-deployment-modes/), [Topologies that work, and the cross-origin wall](/integrating/topologies-that-work--and-the-cross-origin-wall/), and [Rendering a page in coupled mode](/developing/rendering-a-page-in-coupled-mode/).
