fimo 0.14.0 → 0.15.0-staging.2

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

@@ -1,7 +1,5 @@
 # Project Variables And Secrets
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 Use project variables for values that are safe to expose to the browser. Use project secrets for hidden values such as API keys, tokens, webhooks, and service credentials.
 
 There is no private-variable mode. If leaking the value would be a problem, use `fimo secrets`.
@@ -49,7 +47,7 @@ variables.
 
 ## Local Env Files
 
-`fimo init` writes `.env` with tenant content API URLs for Vite and Next runtimes. This lets the framework's normal dev command work without a Fimo wrapper.
+`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 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

@@ -1,7 +1,5 @@
 # Managing projects
 
-> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
-
 Commands for listing projects across an org, cloning a remote project locally, and managing the lifecycle of a single project (delete, publish, unpublish, rename). Most lifecycle commands operate on the **current project** (read from `.fimo/project.json`, or the legacy `.fimo.settings.json`, in the cwd) by default; for `delete`, `publish`, and `unpublish` you can pass an explicit `[projectId]` to target another. (`rename` only edits the linked local project; see below.)
 
 ## The `fimo projects` namespace
@@ -29,7 +27,7 @@ fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the l
 fimo clone [projectId] [dir] [--env <name>] # same as `fimo projects clone`
 ```
 
-Use the top-level shortcut for the common "get this project onto my machine" workflow. After clone succeeds, `cd` into the printed directory, `Read` the project's `AGENTS.md`, and load the code skill with `npx fimo@latest skills get fimo-code` before generating code.
+Use the top-level shortcut for the common "get this project onto my machine" workflow. After clone succeeds, `cd` into the printed directory, `Read` the project's `AGENTS.md`, and load the code skill with `fimo skills get fimo-code` before generating code.
 
 ## Top-level shortcuts (current project)
 

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

@@ -1,7 +1,5 @@
 # Scheduled Commands
 
-> **Run via `npx fimo@latest <command>`** - always the latest CLI, no install needed.
-
 `fimo schedules` manages recurring commands for one project environment. It uses the current checkout environment by default, or the environment passed with `--env <name>`.
 
 The command starts in that environment's sandbox. Commands can still target another environment explicitly, for example with `fimo schemas list --env preview`.

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

@@ -1,7 +1,5 @@
 # Reporting a problem to Fimo
 
-> **Run via `npx fimo@latest <command>`** - always the latest CLI, no install needed.
-
 `fimo support report` sends a project-scoped problem to Fimo support. It automatically includes the project, current environment, and CLI version so support can start investigating without asking the user to repeat that context.
 
 ## When to prepare it

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

@@ -1,7 +1,5 @@
 # Outbound webhooks
 
-> **Run via `npx fimo@latest <command>`** so the event catalog and delivery commands match the platform.
-
 > **Beta:** Test each destination and inspect its delivery history before depending on it in production.
 
 Use `fimo webhooks` to send project events to external HTTPS endpoints. The CLI and Studio edit the same project-wide configurations and delivery history. The CLI has no provider presets: inspect the destination's API documentation, then pass its URL, headers, and JSON body explicitly.

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

@@ -4,7 +4,7 @@ description: >-
   Write schema-first application code with the installed `fimo` package.
   Load when declaring content schemas or forms, using generated content
   clients, rendering Fimo primitives, reading labels, or integrating Fimo
-  with Next.js, React Router, Vite, or another application framework. CLI
+  with Next.js, React Router, Vite, SvelteKit, or another application framework. CLI
   commands and operational workflows live in the `fimo-cli` skill.
 ---
 
@@ -30,7 +30,14 @@ Framework routing:
 - `nextjs` or an `app/`, `src/app/`, `pages/`, or `src/pages/` tree → `references/frameworks/next.md`, then the matching App Router or Pages Router reference.
 - React Router framework mode (`react-router.config.ts`, `src/routes.ts`) → `references/frameworks/react-router.md`.
 - Vite + React without framework mode → `references/frameworks/vite-react.md`.
-- Astro, Nuxt, Remix, SvelteKit, Vue, or another hosting-only setup → `references/frameworks/hosting.md`. The current content/primitives SDK is React-only; do not invent a framework adapter.
+- Astro (`astro.config.*`, `src/pages/**/*.astro`) → `references/frameworks/astro.md`.
+- SvelteKit → `references/frameworks/sveltekit.md`.
+- Nuxt, Remix, Vue, or another hosting-only setup → `references/frameworks/hosting.md`. Do not invent an SDK adapter that the installed package does not export.
+
+When a project's framework version is uncertain, load
+`references/frameworks/compatibility.md`. Use the project's installed version
+and the documented adapter range; do not assume that a framework profile means
+every historical version is supported.
 
 ## Durable content contract
 
@@ -50,8 +57,9 @@ Each reference defines one package contract. Fetch it when the task reaches that
 - Tracked rendering: `Text`, `RichText`, `Image`, `FimoString`, `FimoMedia` → `references/ui.md`
 - Forms: JSON spec, generated Zod schema, `submit*` helpers → `references/forms.md`
 - Media values, `<Image>`, `<StaticImage>` → `references/assets.md`
-- Static editable copy: `t()`, `useLabels`, `getLabels` → `references/labels.md`
+- Static editable copy: `Label`, `t()`, providers, and server label readers → `references/labels.md`
 - Locale ownership and framework handoff → `references/locales.md`
+- Astro connector and output/adapter contract → `references/frameworks/astro.md`
 - Framework detection, production routing, and hosting adapters → `references/frameworks/hosting.md`
 - Major visual work → `references/design.md`
 

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

@@ -22,9 +22,9 @@ Asset values returned from `fimo assets upload` or Fimo media tasks, and stored
 
 Generated content reads wrap this stored value in `FimoMedia`, which exposes `url`, `alt`, `name`, `mime`, and optional `width`/`height`. It does not expose `source`; Fimo tracks that internally. Pass the whole entry value to `<Image>` / `<Video>`.
 
-## Rendering in JSX
+## 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, or `fimo/ui` in React Router/Vite.
+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.
 
 | Asset source                                        | Component             | Pass via                  |
 | --------------------------------------------------- | --------------------- | ------------------------- |

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

@@ -2,7 +2,11 @@
 
 Application code imports the public modules generated from `src/schemas/<Uid>.json`, not `.types.ts` directly.
 
-The exact file split is framework-dependent. Load `references/frameworks/next.md`, `references/frameworks/react-router.md`, or `references/frameworks/vite-react.md` before choosing imports.
+The exact file split is framework-dependent. Load the matching reference under
+`references/frameworks/` before choosing imports. This includes the Next.js,
+Astro, React Router, Vite React, and SvelteKit references. Astro modules are
+server-only promise clients; the hooks below exist only in client-capable
+frameworks.
 
 ## Entry shape
 

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

@@ -7,8 +7,10 @@ Load only what the task needs:
 - `references/content/schema.md` — schema JSON, field types, blocks, references, and safe transitions.
 - `references/content/richtext.md` — Tiptap JSONContent, entry payloads, and slug rules.
 - `references/content/clients.md` — generated collection/singleton clients, queries, projections, population, and locale behavior.
-- `references/ui.md` — source-tracked values and their React renderers.
+- `references/ui.md` — source-tracked values and their framework renderers.
 - `references/frameworks/next.md` — Next App/Pages Router module boundaries.
+- `references/frameworks/astro.md` — Astro server clients and native components.
+- `references/frameworks/sveltekit.md` — request-bound clients, load serialization, native components, and labels.
 - `references/frameworks/react-router.md` — React Router framework-mode setup and imports.
 - `references/frameworks/vite-react.md` — Vite + React setup and imports.
 

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

@@ -0,0 +1,127 @@
+# Astro integration
+
+Use this reference for an existing Astro application. The application keeps its route files, output mode, adapter, locale system, links, `<html lang/dir>`, and SEO. Fimo connects content, labels, native rendering, preview, and hosting.
+
+## Setup
+
+Declare the production framework in `.fimo/config.json`:
+
+```json
+{
+  "runtime": { "framework": "astro" }
+}
+```
+
+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:
+
+```js
+import { defineConfig } from 'astro/config';
+import { fimo } from 'fimo/astro/config';
+
+export default defineConfig({
+  integrations: [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
+existing adapter until a matching server adapter is supported.
+
+`fimo()` loads the platform script only in Fimo previews, reports location to Studio, and performs full-page navigation when Studio changes routes. With `output: 'server'` and no adapter, it also supplies Fimo's hosted server adapter; it never replaces an adapter the application already owns for another deployment target.
+
+Server reads use `FIMO_CONTENT_API_URL`. `fimo init` and `fimo clone` provide it locally; hosted preview and production inject it (alias table: `references/frameworks/hosting.md`).
+
+## Generated content
+
+Declare content in `src/schemas/<Uid>.json` and apply each change with `fimo schemas push <Uid>` (workflow: `fimo-cli/references/content.md`). Astro receives one server-only `<Uid>.ts` public module plus `<Uid>.types.ts`. There are no `.client.ts` modules, React Query hooks, or browser content registry; reads run in frontmatter on the server.
+
+## Read and render
+
+Use generated schema modules for data, `fimo/astro` for `getLabels` and the `fimo` template tag, and `fimo/astro/components` for native components:
+
+```astro
+---
+import { fimo, getLabels } from 'fimo/astro';
+import { Image, RichText, Text } from 'fimo/astro/components';
+
+import * as SiteSettings from '../schemas/SiteSettings';
+import * as Story from '../schemas/Story';
+
+const locale = Astro.currentLocale; // or the app's own resolution — see Locales
+const [settings, stories, labels] = await Promise.all([
+  SiteSettings.get({ locale }),
+  Story.list({ locale, limit: 12 }),
+  getLabels({ locale }),
+]);
+---
+
+<Text as="h1" value={settings.siteName} />
+{
+  stories.items.map((story) => (
+    <article>
+      <Image value={story.cover} width={320} />
+      <Text as="h3" value={story.title} />
+      <RichText value={story.body} />
+      <a href={`/stories/${String(story.slug)}`}>
+        <Text as="span" value={fimo`${labels.t('story.readMore')}: ${story.title}`} />
+      </a>
+    </article>
+  ))
+}
+```
+
+The native surface is `Text`, `RichText`, `Image`, `StaticImage`, `Video`, `Date`, `Boolean`, and `Json` (component table: `references/ui.md`). Pass tracked values whole so Studio can resolve their source; use `String(value)` only for attributes and URLs.
+
+## Static and on-demand rendering
+
+Keep the application's per-route rendering choice:
+
+- Prerendered pages read content once at build; edited content appears after a rebuild/redeploy.
+- On-demand pages (`export const prerender = false`, or `output: 'server'`) read on every request and always serve current content.
+- A fully static app that needs on-demand routes and owns no adapter can set `output: 'server'`, mark still-static pages `export const prerender = true`, and let `fimo()` supply the server adapter.
+
+Expand prerendered dynamic routes from generated reads:
+
+```astro
+---
+import * as Story from '../../schemas/Story';
+
+export async function getStaticPaths() {
+  const { items } = await Story.list({ limit: 100 });
+  return items.map((story) => ({ params: { slug: String(story.slug) } }));
+}
+---
+```
+
+## Locales
+
+The application resolves the locale — route prefix, middleware, domain, `Astro.currentLocale`, cookie, or its i18n library — and passes it to content reads and `getLabels({ locale })`. When a server read omits `locale`, the Fimo API resolves the project default; do not hardcode a fallback locale in application code. Astro needs no Fimo locale provider. Ownership rules: `references/locales.md`.
+
+## Studio route catalog
+
+`.fimo/config.json#routes` is an optional catalog of pages for Studio navigation, not router configuration. Never replace or infer Astro's route files, redirects, middleware, or 404 behavior from it. Keep paths canonical and unlocalized, and describe dynamic segments with `params` so Studio can list entries:
+
+```json
+{
+  "routes": {
+    "home": { "label": "Home", "path": "/" },
+    "story": {
+      "label": "Story",
+      "path": "/stories/:slug",
+      "params": { "slug": { "schema": "Story", "queryField": "slug", "displayField": "title" } }
+    }
+  }
+}
+```
+
+## Client islands
+
+Generated content reads remain server-only. Preserve existing islands and do not add React or a client SDK to work around this boundary.
+
+## Recovery
+
+- `fimo schemas push` reports that the project-local `fimo` package lacks the `fimo/astro` export → upgrade the project's `fimo` dependency, then re-run validation with the project-installed CLI.
+- The site renders in preview but Studio cannot list or open pages → `fimo()` is missing from `astro.config.*`, or a route catalog `path` does not match the page's URL.

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

@@ -0,0 +1,19 @@
+# Framework compatibility
+
+`runtime.framework` selects Fimo's integration profile. The package's optional
+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                                                                   |
+
+The exact versions used by acceptance fixtures are test baselines, not values
+to copy into an application. If a project falls outside a documented range,
+report that boundary before changing framework code; do not silently downgrade
+or replace the application's framework.

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

@@ -28,9 +28,18 @@ Hosted preview and production inject the tenant API through these aliases:
 | Astro, Remix, SvelteKit | `FIMO_CONTENT_API_URL` | `PUBLIC_FIMO_API_URL`      |
 | React Router, Vite, Vue | `FIMO_CONTENT_API_URL` | `VITE_API_URL`             |
 
-Current `fimo init` and `fimo clone` write the Vite and Next aliases locally.
-For another framework, preserve or add its normal local environment alias; do
-not hardcode a tenant URL in application source.
+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`
+(`projectId` + `tenantApiBaseUrl`, recorded once at `init`/`clone`/`link`) and
+expose the Vite, Next and public (`PUBLIC_*`) aliases plus `FIMO_ENV` /
+`NEXT_PUBLIC_FIMO_ENV` at startup. No env file is written on a switch, so a plain `git checkout` is a
+complete env switch. Never hardcode a tenant URL in application source. One
+rule, per variable: a value the user set explicitly (`.env`, shell, their own
+`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.
 
 ## React Router framework mode
 
@@ -75,6 +84,9 @@ Next.js and the other supported native frameworks own their build and routing
 output. Do not add a catch-all rewrite; the framework's hosting preset handles
 routes, server functions, static output, and 404 responses.
 
+Astro has a dedicated connector — load `references/frameworks/astro.md` before
+editing an Astro config.
+
 `.fimo/config.json#routes` is the Studio page catalog, not deployment routing.
 Never generate hosting rewrites from it. If a project already has a
 provider-specific deployment file, preserve it; that file remains authoritative.

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

@@ -1,72 +1,33 @@
-# Setup Fimo on React Router 8
+# React Router framework mode
 
-This recipe describes the canonical Fimo + React Router framework-mode setup.
-It mirrors the default `fimo init` scaffold; you can also apply it to an
-existing RR project.
+This is the canonical Fimo + React Router framework-mode setup used by
+`fimo init`. You can also apply it to an existing React Router project: preserve
+its routes, rendering choices, providers, and SEO.
 
-## Prerequisites
+## Install and build
 
-- Node 22.22+
-- A Fimo project created via `fimo init` (gives you `projectId`,
-  `organizationId`, and an `apiUrl`).
+Install the peers the application uses:
 
-## Install
-
-```
+```bash
 pnpm add fimo react react-dom react-router @tanstack/react-query
-pnpm add -D @react-router/dev @react-router/node @tailwindcss/vite tailwindcss vite @types/node @types/react @types/react-dom typescript
-```
-
-## File: `package.json`
-
-```json
-{
-  "name": "__PROJECT_SLUG__",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "react-router dev --port 5173",
-    "build": "react-router build && fimo export-static",
-    "preview": "vite preview --host 0.0.0.0 --port 4173",
-    "typecheck": "tsc --noEmit"
-  }
-}
+pnpm add -D @react-router/dev @react-router/node vite
 ```
 
-## File: `vite.config.ts`
+Keep the project's React Router Vite plugin explicit:
 
 ```ts
 import { reactRouter } from '@react-router/dev/vite';
-import { resolve } from 'path';
 import { defineConfig } from 'vite';
-
 import { fimo } from 'fimo/vite';
 
 export default defineConfig({
   plugins: [reactRouter(), fimo({ sitemap: true })],
-  resolve: {
-    alias: {
-      '@': resolve(__dirname, './src/'),
-    },
-  },
 });
 ```
 
-Notes:
+`fimo()` is synchronous and returns a Vite `PluginOption[]`. Do not enable `seo: true`; React Router route `meta` exports own SEO.
 
-- **You** call `reactRouter()`. `fimo/vite` no longer auto-injects it — the
-  user's vite.config owns the framework plugin. This is the library-mode shape.
-- `fimo()` is synchronous; it returns a `PluginOption[]` you drop straight into
-  `plugins`. Don't `await` it or spread it.
-- Do **not** add `fimo({ seo: true })` here. RR handles SEO via the `meta`
-  export (see `src/root.tsx`); the build-time SEO plugin would conflict.
-- `sitemap` is opt-in and off by default; pass `fimo({ sitemap: true })` to emit
-  `sitemap.xml` (the canonical template does this). Omitting the option leaves
-  it off.
-- `fimo({ robots: true })` opt-in to emit `robots.txt`.
-
-## File: `react-router.config.ts`
+For the supported client-rendered setup, connect React Router's native build to Fimo hosting:
 
 ```ts
 import type { Config } from '@react-router/dev/config';
@@ -76,59 +37,26 @@ export default {
   appDirectory: 'src',
   ssr: false,
   presets: [fimoPreset()],
-  // Static-site generation is opt-in. By default this template builds as an
-  // SPA (single index.html shell, client-side routing). To prerender routes at
-  // build time — required for crawler-visible per-route SEO — add this line:
-  //
-  //   import { getFimoPaths } from 'fimo/paths';
-  //   prerender: async () => (await getFimoPaths()).map((p) => p.path),
-  //
-  // `getFimoPaths()` expands dynamic routes (e.g. `/blog/:slug`) by fetching
-  // schema entries from the content API. See `references/frameworks/react-router.md`
-  // in the fimo skill for the full setup pattern.
-  buildDirectory: 'dist',
 } satisfies Config;
 ```
 
-`fimoPreset()` connects the client-rendered build to Fimo hosting without
-exposing a provider package. See `references/frameworks/hosting.md`; do not
-apply this SPA preset to an existing SSR project.
-
-**SSG is opt-in now.** Default = SPA (one HTML shell). Add `prerender`
-yourself if you want crawler-visible per-route HTML. The previous
-"prerender everything by default" behavior was a website-builder opinion
-that doesn't fit infrastructure mode — your call which routes to prerender,
-when to render them, and how.
+Do not change an existing SSR project to `ssr: false` merely to add Fimo. The current adapter does not provide React Router SSR support. Prerendering is application-owned and opt-in.
 
-## File: `src/root.tsx`
+## Application root
 
-The explicit `QueryClientProvider` below is the canonical template shape so the
-app can configure query defaults such as `staleTime`. Adopted SPAs can omit it:
-`FimoProviders` reuses an ancestor client when present and supplies a stable
-fallback otherwise.
+`FimoProviders` reuses an ancestor React Query client or supplies a stable fallback. Keep an explicit ancestor when the application owns query defaults or shares the cache:
 
 ```tsx
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-import { FimoProviders, FimoScripts, loadFimoMetaData, buildFimoMeta, fimoHtmlProps } from 'fimo/react-router';
-import type { MetaFunction } from 'react-router';
+import { FimoProviders, FimoScripts } from 'fimo/react-router';
 import { Links, Meta, Outlet, Scripts, ScrollRestoration } from 'react-router';
 
-const queryClient = new QueryClient({
-  defaultOptions: { queries: { staleTime: Infinity } },
-});
-
-export async function loader(args: { request: Request }) {
-  return loadFimoMetaData(args);
-}
-
-export const meta: MetaFunction = (args) => buildFimoMeta(args);
+const queryClient = new QueryClient();
 
 export function Layout({ children }: { children: React.ReactNode }) {
   return (
-    <html {...fimoHtmlProps()}>
+    <html>
       <head>
-        <meta charSet="utf-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1" />
         <Meta />
         <Links />
         <FimoScripts />
@@ -153,7 +81,11 @@ export default function AppRoot() {
 }
 ```
 
-## File: `src/routes.ts`
+Keep the application's existing `Layout` details. Add only the Fimo provider and script connector required by the task.
+
+## Routes and locales
+
+`fimoRoutes()` is an optional helper for Fimo's path-prefix locale convention:
 
 ```ts
 import type { RouteConfig } from '@react-router/dev/routes';
@@ -161,142 +93,38 @@ import { index } from '@react-router/dev/routes';
 import { fimoRoutes } from 'fimo/react-router/routes';
 
 const routes = [index('./pages/Index.tsx', { id: 'home' })] satisfies RouteConfig;
-
 export default fimoRoutes(routes) satisfies RouteConfig;
 ```
 
-Page filenames are your choice; the scaffold uses PascalCase (e.g. `Index.tsx`,
-`Privacy.tsx`).
+Custom locale routers can skip it and pass their resolved locale to `<FimoProviders locale={locale}>`. Use `FimoLink` only when the application adopts Fimo's locale-aware link behavior; otherwise preserve its links. Copyable path-prefix locale examples live in `assets/react-router-locales/`.
 
-`fimoRoutes()` is Fimo's React Router helper for path-prefix locales. It is a no-op for single-locale projects and expands concrete locale aliases when `.fimo/config.json#i18n.locales` contains more locales. Custom routers can ignore this helper and pass their own locale to `<FimoProviders locale={locale}>`; see `references/locales.md`.
+## Content and labels
 
-### Locale-aware navigation
-
-Use `FimoLink` for internal links that should preserve the current locale or deliberately switch it:
+Render tracked values with `fimo/ui`:
 
 ```tsx
-import { FimoLink } from 'fimo/react-router';
+import { Image, Label, RichText, Text } from 'fimo/ui';
 
-<FimoLink to="/pricing">Pricing</FimoLink>
-<FimoLink to="/pricing" locale="es">Spanish pricing</FimoLink>
+return <Label value="home.hero.title" as="h1" />;
 ```
 
-Read the active locale with `useLocale()` when component logic needs the locale list, current canonical route, or document direction:
+Use `useLabels().t()` for attributes, metadata, or composed strings. `references/labels.md` owns the complete contract.
 
-```tsx
-import { useLocale } from 'fimo/ui';
+## Project profile
 
-const { locale, defaultLocale, locales, routePath, dir } = useLocale();
-```
-
-`FimoLink` localizes absolute internal paths using `.fimo/config.json#i18n.routing`; relative, hash, query-only, and external URLs remain unchanged. Copyable route and navigation examples live in `assets/react-router-locales/`.
-
-## File: `src/pages/Index.tsx`
-
-```tsx
-import { Text, useLabels } from 'fimo/ui';
-
-export default function HomePage() {
-  const { t } = useLabels();
-
-  return (
-    <main>
-      <Text value={t('home.hero.title')} as="h1" />
-    </main>
-  );
-}
-```
-
-## File: `.fimo/config.json`
-
-```json
-{
-  "runtime": { "framework": "react-router" },
-  "version": "4",
-  "seo": {
-    "title": "__PROJECT_SLUG__",
-    "siteName": "__PROJECT_SLUG__"
-  },
-  "routes": {
-    "home": {
-      "label": "Home",
-      "path": "/"
-    }
-  }
-}
-```
-
-## File: `.fimo/project.json`
-
-```json
-{
-  "projectId": "__PROJECT_ID__",
-  "organizationId": "__ORG_ID__",
-  "apiUrl": "__API_URL__"
-}
-```
-
-Replace the `__PROJECT_ID__` / `__ORG_ID__` / `__API_URL__` sentinels with the
-values from `fimo init`'s output (or `fimo projects info`).
-
-## File: `tsconfig.json`
+Declare the runtime in `.fimo/config.json`:
 
 ```json
 {
-  "compilerOptions": {
-    "target": "ES2022",
-    "lib": ["DOM", "DOM.Iterable", "ES2022"],
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "jsx": "react-jsx",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "resolveJsonModule": true,
-    "isolatedModules": true,
-    "types": ["@react-router/node", "vite/client"],
-    "paths": { "@/*": ["./src/*"] }
-  },
-  "include": ["src", "*.config.ts"]
+  "runtime": { "framework": "react-router" }
 }
 ```
 
-## File: `index.css`
-
-```css
-@import 'tailwindcss';
-```
-
-(Optional — only if using Tailwind. Tailwind is not required for Fimo to
-function; it just ships with the canonical template.)
-
-## Verify and iterate
-
-Run the app with the project's package-manager `dev` script (`pnpm dev` /
-`npm run dev` / `yarn dev` / `bun dev` — match the lockfile). It serves the site
-on localhost with live reload — this is your iteration loop: edit, see the change,
-repeat with the developer.
-
-`fimo deploy` is on-demand, not part of this loop: run it only when the developer
-wants a hosted preview, a shareable link, or to go live — and only on their signal.
-The dashboard's preview iframe shows the **deployed** app, so it only reflects
-changes after a `fimo deploy` (the local dev server is localhost-only).
-
-## What you don't add
-
-- **No `fimo({ seo: true })`** — React Router's `meta` export covers SEO via
-  `loadFimoMetaData` + `buildFimoMeta`. The build-time SEO plugin is for
-  framework-less Vite + React setups (`references/frameworks/vite-react.md`).
-- **No `<FimoSeo />` component** — not part of the RR setup.
-- **No manual `<script src="overlay-runtime.js">`** — `<FimoScripts />`
-  handles preview-script + overlay loading.
+The optional `routes` object is Studio's semantic page catalog. Keep it aligned with application routes when the project uses Studio navigation, but do not treat it as the production router.
 
-## What to do next
+## Boundaries
 
-- Add more routes: extend `src/routes.ts`, create matching `src/pages/*.tsx`,
-  add route entries in `.fimo/config.json#routes`.
-- Add a sitemap: pass `fimo({ sitemap: true })` (opt-in, off by default; the
-  canonical template enables it). To customize the base URL, set
-  `.fimo/config.json#seo.url`.
-- Override SEO per route with React Router's `meta` export and the existing `loadFimoMetaData` / `buildFimoMeta` integration in `src/root.tsx`.
-- Look up rendering exports in `references/ui.md` and generated content APIs in `references/content/clients.md`.
+- Route modules and `meta` exports own routing and SEO.
+- `FimoScripts` owns preview-script loading; do not add the overlay script manually.
+- 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.