# Kywi Docs ## Kywi Docs URL: https://kywi-docs-production.up.railway.app/ Type: page Updated: 2026-09-02T06:21:01.879Z ## Building with an agent URL: https://kywi-docs-production.up.railway.app/agent Type: docPage Updated: 2026-09-03T05:47:52.890Z ## API keys: scopes are a role ceiling URL: https://kywi-docs-production.up.railway.app/agent/api-keys-scopes-are-a-role-ceiling Type: docPage Updated: 2026-09-03T05:47:52.877Z # 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 deletion requires. An API key's scopes don't grant a role directly — each scope maps to the highest role it allows, and every request the key makes runs as whichever is lower: that ceiling, or the role of the person who created the key. ## The ceiling each scope buys `read` ceilings at **reader**; `write` at **author**; `publish` at **editor**; `admin` and `developer` both ceiling at **siteAdmin**. No scope reaches **superAdmin** — the most destructive operations stay session-only regardless of what a key is scoped to. Combining scopes takes the highest ceiling among them, not the sum: `read` plus `write` plus `publish` still ceilings at editor, one level below what deleting content requires. ## Why read + write + publish still can’t delete Content actions carry their own minimum role — reading needs reader, writing needs author, publishing needs editor, deleting needs siteAdmin. A key scoped `read, write, publish` ceilings at editor, so it 403s the moment it tries `delete_content`, no matter how permissive the key's owner is. Reaching siteAdmin from a key means adding `admin` or `developer` to its scopes specifically — there's no path to it through the content-action scopes alone. ## the scopes a key carries — the same list the admin’s key form offers ## Key management is an api-mode-only tool set `create_api_key`, `list_api_keys` and `revoke_api_key` register only when the developer server resolves to api mode — see [The developer server's mode decides your tool list](/agent/the-developer-servers-mode-decides-your-tool-list/). In filesystem mode, none of the three exist to call. ## These three tools call the wrong path, and say nothing about it As shipped, every call to `create_api_key`, `list_api_keys` or `revoke_api_key` hits `/api-keys`, and the route Kywi actually registers is `/auth/api-keys`. What you will see is not an error: the HTTP client treats a 404 as a result rather than a failure and hands the body straight back, so the tool answers, looking successful, with `{"error":{"code":"NOT_FOUND","message":"Route not found"}}`. An agent that doesn't read that payload will tell you the key was created. Nothing was created. ## A person creates the key, not an agent Correcting that path would not make `create_api_key` work. The create route refuses any request that authenticated with an API key at all — an API key cannot create API keys — and the developer server has no other way to authenticate: it sends `KYWI_MCP_DEV_KEY` on every request. A read-scoped key that could mint an admin-scoped one would walk straight past the ceiling this page is about, so key creation is session-only on purpose: a signed-in person, in the admin, under **Web Services → API Keys** (reachable by any editor, not just a siteAdmin). Listing and revoking carry no such rule — those two would work from the developer server once the path is fixed. ## The ladder these ceilings sit on The five roles a ceiling or a content action can name are the same ladder used everywhere else in Kywi, from session logins to content permissions. See [Roles and the capability matrix](/governing/roles-and-the-capability-matrix/) for what each level can do outside of API keys. ## Brief the agent: the documents a build runs on URL: https://kywi-docs-production.up.railway.app/agent/brief-the-agent-the-documents-a-build-runs-on Type: docPage Updated: 2026-09-03T05:47:52.878Z # 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 to brief an agent — CLAUDE.md just points at it. `AGENTS.md` is the document a build actually runs on. `CLAUDE.md` exists only to send a Claude Code session there — it holds no guidance of its own beyond that pointer. ## What AGENTS.md actually contains The file opens with a short, project-specific header: a sentence naming the deployment mode, a "Where things live" list built from what the generator finds on disk in *this* project, and the three commands that bring it up (`pnpm migrate`, `pnpm seed`, `pnpm dev`). Everything after that header is Kywi's canonical building-patterns guide, appended in full and unmodified — not a summary, not an excerpt. Reading `AGENTS.md` means reading both: the header tells an agent what's true of this project, the guide tells it what's true of Kywi. ## CLAUDE.md is three paragraphs It says to read `AGENTS.md` first, states the core principle — model content in the CMS instead of hardcoding it — and, in its last line, names all four skills: `kywi-content-model` for anything not built yet, plus a pointer to the collections, custom-modules and personalization skills alongside it in `.claude/skills/`. That's the whole file. If you're looking for project-specific guidance and only find generic instruction to go elsewhere, you're reading the wrong one. The header's "Where things live" bullets are assembled from what's actually on this project's disk rather than fixed boilerplate, and the version stamp at the top of `AGENTS.md` is not a freshness check — see [retrofitting an existing project](/agent/retrofit-an-existing-project-for-agents/) for both, and for how to refresh a stale copy deliberately. ## Hand a module to your agent URL: https://kywi-docs-production.up.railway.app/agent/hand-a-module-to-your-agent Type: docPage Updated: 2026-11-11T02:42:50.670Z # 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 resolve_ref instead of guessing. Describing a module to an agent ("the heading in the second band on /about") makes it read the whole layout and guess. Instead, copy the module's reference in the editor and paste it into your request. The agent passes the line to `resolve_ref` on the site MCP server, gets back exactly where that node is and what it holds, and either edits it or tells you why it shouldn't. ## Copy the reference Every module and section in the layout editor has a **Copy reference** action: the link icon in a module's action bar, and a labeled button in a section's toolbar. It is there in both the admin Layout tab and Design on site, including modules and sections inside a personalization or A/B arm. It isn't offered while you edit a reusable component's definition or a blueprint, or on a page that hasn't been created yet, because none of those is a page an agent can address. Copying changes nothing on the page: no unsaved changes, no entry in undo history, nothing selected or deselected. You'll see **Reference copied**. If the browser won't give the editor the clipboard, the line appears in a field, already selected, for you to copy by hand. ## What the line says kywi:marketing/page/3f2a91c0-5b7d-4e2a-9c1f-8d6e0b4a2c17/m/7c91e2d4-0a3b-4f6e-8d2c-1b5a9e7f3c60 — Heading "Run the whole room" on /about Everything before the dash is the address: the site, the content type, the page's id, `m` for a module or `s` for a section, and the node's id. The site is the site's slug when the editor knows it, otherwise its id or `_`; the page id alone is enough to find the page. After the dash is what you were looking at — the module's name, the start of its text and the page's path, or for a section its first text and how many modules it holds. The agent uses that to check it found the thing you meant. ## The default page, or a variant A page variant or a page-level A/B variant starts as a copy of the default page and keeps its node ids, so the same id can be in several versions of one page. A reference copied while one of those is on screen ends with `@pv:…` or `@ab:…:…` to say which. A reference without that ending always means the default page. If the node has since gone from the default page but still exists in a variant, the agent gets the locations and no edit arguments, and should ask you which one you meant. Copying the reference again from what's on screen settles it. ## Paste it with the request kywi:marketing/page/3f2a91c0-5b7d-4e2a-9c1f-8d6e0b4a2c17/m/7c91e2d4-0a3b-4f6e-8d2c-1b5a9e7f3c60 — Heading "Run the whole room" on /about Make this heading shorter, under six words, same meaning. ## Using the site MCP server. Replace the first line with the line you copied. The agent calls resolve_ref with the line, checks the module is the heading you described, then calls update_module_props with the arguments resolve_ref returned. If the module is in an arm or a variant, it confirms with you and edits through get_layout and update_layout; for a linked component, an ambiguous reference or one it can't match, it asks you before changing anything. You don't have to name the tool: `resolve_ref`'s own description tells the agent to call it first whenever it sees a `kywi:` reference, and the building-patterns guide (in an AGENTS.md generated at 0.31.0 or later) says the same. `resolve_ref` is on the site server only; see [Two servers, two jobs](/agent/two-servers-two-jobs/). Save or discard your own changes in the editor before the agent writes, and reload the editor once it has to see its change. If you save over it, you're asked to reload or overwrite, and overwriting drops the agent's edit. ## What the agent gets back The page (id, title, path, status); where the node sits (region, section, column, and any personalization or A/B arm or page variant); its current props and style; and, for a built-in module, its props schema. A custom module's schema lives in `kywi.config.ts`, which the site server can't read, so the agent works from the props on the node. When the node can be edited directly, the result carries ready-made arguments: `update_module_props` and `remove_module` for a module, `add_module` and `remove_row` for a section. It also carries a design hint. Text and settings are props. Spacing, background and colors are the node's style, set with [theme tokens and style overrides](/authoring/module-properties-theme-tokens-style-overrides/). A custom module's markup is its React component in your code, so a request like "make this card's image round" is a code change there. A built-in module's markup isn't yours to change; the agent can use props and style, or propose a [custom module](/developing/build-a-custom-module-the-three-part-contract/). ## When the agent shouldn't edit it directly **Inside a personalization or A/B arm, or a page variant.** The module tools only reach sections placed directly on the default page. For anything else the agent reads the whole layout with `get_layout`, changes that node, and writes it back with `update_layout`. The change reaches only the visitors who get that arm or variant, so a good agent confirms that's what you meant. **A linked component.** If the module, the section around it, or the container it sits in is a [linked component](/authoring/living-with-linked-components/), the result has no edit arguments. The live page renders the component itself, and changing the component changes every page that uses it, so the agent should check where it's used and ask you first. Editing just this placement would quietly turn it into a one-page copy that stops following the component; if that's what you want, detach it in the editor first. **The same id in more than one place.** The result lists every place and gives no edit arguments until you say which one. **A stale reference.** If the node, or the variant the reference names, was removed after you copied it, the agent gets the page's current sections and modules plus your description, and should match them and check with you before changing anything. A reference from a different Kywi site isn't resolved by this site's server; it tells the agent to use the server for the site it came from. ## Developers: which site the reference names A page rendered with `createPublicPage` names its site by slug. A hand-written route that mounts the front-of-site editor itself should pass `siteSlug`; see [The host-app contract](/developing/the-host-app-contract/). ## Layout writes an agent can and can’t reach URL: https://kywi-docs-production.up.railway.app/agent/layout-writes-an-agent-can-and-cant-reach Type: docPage Updated: 2026-11-11T02:42:50.679Z # Layout writes an agent can and can’t reach 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. Kywi withholds exactly one module type from anyone below [`siteAdmin`](/governing/roles-and-the-capability-matrix/): `html`. An agent authenticated with a lower-scoped key sees it in `list_module_types` like any other built-in, but a layout write that introduces or edits an `html` module is rejected — the same rule the admin editor's palette enforces by hiding the module from the drag list in the first place, mirrored server-side so the palette isn't the only thing standing in the way. ## What the rejection looks like Every door a layout write comes through runs through one guard before anything is stored. A rejected write comes back as a 403 with a structured reason, not a stack trace: ## the 403 body the layout write returns That is what the route returns. What the agent sees is that body flattened into the SDK's error message — `Kywi SDK error (403): {…}`, the JSON carried as a string on an exception rather than a structure the tool loop can branch on. An agent handling the refusal reads the message text; there is no parsed `code` field waiting for it. The check diffs the incoming document against what's already stored, by module id: an agent may re-save a page that already carries an admin-placed `html` block untouched, and may move it around, but adding a new one or editing an existing one's props is what trips the guard — existence alone isn't the trigger, content is. ## The gate follows linked components too Placing a module isn't the only way to introduce one. Linking a layout node to a component definition that itself contains an `html` block puts the same markup on the page, so the guard checks that path as well: a newly added component link is expanded to its stored definition, and an `html` block inside it counts as introduced. An agent can't sidestep the gate by stashing the block in a component and linking to it instead. ## The module tools reach the main layout only `update_module_props`, `remove_module`, `add_module` and `remove_row` find their target by region, row and column among the sections placed directly in the page's main layout. A section inside a personalized or A/B tested container, a module that is one arm of a personalized module, and anything in a page variant are not there, so those tools return an error. For those nodes the agent reads the page with `get_layout`, changes the node in place, and writes the whole document back with `update_layout`. ## resolve_ref says which path a node needs Given a reference copied from the editor, `resolve_ref` returns ready-made module-tool arguments only for a node those tools can reach. For one inside a container arm or a page variant it points at `get_layout` + `update_layout`, and for a linked component it gives no edit arguments at all. See [Hand a module to your agent](/agent/hand-a-module-to-your-agent/). ## Custom module types are the developer server’s list, not this one `list_module_types` maps the engine's own built-in palette and nothing else. A module declared in `kywi.config.ts` with `defineModule` is not in it and never will be — the site MCP server talks to a running site over REST and never reads that file. Custom types are listed by `get_modules` on the *developer* server in `api` mode, which reads the config through the running site instead of the file. In `filesystem` mode that same tool comes back empty — its config parser looks for a quoted name as `defineModule`'s first argument, but a module is declared as `defineModule({ name: ..., ... })`, a single object, so nothing ever matches. Either read `kywi.config.ts` yourself in that mode, or tell the agent the type names directly; an agent holding only the site server's tools cannot enumerate a project's custom modules at all, and `update_layout` will place them once it's told. ## The node the tool hands back isn’t the node that was stored Prop defaults get seeded twice, from two different registries. The layout tool seeds the node it sends up to the agent from a built-ins-only registry — this process has no access to the target project's `kywi.config.ts`. The server separately re-seeds the copy it stores, from the site's own full registry, which does fill in a custom module's declared defaults. So for a custom type, what lands in the database is complete while what the tool echoes back looks emptier than what actually landed. Read the layout back rather than trusting the echo: the difference is in what the agent was shown, not in what was written. ## Media through an agent URL: https://kywi-docs-production.up.railway.app/agent/media-through-an-agent Type: docPage Updated: 2026-09-03T05:47:52.893Z # 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 after that. There's no multipart form on this side of the tool boundary. `upload_media` takes the whole file as a base64 string. The tool decodes it before it ever reaches the site, then hands the raw bytes to the SDK from there — the file travels through the tool call as text, roughly a third larger than the source. ## upload_media call ## The risk isn’t a missing mimeType — it’s a wrong one Neither value is optional to begin with: `filename` and `mimeType` are both required strings on the tool, so an agent cannot leave either out. They are what the server reads to decide the file's type and name — the bytes arrive raw, with those two values carried as headers, not as a form field the server can inspect for itself. Which means the server has no way to tell that a declared type is wrong. It checks the filename's extension against one allowlist and the declared MIME type against another, separately, and never compares the two to each other; a generic `application/octet-stream` defers to the extension entirely. So `photo.jpg` declared `image/png` is accepted by both gates and stored with the wrong type on its record, where every later consumer of that record believes it. Take the type from the file rather than from what the agent inferred from the surrounding conversation. ## A rejected upload tells you why An extension the server's allowlist doesn't recognize comes back as the server's own reason, not a raw exception — the tool catches the SDK's error and rewraps it, so the agent (and whoever is reading its output) sees the actual cause rather than a stack trace to interpret. ## The ceiling is 10 MB of file by default The server measures the decoded bytes against `media.maxUploadSizeMb` — 10 unless the project's config says otherwise — and refuses anything over it with a 400 reading *File exceeds maximum upload size of 10MB*. The limit is on the file itself, decoded — the base64 text carrying it through the tool call is bigger still, on top of that. That is the real cost of this path: a handful of small images is nothing, and handing an agent a folder of full-resolution photos to upload one at a time is a different proposition, whichever limit it hits first. ## Listing media is uncapped, unlike listing content Omit `limit` on `list_media` and the site's entire library comes back in one response — the opposite of `list_content`, which caps by default. On a library of any size that is a large answer arriving in an agent's context whether or not it needed all of it, so pass a `limit` when you know roughly what you are looking for. What the two tools do share is `hasMore`: once a `limit` is in play, a true `hasMore` means the answer is partial and the next page has to be asked for. `page` is only meaningful alongside a `limit` — sent on its own it is an error, not a silent page one. ## Point an agent at a Kywi site URL: https://kywi-docs-production.up.railway.app/agent/point-an-agent-at-a-kywi-site Type: docPage Updated: 2026-09-03T19:08:08.144Z # Point an agent at a Kywi site 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. An agent reaches a Kywi site the way it reaches any MCP server: something in its own config runs a command, and that command needs credentials. Kywi's half of that is one small binary, `kywi-mcp-site`, scoped to exactly one site by a base URL and an API key — no project path, no site slug, nothing else to configure. ## What the client config needs Point the command at the installed package and set the two environment variables it reads: `KYWI_API_URL`, the site's REST base ending in `/api/v1`, and `KYWI_MCP_API_KEY`, a key scoped to that site. ## .mcp.json ## The scaffold does not write this for you Running `create-kywi-app` produces no `.mcp.json` and no equivalent for any other client — nothing in the scaffold templates mentions an MCP server at all. Whichever client you're driving the agent from, this file (or that client's equivalent config) is something you write by hand after scaffolding, not a step the CLI does for you. ## A tool call, once it is wired Every tool the site server exposes takes plain arguments over stdio — there is no separate authentication step once the client has started the process. `list_content` is the one you'll reach for first, and it doubles as the cheap way to check whether something already exists before creating it: pass `slug` and read `total` rather than paging through results. ## list_content — arguments ## This is one of two servers The binary above is the **site** server — it only ever talks to one site's content over its REST API. Kywi ships a second binary, `kywi-mcp-dev`, for editing `kywi.config.ts` and scaffolding; it reads a different set of environment variables and does a genuinely different job. Wire it as a second entry in the same config when you need both — see [Two servers, two jobs](/agent/two-servers-two-jobs/). ## Reading a site without duplicating it URL: https://kywi-docs-production.up.railway.app/agent/reading-a-site-without-duplicating-it Type: docPage Updated: 2026-09-03T05:47:52.894Z # 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 is the mistake it guards against. `list_content` defaults to ten rows per page and never returns more than a hundred, however large the underlying list is — reading the whole thing means paging, and knowing whether you've finished paging means checking one field. ## hasMore is the field that answers it Every response carries `total`, `page`, `pageSize` and `hasMore` alongside the rows. While `hasMore` is true, you have not seen every row and the next page is a real `page` value away, not an assumption. A query for "every product" that reads the first page, sees ten rows, and stops there has answered "the first ten products," not the question it was asked — and nothing about the response format warns you that happened unless you check the flag. ## The cheap way to check whether something already exists Don't page through a whole list to find out whether one node exists. Passing `slug` or `path` to `list_content` and reading `total` answers that in one call — a matching row means `total` is at least 1, and no match means it's exactly 0. `get_content` does the same for a single known id or slug, and fails plainly — "Content not found" — when neither matches; there's no fuzzy or near-duplicate lookup behind it, so an exact `slug` or `path` is what makes the check work at all. ## create_content will not stop you from duplicating something Creating content is a plain insert. Nothing checks whether a node with the same title or slug already exists — not even two siblings under the same parent. Whatever the content type's own schema doesn't already enforce, the tool doesn't add: two `create_content` calls for "Pricing" under the same parent both succeed and leave two pages behind, and `get_content` by slug then quietly returns whichever one is older, hiding the newer one from that lookup entirely. See [slugs, paths, and moving a page](/authoring/slugs-paths-and-moving-a-page/) for why the store allows it. The existence check above is the only thing standing between a build and a duplicate; the create call itself won't catch it. ## Why this matters for a build An agent working through [the build-order playbook](/agent/the-order-a-build-wants-to-happen-in/) reads the site tree constantly — checking what's already there before adding to it. Treating a first page of results as the whole site, or skipping the existence check because paging felt unnecessary, is how a build ends up with two "Contact" pages instead of one it just didn't find. Before creating a new page titled "Pricing", call list_content with type "page" and slug "pricing", and tell me the total before you create anything. The agent calls list_content with the slug filter, reports total: 0 (nothing exists yet, safe to create) or total: 1+ (a page already exists — it should offer update_content on the existing row instead of creating a second one), and does not fall back to paging through every page to look for a match. ## Retrofit an existing project for agents URL: https://kywi-docs-production.up.railway.app/agent/retrofit-an-existing-project-for-agents Type: docPage Updated: 2026-09-03T05:47:52.886Z # 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 already there unless you force it. `create-kywi-app agents` installs the same guidance a fresh scaffold gets — `AGENTS.md`, `CLAUDE.md`, and [the four skill files](/agent/the-four-shipped-skills/) — into a project that didn't start with them, or whose copies have drifted or gone missing. Run it from the project root, where `kywi.config.ts` lives; with no `kywi.config.ts` to read the command refuses outright rather than guessing. If it finds the file but can't tell which deployment mode it describes, it doesn't refuse — it assumes `coupled` and says so in a note under its first line of output. ## It writes an honest header, not a fresh-scaffold one Before writing anything, the command inspects the project on disk — whether it has an admin host file, a custom-module map, its own copy of the render helpers, and so on — and shapes the "Where things live" section of `AGENTS.md` around what it actually finds. A hand-rolled or older project gets a header describing its real layout, not a description of what a brand-new scaffold would have. ## Existing files are skipped, not merged The command always considers the same six files — `AGENTS.md`, `CLAUDE.md`, and one `SKILL.md` per skill — and prints a line for every one of them, whether it writes it or not. Here the project already has AGENTS.md, CLAUDE.md, and three of the four skills; only `kywi-personalization` was added to Kywi after this project's guidance was last refreshed, so it's the one file that gets created: $ npx create-kywi-app@latest agents Refreshing agent guidance for acme-site (coupled mode)… skipped (exists): AGENTS.md skipped (exists): CLAUDE.md skipped (exists): .claude/skills/kywi-content-model/SKILL.md skipped (exists): .claude/skills/kywi-collections/SKILL.md skipped (exists): .claude/skills/kywi-custom-modules/SKILL.md created: .claude/skills/kywi-personalization/SKILL.md ✔ 1 created, 0 updated, 5 skipped. Re-run with --force to overwrite the skipped file(s). Agents will pick these up automatically; see AGENTS.md. Run it without `--force` and any target file that already exists is left untouched — this is how the command adds a skill you're missing without disturbing guidance you already have. Add `--force` and every target file is overwritten, not diffed or merged. ## --force replaces the whole file There is no merge step. Anything you or a teammate added to `AGENTS.md` by hand — a note about a house convention, a link to an internal doc, a correction — is gone the moment `--force` writes over it, along with everything else in the file. If you need those notes back, restore them from git history; if you want them to survive the next refresh, keep them in a section you re-add afterward rather than editing the generated prose in place. ## A stale AGENTS.md gives no warning Every generated `AGENTS.md` opens with a version comment naming the `create-kywi-app` release that wrote it, but nothing checks that comment against the core version the project actually runs — a project that has upgraded core several times since its guidance files were written shows no sign of it. If you're not sure your agent's briefing reflects the platform it's actually building against, re-running `agents --force` is the way to find out, not a stamp you can read at a glance. ## Review what the agent wrote to kywi.config.ts URL: https://kywi-docs-production.up.railway.app/agent/review-what-the-agent-wrote-to-kywiconfigts Type: docPage Updated: 2026-09-03T05:47:52.895Z # 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 reading the file afterward. The developer server's eight config-mutation tools — `add_content_type`, `add_field`, `remove_field`, `add_theme`, `update_content_type`, `update_theme_regions`, `add_module`, `add_plugin` — all work the same way: parse `kywi.config.ts` with the TypeScript compiler, splice in the change, and write the file straight back out. None of them return a preview, and none require a second, confirming call. The moment the tool call returns, the file on disk is the new file. ## There is no dry-run A config write is written straight to disk, not staged or held for confirmation. Review it by reading the file after the call, the same way you'd review any other change an agent made to a file in the repo: `git diff kywi.config.ts` shows exactly what moved, and it's the only place a "before" exists once the write has happened. ## Migrations can follow in the same breath The same server also exposes `run_migration`, which shells out to run it. A content-type or field change and the migration that applies it can happen as two back-to-back tool calls with nothing built into the tool set to pause between them — if you want a human checkpoint between "the schema changed" and "the database changed," that checkpoint has to come from how you brief the agent, not from the tools themselves. ## What makes a write fail instead of landing wrong These tools fail closed on a shape they can't safely edit, rather than guessing. A config file with no literal `defineKywiConfig({ ... })` call to splice into fails before anything is written, and says why in the same breath: Could not find the `defineKywiConfig({ ... })` object in the config file. Every entry a Kywi app reads lives inside that object, so there is nowhere safe to write. ## the whole error the agent receives and a target array written as anything other than an array literal — a spread, a function call, an import — fails the same way rather than being silently misapplied. That protection only covers shapes the tool recognizes as unsafe, though: on an array literal it can parse, the splice just happens. ## What a success tells you, and what it doesn’t Each write returns what it added and a note. What "added" looks like depends on the tool — `add_content_type` returns the type's `label` and a count of `fields`; `add_field` returns just the field's name; `add_theme` returns its `regions` — but only the three tools that shape a content type's fields (`add_content_type`, `add_field`, `remove_field`) put "run `run_migration`" in that note; the other five carry a different heads-up about what the tool couldn't finish for you instead. Either way, the note is the only prompt telling you there's a follow-up step, and a field count is the only description of shape any of them give you — three fields is three fields whether or not they are the three you asked for. Nothing in the response says where in the file the splice went, what it landed next to, or that an import was added alongside it (these tools add one when the change needs it). ## Filesystem mode only All of this exists because the developer server is running in `filesystem` mode. In `api` mode there's no direct write path to `kywi.config.ts` through this server at all — a config change has to go through a person editing the file instead. ## The developer server’s mode decides your tool list URL: https://kywi-docs-production.up.railway.app/agent/the-developer-servers-mode-decides-your-tool-list Type: docPage Updated: 2026-09-03T05:47:52.897Z # 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 developer server’s tools. The developer server resolves exactly one mode when it starts — filesystem, or api — and that single mode, not a per-call choice, decides which of its tools actually register. ## How auto resolves With `KYWI_MCP_MODE` unset or set to `auto`, the server tries a writable local config file first: if `KYWI_CONFIG_PATH` points at a file it can write to, mode is **filesystem**. Otherwise, if both `KYWI_API_URL` and `KYWI_MCP_DEV_KEY` are set, mode is **api**. If neither condition holds, the server throws at startup rather than starting with an empty tool list. # resolves to filesystem — the writable file wins even if API vars are also set KYWI_CONFIG_PATH=./kywi.config.ts KYWI_MCP_MODE=auto # resolves to api — no local file, both API vars present KYWI_API_URL=http://localhost:3000/api/v1 KYWI_MCP_DEV_KEY=kywi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx KYWI_MCP_MODE=auto # forces the mode outright — skips detection KYWI_MCP_MODE=filesystem ## .env — three ways to start it ## What each mode actually unlocks The read-only config tools (`get_config_summary`, `get_content_types`, and their siblings) register in either mode. Past that, the two modes unlock genuinely different tools: **filesystem** mode adds the config-mutation tools that edit `kywi.config.ts` directly; **api** mode adds the API-key management tools. Scaffolding tools sit outside this split entirely — they register whenever a `baseUrl` is configured, in either mode. There's no mode that has both config-mutation and API-key tools at once. ## The filesystem-config / API-data split described in the code never runs The server's source has a second detection function, alongside the one that actually runs, whose comment describes exactly the hybrid an agent might expect: config mutations through the local file, data operations through the API, at the same time. That function is never called by the server that starts from the shipped CLI — only the one that returns a single mode is, and it returns one mode for everything. If you were expecting config edits to go to disk while content operations go to the API in the same session, that split isn't wired in; it's one mode for the whole connection. ## In filesystem mode the list tools come back empty In filesystem mode the read-only tools don't parse your config — they run regular expressions over it as text. `get_content_types` looks for `defineContentType(` followed by a quoted string; `get_themes` looks for `defineTheme(` followed by a quoted string. Both helpers are real exports and a real config calls them, but each takes a single object argument and never a quoted name, so neither pattern can ever match. Both tools return an empty list against a config declaring a dozen types. `get_themes` is not the exception here — it carries the identical regex, and so do `get_modules` and `get_plugins`. `get_config_summary` is the one that answers correctly, because it counts the bare call with nothing after the parenthesis to match. Its content-type count is right at the same moment the tool that lists them by name reports none — the number and the list disagree, and the number is the one to believe. For an accurate list, read `contentTypes` out of the config object directly, or use the site server's `list_content_types` tool against the running site. See [Designing a content type](/developing/designing-a-content-type/) for how types are actually declared. ## The four shipped skills URL: https://kywi-docs-production.up.railway.app/agent/the-four-shipped-skills Type: docPage Updated: 2026-09-03T05:47:52.892Z # The four shipped skills A fresh scaffold installs four Claude Code skills — content model, collections, custom modules, personalization — each loaded at its own moment. Every scaffolded project ships the same four Claude Code skills under `.claude/skills/`, one file each, identical text regardless of whether the project runs coupled, headless, or decoupled. A skill loads itself automatically once its trigger matches what you're asking the agent to do. ## The four, and when each one fires kywi-content-model before building anything — design the model, get owner sign-off kywi-collections adding any collection — folder + feed + Feed Display, end to end kywi-custom-modules the built-in module palette falls short — defineModule, SSR/JS-off hazards kywi-personalization the owner wants personalization or A/B — confirm the use case first `kywi-content-model` is meant to fire before a build starts, not partway through one, which is why [the build-order playbook](/agent/the-order-a-build-wants-to-happen-in/) makes it step 0 — though the skill frames itself as guidance rather than a hard gate: a one-page brochure site only needs a sentence of confirmation, not a full model document. The other three are narrower — each waits for the specific situation named in its trigger rather than firing on every prompt. ## Where to look if a skill didn't fire All four are plain files an agent's skill-loading mechanism reads from disk, so a skill that should have triggered and didn't is usually a missing or edited file, not a server-side setting. If the project wasn't scaffolded fresh — or the files were deleted or hand-edited since — see [retrofitting an existing project](/agent/retrofit-an-existing-project-for-agents/) for how to put them back. ## The order a build wants to happen in URL: https://kywi-docs-production.up.railway.app/agent/the-order-a-build-wants-to-happen-in Type: docPage Updated: 2026-09-03T05:47:52.894Z # The order a build wants to happen in The build-order playbook — model, structure, taxonomy, media, templates, then workflow — is a sequence the building-patterns guide and every AGENTS.md repeat. The building-patterns guide's eleven-step build-order playbook isn't the last thing in the file — a short list of anti-patterns follows it — but the playbook itself is copied into every project's `AGENTS.md` unchanged, and it's the sequence an agent building a new site is expected to follow, not one option among several. ## The sequence 0. Propose the content model, get owner sign-off 1. Model: custom content types for every repeated shape 2. Structure: the site tree — pages, folders per collection 3. Taxonomy: categories/tags the feeds will need 4. Media: upload the brand's assets to the library 5. Templates: saved layouts + reusable components 6. Wire collections: feeds + Feed Display placements 7. Forms: contact/newsletter/etc. 8. Workflow: groups, permissions, review path 9. Ask about: personalization/A-B, comments, webhooks, i18n 10. SEO pass, then hand over ## Step 0 asks for confirmation — nothing enforces it Nothing else on the list is meant to start before the owner has approved a content model, but nothing in the tool set stops an agent from skipping straight to step 5. The `kywi-content-model` skill's own trigger just asks the agent to confirm the model with the owner before building anything — it's a prompt for the agent to follow, not a check any tool refuses to run past. An agent that jumps to templates or forms before that sign-off is working against a step the playbook, and the skill meant to catch it, both put first for a reason: every later step assumes the shapes from step 1 are settled. ## One tool set seam looks like enforcement, but isn't reliable Scaffolding a content type and writing it are two separate developer-server calls — `scaffold_content_type` only returns a suggested definition and says so in its own description; `add_content_type` is the call that actually writes it. But whether an agent has both of those tools available depends on how the developer server is configured, not on the playbook: `scaffold_content_type` registers whenever a `baseUrl` is set, in either mode, while `add_content_type` is a config-mutation tool that registers only in filesystem mode with a writable config path. The two exist together only when both conditions are met at once — there's no guarantee an agent that has one also has the other, so this isn't a mechanism that reliably forces a two-step scaffold-then-apply flow. See [the developer server's mode decides your tool list](/agent/the-developer-servers-mode-decides-your-tool-list/) for the full registration rules. ## The suggestion ignores what you described `scaffold_content_type` always proposes the same six fields — title, slug, body, featured image, meta title, meta description — no matter what you pass as `description`. The text you wrote comes back in the result unchanged, but it never shapes the suggested fields. Read the suggestion before calling `add_content_type`, and edit it yourself if the type you actually want isn't a generic page. Before you build anything, propose a content type for an "Event" using scaffold_content_type — I need fields for a date, a venue, and a ticket link, not the generic page fields. Show me the suggestion and wait for my sign-off before calling add_content_type. The agent calls scaffold_content_type and gets back the same generic six fields (title, slug, body, featuredImage, metaTitle, metaDescription) regardless of what was described, shows you that suggestion, and stops there — it does not call add_content_type until you approve, and it should tell you the fields don't match what you asked for rather than applying them as-is. ## Two servers, two jobs URL: https://kywi-docs-production.up.railway.app/agent/two-servers-two-jobs Type: docPage Updated: 2026-11-11T02:42:50.699Z # Two servers, two jobs 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. Kywi ships two MCP servers, and which one is running decides what an agent can do — not a mode flag on a single server, but two separate binaries with two tool sets that meet in exactly three names. ## The site server: one site, its content Everything the site server registers — content, layout, feeds, components, menus, search, media, users — goes over that one site's REST API. It never opens `kywi.config.ts`; there's no local file path in its configuration for it to open. Everything it does, it does as whatever role the API key in its config carries. Its content tools are generic and take the type as an argument: `create_content`, `list_content`, `update_content`. The source also carries a function that would register a `create_`/`list_` pair per declared content type — `create_blogPost`, `list_blogPost` — but the shipped binary never calls it, so those tools do not exist in the list your agent sees. Don't write a prompt that waits for one. ## resolve_ref is a site-server tool The reference an editor copies with **Copy reference** is resolved by `resolve_ref`, which only the site server registers. An agent connected to the developer server alone can't look one up. See [Hand a module to your agent](/agent/hand-a-module-to-your-agent/). ## The developer server: config and scaffolding The developer server can point at a local `kywi.config.ts`, work purely through the REST API, or have both configured — which one it lands on for a given connection is its own page ([The developer server's mode decides your tool list](/agent/the-developer-servers-mode-decides-your-tool-list/)). ## Two of the three shared names are safe `get_building_patterns` and `list_module_types` are registered on both and behave identically on both — an agent driving either server gets the same building-patterns guide and the same live module catalog. See [What the agent already knows](/agent/what-the-agent-already-knows/). The third shared name is the one to watch. ## Which server you are talking to decides what “add a module” means Both servers register a tool called `add_module`, and they do unrelated things. On the site server it places a module into one column of one page's layout — it wants a content type, a content ID, a region, a row and a column, and the page changes. On the developer server it appends a custom-module *definition* to the `modules` array in `kywi.config.ts` — a name, a label and a component path — which is step one of three towards a module that renders, and puts nothing on any page. With both servers wired into one client, an agent that reaches for the wrong `add_module` edits your config when you asked for a section, or the other way round. Name the two entries so the difference is visible in the tool list. ## Wiring both at once Nothing stops both from being configured in the same client — they're separate entries, started as separate processes, and an agent mid-build reaches for whichever one the task needs: content and layout changes go to the site server, a new content type or a module registration goes to the developer server. ## .mcp.json Reaching a site at all — the site server's own config shape — is covered in [Point an agent at a Kywi site](/agent/point-an-agent-at-a-kywi-site/); an API key's own limits, which apply to whichever server is using it, are covered in [API keys: scopes are a role ceiling](/agent/api-keys-scopes-are-a-role-ceiling/). ## What the agent already knows URL: https://kywi-docs-production.up.railway.app/agent/what-the-agent-already-knows Type: docPage Updated: 2026-11-11T02:42:50.719Z # What the agent already knows 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. Two no-argument tools exist on both MCP servers specifically so an agent isn't told the same thing twice: `get_building_patterns`, which returns Kywi's building-patterns guide, and `list_module_types`, which returns the live module catalog. ## get_building_patterns Calling it returns the whole guide as markdown, read once and cached for the life of the server process. It's the identical text whether you call it from the site server or the developer server — and identical, in turn, to what's already sitting in a scaffolded project's own `AGENTS.md`, because `create-kywi-app` pastes this exact file into every generated app's `AGENTS.md` verbatim. If a project's `AGENTS.md` is already in context, calling this tool tells you nothing it didn't already say. ## The guide covers pasted kywi: references The guide tells the agent what to do when you paste a reference copied with the editor's **Copy reference**: call `resolve_ref` first, then act on what it reports. The tool returns the guide from the installed `@kywi-software/mcp`, but a project's `AGENTS.md` keeps the copy it was generated with, so one generated before 0.31.0 lacks this section until you [regenerate it](/agent/retrofit-an-existing-project-for-agents/). See [Hand a module to your agent](/agent/hand-a-module-to-your-agent/). ## get_building_patterns — arguments ## list_module_types Calling it returns every non-deprecated built-in module's name, label, category and props, computed from the same registry the renderer reads — it cannot fall out of sync with what actually renders. Call it before `add_module` — but not because the schema makes you: `module` there is a plain string with no enum behind it, so a misspelled name is accepted by the tool and lands in the layout rather than being rejected. What this catalog covers is the built-ins. A custom module declared in `kywi.config.ts` is an equally valid `module` value and will never appear here; the developer server's `get_modules` is the tool that names those — in api mode. In filesystem mode it comes back empty, for the reason described in [The developer server's mode decides your tool list](/agent/the-developer-servers-mode-decides-your-tool-list/). ## add_module — arguments, with a built-in module ## A tool description names a tool that isn’t there The `list_components` tool's own description — the text an agent reads while deciding what to call — points at `kywi_patterns` for the component recipe. No tool by that name is registered on either server; the real name is `get_building_patterns`. If an agent reports that it couldn't find `kywi_patterns`, this is where it got the name. ## Why call the tool instead of assuming Neither call needs a running project or a config file — both work the moment a server is connected, before anything else about the site or the config is known. That makes them the cheaper source of truth than restating either one in a prompt: the module catalog changes as Kywi ships new built-ins, and a prompt that hardcodes a module list goes stale the moment it does. ## When the agent gets it wrong URL: https://kywi-docs-production.up.railway.app/agent/when-the-agent-gets-it-wrong Type: docPage Updated: 2026-09-03T19:08:08.173Z # When the agent gets it wrong 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. The audit log is not a record of everything an agent did. It's written only from the workflow path — submitting, approving, rejecting — and from revision approve/reject. A direct `create_content`, `update_content`, `publish_content`, or `delete_content` call never touches it. (A changeset that publishes a pending revision runs the same approve bookkeeping, and no content tool builds changesets.) ## Direct writes are untraceable in the audit log — but not unrecoverable A direct write leaves no audit-log entry, so the audit log is the wrong place to look for what an agent changed or when. Two other trails survive it, unevenly. A `delete_content` call is a soft delete — nothing is removed, the row is marked deleted and lands in Trash. Version history runs the other way round from what you'd expect: an update or a publish takes its snapshot after the write lands, not before, so the version it stores is the new state, not the one it replaced. A `create_content` takes no snapshot at all, so a page an agent created and then edited has no version of its original state either. That timing changes what you restore — after one bad agent edit, the newest version in history is the bad state itself, and the version to bring back is the one below it, the last snapshot taken before the bad write landed. A snapshot that fails is logged as a warning and swallowed — the save still succeeds, quietly, with nothing behind it. Recovering from a bad direct write means reading version history for the state before the damage, and checking Trash, not searching for an audit entry that was never written. ## Version history keeps only the newest 50 versions of an item Every snapshot prunes that item's history back to fifty rows. Fifty saves is an afternoon of an agent making small corrections to one page, and there is no protected slot for the last snapshot a person took — it goes off the end with everything else. Before you hand an agent a page you care about, note the newest version's timestamp in Version History; that's the last human state you'll want to find again once the agent's own saves start pushing older versions off the end — there is no page export to fall back on instead. ## Where a row does exist, it doesn’t say "agent" Where the workflow path does stamp an audit row, and wherever an ordinary save stamps `createdBy`/`updatedBy`, the value written is the same user id an interactive session's write would carry — an API-key-authenticated call resolves to the account that owns the key. There's no separate marker distinguishing a key-driven write from that same user editing by hand; a row that says a change came from you could just as well be an agent using your key. ## Telling an agent’s writes apart from your own The one way to make writes attributable is to give each agent its own account and its own key, named for what it is, rather than sharing your own key across every agent you run. A key is created under, and listed under, the account that owns it, so a dedicated agent account turns "who wrote this" back into a question `createdBy` can actually answer — a shared key can't. Nothing else in the schema will do this job for you: the audit table records a user id and an email and has no column for which key, or what kind of caller, made the change. ## Undoing a bad write Whatever the audit log does or doesn't show, [Version history and rollback](/governing/version-history-and-rollback/) and [Trash and permanent deletion](/governing/trash-and-permanent-deletion/) are where you go to actually undo it — restore an earlier version onto a page an agent edited badly, or pull a deleted page back out of Trash before it's gone for good. ## Authoring content URL: https://kywi-docs-production.up.railway.app/authoring Type: docPage Updated: 2026-09-03T05:47:42.277Z ## Categories and tags URL: https://kywi-docs-production.up.railway.app/authoring/categories-and-tags Type: docPage Updated: 2026-09-03T05:47:42.260Z # Categories and tags Categories and tags are both multi-assignable — categories nest into a hierarchy, tags don't — deleting either is immediate: content just loses the assignment. Categories and tags both group content, and both can be assigned to a piece of content any number of times over — the difference is shape. A category can nest under another category, so it works as a hierarchy; a tag has no parent at all and is always flat. ## Assigning categories The category picker in the content editor is a tree of checkboxes, not a single-select dropdown — a piece of content can sit in several categories, at several depths, at once. Don't assume "pick one" the way some CMSes treat a category; here it's closer to tagging with structure. ## Deleting a category or a tag Both delete the same way: immediately, with no usage check standing in the way. The confirm dialog shows how many pieces of content currently carry the one you're about to remove, as a courtesy, but that count never blocks the delete — it's information, not a gate. ## Deleting is permanent, and content just loses the assignment There's no trash for categories or tags — the delete is immediate, and every piece of content carrying it loses that assignment in the same operation. The content itself is untouched; it simply stops being in that category or carrying that tag, and there's no undo. If a category or tag is load-bearing for a feed, a navigation filter, or a public listing, check what depends on it before removing it. ## Deleting a category with children Removing a category does not remove its children — they survive as their own categories. What it does do is leave each child's stored parent pointing at a category that no longer exists; the admin's category tree treats any child whose parent can't be resolved as a top-level category, which is what makes the children look like they've been re-parented to the root. Nothing actually rewrites their parent — the confirm dialog's mention of re-parenting is describing what you'll see in the tree, not a change made to the child records themselves. ## Feeds URL: https://kywi-docs-production.up.railway.app/authoring/feeds Type: docPage Updated: 2026-09-03T05:47:42.261Z # 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 content. A feed is a saved, named query over one content type — build it once in the Feed Builder, then point any number of Feed Display modules at it by slug instead of re-specifying the query on every page that wants the same list. ## What a feed can filter on A feed always names a content type, and can optionally narrow by status, a search term, locale, parent page, sort order and a result limit — that's the full set the Feed Builder form exposes. The underlying query model can also filter by category or tag and combine conditions into filter groups, but none of that shows up in the form: a feed built through the admin can only ever be as specific as the fields on screen. ## How a Feed Display gets its items The `feedDisplay` module can't query anything itself — it only renders whatever list of items it's handed. A separate pass walks the page's [layout](/authoring/regions-sections-columns-and-modules/) before it renders, finds every Feed Display, resolves the feed slug each one points at, runs that feed's query, and drops the results in. If your host app doesn't wire that pass into its render path, every Feed Display on the site renders empty regardless of what the feeds themselves contain — the shipped Next.js integration wires it, so this only bites a from-scratch host. ## Why a Feed Display shows nothing Worth checking in this order. The Feed Display's own feed-slug field is blank — hydration skips a blank slug outright rather than treating it as "show everything." The slug doesn't resolve **on this site** — feed lookup is scoped to the site the page belongs to, so a feed built on one site is invisible to a Feed Display on another, even with a matching slug. Or, most simply, no content currently matches the feed's own filters. ## The live site always forces "published," even if your feed says otherwise A feed's saved status filter is whatever you set it to — including a feed deliberately built to include drafts, for an internal preview list. The public render path overrides that: every Feed Display on a visitor-facing page is forced to `published` regardless of what the feed's own query specifies. If a feed looks right in a query tool but a Feed Display built from it is missing items you expect, check whether those items are still published. ## Fields, the body, and the rich-text editor URL: https://kywi-docs-production.up.railway.app/authoring/fields-the-body-and-the-rich-text-editor Type: docPage Updated: 2026-09-03T05:47:42.262Z # 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 editor with a fixed toolbar. A content type is built from 18 field types — text, richText, textarea, select, multiSelect, relationship, group, image, file, date, boolean, number, json, color, slug, url, email and list. Most behave the way their name suggests; richText is the one worth knowing more about, because a content type’s Body is a richText field like any other, sharing the same editor as every other one on the site. ## One editor, everywhere richText appears The rich-text editor’s toolbar is deliberately small: paragraph text, bold, italic, a link, and headings capped at two levels. There’s no table, no underline, no text-align, and no highlight or text colour — what you see in the toolbar is genuinely the whole formatting vocabulary, not a subset hidden behind a “more” button. ## There’s no way to add an image from inside the editor The editor can render an inline image if one is already present in the stored content, but nothing in its toolbar lets you add one — there’s no image button. A richText field is text formatting only in practice; reach for an `image` field, in a separate slot on the content type, for anything you need to show. ## multiSelect shows nothing selected when you reopen it ## A multiSelect field always looks empty on load, even when it isn’t Opening a record with existing multiSelect choices shows the field with nothing highlighted, regardless of what was actually saved. Because the browser has no idea what was already selected, clicking any option replaces the whole selection with just that click — there’s no way to add one option while keeping the others, since you can’t see the others to keep them. Nothing in the admin shows you the stored value either: Version History’s Diff view only lists fields that differ between two saved versions, not the current record’s full stored state, so it won’t tell you what’s already selected. Treat the field as blank every time you need to change it, and re-select every option you want — not just the one you’re adding — before you save. ## Field limits are enforced on Save, not while you type A field with a length limit doesn’t stop you from typing past it, and it doesn’t quietly truncate what you enter either — the limit is checked when you save, and a value that’s too long is rejected outright with an error rather than cut down to fit. If a save fails for no obvious reason, check whether a text field has run long. ## One malformed json field blocks the entire save A json field accepts free text: empty is fine, but anything you do type has to parse as valid JSON. If it doesn’t, the whole record’s Save is disabled — not just that field — until the value is fixed or cleared. ## Finding your way around the admin URL: https://kywi-docs-production.up.railway.app/authoring/finding-your-way-around-the-admin Type: docPage Updated: 2026-09-03T05:47:42.263Z # 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 is actually reached from. What the sidebar shows you comes from your role, checked once per row — not from the site you’re currently working in. Which SITE you’re on changes what’s inside a surface: which pages are in the tree, which items are in a list. It never changes which surfaces you can see at all. Keeping those two questions apart saves a lot of “why can’t I find this” detours. ## The sidebar is a role filter, not a map of the site Every row is checked against your role before it’s drawn, and a group heading itself disappears the moment none of its rows survive that check — so a colleague on a lower role isn’t looking at a greyed-out version of your sidebar, they’re looking at a shorter one. If something is missing from the sidebar entirely, that’s a role question. If a specific page won’t show up inside a surface you can already see, it isn’t — read on. ## There’s no Content item — Site Tree is the door There’s no top-level “Content” entry in the sidebar; every content surface is deliberately left off it. Site Tree is how you reach a page to work on it — see [Shaping the site tree](/authoring/shaping-the-site-tree/) for what its row menu can do. That’s not just a sidebar shortcut: the edit screen a row opens needs the same role as Site Tree itself, so a direct link to it doesn’t get anyone further than the sidebar already would. ## A page that’s live but missing from a list ## The Content List and Site Tree don’t always agree on what’s visible The Content List hides any page past its scheduled hide time, no matter your role — see [Publishing, scheduling and expiry](/authoring/publishing-scheduling-and-expiry/). Site Tree applies no such filter, so the same page stays fully visible and directly editable there. If a page has disappeared from the Content List, check Site Tree before assuming it’s been unpublished or moved — it’s most likely just past that window, still live, and easiest to find and fix from the tree. ## A missing page vs. a locked one Per-page permission overrides are checked only when a specific page is opened or saved — never when a list or the tree itself is built. So a permission problem shows up as an error on a page you can already see and click into, not as a page quietly absent from a list. If a page isn’t where you expect it, that’s a listing or scheduling question; if you can see it but can’t open it, that’s a permissions one — see [Content-level permission overrides](/governing/content-level-permission-overrides/). ## Forms and submissions URL: https://kywi-docs-production.up.railway.app/authoring/forms-and-submissions Type: docPage Updated: 2026-09-03T05:47:42.264Z # 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 them. A form is an ordinary content node — its fields, its steps, the success message, the redirect URL and the notify-on-submit addresses all live on that one record, so building, editing and [trashing](/authoring/trash-and-recovering-deleted-work/) a form works exactly like any other content. ## How a form reaches a page The `form` and `formEmbed` modules place a form on a page by its **slug**, not by a fixed reference to the record you built — rendering, validation and the success behaviour are all looked up fresh from the form definition at the moment someone visits the page. Change a field on the form and every page embedding it picks up the change immediately; there's nothing to republish on the page side. ## Where submissions live A submitted entry is stored in a table of its own, keyed by the form's content id — but that key isn't a hard database link back to the form. Unlike version history, which is set up to be removed automatically when its content is, a submission has no such tie: nothing in the database keeps the two in step for you. ## Trashing a form hides its submissions, briefly Looking up a form to list its submissions skips anything in Trash, so trashing a form makes its submissions list read "Form not found" even though every submission row is still there, untouched. Restore the form and the list comes back exactly as it was — nothing about this loses data on its own. ## Permanently deleting a form orphans its submissions for good Deleting a form from Trash removes only the form's own content row. With no database link between a form and its submissions, nothing cleans those rows up or moves them anywhere — they stay in the database, unreachable, because every submissions route looks the form up by slug first and finds nothing. If you need a form's responses, export or record them before permanently deleting it — there's no recovering them through the product afterward. ## Living with linked components URL: https://kywi-docs-production.up.railway.app/authoring/living-with-linked-components Type: docPage Updated: 2026-09-03T05:47:42.265Z # 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 detaches every placement first. Editing the content of a linked component instance feels ordinary while you're doing it — you're changing text or an image on the canvas like anything else, and nothing propagates while you work. The link only matters at the moment you save. ## The choice at save time If you edited a linked instance, saving interrupts to ask whether to update every page placing the component or keep the edit on this page alone — see [Saving a section as a reusable component](/editing/saving-a-section-as-a-reusable-component/) for how that choice works. Leave a linked instance untouched and the save goes through the way any other save does. ## Detaching outside a save There's no separate "Fork" button sitting on the canvas. Outside that save-time dialog, the one way to break a link is **Detach from Component** on the props rail for a selected linked module, section, or container — it materializes the component's current definition into an independent copy immediately, without waiting for a save. ## Deleting a component that is still placed ## A delete is never a silent break Deleting a component still placed anywhere is blocked until you confirm detaching every instance first. Confirm, and the server detaches every placement into an independent copy before it deletes the component — so every page that had it, published or not, keeps rendering exactly what it renders right now. Only future edits stop propagating; nothing currently on screen changes. A page sitting in Trash gets the same treatment: if it holds an instance of the component you're deleting, it's detached too, specifically so restoring it later can't bring back a link to something that no longer exists. For what makes a placement linked in the first place, and how a saved layout differs from a saved component, see [Reusing a design: layouts vs components](/authoring/reusing-a-design-layouts-vs-components/). ## Media URL: https://kywi-docs-production.up.railway.app/authoring/media Type: docPage Updated: 2026-09-03T05:47:42.266Z # 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 dangling. The media library holds every image and file you've uploaded, scoped to the site you're currently working in — reusing an asset on a second site means uploading it there too, not picking it from the first site's library. ## Deleting a file that a page still uses Delete a file that's referenced anywhere — a page's featured image, or an image module inside a layout — and the library stops you rather than deleting it out from under that page. It shows you exactly which content items reference the file and where: featured image, or layout — so you can go fix the reference before you touch the file again, instead of guessing which pages would break. ## Forcing the delete leaves the reference dangling You can push the delete through anyway, and the library says plainly that the reference "will be left dangling" before you confirm. Forcing it does not repair anything on the pages that referenced the file — the featured-image field or the layout's image module still points at the now-gone file, and nothing fixes that automatically. Repoint or remove those references yourself, before you force the delete or after. ## Delete means Trash, not gone An ordinary delete — blocked or forced — moves the file to Trash rather than erasing it; it can be restored from there. A separate, permanent-delete action is the one that's actually irreversible, so an unreferenced file you delete by mistake is still recoverable even after you've confirmed the delete. ## Menus URL: https://kywi-docs-production.up.railway.app/authoring/menus Type: docPage Updated: 2026-10-09T22:58:36.771Z # Menus 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. Site navigation comes from one of two independent sources: the site tree itself, auto-derived from your content, or a managed menu you build by hand. Most sites need only the first; a managed menu exists for the shapes the tree can't produce. ## What the tree gives you for free Left alone, navigation is generated straight from content: any page marked nav-visible appears, filtered by its publish status and by any groups it is hidden from, in the order you've set for its siblings in the Site Tree. There's no way to slot in something that isn't a page, and no way to order it apart from reordering the tree. ## Hiding an item from a group On the Navigation tab, **Nav Visibility by Group** lists the site’s groups under Show in Navigation; untick a group and its members no longer see the page in the generated navigation. It applies only to this automatic tree, not to a managed menu or to breadcrumbs, which group visibility never filters. A person is hidden from an item if they are in *any* unticked group, and everything beneath the item goes with it. Visitors who aren’t signed in always see every item. Only a signed-in person’s own session narrows the navigation; an API key or an OAuth client token reads the full, anonymous tree whatever groups its owner belongs to. Each translation has its own setting, with no fallback to the other languages. ## It hides the link, not the page The page stays reachable by its URL, from other links, in search and in the sitemap. Use content permissions if the page itself must be restricted. ## What a managed menu adds A menu is a separate, hand-built structure with its own item order, independent of how the content is arranged underneath it. It can hold two kinds of item the tree has no equivalent of: a **link**, pointing at either a page or an external URL, and a **label**, a heading with no destination — the column heading in a mega-menu, say. Reach for a managed menu when you need any of those: an external link, a label-only heading, an order that diverges from the page tree, or a curated subset rather than everything the tree would show. ## Linked items self-heal A menu item that links to a page doesn't store that page's URL — it looks it up live from the page's current address every time the menu renders. Move or re-slug the page later and the menu item follows automatically; there's nothing to fix on the menu side. ## A URL Override wins When the linked page has a URL Override, the menu item links to the override, not to the page's place in the tree. Deleting or unpublishing the target page isn't the same outcome. Delete it and the item is flagged broken — the editor shows an alert telling you to remove the item or turn it into an external link. Unpublish it and the item isn't broken at all; it's hidden from visitors — dropped from the rendered menu, along with anything nested under it — until the page is published again, which the editor reports as a status note rather than an alert. Nothing to fix there either — publishing the page is what fixes it. ## Restricted and expired pages drop out for everyone The navigation Kywi renders on the site, generated tree and managed menus alike, lists only pages an anonymous visitor could open. A page past its Unpublish At, or one restricted under Permissions, is left out of the tree, and a menu item linking to one is dropped along with the items nested under it. That holds even for signed-in people who could open the page. For what moving or re-slugging a page actually does to its URL, see [Slugs, paths, and moving a page](/authoring/slugs-paths-and-moving-a-page/). ## Module properties, theme tokens, Style Overrides URL: https://kywi-docs-production.up.railway.app/authoring/module-properties-theme-tokens-style-overrides Type: docPage Updated: 2026-11-11T02:42:50.608Z # Module properties, theme tokens, Style Overrides 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. Select a module and its properties rail opens on the right — every prop the module declares, as its own control: plain text, a picklist, a longer text area, rich text, a number, a toggle, a color swatch, a date, an image or file picker, or a structured JSON field for the handful of modules that need one. Nothing here needs a developer; a picklist's choices are the only ones fixed in advance, everything else takes whatever you put in it. ## Sections and hints in a long panel On a module with many fields — several tiles, each with an image, alt text and a caption — the developer can gather fields into sections. Each section is a heading you can open and close, and some may start closed: if a field you expect isn't showing, open the module's sections before assuming it's missing. A line of small text under a field is the developer's hint about what goes in it, such as the format a crop position takes. ## Sections are only as tidy as the module Sections exist only where the module's developer declared them. A module without them still lists every field in one column, in the order it was built. ## Theme tokens aren't in the rail yet A theme defines its own closed sets of colors, spacing, typography, corner radius and shadow values, each one addressable by name rather than as free CSS — and a theme can choose to allow custom values on top of its set, category by category. None of that reaches you here, though: the color control on the props rail is a bare native color picker, not a picker of the theme's own swatches, so nothing stops you from typing in a color that doesn't match anything the theme defines. Treat the theme's documented palette as the source of truth and match it by eye until this is wired through. ## Style Overrides: four properties, no developer Below a module's own props, a collapsed **Style Overrides** section opens onto exactly four free-text fields — padding, margin, background color, and text align — written straight into that module's own inline style. That's the full set; there's no add-a-property option and no reaching any other CSS declaration from here. ## Look for Style Overrides collapsed, not missing The section starts closed on every module, so if you're expecting to see padding or alignment controls and don't, expand it rather than assuming the module doesn't support them — all four properties are available on every module type. See [The module palette](/authoring/the-module-palette-47-built-ins-in-seven-categories/) for what's available to add in the first place, and [Themes and design tokens](/developing/themes-and-design-tokens/) for how a theme's own token set is defined. ## Publishing, scheduling and expiry URL: https://kywi-docs-production.up.railway.app/authoring/publishing-scheduling-and-expiry Type: docPage Updated: 2026-10-09T22:58:36.791Z # Publishing, scheduling and expiry 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. The Publishing tab has five date fields. Published At, Unpublish At and Expires At govern whether a page is live, hidden or gone. Feature Start and Feature End, shown when Feature In Section is Scheduled, only control where a page is called out inside a section. ## Published At waits for the next sweep, not the clock A page with a future Published At goes live when a background sweep notices the time has passed, not at the exact minute, and only if the page is Approved. The same field is also stamped automatically the first time a page goes live by any route, so on an already-published page it records when that happened rather than a dial you’re still turning. ## Choosing Published with a future date schedules the page Setting Status to Published with a Published At still in the future saves the page as Approved and leaves it for the sweep, which publishes it at that time. The note under Status says “Saving schedules this to publish on ” before you save and “Scheduled for ” afterwards. The sweep keeps the date you set as the page’s publish date, and a page that is already published stays published if you move its date forward. ## Unpublish At hides a page without unpublishing it Unpublish At doesn’t change a page’s status at all — the page stays published in the database. Visitors stop seeing it the moment the date passes, because every public read checks the date. ## Hidden pages stay listed in the admin The Site Tree, and the Content List for editors and above, keep listing a page past its Unpublish At with a “Hidden since ” badge. ## Expires At moves a page to Archived — on the same delay Expires At uses the same sweep: once the time passes, the page moves from published to Archived — not deleted. Unlike Unpublish At, nothing hides an expired page in the meantime, so it can stay live for up to one sweep interval (a minute by default) past its Expires At. ## Expiration Notify: tell people when a page expires Under Expires At, Expiration Notify lets you pick who should hear about it: search the people with access to this site by name or email, add as many as you like, and remove anyone with a click. The picker stays disabled until Expires At is set. Changing the list takes editor or above; an author sees it but cannot change it. When the time passes, each person you chose gets one email, whether the page was live, a draft or already archived — it is a prompt to review the page. Changing or clearing Expires At, including by restoring an older version, starts the notices over for everyone on the list; adding a person later notifies only that person. A copy or translation keeps the list but not what was already sent. Someone who has since been deactivated, lost access to the site, or cannot read this page under its permissions is skipped, and the skip is recorded in the audit log. A failed send is retried with a growing delay, up to five attempts; in rare cases someone gets the notice twice. ## Notices need the sweep and a real email provider Notices go out from the same sweep that archives the page, so where the sweep isn’t running nobody is emailed. They also need a real email provider — SMTP or one your host app supplies. With only the console logger configured, notices stay pending rather than being lost, and go out on the next sweep after a provider is added. ## Feature Start and Feature End: a callout window, not a schedule Feature In Section has three settings. **Yes** features the page until you change it. **Scheduled** reveals Feature Start and Feature End, and the page counts as featured from the start up to, but not including, the end; leave one side blank for an open-ended window; both blank is the same as Yes. An end at or before the start cannot be saved. Switching back to No or Yes hides the dates without discarding them. This is worked out when the page is read, not by the sweep, so a window opens and closes on time even where nothing is running the sweep. ## Featuring never makes a hidden page visible A page that is unpublished, or outside its Unpublish At, is not shown whether it is featured or not. ## Published At and Expires At depend on the sweep running Published At and Expires At are handled by one recurring background job, which also publishes [scheduled changesets](/governing/scheduling-a-changeset/). A Kywi site runs it every 60 seconds by default, unless whoever operates it turned it off — usually to run it from an external scheduler instead (see [Deploying a host app](/operating/deploying-a-host-app/#nothing-sweeps-unless-you-make-it-sweep)). It works only on Postgres: on MySQL, Published At, Expires At and Expiration Notify never fire. If a scheduled page hasn’t gone live a couple of minutes after its time, or an expired one is still showing, ask whoever operates the site whether the sweep is running. Unpublish At and the Feature window are checked on every read, so they don’t depend on it. ## Regions, sections, columns and modules URL: https://kywi-docs-production.up.railway.app/authoring/regions-sections-columns-and-modules Type: docPage Updated: 2026-09-03T05:47:42.269Z # 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 other, and ambiguous drags are refused. A page's layout is four levels deep. A **region** is a named slot in the page template — header, main, footer. A region holds **sections**, stacked top to bottom. A section holds one or more **columns**, side by side. A column holds the **modules** — the actual content pieces you drag in from the palette. ## Where personalization and testing fit A variant container can wrap either a whole section or a single module, and those are the only two places one goes — there's no wrapping a column, and no wrapping a region. Whichever level it wraps, a variant container never nests inside another one: you can't put a personalized module inside a personalized section's arm, or a split-tested section inside another section's arm. The editor enforces this at the moment you drop something, not just as a rule you're expected to follow. ## Why some drags do nothing Dropping something on empty space between sections, rather than on a section or a drop zone, does nothing — it used to snap to the nearest zone and move things you didn't mean to move, and that's been deliberately turned off. The same silent refusal covers dropping a whole variant container onto an existing arm, and dragging a module straight from one arm onto another arm: both read as ambiguous about what should happen, so neither does anything rather than guessing. ## Pulling a variant's own content out asks first Dragging the module an arm is currently showing onto a plain column is different from the refusals above: the drop is ambiguous, so rather than guessing, the editor asks. See [Rearranging sections and modules in place](/editing/rearranging-sections-and-modules-in-place/) for what each answer does. The full set of drag gestures — resizing a column, removing a module from an arm, what Copy and Move actually do — is covered in [Rearranging sections and modules in place](/editing/rearranging-sections-and-modules-in-place/); this page is about the shape of the document those gestures move things around in. ## Reusing a design: layouts vs components URL: https://kywi-docs-production.up.railway.app/authoring/reusing-a-design-layouts-vs-components Type: docPage Updated: 2026-09-03T05:47:42.270Z # 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 component updates every page that uses it. Saving a design for reuse means one of two different things, and the picker you insert it from tells you which: a saved **layout** is a one-time copy, and a saved **component** stays linked to where it came from. Both start the same way — select a section, save it under a name — so the distinction is in what happens next, not in how you make one. ## A layout is a blueprint Placing a saved layout drops its sections into the page as ordinary, independent sections. From that moment they have nothing to do with the layout you placed them from — editing the saved layout later never reaches back into a page that already used it, and editing the page never touches the layout. Think of it as a starting point you copy, not a thing you keep pointing at. ## A component stays live Placing a saved component is different: the section on your page keeps a link to the component it came from, and what renders there is whichever definition the component currently has — on every page that placed it, published pages included. Edit the component once and every placement shows the edit on its next request, with nothing to republish. The insert picker marks this explicitly, tagging components and containers **Linked · stays in sync with the source**; a saved layout carries no such tag. ## A component nested inside a layout stays linked Save a section that contains a component, and place it as a layout: the outer section copies the way any layout does, but the component nested inside it doesn’t — it’s still the same live link. Editing or deleting that component later reaches every page you’ve since stamped from the layout, even though the layout itself never changes. If a saved layout contains a component, treat every page it’s placed on as a holder of that component, not as an independent copy. ## What a layout drops Only ordinary sections come along when a layout is applied. If the section you saved included a personalized or split-tested container — its own A/B or audience variants — those variants aren’t part of the copy: the layout applies as if the container had never branched. For what happens when you edit a linked component after placing it, see [Living with linked components](/authoring/living-with-linked-components/). For saving a component from inside the front-of-site editor rather than the admin layout editor, see [Saving a section as a reusable component](/editing/saving-a-section-as-a-reusable-component/). ## Saving and undoing in the layout editor URL: https://kywi-docs-production.up.railway.app/authoring/saving-and-undoing-in-the-layout-editor Type: docPage Updated: 2026-11-11T02:42:50.628Z # Saving and undoing in the layout editor Undo survives a Save but not a reload. Since 0.25.0, a save that would overwrite a newer save asks you first. Saving is explicit — nothing autosaves in the layout editor, on the admin Layout tab or on Design on site. Undo, meanwhile, is ordinary in-memory history: a stack of states the editor keeps for as long as it's open, and nothing more durable than that. ## What undo remembers, and what it doesn't Undo has no idea a save happened — saving updates what the editor treats as the "original" document without touching the history stack, so you can save, then undo back past that save, in the same session. What it can't do is survive the session itself: reload the page, or close the editor and reopen it, and the history is gone. You start again from one entry, the document as it now stands. ## What clears the history on purpose Two actions reset it deliberately. Cancel reverts to the last saved document and clears history along with it — and if you have unsaved edits, Cancel asks first rather than reverting on the spot. The other is an internal refresh of linked component copies, which only runs when the document is still pristine, so it never discards an edit you haven't saved. Leaving with unsaved work prompts you either way: the front-of-site overlay warns before a browser reload or tab close, and the admin form asks before you switch away from the Layout tab with edits pending. ## Copy reference is not an edit Copying a module's or section's reference for [your agent](/agent/hand-a-module-to-your-agent/) adds nothing to undo history and doesn't mark the page as changed. ## Two people saving the same page: you are asked before overwriting Each Save or Publish, from the Layout tab or from Design on site, carries the version of the page the editor loaded. If the page was saved since you opened it (by someone else, another tab of yours, or an agent), the save stops and asks: **Reload the saved layout**, which drops your unsaved layout changes, or **Overwrite with my changes**, which replaces theirs. Nothing merges the two, so check with whoever else had it open before you overwrite. The [version history](/governing/version-history-and-rollback/) the platform keeps after publish is a separate record, not a substitute for that. On the front of the site, Save Draft and Schedule only queue a draft and don't check. Before 0.25.0 there was no check at all: the second save silently replaced the first. ## Shaping the site tree URL: https://kywi-docs-production.up.railway.app/authoring/shaping-the-site-tree Type: docPage Updated: 2026-09-03T05:47:42.271Z # Shaping the site tree Dragging a row only reorders siblings, Move to… only reparents, and Copy only duplicates in place — three gestures, three separate operations. The Site Tree’s row menu and its drag handle look like one toolkit for rearranging pages, but they’re three separate operations underneath, each touching a different part of a page’s identity — its order among siblings, its parent, or its existence as a second copy. Reach for the one that actually does what you want rather than the one that happens to be closest. ## Dragging a row only reorders it among its siblings A drag can only move a page up or down within its current parent — it never changes what that parent is. Dropping a page onto a different branch of the tree isn’t something dragging does; that’s **Move to…**, below. ## A drag can leave two rows tied for the same position Dropping a row copies the order value of the row it lands next to rather than renumbering the whole list, so two siblings can end up sharing the same position. Which one then sorts first isn’t defined by the drag itself. If a reorder doesn’t seem to have “stuck,” dragging it again usually settles it — but if you keep dropping onto the same neighbor and the two rows just keep trading places, that recreates the same tie every time. Drop the row onto a different neighbor instead; that assigns it a different position and actually breaks the tie. ## “Move to…” is the only way to change a page’s parent Picking a new location from the row menu’s **Move to…** is what actually reparents a page: it rewrites the page’s place in the tree and its URL to match the new parent, and carries every page beneath it along for the same change. What it never touches is the page’s own slug — a move changes where a page lives, not what it’s called. See [Slugs, paths, and moving a page](/authoring/slugs-paths-and-moving-a-page/) for what that means for the URL. ## Copy always lands next to the original **Copy** duplicates a page as a sibling of the one you copied — never into a location you pick — and only the new top page’s slug changes, with `-copy` appended to keep it distinct from the original. Anything beneath it copies over with its slugs untouched, so the new subtree needs its own look before you publish it. A page at the very top level of the tree can’t be copied at all; give it a parent first. ## Delete moves a page to Trash Deleting a row from the tree doesn’t remove it outright — it’s a soft delete, and the confirmation says so. See [Trash and recovering deleted work](/authoring/trash-and-recovering-deleted-work/) for getting it back. ## Version History, from here, does nothing yet ## The row menu’s Version History entry currently has no effect The row menu offers a **Version History** item, but clicking it from the Site Tree doesn’t open anything — there’s no handler wired up for that entry point. Version history for a page is reached from inside the page itself, on its own Version History tab, not from the tree. ## Slugs, paths, and moving a page URL: https://kywi-docs-production.up.railway.app/authoring/slugs-paths-and-moving-a-page Type: docPage Updated: 2026-10-09T22:58:36.812Z # Slugs, paths, and moving a page 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. A page’s URL is the chain of slugs from the site root down to it: a page slugged `pricing` inside a section slugged `platform` is served at `/platform/pricing`. Kywi stores that chain on the page itself, and rewrites it only when the page or a section above it is moved or re-slugged. ## What renaming a page does Editing a title changes the label in the tree, the menu and the breadcrumb, and leaves the URL alone. The slug follows the title only at creation, and through a transform that *deletes* punctuation rather than replacing it — so the spaces around a dropped character survive as hyphens. Title Pricing, plans & FAQ Slug pricing-plans--faq ← the comma and the & are deleted, their spaces are not Path /platform/pricing-plans--faq/ Creation is therefore the moment to set the slug you want: the Slug field keeps what you type (trimmed), and only fills itself in from the title when you leave it empty. ## Changing a slug moves everything under it Saving a new slug rewrites this page’s URL and the URL of every page beneath it, in the same save. Re-slug a section from `guides` to `handbook` and its forty children are served from `/handbook/…` at once, with nothing to republish. ## Moving a page **Move to…** in the Site Tree’s row menu gives a page a new parent and rewrites its path and every path beneath it, the way a slug change does. Dragging a row is a different action: it sets the order siblings appear in and never touches a URL. ## The Parent field moves the page too Saving a new value in the Parent field on a page’s Navigation tab is the same move as **Move to…**: the page and its children get new URLs and the old ones redirect. The field takes a raw content id, so **Move to…** is the easier way to pick a parent. A parent inside the page’s own subtree is refused. ## The old URL redirects to the new one Kywi records the old path whenever a page moves or its slug changes, and a request for it is answered with a permanent redirect to where the page lives now, query string included. If the page is unpublished, outside its Unpublish At, or restricted, the old URL is a 404 too. Menu items follow the page on their own; links typed into body copy work through the redirect, but fix them when you can. ## Giving a page its own address with URL Override The Navigation tab has a **URL Override** field. Type a path such as `/team` and that becomes the page’s public address, whatever its place in the tree: the page is served there, its tree URL permanently redirects to it, and menus, navigation, breadcrumbs, the sitemap, the llms files, feeds, search results and the canonical tag all use the override. Pages beneath it keep their own tree URLs. While the page is unpublished, outside its Unpublish At or restricted, both addresses are a 404. An override may use only lowercase letters, digits, hyphens and underscores in each segment — no dots, so no `.html` or other file extension — and is saved lowercased with a trailing slash. It can’t be `/`, can’t begin with a reserved name (`admin`, `api`, `ax`, `kywi`, `media` and the framework’s own routes), a language code or a site-mount prefix, and the home page and site mounts can’t take one. Only page-like content can have one. Overriding a page with its own tree URL just clears the field. Each override is unique within its site and language, against every other page’s tree URL and override; a deleted page frees its address. The check runs both ways: a save that would collide is refused with the reason, and so is a create, slug change, move, copy or trash restore that would land a tree URL on another page’s override. Change or clear the override and the old address redirects. A copy or a translation starts without one. ## Restoring can drop the override If another page took the address while this one was deleted or on an older version, a restore still succeeds but leaves the override empty and says so — a warning in the editor on a version restore, a `restoreWarning` in the API response on a version or trash restore. Publishing a changeset or approving a revision does the same and reports the warning in the API response. Check the Navigation tab after restoring a page that had one; the Trash screen does not show the warning. ## Two pages, one URL ## A slug a sibling page already uses is refused Creating a page, changing its slug or moving it is refused when a sibling page in the same language already has that slug; a copy takes the next free `-copy`, `-copy-2` slug instead. A page and a form may still share one. The check runs only when a slug or parent changes, so two sibling pages that already shared a slug before the upgrade still do: the older one answers every request and the newer one is unreachable. If a page shows something else’s content, look for the sibling that got there first and re-slug one of them. ## The content editor's tabs — and its three save doors URL: https://kywi-docs-production.up.railway.app/authoring/the-content-editors-tabs--and-its-three-save-doors Type: docPage Updated: 2026-09-03T05:47:42.273Z # 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 waits for the single Save button. A page’s editor is nine tabs — Content, Publishing, Navigation, SEO, Layout, Categories & Tags, Related Content, Permissions, Version History — and they don’t all persist the same way. Three separate mechanisms are at work, and mistaking one for another is the most common way an edit looks saved when it isn’t. ## Six tabs wait for the Save button Content, Publishing, Navigation, SEO, Categories & Tags and Related Content all hold their changes in the form until you press the page’s own Save button, outside the tabs. Nothing in any of these six reaches the database before that click. ## Layout has its own Save, separate from the page’s ## The main Save button does not include your layout The Layout tab persists through its own Save, in-tab, writing only the layout document — the page’s main Save button explicitly leaves layout out of what it submits. The two are independent: saving the page doesn’t save layout changes, and saving layout doesn’t save anything else you’ve edited on the other tabs. Save each where you made the change. ## Permissions saves on every click, with no Save button at all ## Granting or revoking access happens immediately The Permissions tab isn’t waiting for you to press Save — every grant and every revoke writes as soon as you click it, independent of the rest of the form. There’s nothing to “not save yet” here, and nothing to undo by navigating away without saving. ## Creating a page is the exception None of this applies the first time you save a brand-new page: there’s no separate layout door yet, because saving layout on its own needs a page that already exists. On a new page, the layout you’ve built travels inside the same single request as everything else. The three-doors picture above describes editing a page that’s already been created, not making one. ## Version History doesn’t save your edits either Diff, Restore and Delete on the Version History tab aren’t a fourth save path — they act on a past version directly, not on whatever you currently have open in the other tabs. Nothing you’ve typed elsewhere in the form travels with them. ## The Layout tab vs "Design on site" URL: https://kywi-docs-production.up.railway.app/authoring/the-layout-tab-vs-design-on-site Type: docPage Updated: 2026-11-11T02:42:50.654Z # The Layout tab vs "Design on site" 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 Layout tab, in a page's admin form, and **Design on site**, the link that opens the same page in place on the live site, are two doors into one editor. Every drag, every add from the palette, every property you set behaves identically whichever door you came through, because it's the same component tree and the same undo history underneath both. (You may still see it called "Edit on site" somewhere — that's the old name for this same link.) ## What actually differs Not capability — render mode. The admin tab always shows the page as structure cards: regions, sections and modules labelled by name, with none of the site's own CSS or real components involved. Design on site shows the page as it actually renders, using the real components in the site's own stylesheet, with the editing controls layered on top. Both are looking at, and writing to, the identical layout document — structure view just trades fidelity for a canvas that never breaks no matter what the site's CSS does. Layout tab (admin) structure cards, no site CSS, always renders Design on site the real page, real components, real CSS ## One save, either door Saving from the Layout tab and saving from Design on site write to the same endpoint. There's no version that's "more live" than the other, and no sync step — editing from one and switching to the other picks up exactly what you left. ## Copy reference works from either door Both show **Copy reference** on every module and section, and the address it copies points at the same module or section either way. If a page variant or A/B variant is on screen, the reference names that version. See [Hand a module to your agent](/agent/hand-a-module-to-your-agent/). ## Design on site is disabled, not hidden, on an unpublished page A page needs a real, materialized URL before Design on site has anywhere to open — a page that's never been published has no such path yet. Rather than removing the link, the toolbar shows it disabled with the tooltip **Set a path to design on site**, so the reason it's unavailable is never a mystery. ## Leaving with unsaved changes Switching away from the Layout tab, or out of the content form entirely, while an edit hasn't been saved opens a confirm dialog rather than discarding it. There's no quiet way to lose work by clicking somewhere else. See [Saving and undoing in the layout editor](/authoring/saving-and-undoing-in-the-layout-editor/) for what undo does and doesn't remember across a save. ## The module palette: what’s in it and what’s held back URL: https://kywi-docs-production.up.railway.app/authoring/the-module-palette-47-built-ins-in-seven-categories Type: docPage Updated: 2026-09-03T05:47:42.275Z # 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) — Section and the deprecated variant module are hidden. Kywi ships 47 built-in modules in seven categories. You won't count 47 in the palette, though — two are held back from everyone, and a third from anyone who isn't a site admin, so what you actually see is 44 or 45 depending on your role. ## The seven categories Every module the registry declares — carousel, accordion, hero, feed display, breadcrumbs, cookie consent among them — grouped the way the palette groups them, with what's held back from your view in the Default column. ## What doesn't reach the palette Section is there in the registry, but it isn't dragged in — it's added from the toolbar's own "+ Section" control, since a section is what everything else lives inside rather than something that goes inside a column. The variant container module is deprecated and hidden outright; personalizing or A/B testing a section or module is done by wrapping it, not by dragging this in directly. And HTML — the one module that injects raw markup — only ever appears for a site admin. ## The palette can look different to two people on the same page Since HTML is gated by role rather than by anything about the page, an editor and a site admin looking at the identical page can see a different-sized Elements category in their palette. If a module you know exists isn't there, check who's signed in before assuming it's missing. The palette itself is just the starting point — once a module is on the page, what you can set on it (and the four free CSS properties every module gets, regardless of category) is covered in [Module properties, theme tokens, Style Overrides](/authoring/module-properties-theme-tokens-style-overrides/). ## Translations URL: https://kywi-docs-production.up.railway.app/authoring/translations Type: docPage Updated: 2026-09-03T05:47:42.275Z # 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 isn't a locale-switched view of one page — it's a separate page, with its own id, related to the source only by convention: the same [slug and parent](/authoring/slugs-paths-and-moving-a-page/), a different locale. Nothing in the database formally links the two rows together. ## What "Create translation" does Creating a translation copies every field from the source, including its full layout, so you start from a complete page rather than a blank one. What it doesn't carry over is identity: the new page always starts life as a draft, no matter what status the source is in, and its id, timestamps, publish date and ownership fields are all its own rather than copies of the source's. ## One translation per locale You can't create a second translation in the same locale for the same source — the server refuses it. A source page and its translations are effectively one variant per slug, parent and locale, so if you need to start a locale over, you edit the translation you already have rather than replacing it with a fresh copy; there's no way to re-clone into an existing locale without deleting that translation first. ## Source and translation live and die separately Because a translation is a plain, independent page, it goes through the same [publishing](/authoring/publishing-scheduling-and-expiry/) and [trash](/authoring/trash-and-recovering-deleted-work/) lifecycle as any other content, on its own schedule. Deleting the source does not touch its translations, and deleting a translation does not touch the source — the "link" between them is the matching slug and parent, not a reference that would cascade either way. ## What this surface doesn't manage The set of locales a site supports is configured in code, not here — this surface only shows and manages which pages exist in which locale, not the locales themselves. If a locale you expect to translate into isn't offered when you create a translation, that's a question for whoever maintains the site's configuration, not a setting to look for in this admin. ## Trash and recovering deleted work URL: https://kywi-docs-production.up.railway.app/authoring/trash-and-recovering-deleted-work Type: docPage Updated: 2026-09-03T05:47:42.276Z # Trash and recovering deleted work Trash only holds pages and media — categories, tags, menus, components and comments delete immediately with no recovery. Trash holds two kinds of thing: content — pages, forms, folders, anything built on the standard content record — and media. Both are marked deleted rather than removed outright, and the admin's Trash surface is simply those two sources merged into one list. ## What never reaches Trash [Categories and tags](/authoring/categories-and-tags/), menus, saved components and comments have no soft-delete state at all — deleting one of these is immediate and final, and it never appears in Trash to be recovered. This isn't a setting anywhere; those records simply don't carry the column Trash depends on. ## Restoring something whose parent is gone Restoring a page checks whether the page it used to live under is still around. If that parent was itself deleted in the meantime, the restored page doesn't fail to come back — it lands in an automatically created "_recovered" folder at the site root instead of its old spot, so a parent's fate never blocks recovering its children. ## What permanently deleting actually removes Permanent delete acts on exactly one row. Deleting a page that still has live children doesn't touch them — they stay right where they are, now pointing at a parent that no longer exists, with no bulk "delete this and everything under it" option available from Trash. ## Permanent deletion doesn't clean up what pointed at it Deleting media for good also removes the stored file, but permanently deleting content does not clean up most of what referenced it. A menu item pointing at a deleted page is one of the few things wired to update itself; something like a [form's submissions](/authoring/forms-and-submissions/) has no such wiring and is simply left behind, permanently unreachable. Once something is gone from Trash, treat anything that pointed at it as broken until you fix it by hand. ## Empty Trash Empty Trash is a real bulk permanent-delete, not a cosmetic "clear the list" action — it runs for the current site, or across every site at once for a super admin. Everything above about permanent deletion applies to every item it removes. ## Developing the project URL: https://kywi-docs-production.up.railway.app/developing Type: docPage Updated: 2026-09-03T05:47:58.152Z ## Access control in kywi.config.ts URL: https://kywi-docs-production.up.railway.app/developing/access-control-in-kywiconfigts Type: docPage Updated: 2026-09-03T05:47:58.123Z # 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 absence always means allowed. A content type's `access` block is four optional predicates, and each one is handed the caller and nothing else — no content node, no site id, no request. That constraint is the design, not an oversight: these run before core has decided which row it is dealing with, so they can only ever answer questions about who is asking. interface AccessControlConfig { read?: (ctx: { user: UserContext | null }) => boolean write?: (ctx: { user: UserContext | null }) => boolean publish?: (ctx: { user: UserContext | null }) => boolean delete?: (ctx: { user: UserContext | null }) => boolean } Synchronous, boolean, and independent of each other. A rule that needs the row it is about — "only the author may edit this page" — is a per-document permission or a `beforeUpdate` hook, not one of these. ## Absence means allowed No `access` block returns `true`. An `access` block with no function for the action being attempted returns `true`. These predicates only ever TIGHTEN: passing one drops the caller into the ordinary role check, so writing `write: () => true` grants nothing an editor did not already have, and omitting `publish` while restricting `write` leaves publishing on the role ladder alone. defineContentType({ name: 'invoice', // … access: { // Both actions still pass the role check afterwards — this narrows, never widens. read: ({ user }) => user?.role === 'superAdmin' || user?.groups.includes('finance') === true, write: ({ user }) => user?.groups.includes('finance') === true, }, }) ## kywi.config.ts They are evaluated at the content routes, one call per action: reading a list and reading one node, the three write doors (POST, PUT, PATCH), delete, and both publish routes. A type whose `read` denies is not filtered out of a listing — the listing route itself refuses, with a 401 for an anonymous caller and a 403 for a signed-in one. ## Field-level access is a separate layer A `FieldDefinition` carries its own `access` with `read` and `write`, evaluated per key rather than per request. On the way out, denied keys are dropped from the record silently. On the way in, they are a 403 `FORBIDDEN_FIELD` whose body names the fields the caller tried to change. ## How a denied field resolves What each combination of field definition and predicate does to one key in a create or update payload. The last row is the one that makes the feature usable at all: an admin form posts every field back on every save, so treating a denied field's own stored value as an attempted write would make a read-only field unsaveable for everyone who can see it. Equality is type-aware — dates compare by timestamp, objects by their JSON. ## Bulk writes forgive nothing The bulk create and update endpoints hold no stored document per item to diff against, so there is no echo to forgive: the mere presence of a write-denied field in any item refuses the entire batch. A client that round-trips whole records works against the single-node routes and fails against the bulk ones with the same payload. ## Where these sit relative to per-document permissions Config predicates gate the TYPE. Per-document permissions gate one node, out of ACL rows in the database, and follow their own rules: superAdmin and siteAdmin bypass them; a node with no rows is open; a node with rows and an anonymous caller is denied. Mutations additionally require read on the node first — you cannot publish or delete something you are not allowed to see. The two layers compose, and neither is a substitute for the other: see [Content-level permission overrides](/governing/content-level-permission-overrides/) for the ACL half and [Roles and the capability matrix](/governing/roles-and-the-capability-matrix/) for the ladder underneath both. ## These live only in code They are functions, so nothing serialises them. The Type Designer cannot express an access predicate, and a type created there has none — which is one of the real differences between a config type and a database type, covered in [Config types, Type Designer types, and extension attributes](/developing/config-types-type-designer-types-and-extension-attributes/). ## The validator knows only read and write The zod schema behind `parseKywiConfig` declares `access` as `{ read?, write? }`, and zod strips unknown keys — so `publish` and `delete` disappear from a parsed config. Your running app is unaffected, because it uses the config object itself; what is affected is anything that reads a config THROUGH the parser, including the CLI and the MCP developer server. Do not conclude from a parsed config that a type has no publish rule. ## Build a custom module: the three-part contract URL: https://kywi-docs-production.up.railway.app/developing/build-a-custom-module-the-three-part-contract Type: docPage Updated: 2026-11-11T02:42:50.740Z # Build a custom module: the three-part contract A custom module is three things that must agree — a defineModule entry, a client component, and one entry in the layer’s module map. A custom module exists only when three separate artefacts agree on one string: a `defineModule` entry in `kywi.config.ts`, a client component, and one key in the module map your site layer exports. Miss any of the three and the failure is somewhere else — a module missing from the palette, an "Unknown module" box on both the public page and the editor canvas, or an app that refuses to boot. The step-by-step recipe ships with the scaffold as the `kywi-custom-modules` skill, in `.claude/skills/`, so an agent in your project already has it. ## One: the config entry defineModule({ name: string // the layout node's type, and the MCP add_module type label: string // what the owner sees in the palette component: string // the key you map in step three category?: string // palette grouping props?: Record propGroups?: Record // props-panel sections (0.30.0+) deprecated?: boolean // hide from the palette; existing placements keep rendering }) Changing it after pages exist orphans every placement. export const docsModules: ModuleConfig[] = [ defineModule({ name: 'callout', label: 'Callout', component: 'callout', category: 'Docs', props: { kind: { type: 'select', label: 'Kind', options: [ { value: 'note', label: 'Note' }, { value: 'tip', label: 'Tip' }, { value: 'warning', label: 'Warning' }, { value: 'danger', label: 'Danger' }, ], defaultValue: 'note', }, title: { type: 'text', label: 'Title (optional)', defaultValue: '' }, body: { type: 'richText', label: 'Body', defaultValue: '' }, addedIn: { type: 'text', label: 'Added in version — e.g. 0.22.0', defaultValue: '' }, }, }), // … ] ## lib/docs/modules.config.ts — this site’s own kit ## Two: the component A `'use client'` React component taking a single `{ props }` object. Every value in it arrives as `unknown` out of a JSONB document, so each one is coerced at the point of use — see [Designing module props](/developing/designing-module-props-for-the-person-who-edits-the-page/) for what the types mean to the owner, and [Custom-module hazards](/developing/custom-module-hazards/) for what a throw in here takes down with it. ## Three: the map, and how it reaches core The map is a `ModuleComponentMap` keyed by the `name` from step one. Under the layer chain it does not reach core as a constructor argument: the site layer exports it, and the generated layer registry is what `createPublicPage` and `createAdminPage` read. // lib/docs/index.ts — keys must match the defineModule names export const docsModuleComponents = { codeBlock: CodeBlock, callout: Callout, agentPrompt: AgentPrompt, // … } satisfies ModuleComponentMap // sites/docs/index.ts — the entire file export { moduleComponents as modules } from '../../lib/modules' ## lib/docs/index.ts, then sites/docs/index.ts Three sites in this project export that same line, which is how one authored map serves all of them. The scaffold writes that re-export for you: `create-kywi-app` generates every `sites//index.ts` as exactly this line, so registering a module never means hunting for a fourth file — you edit the project-wide component map (this project's `lib/modules.tsx`) and the site layer already points at it. Within the chain a theme layer's entry for a name wins over the site layer's, and both win over the `modules` option still accepted by `createPublicPage` — that option, along with `frontEdit` and `personalizationRuntime`, is deprecated in favour of the layer. An entry whose key is a built-in module's name replaces that built-in, on the public page and in the editor canvas alike: the renderer looks in the injected map first and only falls back to the built-ins. That is the supported way to change what a built-in module renders. `create-kywi-app eject ` does hand you a copy of one of core's own render artefacts to fork, but only for the four on its list — `nav`, `frontEdit`, `personalizationRuntime`, `jsLoader` — and a built-in module's renderer is not one of them; see [Upgrading core inside your project](/developing/upgrading-core-inside-your-project/) for what eject does and what it costs, and [The module palette](/authoring/the-module-palette-47-built-ins-in-seven-categories/) for the full list of built-ins. ## A map key with no config entry stops the app booting The layer assertion runs at boot and throws `Unknown layered module "" in sites.. Define it in kywi.config.ts modules or use a built-in module name.` for any key in a layer's map that is neither a built-in nor present in `config.modules`. Registering in the config is load-bearing, not documentation — and the failure is a hard boot error, not a missing palette entry. ## Component references cross the RSC boundary; functions do not The map is serialised into the flight payload for the client admin, so its values must be resolved client-component references — a resolver function there throws "Functions cannot be passed directly to Client Components" and 500s the page. The admin entry point additionally projects the layer registry through `clientLayerRegistry`, which strips the `templates` key wholesale; that is what lets a site layer hold a server `shell` or a `hydrateLayout` pass beside its modules without taking the admin down. ## Retiring one `deprecated: true` hides a module from the palette and from the MCP `list_module_types` catalogue while every existing placement keeps rendering. Deleting the entry instead turns each of those placements into an "Unknown module" box. This is how the legacy `variantContainer` was retired, and it is the right move whenever pages already carry the module you are replacing. ## Changing the content model on a database that has data URL: https://kywi-docs-production.up.railway.app/developing/changing-the-content-model-on-a-database-that-has-data Type: docPage Updated: 2026-09-03T05:47:58.129Z # 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 half-readable database is what offers to drop live tables. `kywi migrate` is not one command. It spawns `kywi migrate:generate` and aborts if that fails, pre-flights the database, refuses to continue if the generated schema does not cover what is live, runs `drizzle-kit generate` to capture the diff as a migration file, then applies it. Two of those steps stop you on purpose; those are the ones worth knowing. ## Generation reads the database, not just the config Types created in the Type Designer live as rows but own real `kywi_ct_*` tables, so a schema derived from `kywi.config.ts` alone describes only part of the content model. Generation therefore connects, lists what is actually there, and writes those runtime-managed tables into `drizzle.config.ts` as exclusions, which keeps drizzle-kit from proposing to delete them. Reachability is probed on its own, before anything is read, and that distinction is the safety property: an **unreachable** database means an offline build, so generation falls back to a config-only schema with a warning. A database that answers `select 1` and then fails the read is a different situation, and the command aborts rather than emit a schema that omits — and so un-protects — those tables. ## This is the path that offers to drop live tables An unprotected schema hands drizzle-kit a content model missing every admin-created table, and drizzle-kit's response to a table it cannot see in the schema is to offer to `DROP` it — with its rows. The same hazard applies inside a runtime-managed table: deleting a field there never drops its column, so the leftovers look like deletions to a diff. Answering "yes" to a drizzle-kit prompt you did not read is how a content type's data disappears. ## The guard that refuses to run drizzle-kit Before spawning drizzle-kit at all, `kywi migrate` checks every live `kywi_ct_*` table against the generated output: each one must either have its own schema file or be negated in `drizzle.config.ts`. If any is neither, it stops: ✖ Refusing to run drizzle-kit: 1 admin-created content-type table(s) exist in the database but are missing from the generated schema: kywi_ct_property Running the migration now would offer to DROP these tables and their rows (#38). Re-run 'kywi migrate' with a DATABASE_URL that can read kywi_content_types, or report this as a bug if the problem persists. This message can only be reached after step 1 (`migrate:generate`) has already exited 0: a database that is reachable but fails the admin-type read aborts inside `migrate:generate` itself, and `kywi migrate` exits on that non-zero status without ever reaching this guard. What actually reaches this guard is the config-only fallback itself, the one cause the guard's own comment names: the database was unreachable when `migrate:generate` ran but answers this guard's own re-probe moments later inside `kywi migrate` — or `migrate:generate` hit a bug that made it fall back to a config-only schema despite the database being reachable. Either way, the fix is the same: re-run `kywi migrate` against a database connection that can actually read `kywi_content_types` at generation time. ## Renaming a field Nothing carries a field's previous name — the column is derived from `field.name` alone. Rename a field and the generator sees one column gone and one new — the one diff drizzle-kit cannot resolve on its own. It asks whether the column was created or renamed from another, and with no terminal attached the prompt resolves nothing and drizzle-kit **exits successfully having written no migration at all**. `kywi migrate` reads the output rather than the exit code, recognises the prompt, and fails loudly. So plan a rename as three deploys — add the new field, backfill it, drop the old one — or resolve the prompt yourself in an interactive terminal and commit the migration it writes. [When migrate can't resolve itself: ambiguous renames](/operating/when-migrate-cant-resolve-itself-ambiguous-renames/) has the operator's version. ## Read the migration before it is applied anywhere The generated SQL is a diff against drizzle's own snapshot, not against your database, and the two can disagree — a generated migration has arrived carrying an `ADD COLUMN` for a column the database already had, which fails on contact. Editing a not-yet-applied file is safe, because it is drizzle-orm's own migrator that hashes each `.sql` file at apply time (`readMigrationFiles`, sha256 over the file content) rather than trusting anything recorded when it was generated — so what you edit today is exactly what gets applied and recorded. Editing an applied one is not. Commit the migration and the snapshot together, or the next generate diffs against a snapshot nobody else has. ## Why --push is awkward on purpose `--push` writes straight to the database and never touches the journal, so on a project that already has one it demands `--force-push` alongside it — an explicit acknowledgement that later journal-based migrations may then fail or silently skip the change. On a project with no journal yet it is the intended prototyping path and needs no flag. Neither case belongs in a deploy — see [Why drizzle-kit push is banned before deploy](/operating/why-drizzle-kit-push-is-banned-before-deploy/), [Running migrations against a live database](/operating/running-migrations-against-a-live-database/), and [Post-migration data steps](/operating/post-migration-data-steps-and-why-they-can-silently-not-run/) for the ones a successful migrate runs afterwards. ## Config as code vs. the database URL: https://kywi-docs-production.up.railway.app/developing/config-as-code-vs-the-database Type: docPage Updated: 2026-09-03T05:47:58.130Z # 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 what a deploy can change. The line runs through the content model itself, not around it: a content type can come from `kywi.config.ts` or from the admin's Type Designer, and both kinds are live in the same registry. What separates them is who can change them and when — a config type moves on a deploy, an admin type moves on a save. ## Where the two halves meet Once, at boot. Building the API handler loads the admin-defined fields and admin-created types out of the database and merges them with the config's into two maps — content types, and the generated tables behind them. Those maps are mutated in place and never reassigned, deliberately: route handlers capture the reference at registration, so a schema reload is visible to them immediately, with no server restart. A type added in the Type Designer is servable before the next deploy; a type added to the config is not there until one. ## Provenance travels with the shape interface ContentTypeConfig { source?: 'config' | 'admin'; /* … */ } interface FieldDefinition { source?: 'config' | 'admin'; /* … */ } Set on admin-created types and admin-added fields; config declarations leave it unset. It is what tells the admin which parts of a type it may offer to edit. The flag is per *field*, not only per type, so a config-owned type can carry admin-added fields and the designer will let you edit exactly those. See [Config types, Type Designer types, and extension attributes](/developing/config-types-type-designer-types-and-extension-attributes/) for how the two are edited side by side. ## Config-only, because these are functions A database column cannot hold a closure, so anything expressed as one lives in the config and only there: the `access` predicates on a type (`read`, `write`, `publish`, `delete`), the nine content-type hooks (`validate`, `beforeCreate` and `afterCreate` through `afterPublish` and `afterUnpublish`), an `ax.jsonLd` type mapping's `transform` escape hatch, a signal adapter's `collect` or `transform`, and a plugin's `init` and `scopeExtensions`. There is no admin surface for any of them, and there cannot be one. Hooks are covered in [Hooks: content-type hooks and the event bus](/developing/hooks-content-type-hooks-and-the-event-bus/), access predicates in [Access control in kywi.config.ts](/developing/access-control-in-kywiconfigts/). ## Database-only, because they are content Everything an editor or a site admin creates at runtime: pages and their version history, menus, media, feeds, audiences, experiments, changesets, comments, per-document permission overrides, per-site settings. And admin-created content types, each of which gets its own generated `kywi_ct_` table. None of it is expressible in `kywi.config.ts`, and none of it should be seeded by hand in SQL — [Seeding structure as code](/developing/seeding-structure-as-code/) is the supported route. ## kywi_sites is the one table your config owns Since 0.23.0 the runtime reconciles `kywi_sites` against `config.sites` at init, before anything reads the table — creating a missing row and updating `name`, `domain`, `defaultLocale` and `theme` in place, matched on the config `id` as the row's slug. Those four columns are config's; editing them in the database is editing something a boot will overwrite. ## Reconciliation never deletes A `kywi_sites` row matching no configured site is reported as an orphan on boot and left exactly where it is, with its content still attached. Kywi does not delete a site because a config stopped mentioning it. Removing one is a deliberate operation — see [Multi-site: the domain field and host-based resolution](/operating/multi-site-the-domain-field-and-host-based-resolution/). ## Typed, validated, and read by nobody Two cache keys are worth knowing about before you tune them. `cache.contentTtl` is real — it becomes the TTL of the cached content queries. `cache.feedTtl`, `cache.navTtl` and `cache.defaultTtl` are typed, validated by the config schema, and reported back by both `GET /cache` and the config export, but no cache path reads them; setting one changes what the admin displays and nothing else. `mode` is in the same position at runtime: it selected which files the scaffold wrote and is now only reported. Neither is a bug you can work around in config — treat the values as descriptive until they are wired. ## Config types, Type Designer types, and extension attributes URL: https://kywi-docs-production.up.railway.app/developing/config-types-type-designer-types-and-extension-attributes Type: docPage Updated: 2026-09-03T05:47:58.131Z # Config types, Type Designer types, and extension attributes Three ways to add fields exist — config types, admin-created types, and extension attributes — differing in where they live and who may change them. Three mechanisms add fields to content, and they differ in where the *definition* lives, where the *value* lives, and which tool owns the DDL. Choosing between them is a deploy decision, not a modelling preference. ## Where each one lives A **config type** is declared in `kywi.config.ts`. Its `kywi_ct_` table is generated as a drizzle schema file and migrated by drizzle-kit; the definition is reviewed in git and changes with a deploy. A **Type Designer type** is rows in `kywi_content_types` and `kywi_content_type_fields` — and it still gets a real `kywi_ct_` table with real columns. That table is created on the first Apply Schema Changes and grown the same way afterwards: adding a field issues an `ALTER TABLE … ADD COLUMN`. Removing one never drops anything — a deleted field leaves its column and its data behind, deliberately. An **extension attribute** adds no column at all. Definitions and values are rows in five fixed tables — subtypes, attribute sets, attributes, data and related sets — and a value lands in whichever of five columns matches its type: `number_value`, `date_value`, `boolean_value`, `json_value`, or `string_value` for everything else (text, select, file and rich text all store as string). It is the only one of the three that needs no migration, ever. ## One table, one manager Schema generation reads the database as well as the config, but not to generate drizzle schema for admin-created tables — to *exclude* them. Every admin table, and every orphaned `kywi_ct_*` table left behind by a deleted type, is written into the generated `drizzle.config.ts` as a negation, so drizzle-kit never sees it in a diff: tablesFilter: ["kywi_*","!kywi_ct_article","!kywi_ct_capability"], ## drizzle.config.ts (generated) ## A schema generated without those negations offers to drop live tables Runtime-managed tables keep columns whose field rows are gone, because deleting a field in the admin never drops a column. Hand that reality to drizzle-kit as a diff and it proposes to delete them — this was found live on a 0.2.x install, where a blog-post table's leftover columns were offered for deletion along with six posts' data. The negations are what prevent it, and they are only written when generation could actually read the database. [Changing the content model on a database that has data](/developing/changing-the-content-model-on-a-database-that-has-data/) covers the guard that refuses to run without them. ## Reloads, restarts and provenance Why a Type Designer type is usable at once while a config type waits for a deploy, and how the two are told apart in code, is the general config-vs-database mechanism — see [Config as code vs the database](/developing/config-as-code-vs-the-database/). Reserved field names are enforced on the designer's field route with a `409`, and the list is deliberately dependency-free so the browser surface and the server route check the same thing. [Designing a content type](/developing/designing-a-content-type/) has the list and the one path that does not check it. ## What extension attributes cost you No column means no migration — and no column to filter, sort or index on. A value reached through a join on attribute id is not a field: it will not back a feed, an audience rule or an ordered listing the way a real column does. The five tables also carry no `site_id`, so the extension model is deployment-global rather than per-site; values are tied to a content row and cascade away with it, which is more than a `relationship` field column gets. Reach for an extension attribute for sparse, subtype-specific data nobody queries across. Reach for a field for anything you will filter, sort or feed on — and for a config field specifically when code depends on the shape. See [Config as code vs the database](/developing/config-as-code-vs-the-database/) for the general version of that line. ## Custom-module hazards URL: https://kywi-docs-production.up.railway.app/developing/custom-module-hazards Type: docPage Updated: 2026-11-11T02:42:50.776Z # Custom-module hazards 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. One module map is handed to two renderers: the public page and the admin's editor canvas. Everything on this page follows from that. A module that throws does not degrade a band on the site — it takes down the surface the owner would use to fix it, and the report you get is "the layout editor is broken", not "the module is broken". The checklist form of these hazards ships with the scaffold as the `kywi-custom-modules` skill (`.claude/skills/`, §6) — an agent in your project already has it. What follows is grounded in core's own source: which surface each hazard actually breaks, and why. ## Render must be deterministic Generate ids with `React.useId()` — a module-scope counter, `Date.now()` or `Math.random()` in render mismatches server and client, and the hydration error that surfaces points nowhere near your module. ## Do not fetch A custom module is a client component: it cannot reach the database, and one that fetches from an effect gives the editor canvas content that appears only after a round trip. Data arrives as props, and anything not authored in the props panel is injected server-side before the document crosses into the renderer: personalizeLayout the audience's variant; other variants stripped hydrateLayoutFeeds feedDisplay modules only hydrateLayoutNav navMenu / navigation / siteMap modules resolveLayoutComponents linked components materialised into the document templates.hydrateLayout YOUR layer's pass — anything else pruneLayoutToServedArms keep only the arm this visitor is served Your pass runs after linked components are materialised, so it reaches a module placed inside a saved component rather than a bare `componentId` placeholder — and before the prune, so it cannot put an unserved arm back on the wire. That position is the contract, not an implementation detail. This project uses the seam for its `capabilityGrid`, because core's feed pass serves only `feedDisplay` and flattens rows to title/summary/image, dropping the two fields that grid exists to show. ## Read ctx.siteId, never runtime.siteId A `hydrateLayout` transform is given `{ runtime, siteId, site }`. `siteId` is the site this REQUEST is for, resolved from the Host header. `runtime.siteId` is the DEFAULT site, resolved once at boot — a process-level fallback that public render code must not key on. A transform that queries with `runtime.siteId` serves the first site's rows on every other domain, and does it silently, because the shape of the data is right. This is not hypothetical: this project hit exactly that and now passes `siteId` explicitly — `hydrateLayout: (layout, { runtime, siteId }) => hydrateCapabilityGrids(layout, runtime, siteId)` in `sites/default/index.ts`. ## What survives with JavaScript off A `'use client'` module still server-renders its initial HTML, so a visitor with JavaScript off sees whatever render produced — the tab open by default has to contain something rather than fill in on mount. The `.md` twin and `llms-full.txt` are a different surface with a different rule: they never call your component at all. A node's Markdown projection reads the stored `body` column when there is one, and otherwise projects the stored LAYOUT DOCUMENT straight to HTML — a walk over the prop schema, not a render of your component. For a custom module that means only PROP VALUES reach the twin — by default the `text`/`textarea`/`richText` ones, and whatever a prop's `ax` hint adds or removes — exactly as [Designing module props](/developing/designing-module-props-for-the-person-who-edits-the-page/) describes for search. Copy your component renders that no prop holds never reaches it. The editor canvas announces itself through a React context, not a prop — one that defaults to false and that the public renderer never provides. That is how the built-in form modules render a form-less preview inside the editor's own form. Read the context, don't sniff the URL. ## Owner copy inside a JSON-LD script tag ends the tag If a module emits `