fimo 0.20.0 → 0.21.0-experimental.1

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

@@ -14,17 +14,23 @@ Declare the production framework in `.fimo/config.json`:
 
 Astro owns its static or server output, routes, and 404 behavior. Do not add a catch-all hosting rewrite, a hosting-provider adapter, a preview URL, or a script tag for Fimo.
 
-Add the integration beside the adapters and integrations the project already uses:
+Install `fimo-astro` at the same version as `fimo` and add the integration
+beside the adapters and integrations the project already uses:
 
 ```js
 import { defineConfig } from 'astro/config';
-import { fimo } from 'fimo/astro/config';
+import { fimo } from 'fimo-astro/config';
 
 export default defineConfig({
   integrations: [fimo()],
 });
 ```
 
+`fimo-astro/config` supplies Fimo hosting for `output: 'server'`. A static
+Astro site that hosts elsewhere can import `fimo` from `fimo/astro/config`
+instead for the preview connector and branch env alone; the runtime
+(`fimo/astro`, `fimo/astro/components`) always comes from `fimo`.
+
 Compatibility: the Fimo peer range covers Astro 5–7. Static output is supported
 across that range. Fimo's automatic server adapter path is currently validated
 with the Astro 7-compatible adapter; Astro 5/6 server apps should keep their

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

@@ -4,15 +4,15 @@
 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                                                                   |
-| _(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                                                                |
+| 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-react-router/routes`, `fimo-react-router/preset`, `fimo-react-router/vite`, `fimo-react` |
+| `vite`                   | Vite `^7.0.0 \|\| ^8.0.0`; React `^18.2.0 \|\| ^19.0.0` only when the app uses React                                                         | `fimo-react`, `fimo-react-router/vite` (React SPA) or `fimo-vite` (no React)                                        |
+| `astro`                  | Astro `^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0`; Fimo hosting (`fimo-astro`) needs Astro `^7.0.0`                                                     | `fimo/astro`, `fimo/astro/components`, `fimo-astro/config`                                                          |
+| `sveltekit`              | SvelteKit `^2.0.0`, Svelte `^5.0.0`, Vite `^7.0.0 \|\| ^8.0.0`                                                                               | `fimo-sveltekit`, `fimo-sveltekit/components`, `fimo-sveltekit/vite`, `fimo-sveltekit/config`                       |
+| `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`

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

@@ -39,27 +39,31 @@ Hosted preview and production inject the tenant API through these aliases:
 
 | Application             | Server                 | Public/build               |
 | ----------------------- | ---------------------- | -------------------------- |
-| Next.js                 | `FIMO_CONTENT_API_URL` | `NEXT_PUBLIC_FIMO_API_URL` |
+| Next.js                 | `FIMO_CONTENT_API_URL` | Provider-owned             |
 | Nuxt                    | `FIMO_CONTENT_API_URL` | `NUXT_PUBLIC_FIMO_API_URL` |
 | Astro, Remix, SvelteKit | `FIMO_CONTENT_API_URL` | `PUBLIC_FIMO_API_URL`      |
 | React Router, Vite, Vue | `FIMO_CONTENT_API_URL` | `VITE_API_URL`             |
 
-Locally, the app derives its env from the **git branch**: `fimo/vite`,
-`withFimo`, the Astro integration and the SvelteKit plugin compute the tenant
-API URL from `.fimo/project.json`
+Locally, the app derives its env from the **git branch**: `fimo-vite` (or
+`fimo-react-router/vite` for React Router projects), the Astro integration and
+the SvelteKit plugin compute the tenant 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. 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 non-empty value the user set explicitly (`.env`, shell, their own
-`define`) is left alone, and Fimo fills the variables they did not set.
+expose the Vite and public (`PUBLIC_*`) aliases plus `FIMO_ENV` at startup,
+during both dev and production builds. Next.js needs no browser alias: the root
+`FimoProvider` and the `fimo-next` server runtime resolve the same connection
+at render time and pass only the public part to the browser. 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
+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
 local environment alias by hand.
 
+`NEXT_PUBLIC_FIMO_*` remains a compatibility override for existing Next.js
+projects. Do not add it to new code, env files, setup instructions, or migration
+plans.
+
 ## React Router framework mode
 
 For the supported client-rendered setup, keep `ssr: false` and add Fimo's
@@ -67,7 +71,7 @@ hosting preset. It hides the active hosting provider from application code:
 
 ```ts
 import type { Config } from '@react-router/dev/config';
-import { fimoPreset } from 'fimo/react-router/preset';
+import { fimoPreset } from 'fimo-react-router/preset';
 
 export default {
   ssr: false,

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

@@ -4,11 +4,10 @@ Preserve the project's existing App Router structure. Fimo does not require a ro
 
 ## Root provider
 
-Resolve the locale using the application's existing strategy, fetch labels on the server, and pass the snapshot into the client provider:
+Render the Server Component `FimoProvider` from `fimo-next` once in the root layout. Resolve the locale using the application's existing strategy, fetch labels on the server, and pass the snapshot:
 
 ```tsx
-import { getLabels } from 'fimo/next';
-import { FimoProvider } from 'fimo/next/client';
+import { FimoProvider, getLabels } from 'fimo-next';
 
 export default async function RootLayout({ children }: { children: React.ReactNode }) {
   const locale = 'en'; // replace with the app's own resolver
@@ -24,14 +23,14 @@ export default async function RootLayout({ children }: { children: React.ReactNo
 }
 ```
 
-Do not hardcode a locale when the app already resolves one from route params, a cookie, headers/domain, middleware, or an i18n library. Load `references/frameworks/next/locales.md` for those cases.
+The provider resolves the Fimo connection on the server and passes only public connection data to the client tree; no page or component receives a runtime prop and no `<script>` for the preview needs adding. Do not hardcode a locale when the app already resolves one from route params, a cookie, headers/domain, middleware, or an i18n library. Load `references/frameworks/next/locales.md` for those cases.
 
 ## Static generation and ISR
 
 Server Components may read generated clients directly. Omit `locale` to use the configured default or bind the application-resolved locale once with `createFimo`:
 
 ```tsx
-import { createFimo, RichText, Text } from 'fimo/next';
+import { createFimo, RichText, Text } from 'fimo-next';
 import { content } from '@/schemas';
 
 export const revalidate = 60;
@@ -51,7 +50,7 @@ export default async function ArticlesPage() {
 
 `createFimo({ content, locale })` is a typed locale-bound facade over the generated registry. It does not own routing and does not force SSG.
 
-Static builds that read Fimo must receive the real build-time `FIMO_CONTENT_API_URL` and default locale environment. Do not switch a route to dynamic rendering merely to hide a missing build environment; choose SSG, ISR, or request-time rendering from the application's intended behavior.
+Static builds read Fimo through the same server connection (linked project + branch locally, platform env when hosted). Do not switch a route to dynamic rendering merely to hide a missing connection; choose SSG, ISR, or request-time rendering from the application's intended behavior.
 
 ## Request-time rendering
 
@@ -59,7 +58,7 @@ Use normal Next request APIs and pass the resulting locale/query values to Fimo:
 
 ```tsx
 import { headers } from 'next/headers';
-import { createFimo, Text } from 'fimo/next';
+import { createFimo, Text } from 'fimo-next';
 import { content } from '@/schemas';
 
 export const dynamic = 'force-dynamic';
@@ -82,12 +81,12 @@ 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`:
+Client Components use the generated `.client` module and `fimo-next/client`:
 
 ```tsx
 'use client';
 
-import { Text, useLabels } from 'fimo/next/client';
+import { Text, useLabels } from 'fimo-next/client';
 import * as Article from '@/schemas/Article.client';
 
 export function FeaturedArticles() {

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

@@ -15,7 +15,7 @@ If omitted, both use the configured default locale. Avoid request-global locale
 
 ## Client context
 
-Pass the same locale through `FimoProvider`. A matching label snapshot supplies it automatically:
+Pass the same locale through the root `FimoProvider` (`fimo-next` in the App Router layout, `fimo-next/client` in `_app`). A matching label snapshot supplies it automatically:
 
 ```tsx
 const labels = await getLabels({ locale });
@@ -35,13 +35,13 @@ When labels are not needed at that boundary, use `<FimoProvider locale={locale}>
 
 ## 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.
+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 is content and provider configuration: `src/locales.ts` reads the file, so the default locale passed to `FimoProvider` and the `<html lang>` follow it. It does not create locale URLs. 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.
+The starter is default-only: one ordinary root layout renders `<html lang={defaultLocale}>` and `FimoProvider`, `/` is the homepage, and unknown paths get Next's native 404. Implement a locale routing strategy only when the product asks for one — prefixed `[locale]` segments, middleware, cookies, domains, or an i18n library are all Next decisions — then resolve the locale in that strategy and pass it into Fimo server reads and `FimoProvider`. Do not install a top-level `[locale]` route or an optional catch-all speculatively: it captures `/favicon.ico` and every unknown top-level path, and Fimo never requires it.
 
-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.
+When the app implements a localized URL shape, describe it in `.fimo/config.json#routes` for Studio. 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. The config route catalog describes 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.
+`FimoProvider` owns the optional Studio preview runtime, including Next navigation and script loading. Application code only passes its resolved locale to the provider. Do not add a preview bridge component, read Fimo preview environment variables, or inject Fimo scripts.
 
 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.
 

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

@@ -4,10 +4,10 @@ Preserve `pages/` or `src/pages/`. Pages Router sends props through JSON seriali
 
 ## Provider in `_app`
 
-Pass each page's label snapshot to one provider:
+Pages Router has no Server Component above `_app`, so `FimoProvider` from `fimo-next/client` is the root integration: it resolves the connection while the server renders `_app`, writes the public connection into the document for the browser, and loads the Studio preview script. Pass each page's label snapshot to it:
 
 ```tsx
-import { FimoProvider, type LabelsSnapshot } from 'fimo/next/client';
+import { FimoProvider, type LabelsSnapshot } from 'fimo-next/client';
 import type { AppProps } from 'next/app';
 
 type FimoPageProps = { fimoLabels: LabelsSnapshot };
@@ -26,7 +26,7 @@ If the application already has providers, compose Fimo with them; do not replace
 ## Static generation and ISR
 
 ```tsx
-import { createFimo, getLabels } from 'fimo/next';
+import { createFimo, getLabels } from 'fimo-next';
 import type { GetStaticProps, InferGetStaticPropsType } from 'next';
 
 import { ArticleView } from '@/components/ArticleView';
@@ -61,7 +61,7 @@ export default function Page({ article: serialized }: InferGetStaticPropsType<ty
 ## Request-time rendering
 
 ```tsx
-import { getLabels } from 'fimo/next';
+import { getLabels } from 'fimo-next';
 import type { GetServerSideProps, InferGetServerSidePropsType } from 'next';
 import * as Article from '@/schemas/Article';
 import * as ArticleClient from '@/schemas/Article.client';
@@ -86,7 +86,7 @@ Use the locale/router values Pages Router already supplies. Do not introduce App
 Interactive components import hooks and primitives from the client surfaces:
 
 ```tsx
-import { Text, useLabels } from 'fimo/next/client';
+import { Text, useLabels } from 'fimo-next/client';
 import * as Article from '@/schemas/Article.client';
 
 export function SearchResults() {

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

@@ -21,14 +21,37 @@ hosted publish. Run `fimo validate`; load
 `references/frameworks/hosting.md` for the shared profile contract and command
 override rules.
 
+## Connection
+
+Render `FimoProvider` once at the application root and nothing else: App Router
+imports it from `fimo-next` in the root layout; Pages Router imports it from
+`fimo-next/client` in `pages/_app.tsx`. It resolves the connection on the
+server — explicit platform env first, else the linked project
+(`.fimo/project.json`) plus the active git branch — and passes only the public
+connection to the browser, where generated `.client` hooks, `useLabels`, form
+submission, and the Studio preview script use it. Never add, read, or document
+`FIMO_CONTENT_API_URL` / `NEXT_PUBLIC_FIMO_API_URL` in application code; the
+platform and the provider own them. `FIMO_CONTENT_API_URL` set by a developer is
+a deliberate host override and wins over derivation.
+
+### Edge routes
+
+Fimo hosting injects the server connection for Edge routes. No application
+configuration is needed. For a local or custom-hosted Edge route only, run
+`fimo --json link` in the linked checkout and use its exact `tenant_api_url` as
+`FIMO_CONTENT_API_URL` in the dev command or host configuration. Never construct
+the URL, write it to a project env file, or add a `NEXT_PUBLIC_FIMO_*` variable.
+Rerun the command after switching Git branches because each Fimo Branch has its
+own tenant URL.
+
 ## Hosted preview config
 
-Wrap the existing Next config once so Fimo can connect its hosted development
-preview without exposing the active preview provider to the application:
+Wrap the existing Next config once so `next dev` accepts Fimo's hosted preview
+origins without exposing the active preview provider to the application:
 
 ```ts
 import type { NextConfig } from 'next';
-import { withFimo } from 'fimo/next/config';
+import { withFimo } from 'fimo-next/config';
 
 const nextConfig: NextConfig = {};
 export default withFimo(nextConfig);
@@ -36,29 +59,15 @@ export default withFimo(nextConfig);
 
 Preserve all existing config fields or config-function logic. Do not hardcode a
 preview domain in `allowedDevOrigins`; Fimo supplies it to the development
-sandbox. The wrapper does not change production builds.
+sandbox. The wrapper changes nothing outside `next dev` and is not the
+application's Fimo connection.
 
 ## Client dependency
 
-Server-only Fimo reads need no client data library. If the app uses `FimoProvider`,
-`useLabels`, or generated `.client` hooks, add `@tanstack/react-query` using the
-project's package manager. It is an optional `fimo` peer so server-only projects
-do not install it automatically.
-
-## Runtime URL
-
-Linked projects need the tenant content API in both Next runtimes:
-
-```dotenv
-FIMO_CONTENT_API_URL=https://<tenant-api>
-NEXT_PUBLIC_FIMO_API_URL=https://<tenant-api>
-```
-
-Current `fimo init` and `fimo clone` write these alongside `VITE_API_URL` while
-preserving user-owned values. `FIMO_API_URL` remains reserved for CLI/control API
-overrides. Keep the
-server variable private; only the public variable is compiled into Client
-Components.
+`fimo-next` requires `@tanstack/react-query` as a peer; add it with the project's
+package manager when it is missing. Generated `.client` hooks and `useLabels`
+run on the React Query client `FimoProvider` supplies (or an application-owned
+one already in context).
 
 ## Generate the content surface
 
@@ -114,10 +123,10 @@ export function ContactForm() {
 }
 ```
 
-Server Components, route handlers, `getStaticProps`, and `getServerSideProps` import from `fimo/next` and generated server modules:
+Server Components, route handlers, `getStaticProps`, and `getServerSideProps` import from `fimo-next` and generated server modules:
 
 ```ts
-import { createFimo, getLabels, Text } from 'fimo/next';
+import { createFimo, getLabels, Text } from 'fimo-next';
 import { content } from '@/schemas';
 
 const fimo = createFimo({ content, locale });
@@ -127,12 +136,12 @@ const [articles, labels] = await Promise.all([
 ]);
 ```
 
-Client Components import from `fimo/next/client` and generated `.client` modules:
+Client Components import from `fimo-next/client` and generated `.client` modules:
 
 ```tsx
 'use client';
 
-import { Text, useLabels } from 'fimo/next/client';
+import { Text, useLabels } from 'fimo-next/client';
 import * as Article from '@/schemas/Article.client';
 
 export function ArticleList() {
@@ -142,21 +151,21 @@ export function ArticleList() {
 }
 ```
 
-Do not import `fimo/next/client` into server-only modules. Do not import React Query hooks from `<Uid>.ts`.
+Do not import `fimo-next/client` into server-only modules. Do not import React Query hooks from `<Uid>.ts`.
 
 ## Provider boundary
 
-Client hooks need one `FimoProvider` near the application root. The server may fetch a label snapshot and pass it across that boundary:
+Client hooks need the one root `FimoProvider`. The server may fetch a label
+snapshot and pass it across that boundary:
 
 ```tsx
-import { getLabels } from 'fimo/next';
-import { FimoProvider } from 'fimo/next/client';
+import { FimoProvider, getLabels } from 'fimo-next';
 
 const labels = await getLabels({ locale });
 return <FimoProvider labels={labels.snapshot}>{children}</FimoProvider>;
 ```
 
-Passing `locale` without `labels` is valid when only content hooks need context. Passing a matching snapshot supplies both locale and labels. Never teach the unreleased `FimoNextProvider` name; the public component is `FimoProvider`.
+Passing `locale` without `labels` is valid when only content hooks need context. Passing a matching snapshot supplies both locale and labels. A nested `FimoProvider` only narrows labels/locale for its subtree. Never teach the unreleased `FimoNextProvider` name; the public component is `FimoProvider`.
 
 ## Rendering modes
 

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

@@ -9,16 +9,18 @@ its routes, rendering choices, providers, and SEO.
 Install the peers the application uses:
 
 ```bash
-pnpm add fimo react react-dom react-router @tanstack/react-query
+pnpm add fimo fimo-react fimo-react-router react react-dom react-router @tanstack/react-query
 pnpm add -D @react-router/dev @react-router/node vite
 ```
 
+`fimo-react-router` carries `fimo-vite`; do not install it separately.
+
 Keep the project's React Router Vite plugin explicit:
 
 ```ts
 import { reactRouter } from '@react-router/dev/vite';
 import { defineConfig } from 'vite';
-import { fimo } from 'fimo/vite';
+import { fimo } from 'fimo-react-router/vite';
 
 export default defineConfig({
   plugins: [reactRouter(), fimo({ sitemap: true })],
@@ -31,7 +33,7 @@ For the supported client-rendered setup, connect React Router's native build to
 
 ```ts
 import type { Config } from '@react-router/dev/config';
-import { fimoPreset } from 'fimo/react-router/preset';
+import { fimoPreset } from 'fimo-react-router/preset';
 
 export default {
   appDirectory: 'src',
@@ -48,7 +50,7 @@ Do not change an existing SSR project to `ssr: false` merely to add Fimo. The cu
 
 ```tsx
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { FimoProviders, FimoScripts } from 'fimo/react-router';
+import { FimoProviders, FimoScripts } from 'fimo-react-router';
 import { Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router';
 
 const queryClient = new QueryClient();
@@ -106,10 +108,10 @@ If an existing project imports `fimo/react-router/routes`, load `references/migr
 
 ## Content and labels
 
-Render tracked values with `fimo/ui`:
+Render tracked values with `fimo-react`:
 
 ```tsx
-import { Image, Label, RichText, Text } from 'fimo/ui';
+import { Image, Label, RichText, Text } from 'fimo-react';
 
 return <Label value="home.hero.title" as="h1" />;
 ```
@@ -133,6 +135,7 @@ For new projects, apply `references/locales.md`, keep the starter's `:locale?` r
 ## Boundaries
 
 - Route modules and `meta` exports own routing and SEO.
-- `FimoScripts` owns preview-script loading; do not add the overlay script manually.
+- `FimoProviders` owns the optional Studio preview runtime. Do not read Fimo preview environment variables or inject its script in application code.
+- `FimoScripts` owns document-only JSON-LD and the development error overlay.
 - Use `fimo deploy` only when the developer requests a hosted preview or publication.
 - Load `references/ui.md` for rendering and `references/locales.md` for locale ownership.

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

@@ -10,13 +10,22 @@ The adapter targets SvelteKit 2 with Svelte 5. The acceptance baseline currently
 uses SvelteKit `2.70.2`, Svelte `5.56.8`, and Vite `8.2.0`; do not assume that
 SvelteKit 1 or Svelte 4 projects are compatible.
 
+## Install both packages
+
+Every SvelteKit surface lives in `fimo-sveltekit`, installed at the same version
+as `fimo`:
+
+```bash
+npm install fimo fimo-sveltekit
+```
+
 ## Connect the Vite plugin
 
 Add Fimo's source-tagging plugin alongside SvelteKit's own plugin:
 
 ```ts
 import { sveltekit } from '@sveltejs/kit/vite';
-import { fimo } from 'fimo/sveltekit/vite';
+import { fimo } from 'fimo-sveltekit/vite';
 import { defineConfig } from 'vite';
 
 export default defineConfig({ plugins: [fimo(), sveltekit()] });
@@ -27,11 +36,10 @@ elements back to source. It does not change production output or own routing.
 
 ## Hosted configuration
 
-For a new Fimo-hosted SvelteKit project, keep the hosting adapter behind Fimo's
-config seam:
+Keep the hosting adapter behind Fimo's config seam:
 
 ```js
-import { fimo } from 'fimo/sveltekit/config';
+import { fimo } from 'fimo-sveltekit/config';
 
 export default {
   kit: { adapter: fimo() },
@@ -49,7 +57,7 @@ SvelteKit's request-aware `fetch`:
 
 ```ts
 // src/routes/articles/+page.server.ts
-import { createFimo } from 'fimo/sveltekit';
+import { createFimo } from 'fimo-sveltekit';
 import { content } from '../../../schemas';
 
 export async function load(event) {
@@ -72,7 +80,7 @@ do not import a Fimo environment variable or hardcode a tenant URL:
 
 ```ts
 // src/routes/+layout.server.ts
-import { getLabels } from 'fimo/sveltekit';
+import { getLabels } from 'fimo-sveltekit';
 
 import { resolveLocale } from '../locales';
 
@@ -86,7 +94,7 @@ export async function load(event) {
 <!-- src/routes/+layout.svelte -->
 <script lang="ts">
   import { afterNavigate } from '$app/navigation';
-  import { FimoProvider } from 'fimo/sveltekit/components';
+  import { FimoProvider } from 'fimo-sveltekit/components';
   import type { LayoutData } from './$types';
   import type { Snippet } from 'svelte';
 
@@ -104,7 +112,8 @@ 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`,
-`DateTime`, `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.
 
@@ -114,7 +123,7 @@ Use a `+page.server` action so SvelteKit owns the request and redirect. Pass its
 event to `createFimoFormClient` and use the generated parser/helper:
 
 ```ts
-import { createFimoFormClient } from 'fimo/sveltekit';
+import { createFimoFormClient } from 'fimo-sveltekit';
 import { parseContactUsFormData, submitContactUs } from '$lib/forms/contact-us';
 
 export const actions = {
@@ -127,16 +136,14 @@ export const actions = {
 
 ## Live preview
 
-`FimoProvider` owns the Studio browser bridge. On mount it reads
-`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 second preview component.
+`FimoProvider` owns the optional Studio preview runtime, including script
+loading, SvelteKit navigation, and content refresh. Do not add a second preview
+component, read Fimo preview environment variables, or inject Fimo scripts.
 
 ## Boundaries
 
 - SvelteKit owns routing, history, 404s, locale URLs, and SEO.
-- `fimo/sveltekit/vite` owns dev source tagging only.
+- `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.
 

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

@@ -5,7 +5,7 @@ Use this reference for a Vite + React SPA without React Router framework mode. P
 ## Install and build
 
 ```bash
-pnpm add fimo react react-dom react-router @tanstack/react-query
+pnpm add fimo fimo-react fimo-react-router react react-dom react-router @tanstack/react-query
 pnpm add -D vite @vitejs/plugin-react
 ```
 
@@ -14,7 +14,7 @@ Add Fimo's Vite plugins without replacing the application's existing plugins:
 ```ts
 import react from '@vitejs/plugin-react';
 import { defineConfig } from 'vite';
-import { fimo } from 'fimo/vite';
+import { fimo } from 'fimo-react-router/vite';
 
 export default defineConfig({
   plugins: [react(), ...fimo({ seo: true })],
@@ -23,13 +23,15 @@ export default defineConfig({
 
 `fimo()` is synchronous and returns a `PluginOption[]`. `seo: true` updates the shared `index.html` at build time. Add `sitemap: true` or `robots: true` only when requested.
 
+Import it from `fimo-react-router/vite` whenever the application renders through React Router, including a plain `BrowserRouter` SPA: it adds the React dependency pre-bundling those apps need. A Vite application with no React at all installs `fimo-vite` instead and imports `fimo` from there.
+
 ## Application root
 
 `FimoProviders` needs a React Router context for Studio navigation and pageview tracking. Keep the application's existing router type:
 
 ```tsx
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { FimoProviders } from 'fimo/react-router';
+import { FimoProviders } from 'fimo-react-router';
 import React from 'react';
 import { createRoot } from 'react-dom/client';
 import { BrowserRouter } from 'react-router';
@@ -55,10 +57,10 @@ An adopted SPA can omit the explicit `QueryClientProvider` when it does not need
 
 ## Content and labels
 
-Use `fimo/ui` for tracked values:
+Use `fimo-react` for tracked values:
 
 ```tsx
-import { Label } from 'fimo/ui';
+import { Label } from 'fimo-react';
 
 export function App() {
   return <Label value="home.hero.title" as="h1" />;

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

@@ -38,10 +38,10 @@ Missing keys render as an empty tracked value. Run `fimo validate`, then create
 
 The label contract is shared; acquisition differs by runtime:
 
-- Next server: `getLabels({ locale? })` from `fimo/next`.
-- Next client: `useLabels()` from `fimo/next/client`, under `FimoProvider`.
-- React Router/Vite client: `Label` and `useLabels()` from `fimo/ui`, under the existing framework integration.
-- SvelteKit: pass the application's resolved locale to `getLabels({ apiUrl, event, locale })`, or omit it to let the API choose the project default. Wrap the root layout with `FimoProvider` from `fimo/sveltekit/components`; the snapshot supplies its locale. Descendants use `Label` from that entrypoint or `useLabels().t()` from `fimo/sveltekit`. Apply the same explicit-or-omitted rule to `createFimo({ content, event, locale? })` in content loads.
+- Next server: `getLabels({ locale? })` from `fimo-next`.
+- Next client: `useLabels()` from `fimo-next/client`, under `FimoProvider`.
+- React Router/Vite client: `Label` and `useLabels()` from `fimo-react`, under the existing framework integration.
+- SvelteKit: pass the application's resolved locale to `getLabels({ apiUrl, event, locale })`, or omit it to let the API choose the project default. Wrap the root layout with `FimoProvider` from `fimo-sveltekit/components`; the snapshot supplies its locale. Descendants use `Label` from that entrypoint or `useLabels().t()` from `fimo-sveltekit`. Apply the same explicit-or-omitted rule to `createFimo({ content, event, locale? })` in content loads.
 - Astro server page: `getLabels({ locale? })` from `fimo/astro`; no provider.
 
 Load the matching framework reference before choosing a provider or server reader.

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

@@ -13,7 +13,7 @@ The application owns locale resolution and routing. Fimo consumes the resolved l
 }
 ```
 
-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.
+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 document language default, and any framework-native locale route boundary or matcher the application implements. 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`.
 
@@ -45,4 +45,4 @@ For an already linked project, enable each locale in Fimo before writing non-def
 
 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.
+Neither Astro nor Next has an optional single-segment filesystem folder; an optional locale boundary in those frameworks is paired native filesystem route trees, one unprefixed for the default locale and one prefixed for the others. The Astro starter ships that pair; the Next starter is default-only, so a Next application adds a `[locale]` tree (or another strategy) only when the product asks for prefixed URLs.