fimo 0.6.0 → 0.7.0-experimental.1

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 } from "@tanstack/react-query";
+import type { InfiniteData, UseInfiniteQueryResult, UseQueryResult, UseSuspenseQueryResult } 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,15 +37,21 @@ export type { <%= model.pascal %>, <%= model.pascal %>Fields, <%= model.pascal %
  */
 export function wrapWithSource(entry: Record<string, any>): <%= model.pascal %> {
   const id = entry.id;
-  const sourcePrefix = `<%= model.pascal %>.${id}`;
+  const entryId = entry.entryId;
+  const documentId = entry.documentId ?? id;
+  const locale = entry.locale ?? defaultLocale();
+  const sourcePrefix = `<%= model.pascal %>.id:${id}:${encodeURIComponent(locale)}`;
   const entryFimo = entry.__fimo && typeof entry.__fimo === "object" ? entry.__fimo : {};
 
   return {
     id,
-    documentId: entry.documentId,
+    entryId,
+    documentId,
     slug: entry.slug != null ? new FimoString(entry.slug, `${sourcePrefix}.slug`) : entry.slug,
-<% if (model.localized) { -%>
-    locale: entry.locale,
+<% if (!model.isSingleton || model.localized) { -%>
+    locale,
+<% } else { -%>
+    ...(entry.locale ? { locale } : {}),
 <% } -%>
     createdAt: entry.createdAt,
     updatedAt: entry.updatedAt,
@@ -101,11 +107,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) => value != null && typeof value === "object" && typeof value.id === "string" ? <%= wrapper %>(value) : value) : entry.<%= key %>,
+    <%= key %>: Array.isArray(entry.<%= key %>) ? entry.<%= key %>.map((value: any) => isPopulatedEntry(value) ? <%= wrapper %>(value) : value) : entry.<%= key %>,
 <%
         } else {
 -%>
-    <%= key %>: entry.<%= key %> != null && typeof entry.<%= key %> === "object" && typeof entry.<%= key %>.id === "string" ? <%= wrapper %>(entry.<%= key %>) : entry.<%= key %>,
+    <%= key %>: isPopulatedEntry(entry.<%= key %>) ? <%= wrapper %>(entry.<%= key %>) : entry.<%= key %>,
 <%
         }
         break;
@@ -121,6 +127,23 @@ 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) {
@@ -132,7 +155,9 @@ if (hasPolymorphicReferences) {
  * (unpopulated) values pass through untouched.
  */
 function wrapPolymorphic(value: any, wrappers: Record<string, (entry: Record<string, any>) => any>): any {
-  if (value == null || typeof value !== "object" || typeof value.id !== "string") return value;
+  if (!isPopulatedEntry(value)) {
+    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;
@@ -159,6 +184,11 @@ 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) %>);
 
@@ -172,8 +202,12 @@ 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> {
@@ -202,6 +236,7 @@ function withReadOptions<TPopulate extends <%= model.pascal %>Populate | undefin
 function splitWritePayload(payload: Partial<<%= model.pascal %>Input>): Record<string, unknown> {
   const {
     id,
+    entryId,
     documentId,
     locale,
     createdAt,
@@ -253,7 +288,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, false)}`, { headers: fimoHeaders() });
+  const res = await fetch(`${base}${withReadOptions(`/entries/<%= model.uid %>/${id}`, options)}`, { 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>;
@@ -354,18 +389,21 @@ 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 res = await fetch(`${base}/entries/<%= model.uid %>/${id}`, {
+  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}`, {
     method: "PUT",
     headers: fimoHeaders({ "Content-Type": "application/json" }),
-    body: JSON.stringify(splitWritePayload(payload))
+    body: JSON.stringify({ data: write.data })
   });
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
   return wrapWithSource(data.data);
 }
 
-export async function remove(id: string): Promise<void> {
-  const res = await fetch(`${base}/entries/<%= model.uid %>/${id}`, { method: "DELETE", headers: fimoHeaders() });
+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() });
   if (!res.ok) throw new Error(await res.text());
 }
 <% } else { -%>
@@ -399,7 +437,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, 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", 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,
@@ -409,8 +447,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 } = {}) {
-  const locale = readLocale(options, false, useQueryLocale(options.locale));
+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);
   const localizedOptions = { ...options, locale };
   return useQuery<<%= model.pascal %>Result<undefined, TPopulate>, Error>({ queryKey: qk.byId(id, localizedOptions), queryFn: () => getById(id, localizedOptions) });
 }
@@ -475,8 +513,8 @@ export function useInfiniteList<
   };
 }
 
-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));
+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);
   const localizedOptions = { ...options, locale };
   return useSuspenseQuery<<%= model.pascal %>Result<undefined, TPopulate>, Error>({ queryKey: qk.byId(id, localizedOptions), queryFn: () => getById(id, localizedOptions) });
 }
@@ -508,30 +546,37 @@ export function useSuspenseGet<
 
 export function useCreate() {
   const qc = useQueryClient();
+  const activeLocale = useQueryLocale();
   return useMutation<<%= model.pascal %>, Error, <%= model.pascal %>Input>({
-    mutationFn   : create,
+    mutationFn   : (payload) => create(withMutationLocale(payload, activeLocale)),
     onSuccess    : () => qc.invalidateQueries({ queryKey: qk.root })
   });
 }
 
 export function useUpdate() {
   const qc = useQueryClient();
-  return useMutation<<%= model.pascal %>, Error, { id: string } & Partial<<%= model.pascal %>Input>>({
-    mutationFn   : ({ id, ...patch }) => update(id, patch),
+  const activeLocale = useQueryLocale();
+  return useMutation<<%= model.pascal %>, Error, { id: string; locale?: string } & Partial<<%= model.pascal %>Input>>({
+    mutationFn   : ({ id, ...patch }) => update(id, withMutationLocale(patch, activeLocale)),
     onSuccess    : (_data, vars) => {
       qc.invalidateQueries({ queryKey: qk.root });
-      qc.invalidateQueries({ queryKey: qk.byId(vars.id) });
+      qc.invalidateQueries({ queryKey: qk.byId(vars.id, { locale: vars.locale ?? activeLocale }) });
     }
   });
 }
 
 export function useRemove() {
   const qc = useQueryClient();
-  return useMutation<void, Error, string>({
-    mutationFn   : remove,
-    onSuccess    : (_data, id) => {
+  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 };
       qc.invalidateQueries({ queryKey: qk.root });
-      qc.removeQueries({ queryKey: ["<%= model.pascal %>", id], exact: false });
+      qc.removeQueries({ queryKey: qk.byId(id, { locale }), exact: false });
     }
   });
 }
@@ -555,8 +600,9 @@ 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: update,
+    mutationFn: (payload) => update(withMutationLocale(payload, activeLocale)),
     onSuccess: () => qc.invalidateQueries({ queryKey: qk.root })
   });
 }

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

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

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`, `documentId`, `slug`, `locale`, `createdAt`, `updatedAt`, `__fimo`.
+`id`, `entryId`, `documentId`, `slug`, `locale`, `createdAt`, `updatedAt`, `__fimo`.
 
-Localized entries expose `locale`; non-localized entries omit it. It remains reserved in both schemas.
+Collection entries expose the effective `locale`. It remains reserved for both localized and shared 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` | `{ "documentId": "..." }`, `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` | `{ "id": "..." }`, `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 store reference objects with the target `documentId`, not row `id` values: `{ "documentId": "..." }`.
+- Entry values use the target's stable `id`, never the variant `entryId`: `{ "id": "..." }`.
 - 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": { "documentId": "750e8400-e29b-41d4-a716-446655440000" },
-    "contributors": [{ "documentId": "750e8400-e29b-41d4-a716-446655440000" }]
+    "author": { "id": "750e8400-e29b-41d4-a716-446655440000" },
+    "contributors": [{ "id": "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 stored 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 existing 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 row.
+- Singleton-to-collection preserves the existing entry.
 
 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.
 
@@ -192,9 +192,10 @@ 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; // localized schemas only; omitted when i18n.enabled is false
+  locale: string;
   createdAt: string;
   updatedAt: string;
   __fimo: {
@@ -213,13 +214,14 @@ Content fields live at the top level. Fimo-owned metadata that is not part of th
 
 ## Localized and shared content
 
-Localized content is stored per locale. Generated hooks read the active Fimo locale automatically.
+Localized content has one variant 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:
 
-- have no public `locale` property;
+- 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;
 - 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.
@@ -228,7 +230,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 store `{ contentType, documentId }`; 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 use `{ contentType, id }`; populated values in generated hooks carry a top-level `$type` that narrows the union:
 
 ```ts
 for (const item of page.featured) {
@@ -245,19 +247,21 @@ 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?: { populate?: TPopulate }): Promise<BlogPostResult<undefined, TPopulate>>
+getById<TPopulate extends BlogPostPopulate | undefined>(id: string, options?: { locale?: string; 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): Promise<void>
+remove(id: string, options?: { locale?: string }): Promise<void>
 
 // react-query hooks
-useGetById(id, { populate? })     // → { data: BlogPostResult<undefined, TPopulate> | undefined, isLoading, ... }
+useGetById(id, { locale?, 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, ... }
@@ -279,7 +283,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; non-localized singletons have one locale-free row.
+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.
 
 Choose the collection interface from the UI behavior. Use `useList` when the UI controls a page, and read pagination state from `pageInfo`:
 
@@ -335,10 +339,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 `documentId` string, for example `where: { author: "750e..." }`; for to-many references that means "contains this target document".
+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".
 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`, and returns only the requested fields beyond that:
+Use `fields` to keep list payloads small. The API always keeps `id`, `entryId`, `documentId`, and `locale`, and returns only the requested fields beyond that:
 
 ```tsx
 const { data: summaries = [] } = BlogPost.useGet({
@@ -346,7 +350,7 @@ const { data: summaries = [] } = BlogPost.useGet({
   sort: '-publishedAt',
   limit: 12,
 });
-// summaries: Array<Pick<BlogPost, 'id' | 'slug' | 'title' | 'excerpt' | 'coverImage'>>
+// summaries: Array<Pick<BlogPost, 'id' | 'entryId' | 'documentId' | 'locale' | 'slug' | 'title' | 'excerpt' | 'coverImage'>>
 ```
 
 Use `populate` to embed reference targets in read results:
@@ -356,7 +360,7 @@ const { data: posts = [] } = BlogPost.useGet({
   fields: ['slug', 'title', 'author'] as const,
   populate: ['author'] as const,
 });
-// Without populate: post.author is { documentId: "..." }.
+// Without populate: post.author is { id: "..." }.
 // With populate: post.author is the target Author entry object, or null.
 ```
 
@@ -384,16 +388,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 `documentId`; use `populate` when embedded target rows 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 `id`; use `populate` when embedded targets are needed |
 
 Rules of thumb:
 
@@ -434,7 +438,7 @@ export function BlogList() {
   return (
     <ul>
       {page.items.map((post) => (
-        <li key={post.id}>
+        <li key={`${post.id}:${post.locale}`}>
           <Text value={post.title} as="h2" />
           <Image value={post.coverImage} width={800} height={400} fit="cover" />
           <RichText value={post.body} className="prose" />
@@ -451,9 +455,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>?fields=slug,title&limit=12`);
+const res = await fetch(`${import.meta.env.VITE_API_URL}/entries/<typeName>?locale=en&fields=slug,title&limit=12`);
 const { data, meta } = await res.json();
-// data: Entry[] — fields flattened at top level (id, slug, title, ...)
+// data: Entry[] — fields flattened at top level (id, entryId, documentId, locale, slug, title, ...)
 // meta: { limit, offset, total, hasMore }
 ```
 

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

@@ -32,7 +32,7 @@ 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.
 
-Schema transitions are automatic. Adding fields and changing labels preserve content. Removing a field removes only that field's stored values. One-to-many reference changes wrap existing references in arrays. Field type changes, scalar/reference changes, reference target changes, and many-to-one changes clear only the changed field. Collection-to-singleton removes that type's entries and cleans inbound references; singleton-to-collection preserves its row. There are no reset or data-loss flags: changing the schema is the migration request. Run `fimo validate` after pushing to verify the regenerated client and whole project.
+Schema transitions are automatic. Adding fields and changing labels preserve content. Removing a field removes only that field's values. One-to-many reference changes wrap existing references in arrays. Field type changes, scalar/reference changes, reference target changes, and many-to-one changes clear only the changed field. Collection-to-singleton removes that type's entries and cleans inbound references; singleton-to-collection preserves its entry. There are no reset or data-loss flags: changing the schema is the migration request. Run `fimo validate` after pushing to verify the regenerated client and whole project.
 
 ## Entries CLI commands
 
@@ -43,9 +43,9 @@ fimo entries create <TypeName> --body '<json>'
 fimo entries create <TypeName> --locale es --document-id <documentId> --body '<json>'
 fimo entries list <TypeName> [--limit N] [--offset N] [--search Q] [--where JSON] [--sort F] [--fields FIELDS] [--populate FIELDS]
 fimo entries list <TypeName> --locale es
-fimo entries get <TypeName> <id>
-fimo entries update <TypeName> <id> --locale es --body '<json>'
-fimo entries delete <TypeName> <id>
+fimo entries get <TypeName> <id> [--locale es]
+fimo entries update <TypeName> <id> [--locale es] --body '<json>'
+fimo entries delete <TypeName> <id> [--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 `fimo/references/content.md`. **Always read that first before constructing an entry payload — slug must be inside `data`, media has a specific shape, richtext must be Tiptap JSONContent.**
@@ -65,12 +65,12 @@ fimo entries list BlogPost --fields slug,title,author --populate author
 Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`, `--offset`, `--fields`, and `--populate`.
 `--where` is a JSON object keyed by schema field name. Simple values mean equality and stay typed inside the JSON (`{"featured":true}`, `{"category":"react"}`, `{"rank":{"$gte":3}}`); operator objects support `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, and `$null`, subject to the field type. Public Fimo-owned metadata lives under `__fimo`; currently `__fimo.contentType` is filterable.
 
-Reference filters take the target `documentId` string even though stored values are objects (`{"author":"750e..."}`). On a to-many field, `$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 `--sort field` / `--sort -field` on scalar fields.
-`--fields` is a comma-separated projection for list payloads. The API always keeps `id`; pass only the fields your view needs, such as `slug,title,excerpt,coverImage`.
+Reference filters take the target `id` string (`{"author":"750e..."}`). On a to-many field, `$eq` and `$contains` mean membership, `$in` means any listed target is present, `$ne` and `$nin` mean none are present, and `$null: true` means empty or missing. Reference fields cannot be sorted; use `--sort field` / `--sort -field` on scalar fields.
+`--fields` is a comma-separated projection for list payloads. The API always keeps `id`, `entryId`, `documentId`, and `locale`; pass only the other fields your view needs, such as `slug,title,excerpt,coverImage`.
 
-`--populate` is a comma-separated list of reference fields to embed. Without it, reference fields return reference objects like `{ "documentId": "..." }`; with `--populate author,contributors`, those fields return the target entry objects for the requested locale. Only reference fields can be populated (scalar fields 400), and populate never selects which target fields come back. A populated target missing in the requested locale resolves to null unless you pass `localeFallbacks=true`, which falls back to the best available locale variant, marked by its `locale` field. Limits: 200 references per to-many write, 500 distinct populated documents per field per request (400 past either).
+`--populate` is a comma-separated list of reference fields to embed. Without it, reference fields return reference objects like `{ "id": "..." }`; with `--populate author,contributors`, those fields return the target entry objects for the requested locale. Only reference fields can be populated (scalar fields 400), and populate never selects which target fields come back. A populated target missing in the requested locale resolves to null unless you pass `localeFallbacks=true`, which falls back to the best available locale variant, marked by its `locale` field. Limits: 200 references per to-many write, 500 distinct populated documents per field per request (400 past either).
 
-Polymorphic references declare `targets: ["Post", "Product"]` instead of `target` (never both) and their values carry both parts: `{ "contentType": "Post", "documentId": "..." }`. 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.
+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 `fimo/references/content.md`. Writes use the separate generated `BlogPostInput` type.
 
@@ -85,28 +85,28 @@ For reference schema JSON and entry value shape, load `fimo/references/content.m
 }
 ```
 
-Entry bodies store reference objects with target `documentId` values:
+Entry bodies use reference objects with target `id` values:
 
 ```bash
-fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":{"documentId":"750e8400-e29b-41d4-a716-446655440000"},"contributors":[]}}'
+fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":{"id":"750e8400-e29b-41d4-a716-446655440000"},"contributors":[]}}'
 ```
 
-Do not add `localized` or field-level `i18n` to reference fields. The reference value belongs to the entry variant that stores it.
+Do not add `localized` or field-level `i18n` to reference fields. The reference value belongs to the entry variant containing it.
 
 ## Localized and shared content
 
-Schemas are localized by default. Omit `--locale` for default-locale entries. Pass `--locale <locale>` when creating, listing, reading, or updating a specific non-default locale.
+Schemas are localized by default. Omit `--locale` to use the project default. Pass it explicitly when reading, updating, or deleting a non-default variant: public identity is stable `id` plus `locale`.
 
 When creating a localized variant of an existing entry, pass the source entry's `documentId` with `--document-id`. Keep projects single-locale unless the user asks for multilingual or localized output; when multiple locales are configured, create and update every locale explicitly.
 
-For content shared across locales, define `"i18n": { "enabled": false }` at the schema root and create each entry once. Do not pass `--document-id` to manufacture locale variants. Shared entry responses omit `locale`; a read locale is only used to resolve populated references that target localized schemas. No other `i18n` options and no field-level localization settings are supported.
+For content shared across locales, define `"i18n": { "enabled": false }` at the schema root and create each entry once. Do not pass `--document-id` to manufacture locale variants. Raw API and CLI responses omit `locale`; generated collection models add the effective active/default locale without creating per-locale variants. No other `i18n` options and no field-level localization settings are supported.
 
 Use `"isSingleton": true` for a type with exactly one logical document. Generated singleton clients expose `get`/`update` and their React Query hooks, not collection create/remove APIs.
 
 ## "Add a blog" recipe
 
 1. Load `fimo/references/content.md` 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`, `documentId`, `locale`, `createdAt`, `updatedAt`, `__fimo`) is reserved entry metadata and will be rejected; every entry gets a `slug` for free.
+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 generate pruna/p-image --prompt "..."` (per-model flags come from `fimo models show <model>`; see `media.md`).
 5. Seed entries: `fimo entries create BlogPost --body '{"data": {"slug": "first-post", "title": "...", "coverImage": {...}}}'`.

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-14T21:14:24.078Z",
+  "bundledAt": "2026-07-15T20:44:56.997Z",
   "cliVersion": "0.6.0",
   "external": [
     "oxc-parser",