Update FlutterFlow CLI documentation: rename 'Download Projects' to 'Exporting Projects' and enhance 'Build with AI Agents' section with more info about the mcp tool

Author: PoojaB26

docs/ff-concepts/advanced/flutterflow-cli/exporting-projects.md

@@ -8,8 +8,7 @@ keywords: [CLI, Collaboration, FlutterFlow, Projects, Local Management]
 ---
 
 
-# Download Projects with FlutterFlow CLI
-
+# Exporting Projects
 Follow the steps below to export your project.
 
 <div style={{

docs/ff-concepts/advanced/flutterflow-cli/flutterflow-mcp.md

@@ -1,137 +1,214 @@
 ---
-slug: /flutterflow-cli/mcp
+slug: /flutterflow-cli/build
 title: Build with AI Agents
-description: Learn how to created and edit FlutterFlow projects with your own agents.
+description: Create and edit FlutterFlow projects from your terminal using your preferred AI coding agent.
 tags: [CLI, AI, MCP]
 sidebar_position: 3
 keywords: [CLI, Agentic AI, Projects, Local Management, MCP]
 ---
 
-
 # Build with AI Agents
-The FlutterFlow CLI lets you build and edit FlutterFlow apps in the terminal instead of in the visual builder. You can use it to create brand-new apps or for changes to ones you already have. It's designed for AI agents, so you can hand work off and review their changes like any other code.
 
-:::info[Remember]
+The FlutterFlow CLI lets you create and edit FlutterFlow apps from the terminal using your own AI coding agent — Claude Code, Gemini CLI, Codex, or any MCP-compatible client. You describe what you want in plain English, the agent plans and applies the changes, and the result lands as a real FlutterFlow project you can open in the visual builder.
 
+A FlutterFlow project is the source of truth. The CLI is how you create or edit it from your local workspace.
+
+:::info[Remember]
 - **FF CLI is not a replacement for the visual builder.** FlutterFlow is still faster for most visual work. FF CLI is for precision, repeatability, and automation.
-- **FF CLI doesn't execute your app.** It produces a FlutterFlow project, which you can test and run inside FlutterFlow visual builder.
+- **FF CLI doesn't execute your app.** It produces a FlutterFlow project, which you can test and run inside the FlutterFlow visual builder.
 :::
 
-A FlutterFlow project is the source of truth. FF CLI is how you create or change it from code. You can write an app in the terminal, open the result in FlutterFlow's visual editor, and keep going in either direction. Both paths give you the same FlutterFlow app.
-
 ![ff-cli-ff-builder-using-same-ff-app.avif](../imgs/ff-cli-ff-builder-using-same-ff-app.avif)
 
-### Create Projects
+## Architecture
+
+`flutterflow ai init` creates a local **workspace** - a folder pre-configured with an MCP config file pointing at the FlutterFlow MCP server. When you launch your AI agent inside that folder, it discovers the MCP server and gains a set of tools that talk to FlutterFlow's cloud:
 
-Let’s walk through using the FlutterFlow CLI by building a simple meditation app:
+1. You prompt the agent.
+2. The agent plans changes and calls the MCP server's tools.
+3. The MCP server applies those changes to your FlutterFlow project.
+4. You verify the result in the FlutterFlow visual builder.
 
-#### 1. Start the workspace setup
+The workspace is just a folder on your disk. The actual project lives in FlutterFlow.
+
+:::tip[What is MCP?] 
+The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that lets AI agents call external tools. The FlutterFlow AI MCP server exposes FlutterFlow's project APIs to your agent so it can read and modify your project on your behalf.
+:::
+
+:::info[Prerequisites]
+
+Before you start, make sure you have:
+
+- **FlutterFlow CLI installed.** See [Installation](./overview.md).
+- **A FlutterFlow API key.** See [generating an API token](../../../accounts-billing/account-management.md#how-do-i-generate-an-api-token).
+- **An MCP-compatible AI agent installed locally** — for example, [Claude Code](https://www.claude.com/product/claude-code), [Gemini CLI](https://github.com/google-gemini/gemini-cli), or [Codex](https://github.com/openai/codex).
+- **A FlutterFlow project ID** (only if you're editing an existing project).
+::: 
+
+## Setup Workspace
 
 Open your terminal in the folder where you want the workspace to live, then run:
 
 ```bash
 flutterflow ai init
 ```
 
-This launches an interactive setup wizard.
+This launches an interactive setup wizard. Walk through the prompts:
+
+1. **Workspace name.** A short, lowercase name with no spaces. This becomes the folder name for your project.
+   ```
+   Workspace name
+     Directory to scaffold the FlutterFlow AI workspace in.
+   > mindfly
+   ```
+2. **Environment.** Use ↑ / ↓ to highlight the FlutterFlow environment you want this workspace to target, then press **Enter**.
+3. **Link to an existing FlutterFlow project?** Press **Enter** (default `N`) to create a new app. Answer `y` to bind the workspace to an existing project — the wizard will then ask for the project ID.
+   ```
+   Link to an existing FlutterFlow project? [y/N]
+   ```
+4. **FlutterFlow API key.** Paste your API key and press **Enter**. Input is masked.
+5. **Register MCP server with detected coding CLIs.** The wizard scans your `PATH` and offers to register the FlutterFlow AI MCP server with each agent it finds (Claude Code, Gemini CLI, Codex). Answer `Y` (default) for each one you plan to use.
+   ```
+   Register FlutterFlow AI MCP server with coding CLIs
+     Detected: claude, gemini, codex
+     Register with claude? [Y/n]
+   ```
+6. **Confirm.** The wizard prints a summary. Review it and press **Enter** (default `Y`) to proceed.
+   ```
+   Ready to create:
+     Workspace:  mindfly
+     Project ID: (none — unlinked)
+     API key:    set (***abcd)
+     Base URL:   https://api.flutterflow.io  (built-in for prod)
+     MCP CLIs:   claude, gemini, codex
+
+   Proceed? [Y/n]
+   ```
+
+When the wizard finishes, you'll have a workspace folder ready for your agent. Depending on which CLIs you registered, the folder will contain one or more of:
+
+- `.mcp.json` — for Claude Code
+- `.gemini/settings.json` — for Gemini CLI
+- `.codex/config.toml` — for Codex
+
+Each file points the corresponding agent at the FlutterFlow AI MCP server.
+
+## Launch your Agent
+
+Move into the workspace and start your agent. The example below uses Claude Code; the same pattern applies to any agent you registered in the wizard — `cd` into the workspace and launch the agent's CLI.
 
-#### 2. Name your workspace
+```bash
+cd mindfly
+claude
+```
 
-The wizard will ask for a workspace name or path. Type a short, lowercase name with no spaces. This becomes the folder name for your project.
+The first time the agent opens the workspace, it detects the new MCP server and asks you to approve it. The exact prompt varies by agent — Claude Code's looks like this:
 
 ```
-Workspace name or path
-> mindfly
-```
+New MCP server found in .mcp.json: flutterflow_ai
 
-#### 3. Pick an environment
+MCP servers may execute code or access system resources.
+All tool calls require approval.
 
-Next you'll see a list of FlutterFlow environments to connect to. Use ↑ / ↓ to highlight your choice and press **Enter**.
+> 1. Use this and all future MCP servers in this project
+  2. Use this MCP server
+  3. Continue without using this MCP server
+```
+
+Choose **option 1** to approve the FlutterFlow AI MCP server (and any others added to this workspace later) without being asked again.
 
+> **Why approve?** Without the MCP server, the agent can edit local files but can't push changes to your FlutterFlow project. With it approved, the agent has the same tools you'd run yourself from the CLI.
 
-#### 4. Paste your FlutterFlow API key
+## Generate a New App
 
-The wizard will ask for your API key. Paste it and press **Enter**.
+With the agent connected, describe the app you want at the prompt:
 
 ```
-FlutterFlow API key
-> your-api-key-here
+> create a minimalist meditation app
 ```
 
-#### 5. Choose: New app or Edit existing
+Phrase it however you like — `a recipe-sharing app with a social feed`, `a habit tracker with streaks`, `a tip calculator for restaurants`. The agent plans the app, generates the changes, pushes them to FlutterFlow through the MCP server, and reports back. Open FlutterFlow in your browser and navigate to the project — the generated app will be reflected in the visual builder. From there you can keep refining visually or send another prompt to the agent.
 
-The wizard now asks whether you want to edit an existing FlutterFlow project or create a new one:
+Once the app exists, the workspace is bound to it. Follow-up prompts in the same session are treated as edits, not new generations, you'll see the agent acknowledge the switch with something like:
 
 ```
-Existing project ID to edit (press Enter to create a new app)
-> paste-your-project-id-here
+The project is bound, so I'll switch to edit mode.
+Let me check the workspace and read the edit template.
 ```
 
-Press **Enter** with no input to create a new app. (To edit an existing project instead, paste its project ID here.)
+From that point on, the same rules apply as when [editing an existing project](#edit-an-existing-project) - concurrency, branches, scope, and refreshing context.
 
-#### 6. Confirm the setup
+## Edit an Existing Project
 
-The wizard prints a summary of what it's about to do:
+:::info[Prerequisite]
+Have your **project ID** ready. Open the project in the FlutterFlow editor. The project ID is the path segment after `/project/` in the URL.
+:::
 
-```
-Ready to create FlutterFlow AI workspace:
-   Workspace:   /Users/.../projects/mindfly
-   Flow:        Create a new app
-   Environment: beta
-   SDK:         0.1.6 (build aed0f835)
-   Base URL:    https://api.flutterflow.io/v2-staging
-
-Proceed? [Y/n]
+Editing an existing project follows the same flow as [creating a new one](#set-up-a-workspace) — you run `flutterflow ai init` to scaffold a workspace, then drive changes from your agent. The only difference is one step in the wizard: when it asks **Link to an existing FlutterFlow project?**, answer `y` and paste your project ID:
+
+```dart
+Link to an existing FlutterFlow project? [y/N] y
+Project ID
+> my-meditation-app-x7k2p9
 ```
 
-Review the workspace path, environment, and flow. If everything looks right, press **Y** and **Enter**.
+The workspace is now bound to that project. `cd` into the workspace folder, [launch your agent](#launch-your-agent), and describe the changes you want — "add a profile screen", "switch the primary color to teal", "wire up the login form to Firebase Auth". The agent reads the current project, plans the change, and pushes it through the MCP server. Open FlutterFlow in your browser to verify.
 
+### Concurrent Edits with Builder
 
-#### 7. Move into the workspace and launch your agent
+You can edit visually while an agent is working, but writes use **optimistic concurrency**: when the agent pushes, the server checks the project's last-modified timestamp against the agent's snapshot. If anyone else (you in the visual builder, a teammate, or another agent) modified the project in between, the push is rejected. The agent will re-read the latest state and retry — which may also mean re-planning, if your change conflicts with what it was about to do.
 
-Move into the new workspace folder and start your preferred coding agent. This example uses Claude Code:
+So nothing gets silently overwritten, but expect occasional retries when you and the agent are editing the same project at once.
 
-```bash
-cd mindfly
-```
-and then...
-```bash
-claude
-```
+## Branches and Rollback
 
-#### 8. Approve the FlutterFlow AI MCP server
+:::warning[Agents commit to main]
+Workspaces always target the project's **main branch**. There's no flag to point them at a feature branch. Every successful push creates a commit on main, so for high-stakes projects, work on a clone, make sure version history is enabled, or coordinate with your team before letting an agent run.
+:::
 
-The first time the agent opens the workspace, it will detect the new MCP server and ask for permission:
+To roll back, use FlutterFlow's project version history in the visual builder — the same mechanism you'd use for visual edits. Each agent push lands as a commit there with whatever commit message the agent supplied.
 
-```
-New MCP server found in .mcp.json: flutterflow_ai
+## Refreshing Stale Context
 
-MCP servers may execute code or access system resources.
-All tool calls require approval.
+If you've made visual edits since the agent last read the project, the agent's local snapshot is stale. Two ways to fix it:
 
-> 1. Use this and all future MCP servers in this project
-  2. Use this MCP server
-  3. Continue without using this MCP server
-```
+- **Ask the agent to refresh.** Most agents call the MCP `refreshContext` tool on their own when they detect drift, but you can prompt explicitly: "refresh the project context."
+- **Run it from the CLI.** `flutterflow ai context-check` reports whether the local snapshot is behind, and `flutterflow ai refresh-context <project-id>` pulls the latest.
 
-Choose **option 1** to use the FlutterFlow AI MCP server (and any others added to this workspace later) without being asked again. Press **Enter** to confirm.
+## Switching Projects
 
-> **Why approve?** Without the MCP server, the agent can edit local files but can't actually push changes to your FlutterFlow project. With it approved, the agent has the same tools you'd run yourself from the CLI.
-> 
+A workspace is bound to one project. To work on a different project, run `flutterflow ai init` in a **new** folder and link it to the new project ID. `init` refuses to run in a non-empty directory, so it won't re-bind an existing workspace.
 
-#### 9. Describe your app in plain English
+## Agent edit scope
 
-Claude Code is now connected to your workspace and the FlutterFlow AI MCP server. Type what you want to build at the prompt:
+**In scope**
 
-```
-> create a minimalist meditation app
-```
+- Pages, components, app state, theme, navigation, action blocks, app events
+- Custom functions, actions, widgets, classes, and enums
+- API endpoints, queries, custom data types and enums
+- Pub and library dependencies, design tokens, GenUI catalog, Firebase Auth wiring
+
+**Out of scope**
+
+- A few DSL gaps that may close over time — shaders, and parameter types like `Document`, `SQLiteRow`, `WidgetBuilder`, `ChildSlotParam`, `ApiResponse`, `TimestampRange`, `GooglePlace`, `RevenueCat` types, `CustomCloudFunctionResponse`, and `ResponseStreamMessage`.
+- Anything outside the FlutterFlow project itself — running the app, deploying it, creating Firebase projects, managing secrets, App Store submissions.
+
+## MCP server tools
+
+Once approved, the FlutterFlow AI MCP server gives your agent the following tools.
+
+**Core actions**
 
-Press **Enter**. The agent will plan the app, generate the code, push it to FlutterFlow through the MCP server, and report back.
+| Tool | What it does |
+| --- | --- |
+| `run` | Applies a planned set of changes to your FlutterFlow project. This is how edits get pushed. |
+| `validate` | Dry-runs a change without pushing it, so the agent can catch errors before committing. |
+| `inspect` | Reads project structure — either a whole-project summary or a scoped view. |
+| `resources` | Lists reusable project and library resources (components, custom code, etc.). |
+| `init` | Scaffolds a new FlutterFlow AI workspace. |
 
-#### 10. Verify the app in the FlutterFlow visual builder
-Open FlutterFlow in your browser and navigate to your project. You’ll see the generated app reflected in the visual builder. From here, you can continue refining the app visually or iterate further using the AI agent.
+**Supporting**
 
-### Modify Projects
-To modify an existing project, [paste your project ID](#5-choose-new-app-or-edit-existing) when prompted instead of pressing Enter. This connects the workspace to your current FlutterFlow app. Once set up, you can use the AI agent to make changes, and updates will be pushed directly to the existing project.
+`status`, `search`, `refreshContext`, `contextCheck`, `docs`, `history` — used by the agent for project metadata, searching, refreshing its context, looking up FlutterFlow documentation, and reviewing prior tool calls.
 
+The agent calls these tools on your behalf based on your prompts. Every tool call is subject to your agent's approval rules.