fimo 0.15.0 → 0.16.0-experimental.2

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/hosting.md

@@ -0,0 +1,114 @@
+# Hosting: how a published project is served
+
+Declare redirects, headers, rewrites, and URL shape in
+`.fimo/config.json#hosting`. This is the only place Fimo reads them from.
+
+## Fields
+
+```json
+{
+  "hosting": {
+    "redirects": [{ "source": "/", "destination": "/fr", "permanent": false }],
+    "rewrites": [{ "source": "/blog/:slug", "destination": "/posts/:slug" }],
+    "headers": [
+      {
+        "source": "/(.*)",
+        "headers": [{ "key": "X-Frame-Options", "value": "DENY" }]
+      }
+    ],
+    "cleanUrls": true,
+    "trailingSlash": false
+  }
+}
+```
+
+| Field           | Effect                                                              |
+| --------------- | ------------------------------------------------------------------- |
+| `redirects`     | Send the browser elsewhere. `permanent: true` is 308, otherwise 307 |
+| ↳ `statusCode`  | Use instead of `permanent` for an exact 301, 302, 307, or 308       |
+| `rewrites`      | Serve a different path without changing the URL                     |
+| `headers`       | Add response headers on matching paths                              |
+| `cleanUrls`     | Serve `/about` for `/about.html` and 308 the extension away         |
+| `trailingSlash` | `true` requires a trailing slash, `false` forbids one               |
+
+Every field is optional. Only what you declare is emitted.
+
+## Matching
+
+`source` matches the pathname only, never the query string.
+
+| Pattern         | Matches                                |
+| --------------- | -------------------------------------- |
+| `/about`        | exactly that path                      |
+| `/blog/:slug`   | one segment, captured as `slug`        |
+| `/proxy/:rest*` | any number of segments, including none |
+| `/(.*)`         | everything                             |
+
+Captured names are reusable in `destination`: `/blog/:slug` →
+`/posts/:slug`. `destination` may be an absolute path or an external URL.
+
+## Conditions
+
+Any redirect, rewrite, or header rule can require more than a path match. `has`
+applies the rule only when every condition holds; `missing` only when none of
+them are present.
+
+```json
+{
+  "redirects": [
+    {
+      "source": "/(.*)",
+      "has": [{ "type": "header", "key": "x-vercel-ip-country", "value": "GB" }],
+      "destination": "/uk/:path*"
+    }
+  ],
+  "rewrites": [
+    {
+      "source": "/",
+      "missing": [{ "type": "cookie", "key": "consent" }],
+      "destination": "/consent"
+    }
+  ]
+}
+```
+
+| `type`   | Matches on                                           |
+| -------- | ---------------------------------------------------- |
+| `header` | a request header, including CDN-injected geo headers |
+| `cookie` | a cookie                                             |
+| `query`  | a query parameter                                    |
+| `host`   | the hostname the request arrived on — takes no `key` |
+
+Omit `value` to match on presence alone, as the `consent` cookie above does.
+
+**Prefer doing this in the application when it can.** Middleware, a loader, or a
+server component can be run and tested locally; a condition here only takes
+effect once published, so a mistake is found in production. Reach for `has` when
+the app cannot act — a redirect that must happen before any code runs, or a
+header on a static asset.
+
+## Rules
+
+- **Prefer the framework's own router.** Use `hosting` for what the router
+  cannot express: cross-origin moves, security headers, host-level URL shape.
+  Do not mirror `.fimo/config.json#routes` here.
+- **`permanent: true` is cached by browsers and hard to take back.** Omitting it
+  gives a temporary redirect, which is the one you can change your mind about.
+  Set it only when the old URL is genuinely retired. Reach for `statusCode` only
+  when you need a literal 301 or 302; it wins over `permanent`.
+- **With `cleanUrls: true`, drop the extension everywhere.** A `source` or
+  `destination` of `/about.html` will not match; write `/about`.
+- **Set `trailingSlash` on any site with more than one page.** Leaving it unset
+  serves `/about` and `/about/` as separate URLs, which search engines index as
+  duplicates.
+- **An empty `hosting: {}` means no platform routing**, which is different from
+  omitting `hosting` entirely — that leaves legacy SPA behaviour untouched.
+- **Not supported:** cron jobs (use `fimo schedules`), image optimization (use
+  Fimo media), per-function runtime settings, deployment regions.
+
+## Verify
+
+`fimo validate` rejects an unknown `hosting` key, so a typo fails locally
+rather than silently doing nothing in production. Behaviour itself only takes
+effect once published — check the live URL after `fimo deploy --publish`, not
+the preview.

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`.                                                                                                                            |
@@ -71,17 +72,27 @@ fimo init my-svelte-site --framework sveltekit --org <organizationId>
 ```
 
 Each shell includes its framework adapter, hosted-preview connector, and
-`.fimo/config.json#runtime.framework`. The Astro shell also includes a minimal
-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.
+`.fimo/config.json#runtime.framework`, plus an application-owned optional locale
+boundary that keeps the default locale unprefixed. The Astro shell also includes a minimal
+content-backed example with static, on-demand, and dynamic routes; the other shells intentionally
+contain no schema, labels, or designed website.
+
+Set the primary locale from the request: when several are explicitly named, use the first as default;
+if none is requested, keep `en` and tell the user. Update `.fimo/config.json#i18n`, the framework-native
+locale boundary, matcher, and HTML language default. Do not keep `en` solely because the shell starts
+there. Do not add `/en`, a language picker, global path-prefix configuration, or localized schemas unless
+the site needs them.
 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)
 
@@ -89,7 +100,7 @@ Pass `--project-id <id>` to set up a known Fimo project. If the project has no c
 
 - The selected project shell: React Router by default, Astro with `--framework astro`, Next.js App Router with `--framework nextjs`, or SvelteKit with `--framework sveltekit`
 - `.fimo/project.json` — links this directory to the remote project (read-only after creation)
-- `.fimo/config.json` — project, route, locale, SEO, and agent policy
+- `.fimo/config.json` — project, optional Studio Pages route metadata, locale, SEO, and agent policy
 - `.fimo/agents/` — versioned agent bundles
 - `.env` — framework-specific tenant content API URLs for local development
 - `AGENTS.md` + `CLAUDE.md` — project rules (from the template) read by AGENTS.md-compatible tools and Claude Code. Both point the agent at `fimo skills get` to load the real skills on demand.
@@ -124,7 +135,7 @@ fimo rename "Acme Coffee"
 pnpm dev &            # or npm run dev / yarn dev / bun dev — the project's package manager
 ```
 
-Outside the first-preview path below, when a unit of work looks done, **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `fimo deploy --publish` to go live) and run it only after the developer confirms.
+Outside the first-preview path below, when a unit of work looks done, **offer** to deploy (`fimo deploy` for a hosted project preview, `fimo deploy --publish` to go live) and run it only after the developer confirms.
 
 ## Load the project context
 
@@ -148,7 +159,7 @@ Whenever `fimo init` created or scaffolded a new project — including a Studio-
 fimo deploy -m "chore: first preview" --json
 ```
 
-`-m` is required because you run non-interactively; the deploy validates, commits pending changes, pushes, and syncs the hosted preview. It is also the sandbox warm-up — never run a separate warm-up deploy on this path. Read `data.preview_url` and `data.dashboard_url` from the envelope and return both links. If the initiating request described a concrete site, build a minimal meaningful first screen before this single deploy; otherwise deploy the scaffolded site as-is and then ask what to build.
+`-m` is required because you run non-interactively; the deploy validates, commits pending changes, pushes, and syncs the hosted preview. It is also the sandbox warm-up — never run a separate warm-up deploy on this path. Read `data.preview_url` and `data.studio_url` from the envelope and return both links. `data.dashboard_url` remains a deprecated compatibility alias for `data.studio_url`. If the initiating request described a concrete site, build a minimal meaningful first screen before this single deploy; otherwise deploy the scaffolded site as-is and then ask what to build.
 
 This first deploy creates a preview only — never add `--publish`, and treat every later deploy as offer-then-confirm. The rule does not apply when `init` cloned a project with existing code or when the work is a migration; those paths keep their normal deployment approval rules.
 

package/assets/skills/fimo-cli/references/integrations/firecrawl.md

@@ -247,3 +247,5 @@ Visual/content QA before publish:
 ```bash
 fimo integrations run firecrawl scrape --url "$(fimo preview url)" --formats markdown,links --json
 ```
+
+Because command substitution captures stdout, `fimo preview url` emits the raw `sandbox_url` in this example. For JSON workflows, pass `data.sandbox_url` to Firecrawl and refresh it after `data.sandbox_expires_at`. The stable `data.preview_url` is an authenticated browser viewer and is not the Firecrawl destination.

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

@@ -15,21 +15,17 @@ 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`.
 
-Edit `.fimo/config.json` only for declarative routing behavior:
+Edit `.fimo/config.json` only for declarative locale and route metadata:
 
 ```jsonc
 {
   "i18n": {
     "defaultLocale": "en",
     "locales": ["en"],
-    "routing": {
-      "strategy": "path-prefix", // only supported strategy: /es/about for Spanish; default locale can stay /about
-      "prefixDefaultLocale": false, // when false, omit /en for the default locale
-    },
   },
 }
 ```
@@ -37,7 +33,7 @@ Edit `.fimo/config.json` only for declarative routing behavior:
 - `defaultLocale` is the locale used by `fimo validate`, `fimo labels set` without `--locale`, and content commands without `--locale`. Change it with `fimo locales set-default`.
 - `locales` must include `defaultLocale`. Add and remove values with `fimo locales add` and `fimo locales remove`.
 - Locale tags should be structurally valid, for example `en`, `es`, `pt-BR`, or `zh-Hans`.
-- `routing.strategy` currently supports `path-prefix`.
+- New projects do not need a global routing strategy. The route contract declares locale placement with `/:locale`; legacy `i18n.routing.strategy` values are read only for compatibility while migrating.
 - If multiple locales are configured, create or update labels and localized content for every configured locale. Create schemas with `i18n: { "enabled": false }` only once.
 
 `fimo locales remove` permanently deletes that locale's stored entries and labels.
@@ -55,38 +51,66 @@ Validation checks:
 - malformed locale tags
 - `defaultLocale` missing from `locales`
 - unsupported routing strategies
-- canonical routes in `.fimo/config.json` that claim reserved locale prefixes, for example `/es`
-- top-level dynamic routes that could capture locale prefixes unless the project uses Fimo's React Router helper
+- routes in `.fimo/config.json` that hardcode a locale prefix, for example `/es/pricing`
+- two routes that answer the same URL once the locale segment is removed
+- a `:locale` segment that is not first, or that declares `schema`, `queryField`, `displayField`
+- an entry param declared `optional`, or missing `schema` / `queryField`
+- top-level dynamic routes other than `:locale` that could capture locale prefixes
 - missing default-locale DB labels
 
 ## Route Metadata Rule
 
-Keep `.fimo/config.json#routes` canonical and unlocalized:
+Write the locale into a route's path with the reserved `:locale` segment, never as a literal prefix. The descriptor `type` is optional: `locale` infers `"locale"`, while every other parameter defaults to `"entry"`:
 
 ```json
 {
   "routes": {
+    "blog-post": {
+      "label": "Blog post",
+      "path": "/:locale/blog/:slug",
+      "params": {
+        "locale": { "type": "locale", "optional": true },
+        "slug": { "schema": "BlogPost", "queryField": "slug", "displayField": "title" }
+      }
+    },
     "pricing": {
       "label": "Pricing",
-      "path": "/pricing"
+      "path": "/:locale/pricing",
+      "params": { "locale": { "type": "locale", "optional": true } }
     }
   }
 }
 ```
 
-Do not add `/es/pricing` as a second Fimo route. The route selector localizes canonical routes for the active preview locale. In React Router projects, use the package helper:
+| Declared path         | `params.locale`                           | URLs the route answers                              |
+| --------------------- | ----------------------------------------- | --------------------------------------------------- |
+| `/:locale/blog/:slug` | omitted                                   | `/blog/hello` for `en`, `/fr/blog/bonjour` for `fr` |
+| `/:locale/blog/:slug` | `{ "type": "locale", "optional": false }` | `/en/blog/hello` and `/fr/blog/bonjour`             |
+| `/:locale/pricing`    | omitted                                   | `/pricing` for `en`, `/fr/pricing` for `fr`         |
+
+- `locale` is reserved. It is read from the URL, so it never takes `schema` or `queryField` and never becomes a CMS query. Every other param is content-backed and needs both.
+- `optional: true` means omit the configured default locale from the URL. With `i18n.defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French.
+- `optional: false` prefixes every locale, including the default (`/en/pricing` and `/fr/pricing`). Changing `i18n.defaultLocale` chooses the fallback locale; it does not by itself change this prefix policy.
+- A route with no `:locale` segment stays application-owned. Studio shows it once and neither adds nor interprets a locale segment.
+- Do not add `/es/pricing` as a second route. A locale segment does not make two routes distinct.
+
+Register the same shape in the router. React Router spells the omittable segment `:locale?`:
 
 ```ts
-import { fimoRoutes } from 'fimo/react-router/routes';
+route(':locale?/blog/:slug', './pages/BlogPost.tsx');
 ```
 
-For every framework, the application owns its URL scheme and passes the resolved locale into Fimo. Canonical route metadata is optional unless the project wants Fimo Studio route selection/navigation.
+These canonical entries are also the optional metadata used by Studio Pages. See `references/pages.md` for content-backed `params` and declared `sources`.
+
+For every framework, the application owns its URL scheme, resolves the locale, and passes it into Fimo. Studio stores the locale the app reports for the current location — including when only the locale changed — and reads content in it. Route metadata is optional unless the project wants Fimo Studio route selection/navigation.
+
+Astro and Next express the same optional-locale semantic with paired native filesystem route trees: an unprefixed default-locale tree and a prefixed non-default tree. Neither framework supports an optional single-segment filesystem folder.
 
 ## Migrate An Existing Locale System
 
 Inspect the existing locale provider, route table, switcher, redirects, and public URLs before editing configuration. Preserve working URL behavior during the migration.
 
-Preserve the existing locale provider, router, switcher, redirects, and public URLs. Use framework helpers only when they fit that architecture. Next.js projects run `fimo skills get fimo-code --ref frameworks/next/locales`; React Router projects load the React Router setup reference; Astro projects run `fimo skills get fimo-code --ref frameworks/astro` and pass the page-resolved locale into server reads and `getLabels`.
+Preserve the existing locale provider, router, switcher, redirects, and public URLs. Next.js projects run `fimo skills get fimo-code --ref frameworks/next/locales`; React Router projects load the React Router setup reference and its focused route-ownership migration when upgrading; Astro projects run `fimo skills get fimo-code --ref frameworks/astro` and pass the page-resolved locale into server reads and `getLabels`.
 
 ## Labels And Content
 

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/pages.md

@@ -0,0 +1,70 @@
+# Pages route metadata
+
+Pages can mirror the application's routes in Fimo Studio. It gives editors a route tree and, for each selected route, a page-shaped workspace for its Labels, Single, bound entries, and Collection results. The CLI writes this optional metadata to `.fimo/config.json` under `routes.<id>`; it does not replace the application router or move or duplicate content.
+
+## Route shape
+
+A route has three separate parts:
+
+- `path` is the URL pattern, such as `/blog/:slug`.
+- `params` optionally binds path placeholders to Collection entries so Studio can select a concrete route in the page header.
+- `sources` optionally names the Labels, Single, and Collection results editors manage after selecting a route.
+
+Each param key matches a `:placeholder` in `path`. `schema` selects the Collection, `queryField` is the entry field stored in the URL, and `displayField` is the field Studio shows to editors. Use `id` or the built-in `slug` for `queryField`; a custom URL field must set both `"required": true` and `"unique": true` in its schema. Params resolve in path order, so a later param query may use an earlier selection:
+
+```bash
+fimo pages set <id> --path '/shop/:category/:product' --params '{"category":{"schema":"Category","queryField":"slug","displayField":"name"},"product":{"schema":"Product","queryField":"slug","displayField":"name","query":{"where":{"category":"$params.category.id"},"sort":"name"}}}'
+```
+
+`sources` is a named object under `routes.<id>.sources`. It is not an array or a route definition. Keep its keys stable and descriptive:
+
+```json
+{
+  "copy": {
+    "type": "labels",
+    "match": ["blog.*"]
+  },
+  "settings": {
+    "type": "single",
+    "schema": "BlogSettings"
+  },
+  "relatedPosts": {
+    "type": "collection",
+    "schema": "BlogPost",
+    "query": {
+      "where": {
+        "category": "$params.slug.category"
+      },
+      "sort": "-publishedAt",
+      "limit": 4
+    }
+  }
+}
+```
+
+Pass that same object as JSON:
+
+```bash
+fimo pages set <id> --sources '{"copy":{"type":"labels","match":["blog.*"]},"settings":{"type":"single","schema":"BlogSettings"},"relatedPosts":{"type":"collection","schema":"BlogPost","query":{"where":{"category":"$params.slug.category"},"sort":"-publishedAt","limit":4}}}'
+```
+
+The three source types select matching Labels, one-off Singles, or Collection results. A Collection source's optional `query` uses the normal content query shape.
+
+## Params queries and source queries
+
+Both use the normal content query shape and may read an earlier bound value with `$params.<param>.<field>`, but they run at different stages and narrow different things:
+
+- A dependent param query runs while Studio resolves the header selectors. On `/shop/:category/:product`, the product query narrows which products can become the `:product` URL segment after a category is chosen.
+- A Collection source query runs after Studio has resolved and selected the route. On `/blog/:slug`, `relatedPosts` uses the selected post's `$params.slug.category` to narrow the entries shown in that route's editor; it does not create more routes.
+
+## Commands
+
+```bash
+fimo pages list
+fimo pages list --expand
+fimo pages set <id> --path /about --label About
+fimo pages set <id> --clear-params
+fimo pages set <id> --clear-sources
+fimo pages rename <id> <new-id>
+fimo pages delete <id>
+```

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

@@ -1,19 +1,27 @@
 # Preview URL (without deploying)
 
-**Use `fimo preview url` whenever you need the current preview link — to open it, screenshot it, hand it to another tool, or verify a change you've already deployed. Never trigger a `fimo deploy` just to refresh a URL.**
+**Use `fimo preview url` whenever you need the current hosted preview — to open it, screenshot it, hand it to another tool, or verify a change you already deployed. Never trigger `fimo deploy` just to retrieve a URL.**
 
-`fimo deploy` is a milestone command: it commits, pushes, syncs the sandbox, and only then prints the preview URL. `fimo preview url` skips all of that. It calls the API directly, gets a fresh 15-min token, and prints the URL. No commit, no push, no restart. Sub-second on a warm sandbox.
+`fimo deploy` commits, pushes, and syncs the sandbox before it prints destinations. `fimo preview url` skips those deployment steps and only resolves the current Branch's preview destinations.
 
 ## 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                                      # current Branch (from git)
+fimo --branch feat/redesign preview url              # specific Branch
+fimo preview url --branch main --json                # structured output for agents / scripts
+fimo preview url --all                               # print every destination as named raw URLs
+curl -L "$(fimo preview url)"                        # fetch the raw sandbox preview
 ```
 
-- **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:
+`--env <name>` remains a compatibility alias for `--branch <name>`. The API and JSON response still use the legacy `env` field and `/env/` dashboard path.
+
+## Human and machine behavior
+
+- **Interactive terminal:** shows the stable `preview_url` and `studio_url` as named links. `preview_url` opens a full-screen Fimo viewer and requires a logged-in user with access to the project.
+- **Piped or captured output:** prints only the short-lived `sandbox_url`. This preserves commands such as `curl -L "$(fimo preview url)"` and gives browsers, screenshot tools, and crawlers the directly fetchable site.
+- **`--all`:** prints `preview_url`, `studio_url`, `sandbox_url`, and `sandbox_expires_at` as named raw values for a person inspecting every destination.
+- **JSON mode** (or `FIMO_OUTPUT=json`): returns both destinations explicitly:
 
 ```json
 {
@@ -23,32 +31,33 @@ fimo preview url --env main --json                  # structured output for agen
   "data": {
     "project_id": "prj_abc",
     "env": "main",
-    "preview_url": "https://...",
-    "dashboard_url": "https://fimo.ai/app/projects/prj_abc/env/main/preview",
-    "expires_at": "2026-06-02T18:42:00.000Z"
+    "preview_url": "https://fimo.ai/preview/prj_abc/main",
+    "sandbox_url": "https://preview.provider.example/session",
+    "sandbox_expires_at": "2026-08-20T18:42:00.000Z",
+    "studio_url": "https://fimo.ai/app/projects/prj_abc/env/main/preview",
+    "dashboard_url": "https://fimo.ai/app/projects/prj_abc/env/main/preview"
   }
 }
 ```
 
-Agents should read `data.preview_url` or `data.dashboard_url`, never parse the human output. The dashboard URL is stable; `expires_at` is the preview token's hard deadline. If you're caching the preview URL for more than ~10 minutes, re-run the command.
+Agents must use `data.sandbox_url` for curl, Firecrawl, screenshots, and other machine reads. Use `data.preview_url` for the authenticated full-screen viewer and `data.studio_url` for the Branch inside Fimo Studio. `data.dashboard_url` is a deprecated compatibility alias for `data.studio_url`. The raw sandbox URL expires; resolve it again when `sandbox_expires_at` is near or has passed. The stable human URLs do not need to be regenerated.
 
 ## When to use it
 
-- **You changed something with `fimo deploy` and now want to look at it** — `fimo preview url` then open the URL.
-- **You need a URL for a screenshot, an agent-browser session, an analytics check, or a manual smoke test** — go straight here.
-- **You're polling the preview in a loop** — call `fimo preview url` once per loop body. Within ~5 minutes the API reuses the same token (cheap), beyond that you'll get a fresh one automatically.
-- **The previous URL stopped working** — the 15-min token expired. Re-run `fimo preview url`, don't redeploy.
+- **You deployed a change and want to inspect it** — open the interactive `preview_url`.
+- **An agent or tool needs to read the site** — pipe the command or use `data.sandbox_url` from JSON.
+- **The raw URL expired** — run `fimo preview url` again; do not redeploy.
 
 ## When NOT to use it
 
-- **You changed code and want it on the preview** — that's still `fimo deploy`. `fimo preview url` only returns a URL; it doesn't push your local edits.
-- **You need the live, published URL** (the `*.fimo.site` or custom domain) — that comes from `fimo deploy --publish` / `fimo publish` and lives on the project, not in this command. See `references/deploy.md` and `references/domains.md`.
+- **You changed code and want it on the preview** — use `fimo deploy`. This command only retrieves destinations.
+- **You need the live published URL** — use `fimo deploy --publish` or `fimo publish`; see `references/deploy.md` and `references/domains.md`.
 
 ## 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.
+Resolving `sandbox_url` may take roughly 60–90 seconds when an idle sandbox must be provisioned or restarted. The stable `preview_url` performs the same authenticated resolution when a project member opens it.
 
 ## See also
 
-- `references/deploy.md` — when you actually need to push code.
-- `references/branches.md` — env semantics and the global `--env <name>` flag.
+- `references/deploy.md` — when you need to push code.
+- `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.