fimo 0.8.0-staging.3 → 0.9.0-experimental.1

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

@@ -70,7 +70,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 +85,7 @@ if (model.fields) {
 function getTypeForField(field) {
   switch(field.type) {
     case 'string':
+    case 'text':
       return 'FimoString';
     case 'richtext':
       return 'FimoRichText';
@@ -102,6 +103,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 +113,7 @@ function getTypeForField(field) {
 function getInputTypeForField(field) {
   switch(field.type) {
     case 'string':
+    case 'text':
       return 'string';
     case 'richtext':
       return 'FimoRichTextContent';
@@ -129,10 +133,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-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:

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

@@ -67,7 +67,7 @@ Use `connect` for provider accounts, workspaces, OAuth installs, and API-key acc
 fimo integrations run firecrawl scrape --url https://example.com
 fimo integrations run firecrawl scrape --url https://example.com --formats markdown,summary,links
 fimo integrations run firecrawl scrape --url https://example.com --connection client-b
-fimo integrations run firecrawl search --query "Example Domain" --max-results 3
+fimo integrations run firecrawl search --query "Example Domain" --max-results 3 --include-domains example.com
 fimo integrations run firecrawl map --url https://example.com --limit 20
 fimo integrations run firecrawl crawl --url https://example.com --limit 3 --formats markdown
 fimo integrations run firecrawl monitor.create --name pricing --url https://example.com/pricing --schedule hourly
@@ -76,6 +76,10 @@ fimo integrations run firecrawl monitor.list
 
 Firecrawl execution supports `search`, `scrape`, `map`, `crawl`, and `monitor.*` lifecycle tools. The default scrape/crawl output format is `markdown`; supported formats are `markdown`, `summary`, `links`, `images`, `html`, and `raw-html`.
 
+Firecrawl search returns query-relevant excerpts by default. Use them for direct, sourced answers and scrape only when
+full context or exact wording is needed. Search can be narrowed with source, category, domain, freshness, location,
+and country options; see the Firecrawl reference for the full command shape.
+
 Use `--connection <alias>` only for one run when a named connection already exists. It does not change the project default
 integration setup.