fimo 0.4.0-experimental.3 → 0.4.0-experimental.5

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

@@ -14,15 +14,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 +79,7 @@ if (model.fields) {
 <%
         }
         break;
-      case 'relation': {
+      case 'reference': {
         const wrapper = field.target === model.uid ? 'wrapWithSource' : `wrap${field.targetPascal}WithSource`;
         if (field.many) {
 -%>
@@ -119,7 +119,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 +131,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 +145,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 +154,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 +179,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 +189,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 +201,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 +283,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 +312,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 +345,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 +404,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

@@ -8,12 +8,12 @@
  */
 %>
 // 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 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 +30,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;
@@ -93,7 +93,7 @@ function getTypeForField(field) {
       return 'Record<string, any>';
     case 'media':
       return field.multiple ? 'FimoMedia[]' : 'FimoMedia';
-    case 'relation':
+    case 'reference':
       return field.many ? 'FimoReference[]' : 'FimoReference | null';
     default:
       return 'any';
@@ -118,7 +118,7 @@ function getInputTypeForField(field) {
       const media = 'Pick<FimoMedia, "url" | "alt" | "name" | "mime" | "width" | "height">';
       return field.multiple ? `${media}[]` : media;
     }
-    case 'relation':
+    case 'reference':
       return field.many ? 'FimoReference[]' : 'FimoReference | null';
     default:
       return 'unknown';
@@ -127,11 +127,11 @@ function getInputTypeForField(field) {
 -%>
 }
 
-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' || 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,27 +77,40 @@ 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" }]
   }
 }
 ```
 
+## 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:
+
+- 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.
+
+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.
+
 **Default to `richtext`** for fields named `body`, `content`, `description`, `summary`, `bio`, `intro`, `details`, `excerpt` — only use `string` when the field is explicitly short (e.g. a 160-char meta description).
 
 ## Tiptap JSONContent (richtext)
@@ -209,9 +222,9 @@ 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. Do not implement locale fallbacks by hand: reads accept an opt-in `localeFallbacks: true` option that resolves populated references missing in the requested locale to the best available variant (project default first), marked by its `locale` field. Public reads stay strict unless the option is passed.
 
 **Generated API:**
 
@@ -277,8 +290,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:
 
@@ -291,7 +304,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({
@@ -314,11 +327,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.
 
@@ -335,7 +348,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

@@ -9,8 +9,8 @@ This file covers the **CLI workflow** for content. Use it when the user wants to
 ## Flow
 
 1. Write `src/schemas/{Uid}.json` — PascalCase filename (e.g. `BlogPost.json`). For the JSON shape and field types, load `fimo/references/content.md`.
-2. Register the schema with `fimo schemas push {Uid}`.
-3. Pre-build generates `src/schemas/{Uid}.types.ts` and `src/schemas/{Uid}.ts` — type definitions plus typed React Query hooks. App code imports from `@/schemas/{Uid}`, not from `.types.ts` directly. See `fimo/references/content.md` for the hook API.
+2. Run `fimo schemas push {Uid}`. It generates `src/schemas/{Uid}.types.ts` and `src/schemas/{Uid}.ts`, then registers the schema with Fimo. It does not run whole-project validation.
+3. App code imports the generated client from `@/schemas/{Uid}`, not from `.types.ts` directly. See `fimo/references/content.md` for the hook API.
 4. Seed entries via `fimo entries create`. Generate cover images first with `fimo generate <model>` if needed (see `media.md` / `assets.md`).
 5. Write React pages that import from `@/schemas/{Uid}` and render with `fimo/ui` components.
 
@@ -29,6 +29,8 @@ 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.
+
 ## Entries CLI commands
 
 Entries are NOT JSON-file-driven. Create/update them via CLI.
@@ -58,20 +60,20 @@ 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, so booleans, strings, and numbers should stay typed inside the JSON (`{"featured":true}`, `{"category":"react"}`, `{"rank":{"$gte":3}}`). Reference field values are reference objects, but reference filters use the target `documentId` string, for example `{"author":"750e..."}`; for to-many references 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 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 `--sort field` for ascending and `--sort -field` for descending 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 `--populate`, 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; asking to populate a scalar field returns 400. Populated targets missing in the requested locale resolve to null by default; pass `localeFallbacks=true` (query param, or the `localeFallbacks` option in generated hooks) to fall back to the best available locale variant, marked by its `locale` field. Limits: a to-many field accepts at most 200 references per write; one populate request resolves at most 500 distinct target documents per field and returns 400 past that.
 
 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 }
   }
 }
 ```
@@ -82,7 +84,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
 
@@ -90,7 +92,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.
 
@@ -107,7 +109,7 @@ Use `"isSingleton": true` for a type with exactly one logical document. Generate
 
 ## When to run sync manually
 
-The `fimo/vite` plugin auto-regenerates `src/schemas/*.ts` on `vite dev` / `vite build`. If you need to regen outside vite (e.g. CI, scripting), use:
+`fimo schemas push`, `fimo validate`, and the `fimo/vite` plugin all reuse the same schema generator. `schemas push` does not run route, label, agent, form, or project-wide checks. For a full local validation and codegen pass without updating the remote schema, use:
 
 ```bash
 fimo validate                  # runs all phases: codegen, lint, route validation, label checks

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": []
 }
 ```
 

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

@@ -37,7 +37,7 @@ Use these notes to decide what is source of truth and what must be rebuilt.
 - Wix/Velo app logic, dynamic pages, search, forms, ecommerce, auth, and member
   areas need explicit replacement plans.
 - Large collections may be split across several files. Preserve stable IDs if
-  present so relations can be reconstructed later.
+  present so references can be reconstructed later.
 
 ## Carrd and static exports
 

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

@@ -85,7 +85,7 @@ Before writing page code:
 2. Map each CMS export or inferred collection to a Fimo schema or unresolved item.
 3. Preserve stable source IDs, slugs, dates, SEO, authors, categories, tags,
    locales, and publish status.
-4. Decide which relations are real. Do not invent references from vague text.
+4. Decide which references are real. Do not invent references from vague text.
 5. Build seed/import entries with source IDs and media references preserved.
 6. Record source count and planned import count for each content type.
 

package/assets/skills/fimo-migration/scripts/build-canonical-manifest.mjs

@@ -222,7 +222,7 @@ function normalizeSourceContentTypes(contentTypes) {
     plannedCount: numberOrNull(type.plannedCount),
     importedCount: numberOrNull(type.importedCount),
     fields: type.fields ?? {},
-    relations: type.relations ?? [],
+    references: type.references ?? [],
   }));
 }
 
@@ -240,7 +240,7 @@ function normalizeUrlCollections(collections) {
     plannedCount: asArray(collection.sourceRoutes).length,
     importedCount: 0,
     fields: Object.fromEntries(asArray(collection.fields).map((field) => [field, { source: field }])),
-    relations: [],
+    references: [],
     notes: ['Inferred from crawled route patterns. Review before import.'],
   }));
 }

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-10T13:57:48.782Z",
+  "bundledAt": "2026-07-11T15:31:56.826Z",
   "cliVersion": "0.3.6",
   "external": [
     "oxc-parser",

package/dist/cli/index.js

@@ -42008,7 +42008,7 @@ var init_common = __esm({
       "boolean",
       "date",
       "json",
-      "relation"
+      "reference"
     ]);
     RESERVED_CONTENT_FIELD_NAMES = [
       "id",
@@ -42152,6 +42152,36 @@ var init_realtime = __esm({
   }
 });
 
+// ../../packages/api-contracts/dist/esm/types/references.js
+function referenceDocumentId(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value && typeof value === "object" && "documentId" in value) {
+    const documentId = value.documentId;
+    return typeof documentId === "string" ? documentId : null;
+  }
+  return null;
+}
+function toReferenceValue(value) {
+  const documentId = referenceDocumentId(value);
+  return documentId ? {
+    documentId
+  } : null;
+}
+var ReferenceValueSchema;
+var init_references = __esm({
+  "../../packages/api-contracts/dist/esm/types/references.js"() {
+    "use strict";
+    init_zod();
+    __name(referenceDocumentId, "referenceDocumentId");
+    __name(toReferenceValue, "toReferenceValue");
+    ReferenceValueSchema = external_exports.preprocess((value) => toReferenceValue(value) ?? value, external_exports.object({
+      documentId: external_exports.uuid()
+    }));
+  }
+});
+
 // ../../packages/api-contracts/dist/esm/types/audit-log.js
 var AUDIT_ACTIONS, AuditActionSchema, AUDIT_OUTCOMES, AuditOutcomeSchema, AUDIT_ACTOR_KINDS, AuditActorKindSchema;
 var init_audit_log = __esm({
@@ -45513,6 +45543,7 @@ var init_esm = __esm({
     init_attachments();
     init_env2();
     init_realtime();
+    init_references();
     init_audit_log();
     init_project_dto();
     init_project_env_dto();
@@ -47120,10 +47151,10 @@ function normalizeFields(fields) {
     })
   );
 }
-function relationImportsFor(schema, fields) {
+function referenceImportsFor(schema, fields) {
   const imports = /* @__PURE__ */ new Map();
   for (const field of Object.values(fields)) {
-    if (field.type !== "relation" || !field.target || field.target === schema.uid) {
+    if (field.type !== "reference" || !field.target || field.target === schema.uid) {
       continue;
     }
     imports.set(field.target, { uid: field.target, pascal: pascalCase(field.target) });
@@ -47137,9 +47168,9 @@ function schemaToModel(schema, localizedByUid) {
     pascal: pascalCase(schema.uid),
     isSingleton: schema.isSingleton ?? false,
     localized: schema.i18n?.enabled !== false,
-    localizedRelationFields: Object.entries(fields).filter(([, field]) => field.type === "relation" && field.target && localizedByUid.get(field.target) !== false).map(([fieldName]) => fieldName),
+    localizedReferenceFields: Object.entries(fields).filter(([, field]) => field.type === "reference" && field.target && localizedByUid.get(field.target) !== false).map(([fieldName]) => fieldName),
     fields,
-    relationImports: relationImportsFor(schema, fields)
+    referenceImports: referenceImportsFor(schema, fields)
   };
 }
 function syncSchemas(options = {}) {
@@ -47246,7 +47277,7 @@ var init_sync_schemas = __esm({
     __name(getSchemaFiles, "getSchemaFiles");
     __name(readSchema, "readSchema");
     __name(normalizeFields, "normalizeFields");
-    __name(relationImportsFor, "relationImportsFor");
+    __name(referenceImportsFor, "referenceImportsFor");
     __name(schemaToModel, "schemaToModel");
     __name(syncSchemas, "syncSchemas");
   }
@@ -103088,34 +103119,34 @@ function validateSchemaFile(absolutePath, file2, schemaUids = /* @__PURE__ */ ne
         file: file2
       });
     }
-    if (type === "relation") {
+    if (type === "reference") {
       const { target, many } = definition;
       if (typeof target !== "string" || !CONTENT_TYPE_NAME_PATTERN.test(target)) {
         errors2.push({
-          rule: "schemas/relation-target",
-          message: `Relation field "${fieldName}" must declare a valid "target" content type.`,
+          rule: "schemas/reference-target",
+          message: `Reference field "${fieldName}" must declare a valid "target" content type.`,
           file: file2
         });
       } else if (schemaUids.size > 0 && !schemaUids.has(target)) {
         errors2.push({
-          rule: "schemas/relation-target",
-          message: `Relation field "${fieldName}" targets unknown schema "${target}".`,
+          rule: "schemas/reference-target",
+          message: `Reference field "${fieldName}" targets unknown schema "${target}".`,
           file: file2
         });
       }
       if (many !== void 0 && typeof many !== "boolean") {
         errors2.push({
-          rule: "schemas/relation-many",
-          message: `Relation field "${fieldName}" must use a boolean "many" value.`,
+          rule: "schemas/reference-many",
+          message: `Reference field "${fieldName}" must use a boolean "many" value.`,
           file: file2
         });
       }
     } else {
-      for (const relationOnlyKey of ["target", "many"]) {
-        if (relationOnlyKey in definition) {
+      for (const referenceOnlyKey of ["target", "many"]) {
+        if (referenceOnlyKey in definition) {
           errors2.push({
-            rule: "schemas/relation-shape",
-            message: `Field "${fieldName}": "${relationOnlyKey}" is only supported on relation fields.`,
+            rule: "schemas/reference-shape",
+            message: `Field "${fieldName}": "${referenceOnlyKey}" is only supported on reference fields.`,
             file: file2
           });
         }
@@ -104893,8 +104924,8 @@ function fieldSignature(field) {
   const type = typeof f.type === "string" ? f.type : "unknown";
   const required2 = f.required === true;
   const parts = [];
-  if (type === "relation" && typeof f.target === "string") {
-    parts.push(`relation(${f.target})`);
+  if (type === "reference" && typeof f.target === "string") {
+    parts.push(`reference(${f.target})`);
   } else if (type === "enum" && Array.isArray(f.options)) {
     parts.push(`enum(${f.options.map(String).join("|")})`);
   } else if (type === "number") {
@@ -109678,6 +109709,7 @@ __name(deleteCommand, "deleteCommand");
 
 // src/cli/commands/schema.ts
 init_dist();
+init_sync_schemas();
 import fs42 from "node:fs";
 import path46 from "node:path";
 init_api();
@@ -109732,8 +109764,7 @@ async function schemaPushCommand(typeName, options, cmd) {
       }
     })
   );
-  const results = [];
-  for (const file2 of files) {
+  const schemas3 = files.map((file2) => {
     const filePath = path46.join(schemasDir, file2);
     if (!fs42.existsSync(filePath)) {
       throw new Error(`Schema file not found: ${filePath}`);
@@ -109742,7 +109773,11 @@ async function schemaPushCommand(typeName, options, cmd) {
     if (issues.length > 0) {
       throw new Error(issues.map((issue2) => `${issue2.file}: ${issue2.message}`).join("\n"));
     }
-    const schema = JSON.parse(fs42.readFileSync(filePath, "utf-8"));
+    return JSON.parse(fs42.readFileSync(filePath, "utf-8"));
+  });
+  syncSchemas({ cwd, verbose: false });
+  const results = [];
+  for (const schema of schemas3) {
     const contentType = toApiShape(schema);
     try {
       const result = await api.createSchema(ctx.projectId, contentType);
@@ -110192,7 +110227,7 @@ schemas2.command("get").description("Get a schema by type name").argument("<type
 schemas2.command("push").description("Push schema JSON files to the API (create or update)").argument("[typeName]", "Schema name to push (omit to push all)").option("-C, --cwd <dir>", "Project directory").action(schemaPushCommand);
 schemas2.command("delete").description("Delete a schema by type name").argument("<typeName>", "Content type name").option("-C, --cwd <dir>", "Project directory").action(schemaDeleteCommand);
 var entries = program.command("entries").description("Manage content entries");
-entries.command("list").description("List entries of a content type").argument("<typeName>", "Content type name").option("-C, --cwd <dir>", "Project directory").option("--limit <n>", "Max entries to return").option("--offset <n>", "Offset for pagination").option("--search <query>", "Search query").option("--where <json>", `JSON filter object, e.g. '{"featured":true}'`).option("--sort <field>", "Sort field, prefix with - for descending").option("--fields <fields>", "Comma-separated fields to return, e.g. slug,title,excerpt").option("--populate <fields>", "Comma-separated relation fields to populate, e.g. author,contributors").option("--locale <locale>", "Locale to list (default en)").option("--sort-by <field>", "Sort field").option("--sort-direction <dir>", "Sort direction (asc|desc)").action(entriesListCommand);
+entries.command("list").description("List entries of a content type").argument("<typeName>", "Content type name").option("-C, --cwd <dir>", "Project directory").option("--limit <n>", "Max entries to return").option("--offset <n>", "Offset for pagination").option("--search <query>", "Search query").option("--where <json>", `JSON filter object, e.g. '{"featured":true}'`).option("--sort <field>", "Sort field, prefix with - for descending").option("--fields <fields>", "Comma-separated fields to return, e.g. slug,title,excerpt").option("--populate <fields>", "Comma-separated reference fields to populate, e.g. author,contributors").option("--locale <locale>", "Locale to list (default en)").option("--sort-by <field>", "Sort field").option("--sort-direction <dir>", "Sort direction (asc|desc)").action(entriesListCommand);
 entries.command("get").description("Get a single entry").argument("<typeName>", "Content type name").argument("<id>", "Entry ID").option("-C, --cwd <dir>", "Project directory").option("--locale <locale>", "Locale to read (default en)").action(entriesGetCommand);
 entries.command("create").description("Create a new entry").argument("<typeName>", "Content type name").option("-C, --cwd <dir>", "Project directory").requiredOption("--body <json>", "Entry JSON body (slug + data)").option("--locale <locale>", "Entry locale (default en)").option("--document-id <id>", "Document ID shared by localized variants").action(entriesCreateCommand);
 entries.command("update").description("Update an existing entry").argument("<typeName>", "Content type name").argument("<id>", "Entry ID").option("-C, --cwd <dir>", "Project directory").requiredOption("--body <json>", "Updated entry JSON body").option("--locale <locale>", "Entry locale").option("--document-id <id>", "Document ID shared by localized variants").action(entriesUpdateCommand);

package/dist/runtime/primitives/index.d.ts

@@ -7,5 +7,5 @@ export { Boolean } from './components/Boolean.js';
 export { RichText } from './components/RichText.js';
 export { useLabels, useTranslations } from './translations.js';
 export { FimoString, FimoDate, FimoMedia, FimoBoolean, FimoRichText, type FimoReference, type FimoSource, type FimoPart, type FimoRichTextContent, type FimoRichTextNodeProps, type FimoRichTextMarkProps, type FimoRichTextComponents, FIMO_SOURCE, FIMO_PARTS, isFimoString, isFimoDate, hasFimoSource, getFimoSource, getFimoParts, fimo, useFimoLiveValue, } from './lib/index.js';
-export type { BoolOps, DateOps, Field, Fields, FilterFor, NullOnlyOps, NumberOps, Populate, Populated, PopulatedResult, Projected, ProjectedWithPopulate, Query, RelationField, RelationMap, ScalarOps, Sort, SortField, StringOps, WithRelations, Where, } from './lib/index.js';
+export type { BoolOps, DateOps, Field, Fields, FilterFor, NullOnlyOps, NumberOps, Populate, Populated, PopulatedResult, Projected, ProjectedWithPopulate, Query, ReferenceField, ReferenceMap, ScalarOps, Sort, SortField, StringOps, WithReferences, Where, } from './lib/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/primitives/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/primitives/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAGpD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAG/D,OAAO,EACL,UAAU,EACV,QAAQ,EACR,SAAS,EACT,WAAW,EACX,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,WAAW,EACX,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,IAAI,EACJ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,OAAO,EACP,OAAO,EACP,KAAK,EACL,MAAM,EACN,SAAS,EACT,WAAW,EACX,SAAS,EACT,QAAQ,EACR,SAAS,EACT,eAAe,EACf,SAAS,EACT,qBAAqB,EACrB,KAAK,EACL,aAAa,EACb,WAAW,EACX,SAAS,EACT,IAAI,EACJ,SAAS,EACT,SAAS,EACT,aAAa,EACb,KAAK,GACN,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/primitives/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAGpD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAG/D,OAAO,EACL,UAAU,EACV,QAAQ,EACR,SAAS,EACT,WAAW,EACX,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,WAAW,EACX,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,IAAI,EACJ,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AAExB,YAAY,EACV,OAAO,EACP,OAAO,EACP,KAAK,EACL,MAAM,EACN,SAAS,EACT,WAAW,EACX,SAAS,EACT,QAAQ,EACR,SAAS,EACT,eAAe,EACf,SAAS,EACT,qBAAqB,EACrB,KAAK,EACL,cAAc,EACd,YAAY,EACZ,SAAS,EACT,IAAI,EACJ,SAAS,EACT,SAAS,EACT,cAAc,EACd,KAAK,GACN,MAAM,gBAAgB,CAAC"}

package/dist/runtime/primitives/lib/index.d.ts

@@ -1,5 +1,5 @@
 export { FimoString, FimoDate, FimoMedia, FimoBoolean, FimoRichText, type FimoReference, type FimoSource, type FimoPart, type FimoRichTextContent, type FimoRichTextNodeProps, type FimoRichTextMarkProps, type FimoRichTextComponents, FIMO_SOURCE, FIMO_PARTS, isFimoString, isFimoDate, hasFimoSource, getFimoSource, getFimoParts, } from './primitives.js';
 export { fimo } from './template.js';
 export { useFimoLiveValue } from './useFimoLiveValue.js';
-export type { BoolOps, DateOps, Field, Fields, FilterFor, NullOnlyOps, NumberOps, Populate, Populated, PopulatedResult, ProjectedWithPopulate, Projected, Query, RelationField, RelationMap, ScalarOps, Sort, SortField, StringOps, Where, WithRelations, } from './query.js';
+export type { BoolOps, DateOps, Field, Fields, FilterFor, NullOnlyOps, NumberOps, Populate, Populated, PopulatedResult, ProjectedWithPopulate, Projected, Query, ReferenceField, ReferenceMap, ScalarOps, Sort, SortField, StringOps, Where, WithReferences, } from './query.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/primitives/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/runtime/primitives/lib/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,UAAU,EACV,QAAQ,EACR,SAAS,EACT,WAAW,EACX,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,WAAW,EACX,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAErC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,YAAY,EACV,OAAO,EACP,OAAO,EACP,KAAK,EACL,MAAM,EACN,SAAS,EACT,WAAW,EACX,SAAS,EACT,QAAQ,EACR,SAAS,EACT,eAAe,EACf,qBAAqB,EACrB,SAAS,EACT,KAAK,EACL,aAAa,EACb,WAAW,EACX,SAAS,EACT,IAAI,EACJ,SAAS,EACT,SAAS,EACT,KAAK,EACL,aAAa,GACd,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/runtime/primitives/lib/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,UAAU,EACV,QAAQ,EACR,SAAS,EACT,WAAW,EACX,YAAY,EACZ,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,mBAAmB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,WAAW,EACX,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,aAAa,EACb,YAAY,GACb,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAErC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,YAAY,EACV,OAAO,EACP,OAAO,EACP,KAAK,EACL,MAAM,EACN,SAAS,EACT,WAAW,EACX,SAAS,EACT,QAAQ,EACR,SAAS,EACT,eAAe,EACf,qBAAqB,EACrB,SAAS,EACT,KAAK,EACL,cAAc,EACd,YAAY,EACZ,SAAS,EACT,IAAI,EACJ,SAAS,EACT,SAAS,EACT,KAAK,EACL,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/runtime/primitives/lib/query.d.ts

@@ -25,21 +25,22 @@ export type BoolOps = ScalarOps<boolean>;
 export type NullOnlyOps = {
     $null?: boolean;
 };
-export type RelationOps = {
+export type ReferenceOps = {
     $eq?: string | null;
     $ne?: string | null;
     $in?: string[];
     $nin?: string[];
-    $contains?: string;
     $null?: boolean;
 };
-export type ManyRelationOps = {
+export type ManyReferenceOps = {
     $eq?: string;
     $ne?: string;
+    $in?: string[];
+    $nin?: string[];
     $contains?: string;
     $null?: boolean;
 };
-export type FilterFor<T> = [T] extends [FimoString | string] ? string | StringOps : [T] extends [FimoBoolean | boolean] ? boolean | BoolOps : [T] extends [FimoDate | Date] ? string | DateOps : [T] extends [number] ? number | NumberOps : [T] extends [FimoReference | null] ? string | null | RelationOps : [T] extends [FimoReference[]] ? string | ManyRelationOps : [T] extends [FimoMedia | FimoMedia[]] ? NullOnlyOps : [T] extends [FimoRichText] ? string | StringOps : NullOnlyOps;
+export type FilterFor<T> = [T] extends [FimoString | string] ? string | StringOps : [T] extends [FimoBoolean | boolean] ? boolean | BoolOps : [T] extends [FimoDate | Date] ? string | DateOps : [T] extends [number] ? number | NumberOps : [T] extends [FimoReference | null] ? string | null | ReferenceOps : [T] extends [FimoReference[]] ? string | ManyReferenceOps : [T] extends [FimoMedia | FimoMedia[]] ? NullOnlyOps : [T] extends [FimoRichText] ? string | StringOps : NullOnlyOps;
 type BaseTopLevelWhere = {
     id?: string | StringOps;
     documentId?: string | StringOps;
@@ -68,18 +69,18 @@ type ListItem<TValue> = TValue extends readonly (infer K)[] ? K : TValue;
 export type Projected<T extends {
     id: string;
 }, TFields extends Fields<T> | undefined> = [TFields] extends [undefined] ? T : Pick<T, Extract<'id' | SelectedFields<TFields>, keyof T>>;
-export declare const FIMO_RELATIONS: unique symbol;
-export interface WithRelations<TRelations> {
-    readonly [FIMO_RELATIONS]?: TRelations;
+export declare const FIMO_REFERENCES: unique symbol;
+export interface WithReferences<TReferences> {
+    readonly [FIMO_REFERENCES]?: TReferences;
 }
-export type RelationMap<TEntry> = TEntry extends WithRelations<infer TRelations> ? TRelations : never;
-export type RelationField<TEntry> = Extract<keyof RelationMap<TEntry>, string>;
-export type Populate<TEntry> = RelationField<TEntry> | readonly RelationField<TEntry>[];
-type PopulatedKeys<TEntry, TPopulate> = Extract<ListItem<TPopulate>, keyof RelationMap<TEntry> & keyof TEntry>;
+export type ReferenceMap<TEntry> = TEntry extends WithReferences<infer TReferences> ? TReferences : never;
+export type ReferenceField<TEntry> = Extract<keyof ReferenceMap<TEntry>, string>;
+export type Populate<TEntry> = ReferenceField<TEntry> | readonly ReferenceField<TEntry>[];
+type PopulatedKeys<TEntry, TPopulate> = Extract<ListItem<TPopulate>, keyof ReferenceMap<TEntry> & keyof TEntry>;
 export type Populated<TEntry extends {
     id: string;
 }, TPopulate extends Populate<TEntry>> = Pick<TEntry, 'id'> & Omit<TEntry, PopulatedKeys<TEntry, TPopulate>> & {
-    [K in PopulatedKeys<TEntry, TPopulate>]: RelationMap<TEntry>[K];
+    [K in PopulatedKeys<TEntry, TPopulate>]: ReferenceMap<TEntry>[K];
 };
 export type PopulatedResult<TEntry extends {
     id: string;

package/dist/runtime/primitives/lib/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../../src/runtime/primitives/lib/query.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../../src/runtime/primitives/lib/query.ts"],"names":[],"mappings":"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"}

package/dist/runtime/primitives/public-surface.test.js

@@ -16,11 +16,11 @@ describe('fimo/ui public type surface', () => {
         const sharedWhere = { locale: 'en' };
         expectTypeOf(sharedWhere).toEqualTypeOf();
     });
-    it('supports the relation populate pattern emitted into generated schemas', () => {
+    it('supports the reference populate pattern emitted into generated schemas', () => {
         const query = {
             where: {
-                sponsor: { $eq: '750e8400-e29b-41d4-a716-446655440000' },
-                relatedPackages: { $contains: '850e8400-e29b-41d4-a716-446655440000' },
+                sponsor: { $in: ['750e8400-e29b-41d4-a716-446655440000'] },
+                relatedPackages: { $nin: ['850e8400-e29b-41d4-a716-446655440000'] },
             },
             fields: ['name'],
             populate: ['sponsor'],
@@ -32,11 +32,14 @@ describe('fimo/ui public type surface', () => {
         expectTypeOf().toEqualTypeOf();
         expectTypeOf().toEqualTypeOf();
         expectTypeOf().toEqualTypeOf();
-        // @ts-expect-error generated relation-aware queries only allow relation fields in populate.
+        // @ts-expect-error generated reference-aware queries only allow reference fields in populate.
         const badQuery = { populate: 'name' };
         expectTypeOf(badQuery).toEqualTypeOf();
-        // @ts-expect-error relation filters use target documentId strings, not raw reference objects.
+        // @ts-expect-error reference filters use target documentId strings, not raw reference objects.
         const badWhere = { where: { sponsor: { documentId: '750e8400-e29b-41d4-a716-446655440000' } } };
         expectTypeOf(badWhere).toEqualTypeOf();
+        // @ts-expect-error contains is only valid for to-many reference fields.
+        const badToOneContains = { where: { sponsor: { $contains: '750e8400-e29b-41d4-a716-446655440000' } } };
+        expectTypeOf(badToOneContains).toEqualTypeOf();
     });
 });

package/dist/scripts/sync-schemas.js

@@ -48,10 +48,10 @@ function normalizeFields(fields) {
         ];
     }));
 }
-function relationImportsFor(schema, fields) {
+function referenceImportsFor(schema, fields) {
     const imports = new Map();
     for (const field of Object.values(fields)) {
-        if (field.type !== 'relation' || !field.target || field.target === schema.uid) {
+        if (field.type !== 'reference' || !field.target || field.target === schema.uid) {
             continue;
         }
         imports.set(field.target, { uid: field.target, pascal: pascalCase(field.target) });
@@ -65,11 +65,11 @@ function schemaToModel(schema, localizedByUid) {
         pascal: pascalCase(schema.uid),
         isSingleton: schema.isSingleton ?? false,
         localized: schema.i18n?.enabled !== false,
-        localizedRelationFields: Object.entries(fields)
-            .filter(([, field]) => field.type === 'relation' && field.target && localizedByUid.get(field.target) !== false)
+        localizedReferenceFields: Object.entries(fields)
+            .filter(([, field]) => field.type === 'reference' && field.target && localizedByUid.get(field.target) !== false)
             .map(([fieldName]) => fieldName),
         fields,
-        relationImports: relationImportsFor(schema, fields),
+        referenceImports: referenceImportsFor(schema, fields),
     };
 }
 export function syncSchemas(options = {}) {

package/dist/scripts/sync-schemas.test.js

@@ -15,7 +15,7 @@ function writeSchema(name, schema) {
     writeFileSync(join(scratch, 'src/schemas', `${name}.json`), JSON.stringify(schema, null, 2));
 }
 describe('syncSchemas', () => {
-    it('generates raw relation references plus typed populated relation helpers', () => {
+    it('generates raw references plus typed populated helpers', () => {
         writeSchema('Author', {
             uid: 'Author',
             name: 'Authors',
@@ -28,9 +28,9 @@ describe('syncSchemas', () => {
             name: 'Posts',
             fields: {
                 title: { type: 'string' },
-                author: { type: 'relation', target: 'Author' },
-                contributors: { type: 'relation', target: 'Author', many: true },
-                relatedPosts: { type: 'relation', target: 'Post', many: true },
+                author: { type: 'reference', target: 'Author' },
+                contributors: { type: 'reference', target: 'Author', many: true },
+                relatedPosts: { type: 'reference', target: 'Post', many: true },
             },
         });
         expect(syncSchemas({ cwd: scratch, verbose: false })).toEqual({ created: 4, updated: 0, deleted: 0 });
@@ -40,7 +40,7 @@ describe('syncSchemas', () => {
         expect(post).toContain('import type { Post, PostInput, PostPopulate, PostResult, PostFields, PostQuery } from "./Post.types";');
         expect(post).toContain('from "./Post.types";');
         expect(post).not.toContain('import type { Author } from "./Author";');
-        expect(post).not.toContain('export interface Post extends WithRelations<PostRelations>');
+        expect(post).not.toContain('export interface Post extends WithReferences<PostReferences>');
         expect(post).not.toContain('type FimoReference');
         expect(post).toContain('Promise<PostResult<undefined, TPopulate>>');
         expect(post).toContain('TPopulate extends PostPopulate | undefined');
@@ -49,12 +49,12 @@ describe('syncSchemas', () => {
         expect(post).toContain('export async function create(payload: PostInput): Promise<Post>');
         expect(post).toContain('return wrapWithSource(data.data);');
         expect(postTypes).toContain('import type { Author } from "./Author.types";');
-        expect(postTypes).toContain('export interface Post extends WithRelations<PostRelations>');
+        expect(postTypes).toContain('export interface Post extends WithReferences<PostReferences>');
         expect(postTypes).toContain('type FimoReference');
         expect(postTypes).toContain('author: FimoReference | null;');
         expect(postTypes).toContain('contributors: FimoReference[];');
         expect(postTypes).toContain('relatedPosts: FimoReference[];');
-        expect(postTypes).toContain('export interface PostRelations');
+        expect(postTypes).toContain('export interface PostReferences');
         expect(postTypes).toContain('export interface PostInput');
         expect(postTypes).toContain('author?: FimoReference | null;');
         expect(postTypes).toContain('author: Author | null;');
@@ -80,8 +80,8 @@ describe('syncSchemas', () => {
             name: 'Settings',
             i18n: { enabled: false },
             fields: {
-                homepage: { type: 'relation', target: 'Homepage' },
-                category: { type: 'relation', target: 'Category' },
+                homepage: { type: 'reference', target: 'Homepage' },
+                category: { type: 'reference', target: 'Category' },
             },
         });
         syncSchemas({ cwd: scratch, verbose: false });
@@ -92,7 +92,7 @@ describe('syncSchemas', () => {
         expect(settingsTypes).not.toContain('locale?: string;');
         expect(homepageTypes).toContain('locale: string;');
         expect(settings).toContain('const LOCALIZED_CONTENT = false;');
-        expect(settings).toContain('const LOCALIZED_RELATION_FIELDS = new Set<string>(["homepage"]);');
+        expect(settings).toContain('const LOCALIZED_REFERENCE_FIELDS = new Set<string>(["homepage"]);');
         expect(settings).not.toContain('    locale: entry.locale,');
         expect(settings).toContain('readLocale(params, LOCALIZED_CONTENT, useQueryLocale(params.locale))');
         expect(settings.match(/readLocale\(params, LOCALIZED_CONTENT, useQueryLocale\(params\.locale\)\)/g)?.length).toBe(2);

package/dist/scripts/validate-schemas.js

@@ -169,36 +169,36 @@ export function validateSchemaFile(absolutePath, file, schemaUids = new Set()) {
                 file,
             });
         }
-        if (type === 'relation') {
+        if (type === 'reference') {
             const { target, many } = definition;
             if (typeof target !== 'string' || !CONTENT_TYPE_NAME_PATTERN.test(target)) {
                 errors.push({
-                    rule: 'schemas/relation-target',
-                    message: `Relation field "${fieldName}" must declare a valid "target" content type.`,
+                    rule: 'schemas/reference-target',
+                    message: `Reference field "${fieldName}" must declare a valid "target" content type.`,
                     file,
                 });
             }
             else if (schemaUids.size > 0 && !schemaUids.has(target)) {
                 errors.push({
-                    rule: 'schemas/relation-target',
-                    message: `Relation field "${fieldName}" targets unknown schema "${target}".`,
+                    rule: 'schemas/reference-target',
+                    message: `Reference field "${fieldName}" targets unknown schema "${target}".`,
                     file,
                 });
             }
             if (many !== undefined && typeof many !== 'boolean') {
                 errors.push({
-                    rule: 'schemas/relation-many',
-                    message: `Relation field "${fieldName}" must use a boolean "many" value.`,
+                    rule: 'schemas/reference-many',
+                    message: `Reference field "${fieldName}" must use a boolean "many" value.`,
                     file,
                 });
             }
         }
         else {
-            for (const relationOnlyKey of ['target', 'many']) {
-                if (relationOnlyKey in definition) {
+            for (const referenceOnlyKey of ['target', 'many']) {
+                if (referenceOnlyKey in definition) {
                     errors.push({
-                        rule: 'schemas/relation-shape',
-                        message: `Field "${fieldName}": "${relationOnlyKey}" is only supported on relation fields.`,
+                        rule: 'schemas/reference-shape',
+                        message: `Field "${fieldName}": "${referenceOnlyKey}" is only supported on reference fields.`,
                         file,
                     });
                 }

package/dist/scripts/validate-schemas.test.js

@@ -36,20 +36,20 @@ describe('validateSchemas', () => {
                     body: { type: 'richtext' },
                     coverImage: { type: 'media' },
                     featured: { type: 'boolean' },
-                    author: { type: 'relation', target: 'Author' },
+                    author: { type: 'reference', target: 'Author' },
                 },
             },
         });
         expect(validateSchemas({ cwd })).toEqual({ errors: [], schemasChecked: 2 });
     });
-    it('accepts self-referential relation fields', () => {
+    it('accepts self-referential reference fields', () => {
         const cwd = writeProject({
             'Item.json': {
                 uid: 'Item',
                 name: 'Items',
                 fields: {
                     title: { type: 'string' },
-                    parent: { type: 'relation', target: 'Item' },
+                    parent: { type: 'reference', target: 'Item' },
                 },
             },
         });
@@ -141,32 +141,32 @@ describe('validateSchemas', () => {
         expect(errors[0].message).toContain('"decimal"');
         expect(errors[0].message).toContain('string, richtext, media');
     });
-    it('rejects relation fields without a valid target', () => {
+    it('rejects reference fields without a valid target', () => {
         const cwd = writeProject({
             'Post.json': {
                 uid: 'Post',
                 name: 'Posts',
-                fields: { author: { type: 'relation' } },
+                fields: { author: { type: 'reference' } },
             },
         });
         const { errors } = validateSchemas({ cwd });
         expect(errors).toHaveLength(1);
-        expect(errors[0]).toMatchObject({ rule: 'schemas/relation-target' });
+        expect(errors[0]).toMatchObject({ rule: 'schemas/reference-target' });
     });
-    it('rejects relation fields targeting a missing local schema', () => {
+    it('rejects reference fields targeting a missing local schema', () => {
         const cwd = writeProject({
             'Post.json': {
                 uid: 'Post',
                 name: 'Posts',
-                fields: { author: { type: 'relation', target: 'Author' } },
+                fields: { author: { type: 'reference', target: 'Author' } },
             },
         });
         const { errors } = validateSchemas({ cwd });
         expect(errors).toHaveLength(1);
-        expect(errors[0]).toMatchObject({ rule: 'schemas/relation-target' });
+        expect(errors[0]).toMatchObject({ rule: 'schemas/reference-target' });
         expect(errors[0].message).toContain('unknown schema "Author"');
     });
-    it('rejects relation-only properties on scalar fields', () => {
+    it('rejects reference-only properties on scalar fields', () => {
         const cwd = writeProject({
             'Post.json': {
                 uid: 'Post',
@@ -176,7 +176,7 @@ describe('validateSchemas', () => {
         });
         const { errors } = validateSchemas({ cwd });
         expect(errors).toHaveLength(1);
-        expect(errors[0]).toMatchObject({ rule: 'schemas/relation-shape' });
+        expect(errors[0]).toMatchObject({ rule: 'schemas/reference-shape' });
     });
     it('rejects schema uid names that cannot be used as content type identifiers', () => {
         const cwd = writeProject({
@@ -214,12 +214,12 @@ describe('validateSchemas', () => {
         expect(errors).toHaveLength(1);
         expect(errors[0]).toMatchObject({ rule: 'schemas/field-i18n' });
     });
-    it('rejects relation-level locale settings', () => {
+    it('rejects reference-level locale settings', () => {
         const cwd = writeProject({
             'Page.json': {
                 uid: 'Page',
                 name: 'Pages',
-                fields: { parent: { type: 'relation', target: 'Page', localized: true } },
+                fields: { parent: { type: 'reference', target: 'Page', localized: true } },
             },
         });
         const { errors } = validateSchemas({ cwd });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fimo",
-  "version": "0.4.0-experimental.3",
+  "version": "0.4.0-experimental.5",
   "description": "Fimo CLI - create, deploy, and manage Fimo projects",
   "bin": {
     "fimo": "dist/cli/index.js"

package/templates/react-router/package.json

@@ -21,7 +21,7 @@
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "fimo": "0.4.0-experimental.3",
+    "fimo": "0.4.0-experimental.5",
     "input-otp": "^1.4.2",
     "isbot": "^5",
     "lucide-react": "^0.577.0",