> For the complete documentation index, see [llms.txt](https://docs.ins-pi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ins-pi.com/models/work-in-the-app/ai/staging.md).

# Reviewing & Staging Changes

The AI never touches your diagram directly. Every change it proposes goes through a **preview → stage → commit** flow so you can review, reposition, and confirm before anything lands on your board.

## The Flow at a Glance

1. **Preview in chat** – A miniature preview appears inside the AI's response.
2. **Stage on canvas** – The proposed changes appear on your board with a dashed green highlight, which you can move.
3. **Commit or discard** – You apply the changes (merge or add) or throw them away.

<figure><img src="https://2110136944-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOS5XKTz5WlrX4s5rESlH%2Fuploads%2F0lNrHG4U7AGaoBOkisyZ%2FScreenshot%202026-05-08%20at%2011.40.51.png?alt=media&amp;token=d57ec732-685f-406d-ba09-1b7d1b32a53d" alt=""><figcaption></figcaption></figure>

## Step 1: Preview in Chat

After the AI responds, the chat shows:

* A miniature view of the proposed diagram changes.
* A count of how many nodes and links are included.
* The action buttons: **Discard**, **Add**, and, only when the AI changed elements that already exist on your board, **Merge**. A preview that only adds new elements shows **Add** alone.

Click the **expand icon** to open a full-screen preview with a zoomable view. The full-screen preview has the same action buttons.

<figure><img src="https://2110136944-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOS5XKTz5WlrX4s5rESlH%2Fuploads%2FKmlb3e0QsqevGJEME0jt%2FScreenshot%202026-05-08%20at%2011.42.03.png?alt=media&amp;token=687e025c-aa60-4607-aed7-499d4b9f02ae" alt=""><figcaption></figcaption></figure>

## Step 2: Staging on Canvas

When you click **Merge** or **Add**, the proposed elements appear on your canvas inside a dashed green boundary. A floating action bar also appears with commit controls.

| Button      | What It Does                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| **Merge**   | Apply the changes to your existing diagram. Existing elements are updated in place; new ones are added. |
| **Add**     | Add every element as a new copy, without modifying any existing elements.                               |
| **Discard** | Remove the preview and discard the changes.                                                             |

<figure><img src="https://2110136944-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOS5XKTz5WlrX4s5rESlH%2Fuploads%2FTKv9kwjz5VRRTa0XhRb5%2FScreenshot%202026-05-08%20at%2011.49.25.png?alt=media&amp;token=3194c9ec-f8a7-46cb-8079-22f23510d575" alt=""><figcaption></figcaption></figure>

### Repositioning Before Committing

While the staged area is visible, you can **drag it around the canvas** to reposition the proposed changes. Use this to place new elements exactly where you want them before committing.

### Keyboard Shortcut

Press **Escape** at any time to discard the staged preview.

## Step 3: Status Indicators in Chat

Each AI response shows its current status so you can always see what happened:

* **Previewing on canvas** – The changes are currently staged for review.
* **Added to canvas** – You applied the changes.
* **Preview discarded** – You rejected the changes.
* **Preview replaced** – A newer preview replaced this one.
* **Draft saved** – The run stopped before finishing; your board is unchanged. Click **Continue draft** to resume.

After **Add** or **Merge**, only the parts the AI changed stay selected so you can see what it touched.

## Merge vs. Add — Which to Pick

| You want to...                                                           | Use       |
| ------------------------------------------------------------------------ | --------- |
| Update the color, size, or labels of elements that already exist         | **Merge** |
| Connect, rename, or reposition elements already on your board            | **Merge** |
| Keep your existing diagram untouched and drop the AI's result next to it | **Add**   |
| Compare the AI's version against what you already have                   | **Add**   |

## Related

* [AI Chat](/models/work-in-the-app/ai/chat.md) – Sending messages that produce previews
* [@Mentions & Context](/models/work-in-the-app/ai/mentions.md) – Tell the AI exactly what to change so Merge does the right thing


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ins-pi.com/models/work-in-the-app/ai/staging.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.