fimo 0.12.0 → 0.12.1

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

@@ -2,7 +2,7 @@
 
 > For the CLI commands (`fimo assets upload`, `fimo image generate`, folder management) and the "when to generate AI images" workflow rules, see **`fimo-cli/references/assets.md`**.
 
-This file covers the **package surface** for working with assets in code: the `media` field value shape, how to render assets with `fimo/ui` components, the URL format.
+This file covers the package surface for working with assets in code: the `media` field value shape, rendering primitives, and URL format.
 
 ## `media` field value (stored/wire shape)
 
@@ -20,11 +20,11 @@ Asset values returned from `fimo assets upload` or Fimo media tasks, and stored
 - `url`: stable HTTPS URL, no auth required, safe to embed.
 - `alt`: optional alt text.
 
-In a generated schema hook this stored value is wrapped in a runtime `FimoMedia` object (from `fimo/ui`) that exposes `url`, `alt`, `name`, `mime`, and optional `width`/`height` — it does **not** carry the `source` key (that's tracked internally for inline editing). Pass the whole entry value to `<Image>` / `<Video>`; don't read `source` off it in app code.
+Generated content reads wrap this stored value in `FimoMedia`, which exposes `url`, `alt`, `name`, `mime`, and optional `width`/`height`. It does not expose `source`; Fimo tracks that internally. Pass the whole entry value to `<Image>` / `<Video>`.
 
 ## Rendering in JSX
 
-Always use the `fimo/ui` primitives — never raw HTML:
+Import the primitives from the active framework adapter: `fimo/next` on the Next server, `fimo/next/client` in Next Client Components, or `fimo/ui` in React Router/Vite.
 
 | Asset source                                        | Component             | Pass via                  |
 | --------------------------------------------------- | --------------------- | ------------------------- |
@@ -32,7 +32,7 @@ Always use the `fimo/ui` primitives — never raw HTML:
 | Hard-coded URL or generated asset referenced inline | `<StaticImage>`       | `src="https://..."`       |
 
 ```tsx
-import { Image, StaticImage, Video } from 'fimo/ui';
+import { Image, StaticImage, Video } from 'fimo/next';
 
 // from a schema entry:
 <Image value={post.coverImage} width={1200} height={630} fit="cover" />
@@ -41,6 +41,8 @@ import { Image, StaticImage, Video } from 'fimo/ui';
 <StaticImage src="https://assets.fimo.ai/<project>/<id>.jpg" alt="Hero" width={1200} height={630} />
 ```
 
+Fimo's `<Image>` is not Next's `next/image` component. Do not pass Next-only props such as `priority`, `fill`, `quality`, or `loader`; use only the props documented for the Fimo primitive. Preserve `next/image` for non-Fimo images when the application needs those Next-specific controls.
+
 **Provide `width` and `height` when known** so Fimo can optimize the asset and reserve layout space (prevents CLS).
 
 **Never hand-construct a `FimoMedia` object** to pass into `<Image>` — that bypasses inline-editing metadata. If you have a raw URL, use `<StaticImage>` instead.

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

@@ -0,0 +1,130 @@
+# Generated content clients
+
+Application code imports the public modules generated from `src/schemas/<Uid>.json`, not `.types.ts` directly.
+
+The exact file split is framework-dependent. Load `references/frameworks/next.md`, `references/frameworks/react-router.md`, or `references/frameworks/vite-react.md` before choosing imports.
+
+## Entry shape
+
+Fields are top-level, never nested under `data`:
+
+```ts
+interface Article {
+  id: string;
+  entryId: string;
+  documentId: string;
+  slug: FimoString;
+  locale: string;
+  createdAt: string;
+  updatedAt: string;
+  __fimo: { contentType: string };
+  title: FimoString;
+  body?: FimoRichText | null;
+}
+```
+
+`id` is stable across locale variants. `entryId` identifies the returned variant. `documentId` is a compatibility alias for `id`. Reference inputs use `{ id: entry.id }`.
+
+## Collection API
+
+Generated collection modules expose promise methods:
+
+```ts
+getById(id, { locale?, populate? })
+getBySlug(slug, { locale?, populate? })
+getByField(fieldName, value, { locale?, populate? })
+list({ limit?, offset?, search?, sort?, where?, fields?, populate?, locale? })
+get(query) // legacy bounded array helper
+create(payload)
+update(id, payload)
+remove(id, { locale? })
+```
+
+## Generated React Query hooks
+
+Client-capable generated modules also expose hooks:
+
+```ts
+useGetById(...)
+useGetBySlug(...)
+useGetByField(...)
+useList(query)
+useInfiniteList(query)
+useGet(query)
+useCreate()
+useUpdate()
+useRemove()
+```
+
+Promise reads and hooks share the same query shape. `list()`/`useList()` returns `{ items, pageInfo }`; `useInfiniteList()` accumulates pages and exposes `items`, `hasMore`, `loadMore`, and `isLoadingMore`.
+
+Write inputs are plain JSON. Read values carry source metadata, so use the generated `ArticleInput` type for writes instead of sending an `Article` read model back.
+
+## Singleton API
+
+A schema with `isSingleton: true` generates:
+
+```ts
+get({ locale?, populate? })
+update(payload)
+useGet(options)
+useSuspenseGet(options)
+useUpdate()
+```
+
+It does not expose create, remove, list, or identity lookup methods.
+
+## Query selection
+
+Supported query keys: `limit` (1–100), `offset`, `search`, `sort`, `where`, `fields`, `populate`, and `locale`.
+
+Use explicit ordering whenever order matters:
+
+```ts
+Article.list({ sort: ['position', 'id'], limit: 20 });
+```
+
+Use scalar equality or operator objects in `where`:
+
+```ts
+Article.list({
+  where: {
+    featured: true,
+    views: { $gte: 100 },
+    title: { $contains: 'Next' },
+    cover: { $null: false },
+  },
+  sort: ['-publishedAt', 'title'],
+});
+```
+
+Operators: `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$contains`, `$startsWith`, and `$null`.
+
+Reference filters use target ID strings. To-many `$eq`/`$contains` means membership; `$in` means any listed target; `$ne`/`$nin` means none; `$null: true` means empty. Reference fields cannot be sorted.
+
+## Projection and population
+
+Keep arrays `as const` so TypeScript narrows the result:
+
+```ts
+const page = await Article.list({
+  fields: ['slug', 'title', 'author'] as const,
+  populate: ['author'] as const,
+});
+```
+
+Fimo always keeps `id`, `entryId`, `documentId`, and `locale`. Without `populate`, references are `{ id }`; with it, they become the target entry or `null`. Populate is depth-one and only accepts reference field names.
+
+When a named type is needed, use the generated result type rather than typing populated data as the base entry:
+
+```ts
+import type { ArticleResult } from '@/schemas/Article';
+
+type ArticleWithAuthor = ArticleResult<undefined, 'author'>;
+```
+
+## Localized and shared reads
+
+Localized types have one variant per locale. Framework providers or explicit query options supply the active locale. Shared types (`i18n.enabled: false`) are created once and returned in every locale context.
+
+Localized reference targets remain strict by default. Pass `localeFallbacks: true` only when the product deliberately wants the best available target variant (project default first); do not implement cross-locale fallback manually.

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

@@ -0,0 +1,5 @@
+# Source-tracked content values moved
+
+Load `references/ui.md` for `FimoString`, `FimoMedia`, and the complete value-to-renderer map.
+
+This compatibility pointer keeps older prompts valid while rendering guidance has one searchable home.

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

@@ -0,0 +1,48 @@
+# Rich text and entry payloads
+
+## Tiptap JSONContent
+
+Richtext values use Tiptap JSONContent, never raw HTML:
+
+```json
+{
+  "type": "doc",
+  "content": [
+    { "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "Title" }] },
+    {
+      "type": "paragraph",
+      "content": [
+        { "type": "text", "text": "Hello " },
+        { "type": "text", "marks": [{ "type": "bold" }], "text": "world" }
+      ]
+    }
+  ]
+}
+```
+
+Nodes: `doc`, `paragraph`, `heading`, `bulletList`, `orderedList`, `listItem`, `blockquote`, `codeBlock`, `horizontalRule`, `hardBreak`, `table`, `tableRow`, `tableHeader`, `tableCell`, `image`, and `iframe`.
+
+Marks: `bold`, `italic`, `underline`, `strike`, `code`, and `link`.
+
+Use semantic nodes instead of flattening long content into paragraphs. Render the returned value with the framework's `<RichText>` primitive so source metadata survives.
+
+## Entry payload
+
+CLI entry writes put every value, including the collection slug, under `data`:
+
+```json
+{
+  "data": {
+    "slug": "my-first-post",
+    "title": "My First Post",
+    "body": { "type": "doc", "content": [] },
+    "cover": { "source": "local", "url": "https://...", "alt": "Cover" }
+  }
+}
+```
+
+Do not put `slug` at the top level; unsupported top-level keys are stripped.
+
+Slugs should be lowercase, hyphenated, stable, meaningful, and unique per content type. Fimo slugifies the supplied candidate. If omitted, Fimo generates one, which is unsuitable for content with durable public URLs.
+
+For media fields, prefer assets uploaded or generated through Fimo. Load `fimo-cli/references/assets.md` or `fimo-cli/references/media.md` for those commands.

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

@@ -0,0 +1,122 @@
+# Content schemas
+
+Write one schema per `src/schemas/<Uid>.json`. The PascalCase filename must match `uid`.
+
+```json
+{
+  "uid": "Article",
+  "name": "Articles",
+  "i18n": { "enabled": true },
+  "fields": {
+    "title": { "type": "string", "required": true },
+    "summary": { "type": "text" },
+    "body": { "type": "richtext" },
+    "publishedAt": { "type": "date" },
+    "featured": { "type": "boolean" },
+    "cover": { "type": "media" },
+    "metadata": { "type": "json" },
+    "author": { "type": "reference", "target": "Author" },
+    "contributors": { "type": "reference", "target": "Author", "many": true }
+  }
+}
+```
+
+Required root keys: `uid`, `name`, and `fields`. Add `"isSingleton": true` for one document such as SiteSettings.
+
+## Locale policy
+
+- Omit `i18n` or use `{ "enabled": true }` for localized variants.
+- Use `{ "enabled": false }` for one shared document/entry across locales.
+- A top-level scalar or reference in a localized type may use `"i18n": false` for one shared field value, such as SKU or price.
+- Fields inside blocks inherit the owning entry locale and cannot declare `i18n`.
+
+## Reserved metadata
+
+Never declare `id`, `entryId`, `documentId`, `slug`, `locale`, `createdAt`, `updatedAt`, or `__fimo` in `fields`. Collections receive `slug` automatically; supply it when creating an entry, not in the schema.
+
+## Field types
+
+| Type        | Write shape                | Use                                      |
+| ----------- | -------------------------- | ---------------------------------------- |
+| `string`    | string                     | one-line text; add `options` for an enum |
+| `text`      | string                     | multiline plain text                     |
+| `richtext`  | Tiptap JSONContent         | formatted content                        |
+| `number`    | number                     | quantities and ordering fields           |
+| `boolean`   | boolean                    | flags                                    |
+| `date`      | ISO date string            | dates/timestamps                         |
+| `media`     | media object or array      | images, video, files                     |
+| `json`      | JSON                       | structured metadata                      |
+| `reference` | `{ "id": "..." }` or array | links to another schema                  |
+| `blocks`    | ordered object array       | nested/repeatable sections               |
+
+An enum string uses `options`; its optional `default` must be one of them:
+
+```json
+"layout": { "type": "string", "options": ["article", "video"], "default": "article" }
+```
+
+## Conditional fields
+
+Use `showIf` when every clause must match and `showIfAny` when one may match:
+
+```json
+{
+  "layout": { "type": "string", "options": ["article", "video"] },
+  "body": { "type": "richtext", "showIf": { "field": "layout", "equals": "article" } },
+  "videoUrl": { "type": "string", "required": true, "showIf": { "field": "layout", "equals": "video" } }
+}
+```
+
+Conditions reference sibling boolean, number, or enumerated string fields. Hidden fields keep stored values but are not validated; generated types therefore keep conditional fields optional. Conditions do not chain.
+
+## Blocks
+
+Use `schema.fields` for one repeated shape and `schema.oneOf` for selectable variants:
+
+```json
+"sections": {
+  "type": "blocks",
+  "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 } }
+      }
+    ]
+  }
+}
+```
+
+- Blocks always read/write arrays; `max: 1` means `[]` or `[item]`.
+- Fimo adds stable `_key` values; `oneOf` items also receive `_type`.
+- Nest blocks up to seven levels. One `oneOf` supports up to 40 variants and one blocks field up to 200 items.
+- Nested scalar values use the same source-tracked value type as top-level fields.
+- Nested reference population and filtering are not supported.
+
+## References
+
+Use fixed `target` references whenever every value has one type. Use `many: true` for to-many fields. Values use stable document `id`, never `entryId`; use `null` or `[]` when empty. To-many array order is preserved.
+
+Use `targets: ["Post", "Video"]` instead of `target` only for genuinely polymorphic slots. Populated polymorphic values expose `$type` for narrowing. They cannot currently be filtered.
+
+## Safe transitions
+
+After writing or changing `src/schemas/<Uid>.json`, run `fimo schemas push <Uid>` before building against that schema. The push validates the JSON, generates its public clients, and updates the linked environment.
+
+- Optional additions and label changes preserve entries.
+- Required additions need a valid default when existing objects require backfill.
+- Removing a field or block variant removes only that value.
+- String/text changes and safe primitive conversions preserve values.
+- Fixed-target relation renames preserve links when the target remains the same; target changes clear them.
+- Preserve explicit nested renames with `--rename old.path=new.path`.
+- Failed migrations are atomic. There is no reset or data-loss flag.