# Your first successful edit

This recipe works through MCP tools or their matching `/v1/<tool_name>` API endpoints. It requires `read` and `content` scopes.

## 1. Understand the site

Call `get_site_context` with `{}`. Record its `revision`, available folders and permissions. Call `get_capabilities` to see supported fields and designs.

Call `search_content` with `{"q":"Alumni milestones"}` to avoid duplicates. If the collection or story already exists, update it instead.

## 2. Validate a small batch

Replace `revision` below with the live value. Generate a fresh key for this logical change. Each `ref` is local to this batch; `$alumni` refers to the folder created in the preceding operation.

```json
{
  "revision": 1,
  "idempotencyKey": "alumni-milestones-001",
  "dryRun": true,
  "changes": [
    { "action": "create_folder", "ref": "alumni", "fields": { "name": "Alumni milestones" } },
    { "action": "create_entry", "ref": "welcome", "fields": {
      "folderId": "$alumni",
      "kind": "story",
      "title": "Every graduate has a story",
      "body": "A place to celebrate our alumni and the paths they take.",
      "status": "draft"
    } }
  ]
}
```

Send this to `apply_changes`. A successful dry run returns `valid: true` and does not write content, audit records or media. IDs from a dry run are not reserved.

## 3. Save the draft

Send the same request with `dryRun: false`. The response includes the new `revision`, `changeCount` and a `created` map containing actual IDs for `alumni` and `welcome`.

The batch saves once, atomically. If any change fails, none of the batch is saved. A new live edit between validation and saving returns `revision-conflict`; reread and reconcile rather than overwriting.

## 4. Preview

Call `preview_site` with `{}`. Open its `previewUrl` in your browser—no account login is required. It uses the real shared renderer, including private photos, for the exact saved revision. Inspect the homepage, a collection, and a profile at desktop and mobile sizes before publishing.

This is a secret, read-only link, not a public share URL. It expires after 10 minutes, when the draft changes, or when its connection is disconnected. Share only with the person reviewing the draft; keep it out of logs and public messages. Run `preview_site` again after edits or expiry. Reloading after the browser removes the secret from the address bar also requires a fresh link.

Tell the user what changed and provide the preview. Do not report the site as live: publishing is a separate step.

## 5. Publish only when requested

If the user asks to publish and the connection has permission, follow [publishing and delivery](publishing). Otherwise the draft is ready for the site's publisher.

## Reliable retries

If a save response is lost, resend the exact batch with the original revision and key. An accepted batch returns `replayed: true`; it is not created again. Changing a batch while reusing its key returns `idempotency-conflict`.