docs: headless & AI — CLI reference for the new commands + AI & MCP tab

ai/claude-code.mdx

@@ -0,0 +1,94 @@
+---
+title: Claude Code
+description: The forest plugin for Claude Code — vibe-code your Forest back-office from natural language.
+---
+
+# Claude Code — the `forest` plugin
+
+The **`forest` plugin** for [Claude Code](https://docs.claude.com/en/docs/claude-code) turns natural-language requests into Forest changes. You describe what you want; Claude runs the Forest CLI to make it happen, and you review the result in the app.
+
+One plugin, one skill per domain — each invoked as `/forest:<skill>`.
+
+## Prerequisites
+
+<Steps>
+  <Step title="Claude Code">
+    Install [Claude Code](https://docs.claude.com/en/docs/claude-code).
+  </Step>
+  <Step title="Forest CLI, logged in">
+    ```bash
+    npm install -g forest-cli
+    forest login
+    ```
+  </Step>
+</Steps>
+
+## Install the plugin
+
+```bash
+# add the Forest Admin marketplace, then install the plugin
+/plugin marketplace add forestadmin/ai-marketplace
+/plugin install forest@forest-admin-ai
+```
+
+Then reload and check the skills are available:
+
+```bash
+/reload-plugins
+/plugin        # Installed → forest → Skills
+```
+
+## The skills
+
+<CardGroup cols={2}>
+  <Card title="/forest:onboard" icon="rocket">
+    From zero to a running back-office — create a project (your database or a zero-DB demo), boot the dev agent, and (opt-in) deploy to production and invite your team.
+  </Card>
+  <Card title="/forest:layout" icon="table-cells">
+    Build the UI as code — workspaces with master→detail components, dashboards & charts, collection display, and folders.
+  </Card>
+  <Card title="/forest:workflows" icon="diagram-project">
+    Author workflows from a declarative `steps` spec — the skill compiles them to BPMN and deploys them, editable afterwards in the UI.
+  </Card>
+  <Card title="/forest:management" icon="users-gear">
+    Administer the project — roles (RBAC as code), users, teams, environments, branches, and production deploys.
+  </Card>
+</CardGroup>
+
+## Example prompts
+
+Just describe the outcome — the skill picks the right commands:
+
+- **Onboard** — *"Create me a Forest demo and start it."*
+- **Layout** — *"Add an 'AML Review' workspace: the list of AML alerts, and when I select one, the related customer's details below it."*
+- **Workflows** — *"Add a refund approval workflow on refund_requests: review → approve/reject → if approved, mark refunded → end."*
+- **Management** — *"Invite alice@acme.co as an editor on the Support team."*
+
+## The loop
+
+<Steps>
+  <Step title="Describe">
+    Tell Claude the outcome you want, in plain language.
+  </Step>
+  <Step title="Preview">
+    The skill shows the plan (and supports `--dry-run` on the underlying commands) before sending anything.
+  </Step>
+  <Step title="Apply">
+    Claude runs the CLI — creating the workspace, compiling the workflow, applying the layout…
+  </Step>
+  <Step title="Review">
+    Open the result in the Forest app, or pull it back as code (`forest layout pull`). Iterate by asking for changes.
+  </Step>
+</Steps>
+
+## How it works
+
+The plugin is a thin layer over the [Forest CLI](/reference/cli/overview): each skill resolves your intent into deterministic `forest` commands (`projects:create:*`, `layout:*`, `workflow:apply`, `roles:*`/`users:*`/`teams:*`, `environments:*`). Because the output is CLI calls and JSON (`forest-layout.json`, workflow BPMN, role CSVs), everything is versionable and reproducible.
+
+<Tip>
+Working on a `development` environment? Layout and workflow edits need a branch first (`forest branch <name>`) — the skills handle this. A zero-DB `create:demo` project accepts direct edits without a branch.
+</Tip>
+
+<Info>
+For writing agent code (Smart Actions, computed fields, hooks) use the companion **forest-code** plugin; for querying/manipulating data from an agent, see [MCP](/ai/mcp).
+</Info>

ai/mcp.mdx

@@ -0,0 +1,53 @@
+---
+title: MCP
+description: Expose your Forest Admin project to AI agents over the Model Context Protocol — query and manipulate data, run actions, inspect the schema.
+---
+
+# MCP — the Forest MCP server
+
+The **Forest MCP server** exposes your Forest project to any [Model Context Protocol](https://modelcontextprotocol.io) client (Claude, IDE agents, your own tools). Where the [`forest` plugin](/ai/claude-code) *builds* your back-office, MCP lets an agent *operate* on it — the same data and actions your team uses, through a governed interface.
+
+## What an agent can do
+
+<CardGroup cols={2}>
+  <Card title="Read" icon="magnifying-glass">
+    List and search records, follow relationships, and read a single record.
+  </Card>
+  <Card title="Write" icon="pen">
+    Create, update, and delete records, and associate/dissociate relationships.
+  </Card>
+  <Card title="Act" icon="bolt">
+    Run your collection's **Smart Actions** — the same business operations exposed in the UI.
+  </Card>
+  <Card title="Understand" icon="sitemap">
+    Describe collections, fields, and relationships so the agent can reason about your schema.
+  </Card>
+</CardGroup>
+
+## Governed by your permissions
+
+The MCP server acts **within Forest's authorization model** — an agent only sees and does what the authenticated scope is allowed to. Roles, scopes and permissions apply exactly as they do in the app, so exposing Forest over MCP doesn't widen access.
+
+<Warning>
+Giving an agent write and action access to production data is powerful. Start against a non-production environment, and scope the agent to a role with the minimum permissions it needs.
+</Warning>
+
+## Connecting
+
+Add the Forest MCP server to your MCP client (for example, as a connector in Claude). It's distributed as the **`forest-mcp`** plugin in the Forest Admin marketplace:
+
+```bash
+/plugin marketplace add forestadmin/ai-marketplace
+/plugin install forest-mcp@forest-admin-ai
+```
+
+<Info>
+Setup specifics (authentication, selecting the project/environment) are covered by the `forest-mcp` plugin. This page describes what the server enables; follow the plugin for exact connection steps.
+</Info>
+
+## When to use MCP vs the plugin
+
+| Goal | Use |
+|---|---|
+| Let an agent **read/write data or run actions** on an existing back-office | **MCP** (this page) |
+| **Build or configure** the back-office itself (layout, workflows, roles, onboarding) | [`forest` plugin](/ai/claude-code) |

ai/overview.mdx

@@ -0,0 +1,40 @@
+---
+title: AI & MCP
+description: Drive Forest Admin with AI — build and operate your back-office from Claude, and expose it to your own agents over MCP.
+---
+
+# AI & MCP
+
+Forest Admin is drivable by AI, in two complementary ways:
+
+<CardGroup cols={2}>
+  <Card title="Claude Code — the forest plugin" icon="wand-magic-sparkles" href="/ai/claude-code">
+    Describe what you want in plain language; Claude runs the Forest CLI to build it — onboarding, UI/layout, workflows, and administration. **Vibe-code your back-office.**
+  </Card>
+  <Card title="MCP — the Forest MCP server" icon="plug" href="/ai/mcp">
+    Expose your Forest project's data and actions to any MCP-compatible agent — query records, create/update/delete, run Smart Actions, inspect the schema.
+  </Card>
+</CardGroup>
+
+## Which one do I use?
+
+| You want to… | Use |
+|---|---|
+| **Build or configure** Forest (create a project, lay out a workspace, author a workflow, manage roles/teams) | **Claude Code** — the [`forest` plugin](/ai/claude-code) |
+| **Operate on your data** from an agent (read/write records, run actions) | **MCP** — the [Forest MCP server](/ai/mcp) |
+
+Both talk to Forest through interfaces you already have — the plugin orchestrates the [CLI](/reference/cli/overview); MCP speaks the Model Context Protocol. No UI required.
+
+## The idea
+
+Everything you do in the Forest UI can be done **headlessly** — and therefore **driven by an AI**:
+
+- **Layout as code** — collections display, workspaces (master→detail), dashboards, folders.
+- **Workflows as code** — author a process from a declarative `steps` spec; it compiles to BPMN.
+- **Administration as code** — roles (RBAC as CSV), users, teams, environments, deploy.
+
+Claude composes these from natural language; you review the result in the app. Because it all maps to CLI commands and JSON, it's **versionable, reviewable, and reproducible**.
+
+<Info>
+These capabilities are rolling out. The `forest` Claude Code plugin ships onboarding today, with layout, workflows and management skills in the same plugin.
+</Info>

docs.json

@@ -304,6 +304,19 @@
           }
         ]
       },
+      {
+        "tab": "AI & MCP",
+        "groups": [
+          {
+            "group": "AI & MCP",
+            "pages": [
+              "ai/overview",
+              "ai/claude-code",
+              "ai/mcp"
+            ]
+          }
+        ]
+      },
       {
         "tab": "Reference",
         "groups": [
@@ -343,10 +356,70 @@
               "reference/cli/overview",
               "reference/cli/init",
               "reference/cli/login",
-              "reference/cli/branch",
-              "reference/cli/push",
-              "reference/cli/deploy",
-              "reference/cli/switch"
+              {
+                "group": "Branches & deployment",
+                "pages": [
+                  "reference/cli/branch",
+                  "reference/cli/switch",
+                  "reference/cli/push",
+                  "reference/cli/deploy"
+                ]
+              },
+              {
+                "group": "Projects",
+                "pages": [
+                  "reference/cli/projects-create-demo",
+                  "reference/cli/projects-create-sql",
+                  "reference/cli/projects-create-nosql"
+                ]
+              },
+              {
+                "group": "Layout",
+                "pages": [
+                  "reference/cli/layout-pull",
+                  "reference/cli/layout-apply",
+                  "reference/cli/layout-patch"
+                ]
+              },
+              {
+                "group": "Workflows",
+                "pages": ["reference/cli/workflow-apply"]
+              },
+              {
+                "group": "Environments",
+                "pages": [
+                  "reference/cli/environments-create",
+                  "reference/cli/environments-get",
+                  "reference/cli/environments-update",
+                  "reference/cli/environments-delete",
+                  "reference/cli/environments-reset"
+                ]
+              },
+              {
+                "group": "Roles",
+                "pages": [
+                  "reference/cli/roles-create",
+                  "reference/cli/roles-apply",
+                  "reference/cli/roles-copy",
+                  "reference/cli/roles-export"
+                ]
+              },
+              {
+                "group": "Teams",
+                "pages": [
+                  "reference/cli/teams-create",
+                  "reference/cli/teams-delete",
+                  "reference/cli/teams-copy-layout"
+                ]
+              },
+              {
+                "group": "Users",
+                "pages": [
+                  "reference/cli/users-list",
+                  "reference/cli/users-invite",
+                  "reference/cli/users-edit"
+                ]
+              }
             ]
           },
           {

reference/cli/environments-create.mdx

@@ -0,0 +1,26 @@
+---
+title: forest environments:create
+description: "Create a new environment"
+---
+
+# forest environments:create
+
+Create a new environment.
+
+## Usage
+
+```bash
+forest environments:create [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-f, --format=<option>` | [default: table] Ouput format. <options: table\|json> |
+| `-n, --name=<value>` | (required) Environment name. |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-t, --type=<option>` | Environment type (defaults to "remote" when omitted). Use "production" to create the first production environment. Development environments are created with "forest init". <options: production\|remote> |
+| `-u, --url=<value>` | Application URL. Required, except with --type production where it may be omitted. |
+| `--disableRoles` | Disable roles on new environment. |
+

reference/cli/environments-delete.mdx

@@ -0,0 +1,27 @@
+---
+title: forest environments:delete
+description: "Delete an environment"
+---
+
+# forest environments:delete
+
+Delete an environment.
+
+## Usage
+
+```bash
+forest environments:delete [ENVIRONMENTID] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `ENVIRONMENTID` | ID of an environment. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-f, --force` | Force delete. |
+

reference/cli/environments-get.mdx

@@ -0,0 +1,27 @@
+---
+title: forest environments:get
+description: "Get the configuration of an environment"
+---
+
+# forest environments:get
+
+Get the configuration of an environment.
+
+## Usage
+
+```bash
+forest environments:get [ENVIRONMENTID] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `ENVIRONMENTID` | ID of an environment. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
+

reference/cli/environments-reset.mdx

@@ -0,0 +1,23 @@
+---
+title: forest environments:reset
+description: "Reset a remote environment by removing all layout changes"
+---
+
+# forest environments:reset
+
+Reset a remote environment by removing all layout changes.
+
+## Usage
+
+```bash
+forest environments:reset [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --environment=<value>` | The remote environment name to reset. |
+| `-p, --projectId=<value>` | The id of the project to work on. |
+| `--force` | Skip reset changes confirmation. |
+