fimo 0.8.0 → 0.9.0-experimental.10

package/assets/agent-templates/content-translator/scripts/write-locale-files.ts

@@ -0,0 +1,66 @@
+/**
+ * Tool: write-locale-files
+ *
+ * For locale-keyed JSON files in `src/locales/<locale>.json`, fill in
+ * missing keys from the default-locale file using the configured
+ * translation provider. Run after translate-entries when projects mix
+ * CMS-driven copy with hardcoded i18n strings.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+
+interface Catalog {
+  [key: string]: string;
+}
+
+async function readCatalog(file: string): Promise<Catalog> {
+  try {
+    const text = await fs.readFile(file, 'utf8');
+    return JSON.parse(text) as Catalog;
+  } catch {
+    return {};
+  }
+}
+
+async function writeCatalog(file: string, catalog: Catalog): Promise<void> {
+  await fs.writeFile(file, JSON.stringify(catalog, null, 2) + '\n', 'utf8');
+}
+
+async function translate(text: string, _to: string): Promise<string> {
+  // Stub — provider-specific call.
+  return text;
+}
+
+async function main(): Promise<void> {
+  const defaultLocale = process.env.FIMO_DEFAULT_LOCALE ?? 'en';
+  const targetLocales = (process.env.FIMO_TARGET_LOCALES ?? '').split(',').filter(Boolean);
+  const localesDir = process.env.FIMO_LOCALES_DIR ?? 'src/locales';
+
+  const defaultFile = path.join(localesDir, `${defaultLocale}.json`);
+  const defaultCatalog = await readCatalog(defaultFile);
+
+  for (const target of targetLocales) {
+    const targetFile = path.join(localesDir, `${target}.json`);
+    const targetCatalog = await readCatalog(targetFile);
+    let dirty = false;
+
+    for (const [key, sourceValue] of Object.entries(defaultCatalog)) {
+      if (targetCatalog[key]) {
+        continue;
+      }
+      targetCatalog[key] = await translate(sourceValue, target);
+      dirty = true;
+    }
+
+    if (dirty) {
+      await writeCatalog(targetFile, targetCatalog);
+      console.log(`Wrote ${targetFile}`);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/assets/agents-starter/claude/settings.json

@@ -0,0 +1,19 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(fimo:*)",
+      "Bash(npx fimo:*)",
+      "Bash(pnpm:*)",
+      "Bash(pnpm dlx:*)",
+      "Bash(npx:*)",
+      "Bash(git status)",
+      "Bash(git status:*)",
+      "Bash(git diff)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git add:*)",
+      "Bash(git restore:*)",
+      "Bash(mkdir:*)"
+    ]
+  }
+}

package/assets/content-templates/hooks-template.eta

@@ -4,9 +4,11 @@
 <% if (model.isSingleton) { -%>
 import { createSingletonClient } from "fimo/ui";
 import type { SingletonContentClient } from "fimo/ui";
+import type { ContentSchema } from "fimo/ui";
 <% } else { -%>
 import { createContentClient } from "fimo/ui";
 import type { CollectionContentClient } from "fimo/ui";
+import type { ContentSchema } from "fimo/ui";
 <% } -%>
 
 import schema from "./<%= model.uid %>.json";
@@ -39,13 +41,13 @@ const client: SingletonContentClient<<%= model.pascal %>, <%= model.pascal %>Inp
   <%= model.pascal %>,
   <%= model.pascal %>Input
 >({
-  schema,
+  schema: schema as unknown as ContentSchema,
 <% } else { -%>
 const client: CollectionContentClient<<%= model.pascal %>, <%= model.pascal %>Input> = createContentClient<
   <%= model.pascal %>,
   <%= model.pascal %>Input
 >({
-  schema,
+  schema: schema as unknown as ContentSchema,
 <% } -%>
 <% if (model.referenceImports && model.referenceImports.length > 0) { -%>
   references: { <%= model.referenceImports.map((referenceImport) => referenceImport.pascal).join(", ") %> },

package/assets/content-templates/types-template.eta

@@ -8,6 +8,7 @@
  *          }
  */
 %>
+// @ts-nocheck — generated internals are exempt from the app's own tsconfig strictness; exported types still work
 // AUTO-GENERATED ⚠️ – do not edit by hand
 import { type Fields, type FimoBoolean, type FimoMedia, type FimoPolymorphicReference, type FimoReference, type FimoRichText, type FimoRichTextContent, type FimoString, type Populate, type PopulatedResult, type ProjectedWithPopulate, type Query, type Sort, type Where, type WithReferences } from "fimo/ui";
 <%
@@ -70,7 +71,7 @@ if (model.fields) {
   Object.entries(model.fields).forEach(([key, field]) => {
     const type = getInputTypeForField(field);
 -%>
-  <%= key %><%= field.required ? '' : '?' %>: <%= type %>;
+  <%= key %><%= isRequiredField(field) ? '' : '?' %>: <%= type %>;
 <%
   });
 }
@@ -85,6 +86,7 @@ if (model.fields) {
 function getTypeForField(field) {
   switch(field.type) {
     case 'string':
+    case 'text':
       return 'FimoString';
     case 'richtext':
       return 'FimoRichText';
@@ -102,6 +104,8 @@ function getTypeForField(field) {
       const raw = Array.isArray(field.targets) && field.targets.length > 0 ? 'FimoPolymorphicReference' : 'FimoReference';
       return field.many ? `${raw}[]` : `${raw} | null`;
     }
+    case 'blocks':
+      return getBlocksType(field, false);
     default:
       return 'any';
   }
@@ -110,6 +114,7 @@ function getTypeForField(field) {
 function getInputTypeForField(field) {
   switch(field.type) {
     case 'string':
+    case 'text':
       return 'string';
     case 'richtext':
       return 'FimoRichTextContent';
@@ -129,10 +134,71 @@ function getInputTypeForField(field) {
       const raw = Array.isArray(field.targets) && field.targets.length > 0 ? 'FimoPolymorphicReference' : 'FimoReference';
       return field.many ? `${raw}[]` : `${raw} | null`;
     }
+    case 'blocks':
+      return getBlocksType(field, true);
     default:
       return 'unknown';
   }
 }
+
+function getNestedFieldType(field, input) {
+  switch(field.type) {
+    case 'string':
+    case 'text':
+      return 'string';
+    case 'richtext':
+      return 'FimoRichTextContent';
+    case 'number':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'date':
+      return 'string';
+    case 'json':
+    case 'media':
+      return 'Record<string, unknown>';
+    case 'reference': {
+      const raw = Array.isArray(field.targets) && field.targets.length > 0 ? 'FimoPolymorphicReference' : 'FimoReference';
+      return field.many ? `${raw}[]` : `${raw} | null`;
+    }
+    case 'blocks':
+      return getBlocksType(field, input);
+    default:
+      return 'unknown';
+  }
+}
+
+function getBlockObjectType(fields, input, metadata = {}) {
+  const properties = [];
+  if (metadata.key) {
+    properties.push(`_key${input ? '?' : ''}: string`);
+  }
+  if (metadata.type) {
+    properties.push(`_type: "${metadata.type}"`);
+  }
+  for (const [key, field] of Object.entries(fields || {})) {
+    properties.push(`${key}${isRequiredField(field) ? '' : '?'}: ${getNestedFieldType(field, input)}`);
+  }
+  return `{ ${properties.join('; ')} }`;
+}
+
+function getBlocksType(field, input) {
+  const schema = field.schema || {};
+  let item;
+  if (Array.isArray(schema.oneOf)) {
+    item = schema.oneOf
+      .map((variant) => getBlockObjectType(variant.fields, input, { key: true, type: variant.uid }))
+      .join(' | ') || 'never';
+    item = `(${item})`;
+  } else {
+    item = getBlockObjectType(schema.fields, input, { key: true });
+  }
+  return `${item}[]`;
+}
+
+function isRequiredField(field) {
+  return Boolean(field.required || (field.type === 'blocks' && Number(field.min || 0) > 0));
+}
 -%>
 
 export interface <%= model.pascal %>References {

package/assets/skills/fimo/SKILL.md

@@ -14,7 +14,7 @@ You are writing code in a Fimo project — a content + media + forms + analytics
 
 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). If `fimo-cli` isn't loaded for your AI tool, register it with `npx fimo@latest skills install --mode=copy`.
+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 <command>` when the project declares a `fimo` dependency (it pins the version matching the project's backend); otherwise use `npx fimo@latest`. If `fimo-cli` isn't loaded for your AI tool, register it with `npx fimo skills install --mode=copy`.
 
 ## Critical: NEVER hardcode user-facing things
 

package/assets/skills/fimo/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/references/translations.md

@@ -0,0 +1,75 @@
+# Translations — package surface
+
+> For the CLI workflow (`fimo validate`, when to run validation, what sync does), see **`fimo-cli/references/translations.md`**.
+
+This file covers the **package surface**: the `t()` helper, the `useTranslations()` hook, and the code-side rules for wrapping strings.
+
+## The rule
+
+Every piece of **user-facing static text** in the app (page titles, button labels, nav items, form placeholders, empty-state copy, alt text, meta tags) MUST be wrapped in `t('key', 'Default text')`.
+
+Raw string literals in JSX are a bug — they won't show up in the Fimo admin as editable content and won't be translatable. **Hard-coded JSX text (`<h1>Welcome</h1>`) skips the entire i18n + inline-editing pipeline and becomes invisible to the editor.**
+
+## Setup (already wired)
+
+Translations are wired automatically by the `fimo/vite` build plugin. It exposes a `virtual:translations` module sourced from `<projectRoot>/translations/en.json`, and `useTranslations()` reads from that virtual module — there's no provider to add or remove. The app entry is `src/root.tsx`, which wraps the app in `<FimoProviders>` from `fimo/react-router`; you never import `translations/en.json` in app code. Pages and components only call `useTranslations()`.
+
+## Usage
+
+```tsx
+import { useTranslations, Text } from 'fimo/ui';
+
+export function Hero() {
+  const { t } = useTranslations();
+  return (
+    <section>
+      <h1>
+        <Text value={t('hero.title', 'Welcome to Acme')} />
+      </h1>
+      <p>
+        <Text value={t('hero.subtitle', 'The fastest way to ship your idea.')} />
+      </p>
+      <input placeholder={String(t('hero.emailPlaceholder', 'you@example.com'))} />
+      <img alt={String(t('hero.imageAlt', 'Team collaborating'))} src="..." />
+    </section>
+  );
+}
+```
+
+- `t(key, default)` returns a `FimoString` (wrapped for source tracking). Render it via `<Text value={...} />` inside JSX.
+- For HTML attributes (`placeholder`, `alt`, `title`, `aria-label`) cast with `String(t(...))` — the attribute can't accept a `FimoString` object directly.
+
+## Hard rules (enforced by the pre-build linter)
+
+**The first argument to `t()` MUST be a string literal.** Dynamic keys break source tracking and fail the lint step.
+
+```tsx
+// ❌ BAD — variable key
+t(item.key, item.label);
+
+// ❌ BAD — template with expression
+t(`nav.${page}`, 'Page');
+
+// ✅ GOOD — put the t() call where the literal lives
+const items = [{ label: t('nav.home', 'Home') }, { label: t('nav.about', 'About') }];
+items.map((item) => <li>{item.label}</li>);
+```
+
+## Key naming
+
+- Dot-namespaced, lowercase, kebab or camelCase leaves: `hero.title`, `nav.signIn`, `footer.copyright`, `errors.required`.
+- Namespace by **page/section/component**, not by feature (`contact.form.submitLabel`, not `forms.contactSubmit`).
+- The default (second arg) is the English copy — make it final, not a TODO; it ships to production if no translation exists for the active locale.
+
+## What NOT to translate
+
+- Dynamic content from entries or forms — that's already stored in the DB (content via schemas, submissions via forms).
+- Content-type field values rendered via `fimo/ui` primitives (`<Text>`, `<RichText>`, …) — those carry their own admin-editing metadata.
+- Purely decorative / non-text (icons, logos).
+- Developer-only strings (`console.log`, error messages thrown for debugging).
+
+## Rule of thumb
+
+If a human reader sees the text AND the project owner might want to reword it in the admin, it goes through `t()`. When in doubt: wrap it.
+
+After adding or changing `t()` calls, run `fimo validate` (or rely on `fimo deploy` doing it). See `fimo-cli/references/translations.md`.

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

@@ -4,8 +4,9 @@ description: >-
   The `fimo` CLI scaffolds and manages Fimo projects from the command line.
   Load when the user wants to create a new Fimo project, build content
   (schemas, entries, forms, media, labels/locales), deploy a site, manage
-  custom domains, check site traffic/analytics, invite collaborators, inspect
-  AI credits, report a failing or slow Fimo API, rejected documented argument,
+  custom domains, configure outbound webhooks and event-driven integrations,
+  check site traffic/analytics, invite collaborators, inspect AI credits,
+  report a failing or slow Fimo API, rejected documented argument,
   undocumented workaround, missing capability that blocks work, forces a
   fragile or heavily manual workaround, or would materially accelerate a
   recurring workflow, or other Fimo platform problem to support, log in or
@@ -21,6 +22,8 @@ This skill describes **what the CLI does and the workflows it drives**. For the
 
 Use `fimo <command> --help` for full flag details on any command.
 
+> **Webhooks are beta.** Verify a destination with `fimo webhooks test <id> --wait` and inspect its delivery history before depending on it in production.
+
 ## Running the CLI: always `npx fimo@latest`
 
 Run every command as **`npx fimo@latest <command>`**. It always fetches the latest CLI — no install, nothing to keep up to date, and it can't fall behind and get blocked. Do **not** install `fimo` globally.
@@ -85,6 +88,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Get the preview URL / open the preview / what's the URL for this env / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.md`
 - "Schedule a command / cron / nightly publish / recurring checks / `fimo schedules`" → `references/schedules.md`
 - "Set env vars / configure API keys / add project secrets / local `.env.local` / `fimo vars` / `fimo secrets`" → `references/project-vars-and-secrets.md`
+- "React to form submissions / publish changes / agent runs / analytics reports / media activity / send events to Resend, Slack, GitHub, Zapier, or an HTTP endpoint / configure or debug outbound webhooks" → `references/webhooks.md`
 - "Enable provider tools / integrations / API key connection for a provider / agent integration access" → `references/integrations.md`
 - "Firecrawl / scrape a public website / competitor research / agent web research" → `references/integrations.md` **+ load `references/integrations/firecrawl.md`**
 - "Check credits / credit balance / can I keep using AI / billing credits / running low / how many credits are left" → `references/credits.md`

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

@@ -20,6 +20,8 @@ Steps 1, 3, and 5 reference the project skill (`fimo`) for shape and React API.
 
 ```bash
 fimo schemas push [TypeName]      # push JSON to API (create or update). Omit TypeName to push all.
+fimo schemas push <TypeName> --rename old.path=new.path
+                                  # preserve a renamed field; repeat --rename for multiple fields.
                                   # Pushing all sends every schema as ONE atomic batch, so types that
                                   # reference each other (even cycles) can be added in a single push.
                                   # Files not present are never deleted — use `schemas delete` for that.
@@ -32,11 +34,11 @@ The command is `fimo schemas` (plural). There is no singular `fimo schema` alias
 
 All commands accept `-C, --cwd <dir>` to point at a different project directory.
 
-Schema transitions are automatic. Adding fields and changing labels preserve content. Removing a field removes only that field's values. One-to-many reference changes wrap existing references in arrays. Field type changes, scalar/reference changes, reference target changes, and many-to-one changes clear only the changed field. Collection-to-singleton removes that type's entries and cleans inbound references; singleton-to-collection preserves its entry. There are no reset or data-loss flags: changing the schema is the migration request. Run `fimo validate` after pushing to verify the regenerated client and whole project.
+Schema transitions are automatic. Adding optional fields and changing labels preserve content. A new required field backfills its `default` only where existing values need it; the push fails safely when no default can satisfy existing content. Removing a nested field or block variant removes only those values. `string` and `text` preserve values in both directions. Other primitive changes convert safe values and reject unsafe ones without changing the schema or entries. Lowering block `max` trims from the end; raising `min` fills from the blocks `default` templates. A reference target change clears its connections. Use repeatable `--rename old.path=new.path` arguments when a field moved by name so the one-time migration preserves its values; the operation is not stored in schema JSON. Collection-to-singleton removes that type's entries and cleans inbound references; singleton-to-collection preserves its entry. Run `fimo validate` after pushing.
 
 ## Entries CLI commands
 
-Entries are NOT JSON-file-driven. Create/update them via CLI.
+Use singular commands for one entry. Bulk create and per-entry bulk update also accept JSON files or stdin.
 
 ```bash
 fimo entries create <TypeName> --body '<json>'
@@ -46,6 +48,11 @@ fimo entries list <TypeName> --locale es
 fimo entries get <TypeName> <id> [--locale es]
 fimo entries update <TypeName> <id> [--locale es] --body '<json>'
 fimo entries delete <TypeName> <id> [--locale es]
+fimo entries query (--sql '<select>' | --file <path> | --stdin)
+fimo entries bulk-create <TypeName> (--body '<json-array>' | --file <path> | --stdin)
+fimo entries bulk-update <TypeName> (--ids <id1>,<id2> | --where '<json>') --body '<json>'
+fimo entries bulk-update <TypeName> (--file <path> | --stdin)
+fimo entries bulk-delete <TypeName> (--ids <id1>,<id2> | --where '<json>') [--locale es]
 ```
 
 `--body` is a **required** option on `create` and `update`. Its JSON shape (where `slug` goes, how `media` fields look, Tiptap richtext format) lives in `fimo/references/content.md`. **Always read that first before constructing an entry payload — slug must be inside `data`, media has a specific shape, richtext must be Tiptap JSONContent.**
@@ -74,6 +81,58 @@ Polymorphic references declare `targets: ["Post", "Product"]` instead of `target
 
 In generated React code, the equivalent is `populate: ['author', 'contributors'] as const` in the schema hook/query params. Let hooks infer the result when possible; if a named TypeScript shape is needed, use the generated `BlogPostResult<TFields, TPopulate>` type documented in `fimo/references/content.md`. Writes use the separate generated `BlogPostInput` type.
 
+### Read-only SQL
+
+Use `entries query` when SQL is clearer than list filters, especially for grouping and aggregation. It requires content view access, accepts one `SELECT` statement, can only read the `entries` table, and supports common aggregation, JSON, text, date, and window functions. Queries time out after five seconds and return at most 1,000 rows.
+
+**Never use SQL for content writes.** SQL writes are rejected because they would bypass schema validation, locale and reference handling, content-change events, and current or future webhooks. Use `entries create`, `entries update`, `entries delete`, or their bulk variants so every mutation follows the content domain path.
+
+```bash
+fimo entries query --sql "SELECT content_type, count(*) AS total FROM entries GROUP BY content_type"
+fimo entries query --sql "SELECT document_id AS id, data->>'title' AS title FROM entries WHERE content_type = 'BlogPost' LIMIT 20"
+fimo entries query --file query.sql
+cat query.sql | fimo entries query --stdin
+```
+
+SQL exposes the raw internal representation. `document_id` is the stable ID used by `fimo entries`, content tools, references, and the API. `id` is the internal ID of one exact locale variant. When query results will feed another Fimo command or tool, select `document_id AS id`; use `locale` to select a variant.
+
+The available columns are `id`, `document_id`, `content_type`, `locale`, `slug`, `data`, `created_at`, and `updated_at`. Schema fields live inside the JSONB `data` column. If a safe read is blocked because a SQL function is unavailable, tell the user which function is missing and follow `references/support.md` to prepare a support report for approval. Do not bypass the restriction with a write.
+
+### Bulk mutations
+
+`bulk-create` takes an array of regular create bodies. Inline JSON, a file, and stdin all carry the same array shape:
+
+```bash
+fimo entries bulk-create BlogPost --body '[{"data":{"title":"First"}},{"data":{"title":"Second"},"locale":"es"}]'
+fimo entries bulk-create BlogPost --file posts.json
+cat posts.json | fimo entries bulk-create BlogPost --stdin
+```
+
+`bulk-update` applies the regular update body to explicit IDs or the normal `--where` filter:
+
+```bash
+fimo entries bulk-update BlogPost --ids <id1>,<id2> --body '{"data":{"status":"published"}}'
+fimo entries bulk-update BlogPost --where '{"status":"draft"}' --body '{"data":{"status":"published"}}'
+```
+
+For different changes per entry, `--file` and `--stdin` accept an array of `{ "id", "body" }` records:
+
+```json
+[
+  { "id": "<id1>", "body": { "data": { "status": "published" } } },
+  { "id": "<id2>", "body": { "data": { "featured": true } } }
+]
+```
+
+```bash
+fimo entries bulk-update BlogPost --file updates.json
+cat updates.json | fimo entries bulk-update BlogPost --stdin
+fimo entries bulk-delete BlogPost --ids <id1>,<id2>
+fimo entries bulk-delete BlogPost --where '{"archived":true}'
+```
+
+Each bulk request handles at most 1,000 entries. Missing requested IDs do not fail valid work: the CLI prints a warning, and `--json` includes both a top-level `warnings` array and the exact IDs in `data.meta.missing`. Bulk writes use the same validation, locale, reference, and content-change paths as singular entry writes. They apply entries one at a time. Recoverable create and update errors report how many earlier entries were already changed.
+
 For reference schema JSON and entry value shape, load `fimo/references/content.md` § Reference fields. The short version:
 
 ```json

package/assets/skills/fimo-cli/references/integrations/firecrawl.md

@@ -2,7 +2,7 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-Use Firecrawl when an agent needs to inspect public websites: landing-page research, competitor structure analysis, migration prep, link extraction, and factual page snapshots. Do not use Firecrawl for private URLs, logged-in websites, or content the user has not asked you to fetch.
+Use Firecrawl when an agent needs to research or inspect public websites: direct web answers, landing-page research, competitor structure analysis, migration prep, link extraction, and factual page snapshots. Do not use Firecrawl for private URLs, logged-in websites, or content the user has not asked you to fetch.
 
 Current execution support is `search`, `scrape`, `map`, `crawl`, and `monitor.*`.
 
@@ -47,6 +47,20 @@ Search the web:
 fimo integrations run firecrawl search --query "Example Domain" --max-results 3
 ```
 
+Search returns query-relevant excerpts with their source URLs. Narrow results when the request names a site, recency,
+source type, category, or geography:
+
+```bash
+fimo integrations run firecrawl search --query "latest React release" --sources web,news --freshness week
+fimo integrations run firecrawl search --query "Firecrawl search API" --include-domains firecrawl.dev --categories research
+fimo integrations run firecrawl search --query "Barcelona developer events" --location "Barcelona, Spain" --country ES
+```
+
+Search options are `--sources web,news,images`, `--categories github,research,pdf`, `--include-domains`,
+`--exclude-domains`, `--freshness hour|day|week|month|year`, `--location`, `--country`,
+and `--no-highlights`. Do not combine `--include-domains` and `--exclude-domains`. Query-relevant highlights are on by
+default.
+
 Default markdown scrape:
 
 ```bash
@@ -179,10 +193,12 @@ fimo deploy
    If they bring a key, run `fimo integrations connect firecrawl --name <name> --token-stdin`, then
    `fimo integrations enable firecrawl --connection <name>`.
 6. For one-off research, pick the smallest action that answers the question:
-   - `search` to discover pages.
-   - `scrape` to read one known page.
+   - `search` to get query-relevant excerpts and source URLs.
+   - `scrape` to read one known page when the excerpt lacks context or exact wording matters.
    - `map` to collect URLs from one site.
    - `crawl --limit <small>` to read several pages.
+     Treat search excerpts as concise evidence for straightforward questions. Scrape the source for full context,
+     exact quotations, implementation details, ambiguous claims, or high-stakes verification.
 7. For a project agent, update `integrations`, validate, preview with `fimo agents integrations <agent>`, then deploy.
 8. Keep findings in the agent report or task output; do not write scraped content into source files unless the user asks.
 
@@ -204,7 +220,7 @@ fimo integrations run firecrawl scrape --url https://competitor.example --format
 Find likely source pages:
 
 ```bash
-fimo integrations run firecrawl search --query "acme pricing page" --max-results 5 --json
+fimo integrations run firecrawl search --query "acme pricing page" --max-results 5 --include-domains acme.example --json
 ```
 
 Collect a simple URL map: