fimo 0.11.0-staging.5 → 0.11.0-staging.6

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
 

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
 
@@ -70,7 +71,7 @@ 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
 
@@ -104,6 +105,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "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 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,7 +130,7 @@ 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`.

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

@@ -2,21 +2,21 @@
 
 > **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`, `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 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.
+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
@@ -41,21 +41,66 @@ 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). `--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)
@@ -67,7 +112,7 @@ fimo agents report <name> [--session <id>] [--env <env>] [--project <id>] [-C <d
 fimo agents logs <name> [--session <id>] [--project <id>] [-C <dir>]
 ```
 
-- **`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 `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`.
+- **`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`.
@@ -76,13 +121,13 @@ fimo agents logs <name> [--session <id>] [--project <id>] [-C <dir>]
 
 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 `agents/<name>/config.yaml` 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.
+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` (the dash-form scaffold file; legacy `fimo.config.json` is 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.
+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
 

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

@@ -39,14 +39,16 @@ For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for C
 
 ## Linking an existing project
 
-Pass `--project-id <id>` to link an EXISTING project instead of creating one. This clones the project's git repo into `[dir]` and writes the local `.fimo.settings.json`, 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

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
 

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

@@ -0,0 +1,85 @@
+# Project MCP
+
+> **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
+
+The **Project MCP** lets an AI coding client use Fimo's project workflows through the Model Context Protocol. It is
+the same Fimo tool surface exposed in two ways:
+
+- **Local MCP**: `fimo mcp` over stdio, for an AI client running next to a checkout.
+- **Remote MCP**: `https://api.fimo.ai/api/mcp` over authenticated Streamable HTTP, for ChatGPT, Claude, and other
+  clients that support OAuth.
+
+The local and remote Project MCP modes share the same catalog. The public Docs MCP at
+`https://fimo.ai/docs/mcp` is separate: it is unauthenticated, read-only, and only provides Fimo documentation.
+
+## Set up the local MCP
+
+Authenticate the CLI first:
+
+```bash
+npx fimo@latest login
+```
+
+Then configure the MCP client to launch:
+
+```text
+npx fimo@latest mcp
+```
+
+For clients that accept a JSON command configuration, the equivalent entry is:
+
+```json
+{
+  "mcpServers": {
+    "fimo": {
+      "command": "npx",
+      "args": ["fimo@latest", "mcp"]
+    }
+  }
+}
+```
+
+Do not add shell output or logging around the command: stdout is reserved for MCP JSON-RPC frames. Diagnostics are
+written to stderr.
+
+## Project and environment scope
+
+When launched inside a linked Fimo project, `fimo mcp` reads the project from `.fimo.settings.json` and uses the
+current git branch as the default environment. This keeps an AI client working against the same project environment as
+the checkout.
+
+Outside a linked project, the server still works, but each project-scoped tool call must provide `projectId` and
+`env`. The client can also pass an environment override when launching the CLI. Never edit `.fimo.settings.json`
+manually to change scope.
+
+The CLI credential represents the signed-in user's Fimo authority. If an MCP server is invoked from a Fimo agent
+session, the session's frozen capability snapshot still limits the operations available to that agent.
+
+## Capabilities
+
+The Project MCP catalog covers:
+
+- **Identity and navigation** — current user, projects, and environments.
+- **Content** — schemas, collection entries, search, create/update/delete, bounded bulk operations, and Singles.
+- **Labels** — list, read, set, batch-set, and delete localized labels.
+- **Media** — list and inspect assets, generate images or videos, create folders, move, and delete assets. Binary
+  upload remains `fimo assets upload`.
+- **Forms** — create, read, update, and delete forms; inspect submissions and statistics.
+- **Files** — read, glob, grep, write, edit, and delete project files within the scoped environment. Sensitive files
+  such as credentials and `.env` files are excluded.
+- **Agents** — list agents, start a run, and inspect run status.
+
+Use the MCP client's tool list as the wire-level source of truth. The catalog is shared with the remote endpoint, so a
+client configured locally sees the same tool names and input shapes as a remote client.
+
+## Local versus remote authorization
+
+Local MCP uses the stored CLI credential (or `FIMO_API_TOKEN` when explicitly configured). It does not use the
+browser OAuth consent screen. Remote MCP uses Fimo OAuth with `read`, `write`, and `agents` scopes; the user selects
+the optional capabilities during consent.
+
+In both modes, Fimo still checks the user's project permissions, environment access, input validation, and file safety
+rules for every operation. MCP does not grant access to projects the user cannot already access.
+
+For ChatGPT, Claude, or another remote MCP client, use the setup guide in the public [MCP documentation](https://fimo.ai/docs/ai/mcp)
+instead of the local stdio configuration above.

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

@@ -62,7 +62,7 @@ fimo agents secrets remove seo-publisher FIRECRAWL_API_KEY
 fimo agents validate
 ```
 
-`fimo agents secrets add` edits `agents/<name>/config.yaml`. It does not create or rotate the secret value. Use `fimo secrets add` to create the value or `fimo secrets update` to rotate it.
+`fimo agents secrets add` edits `.fimo/agents/<name>/config.yaml`. It does not create or rotate the secret value. Use `fimo secrets add` to create the value or `fimo secrets update` to rotate it.
 
 `fimo agents validate` checks that required agent secrets exist in the project. A running agent keeps the environment it started with; the next run reads the deployed agent config again.
 

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

@@ -2,7 +2,7 @@
 
 > **Run via `npx fimo@latest <command>`** — always the latest CLI, no install needed.
 
-Commands for listing projects across an org, cloning a remote project locally, and managing the lifecycle of a single project (delete, publish, unpublish, rename). Most lifecycle commands operate on the **current project** (read from `.fimo.settings.json` in the cwd) by default; for `delete`, `publish`, and `unpublish` you can pass an explicit `[projectId]` to target another. (`rename` is local-only — it never targets a different project; see below.)
+Commands for listing projects across an org, cloning a remote project locally, and managing the lifecycle of a single project (delete, publish, unpublish, rename). Most lifecycle commands operate on the **current project** (read from `.fimo/project.json`, or the legacy `.fimo.settings.json`, in the cwd) by default; for `delete`, `publish`, and `unpublish` you can pass an explicit `[projectId]` to target another. (`rename` only edits the linked local project; see below.)
 
 ## The `fimo projects` namespace
 
@@ -13,15 +13,15 @@ fimo projects clone [projectId] [dir] [--env <name>] # clone an existing project
 fimo projects delete [projectId] [-C <dir>] [-y] # delete (defaults to current project)
 fimo projects publish [projectId] [-C <dir>]     # make the project live (publish from main)
 fimo projects unpublish [projectId] [-C <dir>]   # take the project offline
-fimo projects rename <name> [projectId] [-C <dir>]   # local-only: set seo.siteName in fimo-config.json
+fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the linked project config
 ```
 
 - **`list`** — projects you can see in the org. Live projects are marked.
 - **`create`** — identical to `fimo init` (create-new path); see `references/init.md`.
-- **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo.settings.json`/agent files. Use `fimo clone <projectId>` when scripting or when the ID is known. In an interactive terminal, bare `fimo clone` opens a project picker for the active org; JSON mode and non-TTY shells require an explicit project ID and fail fast instead of prompting. By default it clones `main`; pass `--env <name>` to clone a specific env. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
+- **`clone`** — clone a remote Fimo project's git repo to your machine and write the local `.fimo/project.json` and agent files. Use `fimo clone <projectId>` when scripting or when the ID is known. In an interactive terminal, bare `fimo clone` opens a project picker for the active org; JSON mode and non-TTY shells require an explicit project ID and fail fast instead of prompting. By default it clones `main`; pass `--env <name>` to clone a specific env. The target directory defaults to the project display name/name, or pass `[dir]` explicitly.
 - **`delete`** — destructive; prompts unless `-y`. Removes the remote project.
 - **`publish` / `unpublish`** — toggle the project's public visibility. `publish` flips the current `main` state live (the same "go live" as `fimo deploy --publish`, minus the git push). This is **not** the versioned release path — for that, see `fimo publish` in `references/branches.md`.
-- **`rename`** — **local-only**, unlike the others. It does not touch the remote project record. It requires `.fimo.settings.json` in the cwd, and if you pass a `[projectId]` that doesn't match the linked project it errors and exits 1 (so you can't rename a different project). It writes `seo.siteName` into the local `fimo-config.json`; you must commit and run `fimo deploy` to apply the change.
+- **`rename`** — edits only the linked local project immediately. It requires a project marker in the cwd, and if you pass a `[projectId]` that doesn't match the linked project it errors and exits 1 (so you can't rename a different project). It writes `seo.siteName` into the current or legacy project config; commit and run `fimo deploy` to reconcile the remote `displayName` and deploy the new site name.
 
 ## Top-level clone shortcut
 
@@ -33,15 +33,15 @@ Use the top-level shortcut for the common "get this project onto my machine" wor
 
 ## Top-level shortcuts (current project)
 
-These target the project linked in the cwd's `.fimo.settings.json` — handy from inside a project directory:
+These target the project linked in the cwd's `.fimo/project.json` (or legacy `.fimo.settings.json`) — handy from inside a project directory:
 
 ```bash
 fimo delete [-C <dir>] [-y]      # delete the current project
 fimo unpublish [-C <dir>]        # unpublish the current project
-fimo rename "<Site Name>"        # local edit: set seo.siteName in fimo-config.json
+fimo rename "<Site Name>"        # local edit: set seo.siteName in the project config
 ```
 
-`fimo rename` sets the **site name** (`seo.siteName`) in the local `fimo-config.json` — it is a local edit, not a remote update, so it requires a follow-up commit + `fimo deploy` to take effect. It does **not** change the project's remote display name (the `displayName` shown by `projects list`), which is set once at creation time from the project directory name. See `references/init.md` and `references/deploy.md`.
+`fimo rename` sets the **site name** (`seo.siteName`) in the local project config — it is a local edit, not an immediate remote update, so it requires a follow-up commit + `fimo deploy` to take effect. Deploy reconciles the project's remote `displayName` with the committed site name while pushing the config. See `references/init.md` and `references/deploy.md`.
 
 ## Three "publish" verbs — don't confuse them
 

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

@@ -21,11 +21,11 @@ In development, the generated app reloads when DB label values change. In produc
 
 ## Locale behavior
 
-The default label locale is `i18n.defaultLocale` in `fimo-config.json`, falling back to `en` when it is not set. `fimo validate`, the generated app runtime, and `fimo labels set` without `--locale` all use that default locale.
+The default label locale is `i18n.defaultLocale` in `.fimo/config.json`, falling back to `en` when it is not set. `fimo validate`, the generated app runtime, and `fimo labels set` without `--locale` all use that default locale.
 
 For non-default locales, create explicit DB values with `fimo labels set --locale <locale>` or `fimo labels set-many --locale <locale>`. Keep the code shape the same for every locale: `t('hero.title')` declares the key, and the DB decides which locale value is shown.
 
-`fimo-config.json` owns the locale list:
+`.fimo/config.json` owns the locale list:
 
 ```json
 {