fimo 2.6.0-staging.1 → 2.6.0-staging.2

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/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-migration/SKILL.md

@@ -184,8 +184,9 @@ report the exact failed command and setup requirement.
   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 +379,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/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

package/assets/skills/fimo-migration/references/workers/validator.md

@@ -1,11 +1,13 @@
 # Migration validator
 
 Validation is one independent read-only wave after all writers return. The
-coordinator gives every validator the accepted migration scope and deliberate
-user-approved differences, but no producer findings, repair reasoning,
-transcript, or expected verdict. A validator checks the finished target against
-the source within that contract. It does not report an explicitly excluded
-route, integration, or control as migration drift.
+coordinator gives every validator the accepted migration scope, deliberate
+user-approved differences, and the guardrail inventory path
+(`references/qa.md`, Rendered guardrails), but no producer findings, repair
+reasoning, transcript, or expected verdict. A validator may add a rule the
+source proves; it never removes or narrows one. A validator checks the
+finished target against the source within that contract. It does not report an
+explicitly excluded route, integration, or control as migration drift.
 
 When subagents are available, launch separate workers for build and runtime,
 Fimo data and content, and rendered browser behavior. Run them concurrently
@@ -13,11 +15,18 @@ after their prerequisites pass. They may inspect overlapping files because none
 of them writes.
 
 Compare the source, content plan, actual `git diff`, real Fimo state, and local
-application behavior. A worker report is a claim, not evidence.
+application behavior. A worker report, manifest, or coverage table is a
+diagnostic, not acceptance evidence. A check that observed nothing - zero
+rendered routes, zero collected links, zero matched rules - is failed, not
+passed.
 
 Verify:
 
 - every source route renders with expected status and representative content;
+- the rendered guardrail inventory passes: brand, legal, compliance, and
+  navigation rules are proven on rendered HTML or a running local server with
+  `scripts/check-rendered-guardrails.mjs`, never by grepping target source.
+  Browser captures include the response metadata required by `references/qa.md`;
 - schemas, entries, singles, labels, media, forms, and locales exist through
   CLI read-back;
 - every planned source item is consumed at its original behavior path, not in
@@ -43,6 +52,13 @@ duration, checks run, counts, failing source items, blocked descendants, and
 suggested repair ownership. Stop only when a failed prerequisite makes a check
 meaningless.
 
+End every validator report with an `Acceptance` section: the exact commands
+another party can rerun (build, local start, the guardrail check with its
+inventory and observation source, CLI read-back) and the expected evidence for
+each - exit status, the unmodified `## Guardrails` block ending in
+`Result: passed`, and the counts observed. A pass reported without its command
+and output is a claim.
+
 The coordinator fans every lane into one finding set before editing. It assigns
 disjoint repair owners, waits for the whole repair wave, then reruns one central
 validation wave. It does not restart every worker, repair findings one at a

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

@@ -76,9 +76,11 @@ other after it. Do not add a metadata format for a small overlap.
    framework gate.
 6. Start each code worker only after its own imported records read back as
    non-empty. A build over empty data proves nothing.
-7. After every writer returns, start one read-only validation wave. When
-   subagents are available, run build and runtime, Fimo data and content, and
-   rendered browser checks concurrently after their prerequisites pass.
+7. Before the validation wave, write the cited rendered-guardrail inventory
+   required by `references/qa.md`. After every writer returns, start one
+   read-only validation wave. When subagents are available, run build and
+   runtime, Fimo data and content, and rendered browser checks concurrently
+   after their prerequisites pass.
 
 Each prompt names the worker's source paths, exact target ownership, applicable
 reference above, and dependencies. Each report states status, duration, source