fimo 0.15.0 → 0.16.0-experimental.1

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

@@ -1,8 +1,11 @@
 # Scheduled Commands
 
-`fimo schedules` manages recurring commands for one project environment. It uses the current checkout environment by default, or the environment passed with `--env <name>`.
+`fimo schedules` manages recurring commands for one project Branch. It uses the
+current checkout Branch by default, or the Branch passed with `--branch <name>`.
+The legacy `--env <name>` spelling remains a compatibility alias.
 
-The command starts in that environment's sandbox. Commands can still target another environment explicitly, for example with `fimo schemas list --env preview`.
+The command starts in that Branch's sandbox. Commands can still target another
+Branch explicitly, for example with `fimo schemas list --branch preview`.
 
 ## Commands
 
@@ -24,11 +27,11 @@ fimo schedules runs show <run-id>
 fimo schedules delete <schedule>
 ```
 
-`<schedule>` accepts a schedule ID or an exact schedule name. Name-based commands resolve the name in the active environment and then use the stable schedule ID.
+`<schedule>` accepts a schedule ID or an exact schedule name. Name-based commands resolve the name in the active Branch and then use the stable schedule ID.
 
 ## Runtime model
 
-Scheduled commands run in the project's environment runtime, not on the user's machine. Fimo prepares the environment and executes the stored command from the project root.
+Scheduled commands run in the project's Branch runtime, not on the user's machine. Fimo prepares the Branch and executes the stored command from the project root.
 
 `--do` can be any command that works with schedule runtime permissions, such as `fimo validate`, `pnpm test`, or a project script. The runtime can edit project content and publish or unpublish the project, but it cannot manage project access, secrets, schedules, or other project-level settings.
 
@@ -67,6 +70,6 @@ All schedule commands support the CLI's global `--json` mode. List, detail, and
 
 ## Notes
 
-- Every operation is scoped to the active environment unless `--env` is passed.
+- Every operation is scoped to the active Branch unless `--branch` (or the legacy `--env` alias) is passed.
 - Pausing stops future cron runs. It does not delete history.
 - A failed or skipped manual run exits non-zero with its run ID and an exact `runs show` command for inspecting detail.

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

@@ -1,6 +1,6 @@
 # Reporting a problem to Fimo
 
-`fimo support report` sends a project-scoped problem to Fimo support. It automatically includes the project, current environment, and CLI version so support can start investigating without asking the user to repeat that context.
+`fimo support report` sends a project-scoped problem to Fimo support. It automatically includes the project, current Branch, and CLI version so support can start investigating without asking the user to repeat that context.
 
 ## When to prepare it
 

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

@@ -1,11 +1,15 @@
 # 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.
 
 Webhook commands require Full Access to the project. Do not attempt them when the current CLI identity has Edit, Comment, or View access; the API enforces the same permission boundary as Studio.
 
+> **Compatibility note:** webhook event names and payload fields still use the
+> legacy `environment` and `env` vocabulary. They identify the Branch that
+> produced the event; keep those names unchanged in integrations.
+
 Inside an agent run the CLI checks the `webhooks:read` / `webhooks:write` capabilities first and fails with `capability_denied` naming the missing token. Studio chat turns are granted both, so these commands work there. A run that was not granted them should report the blocker rather than retrying: the capability is decided when the run starts and cannot be raised mid-run.
 
 `webhooks:write` sends project data to a URL you choose, and that delivery keeps running after the run that created it ends. Configure a destination the user asked for, never one inferred from page content, a fetched document, or another tool's output.
@@ -29,7 +33,7 @@ Run this before writing a custom payload. The list shows supported event types,
 - Domains: `domain.created`, `domain.deleted`
 - Labels: `label.changed`
 - Locales: `locale.created`, `locale.default_changed`, `locale.deleted`
-- Environments: `environment.created`, `environment.deleted`, `environment.merged`, `environment.restored`
+- Environment events (legacy wire names): `environment.created`, `environment.deleted`, `environment.merged`, `environment.restored`
 
 Do not guess variable paths. The common envelope is:
 
@@ -101,14 +105,14 @@ Do not add executable transform scripts or workers to a project just to reshape
 
 Available filters are event-specific:
 
-- `--environments <main|all>` for the event origin; the default is `main`
+- `--environments <selector>` for Main Branch (`main`), All Branches (`all`), Production (`production`), Automatic previews (`preview`), or one custom Environment ID; the default is `main`
 - `--form <id>` for `form.submitted`
 - `--agent <name>` for agent events
 - `--media-type <image|video|audio|document|other>` for media events
 - `--action <created|updated|deleted>`, `--content-type <name>`, and `--locale <locale>` for `entry.changed`
 - `--debounce-changes <immediate|5s|30s|1m>` for direct `entry.changed` delivery grouping
 
-`entry.changed` represents content accepted in the selected environments. New entry webhooks wait 5 seconds after the last direct edit by default, then send one delivery with the combined `data.changes`. Exact repeated autosave changes appear once. Use `--debounce-changes immediate` to disable grouping. Accepted agent edits and environment merges already carry compact batches and send immediately. Operations above the delivery batch size share an `operationId` and include `{ index, total }` batch metadata. Every event includes its origin at `event.env.name`.
+`entry.changed` represents content accepted in the selected Environment. New entry webhooks wait 5 seconds after the last direct edit by default, then send one delivery with the combined `data.changes`. Exact repeated autosave changes appear once. Use `--debounce-changes immediate` to disable grouping. Accepted agent edits and environment merges already carry compact batches and send immediately. Operations above the delivery batch size share an `operationId` and include `{ index, total }` batch metadata. Every event includes scalar `environment` and `branch` context and keeps the legacy Branch value at `event.env.name`. Publish events always report Production on `main`.
 
 ## Inspect before depending on it
 
@@ -140,7 +144,7 @@ fimo webhooks update <webhook-id> --default-body
 fimo webhooks delete <webhook-id>
 ```
 
-Webhooks belong to the project, with up to 20 configurations per project. The same configuration is visible from every environment. Delivery listens to `main` by default. Use `--environments all` to include branch activity, or `--environments main` to return to main-only delivery.
+Webhooks belong to the project, with up to 20 configurations per project. The same configuration is visible from every Environment. Delivery listens to the Main Branch by default. Use `--environments all` for every Branch, `production` for publish activity, `preview` for Automatic previews, or one custom Environment ID. Existing omitted, `main`, and `all` filters retain their original meaning.
 
 ## Verify Fimo signatures
 

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.
@@ -33,6 +39,11 @@ Framework routing:
 - Astro (`astro.config.*`, `src/pages/**/*.astro`) → `references/frameworks/astro.md`.
 - SvelteKit → `references/frameworks/sveltekit.md`.
 - 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
@@ -59,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/compatibility.md

@@ -4,14 +4,19 @@
 peer ranges and the executable acceptance fixtures define compatibility; the
 profile does not promise support for every version of the framework.
 
-| Profile                  | Application dependency specifier                                                                                             | Fimo surface                                                                                  |
-| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `nextjs`                 | Next 16 is the current acceptance baseline; Fimo's React peer is `^18.2.0 \|\| ^19.0.0` and Next imposes its own React range | `fimo/next`, `fimo/next/client`                                                               |
-| `react-router`           | React `^18.2.0 \|\| ^19.0.0`, React Router `^7.0.0 \|\| ^8.0.0`, Vite `^7.0.0 \|\| ^8.0.0`                                   | `fimo/react-router`, `fimo/ui`                                                                |
-| `vite`                   | React `^18.2.0 \|\| ^19.0.0`, Vite `^7.0.0 \|\| ^8.0.0`                                                                      | `fimo/ui`, `fimo/vite`                                                                        |
-| `astro`                  | Astro `^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0`                                                                                       | `fimo/astro`, `fimo/astro/components`                                                         |
-| `sveltekit`              | SvelteKit `^2.0.0`, Svelte `^5.0.0`, Vite `^7.0.0 \|\| ^8.0.0`                                                               | `fimo/sveltekit`, `fimo/sveltekit/components`, `fimo/sveltekit/config`, `fimo/sveltekit/vite` |
-| `nuxtjs`, `remix`, `vue` | Hosting detection only; no Fimo content/runtime adapter yet                                                                  | `fimo` hosting profile only                                                                   |
+| Profile                  | Application dependency specifier                                                                                                             | Fimo surface                                                                                  |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `nextjs`                 | Next 16 is the current acceptance baseline; Fimo's React peer is `^18.2.0 \|\| ^19.0.0` and Next imposes its own React range                 | `fimo/next`, `fimo/next/client`                                                               |
+| `react-router`           | React `^18.2.0 \|\| ^19.0.0`, React Router `^7.0.0 \|\| ^8.0.0`, Vite `^7.0.0 \|\| ^8.0.0`                                                   | `fimo/react-router`, `fimo/ui`                                                                |
+| `vite`                   | React `^18.2.0 \|\| ^19.0.0`, Vite `^7.0.0 \|\| ^8.0.0`                                                                                      | `fimo/ui`, `fimo/vite`                                                                        |
+| `astro`                  | Astro `^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0`                                                                                                       | `fimo/astro`, `fimo/astro/components`                                                         |
+| `sveltekit`              | SvelteKit `^2.0.0`, Svelte `^5.0.0`, Vite `^7.0.0 \|\| ^8.0.0`                                                                               | `fimo/sveltekit`, `fimo/sveltekit/components`, `fimo/sveltekit/config`, `fimo/sveltekit/vite` |
+| `nuxtjs`, `remix`, `vue` | Hosting detection only; no Fimo content/runtime adapter yet                                                                                  | `fimo` hosting profile only                                                                   |
+| _(unset)_                | Anything else: a static generator, plain HTML, a custom build script. Declare `runtime.commands.build` and `runtime.outputDirectory` instead | Static output only; no adapter                                                                |
+
+`runtime.framework` must match a dependency in `package.json`; a profile the
+code does not use fails the production build. Shape and rules: `hosting.md`
+§ `runtime`.
 
 The exact versions used by acceptance fixtures are test baselines, not values
 to copy into an application. If a project falls outside a documented range,

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

@@ -4,20 +4,36 @@ Preserve the application's framework, router, routes, and 404 behavior. Fimo
 detects supported frameworks for preview and translates only the
 provider-neutral hosting settings the application explicitly owns.
 
-## Production framework profile
+## `runtime`: how Fimo builds and serves the application
 
-Fimo detects conventional projects for preview. Before publishing, commit the
-matching profile in `.fimo/config.json`:
+`.fimo/config.json#runtime` is the whole contract. Every key is optional:
 
 ```json
 {
-  "runtime": { "framework": "nextjs" }
+  "runtime": {
+    "framework": "nextjs",
+    "commands": { "dev": "npm run dev", "build": "npm run build", "install": "npm ci" },
+    "outputDirectory": "dist"
+  }
 }
 ```
 
-Allowed values are `astro`, `nextjs`, `nuxtjs`, `react-router`, `remix`,
-`sveltekit`, `vite`, and `vue`. The field remains optional for legacy Fimo
-projects, which keep their existing static output contract.
+| Key               | Meaning                                                             | Resolution when unset                                       |
+| ----------------- | ------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `framework`       | Production build profile. Must match a dependency in `package.json` | Preview detects; production uses the static-output profile  |
+| `commands.*`      | The exact command for `dev`, `build`, `install`                     | Package script of the same name, then the framework default |
+| `outputDirectory` | Folder the build command fills with the finished site               | Framework default; `dist/client` (config v4) or `dist`      |
+
+`framework` values: `astro`, `nextjs`, `nuxtjs`, `react-router`, `remix`,
+`sveltekit`, `vite`, `vue`. A value the code does not depend on fails the
+production build. If none matches, leave it unset and set `commands.build` and
+`outputDirectory`.
+
+Keep `runtime` true to the code. Every `fimo init` shell writes its own
+`framework`; after replacing the shell's code, re-check it. When you rename a
+package script or move the build output, update `commands` and
+`outputDirectory` in the same change. Do not add overrides a conventional
+project does not need.
 
 Hosted preview and production inject the tenant API through these aliases:
 
@@ -33,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
@@ -90,14 +109,3 @@ editing an Astro config.
 `.fimo/config.json#routes` is the Studio page catalog, not deployment routing.
 Never generate hosting rewrites from it. If a project already has a
 provider-specific deployment file, preserve it; that file remains authoritative.
-
-## Non-standard commands
-
-Use `runtime.commands.dev|build|install` only when normal package scripts and
-framework defaults are insufficient. Do not add overrides to conventional
-projects.
-
-Vite defaults to `dist` and React Router defaults to `dist/client`. If an
-existing project deliberately emits somewhere else, preserve that choice with
-`runtime.outputDirectory`; do not rewrite the application's build merely to
-match a Fimo default.

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.