fimo 0.21.0-staging.3 → 0.21.0-staging.5

package/assets/skills/fimo/SKILL.md

@@ -33,7 +33,7 @@ Pick by task:
 - Project creation, local setup, cloning, and CLI workflows — init, push, deploy, sync, labels, domains, analytics → `fimo-cli`
 - Fimo agents — create, configure, validate, deploy, run, or inspect them → `fimo-cli` (`references/agents.md`)
 - AI agent setup — connect Claude Code, Codex, Cursor, or another agent → `fimo-cli` (`references/agent-setup.md`)
-- Project MCP setup — configure `fimo mcp` for a local agent → `fimo-cli` (`references/mcp.md`)
+- Remote MCP integrations — add, inspect, search, or run an MCP server → `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

@@ -106,7 +106,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` changes the active **Fimo Branch** (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 agent / fimo skills install / set up Claude Code, Codex, or Cursor for Fimo" → `references/agent-setup.md`
-- "Connect an agent to a Fimo project through MCP / configure `fimo mcp` / expose Fimo tools to a local MCP client" → `references/mcp.md`
+- "Add, inspect, search, or run a remote MCP server / use `fimo mcp`" → `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`

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

@@ -2,6 +2,10 @@
 
 Use integrations to enable external services for a Fimo project. API keys are stored by Fimo and never printed back to the CLI. Teammates and agents receive access to the integration, not the underlying token.
 
+Start with `fimo integrations list` whenever the task could benefit from an external service. It is the project-scoped,
+runtime-truthful inventory; use `info` only for the relevant integration instead of loading every provider's tools into
+context.
+
 ## Inspect
 
 ```bash
@@ -14,6 +18,26 @@ fimo integrations status firecrawl
 
 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.
 
+## Add a remote MCP server
+
+Remote MCP servers have a focused command group while remaining integrations underneath:
+
+```bash
+fimo mcp add sentry --url https://mcp.sentry.dev/mcp
+
+fimo mcp search "issue tracking"
+fimo mcp info sentry
+fimo mcp run sentry <tool> --input '{"key":"value"}'
+```
+
+Automatic discovery connects public endpoints directly and opens the provider authorization page for OAuth servers.
+Use `--auth none` to require a public endpoint, `--auth bearer --token-stdin` for a bearer token, or `--auth header
+--header-name <name> --token-stdin` for a custom private header. A custom header value is sent exactly as piped, so it
+carries any prefix itself. Fimo requires an HTTPS Streamable HTTP endpoint,
+encrypts credentials, assigns an `mcp_`-prefixed integration key, and reads the server's current tools live. OAuth and
+manual headers are alternative grants and are never sent together. Local stdio commands such as `npx` are not supported. Agents continue to use `fimo integrations list|info|run`
+so native and MCP providers share one runtime policy surface.
+
 ## Integration References
 
 Load the integration reference when the user names a specific integration:

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

@@ -1,83 +1,124 @@
-# Project MCP
+# Remote MCP integrations
 
-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:
+Use the `mcp` command group to connect a project to remote Model Context Protocol servers. Fimo stores the connection,
+keeps its credential server-side, and makes the server's tools available through the same integration gateway as native
+providers.
 
-- **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.
+## Add a server
 
-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.
+Start with automatic discovery:
 
-## Set up the local MCP
+```bash
+fimo mcp add sentry --url https://mcp.sentry.dev/mcp
+```
 
-Authenticate the CLI first:
+Fimo connects public servers immediately. When the server advertises OAuth, Fimo opens its authorization page. Use
+`--no-open` to print the URL for a browser on another machine.
+
+Bearer token:
 
 ```bash
-fimo login
+printf '%s\n' "$MCP_TOKEN" | fimo mcp add sentry \
+  --url https://mcp.sentry.dev/mcp \
+  --auth bearer \
+  --token-stdin
 ```
 
-Then configure the MCP client to launch:
+Multiple custom headers:
 
-```text
-fimo mcp
+```bash
+printf '%s\n' "$MCP_HEADERS_JSON" | fimo mcp add internal \
+  --url https://mcp.example.com/mcp \
+  --auth header \
+  --header Authorization \
+  --header X-Workspace \
+  --headers-stdin
 ```
 
-For clients that accept a JSON command configuration, the equivalent entry is:
-
-```json
-{
-  "mcpServers": {
-    "fimo": {
-      "command": "npx",
-      "args": ["fimo@latest", "mcp"]
-    }
-  }
-}
+`MCP_HEADERS_JSON` must be one JSON object containing every configured header and no others, for example
+`{"Authorization":"Bearer abc123","X-Workspace":"workspace-secret"}`. Header names are matched case-insensitively.
+**Each value is the complete header value and is sent byte for byte**, so include any prefix the server expects. There
+is no scheme or prefix option; anything the header needs goes in the value.
+
+Use `--auth none` for a public endpoint or `--auth bearer --token-stdin` for a bearer token, which is the shortcut for
+sending `Authorization: Bearer <token>` from the token alone. The single-header form,
+`--auth header --header-name <name> --token-stdin`, pipes one complete header value.
+
+Fimo requires an HTTPS Streamable HTTP endpoint, validates the MCP handshake before saving it, encrypts the credentials,
+and never prints their values. The resulting integration key begins with `mcp_` so it cannot collide with a native
+provider.
+
+OAuth and manual credentials are alternative connection grants. Fimo never sends custom secret headers alongside an
+OAuth access token.
+
+## Reconnect OAuth
+
+If live discovery or execution reports that an OAuth connection needs authorization again:
+
+```bash
+fimo mcp reconnect sentry
 ```
 
-Do not add shell output or logging around the command: stdout is reserved for MCP JSON-RPC frames. Diagnostics are
-written to stderr.
+This replaces the organization-owned OAuth grant and requires organization admin access. Add `--no-open` to print the
+authorization URL.
 
-## Project and Branch scope
+## Rotate credentials
 
-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 Branch. This keeps an AI client working against the same Branch as the checkout.
+Rotation replaces the complete credential bundle on the connection already enabled for this project:
 
-Outside a linked project, the server still works, but each project-scoped tool call must provide `projectId` and
-`env` (the compatibility-preserved wire field for a Branch name). The canonical catalog tool is `branches_list`;
-`envs_list` remains a compatibility alias. The client can also pass a Branch override when launching the CLI. Never
-edit `.fimo.settings.json` manually to change scope.
+```bash
+printf '%s\n' "$MCP_HEADERS_JSON" | fimo mcp rotate internal --headers-stdin
+printf '%s\n' "$MCP_TOKEN" | fimo mcp rotate sentry --token-stdin
+```
 
-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.
+Custom-header rotation requires the complete value of every configured header. It never merges a partial update, and
+neither command prints the submitted values. Rotation updates the organization-owned connection and requires organization admin access.
 
-## Capabilities
+## Discover servers and tools
 
-The Project MCP catalog covers:
+```bash
+fimo mcp list
+fimo mcp search "issue tracking"
+fimo mcp info sentry
+```
+
+- `list` shows only remote MCP integrations available to the current project.
+- `search` searches the live tool names and descriptions across those servers.
+- `info` shows one server's endpoint, authentication shape, and current live tool catalog.
+
+`info` and `run` accept either the short server name (`sentry`) or its complete integration key (`mcp_sentry`). The
+catalog is loaded live; Fimo does not persist or expose a stale copy to the model.
+
+## Run a tool
+
+```bash
+fimo mcp run sentry search_issues --input '{"query":"open regressions"}'
+fimo mcp run sentry projects_list
+fimo mcp run sentry search_issues --input @request.json
+```
+
+Omit `--input` when the tool takes no arguments. Use inline JSON, a project-relative `@file`, or `--input -` to read JSON
+from stdin.
 
-- **Identity and navigation** — current user, projects, and Branches.
-- **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, read canonical pages or ask one targeted question with `assets_read`, 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 Branch. Sensitive files
-  such as credentials and `.env` files are excluded.
-- **Agents** — list agents, start a run, and inspect run status.
+## Studio and project agents
 
-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.
+Remote MCP servers remain normal project integrations underneath the focused CLI. Studio chat and autonomous agents
+discover and run them through:
+
+```bash
+fimo integrations list
+fimo integrations info mcp_sentry
+fimo integrations run mcp_sentry search_issues --input '{"query":"open regressions"}'
+```
 
-## Local versus remote authorization
+An autonomous agent only sees integrations enabled in its committed `integrations:` policy. Studio receives a frozen
+snapshot of the integrations enabled when the turn starts. Neither surface receives the underlying credential or opens
+a direct connection to the remote server.
 
-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.
+## Supported servers
 
-In both modes, Fimo still checks the user's project permissions, Branch access, input validation, and file safety
-rules for every operation. MCP does not grant access to projects the user cannot already access.
+Remote connections support HTTPS Streamable HTTP servers with OAuth, no authentication, a bearer token, or custom
+private headers. Local stdio commands such as `npx`, arbitrary child processes, resources, and prompts are not supported.
 
-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.
+To connect ChatGPT, Claude, or another remote MCP client to Fimo itself, use Fimo's hosted Project MCP at
+`https://api.fimo.ai/api/mcp`. That is a separate direction from connecting a Fimo project to an external MCP server.

package/assets/skills/fimo-code/references/content/schema.md

@@ -23,6 +23,29 @@ Write one schema per `src/schemas/<Uid>.json`. The PascalCase filename must matc
 
 Required root keys: `uid`, `name`, and `fields`.
 
+## Group fields in Studio
+
+Use optional top-level `groups` when an entry has meaningful editing areas, such as Overview, Tickets, SEO, or Scheduling. They work best for longer forms where editors regularly work on one area at a time. Usually skip groups for short forms, one-field groups, or vague buckets such as General and Other. Prefer two to five groups organized around editor tasks. This is guidance, not a schema limit.
+
+Assign each top-level field with `group`; one field may appear in more than one group. This changes only the Studio layout, not stored content, generated types, validation, permissions, or what agents can edit.
+
+```json
+{
+  "uid": "Event",
+  "name": "Events",
+  "groups": [
+    { "id": "overview", "label": "Overview", "default": true },
+    { "id": "tickets", "label": "Tickets" }
+  ],
+  "fields": {
+    "title": { "type": "string", "group": "overview" },
+    "price": { "type": "number", "group": ["overview", "tickets"] }
+  }
+}
+```
+
+Group IDs must be unique, at most one group may be the default, and memberships must reference a declared group. Only top-level fields can be grouped; fields inside blocks cannot declare `group`.
+
 Use `"isSingleton": true` whenever the site has exactly one logical document: a homepage, site settings, an About page, or one campaign landing page. Do not turn it into a one-entry collection just to seed content; keep the Single and load `fimo-cli/references/content.md` for the `fimo singles update` workflow.
 
 ```json

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

@@ -6,7 +6,7 @@ description: >-
   Triggers: "in Fimo Studio", "in the dashboard", "in the web app",
   "how do I X in the UI", or screenshots of the dashboard. Topics
   covered: dashboard content and CMS, publishing from the dashboard,
-  dashboard SEO/domain settings, schedules and run history, outbound webhooks,
+  dashboard SEO/domain settings, project connections, schedules and run history, outbound webhooks,
   visual editing, version history UI, dashboard sharing/billing, dashboard chat,
   and the command palette. Never describe
   UI locations, buttons, or panels from memory — always read the relevant
@@ -41,6 +41,7 @@ Read the relevant reference file when the user's question matches a topic.
 | SEO Settings             | references/seo-settings.md              | "How do I set up SEO?", "Favicon, title, share image" |
 | Schedules                | references/schedules.md                 | "Recurring commands", "Run history", "Run now"        |
 | Webhooks                 | references/webhooks.md                  | "React to forms", "Send events to another service"    |
+| Connections              | references/connections.md               | "Connect a service", "Add an MCP server"              |
 | Preview & Responsive     | references/preview-and-responsive.md    | "How does it look on mobile?", "How do I test sizes?" |
 | Visual Editing           | references/visual-editing.md            | "Can I edit visually?", "How do I change colors?"     |
 | Version History          | references/version-history.md           | "How do I undo?", "How do I go back?"                 |
@@ -58,6 +59,7 @@ Read the relevant reference file when the user's question matches a topic.
 | Adding images           | Media Library, AI Chat, Edit Mode                                              |
 | Content/CMS             | AI Chat, Media Library                                                         |
 | Webhooks                | Project secrets, Forms, Publishing, Agents                                     |
+| Connections             | AI Chat, Agents, Project secrets                                               |
 | Schedules               | Project secrets, Environments, Agents                                          |
 | Visual changes          | Edit Mode (quick tweaks), AI Chat (bigger changes), Code Editor (full control) |
 | Something went wrong    | Version History, AI Chat                                                       |

package/assets/skills/fimo-studio/references/cms.md

@@ -83,6 +83,8 @@ Press **Alt+J** to move to the next entry or **Alt+K** to move to the previous o
 
 If a field is invalid, the editor keeps the change unsaved and pins a status bar below the header. Choose **Review issues** to jump to the first invalid field, then **Next issue** to move through the remaining fields. Collapsed blocks open automatically. Once every issue is fixed, the editor confirms that all fields are valid and resumes saving.
 
+Longer entry forms may have quiet field-group tabs below the header. Choose a group to focus on that part of the entry, or choose **All fields** for the complete form. Studio remembers the selected group for that content type during the browser session, and copied entry links preserve the active group. If validation finds a problem elsewhere, **Review issues** opens All fields before focusing it. Groups only change the editor view; they do not hide content from the API or restrict what the AI can edit.
+
 A field labelled with a padlocked globe is shared across languages: it holds one value for the whole entry, so editing it in any language changes it in all of them. Fields without that marker are per language and only affect the language you are editing. Hover the icon for the same explanation in context.
 
 ## Editing Text

package/assets/skills/fimo-studio/references/connections.md

@@ -0,0 +1,52 @@
+# Connections
+
+Connections let a project use external services without exposing credentials to editors, chat, or agents. Studio, the
+CLI, and project agents all resolve the same project-scoped connection state.
+
+## See what is available
+
+1. Open the project.
+2. Open **More**, then **Settings**.
+3. Choose **Connections**.
+
+The page has two groups:
+
+- **Services** are integrations maintained by Fimo, such as Firecrawl, Fal, and Slack.
+- **MCP servers** are remote servers installed for this project. Choose **Add MCP server** beside this group to add one.
+
+Each row shows whether the connection is enabled, disabled, or needs attention. Open a row to enable or disable it for
+the current project, inspect its endpoint and live tools, or perform the repair appropriate to its authentication.
+
+## Add an MCP server
+
+Choose **Add MCP server** to open one setup flow:
+
+1. Pick a recommended server, choose **Custom MCP server**, or, if you are an organization owner or admin, choose
+   **Use from another project**.
+2. Recommended servers fill their name and endpoint. A custom server asks for a name and Streamable HTTP HTTPS URL.
+3. **Connect with** offers the recommended sign-in path. Fimo checks the endpoint; public servers connect immediately,
+   while OAuth servers open their provider sign-in page and return after approval.
+4. Open **Other ways to connect** when the server instead documents a bearer token, one or more custom headers, or no
+   authentication.
+
+For **Paste an access token**, enter only the token; Fimo adds the `Bearer` scheme. For **Send custom headers**, enter
+each complete value exactly as the server expects, including any prefix (`Authorization` with `Bearer abc123`). Fimo
+encrypts every saved grant and never shows its private value again.
+
+**Use from another project** does not make other projects' servers generally visible. It is an explicit admin-only
+picker that attaches an existing organization Connection to this project without revealing or copying its credential.
+
+Each authentication method has one repair:
+
+- **Reconnect** signs in again for OAuth.
+- **Update credentials** replaces a bearer token or the complete custom-header bundle after it stops working.
+- **Rotate credentials** replaces a healthy token or header bundle proactively.
+- **Retry connection** asks a public server for its tools again without touching any credential.
+
+Only organization owners and admins can replace a shared credential. OAuth and manual secret headers are never sent
+together.
+
+After the server is added, its detail shows the endpoint and the tools Fimo discovered. Only enabled servers become
+available to Studio chat, autonomous agents, and the Fimo CLI for this project. Agents should discover them with
+`fimo integrations list`, inspect them with `fimo integrations info <integration>`, and run an allowed tool with
+`fimo integrations run <integration> <tool>`.

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-08-23T10:32:11.563Z",
+  "bundledAt": "2026-08-23T18:29:50.492Z",
   "cliVersion": "0.20.0",
   "external": [
     "oxc-parser",