fimo 2.10.0-staging.1 → 2.10.0-staging.10

package/README.md

@@ -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

@@ -41,7 +41,7 @@ Pick by task:
 - AI agent setup — connect Claude Code, Codex, Cursor, or another agent → `fimo-cli` (`references/agent-setup.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

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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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-code/references/content/richtext.md

@@ -33,7 +33,7 @@ generated client hydration helper where required.
 
 ## Entry payload
 
-CLI entry writes put every value, including the collection slug, under `data`:
+`entries create` and `entries update` take `--body` with every field, including the collection slug, under `data`:
 
 ```json
 {
@@ -46,7 +46,7 @@ CLI entry writes put every value, including the collection slug, under `data`:
 }
 ```
 
-Do not put `slug` at the top level; unsupported top-level keys are stripped.
+Keep `slug` inside `data`; `entries create` rejects unsupported top-level keys.
 
 Slugs should be lowercase, hyphenated, stable, meaningful, and unique per content type. Fimo slugifies the supplied candidate. If omitted, Fimo generates one, which is unsuitable for content with durable public URLs.
 

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

@@ -20,11 +20,11 @@ into a real Fimo project without silently dropping source material.
 > supports the source framework, preserve it explicitly and verify the runtime
 > before importing data.
 >
-> Use the CLI invocation selected for this flow for every `fimo` command in the migration. Otherwise use `npx fimo@latest`; do not install it globally.
+> Use the pinned CLI invocation selected for this flow for every `fimo` command in the migration (see CLI provenance); do not install it globally.
 
 The first pass is a faithful migration, not a framework conversion. Detect the
-source framework before creating the target and pass it explicitly to
-`fimo migrate init`. For a Next.js source, use `--framework nextjs`; never rely
+source framework before setup. When `fimo migrate init` creates the target, pass
+it explicitly: for a Next.js source, use `--framework nextjs`; never rely
 on the React Router default. The setup receipt must report the target runtime
 framework, and a mismatch is a setup failure before any schemas, entries,
 assets, labels, or forms are imported.
@@ -90,30 +90,43 @@ artifact, and record which one.
 
 ## Initialized target precondition
 
-Before workers start, the root process must establish a real Fimo project and
-environment, link the migration checkout to it, and prove the data plane is
-reachable with a read such as `fimo schemas list -C <target> --branch <branch>` using
-the selected pinned CLI. Give workers the project id, environment, exact CLI
-invocation, and verification command. Generated `.fimo` JSON without a
-successful platform read is not initialization.
-
-Pick the setup path from the evidence:
-
-- **Source-backed, same framework** — copy or `git worktree` the source into the
-  target directory first, then run `fimo link -C <target> --branch <branch>`
-  (`fimo link <project-id> -C <target> --branch <branch>` when the owner supplied an
-  id). Link creates or selects the project, keeps the source's code, framework,
-  git history, and `origin`, initializes a repository when the copy has none,
-  and adds only the Fimo dependency, `.fimo/project.json`, the `fimo` remote,
-  and `.fimo/config.json#runtime.framework`. It never overlays a template, so
-  the target must already contain the source.
-- **Empty target, or an explicit framework conversion** — `fimo init` or
-  `fimo migrate init <dir>` with the chosen `--framework`. Both refuse a
-  non-empty target and write nothing when they refuse.
-
-If authentication, organization selection, project creation, environment
-resolution, linking, or the verification read fails, stop before workers and
-report the exact failed command and setup requirement.
+This is the one setup decision; every other reference points here. Pick the
+row that matches the user's request and the folder's state. When the target is
+genuinely unclear, ask once in the preflight question batch.
+
+| Starting point                                                                         | Setup                                                                                                                                                                                     | Original evidence                                                                                                                                                                      |
+| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The user asked to put this existing folder on Fimo; it is already linked               | Reuse it. Verify its project, branch, and framework. Run `fimo link <same-id> -C <folder>` only to repair it.                                                                             | Keep the baseline below.                                                                                                                                                               |
+| The same, but the folder is not linked                                                 | Keep the baseline, then run `fimo link -C <folder> --branch <branch>`, with the project id when one was chosen.                                                                           | Keep the baseline below. Never reset, overwrite, or discard existing work.                                                                                                             |
+| The source is read-only input, or the user asked for a separate target; same framework | Copy or clone the source into the target first. If the copy kept a `.fimo/project.json`, reuse that project or resolve it on purpose. Then run `fimo link -C <target> --branch <branch>`. | The original stays read-only. A `git worktree` shares the repository's config and remotes: use an independent copy or clone when adding the `fimo` remote must not touch the original. |
+| An empty or new target with nothing to adopt, or an explicit framework conversion      | `fimo migrate init <target> --framework <chosen>` (see Target setup). Never overlay a template on populated source.                                                                       | The source repository or export stays separate.                                                                                                                                        |
+
+The baseline is an exact copy of the folder's pre-migration state, kept outside
+the folder. A commit plus a detached worktree is enough only when the tree is
+clean; otherwise also keep the dirty and untracked files. Never copy secret
+values into evidence.
+
+`fimo link` keeps the folder's code, framework, git history, branches, and
+`origin`, initializes a repository when there is none, and adds only the Fimo
+dependency, `.fimo/project.json`, the `fimo` remote, and
+`.fimo/config.json#runtime.framework`. It never overlays a template.
+
+Never invent a project or organization id, and never silently relink a folder
+to another project (`fimo link --relink` needs the owner's explicit choice).
+In a non-interactive shell, `fimo link` on an unlinked folder without an id,
+and `fimo migrate init` without `--project-id`, create a new project in the
+active organization, else the only one; `fimo migrate init` also takes `--org`. With several organizations and none
+active, the CLI fails clearly: ask the user which one. Ask only for a selection
+the CLI cannot resolve.
+
+Every row ends at the same gate. Before workers start, prove the actual project
+id and branch, a runtime framework that matches the source or the chosen
+conversion, the selected pinned CLI, and a successful data-plane read such as
+`fimo schemas list -C <target> --branch <branch>`. A local marker, generated
+`.fimo` JSON, or a `ready: true` receipt without that read is not
+initialization. Give workers the project id, branch, exact CLI invocation, and
+verification command. If any setup step fails, stop before workers and report
+the exact failed command and setup requirement.
 
 ## Core contract
 
@@ -135,7 +148,9 @@ report the exact failed command and setup requirement.
   ports the source's APIs, loaders, hardcoded content, integrations, and
   visible behavior into the new framework unchanged, and Fimo schemas,
   payloads, imports, and code wiring happen later through the content workers
-  (`references/workers/content-execution.md`). If the framework or hosting
+  (`references/workers/content-execution.md`). That content pass is part of the
+  migration, never a follow-up: the `editable-text` guardrail
+  (`references/qa.md`) fails while visible text is still typed in the code. If the framework or hosting
   setup is unclear or unsupported, stop and ask instead of guessing,
   converting it, or deleting provider-specific files.
 - Inventory provider-specific files and rules before editing them. Classify each
@@ -247,25 +262,24 @@ report the exact failed command and setup requirement.
 
 ## Target setup
 
-The target is its own Fimo project directory. The client source checkout is
-read-only evidence: never run setup inside it, never modify it, and never
-hand-write a `.fimo/project.json` marker to fake a link.
-
-`fimo migrate init` is the setup gate for an empty target; a target that
-already holds the copied source is set up with `fimo link` instead (see
-Initialized target precondition). `fimo migrate init` validates the target and
-CLI auth, then delegates project selection and creation to the standard
-`fimo init` flow (same options, no separate creation path), and returns a setup
-receipt covering auth, the target link, the migration directory, and readiness.
-It fails with a structured error when auth is missing, the target is missing or
-invalid, or the project or organization is inaccessible. Both forms need a real
-ID supplied by the owner — without one, stop with an unresolved owner action
-instead of inventing an ID:
-
-- Link an owner-supplied (empty) project:
+Choose the setup row in "Initialized target precondition". Never modify an
+original that the row keeps read-only, and never hand-write a
+`.fimo/project.json` marker to fake a link.
+
+`fimo migrate init` serves the empty-target and conversion row. It validates
+the target and CLI auth, then delegates project selection and creation to the
+standard `fimo init` flow (same options, no separate creation path), and
+returns a setup receipt covering auth, the target link, the migration
+directory, and readiness. It fails with a structured error when auth is
+missing, the target is missing or invalid, the target is populated but not
+linked, or the project or organization is inaccessible:
+
+- Use an existing (empty) project:
   `fimo migrate init <target-dir> --project-id <projectId> --framework <framework> --source-platform <platform>`
-- Create a new project in an owner-supplied organization:
-  `fimo migrate init <target-dir> --org <organizationId> --framework <framework> --source-platform <platform>`
+- Create a new project:
+  `fimo migrate init <target-dir> --framework <framework> --source-platform <platform>`,
+  adding `--org <organizationId>` when the precondition's organization rule
+  needs it.
 
 `--source-platform` names what the site is migrated from (`wordpress`, `nextjs`,
 `astro`, `react-router`, `webflow`, `framer`, `squarespace`, `wix`, `carrd`,
@@ -277,9 +291,11 @@ framework files before starting workers. A Next.js target must still have its
 Next runtime/configuration (`next.config.*` and the source router shape), not a
 React Router scaffold.
 
-Setup scaffolds the target and pushes its initial commit; that is the only
-remote write it performs — it never pushes schemas, uploads assets, or imports
-entries. Setup itself never deploys or publishes; the one new-project preview
+`fimo migrate init` on a new target scaffolds it and pushes its initial
+commit. `fimo link` and reusing a linked folder scaffold and push nothing; the
+first commit waits for `fimo deploy`. Project creation or linking and that
+initial push are the only remote writes setup performs — it never pushes
+schemas, uploads assets, or imports entries. Setup itself never deploys or publishes; the one new-project preview
 deploy happens only after successful local QA (see Completion and deployment).
 
 ## Command surface
@@ -289,20 +305,18 @@ up and nothing else: it never reads, fetches, or renders the source site, and
 it produces no evidence pack, draft, manifest, or scaffold to inspect. Reading
 the source is your job, and every finding is yours to prove.
 
-- `fimo migrate init <dir> --project-id <projectId>` — link an owner-supplied
-  project.
-- `fimo migrate init <dir> --org <organizationId>` — create a new project.
+- `fimo migrate init <dir> --project-id <projectId>` — use an existing project.
+- `fimo migrate init <dir> [--org <organizationId>]` — create a new project.
 - Both accept `--framework`, `--source-platform` (see Target setup),
   `--install` / `--no-install`, `--agents` / `-a`, `--mode`, `--template-root`,
   and `--json`; `-C <dir>` replaces the positional for an already-linked target.
 
-The link/creation and its initial commit push are the only remote writes. Data
-writes go through the normal commands against the linked target:
+Setup (`fimo migrate init` or `fimo link`, chosen in Initialized target
+precondition) makes only the remote writes listed in Target setup. Data writes
+go through the normal commands against the linked target:
 
 - `fimo schemas push`, `fimo assets upload`, `fimo entries create|update`,
   `fimo singles update`, `fimo labels set|set-many`, `fimo forms push`.
-- `fimo link`: project creation or selection plus the in-place adoption of a
-  copied source target.
 - `fimo deploy` / `fimo publish` — owner-approved only.
 
 ## Migration loop
@@ -312,7 +326,7 @@ writes go through the normal commands against the linked target:
    edit, or move environment values until the user answers every consent gate.
 2. Run the setup path from "Initialized target precondition" and inspect the
    initialized target before any worker edits it. A `fimo link` adoption keeps
-   the source framework; the `fimo init` / `fimo migrate init` paths choose the
+   the source framework; the `fimo migrate init` path chooses the
    target framework through the same canonical option as
    `fimo init`: pass the detected source framework for a source-backed
    migration, the framework the user explicitly chose for a conversion, and —
@@ -404,8 +418,8 @@ Use one final status:
 
 Never call a migration complete when CMS entries, media mappings, forms, route
 coverage, or migration-induced content-delivery regressions are unknown. Local
-QA remains the acceptance gate. If
-`fimo migrate init` created a new Fimo project, run one `fimo deploy` after QA
+QA remains the acceptance gate. If setup created a new Fimo project
+(`fimo migrate init` or `fimo link`), run one `fimo deploy` after QA
 and return its preview and dashboard links; skip it when the user said not to
 deploy or `FIMO_MIGRATION_NO_DEPLOY=1` is set. For an existing linked project,
 offer the deployment and wait for approval. Never run `fimo publish` without an

package/assets/skills/fimo-migration/references/import-contract.md

@@ -10,7 +10,7 @@ items.
 
 Every data-plane write in this contract targets the linked project from
 workflow Phase 0. Planning and payload authoring need no link; running the
-writes does. When no owner-supplied target exists, the writes stay unresolved
+writes does. When setup cannot produce a linked target, the writes stay unresolved
 owner actions; do not fake a link to make them pass.
 
 ## Media Files

package/assets/skills/fimo-migration/references/qa.md

@@ -182,6 +182,13 @@ check is the acceptance evidence.
      or imprint.
    - `links-resolve`: every internal link rendered on the inventoried routes
      points at an inventoried route or an explicitly allowed path prefix.
+   - `editable-text` (required in every inventory): every visible body text node
+     sits inside an element a Fimo primitive renders, so an editor can change it
+     in Studio. A faithful port is not editable yet: text still typed in the code
+     shows "Nothing to edit". Move it to a label or a CMS field. List in `allow`
+     only the exact text the owner keeps in code, such as a brand glyph or a
+     legal line, and record why in the migration report. Assistive and hidden
+     text does not count.
 
    Internal links are resolved against the final document URL and any
    `<base href>`; query and fragment do not change route identity. An `allow`
@@ -203,14 +210,18 @@ check is the acceptance evidence.
          "source": "<owner decision>"
        },
        { "id": "footer-privacy", "kind": "required-link", "href": "/legal/privacy", "source": "<source navigation>" },
-       { "id": "nav-resolves", "kind": "links-resolve", "allow": ["/blog"], "source": "<source navigation>" }
+       { "id": "nav-resolves", "kind": "links-resolve", "allow": ["/blog"], "source": "<source navigation>" },
+       { "id": "editable-text", "kind": "editable-text", "allow": [], "source": "Fimo: visitors' text is editable" }
      ]
    }
    ```
 
 2. The validator observes the rendered application, not files in the
-   repository. For a server-rendered target, run the check with `--base-url`
-   while the built app serves locally. For a client-rendered target, save each
+   repository, with Fimo editing metadata on: build and serve with
+   `FIMO_EDITING_METADATA=true`, or observe the dev server. Without it no text is
+   marked editable and `editable-text` fails as unmeasured. For a
+   server-rendered target, run the check with `--base-url` while the app serves
+   locally. For a client-rendered target, save each
    hydrated document from the browser pass as `<captures>/index.html` and
    `<captures>/<route>.html` and pass `--captures`. Save a JSON sidecar next to
    each HTML file, such as `index.html.json` or `legal/privacy.html.json`:

package/assets/skills/fimo-migration/references/workers/content-planner.md

@@ -5,7 +5,10 @@ handoff. Do not import entries or rewrite application consumers.
 
 1. Trace active source clients, endpoint/query declarations, frontend types,
    and every consumer before designing schemas. Then inspect their
-   content-bearing files, inline values, APIs, or CMS sources.
+   content-bearing files, inline values, APIs, or CMS sources, and the visible
+   text typed in route and component code: headings, paragraphs, buttons, link
+   and navigation text, alt and placeholder text. Each is an item, even when no
+   data source holds it.
 2. Classify each value as collection content, single content, an
    editor-visible label, or application-owned code. Repetition is evidence,
    not an automatic collection rule. Assistive text, identifiers, and values