fimo 0.17.0 → 0.19.0

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;

package/assets/skills/fimo-code/references/best-practices/astro.md

@@ -0,0 +1,47 @@
+# Astro website best practices
+
+Load `references/frameworks/astro.md` first.
+
+- Put the document shell, navigation, and shared metadata in a layout.
+- Render the H1, primary copy, canonical, and crawlable links in the initial HTML.
+- Pass tracked Fimo values intact to Fimo components; use `String(value)` only for attributes and URLs. Flattening removes Studio's edit target.
+- Start independent Fimo reads with `Promise.all`; do not repeat page reads in children.
+- Ship no client JavaScript for static content. Use `client:visible` or `client:idle` below the fold; reserve `client:load` for immediately required interaction.
+- Use `server:defer` only for slow, secondary, or personalized UI, with a stable fallback. Keep primary content and metadata outside server islands.
+- Prerender when rebuild freshness is acceptable; render on demand when edits must appear immediately.
+- Give images dimensions; eagerly load only the likely LCP image.
+- Return a real 404 for a missing slug. Build one canonical from the public origin and normalized route, never the preview host.
+
+## Consider incremental static builds
+
+For Astro 7.2+ sites with many `getStaticPaths()` pages:
+
+```js
+import { defineConfig } from 'astro/config';
+import { fimo } from 'fimo/astro/config';
+
+export default defineConfig({
+  integrations: [fimo()],
+  experimental: { incrementalBuild: true },
+  build: { concurrency: 1 },
+});
+```
+
+```astro
+export async function getStaticPaths() {
+  const { items } = await Story.list({ limit: 100 });
+  return items.map((story) => ({
+    params: { slug: String(story.slug) },
+    props: { story },
+    cacheKey: story.updatedAt,
+  }));
+}
+```
+
+- The `cacheKey` must change for every rendered data dependency, including shared labels, settings, and related entries. A slug is not an invalidation key.
+- Persist `node_modules/.astro/` between builds. Use `astro build --force` after middleware changes or to ignore the cache.
+- Keep build concurrency at `1`. Pages with server islands also need a stable `ASTRO_KEY`.
+
+Verify production HTML, valid and missing slugs, canonical output, shipped scripts, API waterfalls, and image sizing. For incremental builds, prove one unchanged and one invalidated path.
+
+Sources: [incremental builds](https://docs.astro.build/en/reference/experimental-flags/incremental-build/) and [server islands](https://docs.astro.build/en/guides/server-islands/).

package/assets/skills/fimo-code/references/best-practices/next.md

@@ -0,0 +1,42 @@
+# Next.js website best practices
+
+Load `references/frameworks/next.md` and the matching router reference first. Instant Navigations apply only to Next 16.3+ App Router projects.
+
+- Use Server Components by default and keep Client Components at interactive leaves.
+- Keep root layouts cheap; put slow page-specific Fimo reads in the page or a nested component.
+- Start independent reads together. Server Components should call generated Fimo modules directly, not application Route Handlers.
+- Keep tracked Fimo values intact in Server Components. Use generated `serialize()`/`hydrate()` at JSON prop boundaries. Generated client hooks are already hydrated; pass their values directly to Fimo components.
+- Render the H1, primary copy, canonical, and crawlable links in the server result. Do not repeat the read after hydration.
+- Give images dimensions; prioritize only the likely LCP image.
+
+## Instant Navigations
+
+```ts
+import type { NextConfig } from 'next';
+import { withFimo } from 'fimo/next/config';
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,
+  partialPrefetching: true,
+};
+
+export default withFimo(nextConfig);
+```
+
+Choose per blocking Fimo read:
+
+- **Stream:** use `Suspense` for fresh or slow data. Prefer this when Studio edits must appear immediately.
+- **Cache:** use `use cache` only with a publication-aware lifetime and tag invalidation.
+- **Block:** set `instant = false` as low as possible when partial UI is misleading.
+
+Keep default `<Link>` prefetching. Use `prefetch={true}` only for a few high-intent links; large lists can overload the content API. Prefetch rendering must be side-effect free.
+
+Use `instant = true` to find blocking code, then verify with `next build` and `next start`; development does not prefetch. Inspect the shell and streams with Navigation Inspector.
+
+- Call `notFound()` for a missing slug.
+- Build one canonical from `metadataBase` and the normalized route, never the preview host.
+- Avoid duplicate content reads between `generateMetadata` and the page.
+
+Verify valid and missing slugs, canonical and initial HTML, shipped JavaScript, duplicate reads, image sizing, instant shell rendering, streaming, freshness, and bounded prefetching.
+
+Sources: [Instant Navigations](https://nextjs.org/blog/next-16-3-instant-navigations), [`partialPrefetching`](https://github.com/vercel/next.js/blob/canary/docs/01-app/03-api-reference/05-config/01-next-config-js/partialPrefetching.mdx), and [`instant`](https://github.com/vercel/next.js/blob/canary/docs/01-app/03-api-reference/03-file-conventions/02-route-segment-config/instant.mdx).

package/assets/skills/fimo-code/references/best-practices/sveltekit.md

@@ -0,0 +1,17 @@
+# SvelteKit website best practices
+
+Load `references/frameworks/sveltekit.md` first.
+
+- Keep shared navigation, labels, and metadata in layouts; keep slow page data in the narrowest `+page.server.ts` or `+layout.server.ts`.
+- Pass the request `event`. Serialize generated Fimo values at the load boundary and render them with Fimo components, which restore their Studio editing metadata. Do not flatten tracked values first.
+- Start independent reads together. Use `await parent()` only for a real parent-data dependency.
+- Await primary content. Stream only slow, non-essential promises; add a stable `{#await}` fallback, an error branch, and an early rejection handler when the promise does not use SvelteKit's `fetch`.
+- Render the H1, primary copy, canonical, and crawlable links during SSR. Do not disable SSR or repeat the read after hydration.
+- Keep browser JavaScript at interactive leaves.
+- Use request-time loads when edits must appear immediately. Prerender or cache only when rebuild or invalidation behavior is explicit.
+- Give images dimensions; eagerly load only the likely LCP image.
+- Call `error(404, ...)` for a missing slug. Build one canonical from the configured public origin and normalized route, never the preview host.
+
+Verify the production server response, valid and missing slugs, canonical output, streamed errors, shipped JavaScript, API waterfalls, and image sizing.
+
+Source: [SvelteKit load and streaming](https://svelte.dev/docs/kit/load).

package/assets/skills/fimo-code/references/content/richtext.md

@@ -26,6 +26,11 @@ Marks: `bold`, `italic`, `underline`, `strike`, `code`, and `link`.
 
 Use semantic nodes instead of flattening long content into paragraphs. Render the returned value with the framework's `<RichText>` primitive so source metadata survives.
 
+Richtext and other API values may carry class-backed tracking metadata. Values
+rendered by server Fimo primitives can stay intact. Serialize them before a
+plain-JSON consumer (Markdown, RSS, JSON-LD) or a client prop, then use the
+generated client hydration helper where required.
+
 ## Entry payload
 
 CLI entry writes put every value, including the collection slug, under `data`:

package/assets/skills/fimo-code/references/content/schema.md

@@ -56,12 +56,15 @@ Never declare `id`, `entryId`, `documentId`, `slug`, `locale`, `createdAt`, `upd
 | `richtext`  | Tiptap JSONContent         | formatted content                        |
 | `number`    | number                     | quantities and ordering fields           |
 | `boolean`   | boolean                    | flags                                    |
-| `date`      | ISO date string            | dates/timestamps                         |
+| `date`      | ISO date string            | calendar days; loose about the form      |
+| `datetime`  | ISO instant with offset    | exact moments (`2026-08-13T09:30:00Z`)   |
 | `media`     | media object or array      | images, video, files                     |
 | `json`      | JSON                       | structured metadata                      |
 | `reference` | `{ "id": "..." }` or array | links to another schema                  |
 | `blocks`    | ordered object array       | nested/repeatable sections               |
 
+A `datetime` value must carry `Z` or `±HH:MM`; a bare day or a naive local time is rejected. Render it with `<DateTime>`, which keeps the whole instant in the `<time datetime>` attribute, and a `date` with `<Date>`. `unique` is not supported on `datetime`.
+
 An enum string uses `options`; its optional `default` must be one of them:
 
 ```json

package/assets/skills/fimo-code/references/frameworks/astro.md

@@ -73,7 +73,7 @@ const [settings, stories, labels] = await Promise.all([
 }
 ```
 
-The native surface is `Text`, `RichText`, `Image`, `StaticImage`, `Video`, `Date`, `Boolean`, and `Json` (component table: `references/ui.md`). Pass tracked values whole so Studio can resolve their source; use `String(value)` only for attributes and URLs.
+The native surface is `Text`, `RichText`, `Image`, `StaticImage`, `Video`, `Date`, `DateTime`, `Boolean`, and `Json` (component table: `references/ui.md`). Pass tracked values whole so Studio can resolve their source; use `String(value)` only for attributes and URLs.
 
 ## Forms
 
@@ -107,11 +107,13 @@ export async function getStaticPaths() {
 
 ## Locales
 
-The application resolves the locale — route prefix, middleware, domain, `Astro.currentLocale`, cookie, or its i18n library — and passes it to content reads and `getLabels({ locale })`. When a server read omits `locale`, the Fimo API resolves the project default; do not hardcode a fallback locale in application code. Astro needs no Fimo locale provider. Ownership rules: `references/locales.md`.
+Configure Astro i18n from `.fimo/config.json#i18n` and use `Astro.currentLocale` for content reads, `getLabels({ locale })`, and `<html lang>`. The standard starter keeps the configured default locale unprefixed and prefixes the others. Existing applications may instead resolve locale through middleware, domains, cookies, or another application-owned strategy. Astro needs no Fimo locale provider. Ownership rules: `references/locales.md`.
+
+The new-project shell pairs unprefixed default-locale pages with a parallel `[locale]` tree because Astro has no optional single-segment page filename. Add locales in `.fimo/config.json`; Astro's native i18n router validates the prefixed tree. Route metadata uses `/:locale` with `params.locale.optional: true`; Astro page files remain authoritative.
 
 ## Studio route catalog
 
-`.fimo/config.json#routes` is an optional catalog of pages for Studio navigation, not router configuration. Never replace or infer Astro's route files, redirects, middleware, or 404 behavior from it. Keep paths canonical and unlocalized, and describe dynamic segments with `params` so Studio can list entries:
+`.fimo/config.json#routes` is an optional catalog of pages for Studio navigation, not router configuration. Never replace or infer Astro's route files, redirects, middleware, or 404 behavior from it. Keep routes without locale ownership canonical and unlocalized. For a locale-aware route, declare the reserved `/:locale` segment and mark it optional in `params`; describe other dynamic segments with `params` so Studio can list entries:
 
 ```json
 {

package/assets/skills/fimo-code/references/frameworks/hosting.md

@@ -49,9 +49,12 @@ Locally, the app derives its env from the **git branch**: `fimo/vite`,
 API URL from `.fimo/project.json`
 (`projectId` + `tenantApiBaseUrl`, recorded once at `init`/`clone`/`link`) and
 expose the Vite, Next and public (`PUBLIC_*`) aliases plus `FIMO_ENV` /
-`NEXT_PUBLIC_FIMO_ENV` at startup. No env file is written on a switch, so a plain `git checkout` is a
+`NEXT_PUBLIC_FIMO_ENV` at startup. The Vite connectors derive them during both
+dev and production builds, and `withFimo` derives them in `next dev`, `next
+build`, and `next start`, so a linked project builds and serves locally without
+exporting them by hand. No env file is written on a switch, so a plain `git checkout` is a
 complete env switch. Never hardcode a tenant URL in application source. One
-rule, per variable: a value the user set explicitly (`.env`, shell, their own
+rule, per variable: a non-empty value the user set explicitly (`.env`, shell, their own
 `define`) is left alone, and Fimo fills the variables they did not set.
 
 For a framework whose alias is not in that list yet, preserve or add its normal

package/assets/skills/fimo-code/references/frameworks/next/app-router.md

@@ -76,6 +76,12 @@ This example demonstrates request-time rendering, not a recommended locale polic
 
 ## Client Components
 
+When a Server Component passes Fimo content into a Client Component, it MUST
+serialize with the generated server module and the Client Component MUST
+hydrate with the matching generated `.client` module. Do not pass a raw Fimo
+value merely because its enumerable fields look JSON-safe. No conversion is
+needed while the value stays inside server rendering.
+
 Client Components use the generated `.client` module and `fimo/next/client`:
 
 ```tsx

package/assets/skills/fimo-code/references/frameworks/next/locales.md

@@ -33,6 +33,16 @@ When labels are not needed at that boundary, use `<FimoProvider locale={locale}>
 - Pages Router i18n: reuse `context.locale` in data functions and `router.locale`/page props on the client.
 - Default-only app: omit locale arguments and let Fimo use `.fimo/config.json#i18n.defaultLocale` (fallback `en`).
 
+## New-project boundary
+
+Choose the primary locale from the user's request before building pages. Put the first explicitly requested locale in `.fimo/config.json#i18n.defaultLocale` and keep all requested locales in `i18n.locales`. That edit is the whole locale setup: `src/locales.ts` reads the file, so the default locale passed to `FimoProvider`, the `<html lang>` of each tree, and the set of prefixed URLs follow it. If the user gives no locale signal, keep `en` and state that choice. Never add `NEXT_PUBLIC_FIMO_DEFAULT_LOCALE` or `FIMO_DEFAULT_LOCALE`; the runtime ignores them by design.
+
+The starter keeps default routes in an unprefixed `app/(default)` route group and a native `app/[locale]` tree for the other locales. Only a root layout may render `<html>`, so each tree owns its root layout and renders the shared `src/components/Document.tsx` with its locale: the unprefixed tree with `defaultLocale`, the prefixed tree with `params.locale`. The prefixed layout 404s a locale that is not in `prefixedLocales`, which is why the default locale has exactly one URL. For `/:locale/pricing`, `params.locale.optional: true` means omit the configured default locale: with `i18n.defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French. With `optional: false`, both `/en/pricing` and `/fr/pricing` are prefixed. The default locale value chooses the fallback locale; `optional` independently controls URL prefixes. A route without `:locale` remains application-owned.
+
+Next.js has no optional single-segment route folder, so mirror localized routes in both existing groups as the site grows. Astro uses the same paired native filesystem-tree shape for this semantic. Do not replace the trees with middleware, rewrites, an optional catch-all that captures the application route tree, or a Fimo route helper. The config route catalog describes the URL shapes for Studio; Next's `app` directory remains authoritative.
+
+Keep the starter's client-only `src/components/FimoPreviewBridge.tsx` inside `Document`, so both trees mount it. It reads Next's native pathname/router, reports the settled locale to Studio, and lets Studio navigate through Next; do not move Next imports into Fimo's shared runtime.
+
 With `next-i18next`, keep its routing and translation provider for the strings it owns. Pass the same resolved locale to Fimo; do not replace the library or duplicate its route structure.
 
 Before creating non-default Fimo labels or content variants, confirm that those locales are enabled for the linked Fimo project. Load `fimo-cli` with its `locales` reference and run `fimo locales add <locale> --yes --json`; `.fimo/config.json` documents the application's locale policy, but `fimo validate` does not add project locales.
@@ -54,6 +64,6 @@ Fimo owns:
 - client content/label context after receiving the locale;
 - editable source metadata.
 
-Do not add `.fimo/config.json#routes` to a Next project yet. The current route-metadata validator expects React Router's `src/routes.ts`; a first-class Next Studio catalog and preview bridge are separate product work. Do not create a fake `src/routes.ts` to satisfy that check.
+The new-project shell includes a small `.fimo/config.json#routes` catalog for Studio. It describes the page URLs but does not configure the App Router. Keep the `app` directory authoritative, and do not create a fake `src/routes.ts` or a universal Fimo route helper.
 
-Do not introduce `[locale]` segments, cookie routing, or domain routing unless the product request requires that URL strategy. Do not add a second locale provider when the existing one can supply the resolved locale to Fimo.
+Do not introduce new locale middleware, cookie routing, or domain routing unless the product request requires that URL strategy. Do not add a second locale provider when the existing one can supply the resolved locale to Fimo.

package/assets/skills/fimo-code/references/frameworks/next.md

@@ -82,6 +82,13 @@ Never write the registry by hand and never create alternate `*.schema.json` file
 
 ## Server and client boundaries
 
+Next.js MUST receive generated serialized values across every Server-to-Client
+Component prop boundary. Fimo values may be class-backed even when they look
+JSON-shaped. Values that stay in Server Components may stay intact; values for
+Client Components use the generated server `serialize()` and client
+`hydrate()`. Plain-JSON outputs such as Markdown, RSS, and JSON-LD also use the
+generated serialization rather than `JSON.stringify` as a conversion strategy.
+
 Forms follow the same boundary. Server actions and route handlers import the
 generated server form module; a Client Component imports its generated
 `.client.ts` module. Both expose `submitX(data)` and use the shared Fimo form

package/assets/skills/fimo-code/references/frameworks/react-router.md

@@ -85,18 +85,24 @@ Keep the application's existing `Layout` details. Add only the Fimo provider and
 
 ## Routes and locales
 
-`fimoRoutes()` is an optional helper for Fimo's path-prefix locale convention:
+React Router owns locale paths. Declare the optional locale segment directly so the default locale stays unprefixed:
 
 ```ts
 import type { RouteConfig } from '@react-router/dev/routes';
-import { index } from '@react-router/dev/routes';
-import { fimoRoutes } from 'fimo/react-router/routes';
-
-const routes = [index('./pages/Index.tsx', { id: 'home' })] satisfies RouteConfig;
-export default fimoRoutes(routes) satisfies RouteConfig;
+import { layout, route } from '@react-router/dev/routes';
+
+export default [
+  layout('./pages/LocaleLayout.tsx', [
+    route(':locale?', './pages/Index.tsx'),
+    route(':locale?/pricing', './pages/Pricing.tsx'),
+    route(':locale?/blog/:slug', './pages/BlogPost.tsx'),
+  ]),
+] satisfies RouteConfig;
 ```
 
-Custom locale routers can skip it and pass their resolved locale to `<FimoProviders locale={locale}>`. Use `FimoLink` only when the application adopts Fimo's locale-aware link behavior; otherwise preserve its links. Copyable path-prefix locale examples live in `assets/react-router-locales/`.
+Read `locale` in an application layout and pass it to `<FimoProviders locale={locale}>`; omission resolves the configured default. Copy `assets/react-router-locales/routes.ts` and `LocaleLayout.tsx` for a complete boundary. For multilingual apps, move the root provider there instead of nesting providers. Preserve an existing locale library, and use `FimoLink` only when its locale-preserving behavior matches the app.
+
+If an existing project imports `fimo/react-router/routes`, load `references/migrations/react-router-route-ownership.md` before changing it.
 
 ## Content and labels
 
@@ -122,6 +128,8 @@ Declare the runtime in `.fimo/config.json`:
 
 The optional `routes` object is Studio's semantic page catalog. Keep it aligned with application routes when the project uses Studio navigation, but do not treat it as the production router.
 
+For new projects, apply `references/locales.md`, keep the starter's `:locale?` route, and describe it in Studio metadata as `/:locale` with `params.locale.optional: true`.
+
 ## Boundaries
 
 - Route modules and `meta` exports own routing and SEO.

package/assets/skills/fimo-code/references/frameworks/sveltekit.md

@@ -74,24 +74,27 @@ do not import a Fimo environment variable or hardcode a tenant URL:
 // src/routes/+layout.server.ts
 import { getLabels } from 'fimo/sveltekit';
 
-export async function load(event) {
-  // If the app resolves a locale from its URL or session, pass it:
-  // const locale = resolveLocale(event.url); // your app's resolver
-  // return { labels: await getLabels({ event, locale }) };
+import { resolveLocale } from '../locales';
 
-  // Otherwise, omit it and use the Fimo project default.
-  return { labels: await getLabels({ event }) };
+export async function load(event) {
+  const locale = resolveLocale(event.params);
+  return { locale, labels: await getLabels({ event, locale }) };
 }
 ```
 
 ```svelte
 <!-- src/routes/+layout.svelte -->
 <script lang="ts">
+  import { afterNavigate } from '$app/navigation';
   import { FimoProvider } from 'fimo/sveltekit/components';
   import type { LayoutData } from './$types';
   import type { Snippet } from 'svelte';
 
   let { data, children }: { data: LayoutData; children: Snippet } = $props();
+
+  afterNavigate(() => {
+    document.documentElement.lang = data.locale;
+  });
 </script>
 
 <FimoProvider labels={data.labels}>
@@ -101,7 +104,7 @@ export async function load(event) {
 
 Generated values are serialized at a `load` boundary and hydrated in the
 component that renders them. Use `Text`, `RichText`, `Image`, `Video`, `Date`,
-`Boolean`, `Json`, and `Number` from `fimo/sveltekit/components`. `Number`
+`DateTime`, `Boolean`, `Json`, and `Number` from `fimo/sveltekit/components`. `Number`
 formats plain numeric values for display; numeric fields currently have no
 source metadata, so it is not a Studio-editable primitive.
 
@@ -128,7 +131,7 @@ export const actions = {
 `PUBLIC_FIMO_PREVIEW_SCRIPT_URL` from SvelteKit's dynamic public environment,
 loads that script once, delegates navigation to SvelteKit's `goto`, and
 refreshes data with `invalidateAll()`. Without that environment value it does
-nothing. Do not add a Fimo server hook or a second preview component.
+nothing. Do not add a second preview component.
 
 ## Boundaries
 
@@ -136,3 +139,7 @@ nothing. Do not add a Fimo server hook or a second preview component.
 - `fimo/sveltekit/vite` owns dev source tagging only.
 - `FimoProvider` owns labels and the optional Studio preview bridge.
 - Do not add React, React Query, or a Vite SPA fallback to a SvelteKit project.
+
+The starter uses SvelteKit's native `[[locale=locale]]` boundary and a matcher limited to configured, non-default locales, so unrelated top-level paths are not locales. `src/locales.ts` derives the default and prefixed set from `.fimo/config.json` and owns the shared locale resolver. Keep passing the tracked `event.params` object into that resolver from the root server layout so locale-crossing client navigation reruns labels.
+
+For accessibility, SvelteKit's documented multilingual pattern renders `<html lang="%lang%">` through `src/hooks.server.ts#transformPageChunk`. The root layout updates the attribute after client navigation. Keep those seams aligned with the application's locale resolver. Keep `[[locale=locale]]` for an unprefixed default; use `[locale=locale]` only when every locale must be prefixed.

package/assets/skills/fimo-code/references/labels.md

@@ -32,7 +32,7 @@ const items = [
 
 Do not use variables or interpolated expressions as label keys. Namespace literal keys by page/section/component, such as `hero.title`, `nav.signIn`, or `contact.form.submit`.
 
-Missing keys render as an empty tracked value. Run `fimo validate`, then create values with `fimo labels set` or `set-many`; do not add fallback copy to code.
+Missing keys render as an empty tracked value. Run `fimo validate`, then create values with `fimo labels set` or `set-many`; do not add fallback copy to code (the one exception is a component that cannot mount under the provider — see "Provider mount" below).
 
 ## Framework adapters
 
@@ -46,6 +46,14 @@ The label contract is shared; acquisition differs by runtime:
 
 Load the matching framework reference before choosing a provider or server reader.
 
+## Provider mount
+
+Components that render `Label` or call `useLabels()` MUST be mounted below the framework's `FimoProvider` (or the framework integration that supplies label context). Globally mounted components — cookie banners, toasts, consent dialogs injected near the document root — are the common escapees: outside the provider they render blank labels with no error.
+
+If a component genuinely cannot be moved under the provider, use an explicit hardcoded, non-editable fallback and report that tradeoff to the user. Never ship silently blank copy.
+
+When a label renders empty, check in order: (1) the key exists (`fimo validate`, `fimo labels list`), (2) the active locale has a value, (3) the component is under the provider. Add fallback copy only after those checks, and only in the cannot-mount case above.
+
 ## Locale behavior
 
 `.fimo/config.json#i18n.defaultLocale` selects the default (fallback `en`). The application resolves the active locale and gives it to the framework adapter. Create explicit label values for each configured locale the product supports.

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

@@ -13,7 +13,9 @@ The application owns locale resolution and routing. Fimo consumes the resolved l
 }
 ```
 
-Keep one locale unless the product asks for multilingual output. Locale tags should be structurally valid, such as `en`, `pt-BR`, or `zh-Hans`.
+For new projects, derive the primary locale from the request; when several are explicit, the first one named is the default. Update `i18n.defaultLocale`, `i18n.locales`, the framework-native route boundary and matcher, and the document language default. If the user gives no locale signal, retain the starter default and state that choice.
+
+Keep one locale unless the product asks for multilingual output. Keep it locale-ready without forcing `/en`, a language switcher, global path-prefix routing, or localized schemas. Locale tags should be structurally valid, such as `en`, `pt-BR`, or `zh-Hans`.
 
 For an already linked project, enable each locale in Fimo before writing non-default label or content variants. Load `fimo-cli` with its `locales` reference and run `fimo locales add <locale> --yes --json`; local config and `fimo validate` do not provision project locales. Do not change the application's route strategy to work around a missing locale.
 
@@ -22,6 +24,8 @@ For an already linked project, enable each locale in Fimo before writing non-def
 - Resolve locale from its router, route parameters, domain, request headers, middleware, cookie, existing i18n library, or user preference.
 - Keep its existing public URLs, redirects, links, `<html lang/dir>`, and SEO behavior.
 - Pass the resolved locale to Fimo's server reads and client provider.
+- Keep the default locale separate from the URL prefix policy. `optional: true` means omit the configured default locale from the URL: with `defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French. With `optional: false`, every locale is prefixed (`/en/pricing` and `/fr/pricing`).
+- Treat routes without a `:locale` segment as application-owned. Fimo does not add or interpret a locale prefix for them.
 - Treat any optional Studio route catalog as framework-adapter-specific; load the framework reference before creating or changing one.
 
 ## Fimo responsibilities
@@ -39,4 +43,6 @@ For an already linked project, enable each locale in Fimo before writing non-def
 - React Router standard locale routing → load `references/frameworks/react-router.md`.
 - Vite + React/custom React router → load `references/frameworks/vite-react.md` and pass locale through its existing provider seam.
 
-Do not replace an existing locale system merely to add Fimo. Do not duplicate localized routes in the Studio catalog. Do not assume Fimo's route helpers are universal framework APIs.
+Do not replace an existing locale system merely to add Fimo. Do not duplicate localized routes in the Studio catalog. Every framework resolves its active locale and passes it to Fimo through that framework's provider or server-read seam.
+
+Astro and Next implement an optional locale boundary with paired native filesystem route trees: one unprefixed tree for the default locale and one prefixed tree for the other locales. Neither framework has an optional single-segment filesystem folder.