# 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

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.
