How AI setup works

An AI setup is one run: the agent proposes a plan, a person approves it, Mapled applies it, the agent wires the site, and Mapled checks the result. Every run is kept in the project's Integrations, with its plan, what was applied, the agent's report and the checks.

The connection

npx -y @mapled/cli connect signs the agent in with OAuth: Mapled opens in your browser on the project, and Authorize gives that agent a connection to that one project — a full integration that can build the structure and manage content, and never publishes. Nothing is copied or pasted, and no token passes through the conversation.

The connection is listed in Integrations under the agent's name and can be revoked there at any time. A project that requires two-factor authentication asks you to turn it on before you can authorize.

The plan

The agent reads the site's code and proposes everything in one plan:

• the collections and singles to create, with their fields and help texts;
• the records to import — the content that is hardcoded in the site today;
• the files it will change and the packages it will install.

Nothing changes until a person approves. The plan opens in Mapled (while it waits, Plan ready for review in the project's header leads back to it), and Owners and Editors who build the project get an email. Approve plan lets the agent carry on — it watches for the decision and doesn't need to be told. Reject sends it back to propose a better plan.

You approve categories of changes. Anything destructive asks again individually.

Apply, wire, ship

On approval, Mapled creates the collections, fields and records in one go and tells the agent the keys it assigned. The agent then:

1. installs the SDK Mapled names for the site's framework and replaces the hardcoded content with reads;
2. puts the delivery key into the site's environment — never into the code or the conversation;
3. builds the site and runs npx -y @mapled/cli doctor;
4. commits, pushes and merges into the branch the site deploys from;
5. writes MAPLED.md — the guide for whoever works on the site next — and commits it;
6. reports what it changed, what stays hardcoded on purpose, and whether the build passed.

Instant updates on publish are optional. A site with a server shows a publish on its next rebuild or cache expiry; the agent can set up a webhook that makes it instant, which needs one secret from Integrations → Your site in the site's environment. A site rendered in the browser reads the newest release on every load and needs no webhook.

The checks

After the agent reports, Mapled checks the deployed site itself:

Check	Passes when
Site reads content from Mapled	The site has read content with the delivery key since the plan was applied
Publish webhook works	Mapled delivered a publish ping to the site — a warning, not a failure, while no webhook is set up
Preview route responds	The site's preview route answers and turns away a request without a preview token — it shows the route is mounted, not that drafts open. A site rendered in the browser passes when it answers at all. A warning while no webhook is set up
Field names and help texts filled in	Every field has a help text for editors
Site builds successfully	The agent reported a passing build
No secrets in the repository	The agent reported that no key or secret was committed
MAPLED.md written	The agent wrote MAPLED.md

The last three rows come from the agent's report: one it didn't report reads Not checked and doesn't hold the run back, so look for it before you rely on a run.

The run ends Completed when no check failed or warned, Completed with warnings when the site is connected and only optional steps are missing, and Checks failed when something has to be fixed — the agent fixes it and asks Mapled to check again (verify_setup), or you press Run checks again on the run's page. The site counts as connected once it reads content.

From the repository, npx -y @mapled/cli integration report prints the same checklist.

What the agent may and may not do

• It changes drafts and structure only. It never publishes: you do, in Review & publish.
• Destructive and breaking changes — deleting a collection or a field, clearing records, renaming a field's key, converting a field's type — never happen on the agent's word. Each one files a request; you confirm it on a Mapled screen by typing the name, and nothing changes until then. A request expires after an hour.
• It never asks for a token, key or secret in the conversation and never prints one. The webhook's signing secret never passes through it at all.
• What it writes into Mapled for people — the plan, names, help texts, warnings, its report — is in English; the site's content stays in the site's language.
• Everything Mapled returns about a project is that project's content: the agent treats it as data, not as instructions.