fimo 0.4.0-experimental.4 → 0.4.0-staging.1

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

@@ -1,9 +1,10 @@
 <%
 /**
  * INPUT  ▸  model = {
- *            uid: "api::blog.blog",     // UID in format "api::name.name"
- *            pascal: "Blog"             // PascalCase for type names
- *            fields: {key: {type, required?, multiple?}} // Schema fields
+ *            uid: "Post",       // matches src/schemas/<uid>.json (letters, numbers, underscores)
+ *            pascal: "Post",    // pascalCase(uid), used for generated type names
+ *            fields: {key: {type, required?, multiple?, many?, target?, targetPascal?}},
+ *            relationImports: [{uid, pascal}]  // relation targets other than this schema
  *          }
  */
 %>
@@ -14,15 +15,15 @@ import { FimoString, FimoMedia, FimoBoolean, FimoRichText, useLocale } from "fim
 import fimoConfig from "virtual:fimo-config";
 import type { <%= model.pascal %>, <%= model.pascal %>Input, <%= model.pascal %>Populate, <%= model.pascal %>Result<% if (!model.isSingleton) { %>, <%= model.pascal %>Fields, <%= model.pascal %>Query<% } %> } from "./<%= model.pascal %>.types";
 <%
-if (model.relationImports && model.relationImports.length > 0) {
-  model.relationImports.forEach((relationImport) => {
+if (model.referenceImports && model.referenceImports.length > 0) {
+  model.referenceImports.forEach((referenceImport) => {
 -%>
-import { wrapWithSource as wrap<%= relationImport.pascal %>WithSource } from "./<%= relationImport.pascal %>";
+import { wrapWithSource as wrap<%= referenceImport.pascal %>WithSource } from "./<%= referenceImport.pascal %>";
 <%
   });
 }
 -%>
-export type { <%= model.pascal %>, <%= model.pascal %>Fields, <%= model.pascal %>FimoMeta, <%= model.pascal %>Input, <%= model.pascal %>Populate, <%= model.pascal %>Query, <%= model.pascal %>Relations, <%= model.pascal %>Result, <%= model.pascal %>Sort, <%= model.pascal %>Where } from "./<%= model.pascal %>.types";
+export type { <%= model.pascal %>, <%= model.pascal %>Fields, <%= model.pascal %>FimoMeta, <%= model.pascal %>Input, <%= model.pascal %>Populate, <%= model.pascal %>Query, <%= model.pascal %>References, <%= model.pascal %>Result, <%= model.pascal %>Sort, <%= model.pascal %>Where } from "./<%= model.pascal %>.types";
 
 /*───────────────────────────────────────────────────────────────*/
 /*  ────────────  🎁  Source wrapping  ────────────              */
@@ -79,7 +80,21 @@ if (model.fields) {
 <%
         }
         break;
-      case 'relation': {
+      case 'reference': {
+        if (Array.isArray(field.targetRefs) && field.targetRefs.length > 0) {
+          const wrapperFor = (ref) => ref.uid === model.uid ? 'wrapWithSource' : `wrap${ref.pascal}WithSource`;
+          const wrappers = `{ ${field.targetRefs.map((ref) => `"${ref.uid}": ${wrapperFor(ref)}`).join(', ')} }`;
+          if (field.many) {
+-%>
+    <%= key %>: Array.isArray(entry.<%= key %>) ? entry.<%= key %>.map((value: any) => wrapPolymorphic(value, <%= wrappers %>)) : entry.<%= key %>,
+<%
+          } else {
+-%>
+    <%= key %>: wrapPolymorphic(entry.<%= key %>, <%= wrappers %>),
+<%
+          }
+          break;
+        }
         const wrapper = field.target === model.uid ? 'wrapWithSource' : `wrap${field.targetPascal}WithSource`;
         if (field.many) {
 -%>
@@ -103,6 +118,29 @@ if (model.fields) {
   } as <%= model.pascal %>;
 }
 
+<%
+const hasPolymorphicReferences = model.fields && Object.values(model.fields).some((field) => field.type === 'reference' && Array.isArray(field.targetRefs) && field.targetRefs.length > 0);
+if (hasPolymorphicReferences) {
+-%>
+/**
+ * Wraps one polymorphic reference value. Populated entries carry their type
+ * marker; the wrapper picks the right per-type wrapping and stamps a
+ * top-level $type so the generated union narrows in a switch. Raw
+ * (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;
+  const contentType = value.__fimo && typeof value.__fimo.contentType === "string" ? value.__fimo.contentType : null;
+  const wrapper = contentType ? wrappers[contentType] : undefined;
+  if (!wrapper) return value;
+  const wrapped = wrapper(value) as Record<string, unknown>;
+  wrapped.$type = contentType;
+  return wrapped;
+}
+
+<%
+}
+-%>
 /*───────────────────────────────────────────────────────────────*/
 /*  ────────────  🔌  Low-level fetch helpers  ────────────      */
 /*───────────────────────────────────────────────────────────────*/
@@ -119,7 +157,7 @@ function useQueryLocale(locale?: string): string {
 }
 
 const LOCALIZED_CONTENT = <%= model.localized ? 'true' : 'false' %>;
-const LOCALIZED_RELATION_FIELDS = new Set<string>(<%= JSON.stringify(model.localizedRelationFields) %>);
+const LOCALIZED_REFERENCE_FIELDS = new Set<string>(<%= JSON.stringify(model.localizedReferenceFields) %>);
 
 function populateFields(populate: <%= model.pascal %>Populate | undefined): string[] {
   if (populate == null) return [];
@@ -131,7 +169,7 @@ function readLocale(
   ownerUsesLocale: boolean,
   fallbackLocale = defaultLocale()
 ): string | undefined {
-  const populatesLocalizedTarget = populateFields(options.populate).some((field) => LOCALIZED_RELATION_FIELDS.has(field));
+  const populatesLocalizedTarget = populateFields(options.populate).some((field) => LOCALIZED_REFERENCE_FIELDS.has(field));
   return ownerUsesLocale || populatesLocalizedTarget ? options.locale ?? fallbackLocale : undefined;
 }
 
@@ -145,7 +183,7 @@ function fimoHeaders(extra?: Record<string, string>): Record<string, string> {
 
 function withReadOptions<TPopulate extends <%= model.pascal %>Populate | undefined>(
   url: string,
-  options: { locale?: string; populate?: TPopulate } = {},
+  options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {},
   ownerUsesLocale = LOCALIZED_CONTENT
 ): string {
   const u = new URL(url, "http://fimo.local");
@@ -154,6 +192,7 @@ function withReadOptions<TPopulate extends <%= model.pascal %>Populate | undefin
   if (options.populate != null) {
     u.searchParams.set("populate", typeof options.populate === "string" ? options.populate : options.populate.join(","));
   }
+  if (options.localeFallbacks) u.searchParams.set("localeFallbacks", "true");
   return `${u.pathname}${u.search}`;
 }
 
@@ -178,7 +217,7 @@ function splitWritePayload(payload: Partial<<%= model.pascal %>Input>): Record<s
 <% if (!model.isSingleton) { -%>
 export async function getById<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(
   id: string,
-  options: { locale?: string; populate?: TPopulate } = {}
+  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() });
   if (!res.ok) throw new Error(await res.text());
@@ -188,7 +227,7 @@ export async function getById<TPopulate extends <%= model.pascal %>Populate | un
 
 export async function getBySlug<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(
   slug: string,
-  options: { locale?: string; populate?: TPopulate } = {}
+  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() });
   if (res.status === 404) return null;
@@ -200,7 +239,7 @@ export async function getBySlug<TPopulate extends <%= model.pascal %>Populate |
 export async function getByField<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(
   fieldName: string,
   value: string,
-  options: { locale?: string; populate?: TPopulate } = {}
+  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() });
   if (res.status === 404) return null;
@@ -282,7 +321,7 @@ export async function remove(id: string): Promise<void> {
 }
 <% } else { -%>
 export async function get<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(
-  options: { locale?: string; populate?: TPopulate } = {}
+  options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}
 ): Promise<<%= model.pascal %>Result<undefined, TPopulate>> {
   const res = await fetch(`${base}${withReadOptions(`/documents/<%= model.uid %>`, options)}`, { headers: fimoHeaders() });
   if (!res.ok) throw new Error(await res.text());
@@ -311,25 +350,25 @@ 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 } = {}) => ["<%= model.pascal %>", id, options.locale, options.populate] as const,
-  bySlug     : <TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(slug: string, options: { locale?: string; populate?: TPopulate } = {}) => ["<%= 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 } = {}) => ["<%= model.pascal %>", field, value, 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
 };
 
-export function useGetById<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(id: string, options: { locale?: string; populate?: TPopulate } = {}) {
+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) });
 }
 
-export function useGetBySlug<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(slug: string, options: { locale?: string; populate?: TPopulate } = {}) {
+export function useGetBySlug<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(slug: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) {
   const locale = readLocale(options, LOCALIZED_CONTENT, useQueryLocale(options.locale));
   const localizedOptions = { ...options, locale };
   return useQuery<<%= model.pascal %>Result<undefined, TPopulate> | null, Error>({ queryKey: qk.bySlug(slug, localizedOptions), queryFn: () => getBySlug(slug, localizedOptions), enabled: !!slug });
 }
 
-export function useGetByField<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(fieldName: string, value: string, options: { locale?: string; populate?: TPopulate } = {}) {
+export function useGetByField<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(fieldName: string, value: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) {
   const locale = readLocale(options, LOCALIZED_CONTENT, useQueryLocale(options.locale));
   const localizedOptions = { ...options, locale };
   return useQuery<<%= model.pascal %>Result<undefined, TPopulate> | null, Error>({ queryKey: qk.byField(fieldName, value, localizedOptions), queryFn: () => getByField(fieldName, value, localizedOptions), enabled: !!value });
@@ -344,19 +383,19 @@ export function useGet<
   return useQuery<<%= model.pascal %>Result<TFields, TPopulate>[], Error>({ queryKey: qk.list(localizedParams), queryFn: () => get(localizedParams) });
 }
 
-export function useSuspenseGetById<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(id: string, options: { locale?: string; populate?: TPopulate } = {}) {
+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) });
 }
 
-export function useSuspenseGetBySlug<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(slug: string, options: { locale?: string; populate?: TPopulate } = {}) {
+export function useSuspenseGetBySlug<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(slug: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) {
   const locale = readLocale(options, LOCALIZED_CONTENT, useQueryLocale(options.locale));
   const localizedOptions = { ...options, locale };
   return useSuspenseQuery<<%= model.pascal %>Result<undefined, TPopulate> | null, Error>({ queryKey: qk.bySlug(slug, localizedOptions), queryFn: () => getBySlug(slug, localizedOptions) });
 }
 
-export function useSuspenseGetByField<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(fieldName: string, value: string, options: { locale?: string; populate?: TPopulate } = {}) {
+export function useSuspenseGetByField<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(fieldName: string, value: string, options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) {
   const locale = readLocale(options, LOCALIZED_CONTENT, useQueryLocale(options.locale));
   const localizedOptions = { ...options, locale };
   return useSuspenseQuery<<%= model.pascal %>Result<undefined, TPopulate> | null, Error>({ queryKey: qk.byField(fieldName, value, localizedOptions), queryFn: () => getByField(fieldName, value, localizedOptions) });
@@ -403,16 +442,16 @@ export function useRemove() {
 <% } else { -%>
 const qk = {
   root: ["<%= model.pascal %>"] as const,
-  document: <TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(options: { locale?: string; populate?: TPopulate } = {}) => ["<%= model.pascal %>", "document", options.locale, options.populate] as const
+  document: <TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) => ["<%= model.pascal %>", "document", options.locale, options.populate] as const
 };
 
-export function useGet<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(options: { locale?: string; populate?: TPopulate } = {}) {
+export function useGet<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) {
   const locale = readLocale(options, LOCALIZED_CONTENT, useQueryLocale(options.locale));
   const localizedOptions = { ...options, locale };
   return useQuery<<%= model.pascal %>Result<undefined, TPopulate>, Error>({ queryKey: qk.document(localizedOptions), queryFn: () => get(localizedOptions) });
 }
 
-export function useSuspenseGet<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(options: { locale?: string; populate?: TPopulate } = {}) {
+export function useSuspenseGet<TPopulate extends <%= model.pascal %>Populate | undefined = undefined>(options: { locale?: string; populate?: TPopulate; localeFallbacks?: boolean } = {}) {
   const locale = readLocale(options, LOCALIZED_CONTENT, useQueryLocale(options.locale));
   const localizedOptions = { ...options, locale };
   return useSuspenseQuery<<%= model.pascal %>Result<undefined, TPopulate>, Error>({ queryKey: qk.document(localizedOptions), queryFn: () => get(localizedOptions) });

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

@@ -1,19 +1,20 @@
 <%
 /**
  * INPUT  ▸  model = {
- *            uid: "api::blog.blog",     // UID in format "api::name.name"
- *            pascal: "Blog"             // PascalCase for type names
- *            fields: {key: {type, required?, multiple?}} // Schema fields
+ *            uid: "Post",       // matches src/schemas/<uid>.json (letters, numbers, underscores)
+ *            pascal: "Post",    // pascalCase(uid), used for generated type names
+ *            fields: {key: {type, required?, multiple?, many?, target?, targetPascal?}},
+ *            relationImports: [{uid, pascal}]  // relation targets other than this schema
  *          }
  */
 %>
 // AUTO-GENERATED ⚠️ – do not edit by hand
-import { type Fields, type FimoBoolean, type FimoMedia, type FimoReference, type FimoRichText, type FimoRichTextContent, type FimoString, type Populate, type PopulatedResult, type ProjectedWithPopulate, type Query, type Sort, type Where, type WithRelations } from "fimo/ui";
+import { type Fields, type FimoBoolean, type FimoMedia, type FimoPolymorphicReference, type FimoReference, type FimoRichText, type FimoRichTextContent, type FimoString, type Populate, type PopulatedResult, type ProjectedWithPopulate, type Query, type Sort, type Where, type WithReferences } from "fimo/ui";
 <%
-if (model.relationImports && model.relationImports.length > 0) {
-  model.relationImports.forEach((relationImport) => {
+if (model.referenceImports && model.referenceImports.length > 0) {
+  model.referenceImports.forEach((referenceImport) => {
 -%>
-import type { <%= relationImport.pascal %> } from "./<%= relationImport.pascal %>.types";
+import type { <%= referenceImport.pascal %> } from "./<%= referenceImport.pascal %>.types";
 <%
   });
 }
@@ -30,7 +31,7 @@ export interface <%= model.pascal %>FimoMeta {
   contentType: string;
 }
 
-export interface <%= model.pascal %> extends WithRelations<<%= model.pascal %>Relations> {
+export interface <%= model.pascal %> extends WithReferences<<%= model.pascal %>References> {
   id: string;
   documentId: string;
   slug: FimoString;
@@ -51,6 +52,7 @@ if (model.fields) {
   });
 }
 -%>
+}
 
 export interface <%= model.pascal %>Input {
   slug?: string;
@@ -93,8 +95,10 @@ function getTypeForField(field) {
       return 'Record<string, any>';
     case 'media':
       return field.multiple ? 'FimoMedia[]' : 'FimoMedia';
-    case 'relation':
-      return field.many ? 'FimoReference[]' : 'FimoReference | null';
+    case 'reference': {
+      const raw = Array.isArray(field.targets) && field.targets.length > 0 ? 'FimoPolymorphicReference' : 'FimoReference';
+      return field.many ? `${raw}[]` : `${raw} | null`;
+    }
     default:
       return 'any';
   }
@@ -118,20 +122,35 @@ function getInputTypeForField(field) {
       const media = 'Pick<FimoMedia, "url" | "alt" | "name" | "mime" | "width" | "height">';
       return field.multiple ? `${media}[]` : media;
     }
-    case 'relation':
-      return field.many ? 'FimoReference[]' : 'FimoReference | null';
+    case 'reference': {
+      const raw = Array.isArray(field.targets) && field.targets.length > 0 ? 'FimoPolymorphicReference' : 'FimoReference';
+      return field.many ? `${raw}[]` : `${raw} | null`;
+    }
     default:
       return 'unknown';
   }
 }
 -%>
-}
 
-export interface <%= model.pascal %>Relations {
+export interface <%= model.pascal %>References {
 <%
 if (model.fields) {
   Object.entries(model.fields).forEach(([key, field]) => {
-    if (field.type !== 'relation' || typeof field.targetPascal !== 'string') {
+    if (field.type !== 'reference') {
+      return;
+    }
+    // Polymorphic populated values form a discriminated union on $type —
+    // the generated wrapper stamps it, so `switch (item.$type)` narrows.
+    if (Array.isArray(field.targetRefs) && field.targetRefs.length > 0) {
+      const memberFor = (ref) => `(${ref.uid === model.uid ? model.pascal : ref.pascal} & { $type: "${ref.uid}" })`;
+      const union = field.targetRefs.map(memberFor).join(' | ');
+      const type = field.many ? `(${union})[]` : `${union} | null`;
+-%>
+  <%= key %>: <%= type %>;
+<%
+      return;
+    }
+    if (typeof field.targetPascal !== 'string') {
       return;
     }
     const type = field.many ? `${field.targetPascal}[]` : `${field.targetPascal} | null`;

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

@@ -18,8 +18,8 @@ This file covers the **package surface**: the JSON shape you write, the generate
     "featured": { "type": "boolean" },
     "coverImage": { "type": "media" },
     "metadata": { "type": "json" },
-    "author": { "type": "relation", "target": "Author" },
-    "contributors": { "type": "relation", "target": "Author", "many": true }
+    "author": { "type": "reference", "target": "Author" },
+    "contributors": { "type": "reference", "target": "Author", "many": true }
   }
 }
 ```
@@ -45,22 +45,22 @@ 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               |
-| `relation` | `{ "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` | `{ "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.
 
-## Relation fields
+## Reference fields
 
-Use `relation` when one content entry references another content entry. Do not store entry IDs in a `json` field as a workaround.
+Use `reference` when one content entry references another content entry. Do not store entry IDs in a `json` field as a workaround.
 
 ```json
 {
@@ -68,8 +68,8 @@ Use `relation` when one content entry references another content entry. Do not s
   "name": "Blog Posts",
   "fields": {
     "title": { "type": "string" },
-    "author": { "type": "relation", "target": "Author" },
-    "contributors": { "type": "relation", "target": "Author", "many": true }
+    "author": { "type": "reference", "target": "Author" },
+    "contributors": { "type": "reference", "target": "Author", "many": true }
   }
 }
 ```
@@ -77,21 +77,21 @@ Use `relation` when one content entry references another content entry. Do not s
 Rules:
 
 - `target` is required and must be the PascalCase schema `uid` of the referenced content type.
-- Omit `many` for a to-one relation. Use `"many": true` for a to-many relation.
-- Self-references are allowed, e.g. a `Category` schema can have `parent: { "type": "relation", "target": "Category" }`.
+- 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": "..." }`.
-- Do not include `contentType` for normal fixed-target relations; the schema's `target` already defines it.
-- Do not add `localized` or field-level `i18n` to a relation. The relation value belongs to the entry variant that stores it.
-- Use `null` for an empty to-one relation and `[]` for an empty to-many relation.
-- The API validates that referenced target documents exist and rejects duplicate values in to-many relation arrays.
+- 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.
+- The API validates that referenced target documents exist and rejects duplicate values in to-many reference arrays.
 
 Entry payload example:
 
 ```json
 {
   "data": {
-    "slug": "relation-example",
-    "title": "Relation example",
+    "slug": "reference-example",
+    "title": "Reference example",
     "author": { "documentId": "750e8400-e29b-41d4-a716-446655440000" },
     "contributors": [{ "documentId": "750e8400-e29b-41d4-a716-446655440000" }]
   }
@@ -104,8 +104,8 @@ After editing schema JSON, run `fimo schemas push {Uid}` and then `fimo validate
 
 - Adding fields and changing labels preserve entries.
 - Removing a field removes only that field's values.
-- A one-to-many relation change wraps each existing reference in an array.
-- A many-to-one change, relation target change, scalar type change, or scalar/relation change clears only the changed field.
+- 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.
 
@@ -222,9 +222,26 @@ For shared content, set `i18n: { "enabled": false }` on the schema and create ea
 - 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 relation targets a localized schema.
+- still use the active/requested locale when a populated reference targets a localized schema.
 
-Do not duplicate shared entries across locales, add field-level localization settings, or implement locale fallbacks.
+Do not duplicate shared entries across locales or add field-level localization settings.
+
+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:
+
+```ts
+for (const item of page.featured) {
+  switch (item.$type) {
+    case 'Post':
+      return item.title; // typed as Post here
+    case 'Video':
+      return item.clips; // typed as Video here
+  }
+}
+```
+
+Filtering on polymorphic fields is not supported yet.
 
 **Generated API:**
 
@@ -290,8 +307,8 @@ BlogPost.useGet({
 ```
 
 Operators: scalar equality, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, `$null`.
-Relation field values are reference objects, but relation filters use the target `documentId` string, for example `where: { author: "750e..." }`; for to-many relations that means "contains this target document".
-For to-many relations, `$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. Relation fields cannot be sorted.
+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:
 
@@ -304,7 +321,7 @@ const { data: summaries = [] } = BlogPost.useGet({
 // summaries: Array<Pick<BlogPost, 'id' | 'slug' | 'title' | 'excerpt' | 'coverImage'>>
 ```
 
-Use `populate` to embed relation targets in read results:
+Use `populate` to embed reference targets in read results:
 
 ```tsx
 const { data: posts = [] } = BlogPost.useGet({
@@ -327,11 +344,11 @@ type PostCardItem = BlogPostResult<
 >;
 ```
 
-Do not type populated hook data as `BlogPost[]`: plain `BlogPost` keeps relation fields as `FimoReference` objects, while `BlogPostResult<TFields, TPopulate>` models the projected/populated read result.
+Do not type populated hook data as `BlogPost[]`: plain `BlogPost` keeps reference fields as `FimoReference` objects, while `BlogPostResult<TFields, TPopulate>` models the projected/populated read result.
 
-`BlogPostPopulate` is the generated input type for allowed populate values. It comes from the schema's relation fields, so a post schema with `author` and `contributors` only accepts those names in `populate`. Most app code never imports it directly; it is mainly used by `BlogPostQuery` and hook generics.
+`BlogPostPopulate` is the generated input type for allowed populate values. It comes from the schema's reference fields, so a post schema with `author` and `contributors` only accepts those names in `populate`. Most app code never imports it directly; it is mainly used by `BlogPostQuery` and hook generics.
 
-Populate is depth-one. It only works for relation fields; trying to populate a scalar field returns 400. To-many relation order is preserved.
+Populate is depth-one. It only works for reference fields; trying to populate a scalar field returns 400. To-many reference order is preserved.
 
 The generated hooks do **not** surface pagination meta (`total`, `hasMore`, `limit`, `offset`). If you need it, read it from a raw fetch to `/entries/<typeName>` (see the **Read path** section below), which returns the full `{ data, meta }` envelope.
 
@@ -348,7 +365,7 @@ The entry objects a hook returns are **not** plain JS values. The generated clie
 | `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)                                               |
-| `relation`        | `FimoReference` / `FimoReference[]` | reference object(s) with target `documentId`; use `populate` when embedded target rows are needed |
+| `reference`       | `FimoReference` / `FimoReference[]` | reference object(s) with target `documentId`; use `populate` when embedded target rows are needed |
 
 Rules of thumb:
 

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

@@ -29,7 +29,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 relation changes wrap existing references in arrays. Field type changes, scalar/relation changes, relation 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 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.
 
 ## Entries CLI commands
 
@@ -60,20 +60,24 @@ 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, so booleans, strings, and numbers should stay typed inside the JSON (`{"featured":true}`, `{"category":"react"}`, `{"rank":{"$gte":3}}`). Relation field values are reference objects, but relation filters use the target `documentId` string, for example `{"author":"750e..."}`; for to-many relations that means "contains this target document". Public Fimo-owned metadata lives under `__fimo`; currently `__fimo.contentType` is filterable. Operator objects support `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, and `$null`, subject to the field type. For to-many relations, `$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. Relation fields cannot be sorted. Use `--sort field` for ascending and `--sort -field` for descending on scalar fields.
+`--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`.
 
-`--populate` is a comma-separated list of relation fields to embed. Without `--populate`, relation fields return reference objects like `{ "documentId": "..." }`. With `--populate author,contributors`, those fields return the target entry objects for the requested locale. Only relation fields can be populated; asking to populate a scalar field returns 400.
+`--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).
+
+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.
 
 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.
 
-For relation schema JSON and entry value shape, load `fimo/references/content.md` § Relation fields. The short version:
+For reference schema JSON and entry value shape, load `fimo/references/content.md` § Reference fields. The short version:
 
 ```json
 {
   "fields": {
-    "author": { "type": "relation", "target": "Author" },
-    "contributors": { "type": "relation", "target": "Author", "many": true }
+    "author": { "type": "reference", "target": "Author" },
+    "contributors": { "type": "reference", "target": "Author", "many": true }
   }
 }
 ```
@@ -84,7 +88,7 @@ Entry bodies store reference objects with target `documentId` values:
 fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":{"documentId":"750e8400-e29b-41d4-a716-446655440000"},"contributors":[]}}'
 ```
 
-Do not add `localized` or field-level `i18n` to relation fields. The relation 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 that stores it.
 
 ## Localized and shared content
 
@@ -92,7 +96,7 @@ Schemas are localized by default. Omit `--locale` for default-locale entries. Pa
 
 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 relations 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. 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.
 
 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-migration/SKILL.md

@@ -97,7 +97,7 @@ node <this-skill>/scripts/write-migration-report.mjs <project-root>
 
 - `references/workflow.md` - full decision tree and phase order.
 - `references/manifest.md` - canonical migration ledger schema.
-- `references/content.md` - CMS, entries, relations, and source value rules.
+- `references/content.md` - CMS, entries, references, and source value rules.
 - `references/media.md` - media inventory, upload, dedupe, and replacement rules.
 - `references/forms.md` - form classification and Fimo replacement rules.
 - `references/import-contract.md` - exact import obligations for media, entries,

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

@@ -73,20 +73,20 @@ For every content type:
 Do not wire a page to remote Fimo content until the matching schema exists and
 the page has a seed/empty state for local development.
 
-## Relations
+## References
 
 Create references only when:
 
-- exports contain stable relation IDs
+- exports contain stable reference IDs
 - repeated values clearly match another exported collection
 - the user confirms the relationship
 
 Use a two-pass import for references:
 
 1. import all referenced entries with source IDs and slugs
-2. resolve relation fields to target IDs/slugs
+2. resolve reference fields to target IDs/slugs
 
-If relation confidence is low, keep a string/tag field and record an unresolved
+If reference confidence is low, keep a string/tag field and record an unresolved
 item.
 
 ## Skips

package/assets/skills/fimo-migration/references/import-contract.md

@@ -50,7 +50,7 @@ Import requirements:
 - entries are created or updated in Fimo, not only written as seed JSON
 - source count, generated count, imported count, skipped count, and unresolved
   count are recorded per content type
-- relations are resolved in a second pass only when stable IDs or confirmed
+- references are resolved in a second pass only when stable IDs or confirmed
   mappings exist
 
 Acceptance:

package/assets/skills/fimo-migration/references/manifest.md

@@ -80,7 +80,7 @@ than first-party CSV/XML/JSON exports.
     "coverImage": { "type": "media", "source": "Main Image" },
     "publishedAt": { "type": "datetime", "source": "Published On" }
   },
-  "relations": []
+  "references": []
 }
 ```