npm - fimo - Versions diffs - 2.9.0 → 2.10.0-staging.10 - Mend

fimo 2.9.0 → 2.10.0-staging.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (40) hide show

package/README.md CHANGED Viewed

@@ -37,6 +37,15 @@ cd my-site
 Every command runs the same way: **`npx fimo@latest <command>`**. `fimo init` sets up the site, pushes the first commit, and wires it to your Fimo account. Open it in your coding agent and start building.
+## No account yet?
+`fimo new` creates a site without signing in; a person claims it within 72 hours through the printed claim link. It is the path for sandboxes, CI, and headless coding agents, where `fimo login` cannot open a browser:
+```bash
+npx fimo@latest new my-site          # creates the site and prints the claim link
+npx fimo@latest new --instructions   # the setup guide for coding agents (the text of https://fimo.new)
+```
 ## AI coding tools
 Fimo ships skills and rules for your AI coding tools (Claude Code, Cursor, Codex, Gemini, and more) so the agent knows how to work in a Fimo site. `fimo init` installs them for you — add or refresh them any time (`--mode=copy` is required under npx):

package/assets/skills/fimo/SKILL.md CHANGED Viewed

@@ -39,9 +39,9 @@ Pick by task:
 - Writing code — schemas/forms, generated clients, labels, framework adapters, rendering primitives → `fimo-code`
 - Site creation, local setup, cloning, and CLI workflows — init, push, deploy, sync, labels, domains, analytics → `fimo-cli`
 - AI agent setup — connect Claude Code, Codex, Cursor, or another agent → `fimo-cli` (`references/agent-setup.md`)
-- Remote MCP integrations — add, inspect, search, or run an MCP server → `fimo-cli` (`references/mcp.md`)
+- Integrations — Search Console, Slack, or an MCP server: add, inspect, search, or run its tools → `fimo-cli` (`references/integrations.md`)
 - The Fimo Studio dashboard / web app UI → `fimo-studio`
-- Migrating an existing site into Fimo → `fimo-migration`
+- Migrating an existing site into Fimo, or putting an existing app on Fimo (`fimo link`) → `fimo-migration`
 For project setup, load `fimo-cli` first. Its `references/init.md` decision tree distinguishes a new or empty
 project, an existing Fimo site, and an external migration; load `fimo-migration` for the last path.

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

@@ -100,24 +100,24 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "Deploy / publish / go live / push my changes" → `references/deploy.md`
 - "Add a redirect / security headers / CSP / HSTS / clean URLs / trailing slash" → `references/hosting.md`
 - "Get the preview URL / open the preview / what's the URL for this Branch / refresh the preview link / I just want to see the site / the preview URL stopped working" → `references/preview.md`
-- "Check the site in a browser / is my site accessible / a11y or WCAG check / measure LCP or Web Vitals / why is the page slow / inspect network requests or console errors / Lighthouse score" → `references/site-checks.md`
+- "Check the site in a browser / SEO check / broken links / missing titles, descriptions or alt text / `fimo site check` / is my site accessible / a11y or WCAG check / measure LCP or Web Vitals / why is the page slow / inspect network requests or console errors / Lighthouse score" → `references/site-checks.md`
 - "Schedule a command / cron / nightly publish / recurring checks / `fimo schedules`" → `references/schedules.md`
 - "Set env vars / configure API keys / add project secrets / local `.env.local` / `fimo vars` / `fimo secrets`" → `references/project-vars-and-secrets.md`
 - "React to form submissions / publish changes / analytics reports / media activity / send events to Resend, Slack, GitHub, Zapier, or an HTTP endpoint / configure or debug outbound webhooks" → `references/webhooks.md`
-- "Enable provider tools / integrations / API key connection for a provider / agent integration access" → `references/integrations.md`
+- "Use a connected app / Google Search Console / clicks, impressions, rankings, keywords from Google / Google Analytics / GA4 users, sessions, traffic sources, key events / enable provider tools / integrations / add, inspect, search, or run an MCP server / `fimo integrations` or `fimo mcp`" → `references/integrations.md`
 - "Firecrawl / scrape a public website / competitor research / agent web research" → `references/integrations.md` **+ load `references/integrations/firecrawl.md`**
 - "Check credits / credit balance / can I keep using AI / billing credits / running low / how many credits are left" → `references/credits.md`
 - "List history / create a restore point / recover content and code / restore a previous version / snapshot usage or retention" → `references/history.md`
 - "Create a Branch / feature Branch / switch Branches / merge Branches / diff two Branches / Branch status / what changed on this Branch / sync from parent / cut a release / tag a version / go to prod" → `references/branches.md`
 - "List my projects / clone an existing project locally / check out a project / delete this project / unpublish / rename the project / manage projects across the org" → `references/projects.md`
 - "Migrate an existing Webflow / Framer / Squarespace / Wix / Carrd site from only a published URL" → load the `fimo-migration` skill, set the target up with `fimo migrate init <dir>`, and read the published site yourself with a browser — the CLI does not crawl it
+- "Put my existing site or app on Fimo / link or deploy the app in this folder / host the site I built" → load the `fimo-migration` skill and follow its source-backed, same-framework path: `fimo link` keeps every word typed in the code, which Studio cannot edit, until the migration's content pass moves it to labels and the CMS
 - "Migrate from an exported project, source repository, Webflow code export plus CMS CSVs, Framer CMS CSVs, Squarespace XML/CSV, Wix CSVs, Carrd/static export, or downloaded site files" → load the `fimo-migration` skill and use the source repo/export as the migration source of truth
 - "How do AI agents read my site / markdown for agents" → `references/deploy.md`
 - "Modify the URL of the website / change my project's address / connect a custom domain (e.g. blog.example.com) / rename the Fimo-provided `*.fimo.site` subdomain / buy a new domain through Fimo / set up a domain" → `references/domains.md`
 - "Invite a collaborator / add Marc / share with client" → `references/invite.md`
 - "Login / log out / who am I / switch organization" → `references/account.md` — note: switching **org** is `fimo orgs switch`; bare `fimo switch` changes the active **Fimo Branch** (see `references/branches.md`)
 - "Install Fimo for my agent / fimo skills install / set up Claude Code, Codex, or Cursor for Fimo" → `references/agent-setup.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`
 - "Update / upgrade the project's fimo packages / move to a new Fimo release / `fimo update`" → `references/update.md`. Never edit `fimo` or `fimo-*` versions directly in `package.json`; `fimo update` keeps package pins and codemods aligned.
 - "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`
@@ -135,7 +135,6 @@ These fire at specific moments in the project lifecycle. **Surface them proactiv
 - **Right after `fimo init`** → start the app locally with the project's package-manager `dev` script (`pnpm dev` / `npm run dev` / `yarn dev` / `bun dev`) in the background. This localhost server with live reload is your iteration loop — edit, show, repeat. No deploy is needed to see local changes. If the initiating request did not say what to build, ask the developer — after the first preview on the create-new path, never as a blocker before initializing.
 - **When a user-visible unit of work looks done outside first-time onboarding** → **offer** to deploy (`fimo deploy` for a hosted project preview, `fimo deploy --publish` to go live) and run it only after the developer confirms — or immediately if they ask. Never deploy ordinary edits on your own. See `references/deploy.md`.
 - **Optional, outside new-project onboarding (its first preview already warms the sandbox), if you already know a deploy is coming** → warm the sandbox early with `fimo deploy -m "chore: init" &` in the background so the one-time ~15-30s provision + dep install happens while you work and the real deploy lands warm (~4-10s). This is a perf optimization, not a requirement. See `references/deploy.md` § Warm the sandbox early in a session.
-- **Iterative code-only deploys** → once you are deploying, `fimo deploy --no-restart` skips the sandbox dev-server restart on HMR-safe edits. See `references/deploy.md` § Skipping the dev-server restart for when it's safe.
 - **You need the current preview URL but haven't changed code** (opening it, screenshotting it, handing it to another tool, the previous URL expired) → `fimo preview url`, never a no-op `fimo deploy`. See `references/preview.md`.
 - **When the user wants to try something risky / explore a redesign without touching the live site** → suggest a feature Branch: `fimo checkout -b <name>` gives an isolated Branch + DB + preview. Deploy previews there, then `fimo merge` it back and `fimo publish`. See `references/branches.md`.
 - **After completing or safely preserving the user's main work, when a confirmed Fimo platform failure still materially blocks the task after one safe recovery attempt, or a confirmed missing capability blocks completion or forces a fragile or heavily manual workaround** → use the built-in `supportReport` tool. Do not wait for the user to ask and do not stop after only describing the gap. See `references/support.md`.

package/assets/skills/fimo-cli/references/account.md CHANGED Viewed

@@ -10,6 +10,8 @@ fimo login        # opens your browser; the CLI captures the token automatically
 `fimo login` starts a local loopback server, opens your browser to authorize, and the browser redirects the token back to the CLI — **there's nothing to copy or paste**. After login, the CLI saves the session token and auto-selects an active organization (your session's current org, otherwise the first one) — it never prompts. If you belong to more than one org, change the active one later with `fimo orgs switch` (see below).
+`fimo login` needs a browser on this machine, not a terminal: a coding agent can run it and the user finishes sign-in in the browser that opens. Where no browser can open (a sandbox, CI), it stops at once with `LOGIN_REQUIRES_BROWSER`; create the site without an account instead with `fimo new <dir> --yes --json` (`fimo new --instructions` prints the guide).
 ```bash
 fimo whoami       # show the currently signed-in user + active organization
 fimo logout       # revoke the current session and clear local credentials

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

@@ -84,7 +84,7 @@ Every command that takes agents accepts the same selection inputs:
   - **Additional** — agents that get the global bootstrap skill installed. The popular ones (`claude-code`, `cursor`, `codex`, `opencode`, `windsurf`, `gemini-cli`, `hermes`) appear at the top of the picker; the full list of supported agents remains available below them. Agents already set up on the machine are pre-checked.
 - `--agents=none` (only `fimo init`) — skip the global skill entirely.
-In headless contexts (CI, agent-spawned commands), pass the flag explicitly. Env-var detection (only Claude Code's `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT`) silently targets `claude-code` if the flag is omitted; every other agent must be named explicitly with `--agents` in a headless shell, or the command exits with "No agents detected and no --agents flag passed."
+In headless contexts (CI, agent-spawned commands), pass the flag explicitly. Env-var detection (only Claude Code's `CLAUDECODE` / `CLAUDE_CODE_ENTRYPOINT`) silently targets `claude-code` if the flag is omitted; every other agent must be named explicitly with `--agents` in a headless shell, or the command exits with "No agents detected and no --agents flag passed." `fimo new` takes no agent flags and installs no skill. A non-interactive `fimo init` without `--skills` installs no skill and needs no agent; with `--skills` and no agent found, it still sets up the site and skips the skill install with a warning.
 ## Always current, never stale

package/assets/skills/fimo-cli/references/assets.md CHANGED Viewed

@@ -15,6 +15,8 @@ fimo assets upload ./hero.jpg --name "Hero Image" --parent-id "<folder-uuid>"
 fimo assets upload ./screenshot.png --folder-path ".agents/<session-id>/screenshots"
 ```
+Upload options are `--name`, `--parent-id`, and `--folder-path`. Set alt text in the content media field's `alt` value or the rendering component; upload does not accept `--alt`.
 Response (JSON) — the full asset object, wrapped in a `data` envelope:
 ```json

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

@@ -32,7 +32,7 @@ fimo --branch <name> <command>  # peek at another Branch for one command (does n
 | `fimo branch -d <name>` | `git branch -d`     | Delete a Branch — tears down its sandbox, Neon branch, and R2 prefix. Refuses `main` and `prod`.                                                                             |
 | `fimo checkout <name>`  | `git checkout`      | Switch to a Branch (checks out the matching git branch; the app derives its Branch from that branch at startup). `-b` creates + switches; `--from <branch>` sets the parent. |
 | `fimo switch <name>`    | `git switch`        | Switch to an existing Branch. Takes only `<name>` (no `-b`/`--from`) — use `fimo checkout -b` to create + switch.                                                            |
-| `fimo pull`             | `git pull`          | Sync the current Branch's data plane (DB/assets) down from its parent. `--from <branch>` syncs from an explicit ancestor.                                                    |
+| `fimo pull`             | `git pull`          | Fast-forward the local checkout to the Branch's latest code on Fimo. Never changes the Branch on the server.                                                                 |
 | `fimo diff [from] [to]` | `git diff`          | Two-Branch diff across all surfaces. Defaults `from` = current Branch, `to` = `main`. `--surface <name>` limits to one; `--json`; `--no-color`.                              |
 | `fimo status`           | `git status`        | Multi-surface status for the current Branch vs its parent. See below.                                                                                                        |
 | `fimo merge <from>`     | `git merge`         | Merge another Branch into the current one (multi-surface, atomic, interactive conflict resolver). See below.                                                                 |
@@ -95,7 +95,15 @@ fimo merge feat/seo --allow-direct-merge   # override the "don't merge straight
 ## `fimo pull`
-Syncs the current Branch's data plane from its parent (or `--from <ancestor>`). Conflicts currently resolve **parent-wins** automatically (a future release adds per-row picks). Use it to refresh a stale feature Branch with the latest `main` content/schema state.
+Brings the current Branch's latest code from Fimo into the local checkout, like `git pull --ff-only fimo <branch>`. Run it before editing locally when the Branch may have changed elsewhere (Studio, an agent, a teammate's deploy). It only reads from Fimo: it never changes the Branch on the server. To bring `main` into a feature Branch, use `fimo merge main`.
+It never rebases, merges, or stashes local work. It stops instead:
+- `ENV_BRANCH_BEHIND_DIRTY` — the checkout is behind and has uncommitted changes. Commit or stash them, then run `fimo pull` again.
+- `ENV_BRANCH_DIVERGED` — local commits and remote commits both exist. Run `git pull --rebase fimo <branch>`, fix any conflicts, then `fimo deploy`.
+- `ENV_BRANCH_MISMATCH` — the git checkout is on another branch, or a detached HEAD. Run `fimo checkout <branch>`.
+`--json` returns `details.commits_pulled` and `details.head` (the checkout's commit afterwards).
 ## Publishing — `fimo publish` vs `fimo deploy --publish`

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

@@ -81,7 +81,17 @@ fimo entries bulk-update <TypeName> (--file <path> | --stdin)
 fimo entries bulk-delete <TypeName> (--ids <id1>,<id2> | --where '<json>') [--locale es]
 ```
-`--body` is a **required** option on `create` and `update`. Run `fimo skills get fimo-code --ref content/richtext` before constructing an entry payload: slug belongs inside `data`, media has a specific shape, and richtext must be Tiptap JSONContent.
+`create` and `update` require `--body` with a `data` envelope. The content type is positional. For JSON files, use `bulk-create` or `bulk-update` with their documented array formats.
+```bash
+fimo entries create BlogPost --body '{"data":{"slug":"hello","title":"Hello"}}'
+fimo entries update BlogPost <id> --body '{"data":{"title":"Updated"}}'
+fimo entries list BlogPost --where '{"slug":"hello"}'
+```
+For `get`, `update`, and `delete`, use the UUID returned as `id` by create/list. To find an entry by slug, filter with `list --where` as above, then use its `id`.
+Run `fimo skills get fimo-code --ref content/richtext` before constructing an entry payload: slug belongs inside `data`, media has a specific shape, and richtext must be Tiptap JSONContent.
 `entries list` accepts the same read query surface as generated hooks:

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

@@ -15,7 +15,6 @@ Before deploying, Fimo fast-forwards a clean checkout that is behind and stops o
 ```bash
 fimo deploy                                  # preview only (default; reversible)
 fimo deploy -m "<commit message>"            # commit pending + push + sandbox sync
-fimo deploy --no-restart                     # skip dev-server restart (HMR-safe changes only)
 fimo deploy -m "<commit message>" --publish  # also publish a new live version
 ```
@@ -23,7 +22,6 @@ fimo deploy -m "<commit message>" --publish  # also publish a new live version
 - **`fimo deploy --publish`** — same as above, then triggers a live publish and prints the live URL. Runs from the configured Production source Branch only. **Only use `--publish` when the user signals "ship it"** — first-time site completion, or an explicit "publish" / "go live" request. Otherwise stick to plain `fimo deploy`. (For a _versioned_ prod release, use `fimo publish` instead — see below.)
 - **`-m`** is the commit message used when there are uncommitted local changes; required in non-interactive shells. Omit if the working tree is already clean.
 - **`--description "<why>"`** — the commit body for those changes: why they were made. Teammates and agents that later edit the same files read it, for example when a merge conflicts. Pass it with `-m` when the reason is not obvious from the diff.
-- **`--no-restart`** — tells the sandbox to skip the dev-server restart and let Vite HMR pick up the change. Shaves ~3s per deploy. A deploy that carries changed variables restarts anyway. See "Skipping the dev-server restart" below for when it's safe.
 ## Reading deploy destinations
@@ -89,7 +87,7 @@ Redirects, response headers, and URL shape belong in
 This is a **performance optimization, only worth doing when you already know a deploy is coming** (the developer asked to publish, or you're confident they'll want a hosted preview soon). If you're just iterating locally, skip it — don't deploy pre-emptively. New-project onboarding never needs it: its automatic first preview deploy is the warm-up.
-The first deploy of a project's life pays a one-time cost: the sandbox has to provision (create the VM, install the user's deps if they differ from the template's baked ones, start the dev server) — about 15-30s. Every deploy after that lands on a warm sandbox (~10s, or ~4s when you also use `--no-restart` and the lockfile hasn't changed).
+The first deploy of a project's life pays a one-time cost: the sandbox has to provision (create the VM, install the user's deps if they differ from the template's baked ones, start the dev server) — about 15-30s. Every deploy after that lands on a warm sandbox (~4-10s).
 **To hide that one-time cost, kick off an early deploy in the background while you keep working.** The provisioning happens during your generation work, so by the time the developer wants a hosted preview, the sandbox is already warm and the deploy is fast.
@@ -99,29 +97,6 @@ fimo deploy -m "chore: init" &        # background; keep generating code while i
 There's nothing special about this — it's the same `fimo deploy` you'd run later. The `-m` is the commit message for any files `validate` writes via codegen; pick a sensible conventional-commit string (e.g. `chore: init`, `chore: scaffold`). The point is purely the timing: pay the provisioning tax up front instead of when the user is waiting on a result. **This is also the only path that installs your project's deps on the sandbox** — if you skip it, the first interactive deploy will pay both costs.
-## Skipping the dev-server restart
-`fimo deploy --no-restart` tells the API not to restart the sandbox's dev server after pulling new code. Vite's HMR picks up the change instead, which is what it's designed for — 3+ seconds saved per deploy.
-**Use `--no-restart` when you only touched HMR-safe files:**
-- Anything under `src/**` (components, pages, hooks, styles)
-- Fixed-path static files under `public/`, such as favicons or `robots.txt` (images and videos belong in the media library, not the repository; see the `fimo-code` skill's non-negotiable boundaries)
-- Content / entries / translations / form definitions (JSON the Fimo runtime hot-loads)
-**Do NOT use `--no-restart` when you touched any of these — they require a fresh dev server:**
-- `vite.config.*` (Vite plugin or config changes)
-- `react-router.config.*` (router config)
-- `tsconfig.json` (TypeScript compiler)
-- `.env` (env vars are read at process start)
-- `package.json` or any lockfile (dep changes)
-- Anything under `.fimo/` (Fimo's own pre-build / runtime config)
-**When in doubt, omit the flag.** The default (restart) is the safe choice — a wasted restart costs 3 seconds; a missing one costs the user serving stale code until they notice and re-deploy.
-**One case is handled for you:** if the deploy changes the project's route set (a page added, removed, or moved), the API tells the preview to reload regardless of this flag. A router builds its route table once per document, so the new page would otherwise exist but be unreachable — missing from the Studio route selector and 404-ing from the site's own links. This costs a page load, not a restart.
 ## Publishing: `fimo deploy --publish` vs `fimo publish`
 Use `fimo deploy --publish` to push and publish local changes. Use `fimo publish` to publish the revision already on the Fimo remote without pushing. Both target the configured Production source Branch.

package/assets/skills/fimo-cli/references/domains.md CHANGED Viewed

@@ -51,7 +51,7 @@ Global flags: `--project <id>` / `-C, --cwd <dir>` for project resolution, `--or
 When a user says "I want to change my website's URL," ask which case fits:
 - **"It's fine as-is, just nicer"** → `rename-default` or `suggest-default`. Free, instant, no DNS.
-- **"I own example.com already"** → `add example.com`. Pay as you go or higher. They configure CNAME at their registrar.
+- **"I own example.com already"** → `add example.com`. Starter or higher. They configure CNAME at their registrar.
 - **"I want to buy a domain"** → `search` → `pricing` → `buy`. The registered-domains feature flag and an eligible plan must be on (the flag is not enabled in every environment).
 If they aren't sure, run `fimo domains suggest-default` first — it's free, takes one step, and a good fallback if they don't want to commit to a domain purchase.
@@ -60,7 +60,7 @@ If they aren't sure, run `fimo domains suggest-default` first — it's free, tak
 After the automatic first-preview deploy on a newly created project, offer a cleaner free `*.fimo.site` URL before the first public publish when there is no custom domain and the current default slug still looks generated or was never explicitly chosen. Choosing it now lets the first public launch use the clean URL. Skip the offer if the user already chose the default slug, attached a custom domain, or declined.
-The default URL is free and needs no DNS. A custom domain uses the Pay as you go (or higher) workflow above. A default slug can be reserved before publication, but it returns "Project Not Found" until the site is published. Renaming changes the address that will become public, so never silently claim a suggestion:
+The default URL is free and needs no DNS. A custom domain needs Starter or higher, as above. A default slug can be reserved before publication, but it returns "Project Not Found" until the site is published. Renaming changes the address that will become public, so never silently claim a suggestion:
 1. Run `fimo domains suggest-default --base "<brand>" --json` to get candidates.
 2. Show the candidates and ask the user to choose one explicitly.
@@ -72,7 +72,7 @@ Choosing the slug does not publish the site. The first successful `fimo deploy -
 The CLI never charges directly. Two distinct money paths:
-1. **Pay as you go or higher** — gates custom-domain operations. A valid card activates Pay as you go through the Fimo web app (Hyperline-hosted checkout). When a Free user runs a gated command they get a 403 with the billing URL; surface it as-is to the user.
+1. **Starter or higher** — gates custom-domain operations. Starter or Pro is chosen in the Fimo web app (Hyperline-hosted checkout). When a Free user runs a gated command they get a 403 with the billing URL; surface it as-is to the user.
 2. **Domain registration** — `fimo domains buy` creates a Hyperline invoice with `payment_method_strategy: 'external'` and returns a `checkoutUrl`. The user opens that URL in a browser to pay. **No money moves until they pay the invoice.** That's why `--yes` on `buy` is safe: it queues an invoice; the human still has to consent at checkout.
 Domain prices come from name.com via the registrar reseller. They vary by TLD and can change. Pricing is in USD (cents in the API, formatted as dollars in CLI output).
@@ -121,7 +121,7 @@ Propagation: typically 15–30 minutes, up to 48 hours rarely.
 ## Common errors
 - **"Project Not Found" on a new URL or custom domain.** The route exists but the site was never published — run `fimo deploy --publish`.
-- **"Custom domains require Pay as you go or higher."** — add a card at `/app/billing`, then retry. Free users can still run `list`, `rename-default`, `suggest-default`, `search`, and `pricing`.
+- **"Custom domains require Starter or higher."** — choose a plan at `/app/billing`, then retry. Free users can still run `list`, `rename-default`, `suggest-default`, `search`, and `pricing`.
 - **"Domain purchase is not enabled on this account."** — the registered-domains feature flag is off on this API instance. Contact support.
 - **"This URL is not available."** — slug or hostname collides with another project or is reserved.
 - **"That's a Fimo-owned domain."** — user tried `add <something>.fimo.site`. Use `rename-default` instead.

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

@@ -32,7 +32,7 @@ fimo history list --all-pages
 ```
 The list also reports compressed snapshot usage and the current retention period. Restore points expire after 1 day on
-Free, 30 days on Pay as you go, or 90 days on Premium and Pro. The expiry is fixed when each point is created.
+Free, 30 days on Starter, or 90 days on Premium and Pro. The expiry is fixed when each point is created.
 ## Restore safety

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

@@ -10,30 +10,30 @@ 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).
+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` in a terminal first, or create the site without an account with `fimo new <dir>` (see `account.md`).
 2. **Resolves the project** — with `--project-id <id>` it sets up the named Fimo site: 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 sites use the Next.js App Router by default; `--framework react-router`, `--framework vite`, `--framework astro`, and `--framework sveltekit` select the other minimal framework-native shells.
 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`.
 Generated pnpm projects pin `pnpm@10.26.0` and carry project-owned `pnpm-workspace.yaml#strictDepBuilds: true` and `#allowBuilds` settings. Generated Bun projects trust the same required packages through `package.json#trustedDependencies`. Keep the selected package manager's policy committed. When adding a dependency with an install script, review it before extending that policy; never replace it with a blanket allow-all install.
-| Flag                         | Required                      | Purpose                                                                                                                                                 |
-| ---------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                       |
-| `--project-id <id>`          | no                            | Set up the named Fimo site: scaffold and push a fresh site when it has no code yet, otherwise clone it.                                                 |
-| `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.      |
-| `--branch <name>`            | no                            | Branch to check out when linking an existing project (defaults to `main`).                                                                              |
-| `--env <name>`               | no                            | Rejected as a Branch selector; use `--branch <name>`.                                                                                                   |
-| `--framework <framework>`    | no                            | New-project scaffold: `nextjs` (App Router, default), `react-router`, `vite` (React SPA), `astro`, or `sveltekit`. Existing repositories are preserved. |
-| `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                     |
-| `--install` / `--no-install` | yes in non-TTY                | Install deps after checkout (or skip it).                                                                                                               |
-| `--skills` / `--no-skills`   | yes in non-TTY                | Install the global Fimo skill (or skip it).                                                                                                             |
-| `--agents <list>`            | no                            | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to skip installing the global skill.                                                 |
-| `-a, --agent <id>`           | alternative                   | Repeatable form: `-a claude-code -a cursor`.                                                                                                            |
-| `--template-root <path>`     | no                            | Override the bundled template (development only).                                                                                                       |
-| `-y, --yes`                  | no                            | Run non-interactively using defaults (no prompts).                                                                                                      |
-In a non-TTY shell the create-new path requires `[dir]`, `--install` / `--no-install`, and `--skills` / `--no-skills` (and `--org` if you have no active org and belong to multiple orgs). Without them the command exits with `Cannot prompt in a non-interactive shell.`
+| Flag                         | Required                      | Purpose                                                                                                                                                                          |
+| ---------------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[dir]` positional           | yes in non-TTY for create-new | Target directory (e.g. `my-site`)                                                                                                                                                |
+| `--project-id <id>`          | no                            | Set up the named Fimo site: scaffold and push a fresh site when it has no code yet, otherwise clone it.                                                                          |
+| `--org <id>`                 | no                            | Target organization **id** when creating (use the `ID` column from `fimo orgs list`, NOT the slug). Picker shown interactively if omitted and TTY.                               |
+| `--branch <name>`            | no                            | Branch to check out when linking an existing project (defaults to `main`).                                                                                                       |
+| `--env <name>`               | no                            | Rejected as a Branch selector; use `--branch <name>`.                                                                                                                            |
+| `--framework <framework>`    | no                            | New-project scaffold: `nextjs` (App Router, default), `react-router`, `vite` (React SPA), `astro`, or `sveltekit`. Existing repositories are preserved.                          |
+| `--package-manager <pm>`     | no                            | `npm` \| `pnpm` \| `yarn` \| `bun`.                                                                                                                                              |
+| `--install` / `--no-install` | no                            | Install deps after checkout (or skip it).                                                                                                                                        |
+| `--skills` / `--no-skills`   | no                            | Install the global Fimo skill (or skip it).                                                                                                                                      |
+| `--agents <list>`            | no                            | Comma-separated agent IDs (e.g. `claude-code,cursor`). Pass `none` to skip installing the global skill. Non-interactive runs without it use `none`, unless `--skills` is passed. |
+| `-a, --agent <id>`           | alternative                   | Repeatable form: `-a claude-code -a cursor`.                                                                                                                                     |
+| `--template-root <path>`     | no                            | Override the bundled template (development only).                                                                                                                                |
+| `-y, --yes`                  | no                            | Run non-interactively using defaults (no prompts).                                                                                                                               |
+In a non-TTY shell (or with `-y` / `--json`) the create-new path requires `[dir]`, and `--org` if you have no active org and belong to multiple orgs. Everything else takes a default: dependencies install with the detected package manager unless you pass `--no-install`, and no skill is installed unless you pass `--skills`.
 ### Non-interactive setup
@@ -105,6 +105,10 @@ Use `fimo link <projectId>` to adopt the application in the current folder witho
 fimo link <projectId> --relink
 ```
+Linking keeps every word typed in the code, where Fimo Studio shows "Nothing to edit". When people will edit the site,
+load `fimo-migration` and follow its source-backed, same-framework path: its content pass moves that
+text to labels and the CMS, and its `editable-text` guardrail proves it.
 ## What gets written (create-new path)
 `fimo init` (create-new path) scaffolds:

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

@@ -1,94 +1,73 @@
 # Integrations
-Use integrations to enable external services for a Fimo site. Firecrawl and Fal are built into Fimo: Fimo owns the provider account and bills the project in Fimo credits, so they take no API key at all. Every other credential (MCP servers, OAuth workspaces) is stored encrypted by Fimo and never printed back to the CLI. Teammates and agents receive access to the integration, not the underlying token.
+Integrations are the outside services a site can use. There are three kinds, all used the same way:
-Start with `fimo integrations list` whenever the task could benefit from an external service. It is the site-scoped,
-runtime-truthful inventory; use `info` only for the relevant integration instead of loading every provider's tools into
-context.
+- **Integrations an organization connects**, such as Google Search Console, Google Analytics, and the MCP integrations Semrush, Ahrefs and DataForSEO (SEO data). An organization admin connects one from **Integrations** in Fimo Studio; a site manager turns it on for a site and fills its settings. An MCP integration's tools come live from the provider's server.
+- **MCP integrations from the catalog**, such as PostHog and Resend. An organization admin signs in from Studio, or adds the integration's API key once with `fimo integrations connect <integration> --token-stdin`. Then turn it on per site with `fimo integrations enable <integration>`.
+- **MCP servers your organization adds** with `fimo integrations add`. Their tools come live from the server.
-## Inspect
+`fimo integrations` uses the integrations turned on for the current site. Slack is an integration too, managed from Studio's Slack settings. Every credential is stored encrypted by Fimo and never printed back to the CLI.
-```bash
-fimo integrations list
-fimo integrations info firecrawl
-fimo integrations status firecrawl
-```
+Firecrawl and Fal are Fimo's built-in services, on Fimo's key and Fimo credits. They are no longer available to new sites: a site that already uses one keeps it, sees it in `fimo integrations list`, and runs it as before (`references/integrations/firecrawl.md`). Never offer them to a site that does not have them.
-`info` shows supported auth choices, required credentials, tools, and recipes. For a built-in service the only auth choice is `fimo`. `status` shows the project-specific setup state.
+## Commands
-When running inside an agent session, `fimo integrations list` shows only the integrations the project has enabled for that session.
+| Command                                                                   | Does                                                                                                                                                                                    |
+| ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fimo integrations list`                                                  | Every integration the site could use, with its state: `on`, `needs <setting>`, `off for this site`, or `not installed`. Inside an agent session, the integrations that session may use. |
+| `fimo integrations info <integration>`                                    | The integration's guide: when it helps, how to read its numbers, its rules. Read it before an integration's first run.                                                                  |
+| `fimo integrations tools [integration] [--search <words>] [--tool <key>]` | Tools of the integrations that are on. `--search` keeps the best few matches with the start of what each does; `--tool` shows one tool with its input schema, before you run it.        |
+| `fimo integrations run <integration> <tool> --input '<json>'`             | Run one tool. `--input` also takes `@file.json` or `-` for stdin. `--approval <code>` runs a change a person allowed.                                                                   |
+| `fimo integrations settings <integration> [--set key=value]`              | Show the site's settings for an integration, or change one. A choice must be one the connected account offers.                                                                          |
+| `fimo integrations enable <integration>` / `disable <integration>`        | Turn an integration on or off for this site.                                                                                                                                            |
+| `fimo integrations status <integration>`                                  | The site's setup state for an integration.                                                                                                                                              |
+| `fimo integrations connect <integration> --token-stdin`                   | Add the organization's API key for an integration such as PostHog or Resend (organization admins) and turn it on for this site. Running it again replaces the key.                      |
+| `fimo integrations add <name> --url <mcp-url>`                            | Add an MCP server for the organization and turn it on here. Options: `--auth`, `--header`, `--token-stdin`, `--headers-stdin`.                                                          |
+| `fimo integrations reconnect <integration>`                               | Sign in to an OAuth MCP integration again.                                                                                                                                              |
+| `fimo integrations rotate <integration>`                                  | Replace an MCP integration's credentials from stdin.                                                                                                                                    |
+| `fimo integrations remove <integration> --yes`                            | Remove an MCP server and its connection from every site (organization admins).                                                                                                          |
-## Add a remote MCP server
+`fimo mcp` still works but is deprecated: `mcp run` becomes `integrations run`, `mcp search` becomes `integrations tools --search`, `mcp add` becomes `integrations add`.
-Remote MCP servers have a focused command group while remaining integrations underneath:
+## Find the right tool
+Search by what you need, not by integration name:
 ```bash
-fimo mcp add sentry --url https://mcp.sentry.dev/mcp
+fimo integrations tools --search "search clicks impressions rankings"
+fimo integrations info search-console
+fimo integrations tools search-console --tool query_search_analytics
+fimo integrations run search-console query_search_analytics --input '{"dimensions":["page"],"days":28}'
+fimo integrations tools --search "users sessions traffic sources"
+fimo integrations info google-analytics
+fimo integrations run google-analytics performance_overview --input '{"days":28}'
-fimo mcp search "issue tracking"
-fimo mcp info sentry
-fimo mcp run sentry <tool> --input '{"key":"value"}'
+fimo integrations tools --search "keyword rankings backlinks"
+fimo integrations tools --search "AI search citations share of voice"
 ```
+## Add a remote MCP server
 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:
+carries any prefix itself. Fimo requires an HTTPS Streamable HTTP endpoint, encrypts credentials, assigns an
+`mcp_`-prefixed 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.
-- Firecrawl public website scraping and research → `references/integrations/firecrawl.md`
-## Enable
-```bash
-fimo integrations enable firecrawl
-fimo integrations enable fal
-fimo integrations disable firecrawl
-```
-Bare enable uses the integration's default auth path. For Firecrawl and Fal that is the only path: Fimo credits, no key,
-no connection, nothing to choose. `fimo integrations connect firecrawl` and `connect fal` are refused for that reason.
-If an integration has no safe default auth path, bare enable stops with a repair command instead of guessing.
-To bring your own Firecrawl or Fal account, add it as an MCP server (`fimo mcp add`), which is the generic path for any
-server the user owns. It does not replace the built-in service.
-## Connections
-Use `connect` for provider accounts, workspaces, OAuth installs, and user-owned MCP servers. Connections live at the
-organization level and are shared as capabilities, not as visible credentials. A project chooses one by enabling the
-integration with `--connection <alias>`.
-Set up Slack from **Project Settings > Connections** in Fimo Studio. Slack app creation and workspace approval require an explicit organization app choice, so the CLI does not guess one.
-## Run
-```bash
-fimo integrations run firecrawl scrape --url https://example.com
-fimo integrations run firecrawl scrape --url https://example.com --formats markdown,summary,links
-fimo integrations run firecrawl search --query "Example Domain" --max-results 3 --include-domains example.com
-fimo integrations run firecrawl map --url https://example.com --limit 20
-fimo integrations run firecrawl crawl --url https://example.com --limit 3 --formats markdown
-fimo integrations run firecrawl monitor.create --name pricing --url https://example.com/pricing --schedule hourly
-fimo integrations run firecrawl monitor.list
-```
+## Changes need a yes
-Firecrawl execution supports `search`, `scrape`, `map`, `crawl`, and `monitor.*` lifecycle tools. The default scrape/crawl output format is `markdown`; supported formats are `markdown`, `summary`, `links`, `images`, `html`, and `raw-html`.
+A tool whose `EFFECT` is not `read` changes data in the outside service, such as `submit_sitemap`. Run it only when the user asked for that change. Changes a person runs from their own CLI run straight away. Changes an agent runs need a person's yes, unless the site always allows that tool; paid actions always ask.
-Firecrawl search returns query-relevant excerpts by default. Use them for direct, sourced answers and scrape only when
-full context or exact wording is needed. Search can be narrowed with source, category, domain, freshness, location,
-and country options; see the Firecrawl reference for the full command shape.
+- `APP_APPROVAL_REQUIRED`: give the user the `approve_url`. When they allow the change there, Fimo shows them a one-time code: ask them to paste it, then run the same command, with the same input, plus `--approval <code>`. The code works once, for that exact call, within the hour.
+- `APP_WRITE_BLOCKED`: the change cannot run this way. Do not retry; tell the user.
-Use `--connection <alias>` only for one run of a connection-backed integration when a named connection already exists. It
-does not change the project default integration setup, and built-in services have no connection to name.
+## Errors
-Firecrawl `monitor.*` tools monitor websites for changes. `monitor.list` shows the website change monitors available in the current project. Fimo cleans up those monitors when the project is deleted.
+- `needs property`: the site has not chosen which account data to use. A site manager picks it in Studio, Site settings, Integrations.
+- `app_reconnect_required`: the provider revoked access. An organization admin reconnects the integration from Integrations.
+- `not installed`: no one connected the integration yet. Tell the user what it would let you do; never ask for credentials.
+- `Firecrawl and Fal are no longer available to new sites.`: the site never used that built-in service. Do not retry.
-For Firecrawl-specific recipes and JSON examples, load `references/integrations/firecrawl.md`.
+Set up Slack from **Settings > Integrations > Slack** in Fimo Studio.

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

@@ -1,5 +1,7 @@
 # Remote MCP integrations
+> **Deprecated.** `fimo mcp` still works but prints a warning: use `fimo integrations` instead (`references/integrations.md`). Changes ask for a person's yes the same way either way.
 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.
@@ -102,16 +104,7 @@ from stdin.
 ## Studio chat
-Remote MCP servers remain normal project integrations underneath the focused CLI. Studio chat discovers and runs them
-through:
-```bash
-fimo integrations list
-fimo integrations info mcp_sentry
-fimo integrations run mcp_sentry search_issues --input '{"query":"open regressions"}'
-```
-Studio receives a frozen snapshot of the integrations enabled when the turn starts. It never receives the underlying
+Studio chat finds and runs MCP apps with its own app tools, not with these commands. It never receives the underlying
 credential or opens a direct connection to the remote server.
 ## Supported servers

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

@@ -6,6 +6,22 @@ Three kinds of values, each set per Environment (production, preview, or a custo
 - **Private variables** — API keys and tokens the site's own server code reads. Write-only after saving.
 - **Secrets** — credentials Fimo itself uses for webhooks, schedules, and agents. Never sent to the site.
+## Choose the Environment
+Every `fimo vars` and `fimo secrets` command reads or writes one Environment, chosen with `--env`:
+```bash
+fimo vars add STRIPE_SECRET_KEY --private --stdin --env production
+fimo vars list --env preview
+fimo secrets list --env Staging
+```
+- `--env production`: the live site, used by `fimo publish`.
+- `--env preview`: Studio previews, and hosted previews of Branches no custom Environment claims.
+- `--env <name or id>`: a custom Environment from `fimo environments list`.
+Always pass `--env`. Without it, a command uses the Environment of the checked-out branch: `main` is Preview, not Production. To change the live site, pass `--env production`, check the Environment named in the result, then run `fimo publish`: the live site keeps its current variables until the next publish, and the command warns about it. Do not use `--branch` to choose the Environment; it is deprecated here and prints a warning.
 ## Public Variables
 ```bash
@@ -45,9 +61,9 @@ fimo vars unset STRIPE_SECRET_KEY
 - Fimo agents' shell commands do not receive private values, and output that would show one is redacted. Test a server route through the preview instead of reading the key from a shell.
 - A dev server whose Environment is Production never gets production private values.
 - Private variables cannot use browser prefixes (`VITE_`, `PUBLIC_`, `NEXT_PUBLIC_`, `NUXT_PUBLIC_`). Read them only from server code.
-- Set one value per Environment: a test key for preview, the live key for production.
+- Set one value per Environment: a test key for preview, the live key for production (`--env production`).
 - Public or private is chosen when the variable is created. To switch, unset it and add it again.
-- A changed or removed variable applies on the next deploy: run `fimo deploy` for previews (with no new commit, it restarts the preview and rebuilds the hosted preview when variables changed) and `fimo publish` for the live site. After changing variables for the user, offer that redeploy.
+- A changed or removed Preview or custom Environment variable rebuilds that Environment's hosted previews on its own. The Studio preview picks it up on the next `fimo deploy`, even with no new commit. A Production variable reaches the live site only on `fimo publish`: after changing one for the user, offer to publish.
 - Names that control processes (`PATH`, `NODE_ENV`, `NODE_OPTIONS`, `HTTPS_PROXY`, `GIT_*`, `NPM_CONFIG_*` and similar) are refused for new private variables, and a public variable with such a name never reaches the site's processes or the `.env.local` written by `fimo vars pull`.
 ## Secrets
@@ -71,7 +87,7 @@ Secrets are for Fimo itself: webhook headers, schedule runs, and agents. They ar
 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`.
+`fimo vars add`, `fimo vars update`, and `fimo vars pull` write public project variables to a managed block in `.env.local`. They write the values of the Environment they target, except that writes to Production never touch `.env.local`. Without `--env`, `fimo vars pull` writes the checked-out branch's Environment.
 Local env files are ignored by git in Fimo sites. They are for local development only; deployment reads project variables from Fimo and injects them into the remote build.