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

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.

package/assets/skills/fimo-code/references/migrations/react-router-route-ownership.md

@@ -0,0 +1,93 @@
+# React Router locale route ownership upgrade
+
+Use this guide to move an existing project from the deprecated
+`fimo/react-router/routes` compatibility adapter to application-owned React
+Router routes. Existing projects can upgrade before completing this migration,
+but new projects should not use the adapter and a future breaking release may
+remove it.
+
+## Identify the installed contract
+
+Run the project-local CLI with the package manager selected by the lockfile:
+
+```bash
+pnpm exec fimo --version
+```
+
+Then inspect `package.json`, the lockfile, `src/routes.ts`, the locale layout or
+provider, `.fimo/config.json` (or legacy `fimo-config.json`), the language
+selector, redirects, and SEO/static-generation setup. The installed package is
+authoritative. Do not use a newer globally installed CLI to rewrite the app.
+
+Choose the path by the installed and target contracts, not by a guessed
+version number:
+
+| Installed project                     | Target project  | Action                                                                    |
+| ------------------------------------- | --------------- | ------------------------------------------------------------------------- |
+| Uses `fimo/react-router/routes`       | Current release | Upgrade safely, then follow this guide to leave the deprecated adapter.   |
+| Already uses application-owned routes | Later release   | Keep the app-owned routes; no routing migration is needed.                |
+| Uses another router or framework      | Any release     | Keep that framework's locale system and pass its resolved locale to Fimo. |
+
+The package export and `pnpm exec fimo --version` are the reliable boundary
+until release notes assign concrete version numbers.
+
+## Replace the deprecated route wrapper
+
+Remove the `fimo/react-router/routes` import and declare each localized path
+directly. React Router uses `:locale?`; route metadata uses `/:locale` with an
+optional locale descriptor:
+
+```ts
+import type { RouteConfig } from '@react-router/dev/routes';
+import { layout, route } from '@react-router/dev/routes';
+
+export default [
+  layout('./pages/LocaleLayout.tsx', [
+    route(':locale?/pricing', './pages/Pricing.tsx'),
+    route(':locale?/blog/:slug', './pages/BlogPost.tsx'),
+  ]),
+] satisfies RouteConfig;
+```
+
+Keep the public URL matrix unchanged:
+
+| URL             | route     | active locale      |
+| --------------- | --------- | ------------------ |
+| `/pricing`      | pricing   | configured default |
+| `/es/pricing`   | pricing   | `es`               |
+| `/blog/hello`   | blog post | configured default |
+| `/es/blog/hola` | blog post | `es`               |
+
+Do not add a default-locale prefix. Read the optional route locale in an
+application-owned layout and pass it to `<FimoProviders locale={locale}>`.
+When it is omitted, FimoProviders resolves the configured default locale.
+Preserve existing redirects, link behavior, document language/direction, and
+locale validation.
+
+The copyable boundary is:
+
+```tsx
+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>
+  );
+}
+```
+
+## Verify before finishing
+
+Run the project-local `fimo validate`, then verify all four URL shapes in the
+preview. Switch languages in the application selector and in Studio, and check
+that both report the same locale. Confirm canonical URLs, `hreflang`, sitemap or
+prerender output, and locale-specific metadata/content remain correct.
+
+If the installed version has no exact matching reference, preserve every
+existing public URL and routing behavior. Report the installed version, the
+pattern found, the checks completed, and any uncertainty instead of guessing a
+new route shape.

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

@@ -9,7 +9,8 @@ Use Fimo components for source-tracked schema and label values so Studio can ide
 | media as `FimoMedia`             | `Image`                        | schema media images                                                |
 | non-schema URL                   | `StaticImage`                  | decorative/static image URLs                                       |
 | media as `FimoMedia`             | `Video`                        | schema media videos                                                |
-| date as `FimoString`             | `Date`                         | schema dates                                                       |
+| date as `FimoString`             | `Date`                         | schema dates; `<time datetime>` is the calendar day                |
+| datetime as `FimoString`         | `DateTime`                     | schema instants; `<time datetime>` keeps the time                  |
 | boolean as `FimoBoolean`         | `Boolean`                      | schema booleans                                                    |
 | source-tagged plain JSON         | `Json`                         | schema JSON                                                        |
 | number                           | normal JSX; SvelteKit `Number` | numbers stay plain; SvelteKit `Number` formats display-only values |
@@ -21,6 +22,7 @@ Use Fimo components for source-tracked schema and label values so Studio can ide
 <RichText value={article.body} />
 <Image value={article.cover} width={1200} height={630} />
 <Date value={article.publishedAt} />
+<DateTime value={article.lastReviewedAt} />
 ```
 
 Pass the tracked value directly. Do not replace `<Text>` with `<h1>{article.title}</h1>`, unwrap media into raw `<img>`, or hand-roll richtext rendering.
@@ -44,7 +46,24 @@ Blocks do not change this rule. Every visible nested scalar is source-tracked to
 
 Do not render those values as `{program.title}` or `{highlight.label}`. That displays text but bypasses the primitive that Studio uses to resolve the exact nested edit target.
 
-Use `<StaticImage>` only when the image is deliberately not editor-managed. Use `String(value)` for attributes/third-party APIs that cannot accept a `FimoString`; keep editable visible text in `<Text>`.
+Use `<StaticImage>` only when the image is deliberately not editor-managed.
+
+## Wrapper values in JavaScript logic
+
+`FimoString`, `FimoBoolean`, and the other tracked values are objects, not primitives: a plain string or boolean cannot carry the source field, locale, and edit-target metadata Fimo editing needs. That gives one two-sided rule:
+
+- **MUST** pass the wrapper directly to Fimo rendering primitives (`Text`, `Boolean`, …). Unwrapping first removes the edit target.
+- **MUST** normalize the wrapper before any JavaScript comparison, condition, attribute, or third-party API: `String(value)` for strings, `value.value` (or `value.valueOf()`) for booleans.
+
+```ts
+fimoValue === 'build';         // false — an object never strict-equals a primitive
+String(fimoValue) === 'build'; // true
+
+if (fimoFlag) { … }            // always runs — an object is truthy even when the value is false
+if (fimoFlag.value) { … }      // correct
+```
+
+Keep editable visible text in `<Text>`; normalized primitives are for logic and APIs only, never a substitute for rendering through the primitive.
 
 Numeric fields stay plain JavaScript numbers, so they do not carry Studio source metadata. SvelteKit's `Number` component is an optional display/formatting helper; it is not source-editable. Other framework surfaces should render numeric fields normally until a shared tracked-number contract exists.