fimo 0.5.0 → 0.6.0-experimental.2

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
@@ -36,16 +36,35 @@ export type { <%= model.pascal %>, <%= model.pascal %>Fields, <%= model.pascal %
  * Wraps raw API data with Fimo types for source tracking
  */
 export function wrapWithSource(entry: Record<string, any>): <%= model.pascal %> {
+<% if (!model.isSingleton) { -%>
+  const documentId = entry.documentId;
+  const locale = entry.locale;
+  const sourcePrefix = `<%= model.pascal %>.v2:${documentId}:${encodeURIComponent(locale)}`;
+<% } else { -%>
   const id = entry.id;
-  const sourcePrefix = `<%= model.pascal %>.${id}`;
+  const documentId = entry.documentId;
+  const locale = entry.locale ?? defaultLocale();
+  const usesV2Identity = typeof id !== "string";
+  const sourcePrefix = usesV2Identity
+    ? `<%= model.pascal %>.v2:${documentId}:${encodeURIComponent(locale)}`
+    : `<%= model.pascal %>.${id}`;
+<% } -%>
   const entryFimo = entry.__fimo && typeof entry.__fimo === "object" ? entry.__fimo : {};
 
   return {
-    id,
-    documentId: entry.documentId,
+<% if (!model.isSingleton) { -%>
+    documentId,
+<% } else { -%>
+    ...(typeof id === "string" ? { id } : {}),
+    documentId,
+<% } -%>
     slug: entry.slug != null ? new FimoString(entry.slug, `${sourcePrefix}.slug`) : entry.slug,
-<% if (model.localized) { -%>
-    locale: entry.locale,
+<% if (!model.isSingleton) { -%>
+    locale,
+<% } else if (model.localized) { -%>
+    locale,
+<% } else { -%>
+    ...(usesV2Identity ? { locale } : {}),
 <% } -%>
     createdAt: entry.createdAt,
     updatedAt: entry.updatedAt,
@@ -101,11 +120,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 +140,23 @@ if (model.fields) {
   } as <%= model.pascal %>;
 }
 
+interface PopulatedEntryRecord extends Record<string, unknown> {
+  documentId: 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.documentId === "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 +168,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;
@@ -172,8 +210,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> {
@@ -249,11 +291,11 @@ export type InfiniteListResult<TItem> = UseInfiniteQueryResult<
   readonly isLoadingMore: boolean;
 };
 
-export async function getById<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(
-  id: string,
+export async function getByDocumentId<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(
+  documentId: 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(`/v2/entries/<%= model.uid %>/${documentId}`, 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>;
@@ -263,7 +305,7 @@ export async function getBySlug<TPopulate extends <%= model.pascal %>Populate |
   slug: string,
   options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}
 ): Promise<<%= model.pascal %>Result<undefined, TPopulate> | null> {
-  const res = await fetch(`${base}${withReadOptions(`/entries/<%= model.uid %>/slug/${encodeURIComponent(slug)}`, options)}`, { headers: fimoHeaders() });
+  const res = await fetch(`${base}${withReadOptions(`/v2/entries/<%= model.uid %>/slug/${encodeURIComponent(slug)}`, options)}`, { headers: fimoHeaders() });
   if (res.status === 404) return null;
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
@@ -275,7 +317,7 @@ export async function getByField<TPopulate extends <%= model.pascal %>Populate |
   value: string,
   options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}
 ): Promise<<%= model.pascal %>Result<undefined, TPopulate> | null> {
-  const res = await fetch(`${base}${withReadOptions(`/entries/<%= model.uid %>/field/${encodeURIComponent(fieldName)}/${encodeURIComponent(value)}`, options)}`, { headers: fimoHeaders() });
+  const res = await fetch(`${base}${withReadOptions(`/v2/entries/<%= model.uid %>/field/${encodeURIComponent(fieldName)}/${encodeURIComponent(value)}`, options)}`, { headers: fimoHeaders() });
   if (res.status === 404) return null;
   if (!res.ok) throw new Error(await res.text());
   const data = await res.json();
@@ -321,7 +363,7 @@ export async function list<
   TPopulate extends <%= model.pascal %>Populate | undefined = undefined,
 >(params: <%= model.pascal %>Query<TFields, TPopulate> = {} as <%= model.pascal %>Query<TFields, TPopulate>): Promise<CollectionPage<<%= model.pascal %>Result<TFields, TPopulate>>> {
   const qs = toQueryString(params);
-  const res = await fetch(`${base}/entries/<%= model.uid %>${qs ? "?" + qs : ""}`, { headers: fimoHeaders() });
+  const res = await fetch(`${base}/v2/entries/<%= model.uid %>${qs ? "?" + qs : ""}`, { headers: fimoHeaders() });
   if (!res.ok) throw new Error(await res.text());
   const data = parseCollectionResponse(await res.json());
   const items = data.data.map(wrapWithSource) as <%= model.pascal %>Result<TFields, TPopulate>[];
@@ -343,7 +385,7 @@ export async function get<
 }
 
 export async function create(payload: <%= model.pascal %>Input): Promise<<%= model.pascal %>> {
-  const res = await fetch(`${base}/entries/<%= model.uid %>`, {
+  const res = await fetch(`${base}/v2/entries/<%= model.uid %>`, {
     method: "POST",
     headers: fimoHeaders({ "Content-Type": "application/json" }),
     body: JSON.stringify(splitWritePayload(payload))
@@ -353,19 +395,22 @@ export async function create(payload: <%= model.pascal %>Input): Promise<<%= mod
   return wrapWithSource(data.data);
 }
 
-export async function update(id: string, payload: Partial<<%= model.pascal %>Input>): Promise<<%= model.pascal %>> {
-  const res = await fetch(`${base}/entries/<%= model.uid %>/${id}`, {
+export async function update(documentId: string, payload: Partial<<%= model.pascal %>Input>): Promise<<%= model.pascal %>> {
+  const write = splitWritePayload(payload) as { data: Record<string, unknown>; locale?: string };
+  const url = withReadOptions(`/v2/entries/<%= model.uid %>/${documentId}`, { 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(documentId: string, options: { locale?: string } = {}): Promise<void> {
+  const url = withReadOptions(`/v2/entries/<%= model.uid %>/${documentId}`, options);
+  const res = await fetch(`${base}${url}`, { method: "DELETE", headers: fimoHeaders() });
   if (!res.ok) throw new Error(await res.text());
 }
 <% } else { -%>
@@ -399,7 +444,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,
+  byDocumentId: <TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(documentId: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) => ["<%= model.pascal %>", "document", documentId, 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,10 +454,10 @@ 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 useGetByDocumentId<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(documentId: 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) });
+  return useQuery<<%= model.pascal %>Result<undefined, TPopulate>, Error>({ queryKey: qk.byDocumentId(documentId, localizedOptions), queryFn: () => getByDocumentId(documentId, localizedOptions) });
 }
 
 export function useGetBySlug<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(slug: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) {
@@ -475,10 +520,10 @@ 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 useSuspenseGetByDocumentId<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(documentId: 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) });
+  return useSuspenseQuery<<%= model.pascal %>Result<undefined, TPopulate>, Error>({ queryKey: qk.byDocumentId(documentId, localizedOptions), queryFn: () => getByDocumentId(documentId, localizedOptions) });
 }
 
 export function useSuspenseGetBySlug<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(slug: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) {
@@ -516,22 +561,22 @@ export function useCreate() {
 
 export function useUpdate() {
   const qc = useQueryClient();
-  return useMutation<<%= model.pascal %>, Error, { id: string } & Partial<<%= model.pascal %>Input>>({
-    mutationFn   : ({ id, ...patch }) => update(id, patch),
+  return useMutation<<%= model.pascal %>, Error, { documentId: string; locale?: string } & Partial<<%= model.pascal %>Input>>({
+    mutationFn   : ({ documentId, ...patch }) => update(documentId, patch),
     onSuccess    : (_data, vars) => {
       qc.invalidateQueries({ queryKey: qk.root });
-      qc.invalidateQueries({ queryKey: qk.byId(vars.id) });
+      qc.invalidateQueries({ queryKey: qk.byDocumentId(vars.documentId, { locale: vars.locale ?? defaultLocale() }) });
     }
   });
 }
 
 export function useRemove() {
   const qc = useQueryClient();
-  return useMutation<void, Error, string>({
-    mutationFn   : remove,
-    onSuccess    : (_data, id) => {
+  return useMutation<void, Error, { documentId: string; locale?: string }>({
+    mutationFn   : ({ documentId, locale }) => remove(documentId, { locale }),
+    onSuccess    : (_data, { documentId, locale }) => {
       qc.invalidateQueries({ queryKey: qk.root });
-      qc.removeQueries({ queryKey: ["<%= model.pascal %>", id], exact: false });
+      qc.removeQueries({ queryKey: qk.byDocumentId(documentId, { locale: locale ?? defaultLocale() }), exact: false });
     }
   });
 }
@@ -569,7 +614,7 @@ export function useUpdate() {
 export default {
 <% if (!model.isSingleton) { -%>
   /* async helpers */
-  getById,
+  getByDocumentId,
   getBySlug,
   getByField,
   list,
@@ -579,13 +624,13 @@ export default {
   remove,
 
   /* hooks */
-  useGetById,
+  useGetByDocumentId,
   useGetBySlug,
   useGetByField,
   useList,
   useInfiniteList,
   useGet,
-  useSuspenseGetById,
+  useSuspenseGetByDocumentId,
   useSuspenseGet,
   useSuspenseGetByField,
   useSuspenseGetBySlug,

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

@@ -32,11 +32,15 @@ export interface <%= model.pascal %>FimoMeta {
 }
 
 export interface <%= model.pascal %> extends WithReferences<<%= model.pascal %>References> {
-  id: string;
+<% if (model.isSingleton) { -%>
+  id?: 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/SKILL.md

@@ -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 7 framework mode → `references/setup-react-router.md`
+  - 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`

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

@@ -191,10 +191,9 @@ Import from the public schema module, e.g. `import BlogPost from '@/schemas/Blog
 
 ```ts
 interface BlogPost {
-  id: string;
   documentId: string;
   slug: FimoString;
-  locale: string; // localized schemas only; omitted when i18n.enabled is false
+  locale: string;
   createdAt: string;
   updatedAt: string;
   __fimo: {
@@ -219,7 +218,7 @@ When a project has multiple configured locales, create and update each localized
 
 For shared content, set `i18n: { "enabled": false }` on the schema and create each entry once. Shared entries:
 
-- have no public `locale` property;
+- expose the effective request locale in collection v2 responses;
 - 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.
@@ -247,17 +246,17 @@ Filtering on polymorphic fields is not supported yet.
 
 ```ts
 // low-level fetch helpers
-getById<TPopulate extends BlogPostPopulate | undefined>(id: string, options?: { populate?: TPopulate }): Promise<BlogPostResult<undefined, TPopulate>>
+getByDocumentId<TPopulate extends BlogPostPopulate | undefined>(documentId: 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>
+update(documentId: string, payload: Partial<BlogPostInput>): Promise<BlogPost>
+remove(documentId: string, options?: { locale?: string }): Promise<void>
 
 // react-query hooks
-useGetById(id, { populate? })     // → { data: BlogPostResult<undefined, TPopulate> | undefined, isLoading, ... }
+useGetByDocumentId(documentId, { 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, ... }
@@ -266,7 +265,7 @@ useGet<TFields, TPopulate>(params?)          // → legacy array-shaped { data:
 useCreate() / useUpdate() / useRemove()
 
 // Suspense variants (same signatures, throw to a <Suspense> boundary instead of returning isLoading)
-useSuspenseGetById(id) / useSuspenseGetBySlug(slug) / useSuspenseGetByField(fieldName, value) / useSuspenseGet(params?)
+useSuspenseGetByDocumentId(documentId) / useSuspenseGetBySlug(slug) / useSuspenseGetByField(fieldName, value) / useSuspenseGet(params?)
 ```
 
 Write inputs contain plain JSON values. Read models contain Fimo wrapper values for source tracking, so use `BlogPostInput` rather than sending a `BlogPost` back to `create` or `update`.
@@ -279,7 +278,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`, `getByDocumentId`, 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`:
 
@@ -338,7 +337,7 @@ Operators: scalar equality, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `
 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`, and returns only the requested fields beyond that:
+Use `fields` to keep list payloads small. The v2 API always keeps `documentId` and `locale`, and returns only the requested fields beyond that:
 
 ```tsx
 const { data: summaries = [] } = BlogPost.useGet({
@@ -346,7 +345,7 @@ const { data: summaries = [] } = BlogPost.useGet({
   sort: '-publishedAt',
   limit: 12,
 });
-// summaries: Array<Pick<BlogPost, 'id' | 'slug' | 'title' | 'excerpt' | 'coverImage'>>
+// summaries: Array<Pick<BlogPost, 'documentId' | 'locale' | 'slug' | 'title' | 'excerpt' | 'coverImage'>>
 ```
 
 Use `populate` to embed reference targets in read results:
@@ -434,7 +433,7 @@ export function BlogList() {
   return (
     <ul>
       {page.items.map((post) => (
-        <li key={post.id}>
+        <li key={`${post.documentId}:${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 +450,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}/v2/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 (documentId, locale, slug, title, ...)
 // meta: { limit, offset, total, hasMore }
 ```
 

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

@@ -67,6 +67,14 @@ 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 7
+# Setup Fimo on React Router 8
 
 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 20+
+- Node 22.22+
 - 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 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.
+- 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.
 - Reserve `<a>` for external links, with `target="_blank" rel="noreferrer"`.
 
 ### Loading states

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

@@ -20,6 +20,9 @@ Steps 1, 3, and 5 reference the project skill (`fimo`) for shape and React API.
 
 ```bash
 fimo schemas push [TypeName]      # push JSON to API (create or update). Omit TypeName to push all.
+                                  # Pushing all sends every schema as ONE atomic batch, so types that
+                                  # reference each other (even cycles) can be added in a single push.
+                                  # Files not present are never deleted — use `schemas delete` for that.
 fimo schemas list                 # list all registered schemas
 fimo schemas get <TypeName>       # get a single schema
 fimo schemas delete <TypeName>    # delete a schema
@@ -40,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> <documentId> --locale es
+fimo entries update <TypeName> <documentId> --locale es --body '<json>'
+fimo entries delete <TypeName> <documentId> --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.**
@@ -63,7 +66,7 @@ Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`,
 `--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`.
+`--fields` is a comma-separated projection for list payloads. The v2 API always keeps `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).
 
@@ -92,11 +95,11 @@ Do not add `localized` or field-level `i18n` to reference fields. The reference
 
 ## 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` for default-locale creates and lists. `entries get`, `entries update`, and `entries delete` require `--locale` because collection entry identity is always `documentId + 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. V2 shared entry responses expose the effective request locale even though storage still has one locale-free row. 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.
 

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

@@ -67,6 +67,12 @@ 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.
 
+## 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.
+
 ## Labels And Content
 
 Labels and content are separate translated surfaces:

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-14T09:33:53.022Z",
+  "bundledAt": "2026-07-14T21:53:17.245Z",
   "cliVersion": "0.5.0",
   "external": [
     "oxc-parser",