fimo 0.21.0-staging.4 → 0.21.0-staging.6

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/assets.md

@@ -35,6 +35,30 @@ Read it as `.data.url` / `.data.id` (e.g. `… | jq -r '.data.url'`). Keep the `
 
 Use `--folder-path` when an agent needs a non-interactive upload target and does not already know folder IDs. Missing folders are created automatically. Dot-prefixed root folders such as `.agents` are reserved for internal/agent media and are hidden from the normal media-library UI.
 
+## Upload a manifest
+
+Use one structured manifest for migration batches. Paths resolve from the
+project directory; `sourceId` must be unique so every result can be reconciled.
+
+```json
+[
+  {
+    "sourceId": "strapi:upload:42",
+    "path": ".fimo/migration/media/Hero image.jpg",
+    "name": "Homepage hero",
+    "folderPath": "Imported"
+  }
+]
+```
+
+```bash
+fimo assets bulk-upload --file .fimo/migration/media.json
+```
+
+The result preserves manifest order and reports each `sourceId` as `uploaded`
+or `failed`, plus final counts. Partial failure exits non-zero. Use
+`--concurrency <1-16>` to change the default concurrency of four.
+
 ## Generate AI media
 
 Moved to **`references/media.md`**. Choose the task that describes the outcome:
@@ -125,6 +149,6 @@ fimo assets delete <asset-id>
 
 ## End-to-end workflow
 
-1. Upload with `fimo assets upload` or generate with a task command such as `fimo image generate`.
+1. Upload with `fimo assets upload`, use `fimo assets bulk-upload` for a batch, or generate with a task command such as `fimo image generate`.
 2. Keep the returned `url` (for direct use) or `id` (to attach to a `media` content-type field).
 3. To use in application code, run `fimo skills get fimo-code --ref ui` and load the detected framework reference: schema media → `<Image>` / `<Video>`, deliberate non-schema URLs → `<StaticImage>`. Never use raw `<img src={asset.url}>` for tracked media.

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

@@ -105,7 +105,10 @@ Use `fimo publish` when `main` is already synced; use `fimo deploy --publish` wh
 ## Anti-patterns
 
 - **Using `git checkout -b` instead of `fimo checkout -b`** — raw git creates the branch but **not** the Branch's DB / sandbox / preview. Always use `fimo` for Branch operations so resources are provisioned atomically. (Running `fimo branch <name>` after the fact provisions them.) The running app itself follows the git branch either way.
-- **Hardcoding the tenant API URL** — the app derives it from the git branch and `.fimo/project.json`. Set `VITE_API_URL` / `NEXT_PUBLIC_FIMO_API_URL` yourself only as a deliberate override (e.g. a local API); it then wins over derivation on every branch.
+- **Hardcoding the tenant API URL** — the framework runtime derives it from the
+  git branch and `.fimo/project.json`. Use an explicit host variable only as a
+  deliberate override, such as a local API; it then wins over derivation on
+  every branch.
 - **Trying to push to or delete `prod` / `release/*`** — these are read-only/protected. Publish to update prod; never push.
 - **`fimo merge` straight onto `main` as a habit** — it's gated for a reason. Merge on a branch, then publish.
 - **Confusing `fimo switch` (Branch) with `fimo orgs switch` (org).**

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

@@ -54,7 +54,7 @@ Use this when the user asks "who filled out the contact form?", "how many signup
 
 ## When to run sync manually
 
-The `fimo/vite` plugin regenerates legacy Vite `src/forms/*.ts` after form JSON changes during development. Framework-aware generation runs during validation. Before a production build, regenerate explicitly with:
+The `fimo-vite` plugin regenerates legacy Vite `src/forms/*.ts` after form JSON changes during development. Framework-aware generation runs during validation. Before a production build, regenerate explicitly with:
 
 ```bash
 fimo validate                  # runs all phases: codegen, lint, route validation, label checks

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

@@ -11,7 +11,7 @@ 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 sets up the named Fimo project: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use React Router by default; `--framework astro`, `--framework nextjs`, and `--framework sveltekit` select minimal framework-native shells. An optional `--starter fimo-site@1` adds a content-led starter only to a newly created project without `--project-id`.
+2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo project: a project with no code yet is scaffolded as a fresh site, while an existing repository is cloned. Without it, `init` creates a NEW project. An interactive TTY shows a "Create new / Link existing" picker; non-interactive shells default to create-new. New projects use React Router by default; `--framework vite`, `--framework astro`, `--framework nextjs`, and `--framework sveltekit` select minimal framework-native shells. An optional `--starter fimo-site@1` adds a content-led starter only to a newly created project without `--project-id`.
 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`.
 
@@ -24,7 +24,7 @@ Generated pnpm projects pin `pnpm@10.26.0` and carry project-owned `pnpm-workspa
 | `--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.             |
 | `--branch <name>`            | no                            | Branch to check out when linking an existing project (defaults to `main`).                                                                                     |
 | `--env <name>`               | no                            | Compatibility alias for `--branch <name>`.                                                                                                                     |
-| `--framework <framework>`    | no                            | New-project scaffold: `react-router` (default), `astro`, `nextjs` (App Router), or `sveltekit`. Existing repositories are preserved.                           |
+| `--framework <framework>`    | no                            | New-project scaffold: `react-router` (default), `vite` (React SPA), `astro`, `nextjs` (App Router), or `sveltekit`. Existing repositories are preserved.       |
 | `--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).                                                                                                                      |
@@ -68,6 +68,7 @@ Omit `--framework` for the existing React Router scaffold, or select a
 minimal framework-native shell explicitly:
 
 ```bash
+fimo init my-vite-site --framework vite --org <organizationId>
 fimo init my-astro-site --framework astro --org <organizationId>
 fimo init my-next-site --framework nextjs --org <organizationId>
 fimo init my-svelte-site --framework sveltekit --org <organizationId>
@@ -96,15 +97,22 @@ For `--agents`, pass the AI tool you're running in: `--agents=claude-code` for C
 
 Pass `--project-id <id>` to set up a known Fimo project. If the project has no code yet — for example, one just created in Fimo Studio — `init` scaffolds a fresh site into it and pushes the initial commit: the same create-new path, linked to the existing ID. If the project already has code, `init` clones it into `[dir]`, like `fimo clone`. Use `--branch <name>` to check out a specific Branch (defaults to `main`); `--env <name>` remains a compatibility alias. Without `--project-id`, `fimo init` creates a new project.
 
+## Linking an existing local application
+
+Use `fimo link <projectId>` to adopt the application in the current folder without replacing its code or comparing its Git history. Running it again with the same project id repairs missing Fimo metadata, dependencies, or the `fimo` remote. If the folder is linked to a different project, the command stops before changing the remote or local files. Pass `--relink` only when the project replacement is intentional:
+
+```bash
+fimo link <projectId> --relink
+```
+
 ## What gets written (create-new path)
 
 `fimo init` (create-new path) scaffolds:
 
-- The selected project shell: React Router by default, Astro with `--framework astro`, Next.js App Router with `--framework nextjs`, or SvelteKit with `--framework sveltekit`
+- The selected project shell: React Router by default, a native React SPA with `--framework vite`, Astro with `--framework astro`, Next.js App Router with `--framework nextjs`, or SvelteKit with `--framework sveltekit`
 - `.fimo/project.json` — links this directory to the remote project (read-only after creation)
 - `.fimo/config.json` — project, optional Studio Pages route metadata, locale, SEO, and agent policy
 - `.fimo/agents/` — versioned agent bundles
-- `.env` — framework-specific tenant content API URLs for local development
 - `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
 
@@ -120,7 +128,11 @@ Nothing is written into per-agent skill dirs: the rich skills are fetched on dem
 
 Codex, OpenCode, Aider, and similar AGENTS.md-native tools work directly off AGENTS.md.
 
-`.env` is only the bootstrap app env so local `pnpm dev` works immediately. Fimo writes the tenant API aliases used by its supported frameworks; users should not discover or set those URLs manually. User-managed public variables are stored with `fimo vars add` and synced into a managed `.env.local` block; hidden values use `fimo secrets add`. See `references/project-vars-and-secrets.md`.
+Supported framework runtimes derive the Fimo connection from
+`.fimo/project.json` and the active git branch, so local development needs no
+Fimo env file. User-managed public variables are stored with `fimo vars add`
+and synced into a managed `.env.local` block; hidden values use
+`fimo secrets add`. See `references/project-vars-and-secrets.md`.
 
 ## Right after scaffolding
 

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-cli/references/project-vars-and-secrets.md

@@ -47,7 +47,9 @@ variables.
 
 ## Local Env Files
 
-`fimo init` and `fimo clone` write `.env` with the framework-specific tenant content API URLs needed for local development. These are Fimo-managed connection values, not project variables; users should not discover or set them manually.
+`fimo init`, `fimo clone`, and `fimo link` do not write the Fimo connection to
+an env file. Supported framework runtimes derive it from `.fimo/project.json`
+and the active git branch; hosted preview and production inject it directly.
 
 `fimo vars add`, `fimo vars update`, and `fimo vars pull` write public project variables to a managed block in `.env.local`.
 

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

@@ -19,7 +19,7 @@ fimo projects rename <name> [projectId] [-C <dir>]   # set seo.siteName in the l
 - **`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 `--branch <name>` to clone a specific Branch. The legacy `--env <name>` spelling remains a compatibility alias. 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).
-- **`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.
+- **`rename`** — edits only the linked local project's `seo.siteName`. It does not commit or deploy. 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). Later remote config commands may require reconciliation while the local config is dirty. Finish your local edits, then explicitly run `fimo deploy --no-wait` when ready for a quick sync.
 
 ## Top-level clone shortcut
 
@@ -39,7 +39,7 @@ fimo unpublish [-C <dir>]        # unpublish the current project
 fimo rename "<Site Name>"        # local edit: set seo.siteName in the project config
 ```
 
-`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`.
+`fimo rename` sets the **site name** (`seo.siteName`) in the local project config. It does not commit or deploy. Later remote config commands may require reconciliation while that local config is dirty. Finish your local edits, then explicitly run `fimo deploy --no-wait` when ready for a quick sync. Deploy reconciles the project's remote `displayName` while pushing the config. See `references/init.md` and `references/deploy.md`.
 
 ## Publish commands
 

package/assets/skills/fimo-code/assets/react-router-locales/navigation.tsx

@@ -1,4 +1,4 @@
-import { FimoLink } from 'fimo/react-router';
+import { FimoLink } from 'fimo-react-router';
 
 export function Navigation() {
   return (

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

@@ -24,7 +24,7 @@ Generated content reads wrap this stored value in `FimoMedia`, which exposes `ur
 
 ## Rendering in application code
 
-Import the primitives from the active framework adapter: `fimo/next` on the Next server, `fimo/next/client` in Next Client Components, `fimo/ui` in React Router/Vite, or `fimo/astro/components` in Astro pages.
+Import the primitives from the active framework adapter: `fimo-next` on the Next server, `fimo-next/client` in Next Client Components, `fimo-react` in React Router/Vite, or `fimo/astro/components` in Astro pages.
 
 | Asset source                                        | Component             | Pass via                  |
 | --------------------------------------------------- | --------------------- | ------------------------- |
@@ -32,7 +32,7 @@ Import the primitives from the active framework adapter: `fimo/next` on the Next
 | Hard-coded URL or generated asset referenced inline | `<StaticImage>`       | `src="https://..."`       |
 
 ```tsx
-import { Image, StaticImage, Video } from 'fimo/next';
+import { Image, StaticImage, Video } from 'fimo-next';
 
 // from a schema entry:
 <Image value={post.coverImage} width={1200} height={630} fit="cover" />

package/assets/skills/fimo-code/references/best-practices/next.md

@@ -13,7 +13,7 @@ Load `references/frameworks/next.md` and the matching router reference first. In
 
 ```ts
 import type { NextConfig } from 'next';
-import { withFimo } from 'fimo/next/config';
+import { withFimo } from 'fimo-next/config';
 
 const nextConfig: NextConfig = {
   cacheComponents: true,

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

@@ -106,7 +106,7 @@ export function ContactForm() {
 
 ## Framework bindings
 
-- **Vite/React:** `submitX(data)` keeps using the existing `fimo/ui` runtime and preserves the current generated API.
+- **Vite/React:** `submitX(data)` keeps using the existing `fimo-react` runtime and preserves the current generated API.
 - **Next.js:** server modules import `@/forms/name`; client components import `@/forms/name.client`. Both expose the same `submitX(data)` shape.
 - **Astro:** import the generated server module and call `submitX(data)` in an Astro action or endpoint. Astro keeps the HTML form and redirect.
 - **SvelteKit:** use `createFimoFormClient({ event })` in a server action and pass it as the second argument: `submitX(data, client)`.

package/assets/skills/fimo-code/references/frameworks/astro.md

@@ -14,17 +14,23 @@ Declare the production framework in `.fimo/config.json`:
 
 Astro owns its static or server output, routes, and 404 behavior. Do not add a catch-all hosting rewrite, a hosting-provider adapter, a preview URL, or a script tag for Fimo.
 
-Add the integration beside the adapters and integrations the project already uses:
+Install `fimo-astro` at the same version as `fimo` and add the integration
+beside the adapters and integrations the project already uses:
 
 ```js
 import { defineConfig } from 'astro/config';
-import { fimo } from 'fimo/astro/config';
+import { fimo } from 'fimo-astro/config';
 
 export default defineConfig({
   integrations: [fimo()],
 });
 ```
 
+`fimo-astro/config` supplies Fimo hosting for `output: 'server'`. A static
+Astro site that hosts elsewhere can import `fimo` from `fimo/astro/config`
+instead for the preview connector and branch env alone; the runtime
+(`fimo/astro`, `fimo/astro/components`) always comes from `fimo`.
+
 Compatibility: the Fimo peer range covers Astro 5–7. Static output is supported
 across that range. Fimo's automatic server adapter path is currently validated
 with the Astro 7-compatible adapter; Astro 5/6 server apps should keep their

package/assets/skills/fimo-code/references/frameworks/compatibility.md

@@ -4,15 +4,15 @@
 peer ranges and the executable acceptance fixtures define compatibility; the
 profile does not promise support for every version of the framework.
 
-| Profile                  | Application dependency specifier                                                                                                             | Fimo surface                                                                                  |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `nextjs`                 | Next 16 is the current acceptance baseline; Fimo's React peer is `^18.2.0 \|\| ^19.0.0` and Next imposes its own React range                 | `fimo/next`, `fimo/next/client`                                                               |
-| `react-router`           | React `^18.2.0 \|\| ^19.0.0`, React Router `^7.0.0 \|\| ^8.0.0`, Vite `^7.0.0 \|\| ^8.0.0`                                                   | `fimo/react-router`, `fimo/ui`                                                                |
-| `vite`                   | React `^18.2.0 \|\| ^19.0.0`, Vite `^7.0.0 \|\| ^8.0.0`                                                                                      | `fimo/ui`, `fimo/vite`                                                                        |
-| `astro`                  | Astro `^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0`                                                                                                       | `fimo/astro`, `fimo/astro/components`                                                         |
-| `sveltekit`              | SvelteKit `^2.0.0`, Svelte `^5.0.0`, Vite `^7.0.0 \|\| ^8.0.0`                                                                               | `fimo/sveltekit`, `fimo/sveltekit/components`, `fimo/sveltekit/config`, `fimo/sveltekit/vite` |
-| `nuxtjs`, `remix`, `vue` | Hosting detection only; no Fimo content/runtime adapter yet                                                                                  | `fimo` hosting profile only                                                                   |
-| _(unset)_                | Anything else: a static generator, plain HTML, a custom build script. Declare `runtime.commands.build` and `runtime.outputDirectory` instead | Static output only; no adapter                                                                |
+| Profile                  | Application dependency specifier                                                                                                             | Fimo surface                                                                                                        |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `nextjs`                 | Next 16 is the current acceptance baseline; Fimo's React peer is `^18.2.0 \|\| ^19.0.0` and Next imposes its own React range                 | `fimo-next`, `fimo-next/client`                                                                                     |
+| `react-router`           | React `^18.2.0 \|\| ^19.0.0`, React Router `^7.0.0 \|\| ^8.0.0`, Vite `^7.0.0 \|\| ^8.0.0`                                                   | `fimo-react-router`, `fimo-react-router/routes`, `fimo-react-router/preset`, `fimo-react-router/vite`, `fimo-react` |
+| `vite`                   | Vite `^7.0.0 \|\| ^8.0.0`; React `^18.2.0 \|\| ^19.0.0` only when the app uses React                                                         | `fimo-react`, `fimo-react-router/vite` (React SPA) or `fimo-vite` (no React)                                        |
+| `astro`                  | Astro `^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0`; Fimo hosting (`fimo-astro`) needs Astro `^7.0.0`                                                     | `fimo/astro`, `fimo/astro/components`, `fimo-astro/config`                                                          |
+| `sveltekit`              | SvelteKit `^2.0.0`, Svelte `^5.0.0`, Vite `^7.0.0 \|\| ^8.0.0`                                                                               | `fimo-sveltekit`, `fimo-sveltekit/components`, `fimo-sveltekit/vite`, `fimo-sveltekit/config`                       |
+| `nuxtjs`, `remix`, `vue` | Hosting detection only; no Fimo content/runtime adapter yet                                                                                  | `fimo` hosting profile only                                                                                         |
+| _(unset)_                | Anything else: a static generator, plain HTML, a custom build script. Declare `runtime.commands.build` and `runtime.outputDirectory` instead | Static output only; no adapter                                                                                      |
 
 `runtime.framework` must match a dependency in `package.json`; a profile the
 code does not use fails the production build. Shape and rules: `hosting.md`

package/assets/skills/fimo-code/references/frameworks/hosting.md

@@ -39,27 +39,31 @@ Hosted preview and production inject the tenant API through these aliases:
 
 | Application             | Server                 | Public/build               |
 | ----------------------- | ---------------------- | -------------------------- |
-| Next.js                 | `FIMO_CONTENT_API_URL` | `NEXT_PUBLIC_FIMO_API_URL` |
+| Next.js                 | `FIMO_CONTENT_API_URL` | Provider-owned             |
 | Nuxt                    | `FIMO_CONTENT_API_URL` | `NUXT_PUBLIC_FIMO_API_URL` |
 | Astro, Remix, SvelteKit | `FIMO_CONTENT_API_URL` | `PUBLIC_FIMO_API_URL`      |
 | React Router, Vite, Vue | `FIMO_CONTENT_API_URL` | `VITE_API_URL`             |
 
-Locally, the app derives its env from the **git branch**: `fimo/vite`,
-`withFimo`, the Astro integration and the SvelteKit plugin compute the tenant
-API URL from `.fimo/project.json`
+Locally, the app derives its env from the **git branch**: `fimo-vite` (or
+`fimo-react-router/vite` for React Router projects), the Astro integration and
+the SvelteKit plugin compute the tenant API URL from `.fimo/project.json`
 (`projectId` + `tenantApiBaseUrl`, recorded once at `init`/`clone`/`link`) and
-expose the Vite, Next and public (`PUBLIC_*`) aliases plus `FIMO_ENV` /
-`NEXT_PUBLIC_FIMO_ENV` at startup. The Vite connectors derive them during both
-dev and production builds, and `withFimo` derives them in `next dev`, `next
-build`, and `next start`, so a linked project builds and serves locally without
-exporting them by hand. No env file is written on a switch, so a plain `git checkout` is a
-complete env switch. Never hardcode a tenant URL in application source. One
-rule, per variable: a non-empty value the user set explicitly (`.env`, shell, their own
-`define`) is left alone, and Fimo fills the variables they did not set.
+expose the Vite and public (`PUBLIC_*`) aliases plus `FIMO_ENV` at startup,
+during both dev and production builds. Next.js needs no browser alias: the root
+`FimoProvider` and the `fimo-next` server runtime resolve the same connection
+at render time and pass only the public part to the browser. No env file is
+written on a switch, so a plain `git checkout` is a complete env switch. Never
+hardcode a tenant URL in application source. One rule, per variable: a
+non-empty value the user set explicitly (`.env`, shell, their own `define`) is
+left alone, and Fimo fills the variables they did not set.
 
 For a framework whose alias is not in that list yet, preserve or add its normal
 local environment alias by hand.
 
+`NEXT_PUBLIC_FIMO_*` remains a compatibility override for existing Next.js
+projects. Do not add it to new code, env files, setup instructions, or migration
+plans.
+
 ## React Router framework mode
 
 For the supported client-rendered setup, keep `ssr: false` and add Fimo's
@@ -67,7 +71,7 @@ hosting preset. It hides the active hosting provider from application code:
 
 ```ts
 import type { Config } from '@react-router/dev/config';
-import { fimoPreset } from 'fimo/react-router/preset';
+import { fimoPreset } from 'fimo-react-router/preset';
 
 export default {
   ssr: false,