fimo 0.21.0-staging.5 → 0.21.0-staging.6

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

@@ -35,6 +35,30 @@ Read it as `.data.url` / `.data.id` (e.g. `… | jq -r '.data.url'`). Keep the `
 
 Use `--folder-path` when an agent needs a non-interactive upload target and does not already know folder IDs. Missing folders are created automatically. Dot-prefixed root folders such as `.agents` are reserved for internal/agent media and are hidden from the normal media-library UI.
 
+## Upload a manifest
+
+Use one structured manifest for migration batches. Paths resolve from the
+project directory; `sourceId` must be unique so every result can be reconciled.
+
+```json
+[
+  {
+    "sourceId": "strapi:upload:42",
+    "path": ".fimo/migration/media/Hero image.jpg",
+    "name": "Homepage hero",
+    "folderPath": "Imported"
+  }
+]
+```
+
+```bash
+fimo assets bulk-upload --file .fimo/migration/media.json
+```
+
+The result preserves manifest order and reports each `sourceId` as `uploaded`
+or `failed`, plus final counts. Partial failure exits non-zero. Use
+`--concurrency <1-16>` to change the default concurrency of four.
+
 ## Generate AI media
 
 Moved to **`references/media.md`**. Choose the task that describes the outcome:
@@ -125,6 +149,6 @@ fimo assets delete <asset-id>
 
 ## End-to-end workflow
 
-1. Upload with `fimo assets upload` or generate with a task command such as `fimo image generate`.
+1. Upload with `fimo assets upload`, use `fimo assets bulk-upload` for a batch, or generate with a task command such as `fimo image generate`.
 2. Keep the returned `url` (for direct use) or `id` (to attach to a `media` content-type field).
 3. To use in application code, run `fimo skills get fimo-code --ref ui` and load the detected framework reference: schema media → `<Image>` / `<Video>`, deliberate non-schema URLs → `<StaticImage>`. Never use raw `<img src={asset.url}>` for tracked media.

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

@@ -105,7 +105,10 @@ Use `fimo publish` when `main` is already synced; use `fimo deploy --publish` wh
 ## Anti-patterns
 
 - **Using `git checkout -b` instead of `fimo checkout -b`** — raw git creates the branch but **not** the Branch's DB / sandbox / preview. Always use `fimo` for Branch operations so resources are provisioned atomically. (Running `fimo branch <name>` after the fact provisions them.) The running app itself follows the git branch either way.
-- **Hardcoding the tenant API URL** — the app derives it from the git branch and `.fimo/project.json`. Set `VITE_API_URL` / `NEXT_PUBLIC_FIMO_API_URL` yourself only as a deliberate override (e.g. a local API); it then wins over derivation on every branch.
+- **Hardcoding the tenant API URL** — the framework runtime derives it from the
+  git branch and `.fimo/project.json`. Use an explicit host variable only as a
+  deliberate override, such as a local API; it then wins over derivation on
+  every branch.
 - **Trying to push to or delete `prod` / `release/*`** — these are read-only/protected. Publish to update prod; never push.
 - **`fimo merge` straight onto `main` as a habit** — it's gated for a reason. Merge on a branch, then publish.
 - **Confusing `fimo switch` (Branch) with `fimo orgs switch` (org).**

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

@@ -54,7 +54,7 @@ Use this when the user asks "who filled out the contact form?", "how many signup
 
 ## When to run sync manually
 
-The `fimo/vite` plugin regenerates legacy Vite `src/forms/*.ts` after form JSON changes during development. Framework-aware generation runs during validation. Before a production build, regenerate explicitly with:
+The `fimo-vite` plugin regenerates legacy Vite `src/forms/*.ts` after form JSON changes during development. Framework-aware generation runs during validation. Before a production build, regenerate explicitly with:
 
 ```bash
 fimo validate                  # runs all phases: codegen, lint, route validation, label checks

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

@@ -11,7 +11,7 @@ fimo init [dir] [options]
 `fimo init` runs the full onboarding in one shot:
 
 1. **Signs in automatically** — if there's no session it opens the browser loopback login. In `--json` / non-TTY with no session it fails with `NOT_AUTHENTICATED` (run `fimo login` first).
-2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo project: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use React Router by default; `--framework astro`, `--framework nextjs`, and `--framework sveltekit` select minimal framework-native shells. An optional `--starter fimo-site@1` adds a content-led starter only to a newly created project without `--project-id`.
+2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo project: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use React Router by default; `--framework vite`, `--framework astro`, `--framework nextjs`, and `--framework sveltekit` select minimal framework-native shells. An optional `--starter fimo-site@1` adds a content-led starter only to a newly created project without `--project-id`.
 3. **Installs dependencies** — prompts for the package manager, or honor `--package-manager <pm>` / `--no-install`.
 4. **Optionally sets up Fimo skills** — confirm prompt, or `--skills` / `--no-skills`.
 
@@ -24,7 +24,7 @@ Generated pnpm projects pin `pnpm@10.26.0` and carry project-owned `pnpm-workspa
 | `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.             |
 | `--branch <name>`            | no                            | Branch to check out when linking an existing project (defaults to `main`).                                                                                     |
 | `--env <name>`               | no                            | Compatibility alias for `--branch <name>`.                                                                                                                     |
-| `--framework <framework>`    | no                            | New-project scaffold: `react-router` (default), `astro`, `nextjs` (App Router), or `sveltekit`. Existing repositories are preserved.                           |
+| `--framework <framework>`    | no                            | New-project scaffold: `react-router` (default), `vite` (React SPA), `astro`, `nextjs` (App Router), or `sveltekit`. Existing repositories are preserved.       |
 | `--starter <id>`             | no                            | Opt-in project starter for create-new (currently `fimo-site@1`). It seeds CMS content, labels, a contact form, and manual-only agents. Rejects `--project-id`. |
 | `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                            |
 | `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                                      |
@@ -68,6 +68,7 @@ Omit `--framework` for the existing React Router scaffold, or select a
 minimal framework-native shell explicitly:
 
 ```bash
+fimo init my-vite-site --framework vite --org <organizationId>
 fimo init my-astro-site --framework astro --org <organizationId>
 fimo init my-next-site --framework nextjs --org <organizationId>
 fimo init my-svelte-site --framework sveltekit --org <organizationId>
@@ -96,15 +97,22 @@ For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for C
 
 Pass `--project-id <id>` to set up a known Fimo project. If the project has no code yet — for example, one just created in Fimo Studio — `init` scaffolds a fresh site into it and pushes the initial commit: the same create-new path, linked to the existing ID. If the project already has code, `init` clones it into `[dir]`, like `fimo clone`. Use `--branch <name>` to check out a specific Branch (defaults to `main`); `--env <name>` remains a compatibility alias. Without `--project-id`, `fimo init` creates a new project.
 
+## Linking an existing local application
+
+Use `fimo link <projectId>` to adopt the application in the current folder without replacing its code or comparing its Git history. Running it again with the same project id repairs missing Fimo metadata, dependencies, or the `fimo` remote. If the folder is linked to a different project, the command stops before changing the remote or local files. Pass `--relink` only when the project replacement is intentional:
+
+```bash
+fimo link <projectId> --relink
+```
+
 ## What gets written (create-new path)
 
 `fimo init` (create-new path) scaffolds:
 
-- The selected project shell: React Router by default, Astro with `--framework astro`, Next.js App Router with `--framework nextjs`, or SvelteKit with `--framework sveltekit`
+- The selected project shell: React Router by default, a native React SPA with `--framework vite`, Astro with `--framework astro`, Next.js App Router with `--framework nextjs`, or SvelteKit with `--framework sveltekit`
 - `.fimo/project.json` — links this directory to the remote project (read-only after creation)
 - `.fimo/config.json` — project, optional Studio Pages route metadata, locale, SEO, and agent policy
 - `.fimo/agents/` — versioned agent bundles
-- `.env` — framework-specific tenant content API URLs for local development
 - `AGENTS.md` + `CLAUDE.md` — project rules (from the template) read by AGENTS.md-compatible tools and Claude Code. Both point the agent at `fimo skills get` to load the real skills on demand.
 - A git repository with `fimo` as the remote, and — after dependencies install — an initial commit (including the lockfile) plus an initial push
 
@@ -120,7 +128,11 @@ Nothing is written into per-agent skill dirs: the rich skills are fetched on dem
 
 Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md.
 
-`.env` is only the bootstrap app env so local `pnpm dev` works immediately. Fimo writes the tenant API aliases used by its supported frameworks; users should not discover or set those URLs manually. User-managed public variables are stored with `fimo vars add` and synced into a managed `.env.local` block; hidden values use `fimo secrets add`. See `references/project-vars-and-secrets.md`.
+Supported framework runtimes derive the Fimo connection from
+`.fimo/project.json` and the active git branch, so local development needs no
+Fimo env file. User-managed public variables are stored with `fimo vars add`
+and synced into a managed `.env.local` block; hidden values use
+`fimo secrets add`. See `references/project-vars-and-secrets.md`.
 
 ## Right after scaffolding
 

package/assets/skills/fimo-cli/references/project-vars-and-secrets.md

@@ -47,7 +47,9 @@ variables.
 
 ## Local Env Files
 
-`fimo init` and `fimo clone` write `.env` with the framework-specific tenant content API URLs needed for local development. These are Fimo-managed connection values, not project variables; users should not discover or set them manually.
+`fimo init`, `fimo clone`, and `fimo link` do not write the Fimo connection to
+an env file. Supported framework runtimes derive it from `.fimo/project.json`
+and the active git branch; hosted preview and production inject it directly.
 
 `fimo vars add`, `fimo vars update`, and `fimo vars pull` write public project variables to a managed block in `.env.local`.
 

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

@@ -19,7 +19,7 @@ fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the l
 - **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo/project.json` and agent files. Use `fimo clone <projectId>` when scripting or when the ID is known. In an interactive terminal, bare `fimo clone` opens a project picker for the active org; JSON mode and non-TTY shells require an explicit project ID and fail fast instead of prompting. By default it clones `main`; pass `--branch <name>` to clone a specific Branch. The legacy `--env <name>` spelling remains a compatibility alias. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
 - **`delete`** — destructive; prompts unless `-y`. Removes the remote project.
 - **`publish` / `unpublish`** — toggle the project's public visibility. `publish` flips the current `main` state live (the same "go live" as `fimo deploy --publish`, minus the git push).
-- **`rename`** — edits only the linked local project immediately. It requires a project marker in the cwd, and if you pass a `[projectId]` that doesn't match the linked project it errors and exits 1 (so you can't rename a different project). It writes `seo.siteName` into the current or legacy project config; commit and run `fimo deploy` to reconcile the remote `displayName` and deploy the new site name.
+- **`rename`** — edits only the linked local project's `seo.siteName`. It does not commit or deploy. It requires a project marker in the cwd, and if you pass a `[projectId]` that doesn't match the linked project it errors and exits 1 (so you can't rename a different project). Later remote config commands may require reconciliation while the local config is dirty. Finish your local edits, then explicitly run `fimo deploy --no-wait` when ready for a quick sync.
 
 ## Top-level clone shortcut
 
@@ -39,7 +39,7 @@ fimo unpublish [-C <dir>]        # unpublish the current project
 fimo rename "<Site Name>"        # local edit: set seo.siteName in the project config
 ```
 
-`fimo rename` sets the **site name** (`seo.siteName`) in the local project config — it is a local edit, not an immediate remote update, so it requires a follow-up commit + `fimo deploy` to take effect. Deploy reconciles the project's remote `displayName` with the committed site name while pushing the config. See `references/init.md` and `references/deploy.md`.
+`fimo rename` sets the **site name** (`seo.siteName`) in the local project config. It does not commit or deploy. Later remote config commands may require reconciliation while that local config is dirty. Finish your local edits, then explicitly run `fimo deploy --no-wait` when ready for a quick sync. Deploy reconciles the project's remote `displayName` while pushing the config. See `references/init.md` and `references/deploy.md`.
 
 ## Publish commands
 

package/assets/skills/fimo-code/assets/react-router-locales/navigation.tsx

@@ -1,4 +1,4 @@
-import { FimoLink } from 'fimo/react-router';
+import { FimoLink } from 'fimo-react-router';
 
 export function Navigation() {
   return (

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

@@ -24,7 +24,7 @@ Generated content reads wrap this stored value in `FimoMedia`, which exposes `ur
 
 ## Rendering in application code
 
-Import the primitives from the active framework adapter: `fimo/next` on the Next server, `fimo/next/client` in Next Client Components, `fimo/ui` in React Router/Vite, or `fimo/astro/components` in Astro pages.
+Import the primitives from the active framework adapter: `fimo-next` on the Next server, `fimo-next/client` in Next Client Components, `fimo-react` in React Router/Vite, or `fimo/astro/components` in Astro pages.
 
 | Asset source                                        | Component             | Pass via                  |
 | --------------------------------------------------- | --------------------- | ------------------------- |
@@ -32,7 +32,7 @@ Import the primitives from the active framework adapter: `fimo/next` on the Next
 | Hard-coded URL or generated asset referenced inline | `<StaticImage>`       | `src="https://..."`       |
 
 ```tsx
-import { Image, StaticImage, Video } from 'fimo/next';
+import { Image, StaticImage, Video } from 'fimo-next';
 
 // from a schema entry:
 <Image value={post.coverImage} width={1200} height={630} fit="cover" />

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

@@ -13,7 +13,7 @@ Load `references/frameworks/next.md` and the matching router reference first. In
 
 ```ts
 import type { NextConfig } from 'next';
-import { withFimo } from 'fimo/next/config';
+import { withFimo } from 'fimo-next/config';
 
 const nextConfig: NextConfig = {
   cacheComponents: true,

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

@@ -106,7 +106,7 @@ export function ContactForm() {
 
 ## Framework bindings
 
-- **Vite/React:** `submitX(data)` keeps using the existing `fimo/ui` runtime and preserves the current generated API.
+- **Vite/React:** `submitX(data)` keeps using the existing `fimo-react` runtime and preserves the current generated API.
 - **Next.js:** server modules import `@/forms/name`; client components import `@/forms/name.client`. Both expose the same `submitX(data)` shape.
 - **Astro:** import the generated server module and call `submitX(data)` in an Astro action or endpoint. Astro keeps the HTML form and redirect.
 - **SvelteKit:** use `createFimoFormClient({ event })` in a server action and pass it as the second argument: `submitX(data, client)`.

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 });

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" />;
 ```