fimo 0.17.0 → 0.19.0

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**
@@ -84,6 +85,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`
@@ -117,7 +119,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 +133,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`.
 
@@ -57,6 +60,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.
@@ -118,6 +124,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/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

@@ -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>
+```