Tools: editing

These tools change site code, colors, fonts, layout and the brand guide. They all need an open turn. Follow the Rules for agents. See the Tool reference for shared errors.

write_file

Creates, replaces or deletes one file. A new page starts as ready to publish. A new component is added to the component list automatically.

When to use it: To create a file, delete one, or rewrite more than half of an existing one. For small changes use patch_file.

Needs an open turn: Yes. Call start_turn first.

Input	Type	Required	Meaning
path	string	Yes	File path relative to the site root, such as src/components/sections/Hero.astro.
content	string	Yes	The file's complete content. Send an empty string when deleting.
action	string: create, update or delete	Yes	What to do with the file.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "path": "src/components/ui/Badge.astro",
  "action": "create",
  "content": "---\ninterface Props { label?: string }\nconst { label = 'New' } = Astro.props\n---\n<span data-component=\"Badge\" class=\"rounded-full bg-accent px-3 py-1 text-sm text-white\">{label}</span>\n"
}

Example result

{
  "success": true,
  "path": "src/components/ui/Badge.astro",
  "action": "create",
  "errors": [],
  "fixes": []
}

The result can also include multiImporterWarning when the file is a component used on several pages, so a change affects all of them.

Errors

You see	What it means	What to do
success: false with errors	The change broke a site rule (for example, a raw color or a component outside the three folders). Nothing was written. fixes may suggest the correction.	Fix the content and call again.
"… is generated — don't edit it" or "use … instead"	The file is managed by a dedicated tool.	Use the tool the message names. See Rules for agents.
"Components must live under src/components/{sections,ui,layout}/"	Components can only go in those three folders.	Move the file into one of them.
"write_file/patch_file can only write site source (src/**)"	The path is outside the code you can edit.	Use the dedicated tool for structured data, or pick a path under src/.
"SSR render error …" with success: false	The file was saved, but the page doesn't render.	Fix the error before calling end_turn. Check with get_preview.
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

patch_file

Makes search-and-replace edits to an existing file. Each search text must appear exactly once. Patches apply in order, so later ones see earlier changes.

When to use it: For most edits: changing classes, text or props.

Needs an open turn: Yes. Call start_turn first.

Input	Type	Required	Meaning
path	string	Yes	File path relative to the site root.
patches	array of {search, replace}	Yes	Each search is exact text that appears once in the file; replace is the new text.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "path": "src/components/sections/Hero.astro",
  "patches": [
    {
      "search": "class=\"text-5xl font-bold\"",
      "replace": "class=\"text-4xl font-bold\""
    }
  ]
}

Example result

{
  "success": true,
  "path": "src/components/sections/Hero.astro",
  "errors": [],
  "fixes": []
}

Errors

You see	What it means	What to do
"Search string not found: …"	The search text isn't in the file.	Read the file again and copy the text exactly.
"Ambiguous: … found N times"	The search text appears more than once.	Include more surrounding text so it's unique.
"File not found: …"	There's no file at that path.	Check the path, or create it with write_file.
success: false with errors	The change broke a site rule (for example, a raw color or a component outside the three folders). Nothing was written. fixes may suggest the correction.	Fix the content and call again.
"… is generated — don't edit it" or "use … instead"	The file is managed by a dedicated tool.	Use the tool the message names. See Rules for agents.
"Components must live under src/components/{sections,ui,layout}/"	Components can only go in those three folders.	Move the file into one of them.
"write_file/patch_file can only write site source (src/**)"	The path is outside the code you can edit.	Use the dedicated tool for structured data, or pick a path under src/.
"SSR render error …" with success: false	The file was saved, but the page doesn't render.	Fix the error before calling end_turn. Check with get_preview.
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

modify_layout

Changes the parts of the layout every page shares: which component is the header and which is the footer, and page navigation settings (client-side routing and the page transition).

When to use it: To add, swap or remove the header or footer, or when the user asks to change page transitions. The component must already exist in src/components/layout/.

Needs an open turn: Yes. Call start_turn first.

Input	Type	Required	Meaning
actions	array	Yes	One or more changes, applied together. Each has an action (below).

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "actions": [
    {
      "action": "addComponent",
      "slot": "header",
      "componentName": "Navbar"
    },
    {
      "action": "updateSettings",
      "fields": {
        "clientRouter": true,
        "pageTransition": "fade"
      }
    }
  ]
}

Example result

{
  "success": true
}

Each action:

Field	Type	Meaning
action	addComponent, removeComponent or updateSettings	What to change.
slot	header or footer	Needed for addComponent and removeComponent.
componentName	string	The layout component to place. Needed for addComponent.
fields.clientRouter	boolean	Swap pages without a full reload.
fields.pageTransition	none, fade or slide	The animation between pages while client-side routing is on.

Only change clientRouter or pageTransition when the user asks for it. See Page transitions and navigation.

Errors

You see	What it means	What to do
applied with error	Some actions failed; the message says which.	Fix those actions and call again.
Component not found	The header or footer component doesn't exist.	Create it in src/components/layout/ with write_file first.
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

modify_tokens

Adds, changes, renames or removes the site's colors and fonts. Renames update every use across the site. Changing a value keeps every use working.

When to use it: Whenever the design needs a color or font that isn't in get_tokens, or the user asks to change one.

Needs an open turn: Yes. Call start_turn first.

Input	Type	Required	Meaning
changes	array	Yes	One or more operations, applied together. Each has an operation and the fields it needs (below).

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "changes": [
    {
      "operation": "addScale",
      "scaleName": "primary",
      "baseHex": "#2563eb"
    },
    {
      "operation": "modifyFont",
      "slotName": "heading",
      "font": "Playfair Display"
    }
  ]
}

Example result

{
  "success": true
}

Operations:

operation	Fields	What it does
addScale	scaleName, baseHex	Adds an 11-shade color scale generated from the 500 shade.
importTailwindScale	tailwindColor, optional scaleName	Adds a stock Tailwind palette (such as emerald) with exact values.
modifyScale	scaleName, baseHex	Shifts a whole scale to a new 500 shade.
modifyShade	scaleName, shade, hex	Changes one shade, such as 700.
addSwatch / modifySwatch	name, hex	Adds or recolors a single color. hex takes any CSS color.
renameScale / renameSwatch	scaleName or name, newName	Renames and updates every use.
removeScale / removeSwatch	scaleName or name	Removes the color and strips every class that used it.
addFont / modifyFont	slotName, font	Adds or changes a font from Google Fonts by name. It's hosted with your site.
renameFont	slotName, newName	Renames a font slot and updates every use.
removeFont	slotName	Removes a font slot and strips its classes.

Name scales by role (primary, accent, neutral), not by color. To recolor, modify; don't remove and re-add. See Colors and Fonts.

Errors

You see	What it means	What to do
Font slot name rejected	Font names that clash with Tailwind (bold, light, sans, serif, mono and similar) aren't allowed.	Pick another name, such as display.
Can't remove the last font	A site needs at least one font.	Change it with modifyFont instead.
Name already exists	A color with that name exists.	Pick another name, or modify the existing one.
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

modify_element_defaults

Sets default styling for plain HTML elements, such as the page's background, text color and font (body) or every h1. Classes on an element override its defaults.

When to use it: For site-wide defaults. Use body for the page background, text color and default font.

Needs an open turn: Yes. Call start_turn first.

Input	Type	Required	Meaning
changes	array	Yes	Each item has operation (add, modify or remove), element (such as body or h2) and classes (Tailwind classes).

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "changes": [
    {
      "operation": "modify",
      "element": "body",
      "classes": "bg-cream text-ink font-body antialiased"
    }
  ]
}

Example result

{
  "success": true
}

In the editor these appear under Settings → General → Page Defaults. See Page defaults.

Errors

You see	What it means	What to do
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

set_brand_guide

Replaces the site's brand guide with new Markdown. The old version can be restored by rejecting the session.

When to use it: When the user asks to record brand voice, style or rules for future work.

Needs an open turn: Yes. Call start_turn first.

Input	Type	Required	Meaning
content	string	Yes	The complete new brand guide, in Markdown. It replaces the old one.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "content": "# Voice\nWarm and plain. Short sentences.\n\n# Colors\nUse accent only for calls to action."
}

Example result

{
  "success": true
}

Read it first with get_brand_guide and keep what's there unless the user wants it gone. See Brand guide.

Errors

You see	What it means	What to do
not_lock_holder	Your agent has no open turn on this site, or its turn lapsed.	Call start_turn, then retry.
lock_lost	Someone took the site back (for example with Take back control) or the turn expired and was reopened.	Call start_turn to begin a new turn, then retry.
site_publishing	The site is publishing. Editing is paused until it finishes.	Wait for the publish to finish, then retry.

Related

• Rules for agents
• Styling rules
• Project files