fimo 0.16.0-staging.3 → 0.16.0-staging.5

package/assets/astro/components/DateTime.astro

@@ -0,0 +1,22 @@
+---
+import { getFimoSource } from 'fimo/astro';
+
+interface Props {
+  value: globalThis.Date | String | string | number | null | undefined;
+  locale?: string;
+  options?: Intl.DateTimeFormatOptions;
+  [key: string]: unknown;
+}
+
+const { value, locale, options, ...props } = Astro.props;
+const rawValue = value instanceof String ? value.toString() : value;
+const date = rawValue == null ? null : new globalThis.Date(rawValue as string | number | globalThis.Date);
+const validDate = date && !Number.isNaN(date.getTime()) ? date : null;
+// The whole instant, not just the day: a `datetime` field exists to name a
+// moment, and truncating it here would throw the time away on every page.
+const dateTime = validDate?.toISOString();
+const content = validDate?.toLocaleString(locale, options ?? { dateStyle: 'medium', timeStyle: 'short' });
+const source = getFimoSource(value);
+---
+
+{validDate && <time {...props} datetime={dateTime} data-fimo-source={source}>{content}</time>}

package/assets/astro/components/index.d.ts

@@ -1,5 +1,6 @@
 export { default as Boolean } from './Boolean.astro';
 export { default as Date } from './Date.astro';
+export { default as DateTime } from './DateTime.astro';
 export { default as Image } from './Image.astro';
 export { default as Json } from './Json.astro';
 export { default as RichText } from './RichText.astro';

package/assets/astro/components/index.js

@@ -1,5 +1,6 @@
 export { default as Boolean } from './Boolean.astro';
 export { default as Date } from './Date.astro';
+export { default as DateTime } from './DateTime.astro';
 export { default as Image } from './Image.astro';
 export { default as Json } from './Json.astro';
 export { default as RichText } from './RichText.astro';

package/assets/content-templates/shared/types.eta

@@ -97,6 +97,7 @@ function getTypeForField(field) {
     case 'boolean':
       return 'FimoBoolean';
     case 'date':
+    case 'datetime':
       return 'string';
     case 'json':
       return 'Record<string, any>';
@@ -126,6 +127,7 @@ function getInputTypeForField(field) {
     case 'boolean':
       return 'boolean';
     case 'date':
+    case 'datetime':
       return 'string';
     case 'json':
       return 'Record<string, unknown>';

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

@@ -15,7 +15,7 @@ This skill describes **what the CLI does and the workflows it drives**. For the
 
 Use `fimo <command> --help` for full flag details on any command.
 
-> **Webhooks are beta.** Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
+> Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
 
 ## Running the CLI
 
@@ -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.
 
@@ -75,7 +75,8 @@ Keep `fimo validate --json` at the front of the project's `build` script, which
 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.
 
 - "Create a new Fimo project / scaffold a site / start a new website / add the opt-in content starter / link an existing project locally" → `references/init.md`
-- "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ run `fimo skills get fimo-code --ref content/schema` and load the detected framework reference**
+- "Add a content type / blog / products / content schemas / CMS" → `references/content.md` (workflow) **+ run `fimo skills get fimo-code --ref content/schema` and load the detected framework reference**
+- "Declare Pages routes / configure Pages sources or route params / control what Studio shows for a route" → `references/pages.md`
 - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ run `fimo skills get fimo-code --ref forms` for the JSON spec and generated client**
 - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
 - "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ run `fimo skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**
@@ -117,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`.
@@ -131,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/content.md

@@ -2,12 +2,12 @@
 
 > Package contract: load the version-locked `fimo-code` skill with `fimo skills get fimo-code`, then fetch its nested content and detected-framework references for schema JSON, entry values, generated clients, and imports.
 
-This file covers the **CLI workflow** for content. Use it when the user wants to add a content type (blog, products, pages) or manage Singles and entries.
+This file covers the **CLI workflow** for content schemas, Singles, and entries. Use it when the user wants to add a content type (blog, products, reusable content) or manage content records. For route metadata shown in Studio Pages, load `references/pages.md`.
 
 ## Choose the write path first
 
 - Exactly one homepage, settings document, About page, or campaign page → declare `"isSingleton": true` and write it with `fimo singles update <TypeName>`.
-- Repeated posts, products, team members, or reusable pages → keep a collection and create rows with `fimo entries create <TypeName>`.
+- Repeated posts, products, team members, or other reusable records → keep a collection and create rows with `fimo entries create <TypeName>`.
 
 Never remove `isSingleton: true` merely because `fimo entries create` rejects the type. `entries` and `singles` are separate command namespaces; inspect `fimo singles --help` when the content is one-off.
 

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`.
 
@@ -118,6 +121,8 @@ curl -H 'Accept: text/markdown' https://your-site/  # content negotiation
 curl https://your-site/?format=md                # query param
 ```
 
+This is a hosting capability: Fimo generates the `.md`, content-negotiation, and `?format=md` responses for supported built pages. Application code must not reimplement any of them — in particular, never add a route that fetches the app's own public URL to convert it to Markdown. For a dynamic page, render Markdown from the same server-side data the page itself uses when the framework supports that; otherwise report the capability as unresolved instead of building a self-fetching route.
+
 ## Recovering from Git drift
 
 Most stale states are caught before deploy changes or commits files. Follow the emitted hint: clean a dirty checkout, or reconcile a diverged branch. A push can still lose a race if the remote advances after preflight:

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

@@ -72,9 +72,16 @@ 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
@@ -93,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.
@@ -128,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
 
@@ -152,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

@@ -19,17 +19,13 @@ These commands update the selected Branch through the locale lifecycle API. The
 
 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/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,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-cli/references/webhooks.md

@@ -1,6 +1,6 @@
 # Outbound webhooks
 
-> **Beta:** Test each destination and inspect its delivery history before depending on it in production.
+> Test each destination and inspect its delivery history before depending on it in production.
 
 Use `fimo webhooks` to send project events to external HTTPS endpoints. The CLI and Studio edit the same project-wide configurations and delivery history. The CLI has no provider presets: inspect the destination's API documentation, then pass its URL, headers, and JSON body explicitly.
 

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

@@ -14,6 +14,12 @@ Use this skill for code that consumes the version-locked `fimo` package in the c
 
 Use the project-installed CLI for local inspection, code generation, and validation (`pnpm exec fimo`, `npm exec fimo`, `yarn fimo`, or `bunx --no-install fimo`, matching the lockfile). If that runner tries to install packages even though dependencies already exist, invoke the local `node_modules/.bin/fimo` executable instead. Load the `fimo-cli` skill for remote operational workflows such as schema pushes, label writes, entry mutations, and deploys. If the skill is not already available locally, fetch it with `npx fimo@latest skills get fimo-cli`.
 
+Fimo API values may be class-backed tracked objects, not plain JSON. Keep them
+as-is on the server. Before passing them to a `'use client'` prop or a
+plain-JSON consumer such as Markdown, RSS, or JSON-LD, use the generated
+serializer and hydrate them in the client when the generated client requires
+it. Load the framework reference for the exact boundary.
+
 ## Orient before writing
 
 1. Run the project-installed `fimo describe --json` in a linked project and read `data.framework.slug`, schemas, locales, and tree. If the project is not linked yet, inspect `package.json` and the app directory instead.
@@ -35,6 +41,10 @@ Framework routing:
 - Nuxt, Remix, Vue, or another hosting-only setup → `references/frameworks/hosting.md`. Do not invent an SDK adapter that the installed package does not export.
 - No framework (static generator, plain HTML, a build script) → `references/frameworks/hosting.md` § `runtime`: leave `runtime.framework` unset.
 
+For public-site performance or navigation work, also load the matching
+`references/best-practices/astro.md`, `references/best-practices/sveltekit.md`,
+or `references/best-practices/next.md` reference.
+
 When a project's framework version is uncertain, load
 `references/frameworks/compatibility.md`. Use the project's installed version
 and the documented adapter range; do not assume that a framework profile means
@@ -60,6 +70,7 @@ Each reference defines one package contract. Fetch it when the task reaches that
 - Media values, `<Image>`, `<StaticImage>` → `references/assets.md`
 - Static editable copy: `Label`, `t()`, providers, and server label readers → `references/labels.md`
 - Locale ownership and framework handoff → `references/locales.md`
+- Upgrading a React Router app that imports `fimo/react-router/routes` → `references/migrations/react-router-route-ownership.md`
 - Astro connector and output/adapter contract → `references/frameworks/astro.md`
 - Framework detection, production routing, and hosting adapters → `references/frameworks/hosting.md`
 - Major visual work → `references/design.md`

package/assets/skills/fimo-code/assets/react-router-locales/LocaleLayout.tsx

@@ -0,0 +1,12 @@
+import { FimoProviders } from 'fimo/react-router';
+import { Outlet, useParams } from 'react-router';
+
+export default function LocaleLayout() {
+  const { locale } = useParams();
+
+  return (
+    <FimoProviders locale={locale}>
+      <Outlet />
+    </FimoProviders>
+  );
+}

package/assets/skills/fimo-code/assets/react-router-locales/routes.ts

@@ -1,11 +1,12 @@
 import type { RouteConfig } from '@react-router/dev/routes';
-import { index, route } from '@react-router/dev/routes';
-import { fimoRoutes } from 'fimo/react-router/routes';
+import { layout, route } from '@react-router/dev/routes';
 
 const routes = [
-  index('./pages/Index.tsx', { id: 'home' }),
-  route('pricing', './pages/Pricing.tsx', { id: 'pricing' }),
-  route('blog/:slug', './pages/BlogPost.tsx', { id: 'blog-post' }),
+  layout('./pages/LocaleLayout.tsx', [
+    route(':locale?', './pages/Index.tsx', { id: 'home' }),
+    route(':locale?/pricing', './pages/Pricing.tsx', { id: 'pricing' }),
+    route(':locale?/blog/:slug', './pages/BlogPost.tsx', { id: 'blog-post' }),
+  ]),
 ] satisfies RouteConfig;
 
-export default fimoRoutes(routes) satisfies RouteConfig;
+export default routes;