How the platform fits together
Where the engine ends and your project begins: host app, layers, themes, plugins, hooks, adapters, webhooks, caching, migrations and AX surfaces.
Kywi is a package your project mounts, not a framework your project lives inside of. That distinction runs through every term below: what the engine owns outright, what a project supplies on top of it, and what the platform keeps and publishes without either side having to ask.
The seam between the engine and your project
host app vs core engine
Core cannot import your kywi.config.ts — a published package has no path back into the project that installed it — so the inversion runs the other way: your project hands it in once. What a host app owes core is five thin wiring files plus three stylesheet imports Next keeps out of the package; the whole rest of the render path is core's, and upgrades with it. See The host-app contract.
deployment mode
Deployment mode is a required field answered once, at scaffold time, and it decides exactly one thing: which files create-kywi-app writes. Nothing in core branches on it at runtime — coupled additionally gets the public render path, while headless and decoupled emit a near-identical file set differing only in a comment and a README section. See The three deployment modes and, for the choice itself, Coupled / headless / decoupled.
One codebase, several looks
layer
Three layers, and core is one of them: core owns a working default for everything renderable, so a project supplying nothing below it still renders. Under core sits the site layer, sites/<slug>/, for overrides shared across that site's themes, and inside it the theme layer for presentation. Configuration does not move down — it stays in kywi.config.ts. See What the scaffold generates — and what it deliberately doesn't and The host-app contract.
override by placement
Resolution runs theme → site → core, first hit wins. A lower layer overrides by supplying a same-named artifact, never by editing the one above — which is what lets an upgrade replace core wholesale. And the chain is not a filesystem scan: a generated registry, kywi.layers.ts, enumerates it at build time and is rewritten on upgrade, not hand-edited. See What the scaffold generates — and what it deliberately doesn't and The host-app contract.
What a project styles and configures on top
theme
A theme is a small, fixed shape — a name, the regions it defines, and optional tokens, personalization settings and a custom-value policy — declared in code and named by a site's own config, not something an admin can switch. What a theme visually draws lives in its layer, keyed by the same name; what it declares about itself lives in this object. See Themes and design tokens.
design token
A design token is a named value in one of a theme's five categories — colors, spacing, typography, border radius, shadow — emitted as a --kywi-* CSS custom property on every request, keyed to whichever site the Host header resolved to. A token suffixed @breakpoint becomes a media-query override of the same variable rather than a second variable. See Themes and design tokens.
Five ways to extend a running project
plugin
A plugin is a config entry, declared inline or referenced by package name, that can contribute hooks, content types, modules, scope extensions and admin nav items. One whose content type or module name collides with the app's own is silently dropped in the app's favour; one that fails to load is skipped rather than taking boot down. See Plugins: what one can contribute, and when.
hook
A content type declares nine lifecycle hooks, and only validate can stop a write; the rest transform data or observe after the fact. Underneath sits a much wider event bus that comments, trash, versions and more dispatch onto and plugins subscribe to by name — but nothing on that bus can reject anything: it fires only after the write is decided. See Hooks: content-type hooks and the event bus.
adapter (pull / push)
An adapter is a small typed object — an id, a side, field names, one function — that feeds the audience rule builder from outside the platform. A pull adapter runs: something calls it, and what comes back becomes signals a rule can match on. A push adapter type-checks and registers identically, but nothing anywhere calls it. See Signal adapters: feeding the audience builder from code and Audience adapters: third-party CDP integration.
webhook event
A webhook event is one of eleven named lifecycle moments — content published, a comment approved — an endpoint can subscribe to; Kywi signs the exact bytes it sends with an HMAC over your endpoint's secret. Saving a page's layout is not on the list: it dispatches a different event that only invalidates caches, so an endpoint waiting on the closest-sounding webhook never fires. See Webhooks.
scope
In the SDK, a scope is one typed slice of the REST API — content, media, nav, and fourteen more, seventeen in all. Large parts of the API have no scope at all: audiences, experiments, changesets, bulk operations and cache administration are calls you make with a plain fetch and your own types. See The SDK: what it wraps and what it doesn't.
What the platform keeps and publishes on its own
cache key namespace
The server cache is keyed by a fixed set of namespaces, each prefixed by the site it belongs to — content, feeds, nav, menus, the resolved site config, one per AX surface. One content mutation clears several at once, which is what makes a publish visible immediately rather than after a TTL. The admin's clear-cache action, though, is deployment-wide rather than site-scoped. See Caching semantics for an integrator and Cache administration.
migration journal
The migration journal is the record of every schema change kywi migrate has applied, grown by drizzle-kit generate each time the command runs. Push-mode migration writes straight to the database without touching that record, which is why it is refused on a project that already has a journal and banned from a deploy hook. See Running migrations against a live database and Why drizzle-kit push is banned before deploy.
Agent Experience (AX)
Agent Experience is the collective name for six machine-facing surfaces a Kywi site publishes without an API key or a session, all configured from one block. Every surface defaults on except the per-page Markdown twin, which defaults off, and the cacheable ones clear on the same content-mutation event the rest of the cache does. See AX surfaces as a machine-readable feed and The ax block: what your project publishes to machines.
extension subtype / attribute set
Extension attributes are the third way to add fields to content, and the only one that adds no column and needs no migration, ever. A subtype and its attribute set define what an extension can hold. The cost is reach: a value stored this way is reachable only by content id, so it cannot back a feed or an audience rule. See Config types, Type Designer types, and extension attributes.