fimo 2.6.0 → 2.7.0-experimental.1

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

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

@@ -22,7 +22,8 @@ do not poll indefinitely.
 Start only after this batch's real records read back as non-empty. Own exactly
 the consumer files assigned by the planner.
 
-1. Load the active framework's `fimo-code` reference.
+1. Load the active framework's `fimo-code` reference. Before changing a media
+   read or image component, load `fimo skills get fimo-migration --ref media`.
 2. Establish the generated Fimo client/adapter needed by the batch.
 3. Replace every planned `sourceFile`/`sourceKey` at its existing consumer in
    place. Appending a disconnected duplicate section is not wiring.

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