fimo 0.8.0 → 0.9.0-staging.1

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

@@ -0,0 +1,67 @@
+---
+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.
+---
+
+# Fimo
+
+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.
+
+This skill is version-locked to this project's installed `fimo` package — the shapes here match what your code can actually use.
+
+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`.
+
+## Critical: NEVER hardcode user-facing things
+
+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.
+
+- **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.
+
+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.
+
+## When starting code work, load these references up front
+
+These define the package surface for the load-bearing primitives. **Read all six before generating significant code:**
+
+- `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.

package/assets/skills/{fimo → fimo-code}/references/content.md

@@ -13,6 +13,7 @@ This file covers the **package surface**: the JSON shape you write, the generate
   "i18n": { "enabled": true },
   "fields": {
     "title": { "type": "string" },
+    "summary": { "type": "text" },
     "body": { "type": "richtext" },
     "publishDate": { "type": "string" },
     "featured": { "type": "boolean" },
@@ -45,19 +46,76 @@ 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               |
-| `reference` | `{ "id": "..." }`, `null`, or an array of reference objects when `many: true` | References to another schema      |
+| 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 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.
 
+## 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 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.
+- 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.
@@ -102,16 +160,27 @@ Entry payload example:
 
 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 fields and changing labels preserve entries.
-- Removing a field removes only that field's values.
+- 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.
-- A many-to-one change, reference target change, scalar type change, or scalar/reference change clears only the changed field.
+- 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-singleton removes that type's entries and cleans references to those documents.
 - 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.
 
-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.
+Choose by editing intent:
 
-**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).
+- 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)
 
@@ -202,6 +271,7 @@ interface BlogPost {
     contentType: string;
   };
   title: FimoString;
+  summary: FimoString;
   body: FimoRichText;
   coverImage: FimoMedia;
   publishDate: FimoString;
@@ -391,6 +461,7 @@ The entry objects a hook returns are **not** plain JS values. The generated clie
 | 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`                                           |

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

@@ -6,9 +6,9 @@ description: >-
   Triggers: "in Fimo Studio", "in the dashboard", "in the web app",
   "how do I X in the UI", or screenshots of the dashboard. Topics
   covered: dashboard content and CMS, publishing from the dashboard,
-  dashboard SEO/domain settings, visual editing, version history UI,
-  dashboard sharing/billing, and dashboard chat. Never describe UI
-  locations, buttons, or panels from memory — always read the relevant
+  dashboard SEO/domain settings, outbound webhooks, visual editing, version
+  history UI, dashboard sharing/billing, and dashboard chat. Never describe
+  UI locations, buttons, or panels from memory — always read the relevant
   reference file first.
 ---
 
@@ -37,6 +37,7 @@ Read the relevant reference file when the user's question matches a topic.
 | AI Chat                  | references/ai-chat.md                   | "What can the AI do?", "How do I give context?"       |
 | Code Editor              | references/code-editor.md               | "How do I edit code?", "Where are my files?"          |
 | SEO Settings             | references/seo-settings.md              | "How do I set up SEO?", "Favicon, title, share image" |
+| Webhooks                 | references/webhooks.md                  | "React to forms", "Send events to another service"    |
 | Preview & Responsive     | references/preview-and-responsive.md    | "How does it look on mobile?", "How do I test sizes?" |
 | Visual Editing           | references/visual-editing.md            | "Can I edit visually?", "How do I change colors?"     |
 | Version History          | references/version-history.md           | "How do I undo?", "How do I go back?"                 |
@@ -53,6 +54,7 @@ Read the relevant reference file when the user's question matches a topic.
 | Custom domains          | Publishing (must publish first), Billing (premium required)                    |
 | Adding images           | Media Library, AI Chat, Edit Mode                                              |
 | Content/CMS             | AI Chat, Media Library                                                         |
+| Webhooks                | Project secrets, Forms, Publishing, Agents                                     |
 | Visual changes          | Edit Mode (quick tweaks), AI Chat (bigger changes), Code Editor (full control) |
 | Something went wrong    | Version History, AI Chat                                                       |
 | Working with others     | Sharing, Collaboration                                                         |

package/assets/skills/fimo-studio/references/cms.md

@@ -42,7 +42,7 @@ When you open a Collection, the entry list provides several tools:
 2. Click the **+** (plus) icon button at the top of the Collection (labeled **New entry** on hover). If the Collection is empty, use the **Create entry** button in the center of the empty state instead.
 3. Fill in the form fields (text, images, dates, whatever the collection defines).
 
-Changes save automatically as you fill in each field (the save is debounced), so there is no Save button. The save status appears in the top bar (Saving / Saved). The entry is now part of your Collection. If the Collection is wired to a page on your site, the new content shows up automatically.
+Changes save automatically as you fill in each field (the save is debounced), so there is no Save button. The save status appears in the top bar (Saving / Saved). An incomplete new entry waits until its required fields are valid before it becomes part of the Collection. If the Collection is wired to a page on your site, new content shows up automatically.
 
 ## Editing an Entry
 
@@ -51,6 +51,14 @@ Changes save automatically as you fill in each field (the save is debounced), so
 
 Your edits save automatically as you change each field (the save is debounced), so there is no Save button. Watch the top bar for the save status (Saving / Saved). The entry editor's only header actions are delete (trash icon) and copy link.
 
+If a field is invalid, the editor keeps the change unsaved and pins a status bar below the header. Choose **Review issues** to jump to the first invalid field, then **Next issue** to move through the remaining fields. Collapsed blocks open automatically. Once every issue is fixed, the editor confirms that all fields are valid and resumes saving.
+
+## Editing Text
+
+- Short text such as titles, names, and slugs uses one compact line.
+- Plain multiline text such as summaries and descriptions starts taller and grows as you write.
+- Formatted content uses the rich-text editor for headings, links, lists, and media.
+
 ## Bulk Operations
 
 Need to update or remove several entries at once?

package/assets/skills/fimo-studio/references/webhooks.md

@@ -0,0 +1,42 @@
+# Webhooks
+
+> **Beta:** Test each destination and review its delivery history before depending on it in production.
+
+Webhooks send project activity to an external HTTPS endpoint. Use them for focused reactions such as adding a waitlist submission to an email tool, notifying Slack after a publish, or starting a GitHub workflow after an agent review.
+
+Only project members with Full Access can see Webhooks in Settings or manage its destinations and delivery history.
+
+## Create one
+
+1. Open the project and choose **Settings**.
+2. Select **Webhooks**.
+3. Choose **New webhook**.
+4. Name it, select one event, and enter the destination URL.
+5. Optionally narrow form, agent, media, or entry events with the filter shown for that event.
+6. Review the request and select **Save**.
+
+The event groups are Entries, Forms, Publish, Agents, Analytics, and Media. Webhooks belong to the project, with up to 20 configurations. They listen to main by default or can include every environment.
+
+Entry webhooks show **Combine rapid changes**. The default waits 5 seconds after direct editing stops and sends one delivery with the combined changes. Immediate, 30-second, and 1-minute windows are also available. Bulk edits and environment merges already produce batches and send immediately.
+
+## Configure the request
+
+The default payload is the complete Fimo event, including its type, project, environment, timestamp, and event-specific data. Keep this when the destination can accept it.
+
+Choose **Custom template** when a service expects a specific JSON shape. Use **Insert variable** to pick fields for the selected event. Variables use paths such as `{{ event.data.submission.data.email }}`. The preview catches invalid JSON and missing variables before save.
+
+When Studio recognizes a Resend, Slack, or GitHub URL, it offers a request setup for that service. The suggestion never changes the request automatically. Accept it to prefill relevant headers and JSON, then review every field.
+
+## Add authentication
+
+Under **Headers**, add a header name and type any non-secret prefix, such as `Bearer `. Choose **Insert secret** to select an existing project secret or create one without leaving the webhook editor. Creating a secret never replaces an existing secret with the same name; select the existing secret instead. Fixed values are suitable only for non-sensitive headers.
+
+Fimo signs requests by default. Save the signing secret shown after creation so a custom receiver can verify `X-Fimo-Signature`. Rotate it from the webhook configuration if it is exposed.
+
+## Test and monitor
+
+Use **Send test** before depending on a workflow. Tests use documented sample data and travel through the same delivery path as real events.
+
+Open **Deliveries** to see the event ID, masked destination, request metadata and payload excerpt, queue message ID, status, HTTP response, duration, and individual attempts. Fimo automatically retries temporary failures. After all automatic retries are exhausted, open the failed delivery and choose **Retry now**. A delivery accepts up to five manual retries.
+
+Destination credentials are masked in configuration and delivery details. A successful test means the destination returned a successful HTTP response; it does not necessarily mean the provider completed its downstream action, so check the provider when that distinction matters.

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-07-23T08:29:03.159Z",
+  "bundledAt": "2026-07-24T08:33:36.585Z",
   "cliVersion": "0.8.0",
   "external": [
     "oxc-parser",