From fad27c4ee8c7d2f92a0026d1d2112c7bf1ee8fbb Mon Sep 17 00:00:00 2001
From: Gautier Delache <gautierd@forestadmin.com>
Date: Fri, 17 Jul 2026 13:44:29 +0200
Subject: [PATCH 1/4] docs(cli): document the headless commands
 (projects/layout/workflow/roles/users/teams/environments)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The CLI reference only covered branch/deploy/init/login/push/switch. Add reference
pages for the commands shipped in forest-cli 5.19.0:

- projects:create:demo/sql/nosql
- layout:pull/diff/apply/patch
- workflow:apply
- environments:create/get/update/delete/reset
- roles:create/apply/copy/export · users:list/invite/edit · teams:create/delete/copy-layout

Pages generated from `forest <cmd> --help` (usage + arguments + options). Overview
and docs.json nav updated (sub-groups: Branches & deployment, Projects, Layout,
Workflows, Environments, Roles, Teams, Users).

Follow-up: enrich with worked examples / prose like branch.mdx.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs.json                               | 69 +++++++++++++++++++++++--
 reference/cli/environments-create.mdx   | 26 ++++++++++
 reference/cli/environments-delete.mdx   | 27 ++++++++++
 reference/cli/environments-get.mdx      | 27 ++++++++++
 reference/cli/environments-reset.mdx    | 23 +++++++++
 reference/cli/environments-update.mdx   | 23 +++++++++
 reference/cli/layout-apply.mdx          | 31 +++++++++++
 reference/cli/layout-diff.mdx           | 15 ++++++
 reference/cli/layout-patch.mdx          | 31 +++++++++++
 reference/cli/layout-pull.mdx           | 25 +++++++++
 reference/cli/overview.mdx              | 52 +++++++++++++++++--
 reference/cli/projects-create-demo.mdx  | 29 +++++++++++
 reference/cli/projects-create-nosql.mdx | 38 ++++++++++++++
 reference/cli/projects-create-sql.mdx   | 39 ++++++++++++++
 reference/cli/roles-apply.mdx           | 29 +++++++++++
 reference/cli/roles-copy.mdx            | 23 +++++++++
 reference/cli/roles-create.mdx          | 22 ++++++++
 reference/cli/roles-export.mdx          | 23 +++++++++
 reference/cli/teams-copy-layout.mdx     | 24 +++++++++
 reference/cli/teams-create.mdx          | 22 ++++++++
 reference/cli/teams-delete.mdx          | 23 +++++++++
 reference/cli/users-edit.mdx            | 26 ++++++++++
 reference/cli/users-invite.mdx          | 26 ++++++++++
 reference/cli/users-list.mdx            | 22 ++++++++
 reference/cli/workflow-apply.mdx        | 31 +++++++++++
 25 files changed, 718 insertions(+), 8 deletions(-)
 create mode 100644 reference/cli/environments-create.mdx
 create mode 100644 reference/cli/environments-delete.mdx
 create mode 100644 reference/cli/environments-get.mdx
 create mode 100644 reference/cli/environments-reset.mdx
 create mode 100644 reference/cli/environments-update.mdx
 create mode 100644 reference/cli/layout-apply.mdx
 create mode 100644 reference/cli/layout-diff.mdx
 create mode 100644 reference/cli/layout-patch.mdx
 create mode 100644 reference/cli/layout-pull.mdx
 create mode 100644 reference/cli/projects-create-demo.mdx
 create mode 100644 reference/cli/projects-create-nosql.mdx
 create mode 100644 reference/cli/projects-create-sql.mdx
 create mode 100644 reference/cli/roles-apply.mdx
 create mode 100644 reference/cli/roles-copy.mdx
 create mode 100644 reference/cli/roles-create.mdx
 create mode 100644 reference/cli/roles-export.mdx
 create mode 100644 reference/cli/teams-copy-layout.mdx
 create mode 100644 reference/cli/teams-create.mdx
 create mode 100644 reference/cli/teams-delete.mdx
 create mode 100644 reference/cli/users-edit.mdx
 create mode 100644 reference/cli/users-invite.mdx
 create mode 100644 reference/cli/users-list.mdx
 create mode 100644 reference/cli/workflow-apply.mdx

diff --git a/docs.json b/docs.json
index 29b1f58..5fe0f52 100644
--- a/docs.json
+++ b/docs.json
@@ -343,10 +343,71 @@
               "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-diff",
+                  "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"
+                ]
+              }
             ]
           },
           {
diff --git a/reference/cli/environments-create.mdx b/reference/cli/environments-create.mdx
new file mode 100644
index 0000000..6a3290a
--- /dev/null
+++ b/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. |
+
diff --git a/reference/cli/environments-delete.mdx b/reference/cli/environments-delete.mdx
new file mode 100644
index 0000000..57f6198
--- /dev/null
+++ b/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. |
+
diff --git a/reference/cli/environments-get.mdx b/reference/cli/environments-get.mdx
new file mode 100644
index 0000000..8efa272
--- /dev/null
+++ b/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> |
+
diff --git a/reference/cli/environments-reset.mdx b/reference/cli/environments-reset.mdx
new file mode 100644
index 0000000..b7f8db5
--- /dev/null
+++ b/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. |
+
diff --git a/reference/cli/environments-update.mdx b/reference/cli/environments-update.mdx
new file mode 100644
index 0000000..c469c53
--- /dev/null
+++ b/reference/cli/environments-update.mdx
@@ -0,0 +1,23 @@
+---
+title: forest environments:update
+description: "Update an environment"
+---
+
+# forest environments:update
+
+Update an environment.
+
+## Usage
+
+```bash
+forest environments:update [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --environmentId=<value>` | (required) The forest environment ID to update. |
+| `-n, --name=<value>` | To update the environment name. |
+| `-u, --url=<value>` | To update the application URL. |
+
diff --git a/reference/cli/layout-apply.mdx b/reference/cli/layout-apply.mdx
new file mode 100644
index 0000000..50cceec
--- /dev/null
+++ b/reference/cli/layout-apply.mdx
@@ -0,0 +1,31 @@
+---
+title: forest layout:apply
+description: "Apply a forest-layout.json to an environment (pushes JSON-Patch changes)"
+---
+
+# forest layout:apply
+
+Apply a forest-layout.json to an environment (pushes JSON-Patch changes).
+
+## Usage
+
+```bash
+forest layout:apply [FILE] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `FILE` | Layout file to apply (e.g. forest-layout.json). |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | Environment to apply to (name or id). Prompted if omitted. |
+| `-f, --force` | Skip the confirmation prompt. |
+| `-p, --projectId=<value>` | Id of the project (resolved/prompted when omitted). |
+| `-t, --team=<value>` | Team to apply to (name or id). Prompted if omitted. |
+| `--with-workflows` | Also upload workflow BPMN sidecars (workflows/<id>.bpmn) to the target env — the round-trip counterpart of `pull --with-workflows`. |
+
diff --git a/reference/cli/layout-diff.mdx b/reference/cli/layout-diff.mdx
new file mode 100644
index 0000000..fa799ba
--- /dev/null
+++ b/reference/cli/layout-diff.mdx
@@ -0,0 +1,15 @@
+---
+title: forest layout:diff
+description: "› Error: Command layout:diff not found"
+---
+
+# forest layout:diff
+
+› Error: Command layout:diff not found.
+
+## Usage
+
+```bash
+forest layout:diff
+```
+
diff --git a/reference/cli/layout-patch.mdx b/reference/cli/layout-patch.mdx
new file mode 100644
index 0000000..a3ddbcd
--- /dev/null
+++ b/reference/cli/layout-patch.mdx
@@ -0,0 +1,31 @@
+---
+title: forest layout:patch
+description: "Patch the layout directly (single PATCH per domain, like the front — no pull/apply)"
+---
+
+# forest layout:patch
+
+Patch the layout directly (single PATCH per domain, like the front — no pull/apply).
+
+## Usage
+
+```bash
+forest layout:patch [FILE] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `FILE` | JSON patch file to apply. Use "-" or omit to read from stdin. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | Environment name or id. |
+| `-f, --force` | Skip the confirmation prompt (required when reading from stdin). |
+| `-p, --projectId=<value>` | Project id. |
+| `-t, --team=<value>` | Team name or id. |
+| `--dry-run` | Print operations without sending them. |
+
diff --git a/reference/cli/layout-pull.mdx b/reference/cli/layout-pull.mdx
new file mode 100644
index 0000000..8b3c05e
--- /dev/null
+++ b/reference/cli/layout-pull.mdx
@@ -0,0 +1,25 @@
+---
+title: forest layout:pull
+description: "Pull the layout (rendering) of an environment into a forest-layout.json file"
+---
+
+# forest layout:pull
+
+Pull the layout (rendering) of an environment into a forest-layout.json file.
+
+## Usage
+
+```bash
+forest layout:pull [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | Environment to pull from (name or id). Defaults to the environment of FOREST_ENV_SECRET when set, otherwise the development environment. |
+| `-o, --out=<value>` | [default: forest-layout.json] Output file path (default: forest-layout.json). |
+| `-p, --projectId=<value>` | Id of the project (resolved automatically when you only have one). |
+| `-t, --team=<value>` | Team whose layout to pull (name or id). Defaults to the "Operations" team. |
+| `--with-workflows` | Also download each workflow's BPMN into sidecar files (workflows/<id>.bpmn) for round-trip. |
+
diff --git a/reference/cli/overview.mdx b/reference/cli/overview.mdx
index 4361758..1516bfc 100644
--- a/reference/cli/overview.mdx
+++ b/reference/cli/overview.mdx
@@ -67,10 +67,11 @@ forest init
 | Command | Description |
 |---|---|
 | `forest environments` | List all environments |
-| `forest environments:create` | Create a new environment |
-| `forest environments:delete` | Delete an environment |
-| `forest environments:update` | Update an environment |
-| `forest environments:reset` | Reset all layout changes on a remote environment |
+| [`forest environments:create`](/reference/cli/environments-create) | Create a new environment |
+| [`forest environments:get`](/reference/cli/environments-get) | Get an environment's configuration |
+| [`forest environments:update`](/reference/cli/environments-update) | Update an environment |
+| [`forest environments:delete`](/reference/cli/environments-delete) | Delete an environment |
+| [`forest environments:reset`](/reference/cli/environments-reset) | Reset all layout changes on a remote environment |
 
 ### Project management
 
@@ -78,6 +79,49 @@ forest init
 |---|---|
 | `forest projects` | List all projects |
 | `forest projects:get` | Get a project's configuration |
+| [`forest projects:create:demo`](/reference/cli/projects-create-demo) | Create a project with a zero-DB demo datasource |
+| [`forest projects:create:sql`](/reference/cli/projects-create-sql) | Create a project from a SQL database |
+| [`forest projects:create:nosql`](/reference/cli/projects-create-nosql) | Create a project from a NoSQL (Mongo) database |
+
+### Layout
+
+| Command | Description |
+|---|---|
+| [`forest layout:pull`](/reference/cli/layout-pull) | Pull an environment's layout into a `forest-layout.json` file |
+| [`forest layout:diff`](/reference/cli/layout-diff) | Show the changes `layout:apply` would push |
+| [`forest layout:apply`](/reference/cli/layout-apply) | Apply a `forest-layout.json` to an environment |
+| [`forest layout:patch`](/reference/cli/layout-patch) | Patch the layout directly (single PATCH per domain, like the front) |
+
+### Workflows
+
+| Command | Description |
+|---|---|
+| [`forest workflow:apply`](/reference/cli/workflow-apply) | Create or update a workflow from a JSON `steps` spec (compiles to BPMN) |
+
+### Roles
+
+| Command | Description |
+|---|---|
+| [`forest roles:create`](/reference/cli/roles-create) | Create a role |
+| [`forest roles:apply`](/reference/cli/roles-apply) | Apply a wide-format CSV of role permissions to an environment |
+| [`forest roles:copy`](/reference/cli/roles-copy) | Copy roles between environments |
+| [`forest roles:export`](/reference/cli/roles-export) | Export an environment's roles to a CSV |
+
+### Teams
+
+| Command | Description |
+|---|---|
+| [`forest teams:create`](/reference/cli/teams-create) | Create a team |
+| [`forest teams:delete`](/reference/cli/teams-delete) | Delete a team |
+| [`forest teams:copy-layout`](/reference/cli/teams-copy-layout) | Copy a team's layout to another team |
+
+### Users
+
+| Command | Description |
+|---|---|
+| [`forest users:list`](/reference/cli/users-list) | List the users of a project |
+| [`forest users:invite`](/reference/cli/users-invite) | Invite users to a project |
+| [`forest users:edit`](/reference/cli/users-edit) | Edit a user's role, teams, or permission level |
 
 ### Schema
 
diff --git a/reference/cli/projects-create-demo.mdx b/reference/cli/projects-create-demo.mdx
new file mode 100644
index 0000000..793fe6f
--- /dev/null
+++ b/reference/cli/projects-create-demo.mdx
@@ -0,0 +1,29 @@
+---
+title: forest projects:create:demo
+description: "Create a new Forest Admin project with demo data — no database required"
+---
+
+# forest projects:create:demo
+
+Create a new Forest Admin project with demo data — no database required.
+
+## Usage
+
+```bash
+forest projects:create:demo [APPLICATIONNAME] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `APPLICATIONNAME` | Name of the project to create. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
+| `-P, --applicationPort=<value>` | Port of your admin backend application. |
+| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
+
diff --git a/reference/cli/projects-create-nosql.mdx b/reference/cli/projects-create-nosql.mdx
new file mode 100644
index 0000000..5c2f723
--- /dev/null
+++ b/reference/cli/projects-create-nosql.mdx
@@ -0,0 +1,38 @@
+---
+title: forest projects:create:nosql
+description: "Create a new Forest Admin project"
+---
+
+# forest projects:create:nosql
+
+Create a new Forest Admin project.
+
+## Usage
+
+```bash
+forest projects:create:nosql [APPLICATIONNAME] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `APPLICATIONNAME` | Name of the project to create. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
+| `-P, --applicationPort=<value>` | Port of your admin backend application. |
+| `-c, --databaseConnectionURL=<value>` | Enter the database credentials with a connection URL. |
+| `-h, --databaseHost=<value>` | Enter your database host. |
+| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
+| `-n, --databaseName=<value>` | Enter your database name. |
+| `-p, --databasePort=<value>` | Enter your database port. |
+| `-u, --databaseUser=<value>` | Enter your database user. |
+| `--databasePassword=<value>` | Enter your database password. |
+| `--databaseSSL` | Use SSL for database connection. |
+| `--databaseSslMode=<option>` | SSL mode. <options: preferred\|verify\|required\|disabled> |
+| `--mongoDBSRV` | Use SRV DNS record for mongoDB connection. |
+
diff --git a/reference/cli/projects-create-sql.mdx b/reference/cli/projects-create-sql.mdx
new file mode 100644
index 0000000..4728c50
--- /dev/null
+++ b/reference/cli/projects-create-sql.mdx
@@ -0,0 +1,39 @@
+---
+title: forest projects:create:sql
+description: "Create a new Forest Admin project"
+---
+
+# forest projects:create:sql
+
+Create a new Forest Admin project.
+
+## Usage
+
+```bash
+forest projects:create:sql [APPLICATIONNAME] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `APPLICATIONNAME` | Name of the project to create. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
+| `-P, --applicationPort=<value>` | Port of your admin backend application. |
+| `-c, --databaseConnectionURL=<value>` | Enter the database credentials with a connection URL. |
+| `-d, --databaseDialect=<option>` | Enter your database dialect. <options: mssql\|mysql / mariadb\|postgres> |
+| `-h, --databaseHost=<value>` | Enter your database host. |
+| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
+| `-n, --databaseName=<value>` | Enter your database name. |
+| `-p, --databasePort=<value>` | Enter your database port. |
+| `-s, --databaseSchema=<value>` | Enter your database schema. |
+| `-u, --databaseUser=<value>` | Enter your database user. |
+| `--databasePassword=<value>` | Enter your database password. |
+| `--databaseSSL` | Use SSL for database connection. |
+| `--databaseSslMode=<option>` | SSL mode. <options: preferred\|verify\|required\|disabled> |
+
diff --git a/reference/cli/roles-apply.mdx b/reference/cli/roles-apply.mdx
new file mode 100644
index 0000000..ffc7160
--- /dev/null
+++ b/reference/cli/roles-apply.mdx
@@ -0,0 +1,29 @@
+---
+title: forest roles:apply
+description: "Apply a wide-format CSV to update role permissions in an environment"
+---
+
+# forest roles:apply
+
+Apply a wide-format CSV to update role permissions in an environment.
+
+## Usage
+
+```bash
+forest roles:apply [FILE] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `FILE` | Path to the wide-format CSV file. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-F, --force` | Skip confirmation prompt. |
+| `-e, --env=<value>` | (required) Environment name to apply to. |
+| `-p, --projectId=<value>` | Forest project ID. |
+
diff --git a/reference/cli/roles-copy.mdx b/reference/cli/roles-copy.mdx
new file mode 100644
index 0000000..5e2d8ae
--- /dev/null
+++ b/reference/cli/roles-copy.mdx
@@ -0,0 +1,23 @@
+---
+title: forest roles:copy
+description: "Copy role permissions from one environment to another"
+---
+
+# forest roles:copy
+
+Copy role permissions from one environment to another.
+
+## Usage
+
+```bash
+forest roles:copy [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-f, --from=<value>` | (required) Source environment name. |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-t, --to=<value>` | (required) Destination environment name. |
+
diff --git a/reference/cli/roles-create.mdx b/reference/cli/roles-create.mdx
new file mode 100644
index 0000000..acbf703
--- /dev/null
+++ b/reference/cli/roles-create.mdx
@@ -0,0 +1,22 @@
+---
+title: forest roles:create
+description: "Create a new role in a project"
+---
+
+# forest roles:create
+
+Create a new role in a project.
+
+## Usage
+
+```bash
+forest roles:create [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-n, --name=<value>` | (required) Name of the role to create. |
+| `-p, --projectId=<value>` | Forest project ID. |
+
diff --git a/reference/cli/roles-export.mdx b/reference/cli/roles-export.mdx
new file mode 100644
index 0000000..ebafda4
--- /dev/null
+++ b/reference/cli/roles-export.mdx
@@ -0,0 +1,23 @@
+---
+title: forest roles:export
+description: "Export all roles and their permissions to a wide CSV file"
+---
+
+# forest roles:export
+
+Export all roles and their permissions to a wide CSV file.
+
+## Usage
+
+```bash
+forest roles:export [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | (required) Environment name to export permissions for. |
+| `-o, --output=<value>` | Output file path (default: stdout). |
+| `-p, --projectId=<value>` | Forest project ID. |
+
diff --git a/reference/cli/teams-copy-layout.mdx b/reference/cli/teams-copy-layout.mdx
new file mode 100644
index 0000000..94659e0
--- /dev/null
+++ b/reference/cli/teams-copy-layout.mdx
@@ -0,0 +1,24 @@
+---
+title: forest teams:copy-layout
+description: "Copy a team's whole layout onto another team of the same project"
+---
+
+# forest teams:copy-layout
+
+Copy a team's whole layout onto another team of the same project.
+
+## Usage
+
+```bash
+forest teams:copy-layout [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-f, --from=<value>` | (required) Name of the team to copy the layout from. |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-t, --to=<value>` | (required) Name of the team to copy the layout to (its layout is overwritten). |
+| `--force` | Skip the confirmation prompt. |
+
diff --git a/reference/cli/teams-create.mdx b/reference/cli/teams-create.mdx
new file mode 100644
index 0000000..65f4382
--- /dev/null
+++ b/reference/cli/teams-create.mdx
@@ -0,0 +1,22 @@
+---
+title: forest teams:create
+description: "Create a new team in a project"
+---
+
+# forest teams:create
+
+Create a new team in a project.
+
+## Usage
+
+```bash
+forest teams:create [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-n, --name=<value>` | (required) Name of the team to create. |
+| `-p, --projectId=<value>` | Forest project ID. |
+
diff --git a/reference/cli/teams-delete.mdx b/reference/cli/teams-delete.mdx
new file mode 100644
index 0000000..023fad2
--- /dev/null
+++ b/reference/cli/teams-delete.mdx
@@ -0,0 +1,23 @@
+---
+title: forest teams:delete
+description: "Delete a team from a project"
+---
+
+# forest teams:delete
+
+Delete a team from a project.
+
+## Usage
+
+```bash
+forest teams:delete [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-n, --name=<value>` | (required) Name of the team to delete. |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `--force` | Skip the confirmation prompt. |
+
diff --git a/reference/cli/users-edit.mdx b/reference/cli/users-edit.mdx
new file mode 100644
index 0000000..1b5562d
--- /dev/null
+++ b/reference/cli/users-edit.mdx
@@ -0,0 +1,26 @@
+---
+title: forest users:edit
+description: "Edit a user's role, team(s) or permission level"
+---
+
+# forest users:edit
+
+Edit a user's role, team(s) or permission level.
+
+## Usage
+
+```bash
+forest users:edit [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --email=<value>` | (required) Email of the user to edit. |
+| `-f, --force` | Skip the confirmation prompt when teams would be removed. |
+| `-l, --permission-level=<option>` | New permission level. <options: admin\|editor\|user\|developer\|manager> |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-r, --role=<value>` | New role name to assign. |
+| `-t, --team=<value>...` | Team name to set for this project. Repeatable; this REPLACES the user’s current team set on the project. |
+
diff --git a/reference/cli/users-invite.mdx b/reference/cli/users-invite.mdx
new file mode 100644
index 0000000..31ca8e9
--- /dev/null
+++ b/reference/cli/users-invite.mdx
@@ -0,0 +1,26 @@
+---
+title: forest users:invite
+description: "Invite users to a project"
+---
+
+# forest users:invite
+
+Invite users to a project.
+
+## Usage
+
+```bash
+forest users:invite [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --email=<value>...` | (required) Email of the user to invite (repeat the flag to invite several users). |
+| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
+| `-l, --permission-level=<option>` | (required) Permission level of the invited users. <options: admin\|editor\|user\|developer\|manager> |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-r, --role=<value>` | Role name to assign (prompted if omitted and several exist). |
+| `-t, --team=<value>` | Team name to add the invited users to (prompted if omitted and several exist). |
+
diff --git a/reference/cli/users-list.mdx b/reference/cli/users-list.mdx
new file mode 100644
index 0000000..fc40610
--- /dev/null
+++ b/reference/cli/users-list.mdx
@@ -0,0 +1,22 @@
+---
+title: forest users:list
+description: "List all users of a project"
+---
+
+# forest users:list
+
+List all users of a project.
+
+## Usage
+
+```bash
+forest users:list [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
+| `-p, --projectId=<value>` | Forest project ID. |
+
diff --git a/reference/cli/workflow-apply.mdx b/reference/cli/workflow-apply.mdx
new file mode 100644
index 0000000..b4999d0
--- /dev/null
+++ b/reference/cli/workflow-apply.mdx
@@ -0,0 +1,31 @@
+---
+title: forest workflow:apply
+description: "Create or update a workflow from a JSON steps spec (compiles to BPMN and uploads it)"
+---
+
+# forest workflow:apply
+
+Create or update a workflow from a JSON steps spec (compiles to BPMN and uploads it). Reading the spec from stdin disables prompts: pass -p/-e/-t and --force explicitly.
+
+## Usage
+
+```bash
+forest workflow:apply [FILE] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `FILE` | JSON workflow spec ({ name, collection, steps, id?, segments?, position?, start?, version? }). "-" or omit to read stdin. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | Environment name or id. |
+| `-f, --force` | Skip the confirmation prompt (required when the spec is read from stdin). |
+| `-p, --projectId=<value>` | Project id. |
+| `-t, --team=<value>` | Team name or id. |
+| `--dry-run` | Resolve the scope, match the workflow and print the plan; send nothing. |
+

From 27a8b14dd28b7f924f2f92224fcdd9bb118cdbd3 Mon Sep 17 00:00:00 2001
From: Gautier Delache <gautierd@forestadmin.com>
Date: Fri, 17 Jul 2026 14:04:22 +0200
Subject: [PATCH 2/4] docs(cli): one page per category (not per command); drop
 non-existent layout:diff
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replaces the 23 per-command pages with 7 category pages (projects, layout,
workflows, environments, roles, teams, users) and a flat CLI nav — fixes the
broken links from the over-nested sidebar and removes layout:diff (not shipped).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs.json                                     | 76 +++-------------
 reference/cli/environments-create.mdx         | 26 ------
 reference/cli/environments-delete.mdx         | 27 ------
 reference/cli/environments-get.mdx            | 27 ------
 reference/cli/environments-reset.mdx          | 23 -----
 reference/cli/environments-update.mdx         | 23 -----
 reference/cli/environments.mdx                | 86 +++++++++++++++++++
 reference/cli/layout-apply.mdx                | 31 -------
 reference/cli/layout-diff.mdx                 | 15 ----
 reference/cli/layout-patch.mdx                | 31 -------
 reference/cli/layout-pull.mdx                 | 25 ------
 reference/cli/layout.mdx                      | 65 ++++++++++++++
 reference/cli/overview.mdx                    | 59 +++++++------
 reference/cli/projects-create-demo.mdx        | 29 -------
 reference/cli/projects-create-nosql.mdx       | 38 --------
 reference/cli/projects-create-sql.mdx         | 39 ---------
 reference/cli/projects.mdx                    | 82 ++++++++++++++++++
 reference/cli/roles-apply.mdx                 | 29 -------
 reference/cli/roles-copy.mdx                  | 23 -----
 reference/cli/roles-create.mdx                | 22 -----
 reference/cli/roles-export.mdx                | 23 -----
 reference/cli/roles.mdx                       | 68 +++++++++++++++
 reference/cli/teams-copy-layout.mdx           | 24 ------
 reference/cli/teams-create.mdx                | 22 -----
 reference/cli/teams-delete.mdx                | 23 -----
 reference/cli/teams.mdx                       | 51 +++++++++++
 reference/cli/users-edit.mdx                  | 26 ------
 reference/cli/users-invite.mdx                | 26 ------
 reference/cli/users-list.mdx                  | 22 -----
 reference/cli/users.mdx                       | 56 ++++++++++++
 .../cli/{workflow-apply.mdx => workflows.mdx} | 16 ++--
 31 files changed, 455 insertions(+), 678 deletions(-)
 delete mode 100644 reference/cli/environments-create.mdx
 delete mode 100644 reference/cli/environments-delete.mdx
 delete mode 100644 reference/cli/environments-get.mdx
 delete mode 100644 reference/cli/environments-reset.mdx
 delete mode 100644 reference/cli/environments-update.mdx
 create mode 100644 reference/cli/environments.mdx
 delete mode 100644 reference/cli/layout-apply.mdx
 delete mode 100644 reference/cli/layout-diff.mdx
 delete mode 100644 reference/cli/layout-patch.mdx
 delete mode 100644 reference/cli/layout-pull.mdx
 create mode 100644 reference/cli/layout.mdx
 delete mode 100644 reference/cli/projects-create-demo.mdx
 delete mode 100644 reference/cli/projects-create-nosql.mdx
 delete mode 100644 reference/cli/projects-create-sql.mdx
 create mode 100644 reference/cli/projects.mdx
 delete mode 100644 reference/cli/roles-apply.mdx
 delete mode 100644 reference/cli/roles-copy.mdx
 delete mode 100644 reference/cli/roles-create.mdx
 delete mode 100644 reference/cli/roles-export.mdx
 create mode 100644 reference/cli/roles.mdx
 delete mode 100644 reference/cli/teams-copy-layout.mdx
 delete mode 100644 reference/cli/teams-create.mdx
 delete mode 100644 reference/cli/teams-delete.mdx
 create mode 100644 reference/cli/teams.mdx
 delete mode 100644 reference/cli/users-edit.mdx
 delete mode 100644 reference/cli/users-invite.mdx
 delete mode 100644 reference/cli/users-list.mdx
 create mode 100644 reference/cli/users.mdx
 rename reference/cli/{workflow-apply.mdx => workflows.mdx} (80%)

diff --git a/docs.json b/docs.json
index 5fe0f52..f2b05f3 100644
--- a/docs.json
+++ b/docs.json
@@ -343,71 +343,17 @@
               "reference/cli/overview",
               "reference/cli/init",
               "reference/cli/login",
-              {
-                "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-diff",
-                  "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/branch",
+              "reference/cli/switch",
+              "reference/cli/push",
+              "reference/cli/deploy",
+              "reference/cli/projects",
+              "reference/cli/layout",
+              "reference/cli/workflows",
+              "reference/cli/environments",
+              "reference/cli/roles",
+              "reference/cli/teams",
+              "reference/cli/users"
             ]
           },
           {
diff --git a/reference/cli/environments-create.mdx b/reference/cli/environments-create.mdx
deleted file mode 100644
index 6a3290a..0000000
--- a/reference/cli/environments-create.mdx
+++ /dev/null
@@ -1,26 +0,0 @@
----
-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. |
-
diff --git a/reference/cli/environments-delete.mdx b/reference/cli/environments-delete.mdx
deleted file mode 100644
index 57f6198..0000000
--- a/reference/cli/environments-delete.mdx
+++ /dev/null
@@ -1,27 +0,0 @@
----
-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. |
-
diff --git a/reference/cli/environments-get.mdx b/reference/cli/environments-get.mdx
deleted file mode 100644
index 8efa272..0000000
--- a/reference/cli/environments-get.mdx
+++ /dev/null
@@ -1,27 +0,0 @@
----
-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> |
-
diff --git a/reference/cli/environments-reset.mdx b/reference/cli/environments-reset.mdx
deleted file mode 100644
index b7f8db5..0000000
--- a/reference/cli/environments-reset.mdx
+++ /dev/null
@@ -1,23 +0,0 @@
----
-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. |
-
diff --git a/reference/cli/environments-update.mdx b/reference/cli/environments-update.mdx
deleted file mode 100644
index c469c53..0000000
--- a/reference/cli/environments-update.mdx
+++ /dev/null
@@ -1,23 +0,0 @@
----
-title: forest environments:update
-description: "Update an environment"
----
-
-# forest environments:update
-
-Update an environment.
-
-## Usage
-
-```bash
-forest environments:update [options]
-```
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-e, --environmentId=<value>` | (required) The forest environment ID to update. |
-| `-n, --name=<value>` | To update the environment name. |
-| `-u, --url=<value>` | To update the application URL. |
-
diff --git a/reference/cli/environments.mdx b/reference/cli/environments.mdx
new file mode 100644
index 0000000..05947f7
--- /dev/null
+++ b/reference/cli/environments.mdx
@@ -0,0 +1,86 @@
+---
+title: Environments
+description: "Create and manage your project environments."
+---
+
+# Environments
+
+Create and manage your project environments.
+
+## forest environments:create
+
+Create a new environment.
+
+```bash
+forest environments:create [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. |
+
+## forest environments:get
+
+Get the configuration of an environment.
+
+```bash
+forest environments:get [ENVIRONMENTID] [options]
+```
+
+| Argument | Description |
+|---|---|
+| `ENVIRONMENTID` | ID of an environment. |
+
+| Option | Description |
+|---|---|
+| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
+
+## forest environments:update
+
+Update an environment.
+
+```bash
+forest environments:update [options]
+```
+
+| Option | Description |
+|---|---|
+| `-e, --environmentId=<value>` | (required) The forest environment ID to update. |
+| `-n, --name=<value>` | To update the environment name. |
+| `-u, --url=<value>` | To update the application URL. |
+
+## forest environments:delete
+
+Delete an environment.
+
+```bash
+forest environments:delete [ENVIRONMENTID] [options]
+```
+
+| Argument | Description |
+|---|---|
+| `ENVIRONMENTID` | ID of an environment. |
+
+| Option | Description |
+|---|---|
+| `-f, --force` | Force delete. |
+
+## forest environments:reset
+
+Reset a remote environment by removing all layout changes.
+
+```bash
+forest environments:reset [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. |
+
diff --git a/reference/cli/layout-apply.mdx b/reference/cli/layout-apply.mdx
deleted file mode 100644
index 50cceec..0000000
--- a/reference/cli/layout-apply.mdx
+++ /dev/null
@@ -1,31 +0,0 @@
----
-title: forest layout:apply
-description: "Apply a forest-layout.json to an environment (pushes JSON-Patch changes)"
----
-
-# forest layout:apply
-
-Apply a forest-layout.json to an environment (pushes JSON-Patch changes).
-
-## Usage
-
-```bash
-forest layout:apply [FILE] [options]
-```
-
-## Arguments
-
-| Argument | Description |
-|---|---|
-| `FILE` | Layout file to apply (e.g. forest-layout.json). |
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-e, --env=<value>` | Environment to apply to (name or id). Prompted if omitted. |
-| `-f, --force` | Skip the confirmation prompt. |
-| `-p, --projectId=<value>` | Id of the project (resolved/prompted when omitted). |
-| `-t, --team=<value>` | Team to apply to (name or id). Prompted if omitted. |
-| `--with-workflows` | Also upload workflow BPMN sidecars (workflows/<id>.bpmn) to the target env — the round-trip counterpart of `pull --with-workflows`. |
-
diff --git a/reference/cli/layout-diff.mdx b/reference/cli/layout-diff.mdx
deleted file mode 100644
index fa799ba..0000000
--- a/reference/cli/layout-diff.mdx
+++ /dev/null
@@ -1,15 +0,0 @@
----
-title: forest layout:diff
-description: "› Error: Command layout:diff not found"
----
-
-# forest layout:diff
-
-› Error: Command layout:diff not found.
-
-## Usage
-
-```bash
-forest layout:diff
-```
-
diff --git a/reference/cli/layout-patch.mdx b/reference/cli/layout-patch.mdx
deleted file mode 100644
index a3ddbcd..0000000
--- a/reference/cli/layout-patch.mdx
+++ /dev/null
@@ -1,31 +0,0 @@
----
-title: forest layout:patch
-description: "Patch the layout directly (single PATCH per domain, like the front — no pull/apply)"
----
-
-# forest layout:patch
-
-Patch the layout directly (single PATCH per domain, like the front — no pull/apply).
-
-## Usage
-
-```bash
-forest layout:patch [FILE] [options]
-```
-
-## Arguments
-
-| Argument | Description |
-|---|---|
-| `FILE` | JSON patch file to apply. Use "-" or omit to read from stdin. |
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-e, --env=<value>` | Environment name or id. |
-| `-f, --force` | Skip the confirmation prompt (required when reading from stdin). |
-| `-p, --projectId=<value>` | Project id. |
-| `-t, --team=<value>` | Team name or id. |
-| `--dry-run` | Print operations without sending them. |
-
diff --git a/reference/cli/layout-pull.mdx b/reference/cli/layout-pull.mdx
deleted file mode 100644
index 8b3c05e..0000000
--- a/reference/cli/layout-pull.mdx
+++ /dev/null
@@ -1,25 +0,0 @@
----
-title: forest layout:pull
-description: "Pull the layout (rendering) of an environment into a forest-layout.json file"
----
-
-# forest layout:pull
-
-Pull the layout (rendering) of an environment into a forest-layout.json file.
-
-## Usage
-
-```bash
-forest layout:pull [options]
-```
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-e, --env=<value>` | Environment to pull from (name or id). Defaults to the environment of FOREST_ENV_SECRET when set, otherwise the development environment. |
-| `-o, --out=<value>` | [default: forest-layout.json] Output file path (default: forest-layout.json). |
-| `-p, --projectId=<value>` | Id of the project (resolved automatically when you only have one). |
-| `-t, --team=<value>` | Team whose layout to pull (name or id). Defaults to the "Operations" team. |
-| `--with-workflows` | Also download each workflow's BPMN into sidecar files (workflows/<id>.bpmn) for round-trip. |
-
diff --git a/reference/cli/layout.mdx b/reference/cli/layout.mdx
new file mode 100644
index 0000000..f0a9d91
--- /dev/null
+++ b/reference/cli/layout.mdx
@@ -0,0 +1,65 @@
+---
+title: Layout
+description: "Manage your UI layout as code — pull it to a file, apply it, or patch it directly."
+---
+
+# Layout
+
+Manage your UI layout as code — pull it to a file, apply it, or patch it directly.
+
+## forest layout:pull
+
+Pull the layout (rendering) of an environment into a forest-layout.json file.
+
+```bash
+forest layout:pull [options]
+```
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | Environment to pull from (name or id). Defaults to the environment of FOREST_ENV_SECRET when set, otherwise the development environment. |
+| `-o, --out=<value>` | [default: forest-layout.json] Output file path (default: forest-layout.json). |
+| `-p, --projectId=<value>` | Id of the project (resolved automatically when you only have one). |
+| `-t, --team=<value>` | Team whose layout to pull (name or id). Defaults to the "Operations" team. |
+| `--with-workflows` | Also download each workflow's BPMN into sidecar files (workflows/<id>.bpmn) for round-trip. |
+
+## forest layout:apply
+
+Apply a forest-layout.json to an environment (pushes JSON-Patch changes).
+
+```bash
+forest layout:apply [FILE] [options]
+```
+
+| Argument | Description |
+|---|---|
+| `FILE` | Layout file to apply (e.g. forest-layout.json). |
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | Environment to apply to (name or id). Prompted if omitted. |
+| `-f, --force` | Skip the confirmation prompt. |
+| `-p, --projectId=<value>` | Id of the project (resolved/prompted when omitted). |
+| `-t, --team=<value>` | Team to apply to (name or id). Prompted if omitted. |
+| `--with-workflows` | Also upload workflow BPMN sidecars (workflows/<id>.bpmn) to the target env — the round-trip counterpart of `pull --with-workflows`. |
+
+## forest layout:patch
+
+Patch the layout directly (single PATCH per domain, like the front — no pull/apply).
+
+```bash
+forest layout:patch [FILE] [options]
+```
+
+| Argument | Description |
+|---|---|
+| `FILE` | JSON patch file to apply. Use "-" or omit to read from stdin. |
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | Environment name or id. |
+| `-f, --force` | Skip the confirmation prompt (required when reading from stdin). |
+| `-p, --projectId=<value>` | Project id. |
+| `-t, --team=<value>` | Team name or id. |
+| `--dry-run` | Print operations without sending them. |
+
diff --git a/reference/cli/overview.mdx b/reference/cli/overview.mdx
index 1516bfc..aa1d669 100644
--- a/reference/cli/overview.mdx
+++ b/reference/cli/overview.mdx
@@ -62,66 +62,65 @@ forest init
 | [`forest push`](/reference/cli/push) | Push layout changes from your branch to its origin environment |
 | [`forest deploy`](/reference/cli/deploy) | Deploy layout changes to the production (reference) environment |
 
-### Environment management
+### [Environments](/reference/cli/environments)
 
 | Command | Description |
 |---|---|
 | `forest environments` | List all environments |
-| [`forest environments:create`](/reference/cli/environments-create) | Create a new environment |
-| [`forest environments:get`](/reference/cli/environments-get) | Get an environment's configuration |
-| [`forest environments:update`](/reference/cli/environments-update) | Update an environment |
-| [`forest environments:delete`](/reference/cli/environments-delete) | Delete an environment |
-| [`forest environments:reset`](/reference/cli/environments-reset) | Reset all layout changes on a remote environment |
+| `forest environments:create` | Create a new environment |
+| `forest environments:get` | Get an environment's configuration |
+| `forest environments:update` | Update an environment |
+| `forest environments:delete` | Delete an environment |
+| `forest environments:reset` | Reset all layout changes on a remote environment |
 
-### Project management
+### [Projects](/reference/cli/projects)
 
 | Command | Description |
 |---|---|
 | `forest projects` | List all projects |
 | `forest projects:get` | Get a project's configuration |
-| [`forest projects:create:demo`](/reference/cli/projects-create-demo) | Create a project with a zero-DB demo datasource |
-| [`forest projects:create:sql`](/reference/cli/projects-create-sql) | Create a project from a SQL database |
-| [`forest projects:create:nosql`](/reference/cli/projects-create-nosql) | Create a project from a NoSQL (Mongo) database |
+| `forest projects:create:demo` | Create a project with a zero-DB demo datasource |
+| `forest projects:create:sql` | Create a project from a SQL database |
+| `forest projects:create:nosql` | Create a project from a NoSQL (Mongo) database |
 
-### Layout
+### [Layout](/reference/cli/layout)
 
 | Command | Description |
 |---|---|
-| [`forest layout:pull`](/reference/cli/layout-pull) | Pull an environment's layout into a `forest-layout.json` file |
-| [`forest layout:diff`](/reference/cli/layout-diff) | Show the changes `layout:apply` would push |
-| [`forest layout:apply`](/reference/cli/layout-apply) | Apply a `forest-layout.json` to an environment |
-| [`forest layout:patch`](/reference/cli/layout-patch) | Patch the layout directly (single PATCH per domain, like the front) |
+| `forest layout:pull` | Pull an environment's layout into a `forest-layout.json` file |
+| `forest layout:apply` | Apply a `forest-layout.json` to an environment |
+| `forest layout:patch` | Patch the layout directly (single PATCH per domain, like the front) |
 
-### Workflows
+### [Workflows](/reference/cli/workflows)
 
 | Command | Description |
 |---|---|
-| [`forest workflow:apply`](/reference/cli/workflow-apply) | Create or update a workflow from a JSON `steps` spec (compiles to BPMN) |
+| `forest workflow:apply` | Create or update a workflow from a JSON `steps` spec (compiles to BPMN) |
 
-### Roles
+### [Roles](/reference/cli/roles)
 
 | Command | Description |
 |---|---|
-| [`forest roles:create`](/reference/cli/roles-create) | Create a role |
-| [`forest roles:apply`](/reference/cli/roles-apply) | Apply a wide-format CSV of role permissions to an environment |
-| [`forest roles:copy`](/reference/cli/roles-copy) | Copy roles between environments |
-| [`forest roles:export`](/reference/cli/roles-export) | Export an environment's roles to a CSV |
+| `forest roles:create` | Create a role |
+| `forest roles:apply` | Apply a wide-format CSV of role permissions to an environment |
+| `forest roles:copy` | Copy roles between environments |
+| `forest roles:export` | Export an environment's roles to a CSV |
 
-### Teams
+### [Teams](/reference/cli/teams)
 
 | Command | Description |
 |---|---|
-| [`forest teams:create`](/reference/cli/teams-create) | Create a team |
-| [`forest teams:delete`](/reference/cli/teams-delete) | Delete a team |
-| [`forest teams:copy-layout`](/reference/cli/teams-copy-layout) | Copy a team's layout to another team |
+| `forest teams:create` | Create a team |
+| `forest teams:delete` | Delete a team |
+| `forest teams:copy-layout` | Copy a team's layout to another team |
 
-### Users
+### [Users](/reference/cli/users)
 
 | Command | Description |
 |---|---|
-| [`forest users:list`](/reference/cli/users-list) | List the users of a project |
-| [`forest users:invite`](/reference/cli/users-invite) | Invite users to a project |
-| [`forest users:edit`](/reference/cli/users-edit) | Edit a user's role, teams, or permission level |
+| `forest users:list` | List the users of a project |
+| `forest users:invite` | Invite users to a project |
+| `forest users:edit` | Edit a user's role, teams, or permission level |
 
 ### Schema
 
diff --git a/reference/cli/projects-create-demo.mdx b/reference/cli/projects-create-demo.mdx
deleted file mode 100644
index 793fe6f..0000000
--- a/reference/cli/projects-create-demo.mdx
+++ /dev/null
@@ -1,29 +0,0 @@
----
-title: forest projects:create:demo
-description: "Create a new Forest Admin project with demo data — no database required"
----
-
-# forest projects:create:demo
-
-Create a new Forest Admin project with demo data — no database required.
-
-## Usage
-
-```bash
-forest projects:create:demo [APPLICATIONNAME] [options]
-```
-
-## Arguments
-
-| Argument | Description |
-|---|---|
-| `APPLICATIONNAME` | Name of the project to create. |
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
-| `-P, --applicationPort=<value>` | Port of your admin backend application. |
-| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
-
diff --git a/reference/cli/projects-create-nosql.mdx b/reference/cli/projects-create-nosql.mdx
deleted file mode 100644
index 5c2f723..0000000
--- a/reference/cli/projects-create-nosql.mdx
+++ /dev/null
@@ -1,38 +0,0 @@
----
-title: forest projects:create:nosql
-description: "Create a new Forest Admin project"
----
-
-# forest projects:create:nosql
-
-Create a new Forest Admin project.
-
-## Usage
-
-```bash
-forest projects:create:nosql [APPLICATIONNAME] [options]
-```
-
-## Arguments
-
-| Argument | Description |
-|---|---|
-| `APPLICATIONNAME` | Name of the project to create. |
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
-| `-P, --applicationPort=<value>` | Port of your admin backend application. |
-| `-c, --databaseConnectionURL=<value>` | Enter the database credentials with a connection URL. |
-| `-h, --databaseHost=<value>` | Enter your database host. |
-| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
-| `-n, --databaseName=<value>` | Enter your database name. |
-| `-p, --databasePort=<value>` | Enter your database port. |
-| `-u, --databaseUser=<value>` | Enter your database user. |
-| `--databasePassword=<value>` | Enter your database password. |
-| `--databaseSSL` | Use SSL for database connection. |
-| `--databaseSslMode=<option>` | SSL mode. <options: preferred\|verify\|required\|disabled> |
-| `--mongoDBSRV` | Use SRV DNS record for mongoDB connection. |
-
diff --git a/reference/cli/projects-create-sql.mdx b/reference/cli/projects-create-sql.mdx
deleted file mode 100644
index 4728c50..0000000
--- a/reference/cli/projects-create-sql.mdx
+++ /dev/null
@@ -1,39 +0,0 @@
----
-title: forest projects:create:sql
-description: "Create a new Forest Admin project"
----
-
-# forest projects:create:sql
-
-Create a new Forest Admin project.
-
-## Usage
-
-```bash
-forest projects:create:sql [APPLICATIONNAME] [options]
-```
-
-## Arguments
-
-| Argument | Description |
-|---|---|
-| `APPLICATIONNAME` | Name of the project to create. |
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
-| `-P, --applicationPort=<value>` | Port of your admin backend application. |
-| `-c, --databaseConnectionURL=<value>` | Enter the database credentials with a connection URL. |
-| `-d, --databaseDialect=<option>` | Enter your database dialect. <options: mssql\|mysql / mariadb\|postgres> |
-| `-h, --databaseHost=<value>` | Enter your database host. |
-| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
-| `-n, --databaseName=<value>` | Enter your database name. |
-| `-p, --databasePort=<value>` | Enter your database port. |
-| `-s, --databaseSchema=<value>` | Enter your database schema. |
-| `-u, --databaseUser=<value>` | Enter your database user. |
-| `--databasePassword=<value>` | Enter your database password. |
-| `--databaseSSL` | Use SSL for database connection. |
-| `--databaseSslMode=<option>` | SSL mode. <options: preferred\|verify\|required\|disabled> |
-
diff --git a/reference/cli/projects.mdx b/reference/cli/projects.mdx
new file mode 100644
index 0000000..c4668e5
--- /dev/null
+++ b/reference/cli/projects.mdx
@@ -0,0 +1,82 @@
+---
+title: Projects
+description: "Create Forest projects from a database or a zero-DB demo."
+---
+
+# Projects
+
+Create Forest projects from a database or a zero-DB demo.
+
+## forest projects:create:demo
+
+Create a new Forest Admin project with demo data — no database required.
+
+```bash
+forest projects:create:demo [APPLICATIONNAME] [options]
+```
+
+| Argument | Description |
+|---|---|
+| `APPLICATIONNAME` | Name of the project to create. |
+
+| Option | Description |
+|---|---|
+| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
+| `-P, --applicationPort=<value>` | Port of your admin backend application. |
+| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
+
+## forest projects:create:sql
+
+Create a new Forest Admin project.
+
+```bash
+forest projects:create:sql [APPLICATIONNAME] [options]
+```
+
+| Argument | Description |
+|---|---|
+| `APPLICATIONNAME` | Name of the project to create. |
+
+| Option | Description |
+|---|---|
+| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
+| `-P, --applicationPort=<value>` | Port of your admin backend application. |
+| `-c, --databaseConnectionURL=<value>` | Enter the database credentials with a connection URL. |
+| `-d, --databaseDialect=<option>` | Enter your database dialect. <options: mssql\|mysql / mariadb\|postgres> |
+| `-h, --databaseHost=<value>` | Enter your database host. |
+| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
+| `-n, --databaseName=<value>` | Enter your database name. |
+| `-p, --databasePort=<value>` | Enter your database port. |
+| `-s, --databaseSchema=<value>` | Enter your database schema. |
+| `-u, --databaseUser=<value>` | Enter your database user. |
+| `--databasePassword=<value>` | Enter your database password. |
+| `--databaseSSL` | Use SSL for database connection. |
+| `--databaseSslMode=<option>` | SSL mode. <options: preferred\|verify\|required\|disabled> |
+
+## forest projects:create:nosql
+
+Create a new Forest Admin project.
+
+```bash
+forest projects:create:nosql [APPLICATIONNAME] [options]
+```
+
+| Argument | Description |
+|---|---|
+| `APPLICATIONNAME` | Name of the project to create. |
+
+| Option | Description |
+|---|---|
+| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
+| `-P, --applicationPort=<value>` | Port of your admin backend application. |
+| `-c, --databaseConnectionURL=<value>` | Enter the database credentials with a connection URL. |
+| `-h, --databaseHost=<value>` | Enter your database host. |
+| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
+| `-n, --databaseName=<value>` | Enter your database name. |
+| `-p, --databasePort=<value>` | Enter your database port. |
+| `-u, --databaseUser=<value>` | Enter your database user. |
+| `--databasePassword=<value>` | Enter your database password. |
+| `--databaseSSL` | Use SSL for database connection. |
+| `--databaseSslMode=<option>` | SSL mode. <options: preferred\|verify\|required\|disabled> |
+| `--mongoDBSRV` | Use SRV DNS record for mongoDB connection. |
+
diff --git a/reference/cli/roles-apply.mdx b/reference/cli/roles-apply.mdx
deleted file mode 100644
index ffc7160..0000000
--- a/reference/cli/roles-apply.mdx
+++ /dev/null
@@ -1,29 +0,0 @@
----
-title: forest roles:apply
-description: "Apply a wide-format CSV to update role permissions in an environment"
----
-
-# forest roles:apply
-
-Apply a wide-format CSV to update role permissions in an environment.
-
-## Usage
-
-```bash
-forest roles:apply [FILE] [options]
-```
-
-## Arguments
-
-| Argument | Description |
-|---|---|
-| `FILE` | Path to the wide-format CSV file. |
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-F, --force` | Skip confirmation prompt. |
-| `-e, --env=<value>` | (required) Environment name to apply to. |
-| `-p, --projectId=<value>` | Forest project ID. |
-
diff --git a/reference/cli/roles-copy.mdx b/reference/cli/roles-copy.mdx
deleted file mode 100644
index 5e2d8ae..0000000
--- a/reference/cli/roles-copy.mdx
+++ /dev/null
@@ -1,23 +0,0 @@
----
-title: forest roles:copy
-description: "Copy role permissions from one environment to another"
----
-
-# forest roles:copy
-
-Copy role permissions from one environment to another.
-
-## Usage
-
-```bash
-forest roles:copy [options]
-```
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-f, --from=<value>` | (required) Source environment name. |
-| `-p, --projectId=<value>` | Forest project ID. |
-| `-t, --to=<value>` | (required) Destination environment name. |
-
diff --git a/reference/cli/roles-create.mdx b/reference/cli/roles-create.mdx
deleted file mode 100644
index acbf703..0000000
--- a/reference/cli/roles-create.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: forest roles:create
-description: "Create a new role in a project"
----
-
-# forest roles:create
-
-Create a new role in a project.
-
-## Usage
-
-```bash
-forest roles:create [options]
-```
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-n, --name=<value>` | (required) Name of the role to create. |
-| `-p, --projectId=<value>` | Forest project ID. |
-
diff --git a/reference/cli/roles-export.mdx b/reference/cli/roles-export.mdx
deleted file mode 100644
index ebafda4..0000000
--- a/reference/cli/roles-export.mdx
+++ /dev/null
@@ -1,23 +0,0 @@
----
-title: forest roles:export
-description: "Export all roles and their permissions to a wide CSV file"
----
-
-# forest roles:export
-
-Export all roles and their permissions to a wide CSV file.
-
-## Usage
-
-```bash
-forest roles:export [options]
-```
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-e, --env=<value>` | (required) Environment name to export permissions for. |
-| `-o, --output=<value>` | Output file path (default: stdout). |
-| `-p, --projectId=<value>` | Forest project ID. |
-
diff --git a/reference/cli/roles.mdx b/reference/cli/roles.mdx
new file mode 100644
index 0000000..36f84e6
--- /dev/null
+++ b/reference/cli/roles.mdx
@@ -0,0 +1,68 @@
+---
+title: Roles
+description: "Manage roles and permissions, including roles-as-code via CSV."
+---
+
+# Roles
+
+Manage roles and permissions, including roles-as-code via CSV.
+
+## forest roles:create
+
+Create a new role in a project.
+
+```bash
+forest roles:create [options]
+```
+
+| Option | Description |
+|---|---|
+| `-n, --name=<value>` | (required) Name of the role to create. |
+| `-p, --projectId=<value>` | Forest project ID. |
+
+## forest roles:apply
+
+Apply a wide-format CSV to update role permissions in an environment.
+
+```bash
+forest roles:apply [FILE] [options]
+```
+
+| Argument | Description |
+|---|---|
+| `FILE` | Path to the wide-format CSV file. |
+
+| Option | Description |
+|---|---|
+| `-F, --force` | Skip confirmation prompt. |
+| `-e, --env=<value>` | (required) Environment name to apply to. |
+| `-p, --projectId=<value>` | Forest project ID. |
+
+## forest roles:copy
+
+Copy role permissions from one environment to another.
+
+```bash
+forest roles:copy [options]
+```
+
+| Option | Description |
+|---|---|
+| `-f, --from=<value>` | (required) Source environment name. |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-t, --to=<value>` | (required) Destination environment name. |
+
+## forest roles:export
+
+Export all roles and their permissions to a wide CSV file.
+
+```bash
+forest roles:export [options]
+```
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | (required) Environment name to export permissions for. |
+| `-o, --output=<value>` | Output file path (default: stdout). |
+| `-p, --projectId=<value>` | Forest project ID. |
+
diff --git a/reference/cli/teams-copy-layout.mdx b/reference/cli/teams-copy-layout.mdx
deleted file mode 100644
index 94659e0..0000000
--- a/reference/cli/teams-copy-layout.mdx
+++ /dev/null
@@ -1,24 +0,0 @@
----
-title: forest teams:copy-layout
-description: "Copy a team's whole layout onto another team of the same project"
----
-
-# forest teams:copy-layout
-
-Copy a team's whole layout onto another team of the same project.
-
-## Usage
-
-```bash
-forest teams:copy-layout [options]
-```
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-f, --from=<value>` | (required) Name of the team to copy the layout from. |
-| `-p, --projectId=<value>` | Forest project ID. |
-| `-t, --to=<value>` | (required) Name of the team to copy the layout to (its layout is overwritten). |
-| `--force` | Skip the confirmation prompt. |
-
diff --git a/reference/cli/teams-create.mdx b/reference/cli/teams-create.mdx
deleted file mode 100644
index 65f4382..0000000
--- a/reference/cli/teams-create.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: forest teams:create
-description: "Create a new team in a project"
----
-
-# forest teams:create
-
-Create a new team in a project.
-
-## Usage
-
-```bash
-forest teams:create [options]
-```
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-n, --name=<value>` | (required) Name of the team to create. |
-| `-p, --projectId=<value>` | Forest project ID. |
-
diff --git a/reference/cli/teams-delete.mdx b/reference/cli/teams-delete.mdx
deleted file mode 100644
index 023fad2..0000000
--- a/reference/cli/teams-delete.mdx
+++ /dev/null
@@ -1,23 +0,0 @@
----
-title: forest teams:delete
-description: "Delete a team from a project"
----
-
-# forest teams:delete
-
-Delete a team from a project.
-
-## Usage
-
-```bash
-forest teams:delete [options]
-```
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-n, --name=<value>` | (required) Name of the team to delete. |
-| `-p, --projectId=<value>` | Forest project ID. |
-| `--force` | Skip the confirmation prompt. |
-
diff --git a/reference/cli/teams.mdx b/reference/cli/teams.mdx
new file mode 100644
index 0000000..e999e77
--- /dev/null
+++ b/reference/cli/teams.mdx
@@ -0,0 +1,51 @@
+---
+title: Teams
+description: "Create, delete, and copy the layout of teams."
+---
+
+# Teams
+
+Create, delete, and copy the layout of teams.
+
+## forest teams:create
+
+Create a new team in a project.
+
+```bash
+forest teams:create [options]
+```
+
+| Option | Description |
+|---|---|
+| `-n, --name=<value>` | (required) Name of the team to create. |
+| `-p, --projectId=<value>` | Forest project ID. |
+
+## forest teams:delete
+
+Delete a team from a project.
+
+```bash
+forest teams:delete [options]
+```
+
+| Option | Description |
+|---|---|
+| `-n, --name=<value>` | (required) Name of the team to delete. |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `--force` | Skip the confirmation prompt. |
+
+## forest teams:copy-layout
+
+Copy a team's whole layout onto another team of the same project.
+
+```bash
+forest teams:copy-layout [options]
+```
+
+| Option | Description |
+|---|---|
+| `-f, --from=<value>` | (required) Name of the team to copy the layout from. |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-t, --to=<value>` | (required) Name of the team to copy the layout to (its layout is overwritten). |
+| `--force` | Skip the confirmation prompt. |
+
diff --git a/reference/cli/users-edit.mdx b/reference/cli/users-edit.mdx
deleted file mode 100644
index 1b5562d..0000000
--- a/reference/cli/users-edit.mdx
+++ /dev/null
@@ -1,26 +0,0 @@
----
-title: forest users:edit
-description: "Edit a user's role, team(s) or permission level"
----
-
-# forest users:edit
-
-Edit a user's role, team(s) or permission level.
-
-## Usage
-
-```bash
-forest users:edit [options]
-```
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-e, --email=<value>` | (required) Email of the user to edit. |
-| `-f, --force` | Skip the confirmation prompt when teams would be removed. |
-| `-l, --permission-level=<option>` | New permission level. <options: admin\|editor\|user\|developer\|manager> |
-| `-p, --projectId=<value>` | Forest project ID. |
-| `-r, --role=<value>` | New role name to assign. |
-| `-t, --team=<value>...` | Team name to set for this project. Repeatable; this REPLACES the user’s current team set on the project. |
-
diff --git a/reference/cli/users-invite.mdx b/reference/cli/users-invite.mdx
deleted file mode 100644
index 31ca8e9..0000000
--- a/reference/cli/users-invite.mdx
+++ /dev/null
@@ -1,26 +0,0 @@
----
-title: forest users:invite
-description: "Invite users to a project"
----
-
-# forest users:invite
-
-Invite users to a project.
-
-## Usage
-
-```bash
-forest users:invite [options]
-```
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-e, --email=<value>...` | (required) Email of the user to invite (repeat the flag to invite several users). |
-| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
-| `-l, --permission-level=<option>` | (required) Permission level of the invited users. <options: admin\|editor\|user\|developer\|manager> |
-| `-p, --projectId=<value>` | Forest project ID. |
-| `-r, --role=<value>` | Role name to assign (prompted if omitted and several exist). |
-| `-t, --team=<value>` | Team name to add the invited users to (prompted if omitted and several exist). |
-
diff --git a/reference/cli/users-list.mdx b/reference/cli/users-list.mdx
deleted file mode 100644
index fc40610..0000000
--- a/reference/cli/users-list.mdx
+++ /dev/null
@@ -1,22 +0,0 @@
----
-title: forest users:list
-description: "List all users of a project"
----
-
-# forest users:list
-
-List all users of a project.
-
-## Usage
-
-```bash
-forest users:list [options]
-```
-
-## Options
-
-| Option | Description |
-|---|---|
-| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
-| `-p, --projectId=<value>` | Forest project ID. |
-
diff --git a/reference/cli/users.mdx b/reference/cli/users.mdx
new file mode 100644
index 0000000..2c48b0f
--- /dev/null
+++ b/reference/cli/users.mdx
@@ -0,0 +1,56 @@
+---
+title: Users
+description: "List, invite, and edit the users of a project."
+---
+
+# Users
+
+List, invite, and edit the users of a project.
+
+## forest users:list
+
+List all users of a project.
+
+```bash
+forest users:list [options]
+```
+
+| Option | Description |
+|---|---|
+| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
+| `-p, --projectId=<value>` | Forest project ID. |
+
+## forest users:invite
+
+Invite users to a project.
+
+```bash
+forest users:invite [options]
+```
+
+| Option | Description |
+|---|---|
+| `-e, --email=<value>...` | (required) Email of the user to invite (repeat the flag to invite several users). |
+| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
+| `-l, --permission-level=<option>` | (required) Permission level of the invited users. <options: admin\|editor\|user\|developer\|manager> |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-r, --role=<value>` | Role name to assign (prompted if omitted and several exist). |
+| `-t, --team=<value>` | Team name to add the invited users to (prompted if omitted and several exist). |
+
+## forest users:edit
+
+Edit a user's role, team(s) or permission level.
+
+```bash
+forest users:edit [options]
+```
+
+| Option | Description |
+|---|---|
+| `-e, --email=<value>` | (required) Email of the user to edit. |
+| `-f, --force` | Skip the confirmation prompt when teams would be removed. |
+| `-l, --permission-level=<option>` | New permission level. <options: admin\|editor\|user\|developer\|manager> |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-r, --role=<value>` | New role name to assign. |
+| `-t, --team=<value>...` | Team name to set for this project. Repeatable; this REPLACES the user’s current team set on the project. |
+
diff --git a/reference/cli/workflow-apply.mdx b/reference/cli/workflows.mdx
similarity index 80%
rename from reference/cli/workflow-apply.mdx
rename to reference/cli/workflows.mdx
index b4999d0..db7bd95 100644
--- a/reference/cli/workflow-apply.mdx
+++ b/reference/cli/workflows.mdx
@@ -1,26 +1,24 @@
 ---
-title: forest workflow:apply
-description: "Create or update a workflow from a JSON steps spec (compiles to BPMN and uploads it)"
+title: Workflows
+description: "Author workflows as code from a JSON steps spec."
 ---
 
-# forest workflow:apply
+# Workflows
 
-Create or update a workflow from a JSON steps spec (compiles to BPMN and uploads it). Reading the spec from stdin disables prompts: pass -p/-e/-t and --force explicitly.
+Author workflows as code from a JSON `steps` spec.
+
+## forest workflow:apply
 
-## Usage
+Create or update a workflow from a JSON steps spec (compiles to BPMN and uploads it). Reading the spec from stdin disables prompts: pass -p/-e/-t and --force explicitly.
 
 ```bash
 forest workflow:apply [FILE] [options]
 ```
 
-## Arguments
-
 | Argument | Description |
 |---|---|
 | `FILE` | JSON workflow spec ({ name, collection, steps, id?, segments?, position?, start?, version? }). "-" or omit to read stdin. |
 
-## Options
-
 | Option | Description |
 |---|---|
 | `-e, --env=<value>` | Environment name or id. |

From 23d618860a84c0366dbe8991a9fe858b0c1a02ab Mon Sep 17 00:00:00 2001
From: Gautier Delache <gautierd@forestadmin.com>
Date: Fri, 17 Jul 2026 14:18:19 +0200
Subject: [PATCH 3/4] docs(cli): per-command pages everywhere + grouped nav
 (coherent with existing pages)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Revert the category-page approach: one page per command (matching the existing
branch/deploy/… pages), grouped in the sidebar (Branches & deployment, Projects,
Layout, Workflows, Environments, Roles, Teams, Users) using the same nested-group
pattern already used elsewhere (Connect → Data Sources). layout:diff stays out.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs.json                                     | 75 +++++++++++++---
 reference/cli/environments-create.mdx         | 26 ++++++
 reference/cli/environments-delete.mdx         | 27 ++++++
 reference/cli/environments-get.mdx            | 27 ++++++
 reference/cli/environments-reset.mdx          | 23 +++++
 reference/cli/environments-update.mdx         | 23 +++++
 reference/cli/environments.mdx                | 86 -------------------
 reference/cli/layout-apply.mdx                | 31 +++++++
 reference/cli/layout-patch.mdx                | 31 +++++++
 reference/cli/layout-pull.mdx                 | 25 ++++++
 reference/cli/layout.mdx                      | 65 --------------
 reference/cli/overview.mdx                    | 58 ++++++-------
 reference/cli/projects-create-demo.mdx        | 29 +++++++
 reference/cli/projects-create-nosql.mdx       | 38 ++++++++
 reference/cli/projects-create-sql.mdx         | 39 +++++++++
 reference/cli/projects.mdx                    | 82 ------------------
 reference/cli/roles-apply.mdx                 | 29 +++++++
 reference/cli/roles-copy.mdx                  | 23 +++++
 reference/cli/roles-create.mdx                | 22 +++++
 reference/cli/roles-export.mdx                | 23 +++++
 reference/cli/roles.mdx                       | 68 ---------------
 reference/cli/teams-copy-layout.mdx           | 24 ++++++
 reference/cli/teams-create.mdx                | 22 +++++
 reference/cli/teams-delete.mdx                | 23 +++++
 reference/cli/teams.mdx                       | 51 -----------
 reference/cli/users-edit.mdx                  | 26 ++++++
 reference/cli/users-invite.mdx                | 26 ++++++
 reference/cli/users-list.mdx                  | 22 +++++
 reference/cli/users.mdx                       | 56 ------------
 .../cli/{workflows.mdx => workflow-apply.mdx} | 16 ++--
 30 files changed, 661 insertions(+), 455 deletions(-)
 create mode 100644 reference/cli/environments-create.mdx
 create mode 100644 reference/cli/environments-delete.mdx
 create mode 100644 reference/cli/environments-get.mdx
 create mode 100644 reference/cli/environments-reset.mdx
 create mode 100644 reference/cli/environments-update.mdx
 delete mode 100644 reference/cli/environments.mdx
 create mode 100644 reference/cli/layout-apply.mdx
 create mode 100644 reference/cli/layout-patch.mdx
 create mode 100644 reference/cli/layout-pull.mdx
 delete mode 100644 reference/cli/layout.mdx
 create mode 100644 reference/cli/projects-create-demo.mdx
 create mode 100644 reference/cli/projects-create-nosql.mdx
 create mode 100644 reference/cli/projects-create-sql.mdx
 delete mode 100644 reference/cli/projects.mdx
 create mode 100644 reference/cli/roles-apply.mdx
 create mode 100644 reference/cli/roles-copy.mdx
 create mode 100644 reference/cli/roles-create.mdx
 create mode 100644 reference/cli/roles-export.mdx
 delete mode 100644 reference/cli/roles.mdx
 create mode 100644 reference/cli/teams-copy-layout.mdx
 create mode 100644 reference/cli/teams-create.mdx
 create mode 100644 reference/cli/teams-delete.mdx
 delete mode 100644 reference/cli/teams.mdx
 create mode 100644 reference/cli/users-edit.mdx
 create mode 100644 reference/cli/users-invite.mdx
 create mode 100644 reference/cli/users-list.mdx
 delete mode 100644 reference/cli/users.mdx
 rename reference/cli/{workflows.mdx => workflow-apply.mdx} (80%)

diff --git a/docs.json b/docs.json
index f2b05f3..a73bc1a 100644
--- a/docs.json
+++ b/docs.json
@@ -343,17 +343,70 @@
               "reference/cli/overview",
               "reference/cli/init",
               "reference/cli/login",
-              "reference/cli/branch",
-              "reference/cli/switch",
-              "reference/cli/push",
-              "reference/cli/deploy",
-              "reference/cli/projects",
-              "reference/cli/layout",
-              "reference/cli/workflows",
-              "reference/cli/environments",
-              "reference/cli/roles",
-              "reference/cli/teams",
-              "reference/cli/users"
+              {
+                "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"
+                ]
+              }
             ]
           },
           {
diff --git a/reference/cli/environments-create.mdx b/reference/cli/environments-create.mdx
new file mode 100644
index 0000000..6a3290a
--- /dev/null
+++ b/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. |
+
diff --git a/reference/cli/environments-delete.mdx b/reference/cli/environments-delete.mdx
new file mode 100644
index 0000000..57f6198
--- /dev/null
+++ b/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. |
+
diff --git a/reference/cli/environments-get.mdx b/reference/cli/environments-get.mdx
new file mode 100644
index 0000000..8efa272
--- /dev/null
+++ b/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> |
+
diff --git a/reference/cli/environments-reset.mdx b/reference/cli/environments-reset.mdx
new file mode 100644
index 0000000..b7f8db5
--- /dev/null
+++ b/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. |
+
diff --git a/reference/cli/environments-update.mdx b/reference/cli/environments-update.mdx
new file mode 100644
index 0000000..c469c53
--- /dev/null
+++ b/reference/cli/environments-update.mdx
@@ -0,0 +1,23 @@
+---
+title: forest environments:update
+description: "Update an environment"
+---
+
+# forest environments:update
+
+Update an environment.
+
+## Usage
+
+```bash
+forest environments:update [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --environmentId=<value>` | (required) The forest environment ID to update. |
+| `-n, --name=<value>` | To update the environment name. |
+| `-u, --url=<value>` | To update the application URL. |
+
diff --git a/reference/cli/environments.mdx b/reference/cli/environments.mdx
deleted file mode 100644
index 05947f7..0000000
--- a/reference/cli/environments.mdx
+++ /dev/null
@@ -1,86 +0,0 @@
----
-title: Environments
-description: "Create and manage your project environments."
----
-
-# Environments
-
-Create and manage your project environments.
-
-## forest environments:create
-
-Create a new environment.
-
-```bash
-forest environments:create [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. |
-
-## forest environments:get
-
-Get the configuration of an environment.
-
-```bash
-forest environments:get [ENVIRONMENTID] [options]
-```
-
-| Argument | Description |
-|---|---|
-| `ENVIRONMENTID` | ID of an environment. |
-
-| Option | Description |
-|---|---|
-| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
-
-## forest environments:update
-
-Update an environment.
-
-```bash
-forest environments:update [options]
-```
-
-| Option | Description |
-|---|---|
-| `-e, --environmentId=<value>` | (required) The forest environment ID to update. |
-| `-n, --name=<value>` | To update the environment name. |
-| `-u, --url=<value>` | To update the application URL. |
-
-## forest environments:delete
-
-Delete an environment.
-
-```bash
-forest environments:delete [ENVIRONMENTID] [options]
-```
-
-| Argument | Description |
-|---|---|
-| `ENVIRONMENTID` | ID of an environment. |
-
-| Option | Description |
-|---|---|
-| `-f, --force` | Force delete. |
-
-## forest environments:reset
-
-Reset a remote environment by removing all layout changes.
-
-```bash
-forest environments:reset [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. |
-
diff --git a/reference/cli/layout-apply.mdx b/reference/cli/layout-apply.mdx
new file mode 100644
index 0000000..50cceec
--- /dev/null
+++ b/reference/cli/layout-apply.mdx
@@ -0,0 +1,31 @@
+---
+title: forest layout:apply
+description: "Apply a forest-layout.json to an environment (pushes JSON-Patch changes)"
+---
+
+# forest layout:apply
+
+Apply a forest-layout.json to an environment (pushes JSON-Patch changes).
+
+## Usage
+
+```bash
+forest layout:apply [FILE] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `FILE` | Layout file to apply (e.g. forest-layout.json). |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | Environment to apply to (name or id). Prompted if omitted. |
+| `-f, --force` | Skip the confirmation prompt. |
+| `-p, --projectId=<value>` | Id of the project (resolved/prompted when omitted). |
+| `-t, --team=<value>` | Team to apply to (name or id). Prompted if omitted. |
+| `--with-workflows` | Also upload workflow BPMN sidecars (workflows/<id>.bpmn) to the target env — the round-trip counterpart of `pull --with-workflows`. |
+
diff --git a/reference/cli/layout-patch.mdx b/reference/cli/layout-patch.mdx
new file mode 100644
index 0000000..a3ddbcd
--- /dev/null
+++ b/reference/cli/layout-patch.mdx
@@ -0,0 +1,31 @@
+---
+title: forest layout:patch
+description: "Patch the layout directly (single PATCH per domain, like the front — no pull/apply)"
+---
+
+# forest layout:patch
+
+Patch the layout directly (single PATCH per domain, like the front — no pull/apply).
+
+## Usage
+
+```bash
+forest layout:patch [FILE] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `FILE` | JSON patch file to apply. Use "-" or omit to read from stdin. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | Environment name or id. |
+| `-f, --force` | Skip the confirmation prompt (required when reading from stdin). |
+| `-p, --projectId=<value>` | Project id. |
+| `-t, --team=<value>` | Team name or id. |
+| `--dry-run` | Print operations without sending them. |
+
diff --git a/reference/cli/layout-pull.mdx b/reference/cli/layout-pull.mdx
new file mode 100644
index 0000000..8b3c05e
--- /dev/null
+++ b/reference/cli/layout-pull.mdx
@@ -0,0 +1,25 @@
+---
+title: forest layout:pull
+description: "Pull the layout (rendering) of an environment into a forest-layout.json file"
+---
+
+# forest layout:pull
+
+Pull the layout (rendering) of an environment into a forest-layout.json file.
+
+## Usage
+
+```bash
+forest layout:pull [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | Environment to pull from (name or id). Defaults to the environment of FOREST_ENV_SECRET when set, otherwise the development environment. |
+| `-o, --out=<value>` | [default: forest-layout.json] Output file path (default: forest-layout.json). |
+| `-p, --projectId=<value>` | Id of the project (resolved automatically when you only have one). |
+| `-t, --team=<value>` | Team whose layout to pull (name or id). Defaults to the "Operations" team. |
+| `--with-workflows` | Also download each workflow's BPMN into sidecar files (workflows/<id>.bpmn) for round-trip. |
+
diff --git a/reference/cli/layout.mdx b/reference/cli/layout.mdx
deleted file mode 100644
index f0a9d91..0000000
--- a/reference/cli/layout.mdx
+++ /dev/null
@@ -1,65 +0,0 @@
----
-title: Layout
-description: "Manage your UI layout as code — pull it to a file, apply it, or patch it directly."
----
-
-# Layout
-
-Manage your UI layout as code — pull it to a file, apply it, or patch it directly.
-
-## forest layout:pull
-
-Pull the layout (rendering) of an environment into a forest-layout.json file.
-
-```bash
-forest layout:pull [options]
-```
-
-| Option | Description |
-|---|---|
-| `-e, --env=<value>` | Environment to pull from (name or id). Defaults to the environment of FOREST_ENV_SECRET when set, otherwise the development environment. |
-| `-o, --out=<value>` | [default: forest-layout.json] Output file path (default: forest-layout.json). |
-| `-p, --projectId=<value>` | Id of the project (resolved automatically when you only have one). |
-| `-t, --team=<value>` | Team whose layout to pull (name or id). Defaults to the "Operations" team. |
-| `--with-workflows` | Also download each workflow's BPMN into sidecar files (workflows/<id>.bpmn) for round-trip. |
-
-## forest layout:apply
-
-Apply a forest-layout.json to an environment (pushes JSON-Patch changes).
-
-```bash
-forest layout:apply [FILE] [options]
-```
-
-| Argument | Description |
-|---|---|
-| `FILE` | Layout file to apply (e.g. forest-layout.json). |
-
-| Option | Description |
-|---|---|
-| `-e, --env=<value>` | Environment to apply to (name or id). Prompted if omitted. |
-| `-f, --force` | Skip the confirmation prompt. |
-| `-p, --projectId=<value>` | Id of the project (resolved/prompted when omitted). |
-| `-t, --team=<value>` | Team to apply to (name or id). Prompted if omitted. |
-| `--with-workflows` | Also upload workflow BPMN sidecars (workflows/<id>.bpmn) to the target env — the round-trip counterpart of `pull --with-workflows`. |
-
-## forest layout:patch
-
-Patch the layout directly (single PATCH per domain, like the front — no pull/apply).
-
-```bash
-forest layout:patch [FILE] [options]
-```
-
-| Argument | Description |
-|---|---|
-| `FILE` | JSON patch file to apply. Use "-" or omit to read from stdin. |
-
-| Option | Description |
-|---|---|
-| `-e, --env=<value>` | Environment name or id. |
-| `-f, --force` | Skip the confirmation prompt (required when reading from stdin). |
-| `-p, --projectId=<value>` | Project id. |
-| `-t, --team=<value>` | Team name or id. |
-| `--dry-run` | Print operations without sending them. |
-
diff --git a/reference/cli/overview.mdx b/reference/cli/overview.mdx
index aa1d669..a246fb7 100644
--- a/reference/cli/overview.mdx
+++ b/reference/cli/overview.mdx
@@ -62,65 +62,65 @@ forest init
 | [`forest push`](/reference/cli/push) | Push layout changes from your branch to its origin environment |
 | [`forest deploy`](/reference/cli/deploy) | Deploy layout changes to the production (reference) environment |
 
-### [Environments](/reference/cli/environments)
+### Environments
 
 | Command | Description |
 |---|---|
 | `forest environments` | List all environments |
-| `forest environments:create` | Create a new environment |
-| `forest environments:get` | Get an environment's configuration |
-| `forest environments:update` | Update an environment |
-| `forest environments:delete` | Delete an environment |
-| `forest environments:reset` | Reset all layout changes on a remote environment |
+| [`forest environments:create`](/reference/cli/environments-create) | Create a new environment |
+| [`forest environments:get`](/reference/cli/environments-get) | Get an environment's configuration |
+| [`forest environments:update`](/reference/cli/environments-update) | Update an environment |
+| [`forest environments:delete`](/reference/cli/environments-delete) | Delete an environment |
+| [`forest environments:reset`](/reference/cli/environments-reset) | Reset all layout changes on a remote environment |
 
-### [Projects](/reference/cli/projects)
+### Projects
 
 | Command | Description |
 |---|---|
 | `forest projects` | List all projects |
 | `forest projects:get` | Get a project's configuration |
-| `forest projects:create:demo` | Create a project with a zero-DB demo datasource |
-| `forest projects:create:sql` | Create a project from a SQL database |
-| `forest projects:create:nosql` | Create a project from a NoSQL (Mongo) database |
+| [`forest projects:create:demo`](/reference/cli/projects-create-demo) | Create a project with a zero-DB demo datasource |
+| [`forest projects:create:sql`](/reference/cli/projects-create-sql) | Create a project from a SQL database |
+| [`forest projects:create:nosql`](/reference/cli/projects-create-nosql) | Create a project from a NoSQL (Mongo) database |
 
-### [Layout](/reference/cli/layout)
+### Layout
 
 | Command | Description |
 |---|---|
-| `forest layout:pull` | Pull an environment's layout into a `forest-layout.json` file |
-| `forest layout:apply` | Apply a `forest-layout.json` to an environment |
-| `forest layout:patch` | Patch the layout directly (single PATCH per domain, like the front) |
+| [`forest layout:pull`](/reference/cli/layout-pull) | Pull an environment's layout into a `forest-layout.json` file |
+| [`forest layout:apply`](/reference/cli/layout-apply) | Apply a `forest-layout.json` to an environment |
+| [`forest layout:patch`](/reference/cli/layout-patch) | Patch the layout directly (single PATCH per domain, like the front) |
 
-### [Workflows](/reference/cli/workflows)
+### Workflows
 
 | Command | Description |
 |---|---|
-| `forest workflow:apply` | Create or update a workflow from a JSON `steps` spec (compiles to BPMN) |
+| [`forest workflow:apply`](/reference/cli/workflow-apply) | Create or update a workflow from a JSON `steps` spec (compiles to BPMN) |
 
-### [Roles](/reference/cli/roles)
+### Roles
 
 | Command | Description |
 |---|---|
-| `forest roles:create` | Create a role |
-| `forest roles:apply` | Apply a wide-format CSV of role permissions to an environment |
-| `forest roles:copy` | Copy roles between environments |
-| `forest roles:export` | Export an environment's roles to a CSV |
+| [`forest roles:create`](/reference/cli/roles-create) | Create a role |
+| [`forest roles:apply`](/reference/cli/roles-apply) | Apply a wide-format CSV of role permissions to an environment |
+| [`forest roles:copy`](/reference/cli/roles-copy) | Copy roles between environments |
+| [`forest roles:export`](/reference/cli/roles-export) | Export an environment's roles to a CSV |
 
-### [Teams](/reference/cli/teams)
+### Teams
 
 | Command | Description |
 |---|---|
-| `forest teams:create` | Create a team |
-| `forest teams:delete` | Delete a team |
-| `forest teams:copy-layout` | Copy a team's layout to another team |
+| [`forest teams:create`](/reference/cli/teams-create) | Create a team |
+| [`forest teams:delete`](/reference/cli/teams-delete) | Delete a team |
+| [`forest teams:copy-layout`](/reference/cli/teams-copy-layout) | Copy a team's layout to another team |
 
-### [Users](/reference/cli/users)
+### Users
 
 | Command | Description |
 |---|---|
-| `forest users:list` | List the users of a project |
-| `forest users:invite` | Invite users to a project |
-| `forest users:edit` | Edit a user's role, teams, or permission level |
+| [`forest users:list`](/reference/cli/users-list) | List the users of a project |
+| [`forest users:invite`](/reference/cli/users-invite) | Invite users to a project |
+| [`forest users:edit`](/reference/cli/users-edit) | Edit a user's role, teams, or permission level |
 
 ### Schema
 
diff --git a/reference/cli/projects-create-demo.mdx b/reference/cli/projects-create-demo.mdx
new file mode 100644
index 0000000..793fe6f
--- /dev/null
+++ b/reference/cli/projects-create-demo.mdx
@@ -0,0 +1,29 @@
+---
+title: forest projects:create:demo
+description: "Create a new Forest Admin project with demo data — no database required"
+---
+
+# forest projects:create:demo
+
+Create a new Forest Admin project with demo data — no database required.
+
+## Usage
+
+```bash
+forest projects:create:demo [APPLICATIONNAME] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `APPLICATIONNAME` | Name of the project to create. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
+| `-P, --applicationPort=<value>` | Port of your admin backend application. |
+| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
+
diff --git a/reference/cli/projects-create-nosql.mdx b/reference/cli/projects-create-nosql.mdx
new file mode 100644
index 0000000..5c2f723
--- /dev/null
+++ b/reference/cli/projects-create-nosql.mdx
@@ -0,0 +1,38 @@
+---
+title: forest projects:create:nosql
+description: "Create a new Forest Admin project"
+---
+
+# forest projects:create:nosql
+
+Create a new Forest Admin project.
+
+## Usage
+
+```bash
+forest projects:create:nosql [APPLICATIONNAME] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `APPLICATIONNAME` | Name of the project to create. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
+| `-P, --applicationPort=<value>` | Port of your admin backend application. |
+| `-c, --databaseConnectionURL=<value>` | Enter the database credentials with a connection URL. |
+| `-h, --databaseHost=<value>` | Enter your database host. |
+| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
+| `-n, --databaseName=<value>` | Enter your database name. |
+| `-p, --databasePort=<value>` | Enter your database port. |
+| `-u, --databaseUser=<value>` | Enter your database user. |
+| `--databasePassword=<value>` | Enter your database password. |
+| `--databaseSSL` | Use SSL for database connection. |
+| `--databaseSslMode=<option>` | SSL mode. <options: preferred\|verify\|required\|disabled> |
+| `--mongoDBSRV` | Use SRV DNS record for mongoDB connection. |
+
diff --git a/reference/cli/projects-create-sql.mdx b/reference/cli/projects-create-sql.mdx
new file mode 100644
index 0000000..4728c50
--- /dev/null
+++ b/reference/cli/projects-create-sql.mdx
@@ -0,0 +1,39 @@
+---
+title: forest projects:create:sql
+description: "Create a new Forest Admin project"
+---
+
+# forest projects:create:sql
+
+Create a new Forest Admin project.
+
+## Usage
+
+```bash
+forest projects:create:sql [APPLICATIONNAME] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `APPLICATIONNAME` | Name of the project to create. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
+| `-P, --applicationPort=<value>` | Port of your admin backend application. |
+| `-c, --databaseConnectionURL=<value>` | Enter the database credentials with a connection URL. |
+| `-d, --databaseDialect=<option>` | Enter your database dialect. <options: mssql\|mysql / mariadb\|postgres> |
+| `-h, --databaseHost=<value>` | Enter your database host. |
+| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
+| `-n, --databaseName=<value>` | Enter your database name. |
+| `-p, --databasePort=<value>` | Enter your database port. |
+| `-s, --databaseSchema=<value>` | Enter your database schema. |
+| `-u, --databaseUser=<value>` | Enter your database user. |
+| `--databasePassword=<value>` | Enter your database password. |
+| `--databaseSSL` | Use SSL for database connection. |
+| `--databaseSslMode=<option>` | SSL mode. <options: preferred\|verify\|required\|disabled> |
+
diff --git a/reference/cli/projects.mdx b/reference/cli/projects.mdx
deleted file mode 100644
index c4668e5..0000000
--- a/reference/cli/projects.mdx
+++ /dev/null
@@ -1,82 +0,0 @@
----
-title: Projects
-description: "Create Forest projects from a database or a zero-DB demo."
----
-
-# Projects
-
-Create Forest projects from a database or a zero-DB demo.
-
-## forest projects:create:demo
-
-Create a new Forest Admin project with demo data — no database required.
-
-```bash
-forest projects:create:demo [APPLICATIONNAME] [options]
-```
-
-| Argument | Description |
-|---|---|
-| `APPLICATIONNAME` | Name of the project to create. |
-
-| Option | Description |
-|---|---|
-| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
-| `-P, --applicationPort=<value>` | Port of your admin backend application. |
-| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
-
-## forest projects:create:sql
-
-Create a new Forest Admin project.
-
-```bash
-forest projects:create:sql [APPLICATIONNAME] [options]
-```
-
-| Argument | Description |
-|---|---|
-| `APPLICATIONNAME` | Name of the project to create. |
-
-| Option | Description |
-|---|---|
-| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
-| `-P, --applicationPort=<value>` | Port of your admin backend application. |
-| `-c, --databaseConnectionURL=<value>` | Enter the database credentials with a connection URL. |
-| `-d, --databaseDialect=<option>` | Enter your database dialect. <options: mssql\|mysql / mariadb\|postgres> |
-| `-h, --databaseHost=<value>` | Enter your database host. |
-| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
-| `-n, --databaseName=<value>` | Enter your database name. |
-| `-p, --databasePort=<value>` | Enter your database port. |
-| `-s, --databaseSchema=<value>` | Enter your database schema. |
-| `-u, --databaseUser=<value>` | Enter your database user. |
-| `--databasePassword=<value>` | Enter your database password. |
-| `--databaseSSL` | Use SSL for database connection. |
-| `--databaseSslMode=<option>` | SSL mode. <options: preferred\|verify\|required\|disabled> |
-
-## forest projects:create:nosql
-
-Create a new Forest Admin project.
-
-```bash
-forest projects:create:nosql [APPLICATIONNAME] [options]
-```
-
-| Argument | Description |
-|---|---|
-| `APPLICATIONNAME` | Name of the project to create. |
-
-| Option | Description |
-|---|---|
-| `-H, --applicationHost=<value>` | Hostname of your admin backend application. |
-| `-P, --applicationPort=<value>` | Port of your admin backend application. |
-| `-c, --databaseConnectionURL=<value>` | Enter the database credentials with a connection URL. |
-| `-h, --databaseHost=<value>` | Enter your database host. |
-| `-l, --language=<option>` | Choose the language you want to use for your project. <options: javascript\|typescript> |
-| `-n, --databaseName=<value>` | Enter your database name. |
-| `-p, --databasePort=<value>` | Enter your database port. |
-| `-u, --databaseUser=<value>` | Enter your database user. |
-| `--databasePassword=<value>` | Enter your database password. |
-| `--databaseSSL` | Use SSL for database connection. |
-| `--databaseSslMode=<option>` | SSL mode. <options: preferred\|verify\|required\|disabled> |
-| `--mongoDBSRV` | Use SRV DNS record for mongoDB connection. |
-
diff --git a/reference/cli/roles-apply.mdx b/reference/cli/roles-apply.mdx
new file mode 100644
index 0000000..ffc7160
--- /dev/null
+++ b/reference/cli/roles-apply.mdx
@@ -0,0 +1,29 @@
+---
+title: forest roles:apply
+description: "Apply a wide-format CSV to update role permissions in an environment"
+---
+
+# forest roles:apply
+
+Apply a wide-format CSV to update role permissions in an environment.
+
+## Usage
+
+```bash
+forest roles:apply [FILE] [options]
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `FILE` | Path to the wide-format CSV file. |
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-F, --force` | Skip confirmation prompt. |
+| `-e, --env=<value>` | (required) Environment name to apply to. |
+| `-p, --projectId=<value>` | Forest project ID. |
+
diff --git a/reference/cli/roles-copy.mdx b/reference/cli/roles-copy.mdx
new file mode 100644
index 0000000..5e2d8ae
--- /dev/null
+++ b/reference/cli/roles-copy.mdx
@@ -0,0 +1,23 @@
+---
+title: forest roles:copy
+description: "Copy role permissions from one environment to another"
+---
+
+# forest roles:copy
+
+Copy role permissions from one environment to another.
+
+## Usage
+
+```bash
+forest roles:copy [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-f, --from=<value>` | (required) Source environment name. |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-t, --to=<value>` | (required) Destination environment name. |
+
diff --git a/reference/cli/roles-create.mdx b/reference/cli/roles-create.mdx
new file mode 100644
index 0000000..acbf703
--- /dev/null
+++ b/reference/cli/roles-create.mdx
@@ -0,0 +1,22 @@
+---
+title: forest roles:create
+description: "Create a new role in a project"
+---
+
+# forest roles:create
+
+Create a new role in a project.
+
+## Usage
+
+```bash
+forest roles:create [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-n, --name=<value>` | (required) Name of the role to create. |
+| `-p, --projectId=<value>` | Forest project ID. |
+
diff --git a/reference/cli/roles-export.mdx b/reference/cli/roles-export.mdx
new file mode 100644
index 0000000..ebafda4
--- /dev/null
+++ b/reference/cli/roles-export.mdx
@@ -0,0 +1,23 @@
+---
+title: forest roles:export
+description: "Export all roles and their permissions to a wide CSV file"
+---
+
+# forest roles:export
+
+Export all roles and their permissions to a wide CSV file.
+
+## Usage
+
+```bash
+forest roles:export [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --env=<value>` | (required) Environment name to export permissions for. |
+| `-o, --output=<value>` | Output file path (default: stdout). |
+| `-p, --projectId=<value>` | Forest project ID. |
+
diff --git a/reference/cli/roles.mdx b/reference/cli/roles.mdx
deleted file mode 100644
index 36f84e6..0000000
--- a/reference/cli/roles.mdx
+++ /dev/null
@@ -1,68 +0,0 @@
----
-title: Roles
-description: "Manage roles and permissions, including roles-as-code via CSV."
----
-
-# Roles
-
-Manage roles and permissions, including roles-as-code via CSV.
-
-## forest roles:create
-
-Create a new role in a project.
-
-```bash
-forest roles:create [options]
-```
-
-| Option | Description |
-|---|---|
-| `-n, --name=<value>` | (required) Name of the role to create. |
-| `-p, --projectId=<value>` | Forest project ID. |
-
-## forest roles:apply
-
-Apply a wide-format CSV to update role permissions in an environment.
-
-```bash
-forest roles:apply [FILE] [options]
-```
-
-| Argument | Description |
-|---|---|
-| `FILE` | Path to the wide-format CSV file. |
-
-| Option | Description |
-|---|---|
-| `-F, --force` | Skip confirmation prompt. |
-| `-e, --env=<value>` | (required) Environment name to apply to. |
-| `-p, --projectId=<value>` | Forest project ID. |
-
-## forest roles:copy
-
-Copy role permissions from one environment to another.
-
-```bash
-forest roles:copy [options]
-```
-
-| Option | Description |
-|---|---|
-| `-f, --from=<value>` | (required) Source environment name. |
-| `-p, --projectId=<value>` | Forest project ID. |
-| `-t, --to=<value>` | (required) Destination environment name. |
-
-## forest roles:export
-
-Export all roles and their permissions to a wide CSV file.
-
-```bash
-forest roles:export [options]
-```
-
-| Option | Description |
-|---|---|
-| `-e, --env=<value>` | (required) Environment name to export permissions for. |
-| `-o, --output=<value>` | Output file path (default: stdout). |
-| `-p, --projectId=<value>` | Forest project ID. |
-
diff --git a/reference/cli/teams-copy-layout.mdx b/reference/cli/teams-copy-layout.mdx
new file mode 100644
index 0000000..94659e0
--- /dev/null
+++ b/reference/cli/teams-copy-layout.mdx
@@ -0,0 +1,24 @@
+---
+title: forest teams:copy-layout
+description: "Copy a team's whole layout onto another team of the same project"
+---
+
+# forest teams:copy-layout
+
+Copy a team's whole layout onto another team of the same project.
+
+## Usage
+
+```bash
+forest teams:copy-layout [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-f, --from=<value>` | (required) Name of the team to copy the layout from. |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-t, --to=<value>` | (required) Name of the team to copy the layout to (its layout is overwritten). |
+| `--force` | Skip the confirmation prompt. |
+
diff --git a/reference/cli/teams-create.mdx b/reference/cli/teams-create.mdx
new file mode 100644
index 0000000..65f4382
--- /dev/null
+++ b/reference/cli/teams-create.mdx
@@ -0,0 +1,22 @@
+---
+title: forest teams:create
+description: "Create a new team in a project"
+---
+
+# forest teams:create
+
+Create a new team in a project.
+
+## Usage
+
+```bash
+forest teams:create [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-n, --name=<value>` | (required) Name of the team to create. |
+| `-p, --projectId=<value>` | Forest project ID. |
+
diff --git a/reference/cli/teams-delete.mdx b/reference/cli/teams-delete.mdx
new file mode 100644
index 0000000..023fad2
--- /dev/null
+++ b/reference/cli/teams-delete.mdx
@@ -0,0 +1,23 @@
+---
+title: forest teams:delete
+description: "Delete a team from a project"
+---
+
+# forest teams:delete
+
+Delete a team from a project.
+
+## Usage
+
+```bash
+forest teams:delete [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-n, --name=<value>` | (required) Name of the team to delete. |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `--force` | Skip the confirmation prompt. |
+
diff --git a/reference/cli/teams.mdx b/reference/cli/teams.mdx
deleted file mode 100644
index e999e77..0000000
--- a/reference/cli/teams.mdx
+++ /dev/null
@@ -1,51 +0,0 @@
----
-title: Teams
-description: "Create, delete, and copy the layout of teams."
----
-
-# Teams
-
-Create, delete, and copy the layout of teams.
-
-## forest teams:create
-
-Create a new team in a project.
-
-```bash
-forest teams:create [options]
-```
-
-| Option | Description |
-|---|---|
-| `-n, --name=<value>` | (required) Name of the team to create. |
-| `-p, --projectId=<value>` | Forest project ID. |
-
-## forest teams:delete
-
-Delete a team from a project.
-
-```bash
-forest teams:delete [options]
-```
-
-| Option | Description |
-|---|---|
-| `-n, --name=<value>` | (required) Name of the team to delete. |
-| `-p, --projectId=<value>` | Forest project ID. |
-| `--force` | Skip the confirmation prompt. |
-
-## forest teams:copy-layout
-
-Copy a team's whole layout onto another team of the same project.
-
-```bash
-forest teams:copy-layout [options]
-```
-
-| Option | Description |
-|---|---|
-| `-f, --from=<value>` | (required) Name of the team to copy the layout from. |
-| `-p, --projectId=<value>` | Forest project ID. |
-| `-t, --to=<value>` | (required) Name of the team to copy the layout to (its layout is overwritten). |
-| `--force` | Skip the confirmation prompt. |
-
diff --git a/reference/cli/users-edit.mdx b/reference/cli/users-edit.mdx
new file mode 100644
index 0000000..1b5562d
--- /dev/null
+++ b/reference/cli/users-edit.mdx
@@ -0,0 +1,26 @@
+---
+title: forest users:edit
+description: "Edit a user's role, team(s) or permission level"
+---
+
+# forest users:edit
+
+Edit a user's role, team(s) or permission level.
+
+## Usage
+
+```bash
+forest users:edit [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --email=<value>` | (required) Email of the user to edit. |
+| `-f, --force` | Skip the confirmation prompt when teams would be removed. |
+| `-l, --permission-level=<option>` | New permission level. <options: admin\|editor\|user\|developer\|manager> |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-r, --role=<value>` | New role name to assign. |
+| `-t, --team=<value>...` | Team name to set for this project. Repeatable; this REPLACES the user’s current team set on the project. |
+
diff --git a/reference/cli/users-invite.mdx b/reference/cli/users-invite.mdx
new file mode 100644
index 0000000..31ca8e9
--- /dev/null
+++ b/reference/cli/users-invite.mdx
@@ -0,0 +1,26 @@
+---
+title: forest users:invite
+description: "Invite users to a project"
+---
+
+# forest users:invite
+
+Invite users to a project.
+
+## Usage
+
+```bash
+forest users:invite [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-e, --email=<value>...` | (required) Email of the user to invite (repeat the flag to invite several users). |
+| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
+| `-l, --permission-level=<option>` | (required) Permission level of the invited users. <options: admin\|editor\|user\|developer\|manager> |
+| `-p, --projectId=<value>` | Forest project ID. |
+| `-r, --role=<value>` | Role name to assign (prompted if omitted and several exist). |
+| `-t, --team=<value>` | Team name to add the invited users to (prompted if omitted and several exist). |
+
diff --git a/reference/cli/users-list.mdx b/reference/cli/users-list.mdx
new file mode 100644
index 0000000..fc40610
--- /dev/null
+++ b/reference/cli/users-list.mdx
@@ -0,0 +1,22 @@
+---
+title: forest users:list
+description: "List all users of a project"
+---
+
+# forest users:list
+
+List all users of a project.
+
+## Usage
+
+```bash
+forest users:list [options]
+```
+
+## Options
+
+| Option | Description |
+|---|---|
+| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
+| `-p, --projectId=<value>` | Forest project ID. |
+
diff --git a/reference/cli/users.mdx b/reference/cli/users.mdx
deleted file mode 100644
index 2c48b0f..0000000
--- a/reference/cli/users.mdx
+++ /dev/null
@@ -1,56 +0,0 @@
----
-title: Users
-description: "List, invite, and edit the users of a project."
----
-
-# Users
-
-List, invite, and edit the users of a project.
-
-## forest users:list
-
-List all users of a project.
-
-```bash
-forest users:list [options]
-```
-
-| Option | Description |
-|---|---|
-| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
-| `-p, --projectId=<value>` | Forest project ID. |
-
-## forest users:invite
-
-Invite users to a project.
-
-```bash
-forest users:invite [options]
-```
-
-| Option | Description |
-|---|---|
-| `-e, --email=<value>...` | (required) Email of the user to invite (repeat the flag to invite several users). |
-| `-f, --format=<option>` | [default: table] Output format. <options: table\|json> |
-| `-l, --permission-level=<option>` | (required) Permission level of the invited users. <options: admin\|editor\|user\|developer\|manager> |
-| `-p, --projectId=<value>` | Forest project ID. |
-| `-r, --role=<value>` | Role name to assign (prompted if omitted and several exist). |
-| `-t, --team=<value>` | Team name to add the invited users to (prompted if omitted and several exist). |
-
-## forest users:edit
-
-Edit a user's role, team(s) or permission level.
-
-```bash
-forest users:edit [options]
-```
-
-| Option | Description |
-|---|---|
-| `-e, --email=<value>` | (required) Email of the user to edit. |
-| `-f, --force` | Skip the confirmation prompt when teams would be removed. |
-| `-l, --permission-level=<option>` | New permission level. <options: admin\|editor\|user\|developer\|manager> |
-| `-p, --projectId=<value>` | Forest project ID. |
-| `-r, --role=<value>` | New role name to assign. |
-| `-t, --team=<value>...` | Team name to set for this project. Repeatable; this REPLACES the user’s current team set on the project. |
-
diff --git a/reference/cli/workflows.mdx b/reference/cli/workflow-apply.mdx
similarity index 80%
rename from reference/cli/workflows.mdx
rename to reference/cli/workflow-apply.mdx
index db7bd95..b4999d0 100644
--- a/reference/cli/workflows.mdx
+++ b/reference/cli/workflow-apply.mdx
@@ -1,24 +1,26 @@
 ---
-title: Workflows
-description: "Author workflows as code from a JSON steps spec."
+title: forest workflow:apply
+description: "Create or update a workflow from a JSON steps spec (compiles to BPMN and uploads it)"
 ---
 
-# Workflows
-
-Author workflows as code from a JSON `steps` spec.
-
-## forest workflow:apply
+# forest workflow:apply
 
 Create or update a workflow from a JSON steps spec (compiles to BPMN and uploads it). Reading the spec from stdin disables prompts: pass -p/-e/-t and --force explicitly.
 
+## Usage
+
 ```bash
 forest workflow:apply [FILE] [options]
 ```
 
+## Arguments
+
 | Argument | Description |
 |---|---|
 | `FILE` | JSON workflow spec ({ name, collection, steps, id?, segments?, position?, start?, version? }). "-" or omit to read stdin. |
 
+## Options
+
 | Option | Description |
 |---|---|
 | `-e, --env=<value>` | Environment name or id. |

From 62dc819a0c5c867a26710472214854272b592b34 Mon Sep 17 00:00:00 2001
From: Gautier Delache <gautierd@forestadmin.com>
Date: Fri, 17 Jul 2026 14:35:37 +0200
Subject: [PATCH 4/4] docs(ai): add AI & MCP tab (Claude Code plugin + Forest
 MCP server)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New top-level tab documenting how to drive Forest with AI:
- Overview — the two ways in (Claude Code plugin vs MCP) + when to use which
- Claude Code — the forest plugin: install, the 4 skills (/forest:onboard/layout/workflows/management), example prompts, the vibe-coding loop
- MCP — the Forest MCP server: read/write/act/understand, governed by permissions

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ai/claude-code.mdx | 94 ++++++++++++++++++++++++++++++++++++++++++++++
 ai/mcp.mdx         | 53 ++++++++++++++++++++++++++
 ai/overview.mdx    | 40 ++++++++++++++++++++
 docs.json          | 13 +++++++
 4 files changed, 200 insertions(+)
 create mode 100644 ai/claude-code.mdx
 create mode 100644 ai/mcp.mdx
 create mode 100644 ai/overview.mdx

diff --git a/ai/claude-code.mdx b/ai/claude-code.mdx
new file mode 100644
index 0000000..9c03f50
--- /dev/null
+++ b/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>
diff --git a/ai/mcp.mdx b/ai/mcp.mdx
new file mode 100644
index 0000000..57246ea
--- /dev/null
+++ b/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) |
diff --git a/ai/overview.mdx b/ai/overview.mdx
new file mode 100644
index 0000000..d42bff3
--- /dev/null
+++ b/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>
diff --git a/docs.json b/docs.json
index a73bc1a..7fe7d3e 100644
--- a/docs.json
+++ b/docs.json
@@ -304,6 +304,19 @@
           }
         ]
       },
+      {
+        "tab": "AI & MCP",
+        "groups": [
+          {
+            "group": "AI & MCP",
+            "pages": [
+              "ai/overview",
+              "ai/claude-code",
+              "ai/mcp"
+            ]
+          }
+        ]
+      },
       {
         "tab": "Reference",
         "groups": [