fimo 0.11.0-staging.1 → 0.11.0-staging.11

package/assets/agent-templates/_default/config.yaml

@@ -2,3 +2,5 @@
 # See https://fimo.dev/docs/agents/bundle for the full reference.
 version: 1
 description: 'A new Fimo agent. Edit this tagline to describe what it does.'
+triggers:
+  - type: manual

package/assets/agent-templates/content-translator/GOAL.md

@@ -1,7 +1,7 @@
 # Content translator
 
 Translate CMS entries and DB-backed labels from the project's default
-locale into every non-default locale declared in `fimo-config.json`.
+locale into every non-default locale declared in `.fimo/config.json`.
 Writes go through Fimo's content and label APIs. Do not create locale
 JSON files or put translated values in source code.
 
@@ -9,7 +9,7 @@ JSON files or put translated values in source code.
 
 - The list of CMS entries that have a non-empty default-locale field
   but an empty translation for any non-default locale.
-- The configured target locales (read from `fimo-config.json`).
+- The configured target locales (read from `.fimo/config.json`).
 
 ## What to do
 
@@ -31,4 +31,4 @@ For each entry:
 
 Cloud-time activation of this agent requires
 `agents.notifications.email_recipients` to be non-empty (per ADR-0009).
-Add at least one address before running `fimo agents activate`.
+Add at least one address before deploying, or the cloud trigger stays unwired.

package/assets/agent-templates/seo-audit/config.yaml

@@ -7,7 +7,7 @@ data_sources:
   - main
 
 # Manual-only in v1. Add a schedule trigger when you're ready to run
-# this nightly — make sure fimo.config.json has
+# this nightly — make sure .fimo/config.json has
 # `agents.notifications.email_recipients` set before activating.
 triggers:
   - type: manual

package/assets/skills/fimo/SKILL.md

@@ -25,6 +25,7 @@ Pick by task:
 
 - 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`
+- Project MCP setup — configure `fimo mcp` for a local AI client → `fimo-cli` (`references/mcp.md`)
 - The Fimo Studio dashboard / web app UI → `fimo-studio`
 - Migrating an existing site into Fimo → `fimo-migration`
 

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

@@ -6,6 +6,7 @@ description: >-
   (schemas, entries, forms, media, labels/locales), deploy a site, manage
   custom domains, configure outbound webhooks and event-driven integrations,
   check site traffic/analytics, inspect or restore project history, invite collaborators, inspect AI credits,
+  connect an AI coding client to a Fimo project through MCP,
   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
@@ -43,9 +44,9 @@ Branch on `error.code`, never on `error.message`. The envelope shape is versione
 
 For shell composition use plain pretty mode (`cd $(fimo …)`); for structured parsing use `--json`. JSON mode disables interactive prompts — commands that need a confirmation will fail fast with `NON_INTERACTIVE_REFUSAL` unless every required arg is on the command line (`--yes`, `--org`, etc.).
 
-## Critical: `.fimo.settings.json` is the project link
+## Critical: `.fimo/project.json` is the project link
 
-A Fimo project is identified by `.fimo.settings.json` at its root, written once by `fimo init`. This file connects the local directory to the remote Fimo project. **Never edit it manually.** Most CLI commands look at this file in the cwd to know which project they operate on.
+A Fimo project is identified by `.fimo/project.json`, written by `fimo init`. This file connects the local directory to the remote Fimo project. **Never edit it manually.** Most CLI commands find it by walking up from the cwd.
 
 ## Critical: commands target the env of the current git branch
 
@@ -57,6 +58,7 @@ A project can have multiple **envs** — each is a git branch _plus_ its own DB,
 npx fimo@latest login                          # authenticate via browser
 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 my-site --starter fimo-site@1 --org <id> --yes --no-skills  # opt-in content-led starter for a new project
 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                                     # then load skills on demand: npx fimo@latest skills get fimo-code
@@ -70,13 +72,13 @@ npx fimo@latest deploy --publish               # ON-DEMAND: publish live (only w
 
 The working loop is local: run the app with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev` — match the lockfile), ask the developer what they want, edit, and iterate against the live localhost server. `fimo deploy` is **not** a required final step — reach for it only when the developer wants a hosted preview, a shareable link, or to go live, and only on their signal (see `references/deploy.md`).
 
-`fimo validate` is the single entrypoint for "prove this project is ready" — it covers schema/form codegen, route metadata checks, lint, and missing label checks for `i18n.defaultLocale` from `fimo-config.json` (fallback: `en`). Use `fimo labels set` / `set-many` to create or update label values in the DB. The underlying phases are also available individually under the hidden `fimo scripts` namespace for advanced/debug use.
+`fimo validate` is the single entrypoint for "prove this project is ready" — it covers schema/form codegen, route metadata checks, lint, and missing label checks for `i18n.defaultLocale` from `.fimo/config.json` (fallback: `en`). Use `fimo labels set` / `set-many` to create or update label values in the DB. The underlying phases are also available individually under the hidden `fimo scripts` namespace for advanced/debug use.
 
 ## Decision Tree
 
 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`
+- "Create a new Fimo project / scaffold a site / start a new website / add the opt-in content starter / link an existing project locally" → `references/init.md`
 - "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
@@ -102,8 +104,9 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Modify the URL of the website / change my project's address / connect a custom domain (e.g. blog.example.com) / rename the Fimo-provided `*.fimo.site` subdomain / buy a new domain through Fimo / set up a domain" → `references/domains.md`
 - "Invite a collaborator / add Marc / share with client" → `references/invite.md`
 - "Login / log out / who am I / switch organization" → `references/account.md` — note: switching **org** is `fimo orgs switch`; bare `fimo switch` switches **env** (see `references/branches.md`)
-- "Create / scaffold / run / validate / activate / deactivate an agent / agent bundle / list agent templates / view agent runs, reports, or logs (`fimo agents *`)" → `references/agents.md`
+- "Create / scaffold / run / validate an agent / agent bundle / wire or enable its triggers / 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`
+- "Connect an AI coding client to a Fimo project through MCP / configure `fimo mcp` / expose Fimo tools to a local MCP client" → `references/mcp.md`
 - "Refresh / update installed Fimo skills / fimo skills sync / agent missing the latest fimo conventions" → `references/agent-setup.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`
@@ -128,16 +131,18 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 
 ## Anti-Patterns
 
-- **Editing `.fimo.settings.json`** — read-only; it's the link between local and remote project. Treat as a generated file.
+- **Editing `.fimo/project.json`** — read-only; it's the link between local and remote project. Treat as a generated file.
 - **Treating `fimo deploy` as the working loop or a required final step** — the loop is local (`pnpm dev` etc.). Deploy commits + pushes + round-trips the sandbox; it's for hosted previews / going live, on-demand. Iterate locally and deploy at logical breakpoints. See `references/deploy.md`.
 - **Deploying without the developer asking or confirming** — offer, then wait for their yes. Don't auto-deploy after finishing an edit.
 - **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.
+- **Using a starter on an existing project** — `--starter` is create-new only. Keep `--project-id` flows blank and use explicit content/form/label commands when changing an existing project.
+- **Treating a starter as a permanent demo tenant** — starters are opt-in seed data in the new project, not a global default. Keep starter agents manual-only; do not add schedules or webhooks unless the project owner explicitly asks for automation.
 - **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`).
 - **Treating the daily allowance as extra credits** — `fimo credits` already includes spendable daily free credits in "Available now"; the allowance section is accounting context, not an amount to add.
 - **Trying to refill credits from the CLI** — `fimo credits` is read-only. Buying/refilling credits belongs in the billing UI for now.
-- **`fimo agents activate` / `run` to push bundle changes** — they don't. The bundle reaches the server through `fimo deploy` (it lives in git, not the DB). `activate` only writes activation rows; `run` dispatches the _deployed_ version. Deploy first. See `references/agents.md`.
+- **`fimo agents run` to push bundle changes** — it doesn't. The bundle reaches the server through `fimo deploy` (it lives in git, not the DB), and that push to `main` is also what wires the declared triggers. `run` dispatches the _deployed_ version. Deploy first. There is no `activate` command. See `references/agents.md`.

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

@@ -2,27 +2,26 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-The `fimo agents` namespace authors and operates **agent bundles** — multi-file definitions under `<project>/agents/<name>/` (a `config.yaml`, a `GOAL.md`, optional `capabilities.yaml`, etc.).
+The `fimo agents` namespace authors and operates **agent bundles** — multi-file definitions under `<project>/.fimo/agents/<name>/` (a `config.yaml`, a `GOAL.md`, optional `capabilities.yaml`, etc.). Legacy projects keep using root `agents/<name>/`.
 
 ## Mental model
 
 The namespace splits cleanly in two:
 
-- **Bundle authoring** — `create`, `list-templates`, `list`, `validate`, `secrets add/remove/list`. Local config editing, no API call except the project-level validation path. Operates on the files under `agents/<name>/`.
-- **Cloud ops** — `run`, `activate`, `deactivate`, `runs`, `report`, `logs`. Env-aware, talk to the server. Default `--env` is `main`; `--project` defaults to the `projectId` in `.fimo.settings.json`.
+- **Bundle authoring** — `create`, `list-templates`, `list`, `validate`, `secrets add/remove/list`. Local config editing, no API call except the project-level validation path. Operates on the files under `.fimo/agents/<name>/` (or root `agents/<name>/` for legacy projects).
+- **Cloud ops** — `run`, `runs`, `report`, `logs`. Env-aware, talk to the server. Default `--env` is `main`; `--project` defaults to the linked project in `.fimo/project.json` or legacy `.fimo.settings.json`.
 
-The bundle lives in **git** (`agents/<name>/`), not the database. The DB only holds **activations** (which triggers are wired on which env) and **run sessions**. So the bundle reaches the server through `fimo deploy`, not through `activate`/`run`.
+The bundle lives in **git** (`.fimo/agents/<name>/`, or legacy root `agents/<name>/`), not the database. The DB only mirrors what `config.yaml` declares on `main` (which triggers are wired) plus **run sessions**. So the bundle reaches the server through `fimo deploy` — and that push to `main` is also what wires its triggers. There is no activate command: deploying IS the enablement act, and removing a trigger from `config.yaml` tears it down on the next deploy.
 
 Typical flow:
 
 ```
-fimo agents create <name>     # scaffold agents/<name>/ from a template (local)
+fimo agents create <name>     # scaffold .fimo/agents/<name>/ from a template (local)
 fimo agents secrets add <name> FIRECRAWL_API_KEY  # request a project secret in config.yaml
 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 deploy                   # push to main — this also wires the declared triggers
 fimo agents run <name>        # trigger a manual run → sessionId
 fimo agents runs <name>       # see past sessions
 fimo agents report <name>     # print a run's report (the agent's final message)
@@ -42,45 +41,94 @@ fimo agents secrets remove <name> <KEY> [-C <dir>]
 ```
 
 - **`list-templates`** — list the bundled starter templates with the first line of each template's `GOAL.md` as a summary. Ships with the CLI binary; no API call. The five bundled templates are `_default`, `seo-audit`, `content-translator`, `broken-link-sweeper`, `post-deploy-check`.
-- **`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 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`.
+- **`create <name>`** — scaffold `.fimo/agents/<name>/` from a template (default `_default`, a minimal valid bundle with a manual trigger). `--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/project.json` or legacy `.fimo.settings.json`) and errors out cleanly otherwise, so it never leaks an agent bundle 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>/.fimo/agents/` (or legacy root `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 project config 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 `.fimo/agents/<name>/config.yaml` (or legacy root). 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 `.fimo/agents/<name>/config.yaml` (or legacy root) 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:
+Agent integration access is configured in `.fimo/agents/<name>/config.yaml` (or legacy root). Enable the integration there; omit `tools` to allow all tools that integration exposes, or add a `tools` map to keep the agent on a smaller set:
 
 ```yaml
 integrations:
   firecrawl:
     enabled: true
-    tools:
-      scrape: true
-      search: true
+```
+
+An explicit map is restrictive: only entries set to `true` are available. An omitted or disabled integration cannot be
+used. See `references/integrations.md` for project setup, auth, and provider-specific commands.
+
+## Capabilities
+
+Capabilities describe the non-integration actions an agent may take. Start with the smallest set that matches the goal.
+If `capabilities.yaml` is absent or empty, the agent gets the read-only defaults: `files:read`, `cms:read`, and
+`assets:read`. Once you add a capabilities file, list every extra capability the agent needs.
+There is no all-capabilities wildcard; keeping the list explicit makes each agent's power reviewable.
+
+| Capability                   | Allows the agent to                         | Risk         |
+| ---------------------------- | ------------------------------------------- | ------------ |
+| `files:read`                 | Read project files                          | Low          |
+| `files:write`                | Write or delete project files               | Medium       |
+| `cms:read`                   | Read CMS content                            | Low          |
+| `cms:write`                  | Create, update, or delete CMS entries       | Medium       |
+| `cms:schema:read`            | Read CMS schemas                            | Low          |
+| `cms:schema:write`           | Modify CMS schemas                          | High         |
+| `assets:read`                | Read uploaded media                         | Low          |
+| `assets:write`               | Upload, replace, or delete media            | Medium       |
+| `i18n:read` / `i18n:write`   | Read / modify translation catalogs          | Low / Medium |
+| `forms:read` / `forms:write` | Read / modify form schemas and submissions  | Low / Medium |
+| `git:read`                   | Read git state                              | Low          |
+| `git:branch`                 | Create an agent branch                      | Medium       |
+| `git:commit`                 | Commit changes to the agent branch          | Medium       |
+| `git:push`                   | Push changes to the project remote          | High         |
+| `fimo:logs:read`             | Read production logs                        | Low          |
+| `fimo:analytics:read`        | Read analytics data                         | Low          |
+| `fimo:preview:read`          | Read a current preview URL                  | Low          |
+| `fimo:deploy`                | Trigger a production deploy                 | Critical     |
+| `net:fetch`                  | Make outbound HTTP requests                 | Medium       |
+| `shell:exec`                 | Run arbitrary shell commands in the sandbox | High         |
+| `agent:delegate`             | Invoke declared sub-agents                  | Medium       |
+| `runtime:long_running`       | Run beyond the default time limit           | High         |
+| `runtime:auto_merge`         | Auto-merge trivial proposed branches        | Critical     |
+
+If a capability is missing, the related command is denied and the agent should choose another path or report the
+blocker. Add the capability to `capabilities.yaml`, run `fimo agents validate <name>`, deploy the bundle, and start a
+new run. A denied capability does not grant access to anything else.
+
+Example for a content editor that can read and update entries but cannot change schemas or run shell commands:
+
+```yaml
+- files:read
+- cms:read
+- cms:write
 ```
 
 ## Cloud ops (env-aware)
 
 ```bash
 fimo agents run <name> [--env <env>] [--project <id>] [--skip-drift-check] [-C <dir>]
-fimo agents activate <name> [--trigger <type>] [--env <env>] [--project <id>] [--quiet] [-C <dir>]
-fimo agents deactivate <name> [--trigger <type>] [--env <env>] [--project <id>] [-C <dir>]
 fimo agents runs <name> [--limit <n>] [--env <env>] [--project <id>] [-C <dir>]
 fimo agents report <name> [--session <id>] [--env <env>] [--project <id>] [-C <dir>]
 fimo agents logs <name> [--session <id>] [--project <id>] [-C <dir>]
 ```
 
-- **`run <name>`** — trigger a real manual run on the server; prints a `sessionId` on success (or a skip reason when the server short-circuits). **Pre-flight drift check**: if `agents/<name>/` has uncommitted git changes, the command refuses — the server would dispatch the _deployed_ version, so deploy first. Pass `--skip-drift-check` to dispatch the deployed bundle anyway. Defaults `--env` to `main`.
-- **`activate <name>`** — wire the agent's triggers on an env (writes `agent_activations` rows). A `schedule` trigger creates a cron, a `webhook` trigger reserves a path, and `manual` just enables dispatch. `--trigger <type>` (`schedule` / `webhook` / `manual`) activates only that type; otherwise all declared triggers. **The bundle must be deployed first.** Cloud triggers (`schedule` / `webhook`) require `notifications.email_recipients` in `fimo-config.json` (the dash-form scaffold file; legacy `fimo.config.json` is also accepted). Capability install-consent runs unless `--quiet`.
-- **`deactivate <name>`** — remove activation rows on an env. Idempotent. `--trigger <type>` scopes to a single trigger type.
+- **`run <name>`** — fire the agent's `manual` trigger on the server; prints a `sessionId` on success. Skips with `no-manual-trigger` when `config.yaml` declares none, or `trigger-not-wired` when the push-to-main sync recorded the trigger but refused to wire it (see the wiring note below). **Pre-flight drift check**: if `.fimo/agents/<name>/` (or the legacy root bundle) has uncommitted git changes, the command refuses — the server would dispatch the _deployed_ version, so deploy first. Pass `--skip-drift-check` to dispatch the deployed bundle anyway. Defaults `--env` to `main`.
 - **`runs <name>`** — list past run sessions for the agent in a compact table (id, started, duration, status, trigger, env, cost). Default `--limit 20`; `--env` filters to one env.
 - **`report <name>`** — print a run's **report**: the agent's final message, captured when the run finishes (for a read-only agent like `seo-audit` this _is_ the audit; for a write agent it's a "what I changed" summary). With no `--session`, the most recent run for `<name>` is used (combine with `--env` to scope); `--session <id>` targets a specific run. Output is raw markdown, so it stays readable in the terminal and pipes cleanly (e.g. `fimo agents report seo-audit | glow`). If the run hasn't finished, or produced no message, it says so (and shows the stop reason when there is one). This is the command to read what a run actually produced — see the `logs` note below.
 - **`logs <name>`** — stream a run's log (defaults to the latest session; `--session <id>` targets one). **Note:** the log-streaming endpoint is still a server-side stub at time of writing — the command prints a placeholder rather than real log lines. To read a finished run's output today, use `report`.
 
+## How triggers get wired
+
+Agents are not env-scoped: they belong to the project, are read from `main`, and their triggers are global. A branch env has no agents of its own — Studio's agents view shows main's agents whichever env you are on, and a bundle sitting only on a feature branch appears nowhere until it reaches main.
+
+Pushing `.fimo/agents/<name>/config.yaml` (or a legacy root bundle) to `main` is the whole enablement act — `fimo deploy` does it. The server reconciles the file into its trigger rows on every push: a `schedule` trigger gets a cron, a `webhook` trigger gets its path, and `manual` becomes runnable. Removing a trigger from the file deletes it (cron torn down, path released) on the next deploy; deleting the agent's directory removes the whole deployment.
+
+Cloud triggers (`schedule` / `webhook`) additionally require `notifications.email_recipients` in `.fimo/config.json` (legacy root `fimo-config.json` and `fimo.config.json` are also accepted). Without it the trigger is recorded but deliberately left **unwired** and will not fire — `fimo agents validate` warns about this before you deploy, and the Studio agents view shows the reason afterwards.
+
 ## `-C, --cwd <dir>`
 
-Every `fimo agents` command accepts `-C, --cwd <dir>` to point at a different project directory. For the cloud-ops commands, `--project <id>` overrides the project id otherwise read from `.fimo.settings.json`.
+Every `fimo agents` command accepts `-C, --cwd <dir>` to point at a different project directory. For the cloud-ops commands, `--project <id>` overrides the project id otherwise read from `.fimo/project.json` or legacy `.fimo.settings.json`.
 
 ## Non-interactive use
 
-Authoring commands (`list-templates`, `list`, `validate`) never prompt. `create` and `activate` run an install-consent flow when the bundle declares capabilities — pass `--quiet` to skip it in scripts / CI (critical capabilities still abort).
+No `fimo agents` command prompts — authoring and cloud ops both run unattended.

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

@@ -41,11 +41,11 @@ All of these accept the global `--env` override. `diff`, `status`, `merge`, and
 
 > **`fimo switch` is the ENV switcher, not the org switcher.** To change your active organization, use `fimo orgs switch` — see `references/account.md`.
 
-## The 7 surfaces
+## The 6 surfaces
 
 `status`, `diff`, and `merge` all reason over the same per-env surfaces, in this order:
 
-`code` · `schemas` · `content` · `translations` · `assets` · `forms` · `activations` (agent activations)
+`code` · `schemas` · `content` · `translations` · `assets` · `forms`
 
 `--surface <name>` on `diff` and the per-surface flags on `status` (`--code`, `--content`, `--i18n`, `--agents`, `--assets`, `--forms`) filter to one of them.
 

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

@@ -34,6 +34,8 @@ 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.
 
+Blocks schemas support at most 7 nested `blocks` levels, 40 variants in one `schema.oneOf`, and `min` or `max` values up to 200 items per blocks field. Load `fimo/references/content.md` for the complete blocks JSON shape.
+
 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-Single removes that type's entries and cleans inbound references; Single-to-collection preserves its entry. Run `fimo validate` after pushing.
 
 ## Singles CLI commands

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

@@ -2,7 +2,7 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-`fimo credits` is a read-only command for checking the AI credit balance of the organization that owns a Fimo project. It resolves the project from `.fimo.settings.json` unless `--project <project-id>` is provided.
+`fimo credits` is a read-only command for checking the AI credit balance of the organization that owns a Fimo project. It resolves the project from `.fimo/project.json` unless `--project <project-id>` is provided.
 
 ```bash
 fimo credits

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

@@ -98,7 +98,7 @@ fimo deploy
 ## Other facts
 
 - Source of truth is this git repo.
-- **Never** edit `.fimo.settings.json`; it is written once by `fimo init`.
+- **Never** edit `.fimo/project.json`; it is generated by `fimo init`.
 - Each env deploys to its own branch + preview sandbox; `--publish` and `fimo publish` run from `main` only. See `references/branches.md`.
 
 ## After the first successful deploy

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

@@ -78,4 +78,4 @@ The scoped view still emits the project-level metadata header (name, framework,
 
 - The JSON shape is stable; parse it rather than scraping the human output when you need a specific field.
 - The `framework` field is detected from `package.json#dependencies` (v1 detector). For multi-framework projects or unusual setups, the field may be `null` — fall back to reading `package.json` yourself.
-- The command runs in any directory that contains `.fimo.settings.json` or one of its ancestors. If you're not in a Fimo project, `describe` will run against whatever directory you point it at (it doesn't require Fimo credentials).
+- The command runs in any directory that contains `.fimo/project.json` or one of its ancestors. If you're not in a Fimo project, `describe` will run against whatever directory you point it at (it doesn't require Fimo credentials).

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

@@ -13,7 +13,7 @@ fimo history create "Before content migration"
 fimo history restore <version-id>
 ```
 
-Use the global `--env <name>` option to target a different environment. Use `--project <id>` when there is no local `.fimo.settings.json`.
+Use the global `--env <name>` option to target a different environment. Use `--project <id>` when there is no local `.fimo/project.json`.
 
 ## Pagination and usage
 

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

@@ -13,44 +13,79 @@ fimo init [dir] [options]
 `fimo init` runs the full onboarding in one shot:
 
 1. **Signs in automatically** — if there's no session it opens the browser loopback login. In `--json` / non-TTY with no session it fails with `NOT_AUTHENTICATED` (run `fimo login` first).
-2. **Resolves the project** — with `--project-id <id>` it links an EXISTING project (clones it); without it, it creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new.
+2. **Resolves the project** — with `--project-id <id>` it links an EXISTING project (clones it); without it, it creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. An optional `--starter fimo-site@1` adds a content-led starter only to a newly created project.
 3. **Installs dependencies** — prompts for the package manager, or honor `--package-manager <pm>` / `--no-install`.
 4. **Optionally sets up Fimo skills** — confirm prompt, or `--skills` / `--no-skills`.
 
-| Flag                         | Required                      | Purpose                                                                                                                                            |
-| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                  |
-| `--project-id <id>`          | no                            | Link an EXISTING project instead of creating one (clones it).                                                                                      |
-| `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY. |
-| `--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                | 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`.                                                                                                       |
-| `--template-root <path>`     | no                            | Override the bundled template (development only).                                                                                                  |
-| `-y, --yes`                  | no                            | Run non-interactively using defaults (no prompts).                                                                                                 |
+| Flag                         | Required                      | Purpose                                                                                                                                                        |
+| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                              |
+| `--project-id <id>`          | no                            | Link an EXISTING project instead of creating one (clones it).                                                                                                  |
+| `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.             |
+| `--env <name>`               | no                            | Env to check out when linking an existing project (defaults to `main`).                                                                                        |
+| `--starter <id>`             | no                            | Opt-in project starter for create-new (currently `fimo-site@1`). It seeds CMS content, labels, a contact form, and manual-only agents. Rejects `--project-id`. |
+| `--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                | 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`.                                                                                                                   |
+| `--template-root <path>`     | no                            | Override the bundled template (development only).                                                                                                              |
+| `-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.`
 
+### Non-interactive starter setup
+
+Use explicit flags when a script or agent owns the flow. `--json` gives the
+caller one stable result envelope; `--yes` is useful when running in a TTY but
+is not required in a pipe or CI shell. The starter is never selected by default.
+
+```bash
+npx fimo@latest --json init my-site \
+  --starter fimo-site@1 \
+  --org <organizationId> \
+  --no-install \
+  --no-skills \
+  --agents=none \
+  --yes
+```
+
+The command creates the project, copies the starter overlay, seeds its `HomePage`
+singleton, `contact` form, and labels in `main`, writes the form id into
+`src/forms/contact.json`, and commits the starter agents as manual-only bundles.
+`--starter` is create-new only; an existing-project command such as
+`fimo init --project-id <id> --starter fimo-site@1` fails before cloning or
+writing anything. If dependencies were skipped, install them and run
+`fimo validate` before starting the app so generated clients are present.
+
 > **Zero-install:** run `npx fimo@latest init` — no global install needed. `fimo projects create` is also an alias of `fimo init` (create-new path).
 
 For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for Claude Code, `--agents=cursor` for Cursor, `--agents=codex` for Codex, etc. When the flag is omitted, env-var detection of the invoking harness (e.g. `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT` → claude-code) auto-targets that agent; other agents must be selected explicitly via `--agents`/`-a` or the interactive picker.
 
 ## 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`, 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/project.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)
 
 `fimo init` (create-new path) scaffolds:
 
 - 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)
+- `.fimo/project.json` — links this directory to the remote project (read-only after creation)
+- `.fimo/config.json` — project, route, locale, SEO, and agent policy
+- `.fimo/agents/` — versioned agent bundles
 - `.env` — initial env vars (currently just `VITE_API_URL`)
 - `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
 
+When `--starter fimo-site@1` is supplied, the overlay also includes a
+content-backed homepage, `src/schemas/HomePage.json`, a `contact` form spec,
+nine English labels, and two read-only agent bundles (`site-review` and
+`content-guide`). The seed is opt-in and scoped to the new project; the default
+blank template and all existing-project flows remain unchanged. Starter agents
+declare only a manual trigger so copying them does not create schedules or
+webhooks.
+
 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`.
 
 Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md.

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

@@ -31,7 +31,7 @@ fimo integrations connect firecrawl --name client-a --token-stdin
 fimo integrations enable firecrawl --connection client-a
 ```
 
-`connect` creates or repairs an organization-level connection. `enable --connection <alias>` lets the current project use that connection. Teammates and agents can use the capability, but Fimo never prints the API key back.
+`connect` creates or repairs an organization-level connection. `enable --connection <alias>` lets the current project use that connection. Teammates and agents can use the integration, but Fimo never prints the API key back.
 
 There is no fallback between auth choices. If a named connection is selected and its key is missing or broken, repair the connection. If `fimo` is selected and the backend is not configured, report that Firecrawl needs backend setup.
 
@@ -155,7 +155,16 @@ For users, describe monitors as website change monitors: create a monitor, list
 
 ## Agent Access
 
-Project-level setup makes Firecrawl available to the project. Agent-level policy narrows what a specific agent may use.
+Project-level setup makes Firecrawl available to the project. Add Firecrawl to an agent's `config.yaml` to let that
+agent use it. If you omit `tools`, the agent gets every Firecrawl tool; use a tools map when you want a narrower set.
+
+```yaml
+integrations:
+  firecrawl:
+    enabled: true
+```
+
+Selective access:
 
 ```yaml
 integrations:
@@ -177,7 +186,7 @@ fimo validate
 fimo agents integrations seo-researcher
 ```
 
-For deployed or scheduled agents, deploy the bundle after changing `agents/<name>/config.yaml`:
+For deployed or scheduled agents, deploy the bundle after changing `.fimo/agents/<name>/config.yaml`:
 
 ```bash
 fimo deploy

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

@@ -14,7 +14,7 @@ fimo integrations status firecrawl
 
 `info` shows supported auth choices, required credentials, tools, and recipes. `status` shows the project-specific setup state.
 
-When running inside an autonomous agent session, `fimo integrations list` shows the effective integrations available to that agent runtime, scoped by `agents/<name>/config.yaml`. It lists only usable tools, plus the auth column and the config path that granted access.
+When running inside an autonomous agent session, `fimo integrations list` shows the effective integrations available to that agent runtime, scoped by `.fimo/agents/<name>/config.yaml`. It lists only usable tools, plus the auth column and the config path that granted access.
 
 ## Integration References
 
@@ -89,7 +89,19 @@ For Firecrawl-specific recipes, JSON examples, and agent policy guidance, load `
 
 ## Agent Access Policy
 
-Project integrations are enabled at the project level. Agents narrow access in `agents/<name>/config.yaml`:
+Project integrations are enabled at the project level. An agent opts into an integration in
+`.fimo/agents/<name>/config.yaml` (or the legacy root `agents/<name>/config.yaml`):
+
+When `tools` is omitted, the agent can use every tool currently exposed by that integration. Add a `tools` map only
+when the agent needs a narrower set:
+
+```yaml
+integrations:
+  firecrawl:
+    enabled: true
+```
+
+For a narrower allowlist, add the tools explicitly:
 
 ```yaml
 integrations:
@@ -101,7 +113,7 @@ integrations:
       'monitor.list': true
 ```
 
-Agent integration access is an allowlist. If an integration is omitted, disabled, or has no `tools` entries set to `true`, the agent cannot use it. New provider tools are not automatically available to old agents.
+If an integration is omitted or disabled, the agent cannot use it. If an explicit `tools` map has no `true` entries, it also grants no tools. With no map, newly available provider tools are included automatically on the next run.
 
 Run `fimo validate` after editing agent config to check local shape plus project-level integration setup.
 

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

@@ -93,4 +93,4 @@ fimo invite --email "dev@agency.com" --role full
 - Invited users receive an email with a sign-up link if they don't have an account, or a sign-in link if they do.
 - Organization invites can be resent with `--resend` if the user didn't receive the original.
 - Project invites are scoped to a single project; organization invites grant access to all projects in that organization.
-- If `--cwd` is set and the directory contains a `.fimo.settings.json`, the project is auto-selected.
+- If `--cwd` is set and the directory belongs to a linked Fimo project, that project is auto-selected.

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

@@ -29,7 +29,7 @@ There is no `fimo translations` command. Use `fimo labels`.
 
 ## Locale config
 
-`fimo-config.json` controls label/content locales:
+`.fimo/config.json` controls label/content locales:
 
 ```json
 {

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

@@ -6,7 +6,7 @@ This file covers CLI-side locale configuration and validation. For code helpers
 
 ## Configure Locales
 
-Edit `fimo-config.json`. Keep one locale unless the user asks for multilingual or localized output:
+Edit `.fimo/config.json`. Keep one locale unless the user asks for multilingual or localized output:
 
 ```jsonc
 {
@@ -40,13 +40,13 @@ Validation checks:
 - malformed locale tags
 - `defaultLocale` missing from `locales`
 - unsupported routing strategies
-- canonical routes in `fimo-config.json` that claim reserved locale prefixes, for example `/es`
+- canonical routes in `.fimo/config.json` that claim reserved locale prefixes, for example `/es`
 - top-level dynamic routes that could capture locale prefixes unless the project uses Fimo's React Router helper
 - missing default-locale DB labels
 
 ## Route Metadata Rule
 
-Keep `fimo-config.json#routes` canonical and unlocalized:
+Keep `.fimo/config.json#routes` canonical and unlocalized:
 
 ```json
 {
@@ -71,7 +71,7 @@ For custom frameworks, the project may implement its own URL scheme, but it stil
 
 Inspect the existing locale provider, route table, switcher, redirects, and public URLs before editing configuration. Preserve working URL behavior during the migration.
 
-For React Router projects, prefer one contract based on `fimo-config.json`, `fimoRoutes()`, and `FimoLink`; migrate existing wrappers into the framework root instead of layering a second locale context. If that would change established URLs, keep the custom router temporarily, pass its active locale to `FimoProviders`, and ask the user to choose canonical URLs and redirects before rewriting routes.
+For React Router projects, prefer one contract based on `.fimo/config.json`, `fimoRoutes()`, and `FimoLink`; migrate existing wrappers into the framework root instead of layering a second locale context. If that would change established URLs, keep the custom router temporarily, pass its active locale to `FimoProviders`, and ask the user to choose canonical URLs and redirects before rewriting routes.
 
 ## Labels And Content