fimo 0.18.0 → 0.20.0

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

@@ -60,16 +60,18 @@ pnpm dev                                       # run the app locally (use the pr
 fimo credits                                   # inspect the owning org's AI credit balance (read-only)
 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                                    # ON-DEMAND: hosted project preview (runs validate internally)
 fimo deploy --publish                          # ON-DEMAND: publish live (only when the developer says "ship it")
 ```
 
-The working 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), ask the developer what they want, edit, and iterate against the live localhost server. Outside the first-time onboarding rule below, `fimo deploy` is **not** a required final step — reach for it only when the developer wants a hosted preview, a shareable link, or to go live, and only on their signal (see `references/deploy.md`).
+The working 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), ask the developer what they want, edit, and iterate against the live localhost server. Outside the first-time onboarding rule below, `fimo deploy` is **not** a required final step — reach for it only when the developer wants a hosted project preview or to go live, and only on their signal (see `references/deploy.md`).
 
 `fimo validate` is the single entrypoint for "prove this project is ready" — it covers schema/form codegen, route metadata checks, lint, and missing label checks for `i18n.defaultLocale` from `.fimo/config.json` (fallback: `en`). Use `fimo labels set` / `set-many` to create or update label values in the DB. The underlying phases are also available individually under the hidden `fimo scripts` namespace for advanced/debug use.
 
 Keep `fimo validate --json` at the front of the project's `build` script, which is where the bundled templates put it. The hosted build runs that script, so validation runs on the exact code being published and a rejected build reports the failing rule instead of a generic build error. Removing it is the developer's call, but do not drop it while editing `package.json` for other reasons.
 
+**`fimo validate` does not type check.** Run the project's own `typecheck` or `check` script after changing code.
+
 ## Decision Tree
 
 Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
@@ -85,6 +87,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`
+- "Add a redirect / security headers / CSP / HSTS / clean URLs / trailing slash" → `references/hosting.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`
@@ -118,7 +121,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **When `fimo init` created or scaffolded a new project (create-new path, including a Studio-supplied `--project-id`)** → after init and context loading succeed, run the single first-preview deploy and return the preview and dashboard links — see `references/init.md` § Create the first hosted preview. That deploy is also the sandbox warm-up; never run a separate warm-up deploy. Skip it only if the user explicitly said not to deploy. Linking a project with existing code and migrations keep their own approval rules.
 - **Right after `fimo init`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-init name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/init.md`.
 - **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes. If the initiating request did not say what to build, ask the developer — after the first preview on the create-new path, never as a blocker before initializing.
-- **When a user-visible unit of work looks done outside first-time onboarding** → **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 — or immediately if they ask. Never deploy ordinary edits on your own. See `references/deploy.md`.
+- **When a user-visible unit of work looks done outside first-time onboarding** → **offer** to deploy (`fimo deploy` for a hosted project preview, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy ordinary edits on your own. See `references/deploy.md`.
 - **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`.
@@ -132,7 +135,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Editing `.fimo/project.json`** — read-only; it's the link between local and remote project. Treat as a generated file.
 - **Treating `fimo deploy` as the working loop or a required final step** — the loop is local (`pnpm dev` etc.). Deploy commits + pushes + round-trips the sandbox; it's for hosted previews / going live, on-demand. Iterate locally and deploy at logical breakpoints. See `references/deploy.md`.
 - **Deploying without the developer asking or confirming** — new-project onboarding authorizes exactly one automatic first preview deploy (unless the user said not to deploy); every other deploy is offer-then-confirm. Don't auto-deploy after finishing an ordinary edit.
-- **Running `fimo deploy` just to get a fresh preview URL** — that's a commit + push + sandbox sync for what should be a sub-second read. Use `fimo preview url` instead. See `references/preview.md`.
+- **Running `fimo deploy` just to get the current preview URL** — that's a commit + push + sandbox sync when only destination resolution is needed. Use `fimo preview url` instead. See `references/preview.md`.
 - **Using `fimo deploy --publish` casually** — `--publish` makes the site live to the public. Plain `fimo deploy` (preview) is the default. Use `--publish` only when the user says "ship it" / "go live" / "publish".
 - **Bare `fimo init` in a non-interactive shell** — will hang. Always pass `[dir]`, `--no-install` (or `--install`), `--no-skills` (or `--skills`), and `--org`/`--agents` as needed explicitly when scripted.
 - **Using a starter on an existing project** — `--starter` is create-new only. Keep `--project-id` flows blank and use explicit content/form/label commands when changing an existing project.

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

@@ -78,7 +78,7 @@ There is no all-capabilities wildcard; keeping the list explicit makes each agen
 | `webhooks:write`             | Create, modify, delete, or trigger webhooks | High         |
 | `schedules:read`             | Read schedule configs and run history       | Low          |
 | `schedules:write`            | Create, change, or trigger scheduled runs   | Critical     |
-| `fimo:logs:read`             | Read production logs                        | Low          |
+| `fimo:logs:read`             | Read project deployment logs                | Low          |
 | `fimo:analytics:read`        | Read analytics data                         | Low          |
 | `fimo:preview:read`          | Read a current preview URL                  | Low          |
 | `fimo:history:read`          | Read project restore points                 | Low          |
@@ -92,6 +92,9 @@ If a capability is missing, the related command is denied and the agent should c
 blocker. Add the capability to `capabilities.yaml`, run `fimo agents validate <name>`, deploy the bundle, and start a
 new run. A denied capability does not grant access to anything else.
 
+Studio chat and project-bound Slack turns receive `fimo:logs:read`. Autonomous agents receive it only when their
+`capabilities.yaml` declares it; use `fimo logs` with the deploy guidance when diagnosing a failed preview.
+
 Example for a content editor that can read and update entries but cannot change schemas:
 
 ```yaml

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

@@ -26,7 +26,7 @@ fimo --branch <name> <command>  # peek at another Branch for one command (does n
 
 | Command                 | git analogue        | What it does                                                                                                                                                                 |
 | ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fimo branch`           | `git branch`        | List Branches (current marked `*`). `-v` adds preview URLs + deleted Branches.                                                                                               |
+| `fimo branch`           | `git branch`        | List Branches (current marked `*`). `-v` includes 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. |
@@ -55,7 +55,7 @@ All of these accept the global `--branch` override; legacy `--env` remains an al
 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 Branch
-fimo preview url                 # fresh URL to open / screenshot the feat/seo preview
+fimo preview url                 # canonical 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 Branch back into main (resolve conflicts)

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

@@ -1,14 +1,14 @@
 # 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 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.
+**`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 **project-member preview 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`.
+> **Local vs hosted.** The local dev server is localhost only. The Fimo **dashboard preview** and the authenticated **project-member preview URL** are served by the deployed sandbox — so if the developer wants to see the site in the dashboard or send another project member 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-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.
 
-> **Just need the current preview URL?** That's `fimo preview url` — sub-second, no commit, no push. See `references/preview.md`. `fimo deploy` is only for pushing code changes.
+> **Just need the current preview URL?** That's `fimo preview url` — no commit or push. A cold sandbox can still take time to resolve. See `references/preview.md`. `fimo deploy` is only for pushing code changes.
 
 ## Commands
 
@@ -35,16 +35,27 @@ fimo deploy -m "<commit message>" --publish --json
 
 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 Branch page.         |
-| `app_url`       | Public live site, returned after a successful `--publish`.  |
+| Field                | Destination                                                      |
+| -------------------- | ---------------------------------------------------------------- |
+| `preview_url`        | Stable, authenticated full-screen viewer for project members.    |
+| `sandbox_url`        | Short-lived raw site URL for agents, curl, and screenshot tools. |
+| `sandbox_expires_at` | Expiry of the raw sandbox URL.                                   |
+| `studio_url`         | Stable, authenticated Fimo Studio project and Branch page.       |
+| `dashboard_url`      | Deprecated compatibility alias for `studio_url`.                 |
+| `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.
+When reporting the result, open `preview_url` for a person and use `sandbox_url` for machine reads. 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 runtimes. Project secrets are not injected into app builds; agents request secrets separately through their own config. See `references/project-vars-and-secrets.md`.
 
+## Diagnose a failed publication
+
+Use the publication ID returned by the failed command: run `fimo publish inspect <id> --json` for its durable status, then `fimo publish logs <id> --json` for a bounded build-log tail. Logs come from the hosting provider and may be unavailable after its deployment is reclaimed.
+
+## Diagnose a failed preview deploy
+
+If the sandbox fails to install dependencies or start the app, run `fimo logs --json` before retrying. Read the newest install and dev-server events first; when the response is truncated, use its `previousCursor` as `fimo logs --before <cursor> --json` to fetch the preceding page. Do not recreate or replace the sandbox before collecting logs, because that can discard the failure evidence.
+
 ## Framework hosting
 
 Fimo preview resolves `runtime.commands` override → package script → detected
@@ -57,6 +68,9 @@ needed, load the `fimo-code` skill's framework reference:
 connector and the explicit catch-all used only by plain Vite `BrowserRouter`
 SPAs; Astro's `fimo()` integration lives in `references/frameworks/astro.md`.
 
+Redirects, response headers, and URL shape belong in
+`.fimo/config.json#hosting` — see `references/hosting.md`.
+
 ## Warm the sandbox early in a session (optional)
 
 This is a **performance optimization, only worth doing when you already know a deploy is coming** (the developer asked to publish, or you're confident they'll want a hosted preview soon). If you're just iterating locally, skip it — don't deploy pre-emptively. New-project onboarding never needs it: its automatic first preview deploy is the warm-up.

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

@@ -135,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
 
@@ -159,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/preview.md

@@ -1,22 +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 Branch (from git)
-fimo --branch feat/redesign preview url              # URL for a specific Branch
+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
 ```
 
-`--env <name>` remains a compatibility alias for `--branch <name>`. The API and
-JSON response still use the legacy `env` field and `/env/` dashboard path.
+`--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:
+## 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
 {
@@ -26,32 +31,33 @@ JSON response still use the legacy `env` field and `/env/` dashboard path.
   "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 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.
+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/deploy.md` — when you need to push code.
 - `references/branches.md` — Branch semantics and the global `--branch <name>` flag.

package/assets/skills/fimo-migration/references/qa.md

@@ -112,6 +112,13 @@ Owned by the runtime lane; verified here read-only.
   unavailable in the report.
 - Deployment smoke is explicit owner opt-in; never run deploy or publish as a
   QA step.
+- When an approved publication fails, inspect its returned publication ID with
+  `fimo publish inspect <id> --json`, then read its build evidence with
+  `fimo publish logs <id> --json` before retrying. Provider logs may become
+  unavailable after the deployment is reclaimed.
+- When an approved preview deploy fails, capture `fimo logs --json` before
+  replacing or retrying the sandbox. Repair from that evidence, then make one
+  bounded retry.
 
 ## Behavior
 

package/assets/skills/fimo-studio/references/ai-chat.md

@@ -22,7 +22,7 @@ Give the AI more to work with:
 - **+ button**: Opens a dropdown with options:
   - **Attach Assets** -- browse your media library and attach files.
   - **Attach Entries** -- attach CMS content for the AI to reference.
-  - **Upload from Computer** -- upload a new file directly.
+  - **Upload from Computer** -- upload a file directly. ZIP archives are supported up to 20 MiB; the AI can download and inspect them under `/tmp` in its sandbox while the original stays attached to the conversation.
   - **Draw** -- opens the drawing tool where you can sketch a wireframe or layout idea for the AI to follow.
 - **@ mentions**: Type **@** in the chat to reference specific files, pages, or content inline.
 

package/dist/cli/bundle.json

@@ -1,8 +1,8 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-08-20T15:31:22.295Z",
-  "cliVersion": "0.18.0",
+  "bundledAt": "2026-08-21T16:17:31.344Z",
+  "cliVersion": "0.20.0",
   "external": [
     "oxc-parser",
     "fsevents",