fimo 0.7.0-experimental.3 → 0.7.0-experimental.4

package/README.md

@@ -49,8 +49,7 @@ Manage content, schemas, media, and labels from the CLI:
 ```bash
 fimo schemas push          # sync your content models
 fimo entries list          # browse content
-fimo assets upload <file>  # add existing media
-fimo image generate --prompt "..."  # create an image with AI
+fimo assets upload <file>  # add media (or `fimo assets generate` with AI)
 fimo labels list           # manage labels and localized copy
 ```
 
@@ -86,4 +85,4 @@ fimo domains add example.com
 
 ## Documentation
 
-Full documentation lives at **[fimo.ai/docs](https://fimo.ai/docs)**. Run `fimo --help` to see every command.
+Full documentation lives at **[docs.fimo.ai](https://docs.fimo.ai)**. Run `fimo --help` to see every command.

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

@@ -11,7 +11,7 @@
 // AUTO-GENERATED ⚠️ – do not edit by hand
 import { <% if (!model.isSingleton) { %>useInfiniteQuery, <% } %>useSuspenseQuery, useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
 <% if (!model.isSingleton) { -%>
-import type { InfiniteData, UseInfiniteQueryResult, UseQueryResult, UseSuspenseQueryResult } from "@tanstack/react-query";
+import type { InfiniteData, UseInfiniteQueryResult, UseQueryResult } from "@tanstack/react-query";
 <% } -%>
 import { FimoString, FimoMedia, FimoBoolean, FimoRichText, useLocale<% if (!model.isSingleton) { %>, parseCollectionResponse<% } %> } from "fimo/ui";
 // @ts-ignore - virtual module provided by Fimo's Vite plugin
@@ -37,21 +37,15 @@ export type { <%= model.pascal %>, <%= model.pascal %>Fields, <%= model.pascal %
  */
 export function wrapWithSource(entry: Record<string, any>): <%= model.pascal %> {
   const id = entry.id;
-  const entryId = entry.entryId;
-  const documentId = entry.documentId ?? id;
-  const locale = entry.locale ?? defaultLocale();
-  const sourcePrefix = `<%= model.pascal %>.id:${id}:${encodeURIComponent(locale)}`;
+  const sourcePrefix = `<%= model.pascal %>.${id}`;
   const entryFimo = entry.__fimo && typeof entry.__fimo === "object" ? entry.__fimo : {};
 
   return {
     id,
-    entryId,
-    documentId,
+    documentId: entry.documentId,
     slug: entry.slug != null ? new FimoString(entry.slug, `${sourcePrefix}.slug`) : entry.slug,
-<% if (!model.isSingleton || model.localized) { -%>
-    locale,
-<% } else { -%>
-    ...(entry.locale ? { locale } : {}),
+<% if (model.localized) { -%>
+    locale: entry.locale,
 <% } -%>
     createdAt: entry.createdAt,
     updatedAt: entry.updatedAt,
@@ -107,11 +101,11 @@ if (model.fields) {
         const wrapper = field.target === model.uid ? 'wrapWithSource' : `wrap${field.targetPascal}WithSource`;
         if (field.many) {
 -%>
-    <%= key %>: Array.isArray(entry.<%= key %>) ? entry.<%= key %>.map((value: any) => isPopulatedEntry(value) ? <%= wrapper %>(value) : value) : entry.<%= key %>,
+    <%= key %>: Array.isArray(entry.<%= key %>) ? entry.<%= key %>.map((value: any) => value != null && typeof value === "object" && typeof value.id === "string" ? <%= wrapper %>(value) : value) : entry.<%= key %>,
 <%
         } else {
 -%>
-    <%= key %>: isPopulatedEntry(entry.<%= key %>) ? <%= wrapper %>(entry.<%= key %>) : entry.<%= key %>,
+    <%= key %>: entry.<%= key %> != null && typeof entry.<%= key %> === "object" && typeof entry.<%= key %>.id === "string" ? <%= wrapper %>(entry.<%= key %>) : entry.<%= key %>,
 <%
         }
         break;
@@ -127,23 +121,6 @@ if (model.fields) {
   } as <%= model.pascal %>;
 }
 
-interface PopulatedEntryRecord extends Record<string, unknown> {
-  id: string;
-  __fimo: { contentType: string };
-}
-
-function isPopulatedEntry(value: unknown): value is PopulatedEntryRecord {
-  if (value == null || typeof value !== "object") {
-    return false;
-  }
-  const entry = value as Record<string, unknown>;
-  const fimo = entry.__fimo;
-  return typeof entry.id === "string"
-    && fimo != null
-    && typeof fimo === "object"
-    && typeof (fimo as Record<string, unknown>).contentType === "string";
-}
-
 <%
 const hasPolymorphicReferences = model.fields && Object.values(model.fields).some((field) => field.type === 'reference' && Array.isArray(field.targetRefs) && field.targetRefs.length > 0);
 if (hasPolymorphicReferences) {
@@ -155,9 +132,7 @@ if (hasPolymorphicReferences) {
  * (unpopulated) values pass through untouched.
  */
 function wrapPolymorphic(value: any, wrappers: Record<string, (entry: Record<string, any>) => any>): any {
-  if (!isPopulatedEntry(value)) {
-    return value;
-  }
+  if (value == null || typeof value !== "object" || typeof value.id !== "string") return value;
   const contentType = value.__fimo && typeof value.__fimo.contentType === "string" ? value.__fimo.contentType : null;
   const wrapper = contentType ? wrappers[contentType] : undefined;
   if (!wrapper) return value;
@@ -184,11 +159,6 @@ function useQueryLocale(locale?: string): string {
   return locale ?? activeLocale ?? defaultLocale();
 }
 
-function withMutationLocale<T extends object>(payload: T, activeLocale: string): T & { locale: string } {
-  const locale = (payload as { locale?: string }).locale;
-  return { ...payload, locale: locale ?? activeLocale };
-}
-
 const LOCALIZED_CONTENT = <%= model.localized ? 'true' : 'false' %>;
 const LOCALIZED_REFERENCE_FIELDS = new Set<string>(<%= JSON.stringify(model.localizedReferenceFields) %>);
 
@@ -202,12 +172,8 @@ function readLocale(
   ownerUsesLocale: boolean,
   fallbackLocale = defaultLocale()
 ): string | undefined {
-<% if (!model.isSingleton) { -%>
-  return options.locale ?? fallbackLocale;
-<% } else { -%>
   const populatesLocalizedTarget = populateFields(options.populate).some((field) => LOCALIZED_REFERENCE_FIELDS.has(field));
   return ownerUsesLocale || populatesLocalizedTarget ? options.locale ?? fallbackLocale : undefined;
-<% } -%>
 }
 
 function fimoHeaders(extra?: Record<string, string>): Record<string, string> {
@@ -236,7 +202,6 @@ function withReadOptions<TPopulate extends <%= model.pascal %>Populate | undefin
 function splitWritePayload(payload: Partial<<%= model.pascal %>Input>): Record<string, unknown> {
   const {
     id,
-    entryId,
     documentId,
     locale,
     createdAt,
@@ -288,7 +253,7 @@ export async function getById<TPopulate extends <%= model.pascal %>Populate | un
   id: string,
   options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}
 ): Promise<<%= model.pascal %>Result<undefined, TPopulate>> {
-  const res = await fetch(`${base}${withReadOptions(`/entries/<%= model.uid %>/${id}`, options)}`, { headers: fimoHeaders() });
+  const res = await fetch(`${base}${withReadOptions(`/entries/<%= model.uid %>/${id}`, options, false)}`, { headers: fimoHeaders() });
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
   return wrapWithSource(data.data) as <%= model.pascal %>Result<undefined, TPopulate>;
@@ -389,21 +354,18 @@ export async function create(payload: <%= model.pascal %>Input): Promise<<%= mod
 }
 
 export async function update(id: string, payload: Partial<<%= model.pascal %>Input>): Promise<<%= model.pascal %>> {
-  const write = splitWritePayload(payload) as { data: Record<string, unknown>; locale?: string };
-  const url = withReadOptions(`/entries/<%= model.uid %>/${id}`, { locale: write.locale });
-  const res = await fetch(`${base}${url}`, {
+  const res = await fetch(`${base}/entries/<%= model.uid %>/${id}`, {
     method: "PUT",
     headers: fimoHeaders({ "Content-Type": "application/json" }),
-    body: JSON.stringify({ data: write.data })
+    body: JSON.stringify(splitWritePayload(payload))
   });
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
   return wrapWithSource(data.data);
 }
 
-export async function remove(id: string, options: { locale?: string } = {}): Promise<void> {
-  const url = withReadOptions(`/entries/<%= model.uid %>/${id}`, options);
-  const res = await fetch(`${base}${url}`, { method: "DELETE", headers: fimoHeaders() });
+export async function remove(id: string): Promise<void> {
+  const res = await fetch(`${base}/entries/<%= model.uid %>/${id}`, { method: "DELETE", headers: fimoHeaders() });
   if (!res.ok) throw new Error(await res.text());
 }
 <% } else { -%>
@@ -437,7 +399,7 @@ export async function update(payload: Partial<<%= model.pascal %>Input>): Promis
 <% if (!model.isSingleton) { -%>
 const qk = {
   root       : ["<%= model.pascal %>"] as const,
-  byId       : <TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(id: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) => ["<%= model.pascal %>", "id", id, options.locale, options.populate] as const,
+  byId       : <TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(id: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) => ["<%= model.pascal %>", id, options.locale, options.populate] as const,
   bySlug     : <TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(slug: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) => ["<%= model.pascal %>", "slug", slug, options.locale, options.populate] as const,
   byField    : <TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(field: string, value: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) => ["<%= model.pascal %>", field, value, options.locale, options.populate] as const,
   list       : (params: <%= model.pascal %>Query) => ["<%= model.pascal %>", params] as const,
@@ -447,8 +409,8 @@ const qk = {
   >(params: InfiniteListQuery<TFields, TPopulate>) => ["<%= model.pascal %>", "infinite", params] as const
 };
 
-export function useGetById<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(id: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}): UseQueryResult<<%= model.pascal %>Result<undefined, TPopulate>, Error> {
-  const locale = useQueryLocale(options.locale);
+export function useGetById<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(id: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) {
+  const locale = readLocale(options, false, useQueryLocale(options.locale));
   const localizedOptions = { ...options, locale };
   return useQuery<<%= model.pascal %>Result<undefined, TPopulate>, Error>({ queryKey: qk.byId(id, localizedOptions), queryFn: () => getById(id, localizedOptions) });
 }
@@ -513,8 +475,8 @@ export function useInfiniteList<
   };
 }
 
-export function useSuspenseGetById<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(id: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}): UseSuspenseQueryResult<<%= model.pascal %>Result<undefined, TPopulate>, Error> {
-  const locale = useQueryLocale(options.locale);
+export function useSuspenseGetById<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(id: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) {
+  const locale = readLocale(options, false, useQueryLocale(options.locale));
   const localizedOptions = { ...options, locale };
   return useSuspenseQuery<<%= model.pascal %>Result<undefined, TPopulate>, Error>({ queryKey: qk.byId(id, localizedOptions), queryFn: () => getById(id, localizedOptions) });
 }
@@ -546,37 +508,30 @@ export function useSuspenseGet<
 
 export function useCreate() {
   const qc = useQueryClient();
-  const activeLocale = useQueryLocale();
   return useMutation<<%= model.pascal %>, Error, <%= model.pascal %>Input>({
-    mutationFn   : (payload) => create(withMutationLocale(payload, activeLocale)),
+    mutationFn   : create,
     onSuccess    : () => qc.invalidateQueries({ queryKey: qk.root })
   });
 }
 
 export function useUpdate() {
   const qc = useQueryClient();
-  const activeLocale = useQueryLocale();
-  return useMutation<<%= model.pascal %>, Error, { id: string; locale?: string } & Partial<<%= model.pascal %>Input>>({
-    mutationFn   : ({ id, ...patch }) => update(id, withMutationLocale(patch, activeLocale)),
+  return useMutation<<%= model.pascal %>, Error, { id: string } & Partial<<%= model.pascal %>Input>>({
+    mutationFn   : ({ id, ...patch }) => update(id, patch),
     onSuccess    : (_data, vars) => {
       qc.invalidateQueries({ queryKey: qk.root });
-      qc.invalidateQueries({ queryKey: qk.byId(vars.id, { locale: vars.locale ?? activeLocale }) });
+      qc.invalidateQueries({ queryKey: qk.byId(vars.id) });
     }
   });
 }
 
 export function useRemove() {
   const qc = useQueryClient();
-  const activeLocale = useQueryLocale();
-  return useMutation<void, Error, string | { id: string; locale?: string }>({
-    mutationFn   : (value) => {
-      const { id, locale } = typeof value === "string" ? { id: value, locale: activeLocale } : { ...value, locale: value.locale ?? activeLocale };
-      return remove(id, { locale });
-    },
-    onSuccess    : (_data, value) => {
-      const { id, locale } = typeof value === "string" ? { id: value, locale: activeLocale } : { ...value, locale: value.locale ?? activeLocale };
+  return useMutation<void, Error, string>({
+    mutationFn   : remove,
+    onSuccess    : (_data, id) => {
       qc.invalidateQueries({ queryKey: qk.root });
-      qc.removeQueries({ queryKey: qk.byId(id, { locale }), exact: false });
+      qc.removeQueries({ queryKey: ["<%= model.pascal %>", id], exact: false });
     }
   });
 }
@@ -600,9 +555,8 @@ export function useSuspenseGet<TPopulate extends <%= model.pascal %>Populate | u
 
 export function useUpdate() {
   const qc = useQueryClient();
-  const activeLocale = useQueryLocale();
   return useMutation<<%= model.pascal %>, Error, Partial<<%= model.pascal %>Input>>({
-    mutationFn: (payload) => update(withMutationLocale(payload, activeLocale)),
+    mutationFn: update,
     onSuccess: () => qc.invalidateQueries({ queryKey: qk.root })
   });
 }

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

@@ -33,13 +33,10 @@ export interface <%= model.pascal %>FimoMeta {
 
 export interface <%= model.pascal %> extends WithReferences<<%= model.pascal %>References> {
   id: string;
-  entryId: string;
   documentId: string;
   slug: FimoString;
-<% if (!model.isSingleton || model.localized) { -%>
+<% if (model.localized) { -%>
   locale: string;
-<% } else { -%>
-  locale?: string;
 <% } -%>
   createdAt: string;
   updatedAt: string;

package/assets/skills/fimo/SKILL.md

@@ -14,7 +14,7 @@ You are writing code in a Fimo project — a content + media + forms + analytics
 
 This skill is version-locked to this project's installed `fimo` package — the shapes here match what your code can actually use.
 
-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). If `fimo-cli` isn't loaded for your AI tool, register it with `npx fimo@latest skills install --mode=copy`.
+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 <command>` when the project declares a `fimo` dependency (it pins the version matching the project's backend); otherwise use `npx fimo@latest`. If `fimo-cli` isn't loaded for your AI tool, register it with `npx fimo skills install --mode=copy`.
 
 ## Critical: NEVER hardcode user-facing things
 
@@ -43,7 +43,7 @@ Workflow / CLI-side concerns (pushing schemas, generating images, managing label
 ## 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`
+  - React Router 7 framework mode → `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`
@@ -58,7 +58,7 @@ Workflow / CLI-side concerns (pushing schemas, generating images, managing label
 - **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`.
+- **Pulling stock photos from external URLs** — editors can't manage them. Use `fimo generate` (CLI).
 - **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.

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

@@ -1,12 +1,12 @@
 # Assets — package surface
 
-> 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`**.
+> For the CLI commands (`fimo assets upload`, `fimo 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.
 
 ## `media` field value (stored/wire shape)
 
-Asset values returned from `fimo assets upload` or Fimo media tasks, and stored in `media` content-type fields:
+Asset values returned from `fimo assets upload` or `fimo generate`, and stored in `media` content-type fields:
 
 ```json
 {

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

@@ -34,9 +34,9 @@ Every entry already carries this metadata automatically. Declaring any of them a
 schema field is rejected by `fimo schemas push` with a 400 (e.g. `fields.slug: "slug" is
 reserved entry metadata and cannot be used as a content field.`):
 
-`id`, `entryId`, `documentId`, `slug`, `locale`, `createdAt`, `updatedAt`, `__fimo`.
+`id`, `documentId`, `slug`, `locale`, `createdAt`, `updatedAt`, `__fimo`.
 
-Collection entries expose the effective `locale`. It remains reserved for both localized and shared schemas.
+Localized entries expose `locale`; non-localized entries omit it. It remains reserved in both schemas.
 
 In particular **do not add a `slug` field** — every entry gets a `slug` for free. You still
 pass `slug` inside `data` when _creating an entry_ (see "Entry body shape" below); it just
@@ -45,16 +45,16 @@ something else (e.g. `handle`, `permalink`).
 
 ## Field types
 
-| Type        | `data` JSON shape                                                             | Use for                           |
-| ----------- | ----------------------------------------------------------------------------- | --------------------------------- |
-| `string`    | `"..."`                                                                       | Titles, short text                |
-| `richtext`  | Tiptap JSONContent (see below)                                                | Blog body, descriptions, articles |
-| `number`    | `42`                                                                          | Counts, quantities                |
-| `boolean`   | `true` / `false`                                                              | Flags                             |
-| `date`      | ISO date string, e.g. `"2026-06-03"`                                          | Publish dates, timestamps         |
-| `media`     | `{ "source": "local"\|"external", "url": "https://...", "alt": "..." }`       | Images, video                     |
-| `json`      | any JSON                                                                      | Structured metadata               |
-| `reference` | `{ "id": "..." }`, `null`, or an array of reference objects when `many: true` | References to another schema      |
+| Type        | `data` JSON shape                                                                     | Use for                           |
+| ----------- | ------------------------------------------------------------------------------------- | --------------------------------- |
+| `string`    | `"..."`                                                                               | Titles, short text                |
+| `richtext`  | Tiptap JSONContent (see below)                                                        | Blog body, descriptions, articles |
+| `number`    | `42`                                                                                  | Counts, quantities                |
+| `boolean`   | `true` / `false`                                                                      | Flags                             |
+| `date`      | ISO date string, e.g. `"2026-06-03"`                                                  | Publish dates, timestamps         |
+| `media`     | `{ "source": "local"\|"external", "url": "https://...", "alt": "..." }`               | Images, video                     |
+| `json`      | any JSON                                                                              | Structured metadata               |
+| `reference` | `{ "documentId": "..." }`, `null`, or an array of reference objects when `many: true` | References to another schema      |
 
 A `date` field currently generates as `any` in the TS client, so for typed access (and the `<Date>` component) prefer a `string` field holding an ISO date — which is what the `publishDate` examples below do.
 
@@ -79,7 +79,7 @@ Rules:
 - `target` is required and must be the PascalCase schema `uid` of the referenced content type.
 - Omit `many` for a to-one reference. Use `"many": true` for a to-many reference.
 - Self-references are allowed, e.g. a `Category` schema can have `parent: { "type": "reference", "target": "Category" }`.
-- Entry values use the target's stable `id`, never the variant `entryId`: `{ "id": "..." }`.
+- Entry values store reference objects with the target `documentId`, not row `id` values: `{ "documentId": "..." }`.
 - Do not include `contentType` for normal fixed-target references; the schema's `target` already defines it.
 - Do not add `localized` or field-level `i18n` to a reference. The reference value belongs to the entry variant that stores it.
 - Use `null` for an empty to-one reference and `[]` for an empty to-many reference.
@@ -92,22 +92,22 @@ Entry payload example:
   "data": {
     "slug": "reference-example",
     "title": "Reference example",
-    "author": { "id": "750e8400-e29b-41d4-a716-446655440000" },
-    "contributors": [{ "id": "750e8400-e29b-41d4-a716-446655440000" }]
+    "author": { "documentId": "750e8400-e29b-41d4-a716-446655440000" },
+    "contributors": [{ "documentId": "750e8400-e29b-41d4-a716-446655440000" }]
   }
 }
 ```
 
 ## Schema transitions
 
-After editing schema JSON, run `fimo schemas push {Uid}` and then `fimo validate`. Push regenerates the schema client and applies the schema change to existing content automatically:
+After editing schema JSON, run `fimo schemas push {Uid}` and then `fimo validate`. Push regenerates the schema client and applies the schema change to stored content automatically:
 
 - Adding fields and changing labels preserve entries.
 - Removing a field removes only that field's values.
 - A one-to-many reference change wraps each existing reference in an array.
 - A many-to-one change, reference target change, scalar type change, or scalar/reference change clears only the changed field.
 - Collection-to-singleton removes that type's entries and cleans references to those documents.
-- Singleton-to-collection preserves the existing entry.
+- Singleton-to-collection preserves the existing row.
 
 There are no reset or data-loss flags. Do not invent one or promise that incompatible field values survive; the schema change itself selects the behavior above.
 
@@ -176,7 +176,7 @@ Always provide a meaningful `slug` when creating an entry — it appears in URLs
 - **Stable** — once an entry is live, changing the slug breaks inbound links. Only update intentionally.
 - If you omit `slug`, the backend generates a random one — never rely on this for content you want to link to.
 
-For `media` fields, prefer `source: "local"` with assets uploaded via `fimo assets upload` or generated with a Fimo media task such as `fimo image generate` (see `fimo-cli/references/media.md`).
+For `media` fields, prefer `source: "local"` with assets uploaded via `fimo assets upload` or generated via `fimo generate` (see `fimo-cli/assets.md`).
 
 ## Generated React Query hooks
 
@@ -192,10 +192,9 @@ Import from the public schema module, e.g. `import BlogPost from '@/schemas/Blog
 ```ts
 interface BlogPost {
   id: string;
-  entryId: string;
   documentId: string;
   slug: FimoString;
-  locale: string;
+  locale: string; // localized schemas only; omitted when i18n.enabled is false
   createdAt: string;
   updatedAt: string;
   __fimo: {
@@ -214,14 +213,13 @@ Content fields live at the top level. Fimo-owned metadata that is not part of th
 
 ## Localized and shared content
 
-Localized content has one variant per locale. Generated hooks read the active Fimo locale automatically.
+Localized content is stored per locale. Generated hooks read the active Fimo locale automatically.
 
 When a project has multiple configured locales, create and update each localized content variant explicitly. Use the default locale first, then create non-default variants with the same `documentId` and the target `locale` through the content tools or `fimo entries` commands.
 
 For shared content, set `i18n: { "enabled": false }` on the schema and create each entry once. Shared entries:
 
-- send and expose the effective active/default locale in generated collection queries and models;
-- omit `locale` from raw API responses because there is no localized variant;
+- have no public `locale` property;
 - are returned in every locale context without duplication;
 - ignore locale on owner reads and writes;
 - still use the active/requested locale when a populated reference targets a localized schema.
@@ -230,7 +228,7 @@ Do not duplicate shared entries across locales or add field-level localization s
 
 A populated reference whose target has no variant in the requested locale resolves to null. Reads accept an opt-in `localeFallbacks: true` that resolves those to the best available variant instead (project default first), marked by its `locale` field — never implement fallbacks by hand; public reads stay strict unless the option is passed.
 
-**Polymorphic references:** a field may declare `targets: ["Post", "Video"]` instead of a single `target` (never both) when one slot genuinely holds different types — mixed feeds, hero blocks, curated collections. Prefer a fixed `target` whenever every value is the same type: fixed fields keep `where` filtering and simpler generated types. Polymorphic values use `{ contentType, id }`; populated values in generated hooks carry a top-level `$type` that narrows the union:
+**Polymorphic references:** a field may declare `targets: ["Post", "Video"]` instead of a single `target` (never both) when one slot genuinely holds different types — mixed feeds, hero blocks, curated collections. Prefer a fixed `target` whenever every value is the same type: fixed fields keep `where` filtering and simpler generated types. Polymorphic values store `{ contentType, documentId }`; populated values in generated hooks carry a top-level `$type` that narrows the union:
 
 ```ts
 for (const item of page.featured) {
@@ -247,21 +245,19 @@ Filtering on polymorphic fields is not supported yet.
 
 **Generated API:**
 
-Collection responses use `id` as the stable identity shared by all locale variants. `locale` selects the variant, and generated hooks use the active Fimo locale when it is omitted. `entryId` identifies the exact variant returned by Fimo and is only for diagnostics or migrations. `documentId` remains a compatibility alias for `id`; reference inputs use `{ id: entry.id }`. Filters and sorts follow the same rule: `where.id` and `sort: "id"` use stable identity, while `entryId` addresses an exact variant.
-
 ```ts
 // low-level fetch helpers
-getById<TPopulate extends BlogPostPopulate | undefined>(id: string, options?: { locale?: string; populate?: TPopulate }): Promise<BlogPostResult<undefined, TPopulate>>
+getById<TPopulate extends BlogPostPopulate | undefined>(id: string, options?: { populate?: TPopulate }): Promise<BlogPostResult<undefined, TPopulate>>
 getBySlug<TPopulate extends BlogPostPopulate | undefined>(slug: string, options?: { populate?: TPopulate }): Promise<BlogPostResult<undefined, TPopulate> | null>
 getByField<TPopulate extends BlogPostPopulate | undefined>(fieldName: string, value: string, options?: { populate?: TPopulate }): Promise<BlogPostResult<undefined, TPopulate> | null>
 list<TFields extends BlogPostFields | undefined, TPopulate extends BlogPostPopulate | undefined>(params?: BlogPostQuery<TFields, TPopulate>): Promise<CollectionPage<BlogPostResult<TFields, TPopulate>>>
 get<TFields extends BlogPostFields | undefined, TPopulate extends BlogPostPopulate | undefined>(params?: BlogPostQuery<TFields, TPopulate>): Promise<BlogPostResult<TFields, TPopulate>[]>
 create(payload: BlogPostInput): Promise<BlogPost>
 update(id: string, payload: Partial<BlogPostInput>): Promise<BlogPost>
-remove(id: string, options?: { locale?: string }): Promise<void>
+remove(id: string): Promise<void>
 
 // react-query hooks
-useGetById(id, { locale?, populate? }) // → { data: BlogPostResult<undefined, TPopulate> | undefined, isLoading, ... }
+useGetById(id, { populate? })     // → { data: BlogPostResult<undefined, TPopulate> | undefined, isLoading, ... }
 useGetBySlug(slug, { populate? }) // → { data: BlogPostResult<undefined, TPopulate> | null | undefined, ... } — ideal for /:slug detail routes
 useGetByField(fieldName, value, { populate? })
 useList<TFields, TPopulate>(params?)         // → { data: CollectionPage<BlogPostResult<TFields, TPopulate>> | undefined, ... }
@@ -283,7 +279,7 @@ update(payload: Partial<SettingsInput>): Promise<Settings>
 useGet(options?) / useSuspenseGet(options?) / useUpdate()
 ```
 
-Singleton clients do not expose `create`, `remove`, `getById`, or list queries. Localized singletons have one variant per locale; shared singletons have one entry across locales.
+Singleton clients do not expose `create`, `remove`, `getById`, or list queries. Localized singletons have one variant per locale; non-localized singletons have one locale-free row.
 
 Choose the collection interface from the UI behavior. Use `useList` when the UI controls a page, and read pagination state from `pageInfo`:
 
@@ -339,10 +335,10 @@ BlogPost.useGet({
 ```
 
 Operators: scalar equality, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, `$null`.
-Reference field values are reference objects, but reference filters use the target `id` string, for example `where: { author: author.id }`; for to-many references that means "contains this target".
+Reference field values are reference objects, but reference filters use the target `documentId` string, for example `where: { author: "750e..." }`; for to-many references that means "contains this target document".
 For to-many references, `$eq` and `$contains` mean membership, `$in` means any listed document is present, `$ne` and `$nin` mean none are present, and `$null: true` means empty or missing. Reference fields cannot be sorted.
 
-Use `fields` to keep list payloads small. The API always keeps `id`, `entryId`, `documentId`, and `locale`, and returns only the requested fields beyond that:
+Use `fields` to keep list payloads small. The API always keeps `id`, and returns only the requested fields beyond that:
 
 ```tsx
 const { data: summaries = [] } = BlogPost.useGet({
@@ -350,7 +346,7 @@ const { data: summaries = [] } = BlogPost.useGet({
   sort: '-publishedAt',
   limit: 12,
 });
-// summaries: Array<Pick<BlogPost, 'id' | 'entryId' | 'documentId' | 'locale' | 'slug' | 'title' | 'excerpt' | 'coverImage'>>
+// summaries: Array<Pick<BlogPost, 'id' | 'slug' | 'title' | 'excerpt' | 'coverImage'>>
 ```
 
 Use `populate` to embed reference targets in read results:
@@ -360,7 +356,7 @@ const { data: posts = [] } = BlogPost.useGet({
   fields: ['slug', 'title', 'author'] as const,
   populate: ['author'] as const,
 });
-// Without populate: post.author is { id: "..." }.
+// Without populate: post.author is { documentId: "..." }.
 // With populate: post.author is the target Author entry object, or null.
 ```
 
@@ -388,16 +384,16 @@ Populate is depth-one. It only works for reference fields; trying to populate a
 
 The entry objects a hook returns are **not** plain JS values. The generated client wraps each _trackable_ field in a `fimo/ui` primitive that carries source metadata for inline editing. Which fields wrap, and which stay plain:
 
-| Schema field type | Field value you get                 | Notes                                                                                 |
-| ----------------- | ----------------------------------- | ------------------------------------------------------------------------------------- |
-| `string`          | `FimoString`                        | `extends String` — **not** a primitive `string`                                       |
-| `richtext`        | `FimoRichText`                      | Tiptap JSONContent + source metadata                                                  |
-| `boolean`         | `FimoBoolean`                       | class; `.valueOf()` → `boolean`                                                       |
-| `media`           | `FimoMedia` / `FimoMedia[]`         | shape + rendering in `references/assets.md`                                           |
-| `number`          | `number`                            | plain — not wrapped                                                                   |
-| `json`            | `Record<string, any>`               | plain — not wrapped                                                                   |
-| `date`            | `any` (raw ISO date string)         | not wrapped (`FimoDate` is not emitted — see below)                                   |
-| `reference`       | `FimoReference` / `FimoReference[]` | reference object(s) with target `id`; use `populate` when embedded targets are needed |
+| Schema field type | Field value you get                 | Notes                                                                                             |
+| ----------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `string`          | `FimoString`                        | `extends String` — **not** a primitive `string`                                                   |
+| `richtext`        | `FimoRichText`                      | Tiptap JSONContent + source metadata                                                              |
+| `boolean`         | `FimoBoolean`                       | class; `.valueOf()` → `boolean`                                                                   |
+| `media`           | `FimoMedia` / `FimoMedia[]`         | shape + rendering in `references/assets.md`                                                       |
+| `number`          | `number`                            | plain — not wrapped                                                                               |
+| `json`            | `Record<string, any>`               | plain — not wrapped                                                                               |
+| `date`            | `any` (raw ISO date string)         | not wrapped (`FimoDate` is not emitted — see below)                                               |
+| `reference`       | `FimoReference` / `FimoReference[]` | reference object(s) with target `documentId`; use `populate` when embedded target rows are needed |
 
 Rules of thumb:
 
@@ -438,7 +434,7 @@ export function BlogList() {
   return (
     <ul>
       {page.items.map((post) => (
-        <li key={`${post.id}:${post.locale}`}>
+        <li key={post.id}>
           <Text value={post.title} as="h2" />
           <Image value={post.coverImage} width={800} height={400} fit="cover" />
           <RichText value={post.body} className="prose" />
@@ -455,9 +451,9 @@ For the `<Text>` / `<RichText>` / `<Image>` / `<Date>` components and the rules
 ## Read path (published app, no auth)
 
 ```ts
-const res = await fetch(`${import.meta.env.VITE_API_URL}/entries/<typeName>?locale=en&fields=slug,title&limit=12`);
+const res = await fetch(`${import.meta.env.VITE_API_URL}/entries/<typeName>?fields=slug,title&limit=12`);
 const { data, meta } = await res.json();
-// data: Entry[] — fields flattened at top level (id, entryId, documentId, locale, slug, title, ...)
+// data: Entry[] — fields flattened at top level (id, slug, title, ...)
 // meta: { limit, offset, total, hasMore }
 ```
 

package/assets/skills/fimo/references/design.md

@@ -124,7 +124,7 @@ Write into `src/index.css` as shadcn CSS variables, then use `bg-background` / `
 - **Treatment:** Full-bleed, contained, overlays, filters
 - **Hero:** Specific direction for hero imagery
 
-If the user hasn't supplied images and one is needed, run `fimo image generate --prompt "..."` and reuse the returned `url` or `id`. Run `fimo image generate --help` for current flags. See `references/assets.md`.
+If the user hasn't supplied images and one is needed, generate via `fimo generate <model> --prompt "..."` (run `fimo models list` to pick a model, `fimo models show <model>` for its flags) and reuse the returned `url` / `id`. See `references/assets.md`.
 
 ### Iconography
 

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

@@ -67,14 +67,6 @@ This helper exists so the Fimo UI route selector, preview navigation, labels, an
 
 Copyable examples live in `assets/react-router-locales/routes.ts` and `assets/react-router-locales/navigation.tsx`.
 
-## Existing Custom Locale Systems
-
-Before changing a multilingual app, inspect its locale provider, route table, language switcher, redirects, and current public URLs. Preserve that behavior while migrating.
-
-For React Router projects, prefer converging on one locale contract owned by `fimo-config.json`, `fimoRoutes()`, and `FimoLink`. Move existing providers and language-switcher UI into the framework root instead of replacing them or adding a second locale context. Keep route metadata canonical and reuse page modules across locales.
-
-If adopting the standard helper would change established public URLs, do not silently rewrite them. Keep the custom router temporarily, pass its resolved locale to `<FimoProviders locale={locale}>`, and ask the user to choose the canonical URLs and redirects before normalizing the route table.
-
 ## Links
 
 Use `FimoLink` for internal links that should preserve or switch locale:

package/assets/skills/fimo/references/setup-react-router.md

@@ -1,4 +1,4 @@
-# Setup Fimo on React Router 8
+# Setup Fimo on React Router 7
 
 This recipe describes the canonical Fimo + React Router framework-mode setup.
 It mirrors what `fimo init` scaffolds today; you can also apply it to an
@@ -6,7 +6,7 @@ existing RR project.
 
 ## Prerequisites
 
-- Node 22.22+
+- Node 20+
 - A Fimo project created via `fimo init` (gives you `projectId`,
   `organizationId`, and an `apiUrl`).
 

package/assets/skills/fimo/references/ui.md

@@ -42,7 +42,7 @@ The template uses **Vite + React 19 + TypeScript + Tailwind v4 + shadcn/ui + rea
 
 ### Routing
 
-- This template uses React Router 8 framework mode (file-based route config in `src/routes.ts`). Use `<FimoLink>` from `fimo/react-router` for locale-aware internal links, especially in projects with more than one configured locale. Use React Router `<Link>` / `<NavLink>` only when you intentionally do not want Fimo's locale behavior. Never raw `<a href="/...">` for internal navigation because it causes full page reloads.
+- This template uses React Router v7 framework mode (file-based route config in `src/routes.ts`). Use `<FimoLink>` from `fimo/react-router` for locale-aware internal links, especially in projects with more than one configured locale. Use React Router `<Link>` / `<NavLink>` only when you intentionally do not want Fimo's locale behavior. Never raw `<a href="/...">` for internal navigation because it causes full page reloads.
 - Reserve `<a>` for external links, with `target="_blank" rel="noreferrer"`.
 
 ### Loading states

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

@@ -73,7 +73,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ load `fimo/references/forms.md` 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/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/references/assets.md` for the `FimoMedia` shape if you'll plug the result into UI**
+- "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (the `fimo generate <model>` surface — recipes, defaults, the one-verb shape) **+ load `fimo/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/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/references/locales.md` for code helpers**
 - "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`