fimo 2.6.0-staging.1 → 2.6.0-staging.3

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

@@ -44,7 +44,7 @@ A Fimo project is identified by `.fimo/project.json`, written by `fimo init`. Th
 
 ## Critical: commands target the Branch matching the current git branch
 
-A project can have multiple **Branches** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Project-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the Branch matching the **current git branch**, and print a one-line banner saying which one. New projects start on `main`. Override for a single command with the canonical `--branch <name>` flag; the removed `--env <name>` spelling is rejected. Never edit the link file to switch. The full git-shaped workflow (`branch` / `checkout` / `switch` / `pull` / `diff` / `merge` / `status` / `publish`) lives in `references/branches.md`.
+A project can have multiple **Branches** — each is a git branch _plus_ its own DB, sandbox, preview, and assets. Project-scoped commands (`deploy`, `status`, `entries`, `diff`, …) operate on the Branch matching the **current git branch**, and print a one-line banner saying which one. Analytics reads are the exception: they default to canonical `prod`, independent of the checkout; see `references/analytics.md`. Annotation writes keep the current or explicit Branch. New projects start on `main`. Override for a single command with the canonical `--branch <name>` flag; the removed `--env <name>` spelling is rejected. Never edit the link file to switch. The full git-shaped workflow (`branch` / `checkout` / `switch` / `pull` / `diff` / `merge` / `status` / `publish`) lives in `references/branches.md`.
 
 ## Quick Start
 

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

@@ -4,6 +4,19 @@ Pageview aggregates for the **published** site are stored in Fimo's analytics pi
 
 Analytics has a **retained preview for every org** — free included. The free default is a 7-day retention window, so short ranges (`today`, `yesterday`, `this_week`, `last_week`, `last_7_days`) work for everyone. **Extended date ranges and longer retention are paid** — `last_30_days`, `last_90_days`, `this_month`, `last_month`, `last_quarter`, `last_year`, and `custom` require the `canUseExtendedDateRanges` privilege, which only paid orgs have. Asking for an extended range as a free user returns a 403 with an upgrade hint.
 
+## Select published traffic
+
+For traffic, growth, or site-performance questions, read **`prod`**, regardless of the current Git branch, `FIMO_ENV`, or the source branch published to Production. Analytics reads (`pageviews`, `top`, `annotations list`) default to this canonical published target. On older CLI versions, select it explicitly:
+
+```bash
+fimo --branch prod analytics pageviews --days 7 --json
+fimo --branch prod analytics top countries --json
+```
+
+Structured read results include `branch` (`data.branch` in the CLI JSON envelope). Check it before interpreting metrics. An intentional `--branch <name>` overrides the default; zero traffic on `main` or a preview branch does **not** mean the published site has no traffic. Preview visits are not collected. If publication or access is unavailable, report that limitation; do not fall back to another branch or present the failure as zero traffic.
+
+SDK and hosted MCP reads also default omitted `branch` to `prod` and return the selected `branch`. Annotation **writes** keep the current/explicit Branch and its existing permissions; the read default does not grant permission to write to `prod`.
+
 ## Bot traffic is excluded
 
 Every number below is **humans only**. Bot hits — AI crawlers and headless browsers — are tagged
@@ -37,6 +50,7 @@ The headline command returns everything in one payload — KPIs, the visitors se
 
 ```json
 {
+  "branch": "prod",
   "range": { "preset": "last_30_days", "effectiveFrom": "...", "effectiveTo": "...", "groupBy": "day", ... },
   "deviceFilter": null,
   "visitors": 1240, "pageviews": 3870, "bounceRate": 42.5, "viewsPerVisit": 3.12, "averageVisitDurationSeconds": 95.4,

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

@@ -71,7 +71,7 @@ fimo entries create <TypeName> --body '<json>'
 fimo entries create <TypeName> --locale es --document-id <documentId> --body '<json>'
 fimo entries list <TypeName> [--limit N] [--cursor CURSOR] [--all-pages] [--search Q] [--where JSON] [--sort F] [--fields FIELDS] [--populate FIELDS]
 fimo entries list <TypeName> --locale es
-fimo entries get <TypeName> <id> [--locale es]
+fimo entries get <TypeName> <id> [--locale es] [--populate FIELDS]
 fimo entries update <TypeName> <id> [--locale es] --body '<json>'
 fimo entries delete <TypeName> <id> [--locale es]
 fimo entries query (--sql '<select>' | --file <path> | --stdin)
@@ -101,7 +101,7 @@ Use the canonical read query flags: `--search`, `--sort`, `--where`, `--limit`,
 Reference filters take the target `id` string (`{"author":"750e..."}`). On a to-many field, `$eq` and `$contains` mean membership, `$in` means any listed target is present, `$ne` and `$nin` mean none are present, and `$null: true` means empty or missing. Reference fields cannot be sorted; use `--sort field` / `--sort -field` on scalar fields.
 `--fields` is a comma-separated projection for list payloads. The API always keeps `id`, `entryId`, `documentId`, and `locale`; pass only the other fields your view needs, such as `slug,title,excerpt,coverImage`.
 
-`--populate` is a comma-separated list of reference fields to embed. Without it, reference fields return reference objects like `{ "id": "..." }`; with `--populate author,contributors`, those fields return the target entry objects for the requested locale. Only reference fields can be populated (scalar fields 400), and populate never selects which target fields come back. A populated target missing in the requested locale resolves to null unless you pass `localeFallbacks=true`, which falls back to the best available locale variant, marked by its `locale` field. Limits: 200 references per to-many write, 500 distinct populated documents per field per request (400 past either).
+`--populate` is a comma-separated list of top-level fields to embed, on `entries list`, `entries get`, and `singles get`. It accepts reference fields, media fields, and blocks fields that contain media; naming a blocks field populates every media value inside it. Nested paths such as `sections.image` are not supported, and other field types return 400. Run `fimo schemas get <TypeName> --json` to inspect field names and types. Without it, reference fields return `{ "id": "..." }` and media fields return the stored `{ "source", "id", "url", "alt" }`; with `--populate author,cover`, `author` returns the target entry for the requested locale and `cover` adds the asset's current `name`, `mime`, `width`, and `height`. Populate never selects which target fields come back. A populated target missing in the requested locale resolves to null unless you pass `localeFallbacks=true`, which falls back to the best available locale variant, marked by its `locale` field. Limits: 200 references per to-many write, 500 distinct populated documents per field per request (400 past either).
 
 Polymorphic references declare `targets: ["Post", "Product"]` instead of `target` (never both) and their values carry both parts: `{ "contentType": "Post", "id": "..." }`. Populate returns mixed full entries, and generated hooks expose `$type` on each populated value to branch on. `--where` on polymorphic fields is not supported yet and fails with a clear error. Fixed and polymorphic references also work inside blocks with these same write shapes (`id`, `documentId`, or `slug` selectors), but nested fields cannot be populated or filtered.
 

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

@@ -33,6 +33,17 @@ Declare redirects, headers, rewrites, and URL shape in
 
 Every field is optional. Only what you declare is emitted.
 
+## Preview and security headers
+
+A restrictive application-owned CSP or `X-Frame-Options` policy can block Studio
+Preview. Do not assume automatic header rewriting; Next.js `withFimo` does not
+provide it. Inspect the served policy and scope any manual adaptation to Preview,
+preserving production protections and unrelated headers. `frame-ancestors`
+permits the Studio parent, not the framed app's preview origin. Never derive
+ancestor sources from a preview-origin variable. For `script-src`, `connect-src`,
+`frame-src`, and `form-action`, use resolved/observed Fimo resources and endpoints
+actually used by the iframe. Studio-parent WebSockets do not belong in app CSP.
+
 ## Matching
 
 `source` matches the pathname only, never the query string.

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

@@ -46,11 +46,8 @@ own tenant URL.
 
 ## Hosted preview config
 
-Wrap the existing Next config once so `next dev` accepts Fimo's hosted preview
-origins without exposing the active preview provider to the application. If
-the application does not set Next's `devIndicators`, the wrapper hides it in
-hosted Preview while local `next dev` keeps Next's default. Any explicit
-`devIndicators` setting is preserved:
+Keep the generated `FimoProvider` and `withFimo` integration to render Fimo
+Preview in Fimo Studio and enable Edit Mode. Wrap the existing Next config once:
 
 ```ts
 import type { NextConfig } from 'next';
@@ -60,10 +57,16 @@ const nextConfig: NextConfig = {};
 export default withFimo(nextConfig);
 ```
 
-Preserve all existing config fields or config-function logic. Do not hardcode a
-preview domain in `allowedDevOrigins`; Fimo supplies it to the development
-sandbox. The wrapper changes nothing outside `next dev` and is not the
-application's Fimo connection.
+Preserve existing config fields and config-function logic. `withFimo` currently
+does not rewrite response headers or adapt application-owned CSP. A restrictive
+policy may need a manual Preview adaptation; inspect actual framing and blocked
+requests, preserve production protections, and verify the result in a browser.
+`frame-ancestors` permits the Studio parent, not the app's preview origin or a
+value derived from a preview-origin variable. `script-src`, `connect-src`,
+`frame-src`, and `form-action` concern resources/endpoints used by the iframe;
+use the resolved connection and observed requests. Never add a Studio-parent
+WebSocket to application CSP. Scope exceptions to Preview and keep unrelated
+security headers unchanged.
 
 ## Client dependency
 

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

@@ -53,7 +53,7 @@ Use `<StaticImage>` only when the image is deliberately not editor-managed.
 `FimoString`, `FimoBoolean`, and the other tracked values are objects, not primitives: a plain string or boolean cannot carry the source field, locale, and edit-target metadata Fimo editing needs. That gives one two-sided rule:
 
 - **MUST** pass the wrapper directly to Fimo rendering primitives (`Text`, `Boolean`, …). Unwrapping first removes the edit target.
-- **MUST** normalize the wrapper before any JavaScript comparison, condition, attribute, or third-party API: `String(value)` for strings, `value.value` (or `value.valueOf()`) for booleans.
+- **MUST** normalize the wrapper before any JavaScript comparison, condition, attribute, or third-party API: `String(value)` for strings, `value.value` for booleans.
 
 ```ts
 fimoValue === 'build';         // false — an object never strict-equals a primitive
@@ -63,6 +63,11 @@ if (fimoFlag) { … }            // always runs — an object is truthy even whe
 if (fimoFlag.value) { … }      // correct
 ```
 
+Nothing catches `if (fimoFlag)` for you: an object is unconditionally truthy in
+JavaScript, and TypeScript reports no error. Read `.value` every time. A boolean
+field without `required: true` generates `flag?: FimoBoolean`, so read
+`flag?.value`.
+
 Keep editable visible text in `<Text>`; normalized primitives are for logic and APIs only, never a substitute for rendering through the primitive.
 
 Numeric fields stay plain JavaScript numbers, so they do not carry Studio source metadata. SvelteKit's `Number` component is an optional display/formatting helper; it is not source-editable. Other framework surfaces should render numeric fields normally until a shared tracked-number contract exists.

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

@@ -174,18 +174,18 @@ report the exact failed command and setup requirement.
   reason. Better modeling never redesigns the site: preserve the source's
   content shape and behavior, and record the source-to-Fimo mapping
   (`references/content.md`).
-- Media owns its alt text. Preserve the source alt on the media value and pass
-  it to asset metadata when the upload command supports it; never add a
-  standalone alt field to a content schema. Record the limitation when the
-  command cannot carry it (`references/media.md`).
+- Before writing media or wiring `<Image>`, load
+  `fimo skills get fimo-migration --ref media` for the stored value, explicit
+  `populate`, and responsive-image checks (`references/media.md`).
 - Every write is create-or-update, so any step can be rerun without duplicating
   a schema, entry, asset, single, or label.
 - Every decision cites the source file (and line when it matters) that proves
   it. What no worker could prove stays unresolved with an owner action.
 - Keep coordination evidence in the plain-text files
   `.fimo/migration/migration-plan.md` and
-  `.fimo/migration/migration-report.md`. Use JSON only for actual Fimo
-  schema/content payloads that a data-plane command needs to import. Do not
+  `.fimo/migration/migration-report.md`. Use JSON for actual Fimo
+  schema/content import payloads and the rendered guardrail inventory and
+  capture response metadata required by `references/qa.md`. Do not
   create a target description, worker plan, decision registry, or JSON receipt
   just to describe the filesystem or agent work.
 - Do not report completion until the QA gate passes or every failed check is
@@ -378,6 +378,9 @@ writes go through the normal commands against the linked target:
 - `references/workers/content-execution.md` - data import and code-wiring
   contracts.
 - `references/workers/validator.md` - independent fan-in validation.
+- `scripts/check-rendered-guardrails.mjs` evaluates the cited guardrail
+  inventory against rendered HTML or a local server and fails closed on empty,
+  missing, redirected, or vacuous evidence.
 - `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.

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

@@ -99,8 +99,7 @@ Follow the target project's `fimo-code` Next.js reference and render its
 `FimoProvider` once at the application root. The provider uses an explicit
 host connection when one exists; otherwise it resolves the linked project and
 active git branch on the server and passes only the public connection to the
-browser. `withFimo` handles hosted preview origins, not the application
-connection.
+browser.
 
 Do not create or edit `.env` / `.env.local` for a linked project's Fimo
 connection. Run the project's normal `next dev`, `next build`, and `next start`
@@ -108,31 +107,29 @@ commands, then exercise at least one server read and one client-side data read.
 
 ## Preview embedding and response headers
 
-Fimo Preview loads the app in an iframe and drives it over the postMessage
-preview bridge, so development/preview responses must let the preview origin
-frame the app.
-
-- `withFimo` consumes `FIMO_PREVIEW_ALLOWED_ORIGINS` (platform-supplied,
-  comma-separated `**.<domain>` patterns) only to extend `allowedDevOrigins`
-  during `next dev`. It does not add, remove, or rewrite response headers;
-  wrapping the config never fixes a framing block by itself.
-- When the source `headers()` sends `X-Frame-Options` or a CSP
-  `frame-ancestors` directive, keep `X-Content-Type-Options`,
-  `Strict-Transport-Security`, and `Referrer-Policy` unchanged, and translate
-  the framing block in the migrated config. For a hosted/remote preview, while
-  `FIMO_PREVIEW_ALLOWED_ORIGINS` is set, omit `X-Frame-Options` and send
-  `Content-Security-Policy: frame-ancestors 'self' https://*.<domain>` derived
-  from each `**.<domain>` entry. For local `next dev`, when the platform
-  variable is absent, omit the framing block only while
-  `process.env.NODE_ENV !== 'production'`; keep the source framing policy in
-  production. Never hardcode a preview provider domain.
-- Record every translated or dropped header in the runtime report's Hosting
-  section.
-
-Without a browser, verify embeddability deterministically: with the variable
-set, request a route from the running dev server and assert the response
-headers carry no unconditional framing block, then mark visual proof
-unavailable in the QA report.
+Keep the generated `FimoProvider` and `withFimo` integration. It supports
+rendering Fimo Preview in Fimo Studio and enabling Edit Mode.
+
+The application owns response and security headers; `withFimo` currently does
+not rewrite them or adapt CSP automatically. A restrictive policy may still
+need a manual Preview adaptation. Inspect framing behavior and response headers
+first. Scope changes to Preview, preserve production protections and unrelated
+security headers, and record them in the runtime report's Hosting section.
+When the existing policy sends `X-Frame-Options` or an unconditional
+`frame-ancestors` block, condition or relax that framing control only for the
+verified Preview embedding context; retain it for non-Preview and production
+responses.
+
+- `frame-ancestors` controls which Fimo Studio parent may embed the app. The
+  incident's manual fix used the current Studio sources `https://fimo.ai` and
+  `https://*.fimo.ai`. Verify the Studio parent for the target environment;
+  these sources are not a universal resource allowlist. Never derive them from
+  a preview-origin variable. The sandbox or hosted preview origin identifies
+  the app being framed, not its ancestor.
+- `script-src` controls scripts, `connect-src` API and WebSocket connections,
+  `frame-src` frames embedded by the app, and `form-action` form submission
+  destinations. Base Fimo sources on the resolved connection and observed
+  requests made by the preview iframe, only for resources/endpoints it uses.
 
 ## Locales
 

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

@@ -18,7 +18,7 @@ Prefer local files from exports. Use remote URLs when no local file exists.
 
 ## Required Metadata
 
-Record what is available:
+Record what is available in the inventory and reports:
 
 - source URL or source path
 - filename
@@ -29,47 +29,50 @@ Record what is available:
 - sha256 or another stable hash when possible
 - source references and target references
 
+These are migration records, not extra fields to copy into entry media values.
+
 ## Alt Text Belongs To The Media
 
-Alt text is media metadata, not a content field. An image that has alt text in
-the source never justifies a standalone alt field in a collection or content
-schema; the alt travels with the media value.
+Preserve each source occurrence's alt on its media value, including an explicit
+empty alt. Do not add a separate schema field or use the filename as alt.
+
+Neither `fimo assets upload` nor `fimo assets bulk-upload` currently accepts
+alt metadata: keep the source alt on the value and note that upload limitation
+in the migration report. Population preserves the entry's alt; it does not
+synchronize it with asset alt metadata. If source alt is absent and you write
+a meaningful fallback, identify it as generated in the report.
 
-- Preserve the source alt on the media value alongside `source` and `url`, and
-  pass it through the asset upload metadata when the CLI exposes it. When the
-  upload command cannot carry it, keep it on the media value and record the
-  limitation as a note on the media item.
-- Never use the filename as alt text.
-- When the source has no alt, a meaningful generated alt is an explicit
-  fallback only: mark it with the media item's `altSource`
-  (`references/manifest.md`) so an editor can see which alt text the source did
-  not provide.
+Use the relevant worker report and `.fimo/migration/migration-report.md` for
+provenance and dispositions. New migrations do not create a canonical
+`manifest.json`; see `fimo skills get fimo-migration --ref manifest` for legacy
+manifest handling.
 
 ## Dedupe
 
-Deduplicate by hash when local bytes are available. If not, deduplicate by
-canonicalized URL plus filename. Keep all original references even when multiple
-sources point to one uploaded asset.
+Deduplicate by hash when local bytes are available. Otherwise use canonicalized
+URL plus filename. Keep every source occurrence and its alt even when several
+occurrences reuse one uploaded asset.
 
 ## Upload And Replacement
 
 Referenced media must be uploaded into the Fimo media library. Use
-`fimo assets bulk-upload --file <manifest.json>` for a batch and keep one
-unique `sourceId` per media item; use `fimo assets upload` for a single file.
-Never encode paths or names in whitespace-delimited shell input. Copying a file under `public/` so the deployed site can
-serve it is **not** a completed import: it has no Fimo asset id/URL, editors
-cannot manage it, and the QA gate treats a referenced-but-not-uploaded asset as
-failing. Either upload it (and record the Fimo target), or mark it `unresolved`
-with an owner action. "Bundled locally, upload later" is not an acceptable
-terminal state for referenced media.
-
-After upload, record the Fimo target asset ID/URL in the worker and migration
-reports.
-
-When using downloaded files from a Fimo migration pack, copy the recorded
-`localPath` from the media map exactly. Do not reconstruct local filenames from
-source URLs, because the downloader normalizes characters such as underscores,
-spaces, and encoded characters before writing files.
+`fimo assets bulk-upload --file <manifest.json>` for a batch or
+`fimo assets upload "<file-path>"` for a single file. The bulk-upload input is a
+JSON array with a unique `sourceId` and a `path` per item. Paths resolve from the
+project working directory, not the manifest's directory. Never encode paths or
+names in whitespace-delimited shell input. Load
+`fimo skills get fimo-cli --ref assets` for upload options and result details.
+This upload payload is separate from the migration's Markdown reports.
+
+Copying a file under `public/` is not a completed import: editors cannot manage
+it in Fimo and it has no Fimo asset ID/URL. Either upload it and record the Fimo
+target in the worker and migration reports, or mark it `unresolved` with an
+owner action. "Bundled locally, upload later" is not a terminal disposition.
+
+If a supplied Fimo migration pack includes a media map, copy its recorded
+`localPath` exactly. Do not reconstruct filenames from source URLs or undo
+normalization of underscores, spaces, or encoded characters. Verify the recorded
+path exists before upload.
 
 Replace source references in this order:
 
@@ -78,34 +81,60 @@ Replace source references in this order:
 3. page components
 4. form definitions or confirmation content
 
-Schema media should render through Fimo media primitives. Do not hardcode source
-URLs for editable media fields.
-
-The library asset and the media value stored in an entry are distinct concerns:
-the asset owns the uploaded bytes and their metadata, and the entry field holds
-the media value `{ source, url, alt }` that points at it. Keep both carrying the
-same alt text, and do not duplicate alt into a second schema field.
-
-Do not copy upload metadata into media values yourself. Writing `{ source, url,
-alt }` is enough: the write path resolves and persists the media-library ID, and
-a read that names the field in `populate` returns the asset's current URL, name,
-MIME type, and intrinsic dimensions from the library. A read that does not name
-it returns the stored reference. The ID lets you inspect the asset later with
-`fimo assets open <id> --download`.
-
-Treat intrinsic dimensions as source facts, not layout instructions. Choose the
-displayed size, crop, `sizes`, loading behavior, and fit from the migrated page's
-design and responsive behavior.
+Write each imported media field as `{ source, url, alt }`. For an uploaded
+asset, use `{ source: 'local', url, alt }` with the URL returned by Fimo. Do not
+copy the asset's ID, name, MIME type, width, height, or other upload metadata
+into the stored value. The write path resolves and persists the media-library
+ID; the asset owns the uploaded bytes and their metadata. Inspect an asset
+later with `fimo assets open <id> --download`.
+
+### Populate and render
+
+Use Fimo media primitives for schema media rather than hardcoded URLs. Load
+`fimo skills get fimo-code --ref ui` and the detected framework reference for
+component imports and usage.
+
+Explicitly populate the media field before wiring it to `<Image>`. Without
+`populate`, a read returns the stored reference `{ source, id, url, alt }`,
+including its fallback URL, but does not look up current asset metadata. With
+the field named in `populate`, it returns current asset facts from the library:
+URL, name, MIME type, and intrinsic width and height when available.
+
+For media inside blocks, name the top-level blocks field, for example
+`--populate sections` or
+`populate: ['sections'] as const`, not a nested image path. This populates all
+media inside that field.
+
+CLI examples:
+
+```bash
+fimo entries list BlogPost --limit 1 --populate cover --json
+fimo entries get BlogPost <entry-id> --populate cover --json
+```
+
+Generated-client example:
+
+```tsx
+const article = await BlogPost.getBySlug('hello', { populate: ['cover'] as const });
+return article ? <Image value={article.cover} sizes="100vw" /> : null;
+```
+
+Before completing the migration, verify that the populated raster has its
+intrinsic `width` and `height`. Render the page at desktop and mobile widths,
+then check the optimized responsive `srcset`. With optimization enabled on an
+eligible Fimo URL, `sizes` set, and no custom `srcSet`, its generated width
+candidates stop at the intrinsic width. Choose displayed size, crop, `sizes`,
+and fit from the source layout; intrinsic dimensions are source facts, not
+layout choices. Fix a missing `populate` request instead of copying metadata
+into the entry or hardcoding intrinsic dimensions. If a populated read still
+lacks dimensions, report the gap rather than inventing them.
 
 ## Failure Handling
 
-If a media asset cannot be downloaded or uploaded:
-
-- keep the source reference
-- mark the media item `unresolved` or `unsupported`
-- list every page/entry that references it
-- include a suggested action such as re-exporting the asset folder or providing
-  credentials
+If an asset cannot be downloaded or uploaded, keep its source reference,
+record `unresolved` or `unsupported` in the report, and list affected
+pages/entries, the failure reason, and an owner action, such as re-exporting the
+asset folder or providing credentials.
 
 ## Media obligations
 
@@ -115,8 +144,15 @@ terminal, the coordinator combines and deduplicates those findings into the
 complete media-obligation list. This consolidated list is the media worker's
 only input; do not make the content planner rescan the whole application.
 
-Record each obligation's source location, consuming route/entry, and intended
-target field or node. Give it a stable identity that includes its field or
-rich-text node path; a shared label or source URL is not unique. The media
-worker cannot report complete until every obligation has an uploaded or
-duplicate Fimo mapping, or an explicit unresolved/unsupported disposition.
+Keep one migration mapping per source occurrence: source file or page, field
+or rich-text node path, consuming route/entry, and target field or node plus
+the uploaded asset ID/URL. Use the source location and field or node path for
+stable identity. A shared URL or label is not a unique occurrence;
+retain every mapping even when occurrences reuse one uploaded asset.
+
+The media worker cannot report complete until every obligation has an uploaded
+or duplicate Fimo mapping, or an explicit unresolved/unsupported disposition.
+Reconcile the mappings against every discovery lane's findings, including
+schema media fields and nested richtext/Tiptap image nodes. Run the broader
+migration gate from `fimo skills get fimo-migration --ref qa` before claiming
+the migration is complete.

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

@@ -104,8 +104,7 @@ items.
 
 For linked Next.js targets, the root `FimoProvider` resolves an explicit host
 connection first, otherwise `.fimo/project.json` plus the active git branch,
-and passes only the public connection to the browser. `withFimo` handles
-hosted preview origins, not this connection. Run the normal `next dev`,
+and passes only the public connection to the browser. Run the normal `next dev`,
 `next build`, and `next start` commands without creating a Fimo env file.
 
 ## Hosting
@@ -113,18 +112,23 @@ hosted preview origins, not this connection. Run the normal `next dev`,
 Owned by the runtime lane; verified here read-only.
 
 - The target starts locally: the dev server responds without startup errors.
-- The target is embeddable in Fimo Preview, which frames the app in an iframe
-  and drives it over the postMessage preview bridge. Development/preview
-  responses carry no unconditional `X-Frame-Options` or CSP `frame-ancestors`
-  block; protective headers (nosniff, HSTS, referrer policy) stay. The
-  translation goes through `FIMO_PREVIEW_ALLOWED_ORIGINS`; `withFimo` alone
-  does not solve headers — it only extends `allowedDevOrigins` during
-  `next dev`.
+- Fimo Preview renders the target in Fimo Studio and Edit Mode works. If either
+  is blocked, verify the actual framing behavior and response headers. The
+  application owns its security policy; any Preview exception must preserve
+  production protections and unrelated security headers.
+- Check CSP sources by purpose: `frame-ancestors` permits the Studio parent;
+  the app's preview origin is the framed site. `script-src`, `connect-src`,
+  `frame-src`, and `form-action` use resolved/observed Fimo resources and
+  endpoints actually used by the iframe. Do not copy ancestor sources into
+  resource directives or derive them from a preview-origin variable.
+- `withFimo` does not rewrite response headers. Verify any required manual
+  Preview adaptation of an application-owned restrictive policy.
 - The runtime report covers local startup, preview embedding, build, the
   resolved Fimo connection, header translations, and integration env-key
   names, with every claim backed by evidence.
 - With a browser available, record `browserProof` (rendered route plus console
-  state) for startup and embedding. Without one, use deterministic HTTP
+  state) for startup, Studio embedding, and Edit Mode. Build or HTTP checks alone
+  do not prove these work. Without a browser, use deterministic HTTP
   status/header/process/log checks and mark visual proof explicitly
   unavailable in the report.
 - Deployment smoke is explicit owner opt-in; never run deploy or publish as a
@@ -157,12 +161,102 @@ Owned by the runtime lane; verified here read-only.
   fetched again after hydration. A new client waterfall, repeated full-list
   read, avoidable sequential request chain, or stale edit fails the responsible
   migration lane.
-- Navigation and footer links point to migrated routes or documented external URLs.
+- Navigation and footer links point to migrated routes or documented external
+  URLs. The `links-resolve` rule below checks internal routes; the validator
+  reviews external destinations separately.
 - Missing integration secrets do not block these checks: build, dev, and route
   render run with the integration inert, and the missing key is a recorded
   follow-up.
 - Unsupported app behavior is not hidden behind broken UI.
 
+## Rendered guardrails (required)
+
+Brand, legal, compliance, and navigation rules are proven on the final rendered
+application, never by grepping the target source. Once copy moves into Fimo the
+strings leave the repository: a source grep for a forbidden phrase passes
+because nothing is there, and a grep for the brand name fails for the same
+reason. Worker reports, manifests, and coverage tables are diagnostics; this
+check is the acceptance evidence.
+
+1. Before the validation wave, the coordinator writes the guardrail inventory to
+   `.fimo/migration/guardrails.json` for the deterministic checker. List every
+   route the migration must prove and every rule the source, owner, or accepted
+   scope imposes. Every rule includes `source`: the source page, file, or owner
+   decision that requires it. A rule without a citation is an invention, not a
+   recovered project guardrail.
+   - `required-text`: copy that must render, such as the brand name or a
+     legally required notice.
+   - `forbidden-text`: copy that must never render, such as an old brand name,
+     placeholder text, or a claim the owner withdrew.
+   - `required-link`: a link every page must carry, such as the privacy policy
+     or imprint.
+   - `links-resolve`: every internal link rendered on the inventoried routes
+     points at an inventoried route or an explicitly allowed path prefix.
+
+   Internal links are resolved against the final document URL and any
+   `<base href>`; query and fragment do not change route identity. An `allow`
+   prefix exempts a destination family deliberately outside the accepted scope.
+
+   Scope a rule with `routes` only when it is not global. When the source has
+   no rule of a kind (for example no legal page), say so in the migration
+   report rather than leaving the inventory thin without explanation.
+
+   ```json
+   {
+     "routes": ["/", "/about", "/legal/privacy"],
+     "rules": [
+       { "id": "brand-name", "kind": "required-text", "text": "<target brand>", "source": "<source page or file>" },
+       {
+         "id": "no-old-brand",
+         "kind": "forbidden-text",
+         "text": ["<previous brand>", "Lorem ipsum"],
+         "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>" }
+     ]
+   }
+   ```
+
+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
+   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`:
+
+   ```json
+   { "status": 200, "url": "http://localhost:3000/legal/privacy", "error": null }
+   ```
+
+   Record the actual final navigation response status and document URL,
+   including its trailing slash. Record navigation or capture failures in
+   `error`; never infer a successful status from HTML or fill in missing
+   evidence. Missing, malformed, non-200, or error metadata fails the route.
+   Captures are supplied evidence: the checker cannot authenticate them or
+   recognize every error page served with status 200. The browser smoke below
+   must still prove representative content and working controls.
+
+   Count visitor-visible body text and readable attributes (`alt`, `title`,
+   `aria-label`, `placeholder`, and `meta` content); script, style, and comment
+   strings do not count.
+
+   ```bash
+   node node_modules/fimo/assets/skills/fimo-migration/scripts/check-rendered-guardrails.mjs <target> \
+     --base-url http://localhost:3000 --output .fimo/migration/guardrails-report.md
+   ```
+
+3. The check fails closed and caps the gate at `draft-only` when the inventory
+   or rendered evidence is empty, a route is missing or non-200, a final URL
+   does not match the inventoried route, or a rule observes nothing. Nothing
+   observed is failed, never passed.
+
+4. Copy the emitted `## Guardrails` block unchanged into the validator's
+   worker report and the migration report. Acceptance is `Result: passed` with
+   every inventoried route rendered and every rule observed on at least one
+   route. Each failure names the route and the phrase or link involved, so the
+   repair owner needs no rerun to locate it.
+
 ## Browser smoke (required)
 
 Build success and HTTP 200 responses are not sufficient evidence: a page can
@@ -262,6 +356,8 @@ complete | complete-with-unresolved | draft-only
 
 ## Content Delivery
 
+## Guardrails
+
 ## Timing
 
 ## Checks
@@ -279,6 +375,10 @@ locales) with `gate`,
 coverage must not average away a missing entry or an unuploaded asset. Timing is
 a separate section copied from the worker reports, so it never dilutes coverage.
 
+`Guardrails` is the unmodified block emitted by
+`scripts/check-rendered-guardrails.mjs`. A report without it, or with
+`Result: failed`, cannot be `complete` or `complete-with-unresolved`.
+
 Cache freshness is a report check whenever migration changes the content
 transport or rendering mode. Do not fail a migration for omitted provider cache
 mechanics alone, but do fail stale Fimo edits caused by the target's migrated