fimo 0.4.0-experimental.2 → 0.4.0-experimental.4

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

@@ -10,6 +10,7 @@ This file covers the **package surface**: the JSON shape you write, the generate
 {
   "uid": "BlogPost",
   "name": "Blog Posts",
+  "i18n": { "enabled": true },
   "fields": {
     "title": { "type": "string" },
     "body": { "type": "richtext" },
@@ -25,6 +26,8 @@ This file covers the **package surface**: the JSON shape you write, the generate
 
 **Required**: `uid` (PascalCase, matches filename), `name`, `fields`.
 
+`i18n` is an optional type-level policy. Omit it or use `{ "enabled": true }` for localized content. Use `{ "enabled": false }` for one shared entry that appears in every locale, such as an Author, Category, or Settings type. No other `i18n` keys and no field-level localization settings are supported.
+
 ### Reserved field names — do NOT declare these in `fields`
 
 Every entry already carries this metadata automatically. Declaring any of them as a
@@ -33,6 +36,8 @@ reserved entry metadata and cannot be used as a content field.`):
 
 `id`, `documentId`, `slug`, `locale`, `createdAt`, `updatedAt`, `__fimo`.
 
+Localized entries expose `locale`; non-localized entries omit it. It remains reserved in both schemas.
+
 In particular **do not add a `slug` field** — every entry gets a `slug` for free. You still
 pass `slug` inside `data` when _creating an entry_ (see "Entry body shape" below); it just
 must not appear in the schema's `fields`. If you need an additional URL-ish string, name it
@@ -40,16 +45,16 @@ something else (e.g. `handle`, `permalink`).
 
 ## Field types
 
-| Type       | `data` JSON shape                                                       | Use for                           |
-| ---------- | ----------------------------------------------------------------------- | --------------------------------- |
-| `string`   | `"..."`                                                                 | Titles, short text                |
-| `richtext` | Tiptap JSONContent (see below)                                          | Blog body, descriptions, articles |
-| `number`   | `42`                                                                    | Counts, quantities                |
-| `boolean`  | `true` / `false`                                                        | Flags                             |
-| `date`     | ISO date string, e.g. `"2026-06-03"`                                    | Publish dates, timestamps         |
-| `media`    | `{ "source": "local"\|"external", "url": "https://...", "alt": "..." }` | Images, video                     |
-| `json`     | any JSON                                                                | Structured metadata               |
-| `relation` | document ID string, `null`, or document ID array 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               |
+| `relation` | `{ "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.
 
@@ -74,7 +79,10 @@ 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" }`.
-- Entry values store target `documentId` values, not row `id` values. Use `null` for an empty to-one relation and `[]` for an empty to-many relation.
+- 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.
 
 Entry payload example:
@@ -84,12 +92,25 @@ Entry payload example:
   "data": {
     "slug": "relation-example",
     "title": "Relation example",
-    "author": "750e8400-e29b-41d4-a716-446655440000",
-    "contributors": ["750e8400-e29b-41d4-a716-446655440000"]
+    "author": { "documentId": "750e8400-e29b-41d4-a716-446655440000" },
+    "contributors": [{ "documentId": "750e8400-e29b-41d4-a716-446655440000" }]
   }
 }
 ```
 
+## Schema transitions
+
+After editing schema JSON, run `fimo schemas push {Uid}` and then `fimo validate`. Push regenerates the schema client and applies the schema change to stored content automatically:
+
+- 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.
+- 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)
@@ -159,7 +180,12 @@ For `media` fields, prefer `source: "local"` with assets uploaded via `fimo asse
 
 ## Generated React Query hooks
 
-After pre-build (or `fimo deploy`), `src/schemas/{Uid}.ts` exports typed helpers. Import each schema from its own module, e.g. `import { useGet } from '@/schemas/BlogPost'` — there is no generated `src/schemas/index.ts` barrel.
+After pre-build (or `fimo deploy`), each schema generates two files:
+
+- `src/schemas/{Uid}.types.ts` — pure TypeScript types such as `BlogPost`, `BlogPostInput`, `BlogPostQuery`, and `BlogPostResult`.
+- `src/schemas/{Uid}.ts` — runtime helpers, React Query hooks, default export, and re-exported public types.
+
+Import from the public schema module, e.g. `import BlogPost from '@/schemas/BlogPost'` and `import type { BlogPostResult } from '@/schemas/BlogPost'`. Do not import from `.types.ts` directly in app code. There is no generated `src/schemas/index.ts` barrel.
 
 **Entity shape — fields live at the top level of the entry**, not under a nested `data` key. The generated `BlogPost` interface looks like:
 
@@ -168,7 +194,7 @@ interface BlogPost {
   id: string;
   documentId: string;
   slug: FimoString;
-  locale: string;
+  locale: string; // localized schemas only; omitted when i18n.enabled is false
   createdAt: string;
   updatedAt: string;
   __fimo: {
@@ -185,35 +211,56 @@ interface BlogPost {
 
 Content fields live at the top level. Fimo-owned metadata that is not part of the user schema lives under `__fimo`, so a schema can safely define fields named `contentType`.
 
-## Localized content
+## Localized and shared content
 
-Content entries are stored per locale. Generated hooks read the active Fimo locale automatically.
+Localized content is stored per locale. Generated hooks read the active Fimo locale automatically.
 
 When a project has multiple configured locales, create and update each localized content variant explicitly. Use the default locale first, then create non-default variants with the same `documentId` and the target `locale` through the content tools or `fimo entries` commands.
 
+For shared content, set `i18n: { "enabled": false }` on the schema and create each entry once. Shared entries:
+
+- 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.
+
+Do not duplicate shared entries across locales, add field-level localization settings, or implement locale fallbacks.
+
 **Generated API:**
 
 ```ts
 // low-level fetch helpers
-getById(id: string): Promise<BlogPost>
-getBySlug(slug: string): Promise<BlogPost | null>
-getByField(fieldName: string, value: string): Promise<BlogPost | null>
-get<TFields extends BlogPostFields | undefined>(params?: BlogPostQuery<TFields>): Promise<BlogPostResult<TFields>[]>
-create(payload: Partial<BlogPost>): Promise<BlogPost>
-update(id: string, payload: Partial<BlogPost>): Promise<BlogPost>
+getById<TPopulate extends BlogPostPopulate | undefined>(id: string, options?: { populate?: TPopulate }): Promise<BlogPostResult<undefined, TPopulate>>
+getBySlug<TPopulate extends BlogPostPopulate | undefined>(slug: string, options?: { populate?: TPopulate }): Promise<BlogPostResult<undefined, TPopulate> | null>
+getByField<TPopulate extends BlogPostPopulate | undefined>(fieldName: string, value: string, options?: { populate?: TPopulate }): Promise<BlogPostResult<undefined, TPopulate> | null>
+get<TFields extends BlogPostFields | undefined, TPopulate extends BlogPostPopulate | undefined>(params?: BlogPostQuery<TFields, TPopulate>): Promise<BlogPostResult<TFields, TPopulate>[]>
+create(payload: BlogPostInput): Promise<BlogPost>
+update(id: string, payload: Partial<BlogPostInput>): Promise<BlogPost>
 remove(id: string): Promise<void>
 
 // react-query hooks
-useGetById(id)                    // → { data: BlogPost | undefined, isLoading, ... }
-useGetBySlug(slug)                // → { data: BlogPost | null | undefined, ... } — ideal for /:slug detail routes
-useGetByField(fieldName, value)   // → { data: BlogPost | null | undefined, ... }
-useGet<TFields>(params?)          // → { data: BlogPostResult<TFields>[] | undefined, isLoading, ... }
+useGetById(id, { populate? })     // → { data: BlogPostResult<undefined, TPopulate> | undefined, isLoading, ... }
+useGetBySlug(slug, { populate? }) // → { data: BlogPostResult<undefined, TPopulate> | null | undefined, ... } — ideal for /:slug detail routes
+useGetByField(fieldName, value, { populate? })
+useGet<TFields, TPopulate>(params?) // → { data: BlogPostResult<TFields, TPopulate>[] | undefined, isLoading, ... }
 useCreate() / useUpdate() / useRemove()
 
 // Suspense variants (same signatures, throw to a <Suspense> boundary instead of returning isLoading)
 useSuspenseGetById(id) / useSuspenseGetBySlug(slug) / useSuspenseGetByField(fieldName, value) / useSuspenseGet(params?)
 ```
 
+Write inputs contain plain JSON values. Read models contain Fimo wrapper values for source tracking, so use `BlogPostInput` rather than sending a `BlogPost` back to `create` or `update`.
+
+For a schema with `"isSingleton": true`, codegen omits collection methods and generates this smaller API:
+
+```ts
+get<TPopulate extends SettingsPopulate | undefined>(options?: { locale?: string; populate?: TPopulate }): Promise<SettingsResult<undefined, TPopulate>>
+update(payload: Partial<SettingsInput>): Promise<Settings>
+useGet(options?) / useSuspenseGet(options?) / useUpdate()
+```
+
+Singleton clients do not expose `create`, `remove`, `getById`, or list queries. Localized singletons have one variant per locale; non-localized singletons have one locale-free row.
+
 Access pattern — the hooks **unwrap** the API envelope, so `get()` / `useGet()` resolve to a `BlogPost[]` directly (not a `{ data, meta }` wrapper):
 
 ```tsx
@@ -223,6 +270,7 @@ posts.map((post) => /* ... */); // BlogPost[]
 ```
 
 Query params supported: `limit` (1-100, default 20), `offset` (default 0), `search`, `sort`, `where`, `fields`, and `populate`. Use these canonical names in new code.
+`fields` and `populate` change the returned item type. `where`, `search`, `sort`, `limit`, and `offset` only change selection or ordering. `locale` selects a localized owner variant, or the localized target variant when shared content is populated; raw shared reads omit it.
 
 `where` filters on the server. Use scalar values for equality and operator objects for ranges, lists, text matches, or null checks. Keep boolean, string, and number values typed in the object:
 
@@ -242,6 +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.
 
 Use `fields` to keep list payloads small. The API always keeps `id`, and returns only the requested fields beyond that:
 
@@ -261,10 +311,26 @@ const { data: posts = [] } = BlogPost.useGet({
   fields: ['slug', 'title', 'author'] as const,
   populate: ['author'] as const,
 });
-// Without populate: post.author is a target documentId string.
+// Without populate: post.author is { documentId: "..." }.
 // With populate: post.author is the target Author entry object, or null.
 ```
 
+Keep `fields` and `populate` arrays `as const` so TypeScript can infer the precise projected and populated shape. Prefer hook inference. If a helper/component needs a named type, use the generated result type:
+
+```ts
+import type { BlogPostResult } from '@/schemas/BlogPost';
+
+type PostWithAuthor = BlogPostResult<undefined, 'author'>;
+type PostCardItem = BlogPostResult<
+  readonly ['slug', 'title', 'author', 'contributors'],
+  readonly ['author', 'contributors']
+>;
+```
+
+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.
+
+`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.
+
 Populate is depth-one. It only works for relation fields; trying to populate a scalar field returns 400. To-many relation 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.
@@ -273,16 +339,16 @@ The generated hooks do **not** surface pagination meta (`total`, `hasMore`, `lim
 
 The entry objects a hook returns are **not** plain JS values. The generated client wraps each _trackable_ field in a `fimo/ui` primitive that carries source metadata for inline editing. Which fields wrap, and which stay plain:
 
-| Schema field type | Field value you get         | Notes                                                                                        |
-| ----------------- | --------------------------- | -------------------------------------------------------------------------------------------- |
-| `string`          | `FimoString`                | `extends String` — **not** a primitive `string`                                              |
-| `richtext`        | `FimoRichText`              | Tiptap JSONContent + source metadata                                                         |
-| `boolean`         | `FimoBoolean`               | class; `.valueOf()` → `boolean`                                                              |
-| `media`           | `FimoMedia` / `FimoMedia[]` | shape + rendering in `references/assets.md`                                                  |
-| `number`          | `number`                    | plain — not wrapped                                                                          |
-| `json`            | `Record<string, any>`       | plain — not wrapped                                                                          |
-| `date`            | `any` (raw ISO date string) | not wrapped (`FimoDate` is not emitted — see below)                                          |
-| `relation`        | `string` / `string[]`       | target `documentId` value(s); use `populate` on raw API when embedded target rows are needed |
+| Schema field type | Field value you get                 | Notes                                                                                             |
+| ----------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `string`          | `FimoString`                        | `extends String` — **not** a primitive `string`                                                   |
+| `richtext`        | `FimoRichText`                      | Tiptap JSONContent + source metadata                                                              |
+| `boolean`         | `FimoBoolean`                       | class; `.valueOf()` → `boolean`                                                                   |
+| `media`           | `FimoMedia` / `FimoMedia[]`         | shape + rendering in `references/assets.md`                                                       |
+| `number`          | `number`                            | plain — not wrapped                                                                               |
+| `json`            | `Record<string, any>`               | plain — not wrapped                                                                               |
+| `date`            | `any` (raw ISO date string)         | not wrapped (`FimoDate` is not emitted — see below)                                               |
+| `relation`        | `FimoReference` / `FimoReference[]` | reference object(s) with target `documentId`; use `populate` when embedded target rows are needed |
 
 Rules of thumb:
 
@@ -346,7 +412,7 @@ const { data, meta } = await res.json();
 // meta: { limit, offset, total, hasMore }
 ```
 
-Prefer the generated React Query hooks from `@/schemas/{Uid}` over hand-rolled fetch — they handle caching and types (returning a typed `BlogPost[]`). Reach for this raw fetch only when you need the pagination `meta`, which the hooks don't surface.
+Prefer the generated React Query hooks from `@/schemas/{Uid}` over hand-rolled fetch — they handle caching and types (returning typed `BlogPostResult<TFields, TPopulate>[]` results). Reach for this raw fetch only when you need the pagination `meta`, which the hooks don't surface.
 
 ## Forms vs. schemas
 

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

@@ -22,7 +22,7 @@ Fimo provides locale utilities that follow the Fimo standard, but they are helpe
 - `defaultLocale` is the source/default locale.
 - `locales` lists enabled locales and must include `defaultLocale`. Do not add non-default locales unless the user asks for multiple languages, localized routes, translations, or a specific locale.
 - `routing.strategy` currently supports `path-prefix`.
-- If multiple locales are configured, create or update labels and content for every configured locale.
+- If multiple locales are configured, create or update labels and localized content for every configured locale. Create schemas with `i18n: { "enabled": false }` only once; those entries are shared across locales.
 
 Locale tags should be structurally valid, for example `en`, `es`, `pt-BR`, or `zh-Hans`.
 

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}.ts` — typed React Query hooks. 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 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.
+
 ## Entries CLI commands
 
 Entries are NOT JSON-file-driven. Create/update them via CLI.
@@ -57,11 +59,13 @@ fimo entries list BlogPost --fields slug,title,excerpt,coverImage --sort -publis
 fimo entries list BlogPost --fields slug,title,author --populate author
 ```
 
-Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`, `--offset`, and `--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}}`). 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. Use `--sort field` for ascending and `--sort -field` for descending.
+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.
 `--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 target `documentId` strings. 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 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.
+
+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:
 
@@ -74,18 +78,24 @@ For relation schema JSON and entry value shape, load `fimo/references/content.md
 }
 ```
 
-Entry bodies store target `documentId` values:
+Entry bodies store reference objects with target `documentId` values:
 
 ```bash
-fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":"750e8400-e29b-41d4-a716-446655440000","contributors":[]}}'
+fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello","author":{"documentId":"750e8400-e29b-41d4-a716-446655440000"},"contributors":[]}}'
 ```
 
-## Localized content
+Do not add `localized` or field-level `i18n` to relation fields. The relation value belongs to the entry variant that stores it.
+
+## Localized and shared content
 
-Content entries are stored per locale. Omit `--locale` for default-locale entries. Pass `--locale <locale>` when creating, listing, reading, or updating a specific non-default locale.
+Schemas are localized by default. Omit `--locale` for default-locale entries. Pass `--locale <locale>` when creating, listing, reading, or updating a specific non-default locale.
 
 When creating a localized variant of an existing entry, pass the source entry's `documentId` with `--document-id`. Keep projects single-locale unless the user asks for multilingual or localized output; when multiple locales are configured, create and update every locale explicitly.
 
+For content shared across locales, define `"i18n": { "enabled": false }` at the schema root and create each entry once. Do not pass `--document-id` to manufacture locale variants. Shared entry responses omit `locale`; a read locale is only used to resolve populated relations 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.
+
 ## "Add a blog" recipe
 
 1. Load `fimo/references/content.md` for the JSON shape and field types.
@@ -99,7 +109,7 @@ When creating a localized variant of an existing entry, pass the source entry's
 
 ## 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
@@ -108,7 +118,7 @@ fimo validate                  # runs all phases: codegen, lint, route validatio
 Advanced/internal (hidden from `fimo --help`) — for the bare regen phase:
 
 ```bash
-fimo scripts sync-schemas      # regenerate src/schemas/*.ts only
+fimo scripts sync-schemas      # regenerate src/schemas/*.types.ts and src/schemas/*.ts
 ```
 
 ## Non-interactive use

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

@@ -25,7 +25,7 @@ Edit `fimo-config.json`. Keep one locale unless the user asks for multilingual o
 - `locales` must include `defaultLocale`. Do not add non-default locales unless the user asks for multiple languages, localized routes, translations, or a specific locale.
 - Locale tags should be structurally valid, for example `en`, `es`, `pt-BR`, or `zh-Hans`.
 - `routing.strategy` currently supports `path-prefix`.
-- If multiple locales are configured, create or update labels and content for every configured locale.
+- If multiple locales are configured, create or update labels and localized content for every configured locale. Create schemas with `i18n: { "enabled": false }` only once.
 
 ## Validate
 
@@ -74,4 +74,4 @@ Labels and content are separate translated surfaces:
 - labels: static UI copy declared with `t('key')`, managed with `fimo labels`
 - content: schema entries, managed with `fimo entries`
 
-Omit `--locale` for default-locale writes. Pass `--locale <locale>` for each non-default locale you need to create or update.
+Omit `--locale` for default-locale writes. Pass `--locale <locale>` for each non-default localized entry you need to create or update. Shared schemas (`i18n.enabled: false`) have one locale-free entry instead.

package/dist/cli/bundle.json

@@ -1,8 +1,8 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-09T07:06:21.467Z",
-  "cliVersion": "0.3.5",
+  "bundledAt": "2026-07-11T09:31:12.817Z",
+  "cliVersion": "0.3.6",
   "external": [
     "oxc-parser",
     "fsevents"