fimo 0.16.0-staging.4 → 0.16.0-staging.5

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

@@ -60,11 +60,11 @@ 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.
 
@@ -118,7 +118,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 +132,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/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,13 +35,16 @@ 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`.
 

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/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-08-20T13:43:50.688Z",
+  "bundledAt": "2026-08-20T19:18:12.327Z",
   "cliVersion": "0.15.0",
   "external": [
     "oxc-parser",