fimo 0.12.0 → 0.13.0-staging.1

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

@@ -1,67 +1,57 @@
 ---
 name: fimo-code
 description: >-
-  How to write code in a Fimo project — the npm package surface. Load when
-  writing JSX that renders schema content, defining schemas or forms (JSON),
-  using `t()` for labels, plugging media into `fimo/ui` components,
-  or applying the project's code conventions. CLI commands and workflows
-  (push, deploy, sync, etc.) live in the `fimo-cli` skill.
+  Write schema-first application code with the installed `fimo` package.
+  Load when declaring content schemas or forms, using generated content
+  clients, rendering Fimo primitives, reading labels, or integrating Fimo
+  with Next.js, React Router, Vite, or another application framework. CLI
+  commands and operational workflows live in the `fimo-cli` skill.
 ---
 
-# Fimo
+# Fimo code
 
-You are writing code in a Fimo project — a content + media + forms + analytics platform for React websites with a CMS dashboard. This skill describes the **`fimo` npm package surface** as installed in this specific project: what's exported from `fimo`, `fimo/ui`, `fimo/vite`; the JSON shapes you write; the generated React Query hooks and Zod schemas you import; and the code conventions for using them.
+Use this skill for code that consumes the version-locked `fimo` package in the current project. Fimo connects content, labels, media, forms, editing metadata, and hosting to an application; the application continues to own routing, locale resolution, links, document language/direction, and SEO.
 
-This skill is version-locked to this project's installed `fimo` package — the shapes here match what your code can actually use.
+Use the project-installed CLI for local inspection, code generation, and validation (`pnpm exec fimo`, `npm exec fimo`, `yarn fimo`, or `bunx --no-install fimo`, matching the lockfile). If that runner tries to install packages even though dependencies already exist, invoke the local `node_modules/.bin/fimo` executable instead. Load the `fimo-cli` skill for remote operational workflows such as schema pushes, label writes, entry mutations, and deploys. If the skill is not already available locally, fetch it with `npx fimo@latest skills get fimo-cli`.
 
-For CLI commands and workflows (creating a project, pushing schemas/forms, deploying, managing labels, etc.), the **`fimo-cli`** skill is the source of truth. Run every CLI command as `npx fimo@latest <command>` (always the latest, no global install). Load it on demand with `npx fimo@latest skills get fimo-cli`.
+## Orient before writing
 
-## Critical: NEVER hardcode user-facing things
+1. Run the project-installed `fimo describe --json` in a linked project and read `data.framework.slug`, schemas, locales, and tree. If the project is not linked yet, inspect `package.json` and the app directory instead.
+2. Load only the references required by the task.
+3. Load the framework reference before choosing imports, providers, or rendering APIs.
 
-This is the load-bearing rule for every code change. **Fimo's whole point is that content editors edit content in the dashboard, not in code.** Anything hardcoded breaks that.
+Framework routing:
 
-- **Content** (posts, products, pages, lists, anything structured) → declare a schema, render collections with generated `useList()` or `useInfiniteList()` hooks + `fimo/ui` components. Use `useGet()` only for legacy fixed array queries. **Never** write `const posts = [...]` in JSX.
-- **Strings** (labels, CTAs, headings, descriptions, any visible text) → wrap in `t('key')` and create the default-locale value with `fimo labels set`. Use `--locale <locale>` only when intentionally writing a non-default locale. **Never** write `<h1>Welcome</h1>` directly — write `<Text value={t('home.title')} as="h1" />`.
-- **Media** (images, videos, files) → use `<Image>` / `<Video>` from `fimo/ui` for schema media, `<StaticImage>` for hard-coded URLs. **Never** use `<img src={...}>`.
-- **Forms** → use the generated Zod schema + `submitX` helper from `@/forms/<name>`. Never hand-roll fetch or validation.
+- `nextjs` or an `app/`, `src/app/`, `pages/`, or `src/pages/` tree → `references/frameworks/next.md`, then the matching App Router or Pages Router reference.
+- React Router framework mode (`react-router.config.ts`, `src/routes.ts`) → `references/frameworks/react-router.md`.
+- Vite + React without framework mode → `references/frameworks/vite-react.md`.
 
-If you find yourself about to hardcode anything user-facing, **stop and use the appropriate Fimo primitive instead.** For pushing the schema/form/asset to the backend, that's CLI territory — see the `fimo-cli` skill.
+## Durable content contract
+
+- Declare editor-managed content in `src/schemas/<Uid>.json`; the PascalCase filename must match `uid`.
+- Apply every schema change with `fimo schemas push <Uid>`; it validates the JSON, generates framework-specific clients, and updates the linked environment.
+- Import generated public modules; never edit generated `.ts`, `.client.ts`, `.types.ts`, or `index.ts` files.
+- Render tracked values with the framework's Fimo primitives so Studio can identify and edit their source.
+- Keep migration-only adapters (`Wrapped*`, private loaders, fallback stores) out of greenfield application code.
 
 ## Load only the references the task needs
 
 Each reference defines one package contract. Fetch it when the task reaches that surface; do not batch-load unrelated references:
 
-- `references/content.md` — schema JSON shape, field types, Tiptap nodes, generated React Query hooks
-- `references/forms.md` — form JSON spec, generated Zod + `submitX` helper
-- `references/assets.md` — `FimoMedia` shape, how to render assets
-- `references/labels.md` — `t()` helper, `useLabels()`, wrap rules
-- `references/locales.md` — locale routing helpers, `FimoLink`, custom-framework contract
-- `references/ui.md` — `fimo/ui` components + JSX code conventions + app code rules
-
-Workflow / CLI-side concerns (pushing schemas, generating images, managing labels, deploying) live in the **`fimo-cli`** skill's matching references.
-
-## Decision Tree (specific tasks)
-
-- **Setting up Fimo in a new project** — pick the framework:
-  - React Router framework mode (new projects use React Router 8) → `references/setup-react-router.md`
-  - Plain Vite + React (or upgrading a legacy v3 project) → `references/setup-plain-vite.md`
-- Writing schema JSON / picking field types / Tiptap richtext → `references/content.md`
-- Writing form JSON / generated form client / form code → `references/forms.md`
-- Plugging media into a component / `FimoMedia` shape → `references/assets.md`
-- ANY user-facing string in code → `references/labels.md`
-- Locale-aware routes, links, or framework adapters → `references/locales.md`
-- ANY JSX rendering schema content or `t()` output → `references/ui.md`
-- Major visual / redesign / hero section / brand → `references/design.md`
-
-## Anti-Patterns
-
-- **Hardcoding content in JSX** — `<h1>My Blog</h1>` + an array of posts in code. Use schemas + entries + `t()`.
-- **Raw HTML for schema content** — `<img src={post.coverImage.url}>` instead of `<Image value={post.coverImage}>`. The `fimo/ui` components carry metadata for inline editing in the admin.
-- **Raw `<a href>` for internal navigation** — causes full page reloads. Use `<FimoLink>` for locale-aware internal links or React Router `<Link>` when intentionally bypassing locale helpers. Reserve `<a>` for external links.
-- **Pulling stock photos from external URLs** — editors can't manage them. Use a Fimo media task such as `fimo image generate`.
-- **Editing generated `.ts` files** under `src/schemas/` or `src/forms/` — regenerate them through `fimo validate` or the matching push command.
-- **Writing raw HTML in `richtext` fields** — must be Tiptap JSONContent.
-- **Calling `t()` with a dynamic first argument** — the key must be a string literal so the extractor finds it.
-- **Decorating the disposable starter** — `src/pages/Index.tsx` is throwaway scaffolding. On first real generation, replace it entirely.
-- **Skipping legal pages** — `Privacy.tsx` + `Terms.tsx` are required for public sites; the template ships them.
-- **Showing Fimo branding** in the generated site unless the user explicitly asks for it.
+- Schema JSON, field types, blocks, references, `showIf` → `references/content/schema.md`
+- Richtext/Tiptap, entry payloads, slugs → `references/content/richtext.md`
+- Generated clients: `list`, `getBySlug`, `useList`, `where`, `sort`, `fields`, `populate` → `references/content/clients.md`
+- Tracked rendering: `Text`, `RichText`, `Image`, `FimoString`, `FimoMedia` → `references/ui.md`
+- Forms: JSON spec, generated Zod schema, `submit*` helpers → `references/forms.md`
+- Media values, `<Image>`, `<StaticImage>` → `references/assets.md`
+- Static editable copy: `t()`, `useLabels`, `getLabels` → `references/labels.md`
+- Locale ownership and framework handoff → `references/locales.md`
+- Major visual work → `references/design.md`
+
+## Non-negotiable boundaries
+
+- Do not hardcode editor-owned collections, page content, labels, or media in JSX.
+- Do not hand-roll content API fetches when a generated client covers the read.
+- Do not hand-construct `FimoString`, `FimoMedia`, or other tracked values.
+- Do not replace an application's router, locale library, URL policy, or SEO integration merely to add Fimo.
+- Do not teach one framework's imports as universal package APIs.

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.