fimo 0.21.0-staging.4 → 0.21.0-staging.6

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

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 = {
@@ -134,7 +143,7 @@ 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/ui.md

@@ -73,11 +73,11 @@ Never construct `FimoString`, `FimoRichText`, `FimoBoolean`, or `FimoMedia` manu
 
 Choose the framework surface:
 
-- Next Server Components and data functions → `fimo/next`
-- Next Client Components → `fimo/next/client`
-- React Router/Vite client → `fimo/ui`
+- Next Server Components and data functions → `fimo-next`
+- Next Client Components → `fimo-next/client`
+- React Router/Vite client → `fimo-react`
 - Astro pages → `fimo/astro/components`
-- Svelte components → `fimo/sveltekit/components`
+- Svelte components → `fimo-sveltekit/components`
 
 Load the framework reference before copying an example. Next server and client imports are deliberately separate so React Query/client code does not leak into server bundles. Astro uses native `.astro` components and does not require React.
 

package/assets/skills/fimo-migration/references/frameworks/nextjs.md

@@ -86,21 +86,18 @@ behavior in place; when one cannot be preserved, record an explicit gap with
 the affected routes instead of shipping pages that silently lost their share
 metadata.
 
-## Build-time and browser runtime
-
-The Next server runtime reads `FIMO_CONTENT_API_URL`; client components and
-generated client hooks read `NEXT_PUBLIC_FIMO_API_URL`. For a local production
-build or migration acceptance run, expose both names and point them at the
-same tenant content URL. `FIMO_API_URL` is the management/CLI API and is not a
-substitute for either content API variable.
-
-`withFimo` derives these aliases during `next dev` when the project is linked,
-so local development does not need hand-written values. A production build,
-however, compiles `NEXT_PUBLIC_*` values into the browser bundle and the
-adapter intentionally does not inject them outside the development phase.
-For `next build`/`next start`, set temporary values in the shell or an ignored
-`.env.local`; never commit secret values. In either mode, exercise at least one
-client-side data read after startup.
+## Fimo connection
+
+Follow the target project's `fimo-code` Next.js reference and render its
+`FimoProvider` once at the application root. The provider uses an explicit
+host connection when one exists; otherwise it resolves the linked project and
+active git branch on the server and passes only the public connection to the
+browser. `withFimo` handles hosted preview origins, not the application
+connection.
+
+Do not create or edit `.env` / `.env.local` for a linked project's Fimo
+connection. Run the project's normal `next dev`, `next build`, and `next start`
+commands, then exercise at least one server read and one client-side data read.
 
 ## Preview embedding and response headers
 

package/assets/skills/fimo-migration/references/media.md

@@ -53,8 +53,10 @@ sources point to one uploaded asset.
 
 ## Upload And Replacement
 
-Referenced media must be uploaded into the Fimo media library with
-`fimo assets upload`. Copying a file under `public/` so the deployed site can
+Referenced media must be uploaded into the Fimo media library. Use
+`fimo assets bulk-upload --file <manifest.json>` for a batch and keep one
+unique `sourceId` per media item; use `fimo assets upload` for a single file.
+Never encode paths or names in whitespace-delimited shell input. Copying a file under `public/` so the deployed site can
 serve it is **not** a completed import: it has no Fimo asset id/URL, editors
 cannot manage it, and the QA gate treats a referenced-but-not-uploaded asset as
 failing. Either upload it (and record the Fimo target), or mark it `unresolved`

package/assets/skills/fimo-migration/references/qa.md

@@ -86,11 +86,11 @@ items.
   used a user export or narrowly scoped server-side credential. Missing access
   is unresolved for that lane, and no content was guessed.
 
-For linked Next.js targets, `withFimo` derives `FIMO_CONTENT_API_URL` and
-`NEXT_PUBLIC_FIMO_API_URL` from `.fimo/project.json` during `next dev`,
-`next build`, and `next start`. Both aliases resolve to the same tenant API,
-while non-empty user overrides remain untouched; no committed env file is
-required.
+For linked Next.js targets, the root `FimoProvider` resolves an explicit host
+connection first, otherwise `.fimo/project.json` plus the active git branch,
+and passes only the public connection to the browser. `withFimo` handles
+hosted preview origins, not this connection. Run the normal `next dev`,
+`next build`, and `next start` commands without creating a Fimo env file.
 
 ## Hosting
 
@@ -104,9 +104,9 @@ Owned by the runtime lane; verified here read-only.
   translation goes through `FIMO_PREVIEW_ALLOWED_ORIGINS`; `withFimo` alone
   does not solve headers — it only extends `allowedDevOrigins` during
   `next dev`.
-- The runtime report covers local startup, preview embedding, build, derived
-  aliases, header translations, and integration env-key names, with every
-  claim backed by evidence.
+- The runtime report covers local startup, preview embedding, build, the
+  resolved Fimo connection, header translations, and integration env-key
+  names, with every claim backed by evidence.
 - With a browser available, record `browserProof` (rendered route plus console
   state) for startup and embedding. Without one, use deterministic HTTP
   status/header/process/log checks and mark visual proof explicitly
@@ -149,6 +149,8 @@ one bounded, scriptable browser pass (Playwright, agent-browser, or
 equivalent):
 
 1. Start the app and wait for hydration, not just the HTTP response.
+   Do not use `networkidle` against dev/HMR servers; wait for expected visible
+   content and image readiness.
 2. Open a representative set of pages: home, one collection listing, one
    collection detail, one static page.
 3. Exercise one representative interaction (open the nav menu, an accordion,

package/assets/skills/fimo-migration/references/workers/content-planner.md

@@ -3,10 +3,9 @@
 Own semantic discovery, schema authoring, payload preparation, and the text
 handoff. Do not import entries or rewrite application consumers.
 
-1. Inspect every content-bearing source and consumer: Markdown/MDX bodies and
-   frontmatter, JSX/TSX modules, hardcoded arrays and objects, imports, data
-   clients, and call sites. Identify whether each active source is a file,
-   inline value, API, CMS, or a mix before designing schemas.
+1. Trace active source clients, endpoint/query declarations, frontend types,
+   and every consumer before designing schemas. Then inspect their
+   content-bearing files, inline values, APIs, or CMS sources.
 2. Classify each value as collection content, single content, an
    editor-visible label, or application-owned code. Repetition is evidence,
    not an automatic collection rule. Assistive text, identifiers, and values
@@ -62,11 +61,12 @@ data workers start:
    queries, pagination, locales, publication states, relations, media, and
    consuming call sites. Server rendering may hide requests from the browser,
    so browser traffic is fallback evidence rather than the source of truth.
-2. Prove access with one read-only request. Read public APIs directly. Private
-   APIs require an owner-provided export or narrowly scoped server-side
-   credential; never recover, log, persist, or copy secret values. If the base
-   URL or required access is missing or unreachable, stop and ask the user for
-   it before planning schemas or payloads.
+2. Prefer authoritative backend schemas when source exists. Otherwise probe
+   public OpenAPI metadata, then GraphQL introspection, then only the selected
+   REST endpoints. Ask for an owner-provided export or narrowly scoped
+   server-side token only when website-required records are not public. Never
+   recover, log, persist, or copy secret values. If required access is missing
+   or unreachable, stop before planning schemas or payloads.
 3. Fetch every required page, locale, and referenced record. For a few bounded
    endpoints, direct requests are enough. For repeated or paginated reads,
    write a temporary source-specific read-only script under
@@ -75,7 +75,17 @@ data workers start:
    normalize transport details only. Do not create a provider registry or a
    universal CMS model.
 5. Design Fimo schemas from both the retrieved values and the code that uses
-   them. Never invent replacement content when source access is unavailable.
+   them. Keep uncertain fields optional unless authoritative evidence requires
+   them; sampled enum-like values are strings, and private or absent fields
+   remain unknown. Never invent replacement content when access is unavailable.
+
+For Strapi, the source and public-instance accelerators under
+`scripts/retrieval/strapi/` accept only explicit backend roots, content types,
+and endpoints. The worker may adapt or replace them; they preserve evidence but
+never select content or decide the target schema. Preserve source record order
+by importing in that order; do not add a source-ID or sort field solely to
+recreate creation order. Add an explicit sort field only when the source has
+editorial ordering or another consumer requires stable order.
 
 Once retrieval and consumer tracing are complete, push schemas, prepare
 payloads, and let the coordinator fan out assets and one data batch per

package/assets/skills/fimo-migration/references/workflow.md

@@ -49,12 +49,14 @@ them into migration artifacts. If the source API URL or access is missing or
 unreachable, stop and ask the user for it; do not guess or continue with
 replacement content.
 
-For API-backed content, trace the active client and call sites in source code,
-prove one read, then retrieve all required pages, locales, relations, and media
-during content planning. Use direct requests for bounded endpoints or a
-temporary read-only script for repeated and paginated reads. Do not wait for
-schema or code workers, and do not rely on browser traffic when SSR or build
-time fetches may hide the requests.
+For API-backed content, trace active clients, endpoints, frontend types, and
+consumers first. Prefer backend source schemas; otherwise use public OpenAPI,
+GraphQL introspection, then selected REST endpoints in that order. Request a
+token or export only for website-required records that are not public. Retrieve
+all required pages, locales, relations, and media during content planning.
+Treat absent/private fields as unknown, keep uncertain fields optional, and do
+not turn sampled values into enums. Bounded retrieval scripts are accelerators
+the planner may adapt or replace, never schema decision makers.
 
 For URL-only migrations, run `fimo migrate <url> [dir]` and inspect the
 generated `.fimo/migrations/current/` files as source evidence. Do not copy