fimo 0.8.0 → 0.9.0-experimental.10

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

@@ -67,7 +67,7 @@ Use `connect` for provider accounts, workspaces, OAuth installs, and API-key acc
 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 scrape --url https://example.com --connection client-b
-fimo integrations run firecrawl search --query "Example Domain" --max-results 3
+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
@@ -76,6 +76,10 @@ fimo integrations run firecrawl monitor.list
 
 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`.
 
+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.
+
 Use `--connection <alias>` only for one run when a named connection already exists. It does not change the project default
 integration setup.
 

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

@@ -0,0 +1,162 @@
+# Outbound webhooks
+
+> **Run via `npx fimo@latest <command>`** so the event catalog and delivery commands match the platform.
+
+> **Beta:** Test each destination and inspect its delivery history before depending on it in production.
+
+Use `fimo webhooks` to send project events to external HTTPS endpoints. The CLI and Studio edit the same project-wide configurations and delivery history. The CLI has no provider presets: inspect the destination's API documentation, then pass its URL, headers, and JSON body explicitly.
+
+Webhook commands require Full Access to the project. Do not attempt them when the current CLI identity has Edit, Comment, View, or agent access; the API enforces the same permission boundary as Studio.
+
+## Start from the live event catalog
+
+```bash
+fimo webhooks events
+fimo webhooks events form.submitted
+```
+
+Run this before writing a custom payload. The list shows supported event types, descriptions, and valid
+`event.data...` template variables. Pass one event name to get its example payload too. The initial families are:
+
+- Forms: `form.submitted`
+- Publish: `publish.started`, `publish.succeeded`, `publish.failed`, `publish.unpublished`
+- Agents: run started/completed/failed/cancelled and review requested/resolved
+- Analytics: `analytics.report_ready`
+- Media: uploaded/updated/deleted/generated/processing_failed
+- Entries: `entry.changed`
+
+Do not guess variable paths. The common envelope is:
+
+```json
+{
+  "id": "event-id",
+  "type": "form.submitted",
+  "version": 1,
+  "test": false,
+  "createdAt": "2026-07-17T10:00:00.000Z",
+  "project": { "id": "project-id" },
+  "env": { "name": "main" },
+  "data": {}
+}
+```
+
+Omit `--body` to send this full envelope. Prefer that default when the receiver can accept Fimo's shape.
+
+## Create a provider-specific request
+
+Store credentials as project secrets, never literal header flags:
+
+```bash
+printf '%s' "$RESEND_API_KEY" | fimo secrets set RESEND_API_KEY --stdin
+
+fimo webhooks create waitlist-resend \
+  --event form.submitted \
+  --form waitlist \
+  --url https://api.resend.com/contacts \
+  --header "Authorization=bearer:RESEND_API_KEY" \
+  --body '{"email":"{{ event.data.submission.data.email }}"}'
+```
+
+Header sources:
+
+- `Name=secret:KEY`: secret is the complete value
+- `Name=bearer:KEY`: `Bearer ` plus the secret
+- `Name=token:KEY`: `token ` plus the secret
+- `Name=literal:value`: non-secret fixed value
+
+Secret-backed values resolve when a delivery runs, so rotating a project secret updates later deliveries without editing the webhook. Fimo masks destination URLs, credentials, payload secrets, and response excerpts in CLI and Studio output.
+
+## Shape custom JSON safely
+
+`--body` accepts JSON with exact `{{ event... }}` substitutions in values:
+
+```bash
+fimo webhooks create publish-slack \
+  --event publish.succeeded \
+  --url https://hooks.slack.com/services/... \
+  --body '{"text":"Published {{ event.data.publication.url }}"}'
+```
+
+Use `--body @path/to/payload.json` for a file or `--body -` for stdin. Paths resolve from `-C` or the current
+project directory.
+
+When a variable occupies the entire JSON value, objects and arrays retain their JSON type:
+
+```json
+{
+  "submission": "{{ event.data.submission }}",
+  "email": "{{ event.data.submission.data.email }}"
+}
+```
+
+Do not add executable transform scripts or workers to a project just to reshape a payload. Use the JSON template for deterministic mappings; use an external workflow endpoint only when the integration genuinely needs branching or code.
+
+Available filters are event-specific:
+
+- `--environments <main|all>` for the event origin; the default is `main`
+- `--form <id>` for `form.submitted`
+- `--agent <name>` for agent events
+- `--media-type <image|video|audio|document|other>` for media events
+- `--action <created|updated|deleted>`, `--content-type <name>`, and `--locale <locale>` for `entry.changed`
+- `--debounce-changes <immediate|5s|30s|1m>` for direct `entry.changed` delivery grouping
+
+`entry.changed` represents content accepted in the selected environments. New entry webhooks wait 5 seconds after the last direct edit by default, then send one delivery with the combined `data.changes`. Exact repeated autosave changes appear once. Use `--debounce-changes immediate` to disable grouping. Accepted agent edits and environment merges already carry compact batches and send immediately. Operations above the delivery batch size share an `operationId` and include `{ index, total }` batch metadata. Every event includes its origin at `event.env.name`.
+
+## Inspect before depending on it
+
+```bash
+fimo webhooks list
+fimo webhooks get <webhook-id>
+fimo webhooks test <webhook-id> --wait
+fimo webhooks deliveries <webhook-id> --limit 20
+fimo webhooks delivery <webhook-id> <delivery-id>
+```
+
+`test` uses the selected event's documented example data and adds `X-Fimo-Test: true`. `--wait` waits up to 60
+seconds for success or failure. Pass `--data '{...}'` only when a specific shape needs testing.
+
+Fimo automatically retries temporary failures with backoff. After retries are exhausted:
+
+```bash
+fimo webhooks retry <webhook-id> <delivery-id>
+```
+
+Use the delivery error code and attempt history to distinguish destination errors, timeouts, missing secrets, invalid templates, and blocked unsafe URLs. A delivery accepts up to five manual retries.
+
+## Manage configurations
+
+```bash
+fimo webhooks update <webhook-id> --enabled off
+fimo webhooks update <webhook-id> --url https://example.com/hooks/fimo
+fimo webhooks update <webhook-id> --default-body
+fimo webhooks delete <webhook-id>
+```
+
+Webhooks belong to the project, with up to 20 configurations per project. The same configuration is visible from every environment. Delivery listens to `main` by default. Use `--environments all` to include branch activity, or `--environments main` to return to main-only delivery.
+
+## Verify Fimo signatures
+
+Signing is on by default. Save the signing secret shown once at creation. Fimo sends:
+
+- `X-Fimo-Delivery`: stable delivery ID
+- `X-Fimo-Event`: event type
+- `X-Fimo-Event-Id`: stable event ID for receiver deduplication
+- `X-Fimo-Test`: `true` for synthetic test deliveries
+- `X-Fimo-Timestamp`: Unix timestamp for the attempt
+- `X-Fimo-Signature`: `v1=` plus HMAC-SHA256 of `<timestamp>.<raw-request-body>`
+
+At the receiver, reject stale timestamps and compare the computed signature with a timing-safe comparison before parsing or acting on the payload. Rotate an exposed signing secret with:
+
+```bash
+fimo webhooks rotate-secret <webhook-id>
+```
+
+Save the returned value immediately; it is not shown again.
+
+## Guardrails
+
+- Destinations must use public HTTPS URLs in production. Local/private/link-local addresses and redirects are blocked.
+- Do not place access tokens in URLs, literal headers, payload templates, logs, or committed files.
+- Do not retry a pending or actively retrying delivery manually.
+- Do not assume a successful queue operation means the destination accepted the request; inspect the delivery result.
+- Use `--json` when another agent or script needs stable, parseable output.

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

@@ -17,7 +17,10 @@ exports, source repositories, CMS exports, media folders, or any hybrid of those
 It owns intake, source inventory, URL crawl bootstrapping, ledger normalization,
 imports, and QA so any LLM can run the work without silently dropping content.
 
-> Run every `fimo` command as `npx fimo@latest <command>` — always the latest CLI, no global install.
+> Run every `fimo` command as `npx fimo <command>` when the project declares a
+> `fimo` dependency (adopted/wrapped projects pin an exact version tied to their
+> backend — never override it with `@latest`). Only fall back to
+> `npx fimo@latest` when the project has no `fimo` dependency.
 
 ## Non-Negotiables
 
@@ -30,6 +33,13 @@ imports, and QA so any LLM can run the work without silently dropping content.
   ledger.
 - Source exports beat inferred crawls. If CSV/XML/JSON exports, media folders, or
   source code exist, treat the public URL as visual/SEO reference only.
+- A working JS codebase is wrapped, not rewritten. Wrap mode
+  (`references/wrap.md`) keeps the user's routing, styling, and components
+  untouched; the diff is wiring + wrappers + config only. As the coding
+  agent you own the whole wrap loop — run `npx fimo migrate` yourself and
+  follow `references/wrap.md` § W0 (relay the recorded data-source
+  decisions to the user, then loop `npx fimo migrate wrap --check` to
+  exit 0).
 - Builder HTML is evidence, not the final runtime. Rebuild with Fimo conventions,
   schemas, forms, media primitives, translations, and routes.
 - Do not report completion until the QA gate passes or every failed check is
@@ -59,7 +69,15 @@ imports, and QA so any LLM can run the work without silently dropping content.
      pack.
    - **hybrid**: source files plus public URL. Use source-backed as truth and URL
      for route, SEO, visual, and behavior comparison.
-4. Create or update the canonical ledger described in
+4. Pick the mode:
+   - **wrap** (default for a source-backed, working JS codebase — Next.js,
+     Vite/React, React Router): keep the user's stack, adopt the repo with
+     `fimo init`, and make content editable by wrapping it in place. Never
+     rewrite routing, styling, or components. Follow `references/wrap.md`.
+   - **rebuild**: url-only sources, builder exports/HTML dumps, non-JS
+     backends, or codebases that do not build. Follow the standard workflow
+     phases.
+5. Create or update the canonical ledger described in
    `references/manifest.md`.
 
 ## Workflow
@@ -96,7 +114,11 @@ node <this-skill>/scripts/write-migration-report.mjs <project-root>
 ## References
 
 - `references/workflow.md` - full decision tree and phase order.
+- `references/wrap.md` - wrap mode: adopt a working JS codebase and wrap its
+  content in place (default for source-backed JS sites).
 - `references/manifest.md` - canonical migration ledger schema.
+- `references/pages.md` - the page registry (templates, schema bindings,
+  instances), Studio preview navigation, and the opt-in per-page SEO recipes.
 - `references/content.md` - CMS, entries, references, and source value rules.
 - `references/media.md` - media inventory, upload, dedupe, and replacement rules.
 - `references/forms.md` - form classification and Fimo replacement rules.

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

@@ -18,6 +18,14 @@ ways:
    news teasers, and feature lists are almost always collections even when the
    source renders them inside one page.
 
+> **Rebuild path only.** These rules apply when Fimo re-authors the site
+> (URL/export migrations): the rebuilt code is disposable, so content belongs
+> in collections aggressively. **Wrap mode is deliberately stricter** — the
+> user's code stays primary, page furniture and nav stay in code with `t()`
+> labels, and every collection candidate is confirmed with the user first.
+> See `wrap.md` (W0 and the generated agent-prompt) — in wrap mode that
+> guidance overrides this section.
+
 After the source-faithful rebuild, treat **any hardcoded array of 3+ items with
 the same shape** as a collection candidate. Do not leave it hardcoded.
 
@@ -97,3 +105,19 @@ Skipped fields or entries require a manifest note with:
 - reason
 - owner impact
 - suggested action
+
+## Scaffolded CMS — verify pages render
+
+When `fimo migrate --scaffold-cms` wires the site to Fimo, the machine does the
+deterministic work: it maps the CMS's components and dynamic zones to editable
+Fimo blocks, seeds every block with generic example content in the shape the
+components expect, and swaps the client's fetch for the generated Fimo adapter —
+so the whole site reads from Fimo with no per-view wiring.
+
+The last mile is yours and it is per-site. Open the main pages in `pnpm dev` (a
+list, a detail, the page-builder home) and confirm each renders. Every renderer is
+the site's own code, so a component may read a field the generic content did not
+fill, or expect a slightly different shape. Where a section renders blank or
+throws, fix it at that component — a defensive default, or the field it truly
+needs — and re-check. Record anything you cannot resolve as a caveat. Do not
+re-scaffold, re-wire, or hand-wrap content; the machine owns those.

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

@@ -34,6 +34,7 @@ follow-up agents, and import/QA checks.
   "seo": [],
   "unsupported": [],
   "unresolved": [],
+  "wrap": null,
   "qa": {
     "status": "not-run|passed|failed|passed-with-unresolved",
     "checks": []
@@ -41,6 +42,51 @@ follow-up agents, and import/QA checks.
 }
 ```
 
+## Wrap Block (wrap mode only)
+
+When the migration is a wrap (see `references/wrap.md`), set
+`source.mode: "source-backed"` and fill the `wrap` block; leave it `null` for
+rebuild migrations:
+
+```json
+{
+  "wrap": {
+    "mode": "wrap",
+    "framework": "next|react-router|vite",
+    "adopted": true,
+    "wired": true,
+    "coverage": {
+      "wrappable": 0,
+      "wrapped": 25,
+      "ignored": 0,
+      "unresolvedItems": 0
+    },
+    "seeded": {
+      "labels": 21,
+      "wrappedMedia": 3,
+      "wrappedRichText": 1
+    },
+    "seo": { "decision": "external", "decidedBy": "default" },
+    "planPath": ".fimo/migration/plan.json"
+  }
+}
+```
+
+`wrap.seo` records who owns the site's SEO metadata — a USER decision, like
+`wrap.dataSources`: `decision` is `"fimo"` (Fimo manages per-page SEO,
+editable in the Studio) or `"external"` (the code / an external SEO tool
+keeps ownership — the DEFAULT, nothing is ever wired on it). `decidedBy` is
+`"default"` until the user actually answered; relay defaulted records and
+rewrite them with `decidedBy: "user"`. Page bindings themselves live in the
+page registry (`fimo-config.json#routes` →
+`params: { "<param>": { "schema", "queryField", "displayField" } }`), not in
+the manifest — see `references/pages.md`.
+
+`coverage` mirrors the final `fimo migrate wrap --check` output: `wrappable`
+must be 0 (or fully accounted for by `ignored` + `unresolvedItems`, each with a
+ledger entry). `seeded` counts must match what `fimo labels list` /
+`fimo entries list` report — fallback-only content is not seeded.
+
 ## Required Item Fields
 
 Every route, content type, entry batch, media asset, form, redirect, locale, SEO

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

@@ -0,0 +1,234 @@
+# Pages — the page registry, Preview navigation, and opt-in SEO
+
+A **Page** is a navigable URL surface of the site, in two forms:
+
+- **Page template** — what the app's routing declares: `/pricing` (static),
+  `/blog/:slug` (dynamic). The app's CODE is the source of truth for page
+  structure; `fimo migrate` discovers templates per framework and reconciles
+  them into the registry, `fimo-config.json#routes` (manual entries are
+  preserved). Param syntax is ALWAYS `:param` / catch-all `:param*` — never
+  `[param]`.
+- **Page instance** — a concrete page: template × content entry
+  (`/blog/:slug` × `hello-world`). Instances are NEVER stored; they derive
+  from entries through the template's binding, so they cannot drift.
+
+The registry entry shape:
+
+```json
+"blog-post": {
+  "label": "Blog post",
+  "path": "/blog/:slug",
+  "params": { "slug": { "schema": "BlogPost", "queryField": "slug", "displayField": "title" } },
+  "seo": { "title": "{{blog-post.title}} — {{siteName}}" }
+}
+```
+
+- `params[<param>]` is the **binding**: the schema whose entries materialize
+  the instances. `queryField` = the entry field substituted into the URL
+  (entry `slug` metadata always qualifies); `displayField` = the label the
+  Studio's page picker shows.
+- The Studio preview navigates ONLY what the registry describes: static pages
+  as-is, dynamic pages once bound. An unbound dynamic page navigates to a
+  literal `/blog/:slug` URL — broken by definition.
+- Locale params (`:locale`, `:lang`) are never schema-bound; tooling
+  substitutes the project's default locale. (Studio locale switching for
+  dynamic pages is a platform follow-up, not your problem.)
+
+## Completing the bindings (agent workflow)
+
+`fimo migrate` writes strong-evidence bindings itself (a rewired parent list
+page; a wired CMS with a single page-builder type) and lists candidates +
+unbound pages in the generated prompt. Your job:
+
+1. `npx fimo pages list` — see every template and its status
+   (`static | dynamic:bound | dynamic:unbound`).
+2. For each candidate/unbound page, find the schema whose entries the page
+   renders (read the page component's fetch). Apply with
+   `npx fimo pages set <id> --params '{"<param>":{"schema":"<Type>","queryField":"slug","displayField":"<field>"}}'`
+   — it validates the schema and both fields against the server. Never
+   hand-edit the JSON. If drafts are not adopted yet, run
+   `schemas adopt-drafts` FIRST and bind with the FINAL names.
+3. Add pages the scanner missed (SPA relative/wildcard routes):
+   `npx fimo pages set <id> --path /the/path --label "Label"`.
+   Never repeat the folder/category in the label: the `/features/agents` page
+   is labeled "Agents", NOT "Feature: Agents" — the Studio tree already nests
+   it under Features.
+   Labels must read like a human wrote them: acronyms uppercase ("Agentic
+   CMS", "AI Stack", "SEO GEO" — never "Agentic Cms"), no two sibling pages
+   with the same name (a bound template is named after its schema — "Blog
+   Post" next to the "Blog" index; the machine does this when it binds, fix
+   any leftover with `--label`).
+   When the site's NAV groups flat pages editorially (a "Resources" menu over
+   /for-developers, /for-founders…), mirror it with
+   `npx fimo pages set <id> --group "Resources"` — the Studio Pages tree
+   folds them under that group even without a shared URL segment.
+4. Map each page to its label keys when they diverge. The Studio shows a
+   page's labels by key prefix, defaulting to `<pageId>.` — but wrapped keys
+   derive from FILE names (`AiCms.tsx` → `ai-cms.*`) or data files
+   (`personas.*`), which can differ from the URL-derived page id
+   (`agentic-cms`). A page whose Studio view is EMPTY almost always means
+   this mismatch. `fimo migrate` PREFILLS `labelPrefixes` wherever it can
+   prove the join (a staged key appears verbatim in the route's component
+   file) and the prompt § Routes & pages lists every UNCLAIMED prefix left.
+   Your job: place each unclaimed prefix — claim it with
+   `npx fimo pages set <id> --label-prefix "<prefix>"` (comma-separated for
+   several; claims MERGE into the existing list so machine-prefilled
+   prefixes survive, `""` clears the whole list) when one page renders those keys, or leave it
+   deliberately when it is shared (chrome, multi-page data files) and say so
+   in your report. No prefix may end up merely forgotten.
+5. Give each page the Lucide icon that best matches its CONTENT:
+   `npx fimo pages set <id> --icon <kebab-name>` (pricing → `tag`, blog →
+   `newspaper`, contact → `mail`, legal pages → `scale`, team/about →
+   `users`, docs → `book-open`). Read the page component to judge. Use
+   well-known Lucide names only — an unknown name silently falls back to
+   the default file icon in the Studio. Skip the flag when nothing clearly
+   fits.
+6. Verify: `npx fimo pages list --expand` materializes every instance —
+   each page the site's nav links to must appear as a real URL.
+
+## Shared chrome → Single Types (the content-model rule)
+
+A site's content model must read like a CMS, not like an implementation:
+
+- **Chrome** (header, footer, nav, menus, banners) is edited as ONE thing →
+  a SINGLE TYPE per piece (`src/schemas/<Name>.json` with
+  `"isSingleton": true`, real fields mirroring the source: nav items as an
+  array/blocks field, logo as media), pushed with `npx fimo schemas push`,
+  its ONE document written from the source values with
+  `npx fimo documents set <Name> --body '<json>'` (singletons REJECT the
+  entries endpoints), component rewired to read it. Never a loose label
+  pile, never a collection.
+- **Page-scoped structure** (a pricing page's FAQ list) → a component array
+  on that page's Single, or a collection + reference when genuinely reused
+  across pages. Never an orphan collection nobody can situate. CLAIM the
+  single on its page (`npx fimo pages set pricing --single Pricing`) — it
+  then edits inline in the page's Studio view and leaves the Singles tab.
+- **Real repeating content** (blog posts, team members) → a collection, with
+  HUMAN slugs derived from the display field (never `faq-item-<hash>`), and
+  schema field order matching reading order (question before answer).
+- **A page's SECTIONS are its Single's nested blocks.** A marketing page is
+  a sequence of sections (hero, logo strip, features grid with grouped
+  cards, testimonials, integrations, stats, FAQ) — model the page as ONE
+  Single whose fields are nested block components mirroring that structure
+  (blocks nest: a `features` field holds groups, each group holds cards).
+  Section card lists are NEVER "page furniture" exemptions when they carry
+  real copy — an exemption hides marketing content from the editor, which
+  is a failed migration for that section. Claim the Single on its page.
+  **The machine BUILDS this model for you**: `fimo migrate` writes, per
+  multi-section page, an analysis draft (`.fimo/migration/page-drafts/`,
+  regenerate with `npx fimo pages draft`) AND a ready page Single
+  (`.fimo/migration/page-singles/<Uid>.json` — singleton schema + document
+  filled with the staged label values and the source block rows). Sections
+  flagged `"shared": true` render on several pages — that is chrome: model
+  each once as a Single Type, never as a per-page block. The `wrap --check`
+  Content-model gate fails while a built Single is neither claimed
+  (`pages set <id> --single <Uid>`) nor recorded under
+  `wrap.modelDeviations` (`{"page": "<id>", "reason": "…"}`) — a reason the
+  user would accept; "faster as labels" is not one. Your work per page:
+  rename machine field keys to editorial names, push, `documents set`,
+  rewire the reads with source fallback, claim.
+
+  **Worked real example** (the Fimo homepage, the model the user ratified):
+  the page renders hero → logo strip → features grid (3 groups, each with
+  cards) → testimonials → integrations → stats bar → FAQ. Its Single:
+
+  ```json
+  {
+    "uid": "Home",
+    "isSingleton": true,
+    "fields": {
+      "builtOnTheBest": {
+        "type": "blocks",
+        "schema": { "fields": { "name": { "type": "string" }, "domain": { "type": "string" } } }
+      },
+      "features": {
+        "type": "blocks",
+        "schema": {
+          "fields": {
+            "title": { "type": "string" },
+            "subtitle": { "type": "string" },
+            "cards": {
+              "type": "blocks",
+              "schema": { "fields": { "title": { "type": "string" }, "description": { "type": "text" } } }
+            }
+          }
+        }
+      },
+      "testimonials": {
+        "type": "blocks",
+        "schema": {
+          "fields": {
+            "quote": { "type": "text" },
+            "metricValue": { "type": "string" },
+            "metricLabel": { "type": "string" },
+            "author": { "type": "string" },
+            "role": { "type": "string" }
+          }
+        }
+      },
+      "ecosystem": {
+        "type": "blocks",
+        "max": 1,
+        "schema": {
+          "fields": {
+            "title": { "type": "string" },
+            "stats": { "type": "blocks", "schema": { "fields": { "label": { "type": "string" } } } }
+          }
+        }
+      },
+      "faqs": { "type": "blocks", "schema": { "fields": { "q": { "type": "string" }, "a": { "type": "text" } } } }
+    }
+  }
+  ```
+
+  Note what made it right: block names are the on-page section titles
+  ("Built on top of the best" → `builtOnTheBest`), field names are ROLES
+  (`title`, `quote`, `author`) never copy slugs, a logo strip carries its
+  ITEMS (not just its heading), computed live values (stat numbers) stay in
+  code, and the whole thing was claimed on the page. Smart deviations were
+  reported, not silent.
+
+- **Plumbing** (`WrappedRichText`, `WrappedMedia`) is storage — the Studio
+  hides it from Collections and shows the entries under their pages; never
+  present it as content in your report.
+
+## SEO — a USER decision, never wired by default
+
+Who owns SEO metadata is recorded in `.fimo/migration/manifest.json` →
+`wrap.seo` (`{ "decision": "fimo" | "external", "decidedBy": "user" | "default" }`).
+The default is ALWAYS `external` (nothing touched — the site's code or an
+external SEO tool keeps ownership). When the prompt shows the decision as
+DEFAULTED, relay it to the user once; only an explicit user "fimo" unlocks
+wiring. Never migrate, edit, or inject metadata on the default.
+
+When the user opted into Fimo-managed SEO, the engine is the neutral
+`fimo/seo` export — pure resolution over the registry, no framework coupling:
+
+```ts
+import { getFimoSeoForPath } from 'fimo/seo';
+const seo = getFimoSeoForPath(pathname, { routeData: { 'blog-post': entry } });
+// seo.title / seo.description / seo.image / seo.robots …
+```
+
+Per-framework injection (map the resolved values to the framework's head API):
+
+- **Next (app router)** — in the layout or page, `generateMetadata()` calls
+  `getFimoSeoForPath` with the resolved pathname (+ the entry as `routeData`
+  on dynamic pages) and returns `{ title, description, openGraph: {...} }`.
+- **React Router** — already shipped: `loadFimoMetaData` / `buildFimoMeta` /
+  `fimoHtmlProps` from `fimo/react-router`.
+- **Astro** — a head partial calling `getFimoSeoForPath(Astro.url.pathname)`
+  server-side and rendering the `<meta>` tags.
+- **Nuxt** — `useSeoMeta()` fed from a server util wrapping `getFimoSeoForPath`.
+- **SvelteKit** — resolve in `+layout.server` load, render in the root
+  layout's `<svelte:head>`.
+
+Route-level `seo` blocks support `{{variables}}` resolved against
+`routeData` — per-INSTANCE metadata from one template.
+
+## Sitemap / robots
+
+Once bindings exist, `getFimoPaths` (from `fimo/paths`) materializes the full
+instance list for prerender/sitemap use. It reads the API base URL from
+`VITE_API_URL` (a plain env var or `.env` line works outside Vite). The
+`fimo pages list --expand` output is the same list, CLI-side.

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

@@ -18,8 +18,11 @@ Run this gate before reporting completion.
 ## Behavior
 
 - Dependencies are installed in the target project.
-- The project builds successfully.
-- Local dev starts without Vite loader/schema/form generation errors.
+- The project builds successfully **with its own toolchain** (`next build`,
+  `vite build`, …) — wrapped sites are not Vite/React-Router projects; never
+  assume Fimo-template tooling.
+- Local dev starts without loader/schema/form generation errors (Vite errors
+  apply to rebuild-mode projects only).
 - Primary routes render without console/runtime errors.
 - Collection listing/detail pages work with imported data, seed data, or explicit
   empty states.
@@ -33,6 +36,25 @@ Run this gate before reporting completion.
 - Remove generated placeholder copy from visible UI.
 - Verify media aspect ratios and no broken images on primary routes.
 
+## Wrap Mode (additional blocking checks)
+
+When the manifest says `mode: "wrap"`:
+
+- `fimo migrate wrap --check` exits zero — it enforces coverage (zero
+  unwrapped items), render parity (rendered text/marks/media/links identical
+  to the pre-wrap baseline), and seeding (every wrapped key exists in the
+  database) — or every remaining item is an explicit ignored/unresolved
+  ledger entry with a reason.
+- Labels are seeded: every `FimoText`/`t()` key exists in `fimo labels list`
+  with the original string. Fallback-only content fails the gate.
+- Wrapped media/rich text have their `WrappedMedia`/`WrappedRichText` entries
+  created and assets uploaded.
+- Render parity: pages render identically to pre-migration — same text, same
+  formatting marks (bold/italic/underline/links), same media.
+- Diff audit: the migration diff contains only wiring, wrappers, label calls,
+  config, and dependency changes. Any routing/styling/component rewrite fails
+  the gate.
+
 ## Import Verification
 
 Record:

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

@@ -2,6 +2,14 @@
 
 Use this as the phase contract for complete migrations.
 
+> **Mode fork.** For a source-backed, WORKING JS codebase (Next.js, Vite/React,
+> React Router), wrap mode is the default: skip Phases 0 and 6 below and follow
+> `references/wrap.md` (adopt via `fimo init`, scan via `fimo migrate wrap`,
+> wrap in place, seed, verify). Phases 3–5 (content model, media/forms, import)
+> and Phase 8 (QA + report) still apply — wrap changes how content becomes
+> editable, not the accounting obligations. Everything else here is the rebuild
+> path.
+
 ## Phase 0: Target Safety
 
 1. Confirm the target path.
@@ -119,7 +127,10 @@ Required order:
 Record target IDs, import counts, failures, and unresolved items in the
 canonical ledger. Generated JSON without import counts is still draft state.
 
-## Phase 6: Fimo Implementation
+## Phase 6: Fimo Implementation (rebuild mode)
+
+In wrap mode this phase is replaced by `references/wrap.md` phases W3–W5
+(wire, wrap, seed); do not rebuild pages for a wrapped site.
 
 Implement routes, schemas, forms, entries, media, redirects, translations, and
 React pages with Fimo conventions.