fimo 2.6.0 → 2.7.0-experimental.1

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

@@ -1,9 +1,36 @@
 # Analytics workflow
 
-Pageview aggregates for the **published** site are stored in Fimo's analytics pipeline. Preview traffic is not recorded.
+Pageview aggregates for the **published** site are stored in Fimo's analytics pipeline.
+Ingestion accepts any resolved branch, so do not assume that every possible preview
+sender is excluded; a preview visit is stored under its own branch rather than dropped.
+
+For tracking setup, load `fimo-code`. Reading analytics does not install a tracker.
+If counts are zero, check the selected branch, built scripts, enabled setting,
+browser requests and stored results before diagnosing a missing implementation.
+A successful HTTP response alone does not establish that a row was stored.
+Use `fimo-code` analytics setup for the standalone `fimo-analytics` APIs.
+Confirm that the selected package release contains them before generating imports;
+older Fimo releases and existing published sites do not acquire a tracker automatically.
+
+For Studio tracking verification, load `fimo-studio` and its analytics reference.
+Its tracking status is independent of the chart range and device filter; a failed
+status check is not evidence of missing tracking.
 
 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 do not appear in published traffic. 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 +64,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-cli/references/locales.md

@@ -90,7 +90,7 @@ Write the locale into a route's path with the reserved `:locale` segment, never
 | `/:locale/blog/:slug` | `{ "type": "locale", "optional": false }` | `/en/blog/hello` and `/fr/blog/bonjour`             |
 | `/:locale/pricing`    | omitted                                   | `/pricing` for `en`, `/fr/pricing` for `fr`         |
 
-- `locale` is reserved. It is read from the URL, so it never takes `schema` or `queryField` and never becomes a CMS query. Every other param is content-backed and needs both.
+- `locale` is reserved. It is read from the URL, so it never takes `schema` or `queryField` and never becomes a CMS query. Every other param is an `entry` param that needs both, unless it declares `"type": "external"`: an external param takes no other keys, and the application owns its values.
 - `optional: true` means omit the configured default locale from the URL. With `i18n.defaultLocale: "en"`, `/pricing` is English and `/fr/pricing` is French.
 - `optional: false` prefixes every locale, including the default (`/en/pricing` and `/fr/pricing`). Changing `i18n.defaultLocale` chooses the fallback locale; it does not by itself change this prefix policy.
 - A route with no `:locale` segment stays application-owned. Studio shows it once and neither adds nor interprets a locale segment.
@@ -102,7 +102,7 @@ Register the same shape in the router. React Router spells the omittable segment
 route(':locale?/blog/:slug', './pages/BlogPost.tsx');
 ```
 
-These canonical entries are also the optional metadata used by Studio Pages. See `references/pages.md` for content-backed `params` and declared `sources`.
+These canonical entries are also the optional metadata used by Studio Pages. See `references/pages.md` for the three `params` types and declared `sources`.
 
 For every framework, the application owns its URL scheme, resolves the locale, and passes it into Fimo. Studio stores the locale the app reports for the current location — including when only the locale changed — and reads content in it. Route metadata is optional unless the project wants Fimo Studio route selection/navigation.
 

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

@@ -7,15 +7,27 @@ Pages can mirror the application's routes in Fimo Studio. It gives editors a rou
 A route has three separate parts:
 
 - `path` is the URL pattern, such as `/blog/:slug`.
-- `params` optionally binds path placeholders to Collection entries so Studio can select a concrete route in the page header.
+- `params` optionally describes each path placeholder: an entry bound to a Collection so Studio can select a concrete route in the page header, the reserved `locale` segment, or a value the application owns.
 - `sources` optionally names the Labels, Single, and Collection results editors manage after selecting a route.
 
-Each param key matches a `:placeholder` in `path`. `schema` selects the Collection, `queryField` is the entry field stored in the URL, and `displayField` is the field Studio shows to editors. Use `id` or the built-in `slug` for `queryField`; a custom URL field must set both `"required": true` and `"unique": true` in its schema. Params resolve in path order, so a later param query may use an earlier selection:
+Each param key matches a `:placeholder` in `path`. For an entry param, `schema` selects the Collection, `queryField` is the entry field stored in the URL, and `displayField` is the field Studio shows to editors. Use `id` or the built-in `slug` for `queryField`; a custom URL field must set both `"required": true` and `"unique": true` in its schema. Params resolve in path order, so a later param query may use an earlier selection:
 
 ```bash
 fimo pages set <id> --path '/shop/:category/:product' --params '{"category":{"schema":"Category","queryField":"slug","displayField":"name"},"product":{"schema":"Product","queryField":"slug","displayField":"name","query":{"where":{"category":"$params.category.id"},"sort":"name"}}}'
 ```
 
+A descriptor's `type` is optional and selects one of three param kinds:
+
+- `entry` (the default) binds the placeholder to a Collection with `schema`, `queryField`, `displayField`, and an optional `query`.
+- `locale` is the reserved `:locale` segment with an optional `optional` boolean. See `references/locales.md`.
+- `external` takes no other keys. The application owns the values: Fimo matches the segment from the URL and never looks it up in the CMS.
+
+```bash
+fimo pages set <id> --path '/cartes/:slug' --params '{"slug":{"type":"external"}}'
+```
+
+Declare a placeholder `external` when its values are not Fimo content — a catalogue synced from an upstream source and stored as a media asset, ids that exist only in the visitor's browser, computed archive or pagination segments, third-party ids. Never bind a placeholder to an unrelated Collection to make `fimo validate` pass. `fimo pages list` reports `dynamic:external` and `fimo pages list --expand` skips the route; `fimo/paths` and the generated sitemap emit nothing for it, so the application enumerates those URLs itself. A `$params.<name>.<field>` expression in a param query or a source may reference entry params only. A route may mix kinds: entry params keep their selectors in Studio, and an external param takes a typed value in the preview header.
+
 `sources` is a named object under `routes.<id>.sources`. It is not an array or a route definition. Keep its keys stable and descriptive:
 
 ```json

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

@@ -76,6 +76,14 @@ Each reference defines one package contract. Fetch it when the task reaches that
 - Framework detection, production routing, and hosting adapters → `references/frameworks/hosting.md`
 - Major visual work → `references/design.md`
 
+## Analytics
+
+For pageview installation, read [references/analytics.md](references/analytics.md).
+`FimoProviders` from `fimo-react-router` already tracks when `VITE_API_URL` and
+`VITE_ENABLE_ANALYTICS=true` are configured. Inspect the installed version and
+browser requests before adding a sender. Hosting or the neutral Vite plugin alone
+does not install a tracker. Older releases do not acquire new package exports.
+
 ## Non-negotiable boundaries
 
 - Do not hardcode editor-owned collections, page content, labels, or media in JSX.

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

@@ -0,0 +1,104 @@
+# Pageview tracking
+
+First inspect the installed package and the built page. React Router's
+`FimoProviders` already tracks when `VITE_API_URL` and
+`VITE_ENABLE_ANALYTICS=true` are present. Do not mount another sender beside an
+unmodified legacy tracker. The neutral Vite plugin and hosting alone do not
+install tracking.
+
+## Standalone setup
+
+Install a released version of `fimo-analytics` that exposes the adapter you need.
+Keep any version/channel selector the user already chose. An older `fimo`
+release does not imply these standalone APIs exist, and existing published
+sites need a code update to gain missing instrumentation.
+
+```sh
+pnpm add fimo-analytics
+```
+
+Obtain the tenant API base URL from the project's configured Fimo connection,
+and append `/e/p`. Pass that complete URL as `endpoint`. Never infer it from the
+site's public URL, guess a project hostname, or invent a discovery command. If
+the connection does not supply a tenant endpoint, obtain it before enabling
+tracking. A configured origin-relative proxy is also accepted.
+
+| Framework      | Import                                              | Placement                                    |
+| -------------- | --------------------------------------------------- | -------------------------------------------- |
+| React          | `{ Analytics }` from `fimo-analytics/react`         | Application root                             |
+| React Router   | `{ Analytics }` from `fimo-analytics/react-router`  | Inside root router                           |
+| Next App/Pages | `{ Analytics }` from `fimo-analytics/next`          | Root layout or `_app`                        |
+| Astro          | default `Analytics` from `fimo-analytics/astro`     | Shared layout, no `client:*`                 |
+| Svelte         | default `Analytics` from `fimo-analytics/svelte`    | Root component                               |
+| SvelteKit      | default `Analytics` from `fimo-analytics/sveltekit` | Root `+layout.svelte`                        |
+| Vue            | `{ Analytics }` from `fimo-analytics/vue`           | Root component, history routing              |
+| Nuxt           | `modules: ['fimo-analytics/nuxt']`                  | `analytics: { endpoint, enabled }` in config |
+
+Components accept `endpoint` and `enabled`. React example:
+
+```tsx
+import { Analytics } from 'fimo-analytics/next';
+<Analytics endpoint={endpoint} enabled={isProduction} />;
+```
+
+For Nuxt, also install the optional build peer with `pnpm add -D @nuxt/kit`.
+Next owns its client and Suspense boundaries. SvelteKit uses committed
+navigation; Nuxt covers reused pages and query changes. Generic React, Vue and
+Svelte observe history. For a router that changes the URL before committing,
+use the manual core. For Vue Router, initialize in `onMounted` after initial
+router readiness, send once, subscribe to `router.afterEach`, send only when
+`failure` is falsy, and remove the subscription and destroy on unmount.
+
+```ts
+import { init } from 'fimo-analytics';
+const analytics = init({ endpoint, enabled: isProduction, routing: 'manual' });
+// In the router's successful-navigation callback:
+analytics.pageview();
+// During cleanup:
+analytics.destroy();
+```
+
+Vanilla apps can omit `routing` to track the initial page and browser history.
+Hash routers can pass `{ path: resolvedVirtualPath, pageName }` to `pageview`;
+the React Router adapter already reads its router's virtual location.
+
+For plain HTML, copy the installed `dist/browser.js` into static assets:
+
+```html
+<script defer src="/fimo-analytics.js" data-endpoint="https://YOUR-TENANT-API-HOST/e/p" data-enabled="true"></script>
+```
+
+Use a classic script, not `type="module"`. Set `data-enabled="false"` in preview
+builds. No framework peer is required for core or HTML. Framework peers are
+optional and only the chosen adapter's framework is needed.
+
+## Choose the enabled guard
+
+Tracking defaults to enabled, so always pass `enabled`. Never use `NODE_ENV`:
+a Fimo hosted preview is a production build, so that guard leaves previews
+reporting. Read the build variable Fimo already sets:
+
+| Framework                 | Guard                                              |
+| ------------------------- | -------------------------------------------------- |
+| React Router and any Vite | `import.meta.env.VITE_ENABLE_ANALYTICS === 'true'` |
+| Next.js                   | `process.env.NEXT_PUBLIC_FIMO_ENV === 'prod'`      |
+| Build-time server env     | `process.env.FIMO_ENV === 'prod'`                  |
+
+Astro, SvelteKit, Svelte and Vue have no browser-visible environment name from
+Fimo. Read `FIMO_ENV` at build time and pass the boolean into the bundle through
+the framework's own public-variable mechanism. Do not invent a `PUBLIC_FIMO_ENV`
+and do not expose the whole environment name when a boolean is enough.
+
+## Verify the installed integration
+
+Standalone tracking defaults to enabled. Supply an explicit production guard;
+`bl_preview_token` also suppresses sends. SSR and disabled calls are inert.
+Do not add browser secrets, project IDs or branch claims to payloads.
+
+Verify one initial POST, navigation, query-only changes, back/forward and a
+route revisit. Check duplicate mounts and cleanup. Existing visitor/session
+storage keys are retained; blocked storage uses per-document IDs. Delivery is
+best effort and has no retries. A 202 response alone does not prove persistence;
+check recorded analytics separately. Framework peer ranges are not proof that
+every older framework release was tested. Use the installed package's version
+qualification and preserve existing supported integrations when upgrading.

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

@@ -170,6 +170,8 @@ The new-project shell pairs unprefixed default-locale pages with a parallel `[lo
 }
 ```
 
+A dynamic segment whose values are not Fimo content takes `{ "type": "external" }` instead of a Collection binding; Fimo matches it from the URL, and the page's own `getStaticPaths` (or on-demand rendering) supplies those values.
+
 ## Client islands
 
 Generated content reads remain server-only. Preserve existing islands and do not add React or a client SDK to work around this boundary.

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