fimo 0.8.0 → 0.9.0-staging.1

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

@@ -14,12 +14,14 @@ This file covers the **CLI workflow** for content. Use it when the user wants to
 4. Seed entries via `fimo entries create`. Generate cover images first with `fimo image generate` if needed (see `media.md` / `assets.md`).
 5. Write React pages that import from `@/schemas/{Uid}` and render with `fimo/ui` components.
 
-Steps 1, 3, and 5 reference the project skill (`fimo`) for shape and React API. Steps 2 and 4 are CLI commands documented here.
+Steps 1, 3, and 5 reference the `fimo-code` skill (`npx fimo@latest skills get fimo-code`) for shape and React API. Steps 2 and 4 are CLI commands documented here.
 
 ## Schema CLI commands
 
 ```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 use the built-in `supportReport` tool when the platform gap materially blocks the task. 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/deploy.md

@@ -24,7 +24,7 @@ fimo deploy -m "<commit message>" --publish  # also publish a new live version
 - **`-m`** is the commit message used when there are uncommitted local changes; required in non-interactive shells. Omit if the working tree is already clean.
 - **`--no-restart`** — tells the sandbox to skip the dev-server restart and let Vite HMR pick up the change. Shaves ~3s per deploy. See "Skipping the dev-server restart" below for when it's safe.
 
-Public project variables set with `fimo vars set` are injected into preview/build/deploy environments. Project secrets are not injected into app builds; agents request secrets separately through their own config. See `references/project-vars-and-secrets.md`.
+Public project variables managed with `fimo vars add` and `fimo vars update` are injected into preview/build/deploy environments. Project secrets are not injected into app builds; agents request secrets separately through their own config. See `references/project-vars-and-secrets.md`.
 
 ## Warm the sandbox early in a session (optional)
 

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

@@ -13,7 +13,7 @@ This file covers the **CLI workflow** for forms. Use it when the user wants to a
 3. Pre-build generates `src/forms/{name}.ts` (Zod schema + `submitX` helper). See `fimo/references/forms.md` for the generated API.
 4. Write a React component that imports from `@/forms/{name}`.
 
-Steps 1, 3, and 4 reference the project skill. Step 2 is the CLI command.
+Steps 1, 3, and 4 reference the `fimo-code` skill (`npx fimo@latest skills get fimo-code`). Step 2 is the CLI command.
 
 ## CLI commands
 

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

@@ -25,12 +25,11 @@ fimo init [dir] [options]
 | `--env <name>`               | no                            | Env to check out when linking an existing project (defaults to `main`).                                                                            |
 | `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                |
 | `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                          |
-| `--skills` / `--no-skills`   | yes in non-TTY                | Set up Fimo skills (or skip it).                                                                                                                   |
-| `--agents <list>`            | no                            | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to write only universal AGENTS.md.                                              |
+| `--skills` / `--no-skills`   | yes in non-TTY                | Install the global Fimo skill (or skip it).                                                                                                        |
+| `--agents <list>`            | no                            | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to skip installing the global skill.                                            |
 | `-a, --agent <id>`           | alternative                   | Repeatable form: `-a claude-code -a cursor`.                                                                                                       |
-| `--mode <symlink\|copy>`     | no                            | Project skill install method.                                                                                                                      |
 | `--template-root <path>`     | no                            | Override the bundled template (development only).                                                                                                  |
-| `-y, --yes`                  | no                            | Skip the skills install preview confirmation.                                                                                                      |
+| `-y, --yes`                  | no                            | Run non-interactively using defaults (no prompts).                                                                                                 |
 
 In a non-TTY shell the create-new path requires `[dir]`, `--install` / `--no-install`, and `--skills` / `--no-skills` (and `--org` if you have no active org and belong to multiple orgs). Without them the command exits with `Cannot prompt in a non-interactive shell.`
 
@@ -40,7 +39,7 @@ For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for C
 
 ## Linking an existing project
 
-Pass `--project-id <id>` to link an EXISTING project instead of creating one. This clones the project's git repo into `[dir]` and writes the local `.fimo.settings.json` + agent files, the same as `fimo clone` (init's `--project-id` path reuses it). Use `--env <name>` to check out a specific env (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
+Pass `--project-id <id>` to link an EXISTING project instead of creating one. This clones the project's git repo into `[dir]` and writes the local `.fimo.settings.json`, the same as `fimo clone` (init's `--project-id` path reuses it). Use `--env <name>` to check out a specific env (defaults to `main`). Without `--project-id`, `fimo init` creates a new project.
 
 ## What gets written (create-new)
 
@@ -49,19 +48,14 @@ Pass `--project-id <id>` to link an EXISTING project instead of creating one. Th
 - The project template (Vite + React 19 + TypeScript + Tailwind v4 + shadcn/ui + react-router)
 - `.fimo.settings.json` — links this directory to the remote project (read-only after creation)
 - `.env` — initial env vars (currently just `VITE_API_URL`)
-- `AGENTS.md` — project rules read by all agentskills.io-compatible AI tools (Codex, OpenCode, Aider, etc.)
-- Per-agent variants based on `--agents`:
-  - `claude-code` → `CLAUDE.md` + `.claude/settings.json`
-  - `cursor` → `.cursor/rules/fimo.mdc`
-  - `windsurf` → `.windsurfrules`
-  - `gemini-cli` → `GEMINI.md`
-  - codex / opencode / aider / others → no extra file; AGENTS.md is read natively
-- The project-scope `fimo` skill (npm package surface: schemas, forms, `t()`, `fimo/ui` components) copied into each selected agent's skill dir (`.claude/skills/fimo/`, `.cursor/skills/fimo/`, etc.). Version-locked to the bundled `fimo` package — the installed `SKILL.md` is stamped with `fimoVersion`. Refresh later with `fimo skills sync`. See `references/agent-setup.md`.
-- A git repository with `fimo` as the remote, an initial commit, and an initial push
+- `AGENTS.md` + `CLAUDE.md` — project rules (from the template) read by AGENTS.md-compatible tools and Claude Code. Both point the agent at `fimo skills get` to load the real skills on demand.
+- A git repository with `fimo` as the remote, and — after dependencies install — an initial commit (including the lockfile) plus an initial push
 
-Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md without a per-agent variant.
+Nothing is written into per-agent skill dirs: the rich skills are fetched on demand via `fimo skills get <name>`, never copied into the project. `fimo init` separately installs the small global `fimo` bootstrap skill for the agents you select (machine-wide, not in the project) unless you pass `--no-skills`. For other agents' rule-file variants (`.cursor/rules/fimo.mdc`, `.windsurfrules`, `GEMINI.md`), run `fimo rules sync`. See `references/agent-setup.md`.
 
-`.env` is only the bootstrap app env so local `pnpm dev` works immediately. User-managed public variables are stored with `fimo vars set` and synced into a managed `.env.local` block; hidden values use `fimo secrets set`. See `references/project-vars-and-secrets.md`.
+Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md.
+
+`.env` is only the bootstrap app env so local `pnpm dev` works immediately. User-managed public variables are stored with `fimo vars add` and synced into a managed `.env.local` block; hidden values use `fimo secrets add`. See `references/project-vars-and-secrets.md`.
 
 ## Right after scaffolding
 
@@ -84,17 +78,14 @@ When a unit of work looks done, **offer** to deploy (`fimo deploy` for a hosted
 
 ## Load the project context
 
-After `fimo init` completes, the project root has:
-
-- `AGENTS.md` (universal) plus the per-agent variant for the AI tool you're running in (e.g. `CLAUDE.md` for Claude Code, `.cursor/rules/fimo.mdc` for Cursor)
-- `.claude/skills/fimo/SKILL.md` (or the equivalent per-agent path) — the project-scope `fimo` skill, version-locked to the installed `fimo` package
+After `fimo init` completes, the project root has `AGENTS.md` (universal) and `CLAUDE.md` (for Claude Code) from the template.
 
 **These files came into existence mid-session, so they may not be auto-loaded by the harness.** Explicitly:
 
 1. `cd <project-dir>` — switch into the new project.
 2. `Read` the project rules file: `AGENTS.md` (or `CLAUDE.md` if you're Claude Code).
-3. `Read` the project skill: `.claude/skills/fimo/SKILL.md` (or `.cursor/skills/fimo/SKILL.md` for Cursor, etc.).
-4. From the project skill's "load these references up front" section, batch-read `references/content.md`, `references/forms.md`, `references/assets.md`, `references/labels.md`, `references/locales.md`, `references/ui.md` before generating any significant code.
+3. Load the code skill on demand: `npx fimo@latest skills get fimo-code`.
+4. From the `fimo-code` skill's "load these references up front" section, batch-read the referenced docs (`npx fimo@latest skills get fimo-code --ref content`, `--ref forms`, `--ref assets`, `--ref labels`, `--ref locales`, `--ref ui`) before generating any significant code.
 
 Once those are in context, generation respects the project's conventions (schemas, `t()`, `fimo/ui` components, asset handling).
 
@@ -103,10 +94,11 @@ Once those are in context, generation respects the project's conventions (schema
 If a teammate joins on a different AI tool (e.g. Cursor) after the project was scaffolded for claude-code only:
 
 ```bash
-fimo skills install --agents=cursor       # one command — global skill + project skill + rule file
+fimo skills install --agents=cursor       # install the global Fimo skill for cursor
+fimo rules sync --agents=cursor           # generate cursor's rule file (.cursor/rules/fimo.mdc)
 ```
 
-Run from inside the project. The command detects the project context and wires up everything for the new agent in a single shot. See `references/agent-setup.md`.
+The first installs the global bootstrap skill for the new agent; the second generates its project rule file from `AGENTS.md`. See `references/agent-setup.md`.
 
 ## Multi-org accounts
 

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.
 

package/assets/skills/fimo-cli/references/project-vars-and-secrets.md

@@ -9,12 +9,13 @@ There is no private-variable mode. If leaking the value would be a problem, use
 ## Public Variables
 
 ```bash
-fimo vars set VITE_PUBLIC_SITE_URL https://example.com
+fimo vars add VITE_PUBLIC_SITE_URL https://example.com
+fimo vars update VITE_PUBLIC_SITE_URL https://www.example.com
 fimo vars list
 fimo vars unset VITE_PUBLIC_SITE_URL
 ```
 
-`fimo vars set` stores the value in Fimo and refreshes the managed block in `.env.local` so local development can use it immediately. Fimo also injects public variables into preview, build, and deploy environments.
+`fimo vars add` refuses to replace an existing variable. Use `fimo vars update` when the variable already exists. All variable writes refresh the managed block in `.env.local` so local development can use it immediately. Fimo also injects public variables into preview, build, and deploy environments.
 
 To refresh local values later:
 
@@ -30,13 +31,15 @@ Variables are public by design. They may use browser-safe prefixes such as `VITE
 ## Secrets
 
 ```bash
-fimo secrets set FIRECRAWL_API_KEY --stdin
-fimo secrets set SLACK_BOT_TOKEN --value "$SLACK_BOT_TOKEN"
+fimo secrets add FIRECRAWL_API_KEY --stdin
+fimo secrets update FIRECRAWL_API_KEY --stdin
+fimo secrets add SLACK_BOT_TOKEN --value "$SLACK_BOT_TOKEN"
 fimo secrets list
 fimo secrets unset FIRECRAWL_API_KEY
 ```
 
 Secret values are hidden after write. Listing secrets shows the key and a masked value, never the plaintext.
+`fimo secrets add` refuses to replace an existing value. Use `fimo secrets update` for an intentional rotation.
 
 Secrets are not written to `.env.local`, preview app env files, browser bundles, or generated project files. Secrets cannot use public prefixes such as `VITE_`, `PUBLIC_`, or `NEXT_PUBLIC_`; those prefixes are for public variables.
 
@@ -44,7 +47,7 @@ Secrets are not written to `.env.local`, preview app env files, browser bundles,
 
 `fimo init` writes `.env` for bootstrap app runtime values such as `VITE_API_URL`. This lets `pnpm dev` work without a Fimo wrapper.
 
-`fimo vars set` and `fimo vars pull` write public project variables to a managed block in `.env.local`.
+`fimo vars add`, `fimo vars update`, and `fimo vars pull` write public project variables to a managed block in `.env.local`.
 
 Local env files are ignored by git in Fimo projects. They are for local development only; deployment reads project variables from Fimo and injects them into the remote build.
 
@@ -56,15 +59,15 @@ Agents receive only the secrets they request in their own config.
 fimo agents secrets add seo-publisher FIRECRAWL_API_KEY
 fimo agents secrets list seo-publisher
 fimo agents secrets remove seo-publisher FIRECRAWL_API_KEY
-fimo validate
+fimo agents validate
 ```
 
-`fimo agents secrets add` edits `agents/<name>/config.yaml`. It does not create or rotate the secret value. Use `fimo secrets set` for that.
+`fimo agents secrets add` edits `agents/<name>/config.yaml`. It does not create or rotate the secret value. Use `fimo secrets add` to create the value or `fimo secrets update` to rotate it.
 
-`fimo validate` checks that required agent secrets exist in the project. A running agent keeps the environment it started with; the next run reads the deployed agent config again.
+`fimo agents validate` checks that required agent secrets exist in the project. A running agent keeps the environment it started with; the next run reads the deployed agent config again.
 
 ## Choosing Between Them
 
-- If the value can safely be visible in browser code or page source, use `fimo vars set`.
-- If leaking the value would be a problem, use `fimo secrets set`.
-- If an agent needs a secret, first store it with `fimo secrets set`, then request it in that agent config with `fimo agents secrets add`.
+- If the value can safely be visible in browser code or page source, use `fimo vars add`.
+- If leaking the value would be a problem, use `fimo secrets add`.
+- If an agent needs a secret, first store it with `fimo secrets add`, then request it in that agent config with `fimo agents secrets add`.

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

@@ -29,7 +29,7 @@ fimo projects rename <name> [projectId] [-C <dir>]   # local-only: set seo.siteN
 fimo clone [projectId] [dir] [--env <name>] # same as `fimo projects clone`
 ```
 
-Use the top-level shortcut for the common "get this project onto my machine" workflow. After clone succeeds, `cd` into the printed directory and load the newly written project context (`AGENTS.md` plus the installed project skill) before generating code.
+Use the top-level shortcut for the common "get this project onto my machine" workflow. After clone succeeds, `cd` into the printed directory, `Read` the project's `AGENTS.md`, and load the code skill with `npx fimo@latest skills get fimo-code` before generating code.
 
 ## Top-level shortcuts (current project)
 

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

@@ -4,20 +4,22 @@
 
 `fimo support report` sends a project-scoped problem to Fimo support. It automatically includes the project, current environment, and CLI version so support can start investigating without asking the user to repeat that context.
 
-## When to offer it
+## When to prepare it
 
-Offer to report when:
+Prepare a report proactively when:
 
 - A Fimo command, API, preview, deploy, sandbox, or platform operation repeatedly fails or returns an unexpected response.
 - A documented or previously working API or CLI argument is rejected, ignored, or behaves differently from its contract.
 - A supported operation only works through an undocumented workaround or an unnecessarily complex sequence.
 - A Fimo API repeatedly times out or is abnormally slow enough to disrupt the workflow.
-- A missing Fimo capability blocks completion, forces a fragile or heavily manual workaround, or would materially accelerate recurring work. Bulk creation replacing many single-item calls is a good example.
+- A confirmed missing Fimo capability blocks completion or forces a fragile or heavily manual workaround.
 - The remaining problem or capability gap appears to be in Fimo rather than the user's application code.
 
 For failures, read the error and try one safe, relevant recovery step before reporting. Feature requests do not need a failed recovery attempt; confirm that the capability is actually absent.
 
-Do not report ordinary application bugs, small conveniences, vague wishlist items, one-off latency, or failures you have not inspected. A clearly documented unsupported capability is still worth reporting when its absence crosses the blocking or material-acceleration threshold above; describe it as a feature request rather than a bug.
+Do not interrupt the user's main work to prepare a report. Complete it, use a safe workaround, or preserve progress first. Then use the built-in `supportReport` tool without waiting for the user to request it. Do not stop after merely describing the Fimo problem or gap.
+
+Do not report ordinary application bugs, small conveniences, vague wishlist items, one-off latency, speculative gaps, or failures you have not inspected. A clearly documented unsupported capability is still worth reporting when its absence crosses the blocking threshold above; describe it as a feature request rather than a bug.
 
 ## What to write
 
@@ -33,22 +35,22 @@ Keep the report factual and short:
 
 Do not include secrets, environment values, raw shell history, hidden reasoning, full source files, or unrelated conversation history.
 
-## Required approval
+## Sending
+
+Agents should use the built-in `supportReport` tool after the main work is complete or safely preserved. The tool submits through this CLI command and records the normal tool activity in chat.
 
-Prepare the report, then preview the complete payload without sending it:
+To inspect the exact CLI payload manually without sending it:
 
 ```bash
 fimo support report --message-file /tmp/fimo-support-report.md --preview --json
 ```
 
-Show the user the exact `data.message` from that output. Submit only after the user explicitly approves it:
+To send non-interactively:
 
 ```bash
 fimo support report --message-file /tmp/fimo-support-report.md --yes --json
 ```
 
-`--yes` means the report has already been reviewed and approved. Never pass it preemptively or report automatically.
-
 For a person using an interactive terminal:
 
 ```bash

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

@@ -0,0 +1,164 @@
+# Outbound webhooks
+
+> **Run via `npx fimo@latest <command>`** so the event catalog and delivery commands match the platform.
+
+> **Beta:** Test each destination and inspect its delivery history before depending on it in production.
+
+Use `fimo webhooks` to send project events to external HTTPS endpoints. The CLI and Studio edit the same project-wide configurations and delivery history. The CLI has no provider presets: inspect the destination's API documentation, then pass its URL, headers, and JSON body explicitly.
+
+Webhook commands require Full Access to the project. Do not attempt them when the current CLI identity has Edit, Comment, View, or agent access; the API enforces the same permission boundary as Studio.
+
+## Start from the live event catalog
+
+```bash
+fimo webhooks events
+fimo webhooks events form.submitted
+```
+
+Run this before writing a custom payload. The list shows supported event types, descriptions, and valid
+`event.data...` template variables. Pass one event name to get its example payload too. The initial families are:
+
+- Forms: `form.submitted`
+- Publish: `publish.started`, `publish.succeeded`, `publish.failed`, `publish.unpublished`
+- Agents: run started/completed/failed/cancelled and review requested/resolved
+- Analytics: `analytics.report_ready`
+- Media: uploaded/updated/deleted/generated/processing_failed
+- Entries: `entry.changed`
+
+Do not guess variable paths. The common envelope is:
+
+```json
+{
+  "id": "event-id",
+  "type": "form.submitted",
+  "version": 1,
+  "test": false,
+  "createdAt": "2026-07-17T10:00:00.000Z",
+  "project": { "id": "project-id" },
+  "env": { "name": "main" },
+  "data": {}
+}
+```
+
+Omit `--body` to send this full envelope. Prefer that default when the receiver can accept Fimo's shape.
+
+## Create a provider-specific request
+
+Store credentials as project secrets, never literal header flags:
+
+```bash
+printf '%s' "$RESEND_API_KEY" | fimo secrets add RESEND_API_KEY --stdin
+
+fimo webhooks create waitlist-resend \
+  --event form.submitted \
+  --form waitlist \
+  --url https://api.resend.com/contacts \
+  --header "Authorization=bearer:RESEND_API_KEY" \
+  --body '{"email":"{{ event.data.submission.data.email }}"}'
+```
+
+`fimo secrets add` refuses to replace an existing value. Use `fimo secrets update` for an intentional rotation.
+
+Header sources:
+
+- `Name=secret:KEY`: secret is the complete value
+- `Name=bearer:KEY`: `Bearer ` plus the secret
+- `Name=token:KEY`: `token ` plus the secret
+- `Name=literal:value`: non-secret fixed value
+
+Secret-backed values resolve when a delivery runs, so rotating a project secret updates later deliveries without editing the webhook. Fimo masks destination URLs, credentials, payload secrets, and response excerpts in CLI and Studio output.
+
+## Shape custom JSON safely
+
+`--body` accepts JSON with exact `{{ event... }}` substitutions in values:
+
+```bash
+fimo webhooks create publish-slack \
+  --event publish.succeeded \
+  --url https://hooks.slack.com/services/... \
+  --body '{"text":"Published {{ event.data.publication.url }}"}'
+```
+
+Use `--body @path/to/payload.json` for a file or `--body -` for stdin. Paths resolve from `-C` or the current
+project directory.
+
+When a variable occupies the entire JSON value, objects and arrays retain their JSON type:
+
+```json
+{
+  "submission": "{{ event.data.submission }}",
+  "email": "{{ event.data.submission.data.email }}"
+}
+```
+
+Do not add executable transform scripts or workers to a project just to reshape a payload. Use the JSON template for deterministic mappings; use an external workflow endpoint only when the integration genuinely needs branching or code.
+
+Available filters are event-specific:
+
+- `--environments <main|all>` for the event origin; the default is `main`
+- `--form <id>` for `form.submitted`
+- `--agent <name>` for agent events
+- `--media-type <image|video|audio|document|other>` for media events
+- `--action <created|updated|deleted>`, `--content-type <name>`, and `--locale <locale>` for `entry.changed`
+- `--debounce-changes <immediate|5s|30s|1m>` for direct `entry.changed` delivery grouping
+
+`entry.changed` represents content accepted in the selected environments. New entry webhooks wait 5 seconds after the last direct edit by default, then send one delivery with the combined `data.changes`. Exact repeated autosave changes appear once. Use `--debounce-changes immediate` to disable grouping. Accepted agent edits and environment merges already carry compact batches and send immediately. Operations above the delivery batch size share an `operationId` and include `{ index, total }` batch metadata. Every event includes its origin at `event.env.name`.
+
+## Inspect before depending on it
+
+```bash
+fimo webhooks list
+fimo webhooks get <webhook-id>
+fimo webhooks test <webhook-id> --wait
+fimo webhooks deliveries <webhook-id> --limit 20
+fimo webhooks delivery <webhook-id> <delivery-id>
+```
+
+`test` uses the selected event's documented example data and adds `X-Fimo-Test: true`. `--wait` waits up to 60
+seconds for success or failure. Pass `--data '{...}'` only when a specific shape needs testing.
+
+Fimo automatically retries temporary failures with backoff. After retries are exhausted:
+
+```bash
+fimo webhooks retry <webhook-id> <delivery-id>
+```
+
+Use the delivery error code and attempt history to distinguish destination errors, timeouts, missing secrets, invalid templates, and blocked unsafe URLs. A delivery accepts up to five manual retries.
+
+## Manage configurations
+
+```bash
+fimo webhooks update <webhook-id> --enabled off
+fimo webhooks update <webhook-id> --url https://example.com/hooks/fimo
+fimo webhooks update <webhook-id> --default-body
+fimo webhooks delete <webhook-id>
+```
+
+Webhooks belong to the project, with up to 20 configurations per project. The same configuration is visible from every environment. Delivery listens to `main` by default. Use `--environments all` to include branch activity, or `--environments main` to return to main-only delivery.
+
+## Verify Fimo signatures
+
+Signing is on by default. Save the signing secret shown once at creation. Fimo sends:
+
+- `X-Fimo-Delivery`: stable delivery ID
+- `X-Fimo-Event`: event type
+- `X-Fimo-Event-Id`: stable event ID for receiver deduplication
+- `X-Fimo-Test`: `true` for synthetic test deliveries
+- `X-Fimo-Timestamp`: Unix timestamp for the attempt
+- `X-Fimo-Signature`: `v1=` plus HMAC-SHA256 of `<timestamp>.<raw-request-body>`
+
+At the receiver, reject stale timestamps and compare the computed signature with a timing-safe comparison before parsing or acting on the payload. Rotate an exposed signing secret with:
+
+```bash
+fimo webhooks rotate-secret <webhook-id>
+```
+
+Save the returned value immediately; it is not shown again.
+
+## Guardrails
+
+- Destinations must use public HTTPS URLs in production. Local/private/link-local addresses and redirects are blocked.
+- Do not place access tokens in URLs, literal headers, payload templates, logs, or committed files.
+- Do not retry a pending or actively retrying delivery manually.
+- Do not assume a successful queue operation means the destination accepted the request; inspect the delivery result.
+- Use `--json` when another agent or script needs stable, parseable output.