fimo 0.12.0 → 0.12.1

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

@@ -1,602 +1,17 @@
-# Content (schemas + entries) — package surface
+# Content reference map
 
-> For the CLI workflow (`fimo schemas push`, `fimo entries create`, the "Add a blog" recipe), see **`fimo-cli/references/content.md`**.
+Fimo schemas are framework-neutral JSON contracts with framework-specific public modules under `src/schemas/`.
 
-This file covers the **package surface**: the JSON shape you write, the generated React Query hooks you import, the data types your code receives. All of this is version-locked to this project's installed `fimo` package.
+Load only what the task needs:
 
-## Schema JSON shape
+- `references/content/schema.md` — schema JSON, field types, blocks, references, and safe transitions.
+- `references/content/richtext.md` — Tiptap JSONContent, entry payloads, and slug rules.
+- `references/content/clients.md` — generated collection/singleton clients, queries, projections, population, and locale behavior.
+- `references/ui.md` — source-tracked values and their React renderers.
+- `references/frameworks/next.md` — Next App/Pages Router module boundaries.
+- `references/frameworks/react-router.md` — React Router framework-mode setup and imports.
+- `references/frameworks/vite-react.md` — Vite + React setup and imports.
 
-```json
-{
-  "uid": "BlogPost",
-  "name": "Blog Posts",
-  "i18n": { "enabled": true },
-  "fields": {
-    "title": { "type": "string" },
-    "summary": { "type": "text" },
-    "body": { "type": "richtext" },
-    "publishDate": { "type": "string" },
-    "featured": { "type": "boolean" },
-    "coverImage": { "type": "media" },
-    "metadata": { "type": "json" },
-    "author": { "type": "reference", "target": "Author" },
-    "contributors": { "type": "reference", "target": "Author", "many": true }
-  }
-}
-```
+For schema and content writes, load `fimo-cli/references/content.md`.
 
-**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 schema-root `i18n` keys are supported.
-
-Inside a localized type, an individual top-level scalar or reference field may carry `"i18n": false`. That field then holds one value for the whole document: writing it through any locale updates all of them. Use it for values that are not translated, such as a price, a SKU, a product photo, or a reference that should point at the same target everywhere. Fields inside `blocks` follow the locale of the entry containing them and reject the flag.
-
-```json
-{
-  "uid": "Product",
-  "name": "Products",
-  "fields": {
-    "title": { "type": "string" },
-    "sku": { "type": "string", "i18n": false },
-    "price": { "type": "number", "i18n": false }
-  }
-}
-```
-
-### Reserved field names — do NOT declare these in `fields`
-
-Every entry already carries this metadata automatically. Declaring any of them as a
-schema field is rejected by `fimo schemas push` with a 400 (e.g. `fields.slug: "slug" is
-reserved entry metadata and cannot be used as a content field.`):
-
-`id`, `entryId`, `documentId`, `slug`, `locale`, `createdAt`, `updatedAt`, `__fimo`.
-
-Collection entries expose the effective `locale`. It remains reserved for both localized and shared schemas.
-
-In particular **do not add a `slug` field** — every entry gets a `slug` for free. You still
-pass `slug` inside `data` when _creating an entry_ (see "Entry body shape" below); it just
-must not appear in the schema's `fields`. If you need an additional URL-ish string, name it
-something else (e.g. `handle`, `permalink`).
-
-## Field types
-
-| Type        | `data` JSON shape                                                             | Use for                                                    |
-| ----------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| `string`    | `"..."`                                                                       | One-line text: titles, names, slugs                        |
-| `text`      | `"First line\nSecond line"`                                                   | Multiline plain text without formatting                    |
-| `richtext`  | Tiptap JSONContent (see below)                                                | Formatted content with headings, links, lists, or media    |
-| `number`    | `42`                                                                          | Counts, quantities                                         |
-| `boolean`   | `true` / `false`                                                              | Flags                                                      |
-| `date`      | ISO date string, e.g. `"2026-06-03"`                                          | Publish dates, timestamps                                  |
-| `media`     | `{ "source": "local"\|"external", "url": "https://...", "alt": "..." }`       | Images, video                                              |
-| `json`      | any JSON                                                                      | Structured metadata                                        |
-| `reference` | `{ "id": "..." }`, `null`, or an array of reference objects when `many: true` | References to another schema                               |
-| `blocks`    | ordered array of objects                                                      | Fixed groups, repeated sections, or selectable page blocks |
-
-A `date` field generates as `string` in the TS client and wraps in `FimoString` at read time — the same source-tracked shape as `string`/`text` — so `<Date value={post.someDate} />` and plain string methods (`.slice()`, template literals, …) both work directly.
-
-## Enumerated strings
-
-A `string` field may declare `options` to close its value set. The CMS renders a select, the API validates the value as an enum, and the generated client types the field as a literal union instead of `string`.
-
-```json
-"layout": { "type": "string", "options": ["article", "video"], "default": "article" }
-```
-
-- Values must be unique. Set a `default` that is one of them.
-- `options` cannot be combined with `regex`, `minLength`, or `maxLength`, and is rejected on every field type other than `string`.
-- Writes are validated against the set: a value outside it is rejected with a 400. An optional field also accepts `""` and `null` so the editor can clear the choice; a `required` one only accepts a declared value.
-- Removing an option that entries still hold fails the push, the same way an unsafe type change does. Migrate those entries to a remaining value first.
-
-## Conditional fields
-
-A field may declare `showIf` (every clause must match) or `showIfAny` (one clause is enough) to apply only in some entries. A clause names a sibling field and a value.
-
-```json
-{
-  "layout": { "type": "string", "options": ["article", "video"], "default": "article" },
-  "body": { "type": "richtext", "showIf": { "field": "layout", "equals": "article" } },
-  "videoUrl": { "type": "string", "required": true, "showIf": { "field": "layout", "equals": "video" } },
-  "transcript": {
-    "type": "text",
-    "showIfAny": [
-      { "field": "layout", "equals": "video" },
-      { "field": "hasAudio", "equals": true }
-    ]
-  }
-}
-```
-
-- A clause is `{ "field": "<sibling>", "equals": <value> }` or `{ "field": "<sibling>", "in": [<values>] }`. Use `in` for several values of one field.
-- `showIf` accepts one clause or an array of clauses, and every clause must match. `showIfAny` takes an array and one match is enough. A field declares one key or the other, never both.
-- **A hidden field is not rendered and not validated, so `required` does not apply to it.** An entry whose condition never held can be saved without ever filling the field.
-- **Hiding a field changes nothing about storage or reads.** The value stays in the entry and the API keeps returning it, so an editor who flips the trigger back gets their work back. Narrow on the trigger in site code rather than trusting the value.
-- Because a conditional field can be absent, it is always optional in the generated types even when `required` is set.
-- Conditions resolve against siblings in the same object. A field inside a block variant may only reference fields in that same block item.
-- A clause may reference a `boolean`, `number`, or `string` field. A `string` trigger must declare `options`, which is what lets `fimo validate` reject a clause value that could never match.
-- A trigger cannot itself be conditional — conditions are one level deep, so a chain like A shows B shows C is rejected.
-- `fimo validate` and `fimo schemas push` reject an unknown trigger name, a trigger of the wrong type, a value outside the trigger's `options`, and a trigger that is itself conditional.
-
-## Blocks
-
-`blocks` is the only nested structured-content type and always stores an array. Use `schema.fields` for one homogeneous block shape. Set `max: 1` when the field is a single optional group. Use `schema.oneOf` when editors choose a variant for each item.
-
-```json
-{
-  "seo": {
-    "type": "blocks",
-    "max": 1,
-    "schema": {
-      "fields": {
-        "title": { "type": "string", "required": true },
-        "description": { "type": "text" }
-      }
-    }
-  },
-  "sections": {
-    "type": "blocks",
-    "min": 1,
-    "max": 20,
-    "schema": {
-      "oneOf": [
-        {
-          "uid": "hero",
-          "label": "Hero",
-          "fields": {
-            "heading": { "type": "string", "required": true },
-            "introduction": { "type": "text" }
-          }
-        },
-        {
-          "uid": "quote",
-          "label": "Quote",
-          "fields": {
-            "quote": { "type": "text", "required": true },
-            "author": { "type": "reference", "target": "Author" }
-          }
-        }
-      ]
-    }
-  }
-}
-```
-
-- `blocks.schema.fields` repeats one homogeneous shape.
-- `blocks.schema.oneOf` lets the editor choose exactly one variant per item.
-- Blocks schemas support at most 7 nested `blocks` levels, 40 variants in one `schema.oneOf`, and `min` or `max` values up to 200 items per blocks field.
-- Blocks always read and write arrays. A field with `max: 1` is `[]` or `[item]`, never a bare object.
-- `min` and `max` constrain the total number of blocks. Use `min: 1` to require at least one block; `required: true` has the same minimum-one behavior.
-- Fimo creates a stable `_key` for each item. A `oneOf` item also carries `_type`, matching the variant `uid`.
-- Nested fields support the same defaults and validators as top-level fields.
-- **Each block item's own scalar fields wrap the same way their field type wraps at the top level** — a nested `string`/`text` field is a `FimoString`, a nested `richtext` field is a `FimoRichText`, a nested `media` field is a `FimoMedia`, a nested `boolean` is a `FimoBoolean`, a nested `date` is a `FimoString`, a nested `json` field is a shallow-cloned, source-tagged object, a nested `number` stays a plain `number`, and a nested `blocks` field recurses the same way. Pass those nested values to the matching `fimo/ui` component exactly like a top-level field — `<Text value={section.heading} />` or `<Json value={section.metadata} />` inside a `.map()` over `page.sections` stays inline-editable.
-- Blocks inherit the owning entry's locale.
-- Nested references use one fixed `target`. Unpopulated reads return `{ id, documentId }`, like top-level references.
-- Nested population and filtering are not supported yet.
-- `anyOf` is not supported. One block never merges multiple variant schemas.
-
-## Reference fields
-
-Use `reference` when one content entry references another content entry. Do not store entry IDs in a `json` field as a workaround.
-
-```json
-{
-  "uid": "BlogPost",
-  "name": "Blog Posts",
-  "fields": {
-    "title": { "type": "string" },
-    "author": { "type": "reference", "target": "Author" },
-    "contributors": { "type": "reference", "target": "Author", "many": true }
-  }
-}
-```
-
-Rules:
-
-- `target` is required and must be the PascalCase schema `uid` of the referenced content type.
-- Omit `many` for a to-one reference. Use `"many": true` for a to-many reference.
-- Self-references are allowed, e.g. a `Category` schema can have `parent: { "type": "reference", "target": "Category" }`.
-- Entry values use the target's stable `id`, never the variant `entryId`: `{ "id": "..." }`.
-- Do not include `contentType` for normal fixed-target references; the schema's `target` already defines it.
-- `localized` is not a supported spelling. A reference may carry `"i18n": false` so every locale of the document points at the same target; without it the reference 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": "reference-example",
-    "title": "Reference example",
-    "author": { "id": "750e8400-e29b-41d4-a716-446655440000" },
-    "contributors": [{ "id": "750e8400-e29b-41d4-a716-446655440000" }]
-  }
-}
-```
-
-## Schema transitions
-
-After editing schema JSON, run `fimo schemas push {Uid}` and then `fimo validate`. Push regenerates the schema client and applies the schema change to existing content automatically:
-
-- Adding optional fields and changing labels preserve entries.
-- Adding a required field backfills its `default` only in existing objects that need it. The push fails safely if those objects exist and no valid default is provided.
-- Removing a field or block variant removes only those nested values.
-- A one-to-many reference change wraps each existing reference in an array.
-- Changing between `string` and `text` preserves values.
-- Other primitive type changes convert safe values, such as `42` to `"42"`, and reject unsafe values without changing content or schema.
-- Lowering blocks `max` trims items from the end. Raising `min` appends blocks from the field's non-empty `default` array.
-- Changing a reference target clears those connections. Renaming a relation field with the same target preserves them.
-- Preserve top-level or nested renames with repeatable one-time operations: `fimo schemas push Page --rename sections.hero.heading=sections.hero.title`. Renames are command intent, not schema JSON.
-- A many-to-one change or scalar/reference change clears only the changed field.
-- Collection-to-Single removes that type's entries and cleans references to them.
-- Singleton-to-collection preserves the existing entry.
-- Blocks migrations are surgical: unaffected nested fields, block keys, and block order survive every supported change.
-
-There are no reset or data-loss flags. A failed migration is atomic: neither schema nor entries change.
-
-Choose by editing intent:
-
-- Use `string` for one-line values such as titles, names, labels, slugs, URLs, and short metadata.
-- Use `text` for plain multiline copy such as summaries, descriptions, bios, excerpts, intros, and details when formatting is unnecessary.
-- Use `richtext` for content that needs formatting or structured blocks, especially article bodies and page content.
-
-## Tiptap JSONContent (richtext)
-
-Richtext values MUST be Tiptap JSONContent — never raw HTML strings:
-
-```json
-{
-  "type": "doc",
-  "content": [
-    { "type": "heading", "attrs": { "level": 1 }, "content": [{ "type": "text", "text": "Title" }] },
-    {
-      "type": "paragraph",
-      "content": [
-        { "type": "text", "text": "Hello " },
-        { "type": "text", "marks": [{ "type": "bold" }], "text": "world" }
-      ]
-    }
-  ]
-}
-```
-
-Available nodes: `doc`, `paragraph`, `heading` (levels 1-6; prefer 1-3 for hierarchy), `bulletList`, `orderedList`, `listItem`, `blockquote`, `codeBlock`, `horizontalRule`, `hardBreak` (renders as `<br/>`), `table`, `tableRow`, `tableHeader`, `tableCell`, `image` (`attrs.src`, `attrs.alt`), `iframe` (`attrs.src` — use embed URLs like `https://www.youtube.com/embed/<ID>`).
-
-Marks: `bold`, `italic`, `underline`, `strike`, `code`, `link`.
-
-**Use the full range of block types** when generating richtext — `<RichText>` styles them all out of the box:
-
-- `codeBlock` for code snippets (bordered monospace container)
-- `blockquote` for quotes and callouts (left-border accent)
-- `horizontalRule` to visually separate sections
-- `table` / `tableRow` / `tableHeader` / `tableCell` for structured data
-- `bulletList` / `orderedList` for lists
-- `heading` (levels 1-6; prefer 1-3) to build hierarchy — don't render long-form content as a single wall of `paragraph` nodes.
-
-## Entry body shape
-
-Entries are CLI-driven (see `fimo-cli/content.md`). The body shape passed to `fimo entries create --body '...'` is:
-
-```json
-{
-  "data": {
-    "slug": "my-first-post",
-    "title": "My First Post",
-    "body": { "type": "doc", "content": [...] },
-    "coverImage": { "source": "local", "url": "...", "alt": "..." }
-  }
-}
-```
-
-**`slug` lives INSIDE `data`**, alongside every other field.
-
-> The API validator strips any top-level keys other than `data` — if you put `slug` at the top level it is silently dropped and the backend generates a random one. Always nest it inside `data`.
-
-## Slug rules
-
-Always provide a meaningful `slug` when creating an entry — it appears in URLs. The server will `slugify()` whatever you send (lowercase, hyphen separators, strip special chars), so you can pass a clean candidate straight through.
-
-- **Format**: lowercase, hyphen-separated, ASCII, no special characters (e.g. `my-first-blog-post`).
-- **Derive from** the entry's main human-readable field: `title` for posts/pages, `name` for team members/products.
-- **Concise and descriptive** — max 255 chars; aim for under 60 for readability.
-- **Unique per content type** — two `BlogPost` entries can't share a slug. If seeding duplicates, suffix (`my-post`, `my-post-2`).
-- **Stable** — once an entry is live, changing the slug breaks inbound links. Only update intentionally.
-- If you omit `slug`, the backend generates a random one — never rely on this for content you want to link to.
-
-For `media` fields, prefer `source: "local"` with assets uploaded via `fimo assets upload` or generated with a Fimo media task such as `fimo image generate` (see `fimo-cli/references/media.md`).
-
-## Generated React Query hooks
-
-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` — exposes runtime helpers, React Query hooks, and 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:
-
-```ts
-interface BlogPost {
-  id: string;
-  entryId: string;
-  documentId: string;
-  slug: FimoString;
-  locale: string;
-  createdAt: string;
-  updatedAt: string;
-  __fimo: {
-    contentType: string;
-  };
-  title: FimoString;
-  summary: FimoString;
-  body?: FimoRichText | null;
-  coverImage: FimoMedia;
-  publishDate: FimoString;
-  featured: FimoBoolean;
-  // ...
-}
-```
-
-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`.
-
-Optional richtext fields are nullable in generated read and write types. `<RichText>` accepts the generated value directly and renders nothing when it is null or undefined. A non-conditional required richtext field stays non-null; conditional fields remain optional because their condition may not apply.
-
-## Localized and shared content
-
-Localized content has one variant per locale. Generated hooks read the active Fimo locale automatically.
-
-When a project has multiple configured locales, create and update each localized content variant explicitly. Use the default locale first, then create non-default variants with the same `documentId` and the target `locale` through the content tools or `fimo entries` commands.
-
-For shared content, set `i18n: { "enabled": false }` on the schema and create each entry once. Shared entries:
-
-- send and expose the effective active/default locale in generated collection queries and models;
-- omit `locale` from raw API responses because there is no localized variant;
-- are returned in every locale context without duplication;
-- ignore locale on owner reads and writes;
-- still use the active/requested locale when a populated reference targets a localized schema.
-
-Do not duplicate shared entries across locales. This section is about a whole type being shared; a single shared field inside a localized type is the separate `"i18n": false` field flag described above.
-
-A populated reference whose target has no variant in the requested locale resolves to null. Reads accept an opt-in `localeFallbacks: true` that resolves those to the best available variant instead (project default first), marked by its `locale` field — never implement fallbacks by hand; public reads stay strict unless the option is passed.
-
-**Polymorphic references:** a field may declare `targets: ["Post", "Video"]` instead of a single `target` (never both) when one slot genuinely holds different types — mixed feeds, hero blocks, curated collections. Prefer a fixed `target` whenever every value is the same type: fixed fields keep `where` filtering and simpler generated types. Polymorphic values use `{ contentType, id }`; populated values in generated hooks carry a top-level `$type` that narrows the union:
-
-```ts
-for (const item of page.featured) {
-  switch (item.$type) {
-    case 'Post':
-      return item.title; // typed as Post here
-    case 'Video':
-      return item.clips; // typed as Video here
-  }
-}
-```
-
-Filtering on polymorphic fields is not supported yet.
-
-**Generated API:**
-
-Collection responses use `id` as the stable identity shared by all locale variants. `locale` selects the variant, and generated hooks use the active Fimo locale when it is omitted. `entryId` identifies the exact variant returned by Fimo and is only for diagnostics or migrations. `documentId` remains a compatibility alias for `id`; reference inputs use `{ id: entry.id }`. Filters and sorts follow the same rule: `where.id` and `sort: "id"` use stable identity, while `entryId` addresses an exact variant.
-
-```ts
-// low-level fetch helpers
-getById<TPopulate extends BlogPostPopulate | undefined>(id: string, options?: { locale?: string; populate?: TPopulate }): Promise<BlogPostResult<undefined, TPopulate>>
-getBySlug<TPopulate extends BlogPostPopulate | undefined>(slug: string, options?: { populate?: TPopulate }): Promise<BlogPostResult<undefined, TPopulate> | null>
-getByField<TPopulate extends BlogPostPopulate | undefined>(fieldName: string, value: string, options?: { populate?: TPopulate }): Promise<BlogPostResult<undefined, TPopulate> | null>
-list<TFields extends BlogPostFields | undefined, TPopulate extends BlogPostPopulate | undefined>(params?: BlogPostQuery<TFields, TPopulate>): Promise<CollectionPage<BlogPostResult<TFields, TPopulate>>>
-get<TFields extends BlogPostFields | undefined, TPopulate extends BlogPostPopulate | undefined>(params?: BlogPostQuery<TFields, TPopulate>): Promise<BlogPostResult<TFields, TPopulate>[]>
-create(payload: BlogPostInput): Promise<BlogPost>
-update(id: string, payload: Partial<BlogPostInput>): Promise<BlogPost>
-remove(id: string, options?: { locale?: string }): Promise<void>
-
-// react-query hooks
-useGetById(id, { locale?, populate? }) // → { data: BlogPostResult<undefined, TPopulate> | undefined, isLoading, ... }
-useGetBySlug(slug, { populate? }) // → { data: BlogPostResult<undefined, TPopulate> | null | undefined, ... } — ideal for /:slug detail routes
-useGetByField(fieldName, value, { populate? })
-useList<TFields, TPopulate>(params?)         // → { data: CollectionPage<BlogPostResult<TFields, TPopulate>> | undefined, ... }
-useInfiniteList<TFields, TPopulate>(params?) // → { items, total, hasMore, loadMore, isLoadingMore, ... }
-useGet<TFields, TPopulate>(params?)          // → legacy array-shaped { data: BlogPostResult<TFields, TPopulate>[] | undefined, ... }
-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; shared singletons have one entry across locales.
-
-Choose the collection interface from the UI behavior. Use `useList` when the UI controls a page, and read pagination state from `pageInfo`:
-
-```tsx
-const { data: page, isLoading } = BlogPost.useList({ sort: '-publishedAt', limit: 12, offset: 24 });
-if (isLoading || !page) return null;
-
-page.items.map((post) => /* ... */);
-page.pageInfo; // { limit, offset, total, hasMore, nextOffset }
-```
-
-Use `useInfiniteList` for load-more and infinite-scroll views. It accumulates pages and exposes one typed `items` array, so UI code does not manage offsets or flatten pages:
-
-```tsx
-const {
-  items: posts,
-  hasMore,
-  loadMore,
-  isLoadingMore,
-} = BlogPost.useInfiniteList({
-  sort: '-publishedAt',
-  limit: 12,
-});
-```
-
-`get()` and `useGet()` remain available as legacy array-shaped helpers for small, deliberately bounded subsets:
-
-```tsx
-const { data: featured = [] } = BlogPost.useGet({
-  where: { featured: true },
-  limit: 3,
-});
-```
-
-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:
-
-```ts
-BlogPost.useGet({
-  where: {
-    featured: true,
-    category: 'tech',
-    views: { $gte: 100 },
-    title: { $contains: 'React' },
-    coverImage: { $null: false },
-    __fimo: { contentType: { $eq: 'BlogPost' } },
-  },
-  sort: ['-publishedAt', 'title'],
-  limit: 12,
-});
-```
-
-Operators: scalar equality, `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, `$null`.
-Reference field values are reference objects, but reference filters use the target `id` string, for example `where: { author: author.id }`; for to-many references that means "contains this target".
-For to-many references, `$eq` and `$contains` mean membership, `$in` means any listed document is present, `$ne` and `$nin` mean none are present, and `$null: true` means empty or missing. Reference fields cannot be sorted.
-
-Use `fields` to keep list payloads small. The API always keeps `id`, `entryId`, `documentId`, and `locale`, and returns only the requested fields beyond that:
-
-```tsx
-const { data: summaries = [] } = BlogPost.useGet({
-  fields: ['slug', 'title', 'excerpt', 'coverImage'] as const,
-  sort: '-publishedAt',
-  limit: 12,
-});
-// summaries: Array<Pick<BlogPost, 'id' | 'entryId' | 'documentId' | 'locale' | 'slug' | 'title' | 'excerpt' | 'coverImage'>>
-```
-
-Use `populate` to embed reference targets in read results:
-
-```tsx
-const { data: posts = [] } = BlogPost.useGet({
-  fields: ['slug', 'title', 'author'] as const,
-  populate: ['author'] as const,
-});
-// Without populate: post.author is { id: "..." }.
-// 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 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 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 reference fields; trying to populate a scalar field returns 400. To-many reference order is preserved.
-
-`list()` and `useList()` surface pagination metadata as `pageInfo`. `useInfiniteList()` consumes `nextOffset` internally and exposes `hasMore` plus `loadMore()`.
-
-## Fimo primitives (what the field values are)
-
-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`                                                                                                                                                                       |
-| `text`            | `FimoString`                        | Multiline plain text with the same source tracking as `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. A wrapper would break `<span>{post.views}</span>` (React renders a boxed `String` directly but throws on a boxed `Number`), so it stays untracked and unclickable in the editing surfaces        |
-| `json`            | `Record<string, any>`               | the same shape you wrote, plus a hidden (non-enumerable, symbol-keyed) source tag — render with `<Json>`, see below                                                                                                   |
-| `date`            | `FimoString`                        | same wrapper as `string`/`text`, **not** `FimoDate` — see below                                                                                                                                                       |
-| `blocks`          | array of plain objects              | the array/objects themselves are plain; each item's own scalar fields are wrapped by their own field type (a nested `string` is still `FimoString`, a nested `number` stays a plain `number`, …) — see "Blocks" above |
-| `reference`       | `FimoReference` / `FimoReference[]` | reference object(s) with target `id`; use `populate` when embedded targets are needed                                                                                                                                 |
-
-Rules of thumb:
-
-- **Pass the whole primitive to the matching `fimo/ui` component** — `<Text value={post.title} />`, `<Image value={post.cover} />`, `<RichText value={post.body} />`, `<Boolean value={p.inStock} />`, `<Date value={post.publishDate} />`, `<Json value={post.metadata} />`. Don't unwrap first; the component reads the source metadata so the field stays inline-editable in the dashboard.
-- **`FimoString extends String`**, so `typeof post.title === 'object'` and `post.title === 'Hi'` is `false`. It stringifies fine inside JSX and template literals; call `.toString()` only when something genuinely needs a primitive `string`.
-- **`number` fields are the one scalar type left unwrapped** — `post.views` is a plain `number`, so `{post.views}` renders directly in JSX, `typeof`/`===`/arithmetic all behave normally, and there is no `<Number>` component. This is deliberate, not a gap: wrapping it would break direct JSX rendering in every existing site.
-- **`json` fields are a shallow clone of what you wrote**, tagged with a hidden source symbol — not the original object, and not a class instance. Reading it behaves exactly like plain JSON (`JSON.stringify` round-trips it unchanged; `for...in`/`Object.keys` see only your own keys). Render it with `<Json value={post.metadata} />` (default renders as a `<span>`; pass `as="pre"` for a formatted block, or a children render function for specific keys) so it stays inline-editable and live-updates in the dashboard preview like every other field.
-- **Never hand-construct** a `FimoString` / `FimoMedia` / etc. — that bypasses source tracking. For a literal string use `t()`; for a literal image use `<StaticImage>`.
-- `t()` also returns a `FimoString` (see `references/labels.md`).
-
-`FimoMedia` and `FimoBoolean` shapes:
-
-```ts
-class FimoMedia {
-  readonly url: string;
-  readonly alt: string;
-  readonly name: string;
-  readonly mime: string;
-  readonly width?: number;
-  readonly height?: number;
-}
-
-class FimoBoolean {
-  readonly value: boolean;
-  valueOf(): boolean;
-}
-```
-
-> **`FimoDate`:** exported from `fimo/ui` (it's one of the `<Date>` component's accepted value types), but the generated schema client does **not** wrap `date` fields in it — a `date` field wraps as `FimoString` instead (see the table above), because the generated TypeScript type for a `date` field is `string`, and `FimoString` is what keeps that contract's string methods (`.slice()`, `.includes()`, …) working. `<Date value={post.someDate} />` accepts a `FimoString`, a `FimoDate`, a raw `Date`, or a raw string — all four render correctly.
-
-## UI code pattern
-
-```tsx
-import { useList } from '@/schemas/BlogPost';
-import { Text, RichText, Image, Date } from 'fimo/ui';
-
-export function BlogList() {
-  const { data: page, isLoading } = useList({ limit: 10 });
-  if (isLoading || !page) return null;
-  return (
-    <ul>
-      {page.items.map((post) => (
-        <li key={`${post.id}:${post.locale}`}>
-          <Text value={post.title} as="h2" />
-          <Image value={post.coverImage} width={800} height={400} fit="cover" />
-          <RichText value={post.body} className="prose" />
-          <Date value={post.publishDate} />
-        </li>
-      ))}
-    </ul>
-  );
-}
-```
-
-For the `<Text>` / `<RichText>` / `<Image>` / `<Date>` / `<Json>` components and the rules of thumb, see `references/ui.md`.
-
-## Read path (published app, no auth)
-
-```ts
-const res = await fetch(`${import.meta.env.VITE_API_URL}/entries/<typeName>?locale=en&fields=slug,title&limit=12`);
-const { data, meta } = await res.json();
-// data: Entry[] — fields flattened at top level (id, entryId, documentId, locale, slug, title, ...)
-// meta: { limit, offset, total, hasMore }
-```
-
-Prefer the generated `useList` or `useInfiniteList` hooks from `@/schemas/{Uid}` over hand-rolled fetches. They preserve projected/populated item types, cache results, and expose the pagination state regular list UIs need. Use the raw endpoint only for lower-level integrations outside the generated client.
-
-## Forms vs. schemas
-
-Schemas = **editor-managed content** (blog posts, pages). Forms = **end-user input** (contact, signup). See `references/forms.md` for forms.
+Never edit generated TypeScript. Follow `references/content/schema.md` for schema changes and load the detected framework reference before choosing generated module imports.

package/assets/skills/fimo-code/references/design.md

@@ -4,7 +4,7 @@ Distinctive, production-grade frontend interfaces with high design quality. Avoi
 
 Skip for: bug fixes, refactors, copy changes, or tasks where the user has already specified visual details (exact fonts, colors, layout).
 
-For React / Tailwind / `fimo/ui` code conventions (component sizing, routing, loading states, etc.), see `references/ui.md`. This file is about the aesthetic and creative direction.
+For source-tracked React primitives, see `references/ui.md` plus the detected framework reference. Preserve the application's existing styling, routing, and component conventions. This file is about aesthetic and creative direction.
 
 ## Brief first, code second