# Kywi Docs ## Pages - [Kywi Docs](https://kywi-docs-production.up.railway.app/index.md) - [Building with an agent](https://kywi-docs-production.up.railway.app/agent.md) - [API keys: scopes are a role ceiling](https://kywi-docs-production.up.railway.app/agent/api-keys-scopes-are-a-role-ceiling.md): API keys: scopes are a role ceiling A key’s scopes cap the role its requests run as; read, write and publish together still ceiling below the role that content… - [Brief the agent: the documents a build runs on](https://kywi-docs-production.up.railway.app/agent/brief-the-agent-the-documents-a-build-runs-on.md): Brief the agent: the documents a build runs on Every generated project ships an AGENTS.md header plus the building-patterns guide verbatim, the document meant… - [Hand a module to your agent](https://kywi-docs-production.up.railway.app/agent/hand-a-module-to-your-agent.md): Hand a module to your agent Copy reference gives a module or section a one-line kywi: address; paste it with your request and the agent finds it with… - [Layout writes an agent can and can’t reach](https://kywi-docs-production.up.railway.app/agent/layout-writes-an-agent-can-and-cant-reach.md): The `html` module shows in the catalog like any other, but a layout write introducing one is rejected below `siteAdmin`, even off the admin editor. - [Media through an agent](https://kywi-docs-production.up.railway.app/agent/media-through-an-agent.md): Media through an agent Uploading through `upload_media` means base64-encoding a whole file into one tool call — the server’s filename and allowlist checks fire… - [Point an agent at a Kywi site](https://kywi-docs-production.up.railway.app/agent/point-an-agent-at-a-kywi-site.md): Reaching a Kywi site from an agent means adding the site MCP server’s command, base URL and API key to the client’s own config — by hand. - [Reading a site without duplicating it](https://kywi-docs-production.up.railway.app/agent/reading-a-site-without-duplicating-it.md): Reading a site without duplicating it `list_content` pages results with an explicit `hasMore` flag — stopping at the first page and creating instead of finding… - [Retrofit an existing project for agents](https://kywi-docs-production.up.railway.app/agent/retrofit-an-existing-project-for-agents.md): Retrofit an existing project for agents `create-kywi-app agents` adds AGENTS.md, CLAUDE.md and the four skills to an existing project, skipping anything… - [Review what the agent wrote to kywi.config.ts](https://kywi-docs-production.up.railway.app/agent/review-what-the-agent-wrote-to-kywiconfigts.md): Review what the agent wrote to kywi.config.ts Every developer-server config write lands on disk immediately, with no diff or dry-run step — reviewing it means… - [The developer server’s mode decides your tool list](https://kywi-docs-production.up.railway.app/agent/the-developer-servers-mode-decides-your-tool-list.md): The developer server’s mode decides your tool list Filesystem, API, or auto — one mode wins at startup, and each unlocks a different, non-overlapping slice of… - [The four shipped skills](https://kywi-docs-production.up.railway.app/agent/the-four-shipped-skills.md): The four shipped skills A fresh scaffold installs four Claude Code skills — content model, collections, custom modules, personalization — each loaded at its… - [The order a build wants to happen in](https://kywi-docs-production.up.railway.app/agent/the-order-a-build-wants-to-happen-in.md): The order a build wants to happen in The build-order playbook — model, structure, taxonomy, media, templates, then workflow — is a sequence the… - [Two servers, two jobs](https://kywi-docs-production.up.railway.app/agent/two-servers-two-jobs.md): The site server reads and writes one site’s content over its API; the developer server edits `kywi.config.ts` or scaffolds through that same API. - [What the agent already knows](https://kywi-docs-production.up.railway.app/agent/what-the-agent-already-knows.md): An agent can pull the building-patterns guide and the live module catalog straight from its own tools, so a prompt never needs to restate either. - [When the agent gets it wrong](https://kywi-docs-production.up.railway.app/agent/when-the-agent-gets-it-wrong.md): Most direct content writes leave no audit-log row at all, and the row a workflow write does leave carries the same user id a human edit would. - [Authoring content](https://kywi-docs-production.up.railway.app/authoring.md) - [Categories and tags](https://kywi-docs-production.up.railway.app/authoring/categories-and-tags.md): Categories and tags Categories and tags are both multi-assignable — categories nest into a hierarchy, tags don't — deleting either is immediate: content just… - [Feeds](https://kywi-docs-production.up.railway.app/authoring/feeds.md): Feeds A Feed Display renders empty when its slug is blank, points at a feed on another site, or matches nothing — the public site always filters to published… - [Fields, the body, and the rich-text editor](https://kywi-docs-production.up.railway.app/authoring/fields-the-body-and-the-rich-text-editor.md): Fields, the body, and the rich-text editor Kywi has 18 field types, and every richText field — the Body included — shares one deliberately small rich-text… - [Finding your way around the admin](https://kywi-docs-production.up.railway.app/authoring/finding-your-way-around-the-admin.md): Finding your way around the admin The sidebar is assembled per role rather than per site, and there’s no top-level Content item — Site Tree is where every page… - [Forms and submissions](https://kywi-docs-production.up.railway.app/authoring/forms-and-submissions.md): Forms and submissions A form reaches a page via a module that looks it up by slug; submissions live in a table with no hard link back — trashing the form hides… - [Living with linked components](https://kywi-docs-production.up.railway.app/authoring/living-with-linked-components.md): Living with linked components Editing a linked component and saving asks whether to update every page or detach this one; deleting a component in use always… - [Media](https://kywi-docs-production.up.railway.app/authoring/media.md): Media The media library is scoped to the active site, and deleting a file a page still uses is blocked until you confirm — forcing it leaves that reference… - [Menus](https://kywi-docs-production.up.railway.app/authoring/menus.md): Reach for a managed menu for an external link, a heading-only item, or an order independent of the tree; linked items never go stale when a page moves. - [Module properties, theme tokens, Style Overrides](https://kywi-docs-production.up.railway.app/authoring/module-properties-theme-tokens-style-overrides.md): Every module's own props are editable with no developer needed, and Style Overrides adds four free CSS properties per module — theme tokens aren't wired in yet. - [Publishing, scheduling and expiry](https://kywi-docs-production.up.railway.app/authoring/publishing-scheduling-and-expiry.md): Published At and Expires At fire on a sweep, every minute by default; Expires At can email people; Unpublish At hides a page; Feature Start/End time a callout. - [Regions, sections, columns and modules](https://kywi-docs-production.up.railway.app/authoring/regions-sections-columns-and-modules.md): Regions, sections, columns and modules A page is regions of sections made of columns of modules; variants nest at section or module level, never inside each… - [Reusing a design: layouts vs components](https://kywi-docs-production.up.railway.app/authoring/reusing-a-design-layouts-vs-components.md): Reusing a design: layouts vs components Placing a saved layout copies its sections once; placing a saved component keeps it live-linked, so editing the… - [Saving and undoing in the layout editor](https://kywi-docs-production.up.railway.app/authoring/saving-and-undoing-in-the-layout-editor.md): Undo survives a Save but not a reload. Since 0.25.0, a save that would overwrite a newer save asks you first. - [Shaping the site tree](https://kywi-docs-production.up.railway.app/authoring/shaping-the-site-tree.md): Shaping the site tree Dragging a row only reorders siblings, Move to… only reparents, and Copy only duplicates in place — three gestures, three separate… - [Slugs, paths, and moving a page](https://kywi-docs-production.up.railway.app/authoring/slugs-paths-and-moving-a-page.md): A slug is derived from the title once, at creation; a moved page’s old URL redirects to the new one, and URL Override gives a page its own address. - [The content editor's tabs — and its three save doors](https://kywi-docs-production.up.railway.app/authoring/the-content-editors-tabs--and-its-three-save-doors.md): The content editor's tabs — and its three save doors Layout and Permissions save the moment you act on them, through their own endpoints — every other tab… - [The Layout tab vs "Design on site"](https://kywi-docs-production.up.railway.app/authoring/the-layout-tab-vs-design-on-site.md): The admin Layout tab and the front-of-site "Design on site" overlay edit the same document through the same editor — only the canvas differs. - [The module palette: what’s in it and what’s held back](https://kywi-docs-production.up.railway.app/authoring/the-module-palette-47-built-ins-in-seven-categories.md): The module palette: what’s in it and what’s held back The registry declares 47 modules in seven categories, but the palette shows only 45 (44 for editors) —… - [Translations](https://kywi-docs-production.up.railway.app/authoring/translations.md): Translations Creating a translation clones the source page into a new, publishable draft linked to the original only by matching slug and parent. A translation… - [Trash and recovering deleted work](https://kywi-docs-production.up.railway.app/authoring/trash-and-recovering-deleted-work.md): Trash and recovering deleted work Trash only holds pages and media — categories, tags, menus, components and comments delete immediately with no recovery.… - [Developing the project](https://kywi-docs-production.up.railway.app/developing.md) - [Access control in kywi.config.ts](https://kywi-docs-production.up.railway.app/developing/access-control-in-kywiconfigts.md): Access control in kywi.config.ts Type-level and field-level predicates are functions, so they live only in code — they receive the user and nothing else, and… - [Build a custom module: the three-part contract](https://kywi-docs-production.up.railway.app/developing/build-a-custom-module-the-three-part-contract.md): A custom module is three things that must agree — a defineModule entry, a client component, and one entry in the layer’s module map. - [Changing the content model on a database that has data](https://kywi-docs-production.up.railway.app/developing/changing-the-content-model-on-a-database-that-has-data.md): Changing the content model on a database that has data Schema generation reads config types and admin-created types together, so running it against a… - [Config as code vs. the database](https://kywi-docs-production.up.railway.app/developing/config-as-code-vs-the-database.md): Config as code vs. the database Content types, themes and modules are code; pages, menus, audiences and admin-created types are rows — and the boundary decides… - [Config types, Type Designer types, and extension attributes](https://kywi-docs-production.up.railway.app/developing/config-types-type-designer-types-and-extension-attributes.md): Config types, Type Designer types, and extension attributes Three ways to add fields exist — config types, admin-created types, and extension attributes —… - [Custom-module hazards](https://kywi-docs-production.up.railway.app/developing/custom-module-hazards.md): Modules render in the editor canvas and on the public page from one map, so a throw, a fetch or a non-deterministic id breaks both surfaces at once. - [Designing a content type](https://kywi-docs-production.up.railway.app/developing/designing-a-content-type.md): Designing a content type A content type is a base type plus fields that become real columns in its own table — and fifty field names are already taken by the… - [Designing module props for the person who edits the page](https://kywi-docs-production.up.railway.app/developing/designing-module-props-for-the-person-who-edits-the-page.md): Props are the owner’s editing surface: declaration order decides inline editing, groups turn a long panel into sections, and ax sets what search sees. - [Hooks: content-type hooks and the event bus](https://kywi-docs-production.up.railway.app/developing/hooks-content-type-hooks-and-the-event-bus.md): Hooks: content-type hooks and the event bus Content types carry nine lifecycle hooks; the registry behind them also dispatches comment, category, group, site,… - [Importing from @kywi-software/core](https://kywi-docs-production.up.railway.app/developing/importing-from-kywi-softwarecore.md): A boundary test pins four of the 28 subpaths — ./next, ./next/client, ./next/middleware, ./host — to what may run at the edge, in RSC, or in the browser. - [One config, several sites](https://kywi-docs-production.up.railway.app/developing/one-config-several-sites.md): One config, several sites Sites are matched per request by Host header and reconciled into their database rows by slug at boot, so a new domain is a config… - [Plugins: what one can contribute, and when](https://kywi-docs-production.up.railway.app/developing/plugins-what-one-can-contribute-and-when.md): Plugins: what one can contribute, and when A plugin may contribute hooks, content types, modules, scope extensions and admin nav items — inline or by package —… - [Rendering a page in coupled mode](https://kywi-docs-production.up.railway.app/developing/rendering-a-page-in-coupled-mode.md): Rendering a page in coupled mode One catch-all route resolves the node, personalizes it, hydrates feeds, nav and components, runs your layout transform, then… - [Seeding structure as code](https://kywi-docs-production.up.railway.app/developing/seeding-structure-as-code.md): Seeding structure as code Structure that must be reproducible — types, pages, layouts, menus, media — is written by idempotent scripts against the API, never… - [Shaping the admin your project ships](https://kywi-docs-production.up.railway.app/developing/shaping-the-admin-your-project-ships.md): Shaping the admin your project ships The admin is a registry of surfaces grouped into 25 areas; config denies areas or surfaces at build time and a per-site… - [Signal adapters: feeding the audience builder from code](https://kywi-docs-production.up.railway.app/developing/signal-adapters-feeding-the-audience-builder-from-code.md): Signal adapters: feeding the audience builder from code An adapter declares the fields a rule can target plus a collect or transform function; client,… - [Startup assertions — the config errors that fail a deploy](https://kywi-docs-production.up.railway.app/developing/startup-assertions--the-config-errors-that-fail-a-deploy.md): Startup assertions — the config errors that fail a deploy Four things can fail a Kywi boot, plus two more at config evaluation: a stale layer registry, a split… - [The ax block: what your project publishes to machines](https://kywi-docs-production.up.railway.app/developing/the-ax-block-what-your-project-publishes-to-machines.md): The ax block: what your project publishes to machines Six machine-facing surfaces are configured in one block — llms.txt, llms-full.txt, sitemap, robots,… - [The host-app contract](https://kywi-docs-production.up.railway.app/developing/the-host-app-contract.md): A Kywi host app owes core five wiring points and three stylesheet imports; the render path lives in the package and is not the project’s to hold. - [The local dev loop](https://kywi-docs-production.up.railway.app/developing/the-local-dev-loop.md): The local dev loop Config edits need a restart and content edits do not, and two predev sync steps copy the browser runtime and the admin stylesheet into… - [Themes and design tokens](https://kywi-docs-production.up.railway.app/developing/themes-and-design-tokens.md): Themes and design tokens A theme owns regions, tokens and personalization; tokens become --kywi-* custom properties emitted per request, with key@breakpoint… - [The stylesheet layers of a Kywi project](https://kywi-docs-production.up.railway.app/developing/the-stylesheet-layers-of-a-kywi-project.md): The stylesheet layers of a Kywi project Three stylesheet layers stack in an order Next decides rather than the order your layout imports them: core’s sheet,… - [Upgrading core inside your project](https://kywi-docs-production.up.railway.app/developing/upgrading-core-inside-your-project.md): 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… - [What a field type becomes in Postgres](https://kywi-docs-production.up.railway.app/developing/what-a-field-type-becomes-in-postgres.md): What a field type becomes in Postgres Each field type maps to one Drizzle column — text, varchar, jsonb, uuid, timestamp, boolean or numeric — and boolean is… - [What the scaffold generates — and what it deliberately doesn't](https://kywi-docs-production.up.railway.app/developing/what-the-scaffold-generates--and-what-it-deliberately-doesnt.md): What the scaffold generates — and what it deliberately doesn't Eleven stamped delegate files plus your config, module map and layer folders — the render path… - [Wiring personalization and consent](https://kywi-docs-production.up.railway.app/developing/wiring-personalization-and-consent.md): Wiring personalization and consent Personalization, transparency and the consent gate are theme settings, not site settings — and the consent flag must match… - [Editing your site](https://kywi-docs-production.up.railway.app/editing.md) - [Editing text and images in place](https://kywi-docs-production.up.railway.app/editing/editing-text-and-images-in-place.md): Editing text and images in place Double-clicking a heading, paragraph or rich-text block edits it in place; an image swaps through the properties rail —… - [Personalizing or A/B testing a section in place](https://kywi-docs-production.up.railway.app/editing/personalizing-or-ab-testing-a-section-in-place.md): Personalizing or A/B testing a section in place Wrapping a section in a variant container makes it personalized or split-tested — the section becomes the… - [Rearranging sections and modules in place](https://kywi-docs-production.up.railway.app/editing/rearranging-sections-and-modules-in-place.md): Sections and modules drag to add, reorder and remove, and a column’s width drags via its own handle — nesting a personalized section inside another is refused. - [Saving a section as a reusable component](https://kywi-docs-production.up.railway.app/editing/saving-a-section-as-a-reusable-component.md): Saving a section as a reusable component Editing a section that’s already a shared component forces a choice at save — keep the edit on this page, or push it… - [Saving, publishing, and leaving the editor](https://kywi-docs-production.up.railway.app/editing/saving-publishing-and-leaving-the-editor.md): Save changes the public page at once, Save Draft holds your edit for review, and a failed save keeps the editor open with your changes. - [Turning on edit mode](https://kywi-docs-production.up.railway.app/editing/turning-on-edit-mode.md): A signed-in editor gets a persistent toolbar on any page they can write to; ?kywi-edit=1 opens straight into the editor — both require the page to be published. - [What front-of-site editing can't do](https://kywi-docs-production.up.railway.app/editing/what-front-of-site-editing-cant-do.md): What front-of-site editing can't do The overlay edits layout only — menus, the media library, SEO fields and new pages stay in the admin, and an unpublished… - [Governing content](https://kywi-docs-production.up.railway.app/governing.md) - [Batching and publishing with changesets](https://kywi-docs-production.up.railway.app/governing/batching-and-publishing-with-changesets.md): A changeset batches items into one atomic publish or rollback — rollback returns items to draft rather than restoring what was live before. - [Bypassing the queue: who can transition directly](https://kywi-docs-production.up.railway.app/governing/bypassing-the-queue-who-can-transition-directly.md): Bypassing the queue: who can transition directly Skipping review isn't a siteAdmin privilege — an editor can already move content straight to published, on a… - [Content-level permission overrides](https://kywi-docs-production.up.railway.app/governing/content-level-permission-overrides.md): Content-level permission overrides A content-level grant only restricts a document once the first one exists — with none, a page stays open to anyone your role… - [Managing groups](https://kywi-docs-production.up.railway.app/governing/managing-groups.md): Managing groups A group only ever targets a content-permission grant or owns an approval-chain step; its type and default role aren't read by anything that… - [Managing users, roles, site access](https://kywi-docs-production.up.railway.app/governing/managing-users-roles-site-access.md): Roles and site memberships are global by default — a role change doesn't reach an already-signed-in user until their access token refreshes. - [Moderating comments](https://kywi-docs-production.up.railway.app/governing/moderating-comments.md): Moderating comments Every comment starts pending and stays invisible until approved; flagging an already-live comment pulls it back out of view the same way… - [Passwords: change, admin reset, forced-reset lock](https://kywi-docs-production.up.railway.app/governing/passwords-change-admin-reset-forced-reset-lock.md): Passwords: change, admin reset, forced-reset lock Only a self-service password change clears the forced-reset flag; an admin's reset leaves it set and ends the… - [Reviewing and approving submissions](https://kywi-docs-production.up.railway.app/governing/reviewing-and-approving-submissions.md): The approvals queue merges draft submissions with pending revisions of live pages into one list, and approving either publishes in a single step. - [Roles and the capability matrix](https://kywi-docs-production.up.railway.app/governing/roles-and-the-capability-matrix.md): Roles and the capability matrix Six roles form one strict ladder, and every capability — content actions and every admin surface alike — reduces to a… - [Scheduling a changeset](https://kywi-docs-production.up.railway.app/governing/scheduling-a-changeset.md): Schedule sets a changeset's publish time, but nothing fires it unless the same background sweep that handles content's Published At is running. - [Trash and permanent deletion](https://kywi-docs-production.up.railway.app/governing/trash-and-permanent-deletion.md): Trash and permanent deletion Trash merges soft-deleted content and media into one surface, and Empty Trash has two blast radii — one site for siteAdmin, every… - [Version history and rollback](https://kywi-docs-production.up.railway.app/governing/version-history-and-rollback.md): A restore brings back an old version's fields and layout, takes its status only if your role could make that move, and is itself saved as a new version. - [Integrating](https://kywi-docs-production.up.railway.app/integrating.md) - [Audience adapters: third-party CDP integration](https://kywi-docs-production.up.railway.app/integrating/audience-adapters-third-party-cdp-integration.md): Audience adapters: third-party CDP integration An adapter contributes namespaced signal fields — `client` adapters run in the browser, `server-proxy` adapters… - [Authenticating an external caller](https://kywi-docs-production.up.railway.app/integrating/authenticating-an-external-caller.md): Authenticating an external caller Every caller authenticates through `Authorization: Bearer` — a session JWT, or a `kywi_` API key whose scopes cap the owner’s… - [AX surfaces as a machine-readable feed](https://kywi-docs-production.up.railway.app/integrating/ax-surfaces-as-a-machine-readable-feed.md): Four root surfaces plus a per-page Markdown projection make a site machine-readable; the root four are cached per site, and all five are stamped `X-Kywi-AX`. - [Bulk operations](https://kywi-docs-production.up.railway.app/integrating/bulk-operations.md): Bulk operations Bulk create and update cap at 100 items and refuse any payload carrying a `layout`, and one failing id rejects the whole batch for every route… - [Caching semantics for an integrator](https://kywi-docs-production.up.railway.app/integrating/caching-semantics-for-an-integrator.md): Caching semantics for an integrator Caching is server-side and hook-invalidated: JSON responses send no validators, and only AX surfaces and image variants… - [Discovering the content model at runtime](https://kywi-docs-production.up.railway.app/integrating/discovering-the-content-model-at-runtime.md): Discovering the content model at runtime The content model is discoverable at runtime: five `/config` and `/openapi` reads return content types, the module… - [GraphQL: the read-only subset](https://kywi-docs-production.up.railway.app/integrating/graphql-the-read-only-subset.md): One `POST /graphql` route exposes seven read-only Query fields over types that opted in with `graphql: true`; a query that errors comes back as HTTP 400. - [Media: upload, serving, variants, resize](https://kywi-docs-production.up.railway.app/integrating/media-upload-serving-variants-resize.md): Media: upload, serving, variants, resize Uploads are raw bytes with an `x-filename` header, never multipart; variants come from configured `imageSizes`, and… - [Personalization and experiments from a non-Kywi frontend](https://kywi-docs-production.up.railway.app/integrating/personalization-and-experiments-from-a-non-kywi-frontend.md): Personalization and experiments from a non-Kywi frontend A non-Kywi frontend gets every arm from a headless read and drives personalization and experiments… - [Reading content from outside](https://kywi-docs-production.up.railway.app/integrating/reading-content-from-outside.md): Every content read gates on the row's own site: below an editor of that site you get published rows only, and a hidden row answers 404 like a wrong id. - [Search and feeds as public read endpoints](https://kywi-docs-production.up.railway.app/integrating/search-and-feeds-as-public-read-endpoints.md): Search and feeds as public read endpoints Anonymous search is published-only and offset-addressed; a feed’s `/rss` and `/items` force published-plus-site onto… - [Site scoping and the ?siteId= contract](https://kywi-docs-production.up.railway.app/integrating/site-scoping-and-the-siteid-contract.md): Site resolution runs `?siteId=` first, then a Host match against the configured domains, then `sites[0]` — and most routes take a slug or the DB UUID. - [The browser runtime (kywi-js)](https://kywi-docs-production.up.railway.app/integrating/the-browser-runtime-kywi-js.md): The browser runtime boots itself from `/kywi.js`, reads its context from `kywi:*` meta tags, and enhances nav, forms and feeds even with personalization off. - [The response envelope, pagination and errors](https://kywi-docs-production.up.railway.app/integrating/the-response-envelope-pagination-and-errors.md): The response envelope, pagination and errors Three response envelopes cover the whole API — `{ data }`, `{ data, meta }`, `{ error }` — and `meta.hasMore` is… - [The SDK: what it wraps and what it doesn't](https://kywi-docs-production.up.railway.app/integrating/the-sdk-what-it-wraps-and-what-it-doesnt.md): The SDK: what it wraps and what it doesn't The SDK wraps seventeen route families as typed scopes, turns a 404 body into a normal result, and leaves audiences… - [The three deployment modes](https://kywi-docs-production.up.railway.app/integrating/the-three-deployment-modes.md): The three deployment modes Three deployment modes differ only in which public-render files the scaffold emits — core never branches on `mode` at runtime. mode… - [Topologies that work — and the cross-origin wall](https://kywi-docs-production.up.railway.app/integrating/topologies-that-work--and-the-cross-origin-wall.md): Topologies that work — and the cross-origin wall A decoupled frontend consumes the API server-side: core emits no CORS headers, so a browser on another origin… - [Webhooks](https://kywi-docs-production.up.railway.app/integrating/webhooks.md): Webhooks Eleven lifecycle events POST a signed body to your endpoint: `X-Kywi-Signature` is an HMAC-SHA256 of the exact JSON sent, and the secret is shown only… - [Writing content from outside](https://kywi-docs-production.up.railway.app/integrating/writing-content-from-outside.md): Writing content from outside Creates take `?siteId=` on the query string: the create schema is strict and rejects an in-body `siteId`, and layouts are written… - [Operating](https://kywi-docs-production.up.railway.app/operating.md) - [Applying a hand-written schema patch outside kywi migrate](https://kywi-docs-production.up.railway.app/operating/applying-a-hand-written-schema-patch-outside-kywi-migrate.md): Applying a hand-written schema patch outside kywi migrate Hand-applied SQL is sometimes the only correct path; the cost is that the drizzle journal never… - [AUTH_SECRET and production fail-fast](https://kywi-docs-production.up.railway.app/operating/authsecret-and-production-fail-fast.md): AUTH_SECRET and production fail-fast Kywi refuses to start in production when AUTH_SECRET is missing or set to one of two known dev fallbacks, because tokens… - [Backups: what Kywi does not do for you](https://kywi-docs-production.up.railway.app/operating/backups-what-kywi-does-not-do-for-you.md): Backing up a Kywi deployment is a pg_dump plus the uploads volume, run by you: the CLI ships six commands and none of them is a backup. - [Cache administration](https://kywi-docs-production.up.railway.app/operating/cache-administration.md): Cache administration Two siteAdmin routes report the cache provider with its TTLs and clear every entry; the default in-memory provider is per process, not per… - [Consent policy: the startup-throw and the env mirror](https://kywi-docs-production.up.railway.app/operating/consent-policy-the-startup-throw-and-the-env-mirror.md): Consent policy: the startup-throw and the env mirror Edge middleware cannot read the config, so requireConsent is mirrored as an env var, and the API handler… - [Deploying a host app](https://kywi-docs-production.up.railway.app/operating/deploying-a-host-app.md): Four environment variables, a start command that survives SIGTERM, and a migrate before the push — NODE_ENV only arms one of the three boot checks. - [Email delivery: status and test-send](https://kywi-docs-production.up.railway.app/operating/email-delivery-status-and-test-send.md): Email status echoes the non-secret provider fields and a test send is the only way to tell real SMTP from the console provider Kywi silently falls back to. - [Migrating legacy variant-container content](https://kywi-docs-production.up.railway.app/operating/migrating-legacy-variant-container-content.md): Migrating legacy variant-container content The variant-container migration reports by default and writes only with --apply, refusing any placement that is… - [Multi-site: the domain field and host-based resolution](https://kywi-docs-production.up.railway.app/operating/multi-site-the-domain-field-and-host-based-resolution.md): Multi-site: the domain field and host-based resolution Kywi resolves a site from the request Host header, matched exactly against the domains in config, and… - [Post-migration data steps and why they can silently not run](https://kywi-docs-production.up.railway.app/operating/post-migration-data-steps-and-why-they-can-silently-not-run.md): Post-migration data steps and why they can silently not run Five data steps run around the schema migration, and a database pre-flight that fails skips all… - [Recovering from a stuck host process](https://kywi-docs-production.up.railway.app/operating/recovering-from-a-stuck-host-process.md): Recovering from a stuck host process A failed boot is memoised for the life of the Node process, so every later request replays the same error and recovery is… - [Running migrations against a live database](https://kywi-docs-production.up.railway.app/operating/running-migrations-against-a-live-database.md): Running migrations against a live database Run kywi migrate from your own machine against the production database before you push the deploy, and take a… - [Seeding and demo data commands](https://kywi-docs-production.up.railway.app/operating/seeding-and-demo-data-commands.md): Seeding and demo data commands Two commands bootstrap a database: seed writes the site row, a superAdmin and a home page, and prints the password it just set… - [Site-record public exposure: GET /sites is unauthenticated](https://kywi-docs-production.up.railway.app/operating/site-record-public-exposure-get-sites-is-unauthenticated.md): Site-record public exposure: GET /sites is unauthenticated Every deployment answers an anonymous site-list request with each row of kywi_sites in full: id,… - [The no-consent-banner startup warning (and its false positive)](https://kywi-docs-production.up.railway.app/operating/the-no-consent-banner-startup-warning-and-its-false-positive.md): The no-consent-banner startup warning (and its false positive) One advisory line on the first request reports that nothing places the consent module; it scans… - [Upgrading between minor versions](https://kywi-docs-production.up.railway.app/operating/upgrading-between-minor-versions.md): Upgrading between minor versions A production upgrade is four ordered steps: dump the database, bump the packages, run the scaffold upgrade, then migrate the… - [When migrate can't resolve itself: ambiguous renames](https://kywi-docs-production.up.railway.app/operating/when-migrate-cant-resolve-itself-ambiguous-renames.md): When migrate can't resolve itself: ambiguous renames A rename drizzle-kit cannot infer becomes an interactive prompt, and with no terminal to answer it Kywi… - [Why drizzle-kit push is banned before deploy](https://kywi-docs-production.up.railway.app/operating/why-drizzle-kit-push-is-banned-before-deploy.md): Why drizzle-kit push is banned before deploy Push-mode migration is refused on any project that has a migration journal, and it hung a Railway deployment when… - [Start](https://kywi-docs-production.up.railway.app/start.md) - [Concepts](https://kywi-docs-production.up.railway.app/start/concepts.md) - [Glossary](https://kywi-docs-production.up.railway.app/start/concepts/glossary.md): Glossary Every term the documentation relies on, one line each, linking to the concept page that explains it. Seventy-seven terms, one line each, grouped by… - [How a site is structured](https://kywi-docs-production.up.railway.app/start/concepts/how-a-site-is-structured.md): The vocabulary of a Kywi page — sites, trees, content types, layouts, modules, shared components and media — and where each term is treated in depth. - [How content moves through its lifecycle](https://kywi-docs-production.up.railway.app/start/concepts/how-content-moves-through-its-lifecycle.md): How content moves through its lifecycle The status ladder from draft to archived, plus versions, changesets, trash and audit entries — what each records, and… - [How targeting works](https://kywi-docs-production.up.railway.app/start/concepts/how-targeting-works.md): How targeting works How a visitor becomes an audience and a page becomes arms: signals, rules, scores, variant containers, experiments, consent and the… - [How the platform fits together](https://kywi-docs-production.up.railway.app/start/concepts/how-the-platform-fits-together.md): How the platform fits together Where the engine ends and your project begins: host app, layers, themes, plugins, hooks, adapters, webhooks, caching, migrations… - [Who can do what](https://kywi-docs-production.up.railway.app/start/concepts/who-can-do-what.md): Who can do what Five grantable roles form one ladder; site membership, per-node permissions and API key scopes are the other three things that narrow what a… - [Coupled / headless / decoupled](https://kywi-docs-production.up.railway.app/start/coupled--headless--decoupled.md): Coupled / headless / decoupled Deployment mode decides which files the scaffold gave you, not how the engine behaves — headless and decoupled get an identical… - [Deploy it](https://kywi-docs-production.up.railway.app/start/deploy-it.md): Deploy it Deploying a Kywi app is a Next build plus a Postgres, with one rule — migrations are run by hand, never as a pre-deploy hook. A Kywi deploy is an… - [Install and scaffold](https://kywi-docs-production.up.railway.app/start/install-and-scaffold.md): Install and scaffold Scaffolding asks four questions, then a Kywi project needs a database and a migration before it serves anything, and a seed before you can… - [What Kywi is](https://kywi-docs-production.up.railway.app/start/what-kywi-is.md): Kywi is a CMS engine your Next app mounts, whose pages, audiences and experiments are edited by people and by agents against one API. - [Where to go next](https://kywi-docs-production.up.railway.app/start/where-to-go-next.md): Where to go next Eight surfaces split the documentation by the job you are doing; this page says which one answers your question and what each contains. The… - [Your first site](https://kywi-docs-production.up.railway.app/start/your-first-site.md): Your first site A seeded install gives you a site, a superadmin, an Administrators group and a root node — then you create your first real page in the Site… - [Targeting](https://kywi-docs-production.up.railway.app/targeting.md) - [Checking a rule before you ship it](https://kywi-docs-production.up.railway.app/targeting/checking-a-rule-before-you-ship-it.md): Checking a rule before you ship it The tester proves the rule logic against signals you supply; a preview link forces an audience for whoever opens it, in two… - [How a visitor ends up in one audience](https://kywi-docs-production.up.railway.app/targeting/how-a-visitor-ends-up-in-one-audience.md): How a visitor ends up in one audience A visitor can match several audiences at once, but only the first match in priority order is served — unless they picked… - [Letting visitors tell you who they are](https://kywi-docs-production.up.railway.app/targeting/letting-visitors-tell-you-who-they-are.md): Letting visitors tell you who they are What happens to a self-ID answer: it decides audiences on the server, is kept only with consent, and the page reflects… - [Reading an experiment readout](https://kywi-docs-production.up.railway.app/targeting/reading-an-experiment-readout.md): Reading an experiment readout Significant means a 95%-confidence test against control with at least 100 exposures per arm — never a bare comparison of raw… - [Retiring an audience without breaking pages](https://kywi-docs-production.up.railway.app/targeting/retiring-an-audience-without-breaking-pages.md): Retiring an audience without breaking pages Archiving stops matching without touching a single reference; deleting is guarded by a reference check unless you… - [Running an A/B experiment](https://kywi-docs-production.up.railway.app/targeting/running-an-ab-experiment.md): Running an A/B experiment What it takes for a wrapped section to really split traffic: an experiment created in Admin, named on the container, matching arm… - [Score-based audiences](https://kywi-docs-production.up.railway.app/targeting/score-based-audiences.md): Score-based audiences A threshold changes what an audience means — and five of the six ways to earn points only work if your site runs the optional browser… - [The default arm is the real page](https://kywi-docs-production.up.railway.app/targeting/the-default-arm-is-the-real-page.md): The default arm is the real page Opting out reliably falls back to Default for audiences, but a live A/B split still buckets an opted-out visitor into a real… - [The transparency panel and audience switcher](https://kywi-docs-production.up.railway.app/targeting/the-transparency-panel-and-audience-switcher.md): The transparency panel and audience switcher A hand-picked switch is honored even before consent, unlike the audience the runtime resolves on its own — and a… - [What consent does to your targeting](https://kywi-docs-production.up.railway.app/targeting/what-consent-does-to-your-targeting.md): What consent does to your targeting An undecided visitor loses every stored signal, but a campaign link, a live A/B split, and a hand-picked audience switch… - [What each signal can see, and when](https://kywi-docs-production.up.railway.app/targeting/what-each-signal-can-see-and-when.md): What each signal can see, and when Every rule signal but Pages Visited is decided on the first request; page views and time on site are not rule signals at… - [What is public about a personalized page](https://kywi-docs-production.up.railway.app/targeting/what-is-public-about-a-personalized-page.md): What is public about a personalized page Unserved arms stay out of the page, but the audience rules themselves ship to the browser whenever the client runtime… - [What your rule will actually match](https://kywi-docs-production.up.railway.app/targeting/what-your-rule-will-actually-match.md): What your rule will actually match Groups are OR-ed and conditions inside a group are AND-ed; a "does not equal" rule also matches every visitor missing that… - [Which version of a page a visitor gets](https://kywi-docs-production.up.railway.app/targeting/which-version-of-a-page-a-visitor-gets.md): Which version of a page a visitor gets One precedence decides every arm: a matched audience wins, then a locked winner, then the split assignment, then…