fimo 0.12.0-staging.3 → 0.12.0-staging.4

package/assets/content-templates/types-template.eta

@@ -225,15 +225,21 @@ function isOptionalOutputField(field) {
 function isConditionalField(field) {
   return field.showIf !== undefined || field.showIfAny !== undefined;
 }
+
+const populatedReferenceFields = Object.entries(model.fields || {}).filter(([, field]) => {
+  if (field.type !== 'reference') {
+    return false;
+  }
+  return (Array.isArray(field.targetRefs) && field.targetRefs.length > 0) || typeof field.targetPascal === 'string';
+});
 -%>
 
+<% if (populatedReferenceFields.length === 0) { -%>
+export type <%= model.pascal %>References = Record<never, never>;
+<% } else { -%>
 export interface <%= model.pascal %>References {
 <%
-if (model.fields) {
-  Object.entries(model.fields).forEach(([key, field]) => {
-    if (field.type !== 'reference') {
-      return;
-    }
+populatedReferenceFields.forEach(([key, field]) => {
     // Polymorphic populated values form a discriminated union on $type —
     // the generated wrapper stamps it, so `switch (item.$type)` narrows.
     if (Array.isArray(field.targetRefs) && field.targetRefs.length > 0) {
@@ -252,10 +258,10 @@ if (model.fields) {
 -%>
   <%= key %>: <%= type %>;
 <%
-  });
-}
+});
 -%>
 }
+<% } -%>
 
 export type <%= model.pascal %>Populate = Populate<<%= model.pascal %>>;
 

package/assets/skills/fimo/SKILL.md

@@ -2,7 +2,7 @@
 name: fimo
 description: >-
   Working in or with a Fimo project (a content + media + forms + analytics
-  platform for React websites). Load the current Fimo skills on demand through
+  platform for web applications). Load the current Fimo skills on demand through
   the `fimo` CLI before doing Fimo work — writing schema-driven
   code, running CLI/deploy workflows, using the dashboard, or migrating a site.
 ---
@@ -23,7 +23,7 @@ not files in the project. Load them through the CLI, for example
 
 Pick by task:
 
-- Writing code — schema-driven JSX, schemas/forms JSON, `t()` labels, `fimo/ui` media → `fimo-code`
+- Writing code — schemas/forms, generated clients, labels, framework adapters, rendering primitives → `fimo-code`
 - CLI commands and workflows — push, deploy, sync, labels, domains, analytics → `fimo-cli`
 - Fimo agents — create, configure, validate, deploy, run, or inspect them → `fimo-cli` (`references/agents.md`)
 - AI agent setup — connect Claude Code, Codex, Cursor, or another agent → `fimo-cli` (`references/agent-setup.md`)

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

@@ -9,7 +9,7 @@ description: >-
 
 # Fimo CLI
 
-The `fimo` CLI is the workflow surface for Fimo. Fimo is a content + media + forms + analytics platform for React websites with a CMS dashboard. The CLI handles project creation, content / forms / media / labels / locale workflows, deploys, collaboration, account management, Fimo agents, and AI agent setup.
+The `fimo` CLI is the workflow surface for Fimo. Fimo connects content, media, forms, analytics, editing, and hosting to web applications. The CLI handles project creation, content / forms / media / labels / locale workflows, deploys, collaboration, account management, Fimo agents, AI credit inspection, and AI agent setup.
 
 This skill describes **what the CLI does and the workflows it drives**. For the package surface used IN code (component props, generated hooks, JSON shapes, code-side rules), load the `fimo-code` skill on demand with `npx fimo@latest skills get fimo-code`.
 
@@ -73,13 +73,13 @@ The working loop is local: run the app with the project's package-manager `dev`
 Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
 
 - "Create a new Fimo project / scaffold a site / start a new website / add the opt-in content starter / link an existing project locally" → `references/init.md`
-- "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ load `fimo-code/references/content.md` for the JSON shape and React hooks**
-- "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ load `fimo-code/references/forms.md` for the JSON spec and generated client**
+- "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ run `npx fimo@latest skills get fimo-code --ref content/schema` and load the detected framework reference**
+- "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec and generated client**
 - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
-- "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ load `fimo-code/references/assets.md` for the `FimoMedia` shape and rendering**
-- "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ load `fimo-code/references/assets.md` for the `FimoMedia` shape if you'll plug the result into UI**
-- "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ load `fimo-code/references/labels.md` for the `t()` helper and wrap rules**
-- "Enable locales / configure default locale / route by locale prefix / fix locale route validation" → `references/locales.md` **+ load `fimo-code/references/locales.md` for code helpers**
+- "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ run `npx fimo@latest skills get fimo-code --ref assets` for the `FimoMedia` shape and rendering**
+- "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ run `npx fimo@latest skills get fimo-code --ref assets` for the `FimoMedia` shape if you'll plug the result into UI**
+- "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference**
+- "Enable locales / configure default locale / integrate an existing locale system" → `references/locales.md` **+ run `npx fimo@latest skills get fimo-code --ref locales` and load the detected framework locale reference**
 - "What's in this project / show the project structure / describe the project / what schemas does it have / how many routes / project tree / show me what's here" → `references/describe.md`
 - "Deploy / publish / go live / push my changes" → `references/deploy.md`
 - "Get the preview URL / open the preview / what's the URL for this env / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.md`
@@ -111,7 +111,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 
 These fire at specific moments in the project lifecycle. **Surface them proactively** rather than waiting for the user to ask:
 
-- **Right after `fimo init`** → `cd` into the new directory, then `Read` the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code) to load the project context, and run `npx fimo@latest skills get fimo-code` to load the code skill before generating any code. The `AGENTS.md`/`CLAUDE.md` came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
+- **Right after `fimo init`** → `cd` into the new directory, read the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code), run `fimo describe --json`, then load `fimo-code` and only the task/framework references it routes to. The rules file came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
 - **Right after `fimo init`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-init name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/init.md`.
 - **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background, then ask the developer what they want to build. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes.
 - **When a user-visible unit of work looks done** → **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy on your own. See `references/deploy.md`.

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

@@ -11,7 +11,7 @@ The rich skills (`fimo-code`, `fimo-cli`, `fimo-studio`, `fimo-migration`) are *
 
 ```bash
 npx fimo@latest skills list            # what's available
-npx fimo@latest skills get fimo-code   # writing code: schemas, forms, labels, fimo/ui
+npx fimo@latest skills get fimo-code   # writing code: schemas, generated clients, labels, framework adapters
 npx fimo@latest skills get fimo-cli    # CLI + workflows (this skill)
 npx fimo@latest skills get fimo-cli --ref deploy   # a reference doc
 ```

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

@@ -2,7 +2,7 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-> Package contract: run `npx fimo@latest skills get fimo-code --ref assets` for `FimoMedia`, and `--ref ui` for component integration.
+> Package contract: run `npx fimo@latest skills get fimo-code --ref assets` for `FimoMedia`, `--ref ui` for rendering primitives, and load the detected framework reference for framework-specific integration.
 > For **generating** new images / videos with AI, see **`references/media.md`** for the task commands and recipes.
 
 This file covers the **CLI workflow** for media that already exists: uploading files, browsing the library, opening an asset to inspect it, moving / deleting items.
@@ -129,4 +129,4 @@ fimo assets delete <asset-id>
 
 1. Upload with `fimo assets upload` 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 JSX, load the `fimo-code` UI reference — schema media → `<Image>` / `<Video>`, hardcoded URLs → `<StaticImage>`. **Never** use raw `<img src={asset.url}>`.
+3. To use in application code, run `npx fimo@latest 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/content.md

@@ -2,19 +2,19 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-> Package contract: run `npx fimo@latest skills get fimo-code --ref content` for the JSON shape, field types, Tiptap nodes, slug rules, and generated React Query hooks.
+> Package contract: load the version-locked `fimo-code` skill with `npx fimo@latest skills get fimo-code`, then fetch its nested content and detected-framework references for schema JSON, entry values, generated clients, and imports.
 
 This file covers the **CLI workflow** for content. Use it when the user wants to add a content type (blog, products, pages) or manage Singles and entries.
 
 ## Flow
 
-1. Write `src/schemas/{Uid}.json` — PascalCase filename (e.g. `BlogPost.json`). For the JSON shape and field types, load the `fimo-code` content reference.
-2. Run `fimo schemas push {Uid}`. It generates `src/schemas/{Uid}.types.ts` and `src/schemas/{Uid}.ts`, then registers the schema with Fimo. It does not run whole-project validation.
-3. App code imports the generated client from `@/schemas/{Uid}`, not from `.types.ts` directly. See the `fimo-code` content reference for the hook API.
+1. Write `src/schemas/{Uid}.json` — PascalCase filename (e.g. `BlogPost.json`). Run `npx fimo@latest skills get fimo-code --ref content/schema` for the JSON contract.
+2. Run `fimo schemas push {Uid}`. It registers the schema and generates the framework-specific public modules. It does not run whole-project validation.
+3. App code imports generated public modules, never `.types.ts` directly. Load the detected framework reference before choosing server modules, client modules, hooks, or a registry.
 4. Seed collections via `fimo entries create`, or update one-off content via `fimo singles update`. Generate cover images first with `fimo image generate` if needed (see `media.md` / `assets.md`).
-5. Write React pages that import from `@/schemas/{Uid}` and render with `fimo/ui` components.
+5. Render tracked fields with the detected framework's Fimo primitives.
 
-Steps 1, 3, and 5 reference the `fimo-code` skill (`npx fimo@latest skills get fimo-code`) for shape and React API. Steps 2 and 4 are CLI commands documented here.
+Steps 1, 3, and 5 use `fimo-code`; steps 2 and 4 are CLI workflows documented here.
 
 ## Schema CLI commands
 
@@ -34,9 +34,9 @@ The command is `fimo schemas` (plural). There is no singular `fimo schema` alias
 
 All commands accept `-C, --cwd <dir>` to point at a different project directory.
 
-Blocks schemas support at most 7 nested `blocks` levels, 40 variants in one `schema.oneOf`, and `min` or `max` values up to 200 items per blocks field. Load the `fimo-code` content reference for the complete blocks JSON shape.
+Blocks schemas support at most 7 nested `blocks` levels, 40 variants in one `schema.oneOf`, and `min` or `max` values up to 200 items per blocks field. Run `npx fimo@latest skills get fimo-code --ref content/schema` for the complete blocks JSON shape.
 
-Schema transitions are automatic. Adding optional fields and changing labels preserve content. A new required field backfills its `default` only where existing values need it; the push fails safely when no default can satisfy existing content. Removing a nested field or block variant removes only those values. `string` and `text` preserve values in both directions. Other primitive changes convert safe values and reject unsafe ones without changing the schema or entries. Lowering block `max` trims from the end; raising `min` fills from the blocks `default` templates. A reference target change clears its connections. Use repeatable `--rename old.path=new.path` arguments when a field moved by name so the one-time migration preserves its values; the operation is not stored in schema JSON. Collection-to-Single removes that type's entries and cleans inbound references; Single-to-collection preserves its entry. Run `fimo validate` after pushing.
+Schema transitions are automatic. Adding optional fields and changing labels preserve content. A new required field backfills its `default` only where existing values need it; the push fails safely when no default can satisfy existing content. Removing a nested field or block variant removes only those values. `string` and `text` preserve values in both directions. Other primitive changes convert safe values and reject unsafe ones without changing the schema or entries. Lowering block `max` trims from the end; raising `min` fills from the blocks `default` templates. A reference target change clears its connections. Use repeatable `--rename old.path=new.path` arguments when a field moved by name so the one-time migration preserves its values; the operation is not stored in schema JSON. Collection-to-Single removes that type's entries and cleans inbound references; Single-to-collection preserves its entry.
 
 ## Singles CLI commands
 
@@ -76,7 +76,7 @@ fimo entries bulk-update <TypeName> (--file <path> | --stdin)
 fimo entries bulk-delete <TypeName> (--ids <id1>,<id2> | --where '<json>') [--locale es]
 ```
 
-`--body` is a **required** option on `create` and `update`. Its JSON shape (where `slug` goes, how `media` fields look, Tiptap richtext format) lives in the `fimo-code` content reference. **Always read that first before constructing an entry payload — slug must be inside `data`, media has a specific shape, richtext must be Tiptap JSONContent.**
+`--body` is a **required** option on `create` and `update`. Run `npx fimo@latest skills get fimo-code --ref content/richtext` before constructing an entry payload: slug belongs inside `data`, media has a specific shape, and richtext must be Tiptap JSONContent.
 
 `entries list` accepts the same read query surface as generated hooks:
 
@@ -100,7 +100,7 @@ Reference filters take the target `id` string (`{"author":"750e..."}`). On a to-
 
 Polymorphic references declare `targets: ["Post", "Product"]` instead of `target` (never both) and their values carry both parts: `{ "contentType": "Post", "id": "..." }`. Populate returns mixed full entries, and generated hooks expose `$type` on each populated value to branch on. `--where` on polymorphic fields is not supported yet and fails with a clear error.
 
-In generated React code, the equivalent is `populate: ['author', 'contributors'] as const` in the schema hook/query params. Let hooks infer the result when possible; if a named TypeScript shape is needed, use the generated `BlogPostResult<TFields, TPopulate>` type documented in the `fimo-code` content reference. Writes use the separate generated `BlogPostInput` type.
+In generated application code, the equivalent is `populate: ['author', 'contributors'] as const` in query params. Let the generated client infer the result when possible; if a named TypeScript shape is needed, use `BlogPostResult<TFields, TPopulate>` as documented by `npx fimo@latest skills get fimo-code --ref content/clients`. Writes use `BlogPostInput`.
 
 ### Read-only SQL
 
@@ -191,7 +191,7 @@ fimo entries bulk-delete BlogPost --where '{"archived":true}'
 
 Each bulk request handles at most 1,000 entries. Missing requested IDs do not fail valid work: the CLI prints a warning, and `--json` includes both a top-level `warnings` array and the exact IDs in `data.meta.missing`. Bulk writes use the same validation, locale, reference, and content-change paths as singular entry writes. They apply entries one at a time. Recoverable create and update errors report how many earlier entries were already changed.
 
-For reference schema JSON and entry value shape, load the `fimo-code` content reference § Reference fields. The short version:
+For reference schema JSON and entry value shape, run `npx fimo@latest skills get fimo-code --ref content/schema`. The short version:
 
 ```json
 {
@@ -253,32 +253,18 @@ Rules:
 
 Turning an existing field shared is destructive when the languages currently hold different values. The push collapses each document to its default-locale value and discards the others; there is no prompt and no undo. Most documents already agree, so most collapses change nothing — but tell the user what will happen before adding `"i18n": false` to a field that already holds content, and check whether the languages differ if you are unsure.
 
-Use `"isSingleton": true` for a Single with exactly one set of content. Generated Single clients expose `get`/`update` and their React Query hooks, not collection create/remove APIs.
+Use `"isSingleton": true` for a Single with exactly one set of content. Generated Single clients expose `get`/`update` and client hooks where the framework supports them, not collection create/remove APIs.
 
 ## "Add a blog" recipe
 
-1. Load the `fimo-code` content reference for the JSON shape and field types.
+1. Run `npx fimo@latest skills get fimo-code --ref content/schema` for the JSON shape and field types.
 2. Write `src/schemas/BlogPost.json` with fields `title`, `body` (richtext), `coverImage` (media), etc. Do NOT declare a `slug` field — `slug` (and `id`, `entryId`, `documentId`, `locale`, `createdAt`, `updatedAt`, `__fimo`) is reserved entry metadata and will be rejected; every entry gets a `slug` for free.
 3. Run `fimo schemas push BlogPost`.
 4. Generate cover images: `fimo image generate --prompt "..." --aspect-ratio 16:9` (see `media.md`).
 5. Seed entries: `fimo entries create BlogPost --body '{"data": {"slug": "first-post", "title": "...", "coverImage": {...}}}'`.
-6. Load the `fimo-code` UI reference for the `<Text>`, `<Image>`, `<RichText>` components.
-7. Load the `fimo-code` labels reference for wrapping labels in `t()`.
-8. Write the React page using the generated `useGet()` hook from `@/schemas/BlogPost`.
-
-## When to run sync manually
-
-`fimo schemas push`, `fimo validate`, and the `fimo/vite` development watcher all reuse the same schema generator. Production builds do not rewrite generated source files. `schemas push` does not run route, label, agent, form, or project-wide checks. For a full local validation and codegen pass without updating the remote schema, use:
-
-```bash
-fimo validate                  # runs all phases: codegen, lint, route validation, label checks
-```
-
-Advanced/internal (hidden from `fimo --help`) — for the bare regen phase:
-
-```bash
-fimo scripts sync-schemas      # regenerate src/schemas/*.types.ts and src/schemas/*.ts
-```
+6. Run `npx fimo@latest skills get fimo-code --ref ui` and load the detected framework reference for rendering primitives.
+7. Run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference for labels.
+8. Load the detected framework reference, then build the page with its generated server or client surface.
 
 ## Non-interactive use
 

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

@@ -77,5 +77,5 @@ The scoped view still emits the project-level metadata header (name, framework,
 ## Notes for AI tools
 
 - The JSON shape is stable; parse it rather than scraping the human output when you need a specific field.
-- The `framework` field is detected from `package.json#dependencies` (v1 detector). For multi-framework projects or unusual setups, the field may be `null` — fall back to reading `package.json` yourself.
+- The `framework` field uses Fimo's shared Vercel filesystem detector, which considers package dependencies, configuration files, and framework-specific file layout. For unusual or deliberately mixed projects it may be `null`; inspect `package.json` and the application tree before choosing a framework reference.
 - The command runs in any directory that contains `.fimo/project.json` or one of its ancestors. If you're not in a Fimo project, `describe` will run against whatever directory you point it at (it doesn't require Fimo credentials).

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

@@ -2,16 +2,16 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-> Package contract: run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec, generated Zod schema, submit helper, and React usage.
+> Package contract: run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec, generated Zod schema, submit helper, and application usage.
 
 This file covers the **CLI workflow** for forms. Use it when the user wants to add a contact form, signup, feedback form, etc.
 
 ## Flow
 
-1. Write `src/forms/{name}.json` — kebab-case filename (e.g. `contact-us.json`). For the JSON spec and field types, load the `fimo-code` forms reference.
+1. Write `src/forms/{name}.json` — kebab-case filename (e.g. `contact-us.json`). For the JSON spec and field types, run `npx fimo@latest skills get fimo-code --ref forms`.
 2. Register with `fimo forms push {name}` — creates the form, obtains its `id`, patches it back into the JSON file.
-3. Pre-build generates `src/forms/{name}.ts` (Zod schema + `submitX` helper). See the `fimo-code` forms reference for the generated API.
-4. Write a React component that imports from `@/forms/{name}`.
+3. Pre-build generates `src/forms/{name}.ts` (Zod schema + `submitX` helper). Use the same `fimo-code` reference for the generated API.
+4. Write the application form using the generated `@/forms/{name}` module and the existing framework conventions.
 
 Steps 1, 3, and 4 reference the `fimo-code` skill (`npx fimo@latest skills get fimo-code`). Step 2 is the CLI command.
 
@@ -45,12 +45,12 @@ Use this when the user asks "who filled out the contact form?", "how many signup
 
 ## "Add a contact form" recipe
 
-1. Load the `fimo-code` forms reference for the JSON spec.
+1. Run `npx fimo@latest skills get fimo-code --ref forms` for the JSON spec.
 2. Write `src/forms/contact-us.json` with the required fields.
 3. Run `fimo forms push contact-us` — the `id` is patched back into the JSON automatically.
-4. Load the `fimo-code` forms reference for the generated `submitContactUs` + `ContactUsSchema` API.
-5. Load the `fimo-code` labels reference for wrapping form labels in `t()`.
-6. Write the React form component that imports from `@/forms/contact-us`.
+4. Use the same `fimo-code` forms reference for the generated `submitContactUs` + `ContactUsSchema` API.
+5. Run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference for form labels.
+6. Write the application form using the generated `@/forms/contact-us` module.
 
 **Register BEFORE writing app code that depends on the form** — otherwise the generated `.ts` doesn't exist and the runtime fetch 404s.
 

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

@@ -74,7 +74,7 @@ Pass `--project-id <id>` to link an EXISTING project instead of creating one. Th
 - `.fimo/project.json` — links this directory to the remote project (read-only after creation)
 - `.fimo/config.json` — project, route, locale, SEO, and agent policy
 - `.fimo/agents/` — versioned agent bundles
-- `.env` — initial env vars (currently just `VITE_API_URL`)
+- `.env` — tenant content API URLs for Vite and Next runtimes
 - `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
 
@@ -119,10 +119,11 @@ After `fimo init` completes, the project root has `AGENTS.md` (universal) and `C
 
 1. `cd <project-dir>` — switch into the new project.
 2. `Read` the project rules file: `AGENTS.md` (or `CLAUDE.md` if you're Claude Code).
-3. Load the code skill on demand: `npx fimo@latest skills get fimo-code`.
-4. Load only the `fimo-code` references needed for the first task, using `npx fimo@latest skills get fimo-code --ref <doc>`.
+3. Run `npx fimo@latest describe --json` and read the detected framework, schemas, locales, and tree.
+4. Load the code skill on demand: `npx fimo@latest skills get fimo-code`.
+5. Follow its decision tree and load only the task reference plus the detected framework reference. For Next.js, start with `npx fimo@latest skills get fimo-code --ref frameworks/next`, then load App Router, Pages Router, or locales only when the project shape requires it.
 
-Once those are in context, generation respects the project's conventions (schemas, `t()`, `fimo/ui` components, asset handling).
+Do not batch-load every reference. Progressive disclosure keeps unrelated framework and product guidance out of the coding context.
 
 ## Adding another AI tool to an existing project later
 

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

@@ -2,14 +2,14 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-> Package contract: run `npx fimo@latest skills get fimo-code --ref labels` for `t()`, `useLabels()`, key naming, and wrapping rules.
+> Package contract: run `npx fimo@latest skills get fimo-code --ref labels` for the `t()` contract and key rules, then load the detected framework reference for its label readers.
 > For locale configuration and route-prefix validation, see **`references/locales.md`**.
 
 This file covers the **CLI workflow** for labels: static UI copy such as nav items, buttons, headings, placeholders, alt text, and SEO strings.
 
 ## What validate does
 
-`fimo validate` scans `src/**/*.{ts,tsx,js,jsx}` for `t('literal-key')` calls (skipping `src/ui` and `node_modules`) and verifies every key has a value in the tenant DB for the default locale.
+`fimo validate` scans `src/**/*.{ts,tsx,js,jsx}` for literal `t('key')` calls, including server readers such as `labels.t('key')` (skipping `src/ui` and `node_modules`), and verifies every key has a value in the tenant DB for the default locale.
 
 The database is the source of truth for visible label values. Code declares keys; it does not create visible copy.
 
@@ -61,9 +61,9 @@ Prefer `fimo validate` — this primitive is for narrow debugging/test use.
 
 ## Workflow
 
-1. Write JSX with `t('key')` calls. Load the `fimo-code` labels reference for the rules.
+1. Write code with literal `t('key')` calls. Run `npx fimo@latest skills get fimo-code --ref labels` and load the detected framework reference.
 2. Run `fimo validate`.
 3. Add missing values with `fimo labels set` or `fimo labels set-many`.
 4. Editors can now change copy in the Fimo admin without code changes.
 
-For the helper signatures, hooks, and code patterns, **always** load the `fimo-code` labels reference before writing code that uses `t()`.
+For helper signatures and code patterns, run `npx fimo@latest skills get fimo-code --ref labels` before writing code that uses `t()`.

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

@@ -2,7 +2,7 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-This file covers CLI-side locale configuration and validation. For code helpers such as `fimoRoutes()` and `FimoLink`, run `npx fimo@latest skills get fimo-code --ref locales`.
+This file covers CLI-side locale configuration and validation. For code integration, run `npx fimo@latest skills get fimo-code --ref locales` plus the detected framework's locale reference.
 
 ## Configure Locales
 
@@ -65,13 +65,13 @@ Do not add `/es/pricing` as a second Fimo route. The route selector localizes ca
 import { fimoRoutes } from 'fimo/react-router/routes';
 ```
 
-For custom frameworks, the project may implement its own URL scheme, but it still needs to pass the active locale into Fimo and keep canonical route metadata if it wants Fimo Studio route selection to work.
+For every framework, the application owns its URL scheme and passes the resolved locale into Fimo. Canonical route metadata is optional unless the project wants Fimo Studio route selection/navigation.
 
 ## Migrate An Existing Locale System
 
 Inspect the existing locale provider, route table, switcher, redirects, and public URLs before editing configuration. Preserve working URL behavior during the migration.
 
-For React Router projects, prefer one contract based on `.fimo/config.json`, `fimoRoutes()`, and `FimoLink`; migrate existing wrappers into the framework root instead of layering a second locale context. If that would change established URLs, keep the custom router temporarily, pass its active locale to `FimoProviders`, and ask the user to choose canonical URLs and redirects before rewriting routes.
+Preserve the existing locale provider, router, switcher, redirects, and public URLs. Use framework helpers only when they fit that architecture. Next.js projects run `npx fimo@latest skills get fimo-code --ref frameworks/next/locales`; React Router projects load the React Router setup reference.
 
 ## Labels And Content
 

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

@@ -45,7 +45,7 @@ Secrets are not written to `.env.local`, preview app env files, browser bundles,
 
 ## Local Env Files
 
-`fimo init` writes `.env` for bootstrap app runtime values such as `VITE_API_URL`. This lets `pnpm dev` work without a Fimo wrapper.
+`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 vars add`, `fimo vars update`, and `fimo vars pull` write public project variables to a managed block in `.env.local`.
 

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

@@ -1,67 +1,57 @@
 ---
 name: fimo-code
 description: >-
-  How to write code in a Fimo project — the npm package surface. Load when
-  writing JSX that renders schema content, defining schemas or forms (JSON),
-  using `t()` for labels, plugging media into `fimo/ui` components,
-  or applying the project's code conventions. CLI commands and workflows
-  (push, deploy, sync, etc.) live in the `fimo-cli` skill.
+  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
+  commands and operational workflows live in the `fimo-cli` skill.
 ---
 
-# Fimo
+# Fimo code
 
-You are writing code in a Fimo project — a content + media + forms + analytics platform for React websites with a CMS dashboard. This skill describes the **`fimo` npm package surface** as installed in this specific project: what's exported from `fimo`, `fimo/ui`, `fimo/vite`; the JSON shapes you write; the generated React Query hooks and Zod schemas you import; and the code conventions for using them.
+Use this skill for code that consumes the version-locked `fimo` package in the current project. Fimo connects content, labels, media, forms, editing metadata, and hosting to an application; the application continues to own routing, locale resolution, links, document language/direction, and SEO.
 
-This skill is version-locked to this project's installed `fimo` package — the shapes here match what your code can actually use.
+Use the project-installed CLI for local inspection, code generation, and validation (`pnpm exec fimo`, `npm exec fimo`, `yarn fimo`, or `bunx --no-install fimo`, matching the lockfile). If that runner tries to install packages even though dependencies already exist, invoke the local `node_modules/.bin/fimo` executable instead. Load the `fimo-cli` skill for remote operational workflows such as schema pushes, label writes, entry mutations, and deploys. If the skill is not already available locally, fetch it with `npx fimo@latest skills get fimo-cli`.
 
-For CLI commands and workflows (creating a project, pushing schemas/forms, deploying, managing labels, etc.), the **`fimo-cli`** skill is the source of truth. Run every CLI command as `npx fimo@latest <command>` (always the latest, no global install). Load it on demand with `npx fimo@latest skills get fimo-cli`.
+## Orient before writing
 
-## Critical: NEVER hardcode user-facing things
+1. Run the project-installed `fimo describe --json` in a linked project and read `data.framework.slug`, schemas, locales, and tree. If the project is not linked yet, inspect `package.json` and the app directory instead.
+2. Load only the references required by the task.
+3. Load the framework reference before choosing imports, providers, or rendering APIs.
 
-This is the load-bearing rule for every code change. **Fimo's whole point is that content editors edit content in the dashboard, not in code.** Anything hardcoded breaks that.
+Framework routing:
 
-- **Content** (posts, products, pages, lists, anything structured) → declare a schema, render collections with generated `useList()` or `useInfiniteList()` hooks + `fimo/ui` components. Use `useGet()` only for legacy fixed array queries. **Never** write `const posts = [...]` in JSX.
-- **Strings** (labels, CTAs, headings, descriptions, any visible text) → wrap in `t('key')` and create the default-locale value with `fimo labels set`. Use `--locale <locale>` only when intentionally writing a non-default locale. **Never** write `<h1>Welcome</h1>` directly — write `<Text value={t('home.title')} as="h1" />`.
-- **Media** (images, videos, files) → use `<Image>` / `<Video>` from `fimo/ui` for schema media, `<StaticImage>` for hard-coded URLs. **Never** use `<img src={...}>`.
-- **Forms** → use the generated Zod schema + `submitX` helper from `@/forms/<name>`. Never hand-roll fetch or validation.
+- `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`.
 
-If you find yourself about to hardcode anything user-facing, **stop and use the appropriate Fimo primitive instead.** For pushing the schema/form/asset to the backend, that's CLI territory — see the `fimo-cli` skill.
+## Durable content contract
+
+- Declare editor-managed content in `src/schemas/<Uid>.json`; the PascalCase filename must match `uid`.
+- Apply every schema change with `fimo schemas push <Uid>`; it validates the JSON, generates framework-specific clients, and updates the linked environment.
+- Import generated public modules; never edit generated `.ts`, `.client.ts`, `.types.ts`, or `index.ts` files.
+- Render tracked values with the framework's Fimo primitives so Studio can identify and edit their source.
+- Keep migration-only adapters (`Wrapped*`, private loaders, fallback stores) out of greenfield application code.
 
 ## Load only the references the task needs
 
 Each reference defines one package contract. Fetch it when the task reaches that surface; do not batch-load unrelated references:
 
-- `references/content.md` — schema JSON shape, field types, Tiptap nodes, generated React Query hooks
-- `references/forms.md` — form JSON spec, generated Zod + `submitX` helper
-- `references/assets.md` — `FimoMedia` shape, how to render assets
-- `references/labels.md` — `t()` helper, `useLabels()`, wrap rules
-- `references/locales.md` — locale routing helpers, `FimoLink`, custom-framework contract
-- `references/ui.md` — `fimo/ui` components + JSX code conventions + app code rules
-
-Workflow / CLI-side concerns (pushing schemas, generating images, managing labels, deploying) live in the **`fimo-cli`** skill's matching references.
-
-## Decision Tree (specific tasks)
-
-- **Setting up Fimo in a new project** — pick the framework:
-  - React Router framework mode (new projects use React Router 8) → `references/setup-react-router.md`
-  - Plain Vite + React (or upgrading a legacy v3 project) → `references/setup-plain-vite.md`
-- Writing schema JSON / picking field types / Tiptap richtext → `references/content.md`
-- Writing form JSON / generated form client / form code → `references/forms.md`
-- Plugging media into a component / `FimoMedia` shape → `references/assets.md`
-- ANY user-facing string in code → `references/labels.md`
-- Locale-aware routes, links, or framework adapters → `references/locales.md`
-- ANY JSX rendering schema content or `t()` output → `references/ui.md`
-- Major visual / redesign / hero section / brand → `references/design.md`
-
-## Anti-Patterns
-
-- **Hardcoding content in JSX** — `<h1>My Blog</h1>` + an array of posts in code. Use schemas + entries + `t()`.
-- **Raw HTML for schema content** — `<img src={post.coverImage.url}>` instead of `<Image value={post.coverImage}>`. The `fimo/ui` components carry metadata for inline editing in the admin.
-- **Raw `<a href>` for internal navigation** — causes full page reloads. Use `<FimoLink>` for locale-aware internal links or React Router `<Link>` when intentionally bypassing locale helpers. Reserve `<a>` for external links.
-- **Pulling stock photos from external URLs** — editors can't manage them. Use a Fimo media task such as `fimo image generate`.
-- **Editing generated `.ts` files** under `src/schemas/` or `src/forms/` — regenerate them through `fimo validate` or the matching push command.
-- **Writing raw HTML in `richtext` fields** — must be Tiptap JSONContent.
-- **Calling `t()` with a dynamic first argument** — the key must be a string literal so the extractor finds it.
-- **Decorating the disposable starter** — `src/pages/Index.tsx` is throwaway scaffolding. On first real generation, replace it entirely.
-- **Skipping legal pages** — `Privacy.tsx` + `Terms.tsx` are required for public sites; the template ships them.
-- **Showing Fimo branding** in the generated site unless the user explicitly asks for it.
+- Schema JSON, field types, blocks, references, `showIf` → `references/content/schema.md`
+- Richtext/Tiptap, entry payloads, slugs → `references/content/richtext.md`
+- Generated clients: `list`, `getBySlug`, `useList`, `where`, `sort`, `fields`, `populate` → `references/content/clients.md`
+- 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`
+- Locale ownership and framework handoff → `references/locales.md`
+- Major visual work → `references/design.md`
+
+## Non-negotiable boundaries
+
+- Do not hardcode editor-owned collections, page content, labels, or media in JSX.
+- Do not hand-roll content API fetches when a generated client covers the read.
+- Do not hand-construct `FimoString`, `FimoMedia`, or other tracked values.
+- Do not replace an application's router, locale library, URL policy, or SEO integration merely to add Fimo.
+- Do not teach one framework's imports as universal package APIs.

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

@@ -2,7 +2,7 @@
 
 > For the CLI commands (`fimo assets upload`, `fimo image generate`, folder management) and the "when to generate AI images" workflow rules, see **`fimo-cli/references/assets.md`**.
 
-This file covers the **package surface** for working with assets in code: the `media` field value shape, how to render assets with `fimo/ui` components, the URL format.
+This file covers the package surface for working with assets in code: the `media` field value shape, rendering primitives, and URL format.
 
 ## `media` field value (stored/wire shape)
 
@@ -20,11 +20,11 @@ Asset values returned from `fimo assets upload` or Fimo media tasks, and stored
 - `url`: stable HTTPS URL, no auth required, safe to embed.
 - `alt`: optional alt text.
 
-In a generated schema hook this stored value is wrapped in a runtime `FimoMedia` object (from `fimo/ui`) that exposes `url`, `alt`, `name`, `mime`, and optional `width`/`height` — it does **not** carry the `source` key (that's tracked internally for inline editing). Pass the whole entry value to `<Image>` / `<Video>`; don't read `source` off it in app code.
+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
 
-Always use the `fimo/ui` primitives — never raw HTML:
+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.
 
 | Asset source                                        | Component             | Pass via                  |
 | --------------------------------------------------- | --------------------- | ------------------------- |
@@ -32,7 +32,7 @@ Always use the `fimo/ui` primitives — never raw HTML:
 | Hard-coded URL or generated asset referenced inline | `<StaticImage>`       | `src="https://..."`       |
 
 ```tsx
-import { Image, StaticImage, Video } from 'fimo/ui';
+import { Image, StaticImage, Video } from 'fimo/next';
 
 // from a schema entry:
 <Image value={post.coverImage} width={1200} height={630} fit="cover" />
@@ -41,6 +41,8 @@ import { Image, StaticImage, Video } from 'fimo/ui';
 <StaticImage src="https://assets.fimo.ai/<project>/<id>.jpg" alt="Hero" width={1200} height={630} />
 ```
 
+Fimo's `<Image>` is not Next's `next/image` component. Do not pass Next-only props such as `priority`, `fill`, `quality`, or `loader`; use only the props documented for the Fimo primitive. Preserve `next/image` for non-Fimo images when the application needs those Next-specific controls.
+
 **Provide `width` and `height` when known** so Fimo can optimize the asset and reserve layout space (prevents CLS).
 
 **Never hand-construct a `FimoMedia` object** to pass into `<Image>` — that bypasses inline-editing metadata. If you have a raw URL, use `<StaticImage>` instead.