fimo 2.3.2 → 2.4.0-staging.2

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

@@ -100,7 +100,7 @@ Load the matching reference when the user's request fires its trigger. Recipes t
 - "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 and start with `fimo migrate <url> [dir]` to prepare the agent-ready migration draft
+- "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
 - "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`

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

@@ -8,7 +8,7 @@
 
 Before deploying, Fimo fast-forwards a clean checkout that is behind and stops on dirty-behind or diverged branches. This syncs the whole branch, including config commits from Studio or locale commands.
 
-> **Just need the current preview URL?** That's `fimo preview url` — no commit or push. A cold sandbox can still take time to resolve. See `references/preview.md`. `fimo deploy` is only for pushing code changes.
+> **Just need the current preview URL?** That's `fimo preview url` — no commit or push. It waits if the hosted generation is still building. See `references/preview.md`.
 
 ## Commands
 
@@ -19,7 +19,7 @@ fimo deploy --no-restart                     # skip dev-server restart (HMR-safe
 fimo deploy -m "<commit message>" --publish  # also publish a new live version
 ```
 
-- **`fimo deploy`** — commits pending changes, pushes to the current Branch, syncs that Branch's preview sandbox, and links to the Preview and Fimo dashboard.
+- **`fimo deploy`** — commits pending changes, pushes to the current Branch, syncs that Branch's preview sandbox, and links to Fimo Studio.
 - **`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.
 - **`--no-restart`** — tells the sandbox to skip the dev-server restart and let Vite HMR pick up the change. Shaves ~3s per deploy. See "Skipping the dev-server restart" below for when it's safe.
@@ -35,16 +35,13 @@ fimo deploy -m "<commit message>" --publish --json
 
 Read these fields from `data`:
 
-| Field                | Destination                                                      |
-| -------------------- | ---------------------------------------------------------------- |
-| `preview_url`        | Stable, authenticated full-screen viewer for project members.    |
-| `sandbox_url`        | Short-lived raw site URL for agents, curl, and screenshot tools. |
-| `sandbox_expires_at` | Expiry of the raw sandbox URL.                                   |
-| `studio_url`         | Stable, authenticated Fimo Studio project and Branch page.       |
-| `dashboard_url`      | Deprecated compatibility alias for `studio_url`.                 |
-| `app_url`            | Public live site, returned after a successful `--publish`.       |
+| Field           | Destination                                                |
+| --------------- | ---------------------------------------------------------- |
+| `studio_url`    | Stable Fimo Studio project and Branch page.                |
+| `dashboard_url` | Deprecated compatibility alias for `studio_url`.           |
+| `app_url`       | Public live site, returned after a successful `--publish`. |
 
-When reporting the result, open `preview_url` for a person and use `sandbox_url` for machine reads. If no code changed and you only need fresh destinations, use `fimo preview url --json` instead of deploying again.
+When reporting the result, give the user `studio_url`. If a person or tool needs the hosted site itself, run `fimo preview url` after deploy.
 
 Public project variables managed with `fimo vars add` and `fimo vars update` are injected into preview/build/deploy runtimes. Project secrets are not injected into app builds; agents request secrets separately through their own config. See `references/project-vars-and-secrets.md`.
 

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

@@ -165,7 +165,7 @@ Whenever `fimo init` created or scaffolded a new project — including a Studio-
 fimo deploy -m "chore: first preview" --json
 ```
 
-`-m` is required because you run non-interactively; the deploy validates, commits pending changes, pushes, and syncs the hosted preview. It is also the sandbox warm-up — never run a separate warm-up deploy on this path. Read `data.preview_url` and `data.studio_url` from the envelope and return both links. `data.dashboard_url` remains a deprecated compatibility alias for `data.studio_url`. If the initiating request described a concrete site, build a minimal meaningful first screen before this single deploy; otherwise deploy the scaffolded site as-is and then ask what to build.
+`-m` is required because you run non-interactively; the deploy validates, commits pending changes, pushes, and syncs the preview sandbox. Return `data.studio_url` from the envelope. Run `fimo preview url --json` only when the hosted site URL itself is needed. If the initiating request described a concrete site, build a minimal meaningful first screen before this single deploy; otherwise deploy the scaffolded site as-is and then ask what to build.
 
 This first deploy creates a preview only — never add `--publish`, and treat every later deploy as offer-then-confirm. The rule does not apply when `init` cloned a project with existing code or when the work is a migration; those paths keep their normal deployment approval rules.
 

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

@@ -228,4 +228,4 @@ Visual/content QA before publish:
 fimo integrations run firecrawl scrape --url "$(fimo preview url)" --formats markdown,links --json
 ```
 
-Because command substitution captures stdout, `fimo preview url` emits the raw `sandbox_url` in this example. For JSON workflows, pass `data.sandbox_url` to Firecrawl and refresh it after `data.sandbox_expires_at`. The stable `data.preview_url` is an authenticated browser viewer and is not the Firecrawl destination.
+`fimo preview url` emits the hosted deployment URL in this example. In JSON workflows, pass `data.preview_url` to Firecrawl.

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

@@ -1,27 +1,19 @@
-# Preview URL (without deploying)
+# Hosted preview URL
 
-**Use `fimo preview url` whenever you need the current hosted preview — to open it, screenshot it, hand it to another tool, or verify a change you already deployed. Never trigger `fimo deploy` just to retrieve a URL.**
-
-`fimo deploy` commits, pushes, and syncs the sandbox before it prints destinations. `fimo preview url` skips those deployment steps and only resolves the current Branch's preview destinations.
-
-## Commands
+Use `fimo preview url` to get the current Branch's hosted preview without committing or pushing.
 
 ```bash
-fimo preview url                                      # current Branch (from git)
-fimo --branch feat/redesign preview url              # specific Branch
-fimo preview url --branch main --json                # structured output for agents / scripts
-fimo preview url --all                               # print every destination as named raw URLs
-curl -L "$(fimo preview url)"                        # fetch the raw sandbox preview
+fimo preview url
+fimo --branch feat/redesign preview url
+fimo preview url --branch main --json
+curl -L "$(fimo preview url)"
 ```
 
-`--env <name>` is rejected as a Branch selector; use `--branch <name>`. The JSON envelope carries the canonical `branch` field and may include a deprecated `env` compatibility duplicate. Studio deep links still use the `/env/` path, which redirects to `/branch/`.
+The command returns the hosted deployment URL in every output mode, whatever the project's Preview setting says: every live Branch except production owns a hosted build.
 
-## Human and machine behavior
+If the current generation is queued or building, the command waits up to five minutes, polling with a backoff. It stops at once — without waiting — on a state waiting cannot change: a build that failed, and a Branch with no hosted preview (production, or a Branch nothing has changed yet). Every failure returns `PREVIEW_URL_FAILED`; read `error.message` for which one it was and `error.hint` for the next step. Only the timeout is worth retrying.
 
-- **Interactive terminal:** shows the stable `preview_url` and `studio_url` as named links. `preview_url` opens a full-screen Fimo viewer and requires a logged-in user with access to the project.
-- **Piped or captured output:** prints only the short-lived `sandbox_url`. This preserves commands such as `curl -L "$(fimo preview url)"` and gives browsers, screenshot tools, and crawlers the directly fetchable site.
-- **`--all`:** prints `preview_url`, `studio_url`, `sandbox_url`, and `sandbox_expires_at` as named raw values for a person inspecting every destination.
-- **JSON mode** (or `FIMO_OUTPUT=json`): returns both destinations explicitly:
+JSON output contains only the Branch identity and hosted URL:
 
 ```json
 {
@@ -32,33 +24,11 @@ curl -L "$(fimo preview url)"                        # fetch the raw sandbox pre
     "project_id": "prj_abc",
     "branch": "main",
     "env": "main",
-    "preview_url": "https://fimo.ai/preview/prj_abc/main",
-    "sandbox_url": "https://preview.provider.example/session",
-    "sandbox_expires_at": "2026-08-20T18:42:00.000Z",
-    "studio_url": "https://fimo.ai/app/projects/prj_abc/branch/main/preview",
-    "dashboard_url": "https://fimo.ai/app/projects/prj_abc/branch/main/preview"
+    "preview_url": "https://fimo-preview-example.vercel.app"
   }
 }
 ```
 
-Agents must use `data.sandbox_url` for curl, Firecrawl, screenshots, and other machine reads. Use `data.preview_url` for the authenticated full-screen viewer and `data.studio_url` for the Branch inside Fimo Studio. `data.dashboard_url` is a deprecated compatibility alias for `data.studio_url`. The raw sandbox URL expires; resolve it again when `sandbox_expires_at` is near or has passed. The stable human URLs do not need to be regenerated.
-
-## When to use it
-
-- **You deployed a change and want to inspect it** — open the interactive `preview_url`.
-- **An agent or tool needs to read the site** — pipe the command or use `data.sandbox_url` from JSON.
-- **The raw URL expired** — run `fimo preview url` again; do not redeploy.
-
-## When NOT to use it
-
-- **You changed code and want it on the preview** — use `fimo deploy`. This command only retrieves destinations.
-- **You need the live published URL** — use `fimo deploy --publish` or `fimo publish`; see `references/deploy.md` and `references/domains.md`.
-
-## Cold sandbox case
-
-Resolving `sandbox_url` may take roughly 60–90 seconds when an idle sandbox must be provisioned or restarted. The stable `preview_url` performs the same authenticated resolution when a project member opens it.
-
-## See also
+Use `fimo deploy` when code still needs to be pushed. Use `fimo deploy --publish` or `fimo publish` only when the site should go live.
 
-- `references/deploy.md` — when you need to push code.
-- `references/branches.md` — Branch semantics and the global `--branch <name>` flag.
+See `references/deploy.md` for deployment and `references/branches.md` for Branch selection.

package/assets/skills/fimo-code/references/frameworks/next/app-router.md

@@ -109,24 +109,10 @@ Do not add `'use client'` to a page solely because Fimo is present. Keep promise
 
 ## Metadata
 
-Fimo owns the site-wide defaults; the application owns per-page overrides. Keep (or add) the starter wiring in the root layout — it maps `.fimo/config.json#seo` (Studio's Settings → SEO: title, description, favicon, share image, robots, theme color, canonical) onto Next `Metadata`/`Viewport`:
-
-```ts
-import { buildFimoMetadata, buildFimoViewport } from 'fimo-next';
-
-export const generateMetadata = () => buildFimoMetadata();
-export const generateViewport = () => buildFimoViewport();
-```
-
-If the root layout lacks this wiring, add it (updating the fimo packages if `fimo-next` does not export the helpers); without it, Settings → SEO never reaches the rendered head.
-
-Per-page `metadata`/`generateMetadata` exports override the defaults field by field. Resolve labels/content on the server and convert tracked strings only where Next expects primitives:
-
-```ts
-export async function generateMetadata() {
-  const labels = await getLabels();
-  return { title: String(labels.t('seo.home.title')) };
-}
-```
-
-Do not expect `FimoProvider` to inject SEO, routes, language, or direction.
+When creating a site, adding a route, or integrating SEO, load
+`references/frameworks/next/seo.md` (`--ref frameworks/next/seo`). Keep root
+global defaults separate from explicit Home and route SEO. Reuse the app's
+established route integration for new pages; a dynamic route module covers all
+its instances. Next replaces nested metadata objects, not their individual
+fields. Preserve app-owned policies and image routes. `FimoProvider` does not
+inject SEO.

package/assets/skills/fimo-code/references/frameworks/next/seo.md

@@ -0,0 +1,168 @@
+# Next.js SEO
+
+Use the installed package APIs. The app owns routing, metadata policy and
+rendering mode. Fimo supplies editable values, not a router or a merge policy.
+
+## Read, resolve, convert
+
+```ts
+import { getFimoSeo } from 'fimo/seo/server';
+import { toNextMetadata, toNextViewport } from 'fimo-next/seo';
+
+// Root layout: global defaults, never implicitly Home.
+export const generateMetadata = () => toNextMetadata(getFimoSeo());
+export const generateViewport = () => toNextViewport(getFimoSeo());
+```
+
+For a new App Router site, keep this root wiring. Home is an explicit route:
+
+```ts
+// app/page.tsx
+export const generateMetadata = () => toNextMetadata(getFimoSeo({ pathname: '/' }));
+```
+
+For each route module with configured route SEO, resolve its real pathname.
+One dynamic module handles every slug. Reuse the app's content loader and URL
+builder; do not try to infer a full pathname from Next's params in the root.
+
+```ts
+// app/blog/[slug]/page.tsx, using the app's existing loader and URL builder
+export async function generateMetadata({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const article = await getArticle(slug);
+  return toNextMetadata(
+    getFimoSeo({
+      pathname: articlePath(article),
+      routeData: { article },
+    })
+  );
+}
+```
+
+Loaders should retain their normal not-found and caching behavior. Add
+`generateViewport` at a route only when route-specific `themeColor` needs to
+apply; share the existing cached loader if both exports need its data. Other
+routes inherit the root color. When adding a page, follow the established
+pattern and keep its Fimo catalog entry aligned with a URL the app serves.
+
+`getFimoSeo({ pathname?, routeData?, rootDir? })` is synchronous and Node-only.
+No pathname reads global SEO. A pathname applies matching route overrides.
+It reads current or legacy project config using Fimo's config discovery;
+missing config/SEO returns `undefined`, malformed JSON and other I/O errors
+throw. Pass `rootDir` for a monorepo app located away from the process cwd.
+It does not cache, fetch content, infer locales or invalidate Next's caches.
+Config edits reach static output on rebuild and cached output on the app's
+normal revalidation path. Fetched route content can remain cached across
+builds; use the app's data-cache invalidation/revalidation policy and verify
+the rendered value after a content edit. Rebuild success is not freshness proof.
+
+For bundled data or Edge, supply config yourself to the pure resolver instead
+of importing the Node reader:
+
+```ts
+import { resolveSeoForPath } from 'fimo/seo';
+import { toNextMetadata } from 'fimo-next/seo';
+
+const seo = resolveSeoForPath(pathname, publicSeoConfig, { article });
+const metadata = toNextMetadata(seo);
+```
+
+Bundle only public SEO/routes, not credentials or project connection data.
+Every ancestor layout of an Edge page must also avoid the Node reader. Use
+bundled public SEO for shared root defaults, not just for the Edge leaf.
+The converters have no I/O or Next request dependency. Their output is for
+App Router; Pages Router keeps its existing `next/head` or SEO library and
+maps resolved Fimo values there. Do not convert routers for SEO.
+
+## Available fields
+
+Global values live at `seo` and overrides at `routes.<id>.seo` in the project's
+existing Fimo config (normally `.fimo/config.json`). Preserve other config keys.
+`fimo pages set` manages the route catalog but has no `--seo` flag; edit the
+config to author route SEO. For example:
+
+```json
+{
+  "seo": { "title": "Journal", "description": "Notes from the field" },
+  "routes": {
+    "article": {
+      "path": "/blog/:slug",
+      "seo": { "title": "{{article.title}}", "description": "{{article.summary}}" }
+    }
+  }
+}
+```
+
+`FimoSEO` from `fimo/seo` has these optional string fields:
+
+| Fimo field    | Next output                                            |
+| ------------- | ------------------------------------------------------ |
+| `title`       | `title`                                                |
+| `description` | `description`                                          |
+| `siteName`    | `openGraph.siteName`                                   |
+| `url`         | `metadataBase`, relative canonical and `openGraph.url` |
+| `image`       | `openGraph.images`                                     |
+| `favicon`     | `icons.icon` and `icons.apple`                         |
+| `twitterSite` | `twitter.site`                                         |
+| `robots`      | `robots` meta, not robots.txt                          |
+| `themeColor`  | `Viewport.themeColor`, not Metadata                    |
+| `locale`      | `openGraph.locale`, not URL or translation selection   |
+
+Route fields use the same shape. `{{article.title}}` reads caller-supplied
+`routeData.article.title`; `siteName` and route `label` are built-in context.
+A missing, empty or nonscalar token falls back for the entire field to its
+global value, then absence. Tracked Fimo strings are supported. This does not
+invent content when an article is missing.
+
+Converters return `{}` for undefined SEO. They leave social title/description
+and Twitter images unset so Next derives them from final page metadata/OG.
+They default OG type to `website` and Twitter card to `summary_large_image`.
+`url` is a site base; relative canonical/OG URLs follow the active route.
+App-specific canonical policies, hreflang, JSON-LD, sitemaps, robots.txt,
+verification tags and generated social images remain app-owned.
+
+## Existing app: adopt only chosen fields
+
+Inspect existing root/section/page exports and file-based icons/social images
+first. Do not spread every resolved global value into a leaf: that can replace
+a section's `noindex` policy or image. Keep the app's established metadata
+builder and choose the fields Fimo should supply. For example, an app choosing
+Fimo's editable description while retaining its title and policy:
+
+```ts
+export async function generateMetadata(context: Props) {
+  const application = await getApplicationMetadata(context);
+  const seo = getFimoSeo({ pathname: await getApplicationPathname(context) });
+  return {
+    ...application,
+    ...(seo?.description ? { description: seo.description } : {}),
+  };
+}
+```
+
+The loader/path helpers above belong to the app, not Fimo. For nested fields,
+explicitly retain the siblings the app intends to keep. Next replaces
+`openGraph`, `twitter`, `icons` and `alternates` objects across segments; there
+is no generic deep-merge or null-based suppression guarantee. Never spread
+parent `ResolvedMetadata` wholesale. File-based images can mask config values;
+preserve them unless the user chooses to replace that behavior.
+
+Use one title-suffix owner. If a Fimo template already produces a complete
+title, return `title: { absolute: seo.title }` to bypass an ancestor
+`title.template`, or remove the duplicated suffix from the Fimo template.
+Next's layout `title.template` does not apply to a page in that same segment;
+give Home its complete app-owned title when it needs the suffix too.
+Preserve deliberate Twitter-specific images; otherwise allow Next's OG fallback.
+
+The existing `buildFimoMetadata(rootDir?)` and `buildFimoViewport(rootDir?)` from `fimo-next`
+remain global-only helpers. Their string argument is a directory, not a route.
+
+## Prove the rendered result
+
+Build and request representative Home, static and dynamic routes. Check the
+actual title, description, canonical, OG/Twitter images, icons, robots and
+theme color against configured values. Include missing template data and an
+existing section policy. Confirm social titles follow the final page title,
+suffixes occur once, and no Home values leak to other routes. A helper import
+or a successful build alone does not prove SEO. Check supported runtime and
+revalidation behavior when those are part of the task.

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

@@ -2,7 +2,7 @@
 
 Use this reference when `fimo describe --json` reports `framework.slug: "nextjs"`, or the project uses an App Router (`app/` or `src/app/`) or Pages Router (`pages/` or `src/pages/`) tree.
 
-Fimo supports schema-first content in both routers across static generation, ISR, request-time rendering, and Client Components. The application owns routes, locale resolution, links, `<html lang/dir>`, and per-page SEO overrides. Fimo receives the resolved locale and supplies content, labels, source metadata, client editing context, and the site-wide SEO defaults (App Router: `buildFimoMetadata`/`buildFimoViewport` in the root layout — see the router reference's Metadata section).
+Fimo supports schema-first content in both routers across static generation, ISR, request-time rendering, and Client Components. The application owns routes, locale resolution, links, `<html lang/dir>`, and SEO policy. Fimo supplies content, labels, editing context and optional resolved SEO values. For site creation, new routes or SEO changes, load `references/frameworks/next/seo.md`.
 
 ## Choose the router reference
 

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

@@ -100,9 +100,9 @@ Pick the setup path from the evidence:
   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` with the
-  chosen `--framework`, or `fimo migrate init <url> <dir>` for a URL crawl.
-  Both refuse a non-empty target and write nothing when they refuse.
+- **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
@@ -151,7 +151,7 @@ report the exact failed command and setup requirement.
   unresolved item with the source evidence, the owner action, and the
   user-visible impact. Never claim completion while source content is
   unwired.
-- Prefer source code and exports over inferred crawl data. Use a public URL as
+- Prefer source code and exports over what a page renders. Use a public URL as
   visual, SEO, route, and behavior evidence when better source material exists.
   When the source defines an active CMS but its deployed records are unavailable,
   rebuild published content from the public site only after the user explicitly
@@ -205,8 +205,12 @@ report the exact failed command and setup requirement.
    - **source-backed**: source repository, export, downloaded HTML, CMS data,
      or media folder. The source files are truth; the workers read them
      directly.
-   - **url-only**: only a published URL. Run `fimo migrate <url> [dir]` to
-     create the draft evidence pack.
+   - **url-only**: only a published URL. You read the site yourself: open each
+     route in a browser, let client-side rendering finish, and record the
+     sections, copy, images, links, and forms you actually see. Fetching HTML
+     without executing JavaScript is not evidence — a client-rendered page
+     returns an empty root element, which reads as a site with no content.
+     Never report a route as covered from a fetch that returned no sections.
    - **hybrid**: source material plus a public URL. Treat source material as
      truth and the URL as comparison evidence.
 4. Read `references/questions-and-improvements.md`, finish its read-only
@@ -254,7 +258,8 @@ instead of inventing an ID:
 
 `--source-platform` names what the site is migrated from (`wordpress`, `nextjs`,
 `astro`, `react-router`, `webflow`, `framer`, `squarespace`, `wix`, `carrd`,
-`other`); pass what the source checkout proves, `unknown` only when nothing does.
+`other`); pass what the source proves, `unknown` only when nothing does. It is
+explicit only — nothing detects it, and omitting it records `unknown`.
 
 After setup, check `.fimo/config.json#runtime.framework` and the scaffold's
 framework files before starting workers. A Next.js target must still have its
@@ -268,32 +273,23 @@ deploy happens only after successful local QA (see Completion and deployment).
 
 ## Command surface
 
-Plan-only commands operate on local artifacts and work before the target is
-linked:
-
-- `fimo migrate init <url> [dir]` — URL migrations only: crawl the live site
-  into the draft evidence pack.
-- `fimo migrate inspect` — summarize the URL draft or an existing legacy ledger.
-- `fimo migrate import` — print the import plan; it writes no data.
-- `fimo migrate apply` / `fimo migrate refine` — URL-draft-only scaffold and
-  refinement handoff; they play no role in a source-backed migration. `apply`
-  must never run against an initialized non-React-Router target: it is the
-  legacy React Router scaffold path and must fail instead of downgrading a
-  Next.js (or another framework) project.
-- `fimo migrate manifest` / `fimo migrate report` — legacy URL-draft helpers.
-  New source-backed migrations use the plain-text migration plan, worker
-  reports, and final migration report; they do not bootstrap another JSON
-  registry.
-
-Commands that perform actual data writes, all requiring the linked target:
+`fimo migrate init <dir>` is the only migration subcommand. It sets the target
+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.
+- 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:
 
 - `fimo schemas push`, `fimo assets upload`, `fimo entries create|update`,
   `fimo singles update`, `fimo labels set|set-many`, `fimo forms push`.
-- `fimo migrate init` (source-backed form): the project link/creation and
-  initial commit push described above. Pass `--source-platform <platform>`
-  (webflow, framer, squarespace, wix, carrd, wordpress, nextjs, astro,
-  react-router, other) when the source is known; URL crawls detect it.
-
 - `fimo link`: project creation or selection plus the in-place adoption of a
   copied source target.
 - `fimo deploy` / `fimo publish` — owner-approved only.
@@ -378,9 +374,9 @@ Commands that perform actual data writes, all requiring the linked target:
 - `references/workers/content-execution.md` - data import and code-wiring
   contracts.
 - `references/workers/validator.md` - independent fan-in validation.
-- Existing manifest/decision helper scripts are legacy compatibility tools for
-  older migration artifacts. Do not invoke them in a new migration unless the
-  user explicitly asks to replay an older artifact.
+- `scripts/apply-decision.mjs` and `scripts/write-migration-report.mjs` replay
+  an older JSON-ledger migration. A new migration writes the plain-text plan
+  and report instead; do not invoke them unless the user asks for that replay.
 
 ## Completion and deployment
 

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

@@ -119,7 +119,7 @@ Then use source headers, values, and repeated patterns:
 - excerpt/summary/dek -> `text`
 - image/photo/thumbnail/media/asset/file -> `media`, carrying the source alt on
   the media value; never add a separate alt field (`references/media.md`)
-- date/published/created/updated -> `date`; use `datetime` only when the crawled
+- date/published/created/updated -> `date`; use `datetime` only when the source
   values carry a time and a UTC offset, which `datetime` requires
 - event start/end time -> `datetime`
 - price/amount/rating/order/count -> `number`

package/assets/skills/fimo-migration/references/frameworks/nextjs.md

@@ -86,6 +86,13 @@ behavior in place; when one cannot be preserved, record an explicit gap with
 the affected routes instead of shipping pages that silently lost their share
 metadata.
 
+Before adopting Fimo SEO values, load the target's `fimo-code` reference
+`frameworks/next/seo`. Record which fields remain app-owned and which become
+editor-managed. Preserve section robots policies, title templates and
+file-based images; verify the rendered result on representative routes. Link
+the established route pattern in the project's instructions so later pages
+reuse it. Do not replace an existing SEO library or add a universal merge wrapper.
+
 ## Fimo connection
 
 Follow the target project's `fimo-code` Next.js reference and render its

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

@@ -9,18 +9,16 @@ assets, schemas, entries, and forms, or the gaps are owner-visible unresolved
 items.
 
 Every data-plane write in this contract targets the linked project from
-workflow Phase 0. Local artifacts never require the link — `fimo migrate
-import` only prints the import plan (it writes no data) and warns in an
-unlinked directory — running the printed commands is what needs the link.
-When no owner-supplied target exists, the writes stay unresolved owner
-actions; do not fake a link to make them pass.
+workflow Phase 0. Planning and payload authoring need no link; running the
+writes does. When no owner-supplied target exists, the writes stay unresolved
+owner actions; do not fake a link to make them pass.
 
 ## Media Files
 
 Discovery must include:
 
 - local export media folders
-- media URLs from crawled HTML/CSS
+- media URLs found in the source HTML/CSS
 - CMS media fields
 - SEO/share images
 - downloadable files linked from pages or entries

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

@@ -4,9 +4,10 @@ New migrations do not create a canonical `manifest.json`. The coordinator uses
 the readable `.fimo/migration/migration-plan.md` and
 `.fimo/migration/migration-report.md` instead.
 
-Older URL-only migrations may contain `.fimo/migrations/current/manifest.json`.
-Read it as source evidence when useful, but do not copy it into another
-registry or ask workers to keep it synchronized.
+A pre-existing project may still contain `.fimo/migrations/current/manifest.json`
+from a retired URL crawl. Nothing writes it any more, and it was never
+trustworthy on a client-rendered site: read it as a hint at most, re-verify
+every claim against the source, and do not copy it into another registry.
 
 JSON remains appropriate for actual Fimo artifacts: schema files and the
 content payloads passed to data-plane commands. It is not needed to describe

package/assets/skills/fimo-migration/references/questions-and-improvements.md

@@ -94,7 +94,7 @@ The question should sound like this:
 
 If the owner chooses the public website, stay inside the selected route scope.
 Public retrieval does not authorize private endpoint discovery, credential use,
-or a broader crawl. Record the URL, retrieval time, redirects, and every field
+or a broader sweep. Record the URL, retrieval time, redirects, and every field
 or relation that remains unknown.
 
 ## Ask what happens outside a partial migration

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

@@ -18,12 +18,11 @@ ask a generic optimization question.
 1. Confirm the target path. The target is a separate directory; the source
    checkout remains read-only evidence.
 2. Initialize or reuse exactly one linked Fimo target before workers start:
-   - URL migration: `fimo migrate init <source-url> <target-dir> --framework <framework>`
    - link an existing project: `fimo migrate init <target-dir> --project-id <projectId> --framework <framework>`
    - create a project: `fimo migrate init <target-dir> --org <organizationId> --framework <framework>`
    - add `--source-platform <platform>` when the source platform is known
      (webflow, framer, squarespace, wix, carrd, wordpress, nextjs, astro,
-     react-router, other); URL crawls detect it themselves.
+     react-router, other). Nothing detects it; omitting it records `unknown`.
      Use the detected source framework for source-backed migrations. A framework
      conversion requires an explicit user choice; URL-only and rebuild
      migrations ask the user which framework to use. Never choose a framework by
@@ -78,9 +77,12 @@ Treat absent/private fields as unknown, keep uncertain fields optional, and do
 not turn sampled values into enums. Bounded retrieval scripts are accelerators
 the planner may adapt or replace, never schema decision makers.
 
-For URL-only migrations, run `fimo migrate <url> [dir]` and inspect the
-generated `.fimo/migrations/current/` files as source evidence. Do not copy
-that crawl manifest into another canonical JSON registry.
+For URL-only migrations, read the published site yourself with a browser. Open
+every selected route, let client-side rendering finish, and record the sections,
+copy, images, links, and forms you actually see. An HTML response fetched
+without executing JavaScript is not evidence: a client-rendered page returns an
+empty root element, and treating that as the page reports an empty site as a
+complete one.
 
 ## Phase 2: Fan out workers
 

package/dist/cli/bundle.json

@@ -1,7 +1,7 @@
 {
   "bundled": true,
   "bundler": "esbuild",
-  "bundledAt": "2026-09-04T18:04:09.580Z",
+  "bundledAt": "2026-09-05T10:27:58.561Z",
   "cliVersion": "2.3.2",
   "external": [
     "oxc-parser",