# Quickstart: Builder with your agent

Builder at [mantle.tools/builder](https://mantle.tools/builder) is a browser page that exposes WebMCP tools to your agent. This page is for people who want to design and verify a Manifest without writing code first, then hand the result to a coding agent.

## 1. Open Builder with your agent

Open Builder in a browser that supports WebMCP. Choose Intake, Reservation, Transaction, Procurement, or Blank and copy the starting prompt into your agent chat.

Without WebMCP, the page offers an Open in ChatGPT link. The destination browser still needs to support the tools.

## 2. Describe the workflow

Tell your agent who uses the service, what they submit, what staff can do, and which changes need approval. The agent calls `builder_get_started` before editing. That call returns the pinned grammar summary, the preset list, the active project and its revision, and the exact next tool calls. Reference sections `overview`, `schema`, `view`, `procedure`, `trigger`, `builtin` and `auth` return the corresponding full page from the vendored SDK handbook. `builtin` and `procedure` share the Procedure page; no Markdown-heading extraction is used.

Builder accepts two kinds of edit:

| Tool | Applies to | Input |
|---|---|---|
| `builder_apply_preset` | An empty project only | One preset name: `intake`, `reservation`, `transaction`, `procurement`. `blank` skips the preset. |
| `builder_apply_manifest_patch` | Any project | An RFC 6902 JSON Patch against the committed Manifest; validated before it is committed. |

Both require `baseRevision`. Builder rejects a patch whose base is older than the current revision, so an agent cannot overwrite work it has not seen. Builder authors declarative Views and builtin Procedure handlers only; handler refs need generated TypeScript in a real project.

## 3. Inspect and exercise the preview

Use the Admin graph to inspect atoms and their connections. Ask your agent to run `builder_execute_preview`: it resets or seeds the persistent preview sandbox in the browser, calls the projected capabilities as a mock `anonymous`, `member` or `owner` actor, and reports the persisted entries before and after. Verify both allowed operations and denied access. With `navigation: "walkthrough"` the agent can step you through each call and the affected Admin page.

Preview data belongs to the sandbox, not production. Nothing runs on a Worker, no D1 is touched, and no identity is real. The small graph shown on the public homepage is a separate read-only example.

Every accepted edit also returns a `draft-delta` D1 preview: source and target
storage fingerprints, additive/destructive risk, ordered SQL, and an immutable
checksum. Builder verifies the checksum but does not call this a deployment
artifact: Cloud rebuilds that from the last active revision. Preview execution
stays on Mantle's IndexedDB adapter, with no second SQLite/WASM runtime.
Destructive changes remain visible for export/reset review; CI executes
additive SQL against SQLite and Mantle Cloud/D1 verifies it before upload.

## 4. Hand off the service

Download the handoff ZIP from the project menu. Builder refuses to build it when the project has no atoms or when the project changed since the snapshot was taken.

### What the handoff contains

- `manifests/site.yaml` — the committed Manifest. This is the source of truth.
- `HANDOFF.md` — the pinned `@aotter/mantle*` version, the source revisions, links to the pinned develop skill and grammar, and the steps a coding agent follows.
- `DEPLOY.md` — local verification, pushing to GitHub, the first `wrangler` deploy, and enabling Admin with self-managed GitHub OAuth.
- `examples/register-webmcp.example.ts` — a reference for registering the service's own WebMCP tools in a page; every placeholder must be replaced from the Manifest.

The ZIP is a coding-agent handoff, not a runnable application. It deploys nothing and contains no secrets. Do not copy sandbox identities or preview records into the real service.

### From handoff to deployment

1. Give the ZIP to a coding agent. It authors the project around `manifests/site.yaml`: `package.json` pinned to the version in `HANDOFF.md`, the Worker entry, provider configuration, and the frontend the Manifest cannot express. See [Project layout and the CLI loop](./project-and-cli.md).
2. The agent runs only the checks the project declares: `mantle validate`, `mantle generate`, typecheck, tests when a `test` script exists, build, and a Worker dry run.
3. Follow [Deploy and operate](../cloudflare/deploy-and-operate.md) for the first deploy and the verify loop.
4. Follow [Authentication](../cloudflare/authentication.md) to set `MANTLE_AUTH_MODE`, the non-secret vars and the two secrets, then sign in as the first owner. Admin and `/mcp/staff` return `503 setup_incomplete` until this is complete.

## Source
- [Manifest reference](https://github.com/aotter/mantle/blob/37f74c8e6d03d76f723656e68745ebe36c08005d/docs/handbook/reference/manifest.md)
- [`skills/develop/SKILL.md`](https://github.com/aotter/mantle/blob/361e143a4a1fb4aca050bb0454070284dc64d447/skills/develop/SKILL.md)
- [`docs/direct-authoring.md`](https://github.com/aotter/mantle/blob/361e143a4a1fb4aca050bb0454070284dc64d447/docs/direct-authoring.md)
- Builder tool definitions: [`src/lib/builder.ts`](https://github.com/aotter/mantle-home/blob/main/src/lib/builder.ts), [`src/App.tsx`](https://github.com/aotter/mantle-home/blob/main/src/App.tsx)
- Handoff ZIP contents: [`src/lib/project-export.ts`](https://github.com/aotter/mantle-home/blob/main/src/lib/project-export.ts)