fimo 0.8.0 → 0.9.0-staging.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

@@ -1,67 +1,30 @@
 ---
 name: fimo
 description: >-
-  How to write code in a Fimo project — the npm package surface. Load when
-  writing JSX that renders schema content, defining schemas or forms (JSON),
-  using `t()` for labels, plugging media into `fimo/ui` components,
-  or applying the project's code conventions. CLI commands and workflows
-  (push, deploy, sync, etc.) live in the `fimo-cli` skill.
+  Working in or with a Fimo project (a content + media + forms + analytics
+  platform for React websites). Load the real, version-locked Fimo skills on
+  demand through the `fimo` CLI before doing Fimo work — writing schema-driven
+  code, running CLI/deploy workflows, using the dashboard, or migrating a site.
 ---
 
 # Fimo
 
-You are writing code in a Fimo project — a content + media + forms + analytics platform for React websites with a CMS dashboard. This skill describes the **`fimo` npm package surface** as installed in this specific project: what's exported from `fimo`, `fimo/ui`, `fimo/vite`; the JSON shapes you write; the generated React Query hooks and Zod schemas you import; and the code conventions for using them.
+Fimo ships its skills through its CLI so they always match the installed `fimo` version. This file is
+just a pointer — do not rely on cached instructions. Fetch the real skill from the CLI when you need it.
 
-This skill is version-locked to this project's installed `fimo` package — the shapes here match what your code can actually use.
+When you are about to do Fimo work:
 
-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`.
+1. List what's available: `npx fimo@latest skills list`
+2. Load the relevant skill: `npx fimo@latest skills get <name>` (add `--ref <doc>` for a reference doc)
 
-## Critical: NEVER hardcode user-facing things
+Pick by task:
 
-This is the load-bearing rule for every code change. **Fimo's whole point is that content editors edit content in the dashboard, not in code.** Anything hardcoded breaks that.
+- Writing code — schema-driven JSX, schemas/forms JSON, `t()` labels, `fimo/ui` media → `fimo-code`
+- CLI commands and workflows — push, deploy, sync, labels, domains, analytics → `fimo-cli`
+- The Fimo Studio dashboard / web app UI → `fimo-studio`
+- Migrating an existing site into Fimo → `fimo-migration`
 
-- **Content** (posts, products, pages, lists, anything structured) → declare a schema, render collections with generated `useList()` or `useInfiniteList()` hooks + `fimo/ui` components. Use `useGet()` only for legacy fixed array queries. **Never** write `const posts = [...]` in JSX.
-- **Strings** (labels, CTAs, headings, descriptions, any visible text) → wrap in `t('key')` and create the default-locale value with `fimo labels set`. Use `--locale <locale>` only when intentionally writing a non-default locale. **Never** write `<h1>Welcome</h1>` directly — write `<Text value={t('home.title')} as="h1" />`.
-- **Media** (images, videos, files) → use `<Image>` / `<Video>` from `fimo/ui` for schema media, `<StaticImage>` for hard-coded URLs. **Never** use `<img src={...}>`.
-- **Forms** → use the generated Zod schema + `submitX` helper from `@/forms/<name>`. Never hand-roll fetch or validation.
+If a confirmed Fimo platform failure or missing capability materially blocks the task, finish or safely preserve the main work first, then use the built-in `supportReport` tool. Load the `fimo-cli` support instructions for the reporting criteria.
 
-If you find yourself about to hardcode anything user-facing, **stop and use the appropriate Fimo primitive instead.** For pushing the schema/form/asset to the backend, that's CLI territory — see the `fimo-cli` skill.
-
-## When starting code work, load these references up front
-
-These define the package surface for the load-bearing primitives. **Read all six before generating significant code:**
-
-- `references/content.md` — schema JSON shape, field types, Tiptap nodes, generated React Query hooks
-- `references/forms.md` — form JSON spec, generated Zod + `submitX` helper
-- `references/assets.md` — `FimoMedia` shape, how to render assets
-- `references/labels.md` — `t()` helper, `useLabels()`, wrap rules
-- `references/locales.md` — locale routing helpers, `FimoLink`, custom-framework contract
-- `references/ui.md` — `fimo/ui` components + JSX code conventions + app code rules
-
-Workflow / CLI-side concerns (pushing schemas, generating images, managing labels, deploying) live in the **`fimo-cli`** skill's matching references.
-
-## Decision Tree (specific tasks)
-
-- **Setting up Fimo in a new project** — pick the framework:
-  - React Router framework mode (new projects use React Router 8) → `references/setup-react-router.md`
-  - Plain Vite + React (or upgrading a legacy v3 project) → `references/setup-plain-vite.md`
-- Writing schema JSON / picking field types / Tiptap richtext → `references/content.md`
-- Writing form JSON / generated form client / form code → `references/forms.md`
-- Plugging media into a component / `FimoMedia` shape → `references/assets.md`
-- ANY user-facing string in code → `references/labels.md`
-- Locale-aware routes, links, or framework adapters → `references/locales.md`
-- ANY JSX rendering schema content or `t()` output → `references/ui.md`
-- Major visual / redesign / hero section / brand → `references/design.md`
-
-## Anti-Patterns
-
-- **Hardcoding content in JSX** — `<h1>My Blog</h1>` + an array of posts in code. Use schemas + entries + `t()`.
-- **Raw HTML for schema content** — `<img src={post.coverImage.url}>` instead of `<Image value={post.coverImage}>`. The `fimo/ui` components carry metadata for inline editing in the admin.
-- **Raw `<a href>` for internal navigation** — causes full page reloads. Use `<FimoLink>` for locale-aware internal links or React Router `<Link>` when intentionally bypassing locale helpers. Reserve `<a>` for external links.
-- **Pulling stock photos from external URLs** — editors can't manage them. Use a Fimo media task such as `fimo image generate`.
-- **Editing generated `.ts` files** under `src/schemas/` or `src/forms/` — regenerate them through `fimo validate` or the matching push command.
-- **Writing raw HTML in `richtext` fields** — must be Tiptap JSONContent.
-- **Calling `t()` with a dynamic first argument** — the key must be a string literal so the extractor finds it.
-- **Decorating the disposable starter** — `src/pages/Index.tsx` is throwaway scaffolding. On first real generation, replace it entirely.
-- **Skipping legal pages** — `Privacy.tsx` + `Terms.tsx` are required for public sites; the template ships them.
-- **Showing Fimo branding** in the generated site unless the user explicitly asks for it.
+If the project has an `AGENTS.md` (or `CLAUDE.md`), read it too — it carries project-specific context.
+Always fetch the skill fresh from the CLI rather than trusting a copy.

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
@@ -17,15 +18,17 @@ description: >-
 
 The `fimo` CLI is the workflow surface for Fimo. Fimo is a content + media + forms + analytics platform for React websites with a CMS dashboard. The CLI handles project creation, all content / forms / media / labels / locale workflows, deploys, collaboration, account management, AI credit inspection, and AI agent setup.
 
-This skill describes **what the CLI does and the workflows it drives**. For the package surface used IN code (component props, generated hooks, JSON shapes, code-side rules), see the `fimo` skill — its description triggers automatically when the agent is in a Fimo project.
+This skill describes **what the CLI does and the workflows it drives**. For the package surface used IN code (component props, generated hooks, JSON shapes, code-side rules), load the `fimo-code` skill on demand with `npx fimo@latest skills get fimo-code`.
 
 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.
 
-The examples in this skill and its references write `fimo <command>` for brevity — mentally prefix them with `npx fimo@latest`. (One exception, because npx has no stable package path to symlink into: install skills with `npx fimo@latest skills install --mode=copy`.)
+The examples in this skill and its references write `fimo <command>` for brevity — mentally prefix them with `npx fimo@latest`.
 
 ## Output for agents: `--json` is the stable contract
 
@@ -52,11 +55,11 @@ A project can have multiple **envs** — each is a git branch _plus_ its own DB,
 
 ```bash
 npx fimo@latest login                          # authenticate via browser
-npx fimo@latest skills install --mode=copy     # install Fimo skills for your AI tools (copy mode: required under npx)
+npx fimo@latest skills install                 # install the global Fimo skill for your AI tools
 npx fimo@latest init my-site --org <id>        # one-stop setup: sign in, create/link a project, install deps + skills. Use the org **id** from `fimo orgs list`, NOT the slug.
 npx fimo@latest init --project-id <id> my-site # link an EXISTING project instead of creating one
 npx fimo@latest clone                          # interactively choose an existing project to clone locally
-cd my-site                                     # the `fimo` project skill auto-loads from here
+cd my-site                                     # then load skills on demand: npx fimo@latest skills get fimo-code
 pnpm dev                                       # run the app locally (use the project's PM: pnpm/npm run/yarn/bun) — your iteration loop
 npx fimo@latest credits                        # inspect the owning org's AI credit balance (read-only)
 npx fimo@latest validate                       # run all checks + codegen; fails on missing DB labels
@@ -70,21 +73,22 @@ The working loop is local: run the app with the project's package-manager `dev`
 
 ## Decision Tree
 
-Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo` skill's package references — they're called out where relevant.
+Load the matching reference when the user's request fires its trigger. Recipes that involve writing code also need the `fimo-code` skill's package references — they're called out where relevant.
 
 - "Create a new Fimo project / scaffold a site / start a new website / link an existing project locally" → `references/init.md`
-- "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ load `fimo/references/content.md` for the JSON shape and React hooks**
-- "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ load `fimo/references/forms.md` for the JSON spec and generated client**
+- "Add a content type / blog / products / pages / CMS" → `references/content.md` (workflow) **+ load `fimo-code/references/content.md` for the JSON shape and React hooks**
+- "Add a contact / signup / feedback / newsletter form" → `references/forms.md` (workflow) **+ load `fimo-code/references/forms.md` for the JSON spec and generated client**
 - "View form submissions / who filled out the contact form / inspect what users sent / how many signups" → `references/forms.md` § Reading submissions
-- "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ load `fimo/references/assets.md` for the `FimoMedia` shape and rendering**
-- "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ load `fimo/references/assets.md` for the `FimoMedia` shape if you'll plug the result into UI**
-- "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ load `fimo/references/labels.md` for the `t()` helper and wrap rules**
-- "Enable locales / configure default locale / route by locale prefix / fix locale route validation" → `references/locales.md` **+ load `fimo/references/locales.md` for code helpers**
+- "Upload an image / hero / cover / existing media file" → `references/assets.md` (workflow: upload, browse, open, delete) **+ load `fimo-code/references/assets.md` for the `FimoMedia` shape and rendering**
+- "Generate AI image / video / draft preview / image edit / cover from a prompt" → `references/media.md` (task commands, quality, recipes, and verification) **+ load `fimo-code/references/assets.md` for the `FimoMedia` shape if you'll plug the result into UI**
+- "Add labels / update static copy / fix missing `t()` values" → `references/labels.md` (workflow) **+ load `fimo-code/references/labels.md` for the `t()` helper and wrap rules**
+- "Enable locales / configure default locale / route by locale prefix / fix locale route validation" → `references/locales.md` **+ load `fimo-code/references/locales.md` for code helpers**
 - "What's in this project / show the project structure / describe the project / what schemas does it have / how many routes / project tree / show me what's here" → `references/describe.md`
 - "Deploy / publish / go live / push my changes" → `references/deploy.md`
 - "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`
@@ -99,7 +103,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Create / scaffold / run / validate / activate / deactivate an agent / agent bundle / list agent templates / view agent runs, reports, or logs (`fimo agents *`)" → `references/agents.md`
 - "Install Fimo for my AI tool / fimo skills install / set up Claude Code or Cursor for Fimo / add an agent to this project" → `references/agent-setup.md`
 - "Refresh / update installed Fimo skills / fimo skills sync / agent missing the latest fimo conventions" → `references/agent-setup.md`
-- "Report a Fimo problem or feature request / contact Fimo support / a Fimo API or command keeps failing / a documented argument is rejected / a supported operation needs an undocumented workaround / a Fimo API is abnormally slow / a missing capability blocks work, forces a fragile or heavily manual workaround, or would materially accelerate a recurring workflow such as bulk create" → `references/support.md`
+- "Report a Fimo problem or blocking feature request / contact Fimo support / a Fimo API or command keeps failing / a documented argument is rejected / a supported operation needs an undocumented workaround / a Fimo API is abnormally slow / a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround" → `references/support.md`
 - "Regenerate rule files / I edited AGENTS.md / fimo rules sync" → `references/agent-setup.md`
 - "Show analytics / visitor stats / traffic / pageviews / how is my site performing / top pages / where do visitors come from" → `references/analytics.md` (7-day preview free for all; longer ranges require paid)
 - "Mark a date on the analytics chart / annotate the chart with a deploy / add a launch note" → `references/analytics.md` § Annotations
@@ -108,7 +112,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 
 These fire at specific moments in the project lifecycle. **Surface them proactively** rather than waiting for the user to ask:
 
-- **Right after `fimo init`** → `cd` into the new directory, then `Read` the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code) **and** `.claude/skills/fimo/SKILL.md` (or `.cursor/skills/fimo/SKILL.md` etc. for other agents) to load the project context before generating any code. The new files came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
+- **Right after `fimo init`** → `cd` into the new directory, then `Read` the project's `AGENTS.md` (or `CLAUDE.md` for Claude Code) to load the project context, and run `npx fimo@latest skills get fimo-code` to load the code skill before generating any code. The `AGENTS.md`/`CLAUDE.md` came into existence mid-session and may not be auto-loaded by the harness. See `references/init.md` § Load the project context.
 - **Right after `fimo init`** → suggest `fimo rename "<Display Name>"` to set a human-readable name (the default post-init name is an auto-generated slug). Infer the name from what the user is building (e.g. "Acme Coffee" for a café, "Jane Doe Portfolio" for a personal site). See `references/init.md`.
 - **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background, then ask the developer what they want to build. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes.
 - **When a user-visible unit of work looks done** → **offer** to deploy (`fimo deploy` for a hosted preview / shareable link, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy on your own. See `references/deploy.md`.
@@ -116,7 +120,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Iterative code-only deploys** → once you are deploying, `fimo deploy --no-restart` skips the sandbox dev-server restart on HMR-safe edits. See `references/deploy.md` § Skipping the dev-server restart for when it's safe.
 - **You need the current preview URL but haven't changed code** (opening it, screenshotting it, handing it to another tool, the previous URL expired) → `fimo preview url`, never a no-op `fimo deploy`. See `references/preview.md`.
 - **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature env: `fimo checkout -b <name>` gives an isolated branch + DB + preview. Deploy previews there, then `fimo merge` it back and `fimo publish`. See `references/branches.md`.
-- **When a Fimo API or command still fails after one safe recovery attempt, rejects a documented or previously working argument, needs an undocumented workaround for a supported operation, is repeatedly abnormally slow, or lacks a capability that blocks work, forces a fragile or heavily manual workaround, or would materially accelerate a recurring workflow** → offer to prepare a support report. Show the exact report and wait for explicit approval before running `fimo support report --yes`. See `references/support.md`.
+- **After completing or safely preserving the user's main work, when a confirmed Fimo platform failure still materially blocks the task after one safe recovery attempt, or a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround** → use the built-in `supportReport` tool. Do not wait for the user to ask and do not stop after only describing the gap. See `references/support.md`.
 - **After the first successful `fimo deploy`** → suggest `fimo invite` if the project involves multiple people. Typical roles: `edit` for developers/content editors, `view` or `comment` for clients/stakeholders, `full` for project leads. See `references/invite.md`.
 - **When the user wants to modify the URL of their website** → walk through `references/domains.md`. The CLI surface covers renaming the Fimo-provided subdomain (`fimo domains rename-default`, free), attaching a domain they already own (`fimo domains add`, Premium), and buying a new domain through Fimo (`fimo domains buy`, Premium). The auto-generated default URL on every project is a fallback, not a final choice — proactively offer this after `fimo deploy --publish` if the user mentioned a real brand or domain.
 
@@ -128,7 +132,7 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Running `fimo deploy` just to get a fresh preview URL** — that's a commit + push + sandbox sync for what should be a sub-second read. Use `fimo preview url` instead. See `references/preview.md`.
 - **Using `fimo deploy --publish` casually** — `--publish` makes the site live to the public. Plain `fimo deploy` (preview) is the default. Use `--publish` only when the user says "ship it" / "go live" / "publish".
 - **Bare `fimo init` in a non-interactive shell** — will hang. Always pass `[dir]`, `--no-install` (or `--install`), `--no-skills` (or `--skills`), and `--org`/`--agents` as needed explicitly when scripted.
-- **Hardcoding content / strings / images in code** — that's what schemas, `t()`, and the media library are for. See the `fimo` skill's anti-patterns.
+- **Hardcoding content / strings / images in code** — that's what schemas, `t()`, and the media library are for. See the `fimo-code` skill's anti-patterns.
 - **Adding another deploy tool (Vercel, Netlify, Cloudflare Pages)** — Fimo handles deploys; don't bolt another platform on.
 - **Committing secrets** — hidden values use `fimo secrets`; public browser-safe values use `fimo vars`. Local env files are ignored and must not become deploy inputs.
 - **Hardcoding tokens in flags** — use the credentials written by `fimo login` (one file per backend at `~/.config/fimo/credentials/<host>-<hash>.json`).

package/assets/skills/fimo-cli/references/agent-setup.md

@@ -2,75 +2,59 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-Fimo wires up to AI coding tools in three layers:
+Fimo wires up to AI coding tools in two layers:
 
-1. **Global skills** — `fimo-cli`, `fimo-studio`, and `fimo-migration` skills installed once per user, machine-wide. They describe the CLI workflows, the Fimo Studio web app, and URL/source-backed migrations, and load in any compatible AI tool.
-2. **Per-project rule files** — `AGENTS.md` (universal) plus per-agent variants (`CLAUDE.md`, `.cursor/rules/fimo.mdc`, `.windsurfrules`, `GEMINI.md`, `.claude/settings.json`) generated for the AI tools each project supports.
-3. **Project-scope `fimo` skill** — the code-side skill (npm package surface: schemas, forms, `t()`, `fimo/ui` components) installed under `.claude/skills/fimo/`, `.cursor/skills/fimo/`, etc., **version-locked to the project's installed `fimo` package**.
+1. **One global bootstrap skill** — a tiny, generic `fimo` skill installed once per user, machine-wide (symlinked into each agent's global skills dir). It doesn't contain workflow content itself; it tells the agent to load the real, version-locked skills on demand from the CLI. It never goes stale because it just points at `fimo skills get`.
+2. **Per-project rule files** — `AGENTS.md` (universal) and `CLAUDE.md` ship in the project template. `fimo rules sync` regenerates the other agents' variants (`.cursor/rules/fimo.mdc`, `.windsurfrules`, `GEMINI.md`) from `AGENTS.md`.
 
-Two CLI namespaces manage all three:
+The rich skills (`fimo-code`, `fimo-cli`, `fimo-studio`, `fimo-migration`) are **never installed as files**. They're served on demand straight from the CLI, so they always match the installed version and never land in the project:
 
-- `fimo skills install / sync / uninstall` — skill artifacts (layers 1 + 3)
-- `fimo rules sync` — rule files (layer 2)
+```bash
+npx fimo@latest skills list            # what's available
+npx fimo@latest skills get fimo-code   # writing code: schemas, forms, labels, fimo/ui
+npx fimo@latest skills get fimo-cli    # CLI + workflows (this skill)
+npx fimo@latest skills get fimo-cli --ref deploy   # a reference doc
+```
 
-## Set up skills (no install needed)
+Two CLI namespaces manage the two layers:
 
-Run the CLI via `npx fimo@latest` — do not install `fimo` globally. To set up the Fimo skills for your AI tools, use **copy mode** (npx runs from an ephemeral cache with no stable package path to symlink into):
+- `fimo skills install / sync / uninstall` — the single global bootstrap skill (layer 1)
+- `fimo rules sync` — per-project rule files (layer 2)
 
-```bash
-npx fimo@latest skills install --mode=copy
-```
+## Set up the global skill (no install needed)
 
-This opens the agent picker and installs everything that applies (see below). Then connect your account when you are ready:
+Run the CLI via `npx fimo@latest` — do not install `fimo` globally.
 
 ```bash
-npx fimo@latest login
+npx fimo@latest skills install         # opens the agent picker, installs the global fimo bootstrap
+npx fimo@latest login                  # connect your account when ready
 ```
 
 ## `fimo skills` — install + sync + uninstall
 
 ```bash
-fimo skills install                            # interactive: pick agents, install everything that applies
+fimo skills install                            # interactive: pick agents, install the global bootstrap
 fimo skills install --agents=claude-code,cursor   # explicit list
 fimo skills install -a claude-code -a cursor      # repeatable form
-fimo skills install --agents=claude-code --yes    # skip the install preview prompt (headless / scripts)
-fimo skills install --mode=copy                # copy files instead of symlinking (required under npx)
-fimo skills sync                               # refresh installed skills (global + project, where applicable)
-fimo skills uninstall                          # remove the global skills
+fimo skills sync                               # re-ensure the bootstrap + clean up stale old skills
+fimo skills uninstall                          # remove the global bootstrap
 ```
 
-`fimo skills install` shows a one-screen preview of every path it will touch (`.agents/skills/...`, `.claude/skills/...`, `AGENTS.md`, per-agent rule files, …) before writing. Pass `-y` / `--yes` to skip the confirmation in scripts.
-
-**`fimo skills install` is context-aware**:
-
-- **Outside a Fimo project** — installs only the global `fimo-cli`, `fimo-studio`, and `fimo-migration` skills for the selected agents.
-- **Inside a Fimo project** (`.fimo.settings.json` found by walking up from cwd) — installs the global skills _and_ writes the project `fimo` skill _and_ generates the per-agent rule file (`CLAUDE.md` / `.cursor/rules/fimo.mdc` / `.windsurfrules` / `GEMINI.md`) for each selected agent. One command, full setup.
-
-The command prints exactly which files were written, so the context-aware behavior is never silent magic.
-
-**Adding an agent to an existing project** is the same command — `fimo skills install --agents=cursor` inside the project does global + project skill + rule file for cursor in one shot.
-
-**`fimo skills sync`** is the refresh / update path — no consent prompts, no new agents added. It re-copies whatever is already installed:
-
-- Global skills for whichever agents already have them
-- Project `fimo` skill for whichever agents have rule files (when run inside a Fimo project)
-
-You rarely have to invoke it by hand:
+`fimo skills install` installs the single global `fimo` bootstrap skill for the selected agents (symlinked into each agent's global skills dir; it transparently falls back to a copy when a symlink can't be created, e.g. under `npx`). It writes **nothing** into your project — the working tree stays clean.
 
-- **Global skills auto-refresh** whenever a newer CLI runs — any `npx fimo@latest …` command detects a version change (marker at `~/.config/fimo/last-version`) and re-copies the latest skills.
-- **The project skill auto-refreshes during Fimo-controlled installs** when the `fimo` package version bumps — the package's postinstall hook re-syncs the skill from `node_modules/fimo/assets/skills/fimo/` (which is version-locked to the installed package). For pnpm, `fimo init --install`, sandbox `fimopm install`, and E2E helper installs pass a scoped allow-all-builds flag so the hook can run without persisting build-script approvals in the template. npm / yarn run lifecycle scripts by default and need no extra config.
+Once installed, the agent discovers everything else through the bootstrap: it runs `fimo skills get <name>` to load the real skill for the task at hand.
 
-Invoke `fimo skills sync` explicitly when iterating on skill content locally, when you bumped the package via something other than a fresh install, or any time you want to force a refresh.
+**`fimo skills sync`** re-ensures the global bootstrap for whichever agents already have it, and cleans up stale global skills that older CLI versions used to copy in (`fimo-cli`, `fimo-studio`, `fimo-migration`, and legacy migration skills). You rarely need it: the bootstrap is a symlink, so it always tracks the running CLI, and the real skills are fetched fresh via `fimo skills get`. Run it after upgrading from an old CLI to clear leftovers.
 
-**`fimo skills uninstall`** removes only the global skills. Project files are part of the project — delete the project (or `rm -rf .claude/skills/fimo .cursor/skills/fimo`) if you want them gone.
+**`fimo skills uninstall`** removes the global bootstrap for the selected agents.
 
 ## `fimo rules sync` — rule files only
 
-`fimo init` writes `AGENTS.md` (the universal-spec file) and per-agent variants for the AI tools you selected. Variants and their generators:
+`fimo init` scaffolds `AGENTS.md` (the universal-spec file) and `CLAUDE.md` from the template. Other agents' variants are generated on demand:
 
 | Agent                             | File(s) generated                     |
 | --------------------------------- | ------------------------------------- |
-| claude-code                       | `CLAUDE.md` + `.claude/settings.json` |
+| claude-code                       | `CLAUDE.md` (ships in the template)   |
 | cursor                            | `.cursor/rules/fimo.mdc`              |
 | windsurf                          | `.windsurfrules`                      |
 | gemini-cli                        | `GEMINI.md`                           |
@@ -79,16 +63,16 @@ Invoke `fimo skills sync` explicitly when iterating on skill content locally, wh
 `fimo rules sync` regenerates these variants from the current `AGENTS.md`. Use it when:
 
 - You edited `AGENTS.md` and want variants refreshed (delete the variant first — see below).
-- You added an agent in a different way and need its rule file generated.
+- You added an agent that needs its own rule file generated.
 
 ```bash
 fimo rules sync                       # interactive: pick agents
 fimo rules sync --agents=cursor       # explicit
 ```
 
-`fimo rules sync` is **purely additive** — it creates missing variant files but never overwrites existing ones. Project-specific edits in `CLAUDE.md`, `.cursor/rules/fimo.mdc`, `.claude/settings.json`, etc. are preserved. To regenerate a stale variant, delete the variant file first and re-run.
+`fimo rules sync` is **purely additive** — it creates missing variant files but never overwrites existing ones, so project-specific edits are preserved. To regenerate a stale variant, delete the variant file first and re-run.
 
-**`fimo rules sync` does NOT install skill files.** That's `fimo skills install / sync` territory. The split is deliberate — rules are generated config files, skills are reusable knowledge artifacts.
+**`fimo rules sync` does NOT install skills.** That's `fimo skills` territory. The split is deliberate — rules are generated project config files (committed with the project); skills are fetched on demand and never committed.
 
 ## Selecting agents (interactive vs flags)
 
@@ -98,21 +82,20 @@ Every command that takes agents accepts the same selection inputs:
 - `-a claude-code -a cursor` — repeatable short form
 - No flag → interactive multi-select. The picker has two sections:
   - **Universal** — agents that read `AGENTS.md` natively (codex, opencode, aider, …). Always covered, not toggleable.
-  - **Additional** — agents that need a per-agent rule file or skills dir. The 6 popular ones (`claude-code`, `cursor`, `codex`, `opencode`, `windsurf`, `gemini-cli`) appear at the top of an 8-item scrollable viewport; the full list of 50+ supported agents is below the fold. Each row shows the install path next to the name (e.g. `Claude Code (.claude/skills)`). Agents already present on the machine are pre-checked.
-- `--agents=none` (only `fimo init`) — skip per-agent variants entirely; write only `AGENTS.md`.
-- `--mode=symlink|copy` (only `fimo skills install` and `fimo init`) — pick the install method for the per-agent skills layer. Defaults to symlink so the canonical `.agents/skills/<name>/` is the single source of truth; pass `--mode=copy` to materialize the skill in each per-agent dir.
+  - **Additional** — agents that get the global bootstrap skill installed. The 6 popular ones (`claude-code`, `cursor`, `codex`, `opencode`, `windsurf`, `gemini-cli`) appear at the top of an 8-item scrollable viewport; the full list of 50+ supported agents is below the fold. Agents already set up on the machine are pre-checked.
+- `--agents=none` (only `fimo init`) — skip the global skill entirely.
 
 In headless contexts (CI, AI-tool-spawned commands), pass the flag explicitly. Env-var detection (only Claude Code's `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT`) silently targets `claude-code` if the flag is omitted; every other agent must be named explicitly with `--agents` in a headless shell, or the command exits with "No agents detected and no --agents flag passed."
 
-## Version stamping
+## Always current, never stale
 
-Every installed `SKILL.md` (global or project) is stamped with `fimoVersion: <cli-version>` in its YAML frontmatter at install time. That gives the CLI (and you) a way to detect stale installs — compare the stamped version to the currently-running CLI version.
+Because the only installed artifact is a generic pointer, and the real skills are fetched with `fimo skills get`, the content an agent reads always matches the running CLI. There's no version stamp to check and no cached copy to refresh — re-run `fimo skills get <name>` any time to get the current instructions.
 
 ## When to use which
 
 - "I want this AI tool to know about Fimo" → `fimo skills install` (interactive)
-- "I want to add Cursor to this project" → `fimo skills install --agents=cursor` (from inside the project)
-- "The agent doesn't know about my project's latest fimo conventions" → `fimo skills sync`
+- "Load the code / CLI / studio / migration skill now" → `fimo skills get fimo-code` / `fimo-cli` / `fimo-studio` / `fimo-migration`
+- "Clean up skills left by an old CLI version" → `fimo skills sync`
 - "I edited `AGENTS.md` and want variants regenerated" → delete the stale variant + `fimo rules sync`
 - "I'm done with Fimo on this machine" → `fimo skills uninstall`
-- For a fresh project, `fimo init` wires up everything for the AI tools you select at scaffold time.
+- For a fresh project, `fimo init` installs the global skill for the AI tools you select at scaffold time.

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

@@ -18,9 +18,9 @@ Typical flow:
 ```
 fimo agents create <name>     # scaffold agents/<name>/ from a template (local)
 fimo agents secrets add <name> FIRECRAWL_API_KEY  # request a project secret in config.yaml
-fimo secrets set FIRECRAWL_API_KEY --stdin        # store the hidden value in Fimo
-fimo agents validate <name>   # confirm it parses + passes policy (local)
-fimo validate                 # also checks that requested project secrets exist
+fimo secrets add FIRECRAWL_API_KEY --stdin        # store the hidden value in Fimo
+fimo agents validate <name>   # parse + policy + composition + requested secrets
+fimo validate                 # project build and codegen checks
 fimo deploy                   # push the bundle to the env's git branch
 fimo agents activate <name>   # wire its triggers on the env (DB row)
 fimo agents run <name>        # trigger a manual run → sessionId
@@ -45,7 +45,7 @@ fimo agents secrets remove <name> <KEY> [-C <dir>]
 - **`create <name>`** — scaffold `agents/<name>/` from a template (default `_default`, a minimal valid bundle). `--description <text>` writes a one-line tagline into the scaffolded `config.yaml` (surfaces in the dashboard's agents list). When run **without** `-C`, it requires the cwd to be inside a real Fimo project (walks up for `.fimo.settings.json`) and errors out cleanly otherwise, so it never leaks `agents/<name>/` into a stray cwd. If the template declares capabilities, an install-consent flow runs after the copy (`--quiet` skips it; critical caps still abort).
 - **`list`** — list the agents declared under `<project>/agents/`, with each one's trigger types and capability count. Local — the bundle list is the source of truth even if the project isn't linked yet.
 - **`validate [name]`** — run the full validation pipeline: parse → capability vocabulary → composition (cycle / missing sub-agents / invalid grants) → semantic + `fimo.config.json` policy checks. Omit `name` to validate every bundle. `--json` emits a structured `ValidationReport` for CI; exit code is non-zero on any failure.
-- **`secrets add/remove/list`** — edit or inspect the agent's requested secret names in `agents/<name>/config.yaml`. These commands do not create, rotate, or reveal secret values. Store values with `fimo secrets set`; run `fimo validate` to check that required requested secrets exist in the project. See `references/project-vars-and-secrets.md`.
+- **`secrets add/remove/list`** — edit or inspect the agent's requested secret names in `agents/<name>/config.yaml`. These commands do not create, rotate, or reveal secret values. Store values with `fimo secrets add`; run `fimo agents validate` to check that required requested secrets exist in the project. See `references/project-vars-and-secrets.md`.
 - **`integrations <name>`** — preview the agent's `integrations` allowlist from `agents/<name>/config.yaml` and, when linked, overlay project integration status. See `references/integrations.md`.
 
 Agent integration access is configured in `agents/<name>/config.yaml` with an allowlist. Omitted integrations and omitted tools are not available to the agent: