fimo 0.15.0 → 0.16.0-staging.2

package/assets/content-templates/forms/react.eta

@@ -78,7 +78,7 @@ const fileFieldKeys = Object.entries(form.fields)
 
 import { z } from "zod";
 
-export const FORM_ID = <%= quote(form.id ?? 'undefined') %>;
+export const FORM_ID = <%= form.id ? quote(form.id) : 'undefined' %>;
 
 export const <%= form.pascal %>Schema = z.object({
 <% Object.entries(form.fields).forEach(([key, field]) => { -%>
@@ -154,8 +154,8 @@ export async function submit<%= form.pascal %>(data: <%= form.pascal %>Data): Pr
   status: number;
   errors?: Record<string, string>;
 }> {
-  if (!FORM_ID || FORM_ID === "undefined") {
-    throw new Error(`Form "${FORM_ID || "unknown"}" has not been pushed. Run fimo forms push first.`);
+  if (!FORM_ID) {
+    throw new Error(<%= quote(`Form "${form.name}" has not been pushed. Run fimo forms push first.`) %>);
   }
 
 <% if (hasFileFields) { -%>

package/assets/skills/fimo-cli/SKILL.md

@@ -2,7 +2,7 @@
 name: fimo-cli
 description: >-
   Use the `fimo` CLI to create or operate a Fimo project: content, forms,
-  media, labels/locales, deploys, environments, domains, analytics,
+  media, labels/locales, deploys, Branches, Environments, domains, analytics,
   integrations, Fimo agents, collaboration, accounts, and credits. Also use
   for AI agent or MCP setup and confirmed Fimo platform blockers.
 ---
@@ -42,9 +42,9 @@ Pretty output may hide URLs behind clickable labels. Agents should use `--json`
 
 A Fimo project is identified by `.fimo/project.json`, written by `fimo init`. This file connects the local directory to the remote Fimo project. **Never edit it manually.** Most CLI commands find it by walking up from the cwd.
 
-## Critical: commands target the env of the current git branch
+## Critical: commands target the Branch matching the current git branch
 
-A project can have multiple **envs** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Project-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the env of the **current git branch**, and print a one-line banner saying which one. New projects start on `main`. Override for a single command with the global `--env <name>` flag; never edit the link file to switch. The full git-shaped workflow (`branch` / `checkout` / `switch` / `pull` / `diff` / `merge` / `status` / `publish`) lives in `references/branches.md`.
+A project can have multiple **Branches** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Project-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the Branch matching the **current git branch**, and print a one-line banner saying which one. New projects start on `main`. Override for a single command with the canonical `--branch <name>` flag; the legacy `--env <name>` spelling remains a compatibility alias. Never edit the link file to switch. The full git-shaped workflow (`branch` / `checkout` / `switch` / `pull` / `diff` / `merge` / `status` / `publish`) lives in `references/branches.md`.
 
 ## Quick Start
 
@@ -58,7 +58,7 @@ fimo clone                                     # interactively choose an existin
 cd my-site                                     # then load skills on demand: fimo skills get fimo-code
 pnpm dev                                       # run the app locally (use the project's PM: pnpm/npm run/yarn/bun) — your iteration loop
 fimo credits                                   # inspect the owning org's AI credit balance (read-only)
-fimo history list                              # inspect this environment's restore points
+fimo history list                              # inspect this Branch's restore points
 fimo validate                                  # run all checks + codegen; fails on missing DB labels
 fimo deploy                                    # ON-DEMAND: hosted preview / shareable link (runs validate internally)
 fimo deploy --publish                          # ON-DEMAND: publish live (only when the developer says "ship it")
@@ -82,7 +82,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Enable locales / configure default locale / integrate an existing locale system" → `references/locales.md` **+ run `fimo skills get fimo-code --ref locales` and load the detected framework locale reference**
 - "What's in this project / show the project structure / describe the project / what schemas does it have / how many routes / project tree / show me what's here" → `references/describe.md`
 - "Deploy / publish / go live / push my changes" → `references/deploy.md`
-- "Get the preview URL / open the preview / what's the URL for this env / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.md`
+- "Get the preview URL / open the preview / what's the URL for this Branch / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.md`
 - "Schedule a command / cron / nightly publish / recurring checks / `fimo schedules`" → `references/schedules.md`
 - "Set env vars / configure API keys / add project secrets / local `.env.local` / `fimo vars` / `fimo secrets`" → `references/project-vars-and-secrets.md`
 - "React to form submissions / publish changes / agent runs / analytics reports / media activity / send events to Resend, Slack, GitHub, Zapier, or an HTTP endpoint / configure or debug outbound webhooks" → `references/webhooks.md`
@@ -90,14 +90,14 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Firecrawl / scrape a public website / competitor research / agent web research" → `references/integrations.md` **+ load `references/integrations/firecrawl.md`**
 - "Check credits / credit balance / can I keep using AI / billing credits / running low / how many credits are left" → `references/credits.md`
 - "List history / create a restore point / recover content and code / restore a previous version / snapshot usage or retention" → `references/history.md`
-- "Create a branch / feature environment / new env / switch envs / merge envs / diff two envs / env status / what changed on this branch / sync from parent / cut a release / tag a version / go to prod" → `references/branches.md`
+- "Create a Branch / feature Branch / switch Branches / merge Branches / diff two Branches / Branch status / what changed on this Branch / sync from parent / cut a release / tag a version / go to prod" → `references/branches.md`
 - "List my projects / clone an existing project locally / check out a project / delete this project / unpublish / rename the project / manage projects across the org" → `references/projects.md`
 - "Migrate an existing Webflow / Framer / Squarespace / Wix / Carrd site from only a published URL" → load the `fimo-migration` skill and start with `fimo migrate <url> [dir]` to prepare the agent-ready migration draft
 - "Migrate from an exported project, source repository, Webflow code export plus CMS CSVs, Framer CMS CSVs, Squarespace XML/CSV, Wix CSVs, Carrd/static export, or downloaded site files" → load the `fimo-migration` skill and use the source repo/export as the migration source of truth
 - "How do AI agents read my site / markdown for agents" → `references/deploy.md`
 - "Modify the URL of the website / change my project's address / connect a custom domain (e.g. blog.example.com) / rename the Fimo-provided `*.fimo.site` subdomain / buy a new domain through Fimo / set up a domain" → `references/domains.md`
 - "Invite a collaborator / add Marc / share with client" → `references/invite.md`
-- "Login / log out / who am I / switch organization" → `references/account.md` — note: switching **org** is `fimo orgs switch`; bare `fimo switch` switches **env** (see `references/branches.md`)
+- "Login / log out / who am I / switch organization" → `references/account.md` — note: switching **org** is `fimo orgs switch`; bare `fimo switch` changes the active **Fimo Branch** (see `references/branches.md`)
 - "Create / scaffold / run / validate an agent / agent bundle / wire or enable its triggers / list agent templates / view agent runs, reports, or logs (`fimo agents *`)" → `references/agents.md`
 - "Install Fimo for my agent / fimo skills install / set up Claude Code, Codex, or Cursor for Fimo" → `references/agent-setup.md`
 - "Connect an agent to a Fimo project through MCP / configure `fimo mcp` / expose Fimo tools to a local MCP client" → `references/mcp.md`
@@ -119,7 +119,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Optional, outside new-project onboarding (its first preview already warms the sandbox), if you already know a deploy is coming** → warm the sandbox early with `fimo deploy -m "chore: init" &` in the background so the one-time ~15-30s provision + dep install happens while you work and the real deploy lands warm (~4-10s). This is a perf optimization, not a requirement. See `references/deploy.md` § Warm the sandbox early in a session.
 - **Iterative code-only deploys** → once you are deploying, `fimo deploy --no-restart` skips the sandbox dev-server restart on HMR-safe edits. See `references/deploy.md` § Skipping the dev-server restart for when it's safe.
 - **You need the current preview URL but haven't changed code** (opening it, screenshotting it, handing it to another tool, the previous URL expired) → `fimo preview url`, never a no-op `fimo deploy`. See `references/preview.md`.
-- **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature env: `fimo checkout -b <name>` gives an isolated branch + DB + preview. Deploy previews there, then `fimo merge` it back and `fimo publish`. See `references/branches.md`.
+- **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature Branch: `fimo checkout -b <name>` gives an isolated Branch + DB + preview. Deploy previews there, then `fimo merge` it back and `fimo publish`. See `references/branches.md`.
 - **After completing or safely preserving the user's main work, when a confirmed Fimo platform failure still materially blocks the task after one safe recovery attempt, or a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround** → use the built-in `supportReport` tool. Do not wait for the user to ask and do not stop after only describing the gap. See `references/support.md`.
 - **After the first successful `fimo deploy`** → suggest `fimo invite` if the project involves multiple people. Typical roles: `edit` for developers/content editors, `view` or `comment` for clients/stakeholders, `full` for project leads. See `references/invite.md`.
 - **When the user wants to modify the URL of their website** → walk through `references/domains.md`. The CLI surface covers renaming the Fimo-provided subdomain (`fimo domains rename-default`, free), attaching a domain they already own (`fimo domains add`, Premium), and buying a new domain through Fimo (`fimo domains buy`, Premium). The auto-generated default URL on every project is a fallback, not a final choice — proactively offer this after `fimo deploy --publish` if the user mentioned a real brand or domain.

package/assets/skills/fimo-cli/references/account.md

@@ -26,7 +26,7 @@ fimo orgs switch                     # interactive picker to change the active o
 fimo orgs switch --org <id-or-slug>  # explicit switch (required in non-TTY)
 ```
 
-> **`fimo switch` is NOT the org switcher.** Bare `fimo switch <name>` is an alias for `fimo checkout` — it switches the active **env** (git branch). Org switching is `fimo orgs switch`. See `references/branches.md`.
+> **`fimo switch` is NOT the org switcher.** Bare `fimo switch <name>` is an alias for `fimo checkout` — it changes the active **Fimo Branch**. A Fimo Branch keeps its code, database, sandbox, content, and preview together. Org switching is `fimo orgs switch`. See `references/branches.md`.
 
 ## Inviting collaborators
 

package/assets/skills/fimo-cli/references/agents.md

@@ -7,7 +7,7 @@ The `fimo agents` namespace authors and operates **agent bundles** — multi-fil
 The namespace splits cleanly in two:
 
 - **Bundle authoring** — `create`, `list-templates`, `list`, `validate`, `secrets add/remove/list`. Local config editing, no API call except the project-level validation path. Operates on the files under `.fimo/agents/<name>/` (or root `agents/<name>/` for legacy projects).
-- **Cloud ops** — `run`, `runs`, `report`, `logs`. Env-aware, talk to the server. Default `--env` is `main`; `--project` defaults to the linked project in `.fimo/project.json` or legacy `.fimo.settings.json`.
+- **Cloud ops** — `run`, `runs`, `report`, `logs`. Branch-aware, talk to the server. Default `--branch` is `main`; the legacy `--env` spelling remains an alias. `--project` defaults to the linked project in `.fimo/project.json` or legacy `.fimo.settings.json`.
 
 The bundle lives in **git** (`.fimo/agents/<name>/`, or legacy root `agents/<name>/`), not the database. The DB only mirrors what `config.yaml` declares on `main` (which triggers are wired) plus **run sessions**. So the bundle reaches the server through `fimo deploy` — and that push to `main` is also what wires its triggers. There is no activate command: deploying IS the enablement act, and removing a trigger from `config.yaml` tears it down on the next deploy.
 
@@ -99,23 +99,23 @@ Example for a content editor that can read and update entries but cannot change
 - cms:write
 ```
 
-## Cloud ops (env-aware)
+## Cloud ops (Branch-aware)
 
 ```bash
-fimo agents run <name> [--env <env>] [--project <id>] [--skip-drift-check] [-C <dir>]
-fimo agents runs <name> [--limit <n>] [--env <env>] [--project <id>] [-C <dir>]
-fimo agents report <name> [--session <id>] [--env <env>] [--project <id>] [-C <dir>]
+fimo agents run <name> [--branch <branch>] [--project <id>] [--skip-drift-check] [-C <dir>]
+fimo agents runs <name> [--limit <n>] [--branch <branch>] [--project <id>] [-C <dir>]
+fimo agents report <name> [--session <id>] [--branch <branch>] [--project <id>] [-C <dir>]
 fimo agents logs <name> [--session <id>] [--project <id>] [-C <dir>]
 ```
 
-- **`run <name>`** — fire the agent's `manual` trigger on the server; prints a `sessionId` on success. Skips with `no-manual-trigger` when `config.yaml` declares none, or `trigger-not-wired` when the push-to-main sync recorded the trigger but refused to wire it (see the wiring note below). **Pre-flight drift check**: if `.fimo/agents/<name>/` (or the legacy root bundle) has uncommitted git changes, the command refuses — the server would dispatch the _deployed_ version, so deploy first. Pass `--skip-drift-check` to dispatch the deployed bundle anyway. Defaults `--env` to `main`.
-- **`runs <name>`** — list past run sessions for the agent in a compact table (id, started, duration, status, trigger, env, cost). Default `--limit 20`; `--env` filters to one env.
-- **`report <name>`** — print a run's **report**: the agent's final message, captured when the run finishes (for a read-only agent like `seo-audit` this _is_ the audit; for a write agent it's a "what I changed" summary). With no `--session`, the most recent run for `<name>` is used (combine with `--env` to scope); `--session <id>` targets a specific run. Output is raw markdown, so it stays readable in the terminal and pipes cleanly (e.g. `fimo agents report seo-audit | glow`). If the run hasn't finished, or produced no message, it says so (and shows the stop reason when there is one). This is the command to read what a run actually produced — see the `logs` note below.
+- **`run <name>`** — fire the agent's `manual` trigger on the server; prints a `sessionId` on success. Skips with `no-manual-trigger` when `config.yaml` declares none, or `trigger-not-wired` when the push-to-main sync recorded the trigger but refused to wire it (see the wiring note below). **Pre-flight drift check**: if `.fimo/agents/<name>/` (or the legacy root bundle) has uncommitted git changes, the command refuses — the server would dispatch the _deployed_ version, so deploy first. Pass `--skip-drift-check` to dispatch the deployed bundle anyway. Defaults `--branch` to `main`; legacy `--env` remains an alias.
+- **`runs <name>`** — list past run sessions for the agent in a compact table (id, started, duration, status, trigger, Branch, cost). Default `--limit 20`; `--branch` filters to one Branch. The response's legacy `env` field is still present for API compatibility.
+- **`report <name>`** — print a run's **report**: the agent's final message, captured when the run finishes (for a read-only agent like `seo-audit` this _is_ the audit; for a write agent it's a "what I changed" summary). With no `--session`, the most recent run for `<name>` is used (combine with `--branch` to scope); `--session <id>` targets a specific run. Output is raw markdown, so it stays readable in the terminal and pipes cleanly (e.g. `fimo agents report seo-audit | glow`). If the run hasn't finished, or produced no message, it says so (and shows the stop reason when there is one). This is the command to read what a run actually produced — see the `logs` note below.
 - **`logs <name>`** — stream a run's log (defaults to the latest session; `--session <id>` targets one). **Note:** the log-streaming endpoint is still a server-side stub at time of writing — the command prints a placeholder rather than real log lines. To read a finished run's output today, use `report`.
 
 ## How triggers get wired
 
-Agents are not env-scoped: they belong to the project, are read from `main`, and their triggers are global. A branch env has no agents of its own — Studio's agents view shows main's agents whichever env you are on, and a bundle sitting only on a feature branch appears nowhere until it reaches main.
+Agents are not Branch-scoped: they belong to the project, are read from `main`, and their triggers are global. A Branch has no agents of its own — Studio's agents view shows main's agents whichever Branch you are on, and a bundle sitting only on a feature Branch appears nowhere until it reaches main.
 
 Pushing `.fimo/agents/<name>/config.yaml` (or a legacy root bundle) to `main` is the whole enablement act — `fimo deploy` does it. The server reconciles the file into its trigger rows on every push: a `schedule` trigger gets a cron, a `webhook` trigger gets its path, and `manual` becomes runnable. Removing a trigger from the file deletes it (cron torn down, path released) on the next deploy; deleting the agent's directory removes the whole deployment.
 

package/assets/skills/fimo-cli/references/branches.md

@@ -1,48 +1,49 @@
-# Envs & branches (git-shaped workflow)
+# Branches (git-shaped workflow)
 
-> **Beta:** Branch environments are still in beta. The CLI surface is available for early workflows, but not every command or cross-surface merge path is guaranteed to work reliably yet.
+> **Beta:** Branches are still in beta. The CLI surface is available for early workflows, but not every command or cross-surface merge path is guaranteed to work reliably yet.
 
-A Fimo **env** is a multi-surface clone of the project: a git branch **plus** its own Neon DB branch, sandbox, preview URL, and R2 asset prefix. The CLI mirrors `git` command shapes so the workflow transfers directly — same verbs, multi-surface semantics.
+A Fimo **Branch** is a multi-surface clone of the project: a git branch **plus** its own Neon DB branch, sandbox, preview URL, and R2 asset prefix. The CLI mirrors `git` command shapes so the workflow transfers directly — same verbs, multi-surface semantics. In Project Settings, an **Environment** is a grouping policy such as Production or Preview; it is not this Branch-backed clone.
 
-Every project starts with one env: `main`. You create more for feature work, deploy previews per-env, then merge back and publish.
+Every project starts with one Branch: `main`. You create more for feature work, deploy previews per Branch, then merge back and publish.
 
-## The env model — how every command picks its target
+## The Branch model — how every command picks its target
 
-**This is the single most important concept: project-scoped commands target the env of the _current git branch_.** When you're on git branch `feat/seo`, `fimo deploy`, `fimo status`, `fimo entries list`, etc. all operate on the `feat/seo` env's DB / sandbox / preview. The CLI prints a one-line stderr banner telling you which env it resolved.
+**This is the single most important concept: project-scoped commands target the Branch matching the _current git branch_.** When you're on git branch `feat/seo`, `fimo deploy`, `fimo status`, `fimo entries list`, etc. all operate on the `feat/seo` Branch's DB / sandbox / preview. The CLI prints a one-line stderr banner telling you which Branch it resolved.
 
 ```bash
-fimo --env <name> <command>     # peek at another env for one command (does not switch)
+fimo --branch <name> <command>  # peek at another Branch for one command (does not switch)
 ```
 
-- **`--env <name>`** is a global override. `fimo --env main status` inspects `main` while you stay checked out on your feature branch.
+- **`--branch <name>`** is the canonical global override. `fimo --branch main status` inspects `main` while you stay checked out on your feature Branch.
+- **`--env <name>`** remains a compatibility alias for `--branch`; it still carries the legacy `env` wire name.
 - Git-changing commands use the current branch; cross-branch status only reports the mismatch.
-- If the branch maps to no env, the CLI errors with a hint (`fimo branch` to list, `fimo branch <name>` to create) rather than guessing.
-- **`main`** is the default env and cannot be deleted.
-- **`release/*`** envs are **read-only** — they're tags produced by `fimo publish`, not branches you push to. `fimo deploy` refuses them.
+- If the git branch maps to no Fimo Branch, the CLI errors with a hint (`fimo branch` to list, `fimo branch <name>` to create) rather than guessing.
+- **`main`** is the default Branch and cannot be deleted.
+- **`release/*`** Branches are **read-only** — they're tags produced by `fimo publish`, not branches you push to. `fimo deploy` refuses them.
 - **`prod`** is protected: it cannot be created, forked from, checked out, or deleted. It's updated by publishing, never by pushing.
 
 ## Commands
 
-| Command                 | git analogue        | What it does                                                                                                                                                                     |
-| ----------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fimo branch`           | `git branch`        | List envs (current marked `*`). `-v` adds preview URLs + deleted envs.                                                                                                           |
-| `fimo branch <name>`    | `git branch <name>` | Create an env off the current one. `--from <env>` forks from a different parent. Provisions DB + sandbox + preview + R2 prefix.                                                  |
-| `fimo branch -d <name>` | `git branch -d`     | Delete an env — tears down its sandbox, Neon branch, and R2 prefix. Refuses `main` and `prod`.                                                                                   |
-| `fimo checkout <name>`  | `git checkout`      | Switch to an env (checks out the matching git branch; the app derives its env from that branch at startup). `-b` creates + switches; `--from <env>` sets the parent (with `-b`). |
-| `fimo switch <name>`    | `git switch`        | Switch to an existing env. Takes only `<name>` (no `-b`/`--from`) — use `fimo checkout -b` to create + switch.                                                                   |
-| `fimo pull`             | `git pull`          | Sync the current env's data plane (DB/assets) down from its parent. `--from <env>` syncs from an explicit ancestor.                                                              |
-| `fimo diff [from] [to]` | `git diff`          | Two-env diff across all surfaces. Defaults `from` = current env, `to` = `main`. `--surface <name>` limits to one; `--json`; `--no-color`.                                        |
-| `fimo status`           | `git status`        | Multi-surface status for the current env vs its parent. See below.                                                                                                               |
-| `fimo merge <from>`     | `git merge`         | Merge another env into the current one (multi-surface, atomic, interactive conflict resolver). See below.                                                                        |
-| `fimo publish`          | —                   | Tag `main@HEAD` as `release/<version>` and trigger the prod swap. See "Publishing" below.                                                                                        |
+| Command                 | git analogue        | What it does                                                                                                                                                                 |
+| ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fimo branch`           | `git branch`        | List Branches (current marked `*`). `-v` adds preview URLs + deleted Branches.                                                                                               |
+| `fimo branch <name>`    | `git branch <name>` | Create a Branch off the current one. `--from <branch>` forks from a different parent. Provisions DB + sandbox + preview + R2 prefix.                                         |
+| `fimo branch -d <name>` | `git branch -d`     | Delete a Branch — tears down its sandbox, Neon branch, and R2 prefix. Refuses `main` and `prod`.                                                                             |
+| `fimo checkout <name>`  | `git checkout`      | Switch to a Branch (checks out the matching git branch; the app derives its Branch from that branch at startup). `-b` creates + switches; `--from <branch>` sets the parent. |
+| `fimo switch <name>`    | `git switch`        | Switch to an existing Branch. Takes only `<name>` (no `-b`/`--from`) — use `fimo checkout -b` to create + switch.                                                            |
+| `fimo pull`             | `git pull`          | Sync the current Branch's data plane (DB/assets) down from its parent. `--from <branch>` syncs from an explicit ancestor.                                                    |
+| `fimo diff [from] [to]` | `git diff`          | Two-Branch diff across all surfaces. Defaults `from` = current Branch, `to` = `main`. `--surface <name>` limits to one; `--json`; `--no-color`.                              |
+| `fimo status`           | `git status`        | Multi-surface status for the current Branch vs its parent. See below.                                                                                                        |
+| `fimo merge <from>`     | `git merge`         | Merge another Branch into the current one (multi-surface, atomic, interactive conflict resolver). See below.                                                                 |
+| `fimo publish`          | —                   | Tag `main@HEAD` as `release/<version>` and trigger the prod swap. See "Publishing" below.                                                                                    |
 
-All of these accept the global `--env` override. `diff`, `status`, `merge`, and `publish` additionally accept `-C, --cwd <dir>` to point at a project directory.
+All of these accept the global `--branch` override; legacy `--env` remains an alias. `diff`, `status`, `merge`, and `publish` additionally accept `-C, --cwd <dir>` to point at a project directory.
 
-> **`fimo switch` is the ENV switcher, not the org switcher.** To change your active organization, use `fimo orgs switch` — see `references/account.md`.
+> **`fimo switch` changes the active Fimo Branch, not the org.** A Fimo Branch keeps its code, database, sandbox, content, and preview together. To change your active organization, use `fimo orgs switch` — see `references/account.md`.
 
 ## The 6 surfaces
 
-`status`, `diff`, and `merge` all reason over the same per-env surfaces, in this order:
+`status`, `diff`, and `merge` all reason over the same per-Branch surfaces, in this order:
 
 `code` · `schemas` · `content` · `translations` · `assets` · `forms`
 
@@ -51,25 +52,25 @@ All of these accept the global `--env` override. `diff`, `status`, `merge`, and
 ## Typical PR-style flow
 
 ```bash
-fimo checkout -b feat/seo        # branch off main: git branch + env provisioned
+fimo checkout -b feat/seo        # branch off main: git branch + Branch provisioned
 # …generate / edit code, schemas, content, translations…
-fimo deploy -m "feat: seo pass"  # deploy a preview of the feat/seo env
+fimo deploy -m "feat: seo pass"  # deploy a preview of the feat/seo Branch
 fimo preview url                 # fresh URL to open / screenshot the feat/seo preview
 fimo status                      # see what changed vs main, surface by surface
 fimo checkout main               # back to main
-fimo merge feat/seo              # merge the env back into main (resolve conflicts)
+fimo merge feat/seo              # merge the Branch back into main (resolve conflicts)
 fimo publish --version 1.4.0     # tag a release + prod swap
-fimo branch -d feat/seo          # tear down the feature env
+fimo branch -d feat/seo          # tear down the feature Branch
 ```
 
 ## `fimo status`
 
-The showcase command — a unified, color-coded report of what's changed on the current env, grouped by surface, with per-surface counts.
+The showcase command — a unified, color-coded report of what's changed on the current Branch, grouped by surface, with per-surface counts.
 
 ```bash
-fimo status                  # full report, current env vs parent (or main)
+fimo status                  # full report, current Branch vs parent (or main)
 fimo status --short          # one line per surface
-fimo status --vs main        # compare against an explicit env
+fimo status --vs main        # compare against an explicit Branch
 fimo status --content        # only the content surface (combine flags freely)
 fimo status --json           # machine-readable
 ```
@@ -80,7 +81,7 @@ fimo status --json           # machine-readable
 ## `fimo merge`
 
 ```bash
-fimo merge feat/seo                   # merge feat/seo into the current env
+fimo merge feat/seo                   # merge feat/seo into the current Branch
 fimo merge feat/seo -y                # non-interactive: parent-wins on every conflict
 fimo merge feat/seo --allow-direct-merge   # override the "don't merge straight onto main" gate
 ```
@@ -90,7 +91,7 @@ fimo merge feat/seo --allow-direct-merge   # override the "don't merge straight
 
 ## `fimo pull`
 
-Syncs the current env's data plane from its parent (or `--from <ancestor>`). Conflicts currently resolve **parent-wins** automatically (a future release adds per-row picks). Use it to refresh a stale feature env with the latest `main` content/schema state.
+Syncs the current Branch's data plane from its parent (or `--from <ancestor>`). Conflicts currently resolve **parent-wins** automatically (a future release adds per-row picks). Use it to refresh a stale feature Branch with the latest `main` content/schema state.
 
 ## Publishing — `fimo publish` vs `fimo deploy --publish`
 
@@ -103,8 +104,8 @@ Use `fimo publish` for versioned prod releases; use `fimo deploy --publish` for
 
 ## Anti-patterns
 
-- **Using `git checkout -b` instead of `fimo checkout -b`** — raw git creates the branch but **not** the env's DB / sandbox / preview. Always use `fimo` for branch operations so resources are provisioned atomically. (Running `fimo branch <name>` after the fact provisions them.) The running app itself follows the git branch either way.
+- **Using `git checkout -b` instead of `fimo checkout -b`** — raw git creates the branch but **not** the Branch's DB / sandbox / preview. Always use `fimo` for Branch operations so resources are provisioned atomically. (Running `fimo branch <name>` after the fact provisions them.) The running app itself follows the git branch either way.
 - **Hardcoding the tenant API URL** — the app derives it from the git branch and `.fimo/project.json`. Set `VITE_API_URL` / `NEXT_PUBLIC_FIMO_API_URL` yourself only as a deliberate override (e.g. a local API); it then wins over derivation on every branch.
 - **Trying to push to or delete `prod` / `release/*`** — these are read-only/protected. Publish to update prod; never push.
 - **`fimo merge` straight onto `main` as a habit** — it's gated for a reason. Merge on a branch, then publish.
-- **Confusing `fimo switch` (env) with `fimo orgs switch` (org).**
+- **Confusing `fimo switch` (Branch) with `fimo orgs switch` (org).**

package/assets/skills/fimo-cli/references/credits.md

@@ -9,7 +9,7 @@ fimo credits --project <project-id>
 fimo credits -C ./path/to/project
 ```
 
-This command is **project-scoped but not env-scoped**. It does not depend on the current git branch or `--env`, because credits belong to the project's organization, not to a branch/env.
+This command is **project-scoped but not Branch-scoped**. It does not depend on the current git branch or `--branch`, because credits belong to the project's organization, not to a Branch.
 
 ## Pretty Output
 

package/assets/skills/fimo-cli/references/deploy.md

@@ -1,10 +1,10 @@
 # Deploy pipeline
 
-**`fimo deploy` is on-demand, not the working loop and not a required final step.** The loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), iterate with the developer, and let live reload show changes. Reach for `fimo deploy` only when the developer wants a **hosted preview**, a **shareable link**, or to **go live** — and only on their signal. New-project onboarding counts as the signal for its single automatic first preview deploy (see `references/init.md` § Create the first hosted preview). It commits everything, pushes to the current env's branch, and round-trips that env's sandbox (install + restart); it's a milestone command, not a save step. Batch related edits into one deploy; never deploy after every change.
+**`fimo deploy` is on-demand, not the working loop and not a required final step.** The loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), iterate with the developer, and let live reload show changes. Reach for `fimo deploy` only when the developer wants a **hosted preview**, a **shareable link**, or to **go live** — and only on their signal. New-project onboarding counts as the signal for its single automatic first preview deploy (see `references/init.md` § Create the first hosted preview). It commits everything, pushes to the current Branch, and round-trips that Branch's sandbox (install + restart); it's a milestone command, not a save step. Batch related edits into one deploy; never deploy after every change.
 
 > **Local vs hosted.** The local dev server is localhost only. The Fimo **dashboard preview** and the **shareable preview URL** are served by the deployed sandbox — so if the developer wants to see the site in the dashboard or send someone a link, that requires a `fimo deploy`.
 
-`fimo deploy` uses the current branch. New projects start on `main`; `release/*` is read-only, and `--publish` only runs from `main`. See `references/branches.md` for the multi-env workflow.
+`fimo deploy` uses the current Branch. New projects start on `main`; `release/*` is read-only, and `--publish` only runs from `main`. See `references/branches.md` for the multi-Branch workflow.
 
 Before deploying, Fimo fast-forwards a clean checkout that is behind and stops on dirty-behind or diverged branches. This syncs the whole branch, including config commits from Studio or locale commands.
 
@@ -19,7 +19,7 @@ fimo deploy --no-restart                     # skip dev-server restart (HMR-safe
 fimo deploy -m "<commit message>" --publish  # also publish a new live version
 ```
 
-- **`fimo deploy`** — commits pending changes, pushes to the current env's branch, syncs that env's preview sandbox, and links to the Preview and Fimo dashboard.
+- **`fimo deploy`** — commits pending changes, pushes to the current Branch, syncs that Branch's preview sandbox, and links to the Preview and Fimo dashboard.
 - **`fimo deploy --publish`** — same as above, then triggers a live publish and prints the live URL. Runs from `main` only. **Only use `--publish` when the user signals "ship it"** — first-time site completion, or an explicit "publish" / "go live" request. Otherwise stick to plain `fimo deploy`. (For a _versioned_ prod release, use `fimo publish` instead — see below.)
 - **`-m`** is the commit message used when there are uncommitted local changes; required in non-interactive shells. Omit if the working tree is already clean.
 - **`--no-restart`** — tells the sandbox to skip the dev-server restart and let Vite HMR pick up the change. Shaves ~3s per deploy. See "Skipping the dev-server restart" below for when it's safe.
@@ -38,12 +38,12 @@ Read these fields from `data`:
 | Field           | Destination                                                 |
 | --------------- | ----------------------------------------------------------- |
 | `preview_url`   | Shareable preview. Its token expires, so do not persist it. |
-| `dashboard_url` | Stable, authenticated Fimo project and environment page.    |
+| `dashboard_url` | Stable, authenticated Fimo project and Branch page.         |
 | `app_url`       | Public live site, returned after a successful `--publish`.  |
 
 When reporting the result, present the raw values as named Markdown links. If no code changed and you only need fresh destinations, use `fimo preview url --json` instead of deploying again.
 
-Public project variables managed with `fimo vars add` and `fimo vars update` are injected into preview/build/deploy environments. Project secrets are not injected into app builds; agents request secrets separately through their own config. See `references/project-vars-and-secrets.md`.
+Public project variables managed with `fimo vars add` and `fimo vars update` are injected into preview/build/deploy runtimes. Project secrets are not injected into app builds; agents request secrets separately through their own config. See `references/project-vars-and-secrets.md`.
 
 ## Framework hosting
 
@@ -123,7 +123,7 @@ curl https://your-site/?format=md                # query param
 Most stale states are caught before deploy changes or commits files. Follow the emitted hint: clean a dirty checkout, or reconcile a diverged branch. A push can still lose a race if the remote advances after preflight:
 
 ```bash
-git pull --rebase fimo <env>   # <env> = the branch you're deploying (e.g. main)
+git pull --rebase fimo <branch>   # <branch> = the Branch you're deploying (e.g. main)
 # fix any conflicts
 fimo deploy
 ```
@@ -132,7 +132,7 @@ fimo deploy
 
 - Source of truth is this git repo.
 - **Never** edit `.fimo/project.json`; it is generated by `fimo init`.
-- Each env deploys to its own branch + preview sandbox; `--publish` and `fimo publish` run from `main` only. See `references/branches.md`.
+- Each Branch deploys to its own preview sandbox; `--publish` and `fimo publish` run from `main` only. See `references/branches.md`.
 
 ## After the first successful deploy
 

package/assets/skills/fimo-cli/references/history.md

@@ -1,8 +1,13 @@
 # Project History
 
-History is scoped to the selected project environment. A restore point records the environment's CMS content and the matching Git commit so code and content can be recovered together.
+History is scoped to the selected project Branch. A restore point records the
+Branch's CMS content and the matching Git commit so code and content can be
+recovered together.
 
-Fimo also creates restore points automatically after a successful deploy, on the destination of a completed environment merge, and after direct content editing has been quiet for 30 seconds. Rapid Studio auto-saves are grouped into one content point.
+Fimo also creates restore points automatically after a successful deploy, on the
+destination of a completed Branch merge, and after direct content editing has
+been quiet for 30 seconds. Rapid Studio auto-saves are grouped into one content
+point.
 
 ```bash
 fimo history list
@@ -13,7 +18,9 @@ fimo history restore <version-id>
 
 Studio chat can run `history list` and `history show`. Create and restore remain available through the standalone CLI and Studio's History page.
 
-Use the global `--env <name>` option to target a different environment. Use `--project <id>` when there is no local `.fimo/project.json`.
+Use the global `--branch <name>` option to target a different Branch. The legacy
+`--env <name>` spelling remains a compatibility alias. Use `--project <id>` when
+there is no local `.fimo/project.json`.
 
 ## Pagination and usage
 
@@ -27,7 +34,7 @@ The list also reports compressed snapshot usage and the current retention period
 
 ## Restore safety
 
-Before replacing code and content, Fimo creates an automatic `restore-safety` point from the environment's current state. Restoring that point is the fast recovery path when the selected result is not what the user expected.
+Before replacing code and content, Fimo creates an automatic `restore-safety` point from the Branch's current state. Restoring that point is the fast recovery path when the selected result is not what the user expected.
 
 Pretty mode asks for confirmation. Agents and other non-interactive callers must pass both `--json` and `--yes`:
 
@@ -37,6 +44,6 @@ fimo --json history restore <version-id> --yes
 
 If another history create, update, delete, or restore is already running, the command fails with `HISTORY_BUSY`. Retry after the active history operation finishes. Do not loop without a delay.
 
-If content or Git restore does not finish cleanly, the command fails with `RESTORE_INCOMPLETE` and names the automatic safety point. Stop active editing, inspect the environment, and retry the restore. Collaborative-editor resync continues in the background after code and content are ready.
+If content or Git restore does not finish cleanly, the command fails with `RESTORE_INCOMPLETE` and names the automatic safety point. Stop active editing, inspect the Branch, and retry the restore. Collaborative-editor resync continues in the background after code and content are ready.
 
-Normal CMS requests and Git pushes do not wait for snapshot creation. Their queued restore-point capture takes the history-operation lock later and retries if another History operation is active. Unsaved collaborative-editor changes are not captured. Avoid starting a restore while someone is actively editing the same environment.
+Normal CMS requests and Git pushes do not wait for snapshot creation. Their queued restore-point capture takes the history-operation lock later and retries if another History operation is active. Unsaved collaborative-editor changes are not captured. Avoid starting a restore while someone is actively editing the same Branch.

package/assets/skills/fimo-cli/references/init.md

@@ -20,7 +20,8 @@ fimo init [dir] [options]
 | `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                              |
 | `--project-id <id>`          | no                            | Set up the named Fimo project: scaffold and push a fresh site when it has no code yet, otherwise clone it.                                                     |
 | `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.             |
-| `--env <name>`               | no                            | Env to check out when linking an existing project (defaults to `main`).                                                                                        |
+| `--branch <name>`            | no                            | Branch to check out when linking an existing project (defaults to `main`).                                                                                     |
+| `--env <name>`               | no                            | Compatibility alias for `--branch <name>`.                                                                                                                     |
 | `--framework <framework>`    | no                            | New-project scaffold: `react-router` (default), `astro`, `nextjs` (App Router), or `sveltekit`. Existing repositories are preserved.                           |
 | `--starter <id>`             | no                            | Opt-in project starter for create-new (currently `fimo-site@1`). It seeds CMS content, labels, a contact form, and manual-only agents. Rejects `--project-id`. |
 | `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                            |
@@ -75,13 +76,16 @@ Each shell includes its framework adapter, hosted-preview connector, and
 content-backed example with static, on-demand, and dynamic routes plus an English default locale;
 the other shells intentionally contain no schema, labels, or designed website.
 After init, load the project rules and `fimo-code` to build the requested site.
+If you replace a shell's code with a site that uses another framework or none,
+fix `runtime.framework` in the same change
+(`fimo-code` → `references/frameworks/hosting.md`).
 The current `fimo-site@1` content starter supports React Router only.
 
 For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for Claude Code, `--agents=cursor` for Cursor, `--agents=codex` for Codex, etc. When the flag is omitted, env-var detection of the invoking harness (e.g. `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT` → claude-code) auto-targets that agent; other agents must be selected explicitly via `--agents`/`-a` or the interactive picker.
 
 ## Setting up a project by ID
 
-Pass `--project-id <id>` to set up a known Fimo project. If the project has no code yet — for example, one just created in Fimo Studio — `init` scaffolds a fresh site into it and pushes the initial commit: the same create-new path, linked to the existing ID. If the project already has code, `init` clones it into `[dir]`, like `fimo clone`. Use `--env <name>` to check out a specific env (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
+Pass `--project-id <id>` to set up a known Fimo project. If the project has no code yet — for example, one just created in Fimo Studio — `init` scaffolds a fresh site into it and pushes the initial commit: the same create-new path, linked to the existing ID. If the project already has code, `init` clones it into `[dir]`, like `fimo clone`. Use `--branch <name>` to check out a specific Branch (defaults to `main`); `--env <name>` remains a compatibility alias. Without `--project-id`, `fimo init` creates a new project.
 
 ## What gets written (create-new path)
 

package/assets/skills/fimo-cli/references/locales.md

@@ -15,7 +15,7 @@ fimo locales remove es --yes --json
 
 Studio chat can run `locales list`. Manage the locale lifecycle through Studio Settings or the standalone CLI.
 
-These commands update the selected environment through the locale lifecycle API. The API commits `.fimo/config.json` to the Fimo branch, then the CLI synchronizes the **whole local branch** to that commit. They refuse a dirty config, a local-ahead branch, or a diverged branch before applying the remote change. `--yes` bypasses only the explanatory prompt.
+These commands update the selected Branch through the locale lifecycle API. The API commits `.fimo/config.json` to the Fimo Branch, then the CLI synchronizes the **whole local branch** to that commit. They refuse a dirty config, a local-ahead branch, or a diverged branch before applying the remote change. `--yes` bypasses only the explanatory prompt.
 
 If a mutation exits with code `2` and `data.code` is `LOCALE_APPLIED_SYNC_REQUIRED`, the remote operation succeeded (`data.applied` is `true`) but the local fast-forward did not. **Do not retry the locale command.** Run the commands in `data.sync.recovery`, resolve the checkout, and confirm with `fimo status` or `fimo locales list`.
 

package/assets/skills/fimo-cli/references/mcp.md

@@ -40,15 +40,15 @@ For clients that accept a JSON command configuration, the equivalent entry is:
 Do not add shell output or logging around the command: stdout is reserved for MCP JSON-RPC frames. Diagnostics are
 written to stderr.
 
-## Project and environment scope
+## Project and Branch scope
 
 When launched inside a linked Fimo project, `fimo mcp` reads the project from `.fimo.settings.json` and uses the
-current git branch as the default environment. This keeps an AI client working against the same project environment as
-the checkout.
+current git branch as the default Branch. This keeps an AI client working against the same Branch as the checkout.
 
 Outside a linked project, the server still works, but each project-scoped tool call must provide `projectId` and
-`env`. The client can also pass an environment override when launching the CLI. Never edit `.fimo.settings.json`
-manually to change scope.
+`env` (the compatibility-preserved wire field for a Branch name). The canonical catalog tool is `branches_list`;
+`envs_list` remains a compatibility alias. The client can also pass a Branch override when launching the CLI. Never
+edit `.fimo.settings.json` manually to change scope.
 
 The CLI credential represents the signed-in user's Fimo authority. If an MCP server is invoked from a Fimo agent
 session, the session's frozen capability snapshot still limits the operations available to that agent.
@@ -57,13 +57,13 @@ session, the session's frozen capability snapshot still limits the operations av
 
 The Project MCP catalog covers:
 
-- **Identity and navigation** — current user, projects, and environments.
+- **Identity and navigation** — current user, projects, and Branches.
 - **Content** — schemas, collection entries, search, create/update/delete, bounded bulk operations, and Singles.
 - **Labels** — list, read, set, batch-set, and delete localized labels.
 - **Media** — list and inspect assets, generate images or videos, create folders, move, and delete assets. Binary
   upload remains `fimo assets upload`.
 - **Forms** — create, read, update, and delete forms; inspect submissions and statistics.
-- **Files** — read, glob, grep, write, edit, and delete project files within the scoped environment. Sensitive files
+- **Files** — read, glob, grep, write, edit, and delete project files within the scoped Branch. Sensitive files
   such as credentials and `.env` files are excluded.
 - **Agents** — list agents, start a run, and inspect run status.
 
@@ -76,7 +76,7 @@ Local MCP uses the stored CLI credential (or `FIMO_API_TOKEN` when explicitly co
 browser OAuth consent screen. Remote MCP uses Fimo OAuth with `read`, `write`, and `agents` scopes; the user selects
 the optional capabilities during consent.
 
-In both modes, Fimo still checks the user's project permissions, environment access, input validation, and file safety
+In both modes, Fimo still checks the user's project permissions, Branch access, input validation, and file safety
 rules for every operation. MCP does not grant access to projects the user cannot already access.
 
 For ChatGPT, Claude, or another remote MCP client, use the setup guide in the public [MCP documentation](https://fimo.ai/docs/ai/mcp)

package/assets/skills/fimo-cli/references/preview.md

@@ -7,11 +7,14 @@
 ## Commands
 
 ```bash
-fimo preview url                                    # URL for the current env (from the git branch)
-fimo --env feat/redesign preview url                # URL for a specific env
-fimo preview url --env main --json                  # structured output for agents / scripts
+fimo preview url                                      # URL for the current Branch (from git)
+fimo --branch feat/redesign preview url              # URL for a specific Branch
+fimo preview url --branch main --json                # structured output for agents / scripts
 ```
 
+`--env <name>` remains a compatibility alias for `--branch <name>`. The API and
+JSON response still use the legacy `env` field and `/env/` dashboard path.
+
 - **Interactive mode** shows named Preview and Fimo links. When piped, it prints only the raw preview URL, so `fimo preview url | xargs open` and `curl "$(fimo preview url)"` keep working.
 - **JSON mode** (or `FIMO_OUTPUT=json`) emits the standard envelope:
 
@@ -46,9 +49,9 @@ Agents should read `data.preview_url` or `data.dashboard_url`, never parse the h
 
 ## Cold sandbox case
 
-If the env's sandbox has been torn down (long idle period, explicit teardown), the first `fimo preview url` lazy-provisions one — same ~60–90 s cost a `fimo deploy` would have paid. Subsequent calls are sub-second again. You don't need to do anything special; just wait it out.
+If the Branch's sandbox has been torn down (long idle period, explicit teardown), the first `fimo preview url` lazy-provisions one — same ~60–90 s cost a `fimo deploy` would have paid. Subsequent calls are sub-second again. You don't need to do anything special; just wait it out.
 
 ## See also
 
 - `references/deploy.md` — when you actually need to push code.
-- `references/branches.md` — env semantics and the global `--env <name>` flag.
+- `references/branches.md` — Branch semantics and the global `--branch <name>` flag.

package/assets/skills/fimo-cli/references/project-vars-and-secrets.md

@@ -66,7 +66,7 @@ fimo agents validate
 
 `fimo agents secrets add` edits `.fimo/agents/<name>/config.yaml`. It does not create or rotate the secret value. Use `fimo secrets add` to create the value or `fimo secrets update` to rotate it.
 
-`fimo agents validate` checks that required agent secrets exist in the project. A running agent keeps the environment it started with; the next run reads the deployed agent config again.
+`fimo agents validate` checks that required agent secrets exist in the project. A running agent keeps the Branch it started with; the next run reads the deployed agent config again.
 
 ## Choosing Between Them
 

package/assets/skills/fimo-cli/references/projects.md

@@ -7,7 +7,7 @@ Commands for listing projects across an org, cloning a remote project locally, a
 ```bash
 fimo projects list [--org <id>]                 # list projects in an org (defaults to active org)
 fimo projects create [dir] [--org <id>] [--framework react-router|astro|nextjs|sveltekit] [--install|--no-install]
-fimo projects clone [projectId] [dir] [--env <name>] # clone an existing project locally
+fimo projects clone [projectId] [dir] [--branch <name>] # clone an existing project locally
 fimo projects delete [projectId] [-C <dir>] [-y] # delete (defaults to current project)
 fimo projects publish [projectId] [-C <dir>]     # make the project live (publish from main)
 fimo projects unpublish [projectId] [-C <dir>]   # take the project offline
@@ -16,7 +16,7 @@ fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the l
 
 - **`list`** — projects you can see in the org. Live projects are marked.
 - **`create`** — identical to `fimo init` (create-new path); see `references/init.md`.
-- **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo/project.json` and agent files. Use `fimo clone <projectId>` when scripting or when the ID is known. In an interactive terminal, bare `fimo clone` opens a project picker for the active org; JSON mode and non-TTY shells require an explicit project ID and fail fast instead of prompting. By default it clones `main`; pass `--env <name>` to clone a specific env. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
+- **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo/project.json` and agent files. Use `fimo clone <projectId>` when scripting or when the ID is known. In an interactive terminal, bare `fimo clone` opens a project picker for the active org; JSON mode and non-TTY shells require an explicit project ID and fail fast instead of prompting. By default it clones `main`; pass `--branch <name>` to clone a specific Branch. The legacy `--env <name>` spelling remains a compatibility alias. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
 - **`delete`** — destructive; prompts unless `-y`. Removes the remote project.
 - **`publish` / `unpublish`** — toggle the project's public visibility. `publish` flips the current `main` state live (the same "go live" as `fimo deploy --publish`, minus the git push). This is **not** the versioned release path — for that, see `fimo publish` in `references/branches.md`.
 - **`rename`** — edits only the linked local project immediately. It requires a project marker in the cwd, and if you pass a `[projectId]` that doesn't match the linked project it errors and exits 1 (so you can't rename a different project). It writes `seo.siteName` into the current or legacy project config; commit and run `fimo deploy` to reconcile the remote `displayName` and deploy the new site name.
@@ -24,7 +24,7 @@ fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the l
 ## Top-level clone shortcut
 
 ```bash
-fimo clone [projectId] [dir] [--env <name>] # same as `fimo projects clone`
+fimo clone [projectId] [dir] [--branch <name>] # same as `fimo projects clone`
 ```
 
 Use the top-level shortcut for the common "get this project onto my machine" workflow. After clone succeeds, `cd` into the printed directory, `Read` the project's `AGENTS.md`, and load the code skill with `fimo skills get fimo-code` before generating code.