fimo 0.17.0 → 0.19.0

package/assets/skills/fimo-migration/references/import-contract.md

@@ -8,6 +8,13 @@ but it is not complete until the relevant Fimo project contains the imported
 assets, schemas, entries, and forms, or the gaps are owner-visible unresolved
 items.
 
+Every data-plane write in this contract targets the linked project from
+workflow Phase 0. Local artifacts never require the link — `fimo migrate
+import` only prints the import plan (it writes no data) and warns in an
+unlinked directory — running the printed commands is what needs the link.
+When no owner-supplied target exists, the writes stay unresolved owner
+actions; do not fake a link to make them pass.
+
 ## Media Files
 
 Discovery must include:
@@ -17,13 +24,17 @@ Discovery must include:
 - CMS media fields
 - SEO/share images
 - downloadable files linked from pages or entries
+- every schema media field, including empty or unresolved source values
+- image nodes nested anywhere in richtext or Tiptap payloads
 
 Import requirements:
 
-- every imported asset records a Fimo target asset ID or URL in
-  `.fimo/migration/manifest.json`
+- every imported asset records a Fimo target asset ID or URL in the worker and
+  migration reports
 - every failed asset has an unresolved item with references to the affected
   route or entry
+- every planner media obligation has an uploaded mapping, an explicit
+  unresolved/unsupported disposition, or a proven duplicate mapping
 - CMS media fields are rewritten after upload; source URLs are not left in
   editable entry payloads unless explicitly unresolved
 
@@ -46,10 +57,14 @@ Discovery must include:
 
 Import requirements:
 
-- schemas are pushed before entries
+- schemas are validated and pushed before media or content writes
+- `fimo schemas push` reconciles an ambiguous 504 by reading every requested
+  schema back. A complete match counts as committed; when all are absent it
+  retries once; mixed, mismatched, or still-absent state stops for review
+  instead of replaying another blind write.
 - entries are created or updated in Fimo, not only written as seed JSON
 - source count, generated count, imported count, skipped count, and unresolved
-  count are recorded per content type
+  count are recorded per content type in the text plan/report
 - references are resolved in a second pass only when stable IDs or confirmed
   mappings exist
 
@@ -72,32 +87,69 @@ Discovery must include:
 
 Import requirements:
 
-- simple contact/newsletter/lead forms become `src/forms/*.json` and are pushed
-  to Fimo
-- third-party or unsupported forms are recorded with source action, reason, and
-  owner action
+- a form becomes `src/forms/*.json` and is pushed to Fimo only when the Fimo
+  form reproduces the source form's user-visible behavior end to end
+- a third-party form whose behavior is not 1:1 reproducible keeps its original
+  integration wired, with the required credential environment keys recorded by
+  name (never their values) and any missing secret reported as a user
+  follow-up
+- unsupported forms are recorded with source action, reason, and owner action
 - the report records form count, Fimo-native count, third-party count, and
   unsupported/unresolved count
 
 Acceptance:
 
-- every visible source form is represented by a Fimo form, third-party plan, or
-  unsupported/unresolved item
+- every visible source form is represented by a Fimo form, a preserved
+  third-party integration, or an unsupported/unresolved item
 - no page keeps a broken form UI that appears live
 
+Historical form submissions do not have a write contract. The current
+form-submissions CLI is read-only, so never claim that old submissions were
+imported. Preserve the source export and record historical submission import as
+unsupported with an owner action until a dedicated import contract exists.
+
+## Pagination And Batching
+
+The data-plane commands are paginated and capped. Read the limits instead of
+assuming one request covers everything:
+
+- `fimo entries list` and `fimo assets list` return 20 items by default and at
+  most 100 per request (`--limit`, `--offset`). The response carries `total`
+  and `hasMore`; page until `hasMore` is false before treating a listing as
+  complete.
+- `fimo entries bulk-create` chunks at 100 entries by default. Migration data
+  workers use `--upsert-by slug`; the identity includes locale, the command
+  rereads after an ambiguous 504 before retrying absent entries, and its
+  receipt aggregates per-chunk created/updated/conflict counts. Use
+  `--chunk-size` only when the transport supports a different bounded size
+  (maximum 1,000). `bulk-update` and `bulk-delete` remain capped at 1,000.
+- `fimo labels set-many` sends its whole `--file`/`--data` payload in one
+  request; keep one payload per worker batch so a retry replays a bounded set.
+
+Listing existing Fimo entries or assets serves idempotency, retry, and fan-in
+reconciliation only - confirming what a rerun must update instead of create.
+The source of the content is always the source tree or export, never a listing
+of what already exists in Fimo.
+
 ## Minimum Import Loop
 
 For each migration, agents should run this loop:
 
-1. Build or refresh the canonical manifest.
-2. Fill missing media, CMS, and form discovery data.
-3. Generate reviewed schemas/forms/import payloads.
-4. Import media first.
-5. Push schemas.
-6. Import entries with media references resolved.
-7. Push forms.
-8. Refresh the canonical manifest with target IDs and counts.
-9. Write the migration report.
+1. Read the text migration plan and the initialized target.
+2. Have the owning workers define complete schemas/forms and write them through
+   the normal Fimo contracts.
+3. Validate and push schemas before dependent content writes.
+4. Upload media.
+5. Import entries, then resolve proven references against stable target IDs.
+6. Update singles and apply labels.
+7. Handle form definitions through their separate supported contract; do not
+   import historical submissions.
+8. Write target IDs, counts, failures, and unresolved items into worker and
+   migration reports.
+
+The data-plane dependency order remains `schemas`, `media`,
+`entries/references`, `singles`, and `labels`. It is a simple execution order,
+not a reason to add another orchestrator.
 
 If any step cannot be completed, write an unresolved item immediately with the
 source evidence and owner action needed.

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

@@ -1,164 +1,14 @@
-# Canonical Migration Manifest
+# Legacy migration manifest
 
-Write `.fimo/migration/manifest.json`. It is the source of truth for humans,
-follow-up agents, and import/QA checks.
+New migrations do not create a canonical `manifest.json`. The coordinator uses
+the readable `.fimo/migration/migration-plan.md` and
+`.fimo/migration/migration-report.md` instead.
 
-## Shape
+Older URL-only migrations may contain `.fimo/migrations/current/manifest.json`.
+Read it as source evidence when useful, but do not copy it into another
+registry or ask workers to keep it synchronized.
 
-```json
-{
-  "version": 1,
-  "source": {
-    "mode": "url-only|source-backed|hybrid",
-    "platform": "webflow|framer|squarespace|wix|wordpress|carrd|custom|unknown",
-    "publicUrl": "https://example.com",
-    "rootPath": "../source",
-    "inventoryPath": ".fimo/migration/inventory.json",
-    "sourceLedgers": []
-  },
-  "artifacts": {
-    "code": [],
-    "cms": [],
-    "media": [],
-    "forms": [],
-    "screenshots": [],
-    "other": []
-  },
-  "routes": [],
-  "contentTypes": [],
-  "entries": [],
-  "media": [],
-  "forms": [],
-  "redirects": [],
-  "locales": [],
-  "seo": [],
-  "unsupported": [],
-  "unresolved": [],
-  "qa": {
-    "status": "not-run|passed|failed|passed-with-unresolved",
-    "checks": []
-  }
-}
-```
-
-## Required Item Fields
-
-Every route, content type, entry batch, media asset, form, redirect, locale, SEO
-item, unsupported item, and unresolved item should include:
-
-```json
-{
-  "id": "stable-human-readable-id",
-  "status": "discovered|planned|generated|imported|verified|ignored|unsupported|unresolved",
-  "sourceFiles": [],
-  "sourceUrls": [],
-  "targetFiles": [],
-  "confidence": 1,
-  "notes": []
-}
-```
-
-Use honest confidence. Inferred content from crawled pages is lower confidence
-than first-party CSV/XML/JSON exports.
-
-## Content Type Item
-
-```json
-{
-  "id": "blog-post",
-  "uid": "BlogPost",
-  "name": "Blog Posts",
-  "status": "planned",
-  "sourceFiles": ["exports/blog.csv"],
-  "targetFiles": ["src/schemas/BlogPost.json"],
-  "sourceCount": 42,
-  "plannedCount": 42,
-  "importedCount": 0,
-  "fields": {
-    "title": { "type": "string", "source": "Name" },
-    "body": { "type": "richtext", "source": "Post Body" },
-    "coverImage": { "type": "media", "source": "Main Image" },
-    "publishedAt": { "type": "datetime", "source": "Published On" }
-  },
-  "references": []
-}
-```
-
-> **Do not put reserved names in `fields`.** `id`, `documentId`, `slug`, `locale`,
-> `createdAt`, `updatedAt`, and `__fimo` are built-in entry metadata — declaring them as
-> schema fields makes `fimo schemas push` fail with a 400. Map a source "Slug" column onto
-> the entry's built-in `slug` (inside `data`) at import time, not onto a schema field.
-
-## Entry Batch Item
-
-```json
-{
-  "id": "blog-post-entries",
-  "contentType": "BlogPost",
-  "status": "generated",
-  "sourceFiles": ["exports/blog.csv"],
-  "targetFiles": [".fimo/migration/entries/BlogPost.json"],
-  "sourceCount": 42,
-  "generatedCount": 42,
-  "importedCount": 0,
-  "skipped": []
-}
-```
-
-## Media Item
-
-```json
-{
-  "id": "media-hero-jpg",
-  "status": "imported",
-  "sourceUrl": "https://example.com/hero.jpg",
-  "sourcePath": "assets/hero.jpg",
-  "targetAssetId": "asset_123",
-  "targetUrl": "https://...",
-  "sha256": "optional",
-  "contentType": "image/jpeg",
-  "bytes": 123456,
-  "width": 1600,
-  "height": 900,
-  "alt": "Hero image",
-  "referencedBy": ["route:/", "entry:BlogPost/welcome"],
-  "uploadError": null
-}
-```
-
-## Form Item
-
-```json
-{
-  "id": "contact",
-  "name": "contact",
-  "status": "generated",
-  "classification": "fimo-native|third-party|unsupported",
-  "sourceFiles": ["contact.html"],
-  "targetFiles": ["src/forms/contact.json"],
-  "action": "https://formspree.io/...",
-  "method": "post",
-  "fields": [],
-  "unsupportedReason": null
-}
-```
-
-## Unresolved Item
-
-```json
-{
-  "id": "mailchimp-newsletter-action",
-  "area": "forms",
-  "severity": "medium",
-  "status": "unresolved",
-  "message": "Newsletter form posts to Mailchimp and requires integration credentials.",
-  "suggestedAction": "Create a Fimo form or configure a Mailchimp integration with the owner."
-}
-```
-
-## Rules
-
-- Prefer stable source IDs over generated IDs.
-- Preserve original field names in `source`; use clean Fimo field IDs in schemas.
-- Never delete unresolved items just to make the report cleaner.
-- Update item statuses as work progresses.
+JSON remains appropriate for actual Fimo artifacts: schema files and the
+content payloads passed to data-plane commands. It is not needed to describe
+worker ownership, target paths, decisions, timings, or QA status. Put those in
+plain-text plans, worker reports, and the final migration report.

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

@@ -29,6 +29,22 @@ Record what is available:
 - sha256 or another stable hash when possible
 - source references and target references
 
+## 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 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.
+
 ## Dedupe
 
 Deduplicate by hash when local bytes are available. If not, deduplicate by
@@ -45,7 +61,8 @@ 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, update the manifest with the Fimo target asset ID/URL.
+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
@@ -62,6 +79,11 @@ Replace source references in this order:
 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.
+
 ## Failure Handling
 
 If a media asset cannot be downloaded or uploaded:
@@ -71,3 +93,13 @@ If a media asset cannot be downloaded or uploaded:
 - list every page/entry that references it
 - include a suggested action such as re-exporting the asset folder or providing
   credentials
+
+## Planner obligations
+
+The content planner enumerates every media obligation before fan-out: route and
+SEO media, every schema media field, and every image node nested in richtext or
+Tiptap JSON. Record its source location, consuming route/entry, and intended
+target field or node. Give each obligation a stable identity that includes its
+field or rich-text node path; a shared label or source URL is not unique. The
+asset worker cannot report complete until every obligation has an uploaded or
+duplicate Fimo mapping, or an explicit unresolved/unsupported disposition.

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

@@ -50,5 +50,29 @@ Use these notes to decide what is source of truth and what must be rebuilt.
 
 - Search for structured data before assuming static content: CSV, JSON, MD/MDX,
   frontmatter, CMS SDK calls, route loaders, API fixtures.
-- Identify the current framework only to understand routing/data, not to copy
-  implementation patterns into Fimo.
+- Identify the current framework to understand routing and data. A source
+  repository keeps its framework, router, and runtime for the first migration.
+  If detection or hosting compatibility stays unclear, stop and ask. Do not
+  select Next.js as a fallback; a conversion happens only after the user's
+  explicit choice, through the framework conversion worker and gate in
+  `references/workers.md`.
+
+## Provider-specific hosting
+
+- A provider file is evidence, not disposable scaffolding. Inventory its rules
+  and classify each one as preserved, replaced, safely unnecessary
+  implementation detail, or unresolved.
+- Preserve the file until its externally observable behavior has an accepted,
+  verified replacement. Delete it only when redundancy is proven or the user
+  explicitly accepts the loss.
+- Cloudflare cache storage, purge, and revalidation code may be safely
+  unnecessary when it has no external caller and no accepted freshness
+  contract depends on it. Do not copy provider mechanics merely to imitate the
+  implementation.
+- Redirects, security headers, route and 404 behavior, Markdown negotiation,
+  feeds, sitemap, `llms.txt`, social metadata, and forms are public behavior.
+  Preserve them or replace them with an equivalent and verify the result.
+- A React Router/Vite site can remain React Router/Vite even when Cloudflare-only
+  hosting features are conditional or unresolved. Hosting uncertainty is not
+  permission to convert the application; only the user's explicit choice
+  starts a conversion.

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

@@ -1,19 +1,117 @@
 # Migration QA Gate
 
-Run this gate before reporting completion.
+Run this gate before reporting completion. The gate is read-only: it starts
+only after every other worker has returned a terminal report, and it never
+repairs what it finds — failures become bounded repair tasks or unresolved
+items.
 
 ## Coverage
 
 - Every intended source route is implemented, ignored with a reason, or unresolved.
+- The source route surface is preserved: routes were not restructured to
+  shrink the migration, and no group of source pages was replaced by a generic
+  static shell.
+- Every imported schema, entry, single, and label has a consuming target route
+  or component. Content that exists in Fimo but is not rendered by the
+  application is unwired, not covered.
+- Every source content item is represented in the target: a content type, a
+  field, a block, a reference, a label, or an explicit unresolved item.
+- The editorial model is Fimo-native and not silently flattened. Structured or
+  repeatable editorial sections are blocks, rich bodies are richtext, and
+  categories, authors, related items, and repeated taxonomies are references -
+  not hardcoded strings, raw IDs, or opaque JSON. Every `json` field carries a
+  recorded reason that no Fimo-native model fits.
+- Editable shared chrome (header, footer, navigation, site settings) has a
+  singleton or other content model an owner can edit, and labels are limited to
+  small UI copy and reusable translations.
+- Content type, field, and block names are semantic and editor-facing: no markup
+  tags, HTML attributes, locale suffixes, or column indexes.
+- Modeling did not redesign the site: the migrated routes render the same
+  content, order, and copy as the source, and the text plan records the
+  source-to-Fimo mapping.
+- Media alt text is attached to the media (asset metadata and media value), with
+  no standalone alt field in a content schema. Alt is never the filename, and a
+  generated fallback is recorded as generated.
+- Every planner `sourceFile`/`sourceKey` maps to its original consumer. Imported
+  labels or prose that are only appended elsewhere, including an additive
+  “Page content” section, are unwired gaps. Use existing literal-key extraction
+  for a bounded read-only comparison when it is sound; otherwise report every
+  unmapped key from the planner consumer map. Do not build a generic AST or
+  codemod system for this check.
 - Every CMS export file is mapped to a schema, ignored with a reason, or unresolved.
 - Source entry counts match imported counts (entries created in Fimo), excluding
   documented skips/unresolved. Generated seed JSON alone does not satisfy this.
 - Every media item referenced by routes, CMS entries, SEO, or forms is uploaded to
   the Fimo media library (Fimo asset id/URL) or has an unresolved item. A local
   `public/` copy is not an upload mapping.
-- Every visible form has a Fimo replacement, third-party plan, or unsupported note.
+- Every planner media obligation, including schema media fields and nested
+  richtext/Tiptap image nodes, has a mapping or explicit disposition; the asset
+  worker's completion claim alone is not evidence.
+- Every visible form has a Fimo replacement, a preserved third-party
+  integration, or an unsupported note. A form became Fimo-native only when the
+  Fimo form matches the source behavior 1:1.
+- The detected source framework, router, runtime, and configuration are
+  preserved. React Router/Vite remains React Router/Vite; any Next.js conversion
+  has the user's explicit choice. Unsupported or unclear hosting is unresolved,
+  not hidden by a conversion or deleted configuration.
+- In conversion mode, the framework gate passed before content code work: the
+  conversion worker's self-checks and the coordinator's independent rerun of
+  the build and representative route checks are both recorded. A gate failure
+  caps the status at draft-only or leaves the affected routes unresolved; no
+  route was replaced by a generic shell or another framework as a fallback.
+- Every preserved third-party integration keeps its original wiring, and the
+  credential environment keys it needs are recorded by name. A missing secret
+  is an unresolved user follow-up, never silently removed behavior.
 - SEO title, description, canonical URL, share image, slugs, dates, authors,
   categories, tags, redirects, and locales are preserved when present.
+- Existing SEO, OG, and social behavior - including dynamic OG image routes -
+  is preserved or explicitly reported as a gap.
+- When the source has no low-risk SEO or social value, safe defaults derived
+  from verified page/site data are present or the missing behavior is reported;
+  the migration must not invent marketing claims.
+- Redirects and security headers stay in the source framework config when the
+  target keeps the source runtime and host, or are translated with a recorded
+  note in the text migration report when the target runtime or host requires
+  it.
+- Every provider-specific rule is classified as preserved, replaced, safely
+  unnecessary implementation detail, or unresolved. A deletion has evidence of
+  redundancy or the user's accepted loss.
+- Public behavior is verified independently: blog routes and 404s, Markdown
+  negotiation, RSS, sitemap, `llms.txt`, OG/social metadata, redirects,
+  security headers, and forms where present. Cloudflare cache storage, purge,
+  and revalidation internals need no copy when proven externally irrelevant.
+- Each content/data lane records its source-access class. Local files/exports
+  and public APIs were read under their simple access rules; private sources
+  used a user export or narrowly scoped server-side credential. Missing access
+  is unresolved for that lane, and no content was guessed.
+
+For linked Next.js targets, `withFimo` derives `FIMO_CONTENT_API_URL` and
+`NEXT_PUBLIC_FIMO_API_URL` from `.fimo/project.json` during `next dev`,
+`next build`, and `next start`. Both aliases resolve to the same tenant API,
+while non-empty user overrides remain untouched; no committed env file is
+required.
+
+## Hosting
+
+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`.
+- The runtime report covers local startup, preview embedding, build, derived
+  aliases, 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
+  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
+  QA step.
 
 ## Behavior
 
@@ -21,13 +119,49 @@ Run this gate before reporting completion.
 - The project builds successfully.
 - Local dev starts without Vite loader/schema/form generation errors.
 - Primary routes render without console/runtime errors.
+- In conversion mode, every route in the conversion worker's route map renders
+  locally with the expected status (including 404) and shows its source text
+  landmarks, and the target has exactly one app tree.
 - Collection listing/detail pages work with imported data, seed data, or explicit
   empty states.
+- Every content-code batch exercised at least one non-empty imported item
+  through each Server-to-Client or plain-JSON boundary it introduced; build
+  success over an empty query result does not pass this check.
 - Navigation and footer links point to migrated routes or documented external URLs.
+- 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.
 
+## Browser smoke (required)
+
+Build success and HTTP 200 responses are not sufficient evidence: a page can
+build, return 200, and still render blank labels or an empty collection. Run
+one bounded, scriptable browser pass (Playwright, agent-browser, or
+equivalent):
+
+1. Start the app and wait for hydration, not just the HTTP response.
+2. Open a representative set of pages: home, one collection listing, one
+   collection detail, one static page.
+3. Exercise one representative interaction (open the nav menu, an accordion,
+   or a filter) and assert its visible result.
+4. Assert expected visible text on each opened page and at least one dynamic
+   collection item rendered from imported Fimo data.
+5. Assert globally rendered label/button text (header/footer nav, CTAs, cookie
+   banner) is non-empty; blank text usually means the component is mounted
+   outside the label provider.
+6. Inspect the browser console and server output for runtime errors.
+
+Keep it bounded: representative pages and one interaction, not an interactive
+walk of every route or a multi-hour visual audit. The Visual section below
+remains a separate spot check.
+
 ## Visual
 
+Visual checks need a browser. When none is available, run the deterministic
+Hosting checks instead and mark visual proof explicitly unavailable in the
+report; never claim a visual check that did not run.
+
 - Compare source and migrated site at desktop and mobile sizes.
 - Prioritize layout, typography, content hierarchy, media, and brand tokens.
 - Remove generated placeholder copy from visible UI.
@@ -42,8 +176,11 @@ Record:
 - media uploaded/failed
 - forms pushed
 - redirects/locales imported or unresolved
+- the exact CLI used for the run, recorded in the report's Source section (see
+  "CLI provenance" in `SKILL.md`)
 
-Counts must be written into `.fimo/migration/manifest.json`.
+Counts belong in `.fimo/migration/migration-report.md` and the relevant worker
+reports. Do not create a JSON QA registry just to store them.
 
 Media, entries, and forms are blocking checks. Entries generated as seed JSON but
 not created in Fimo, and media bundled under `public/` but not uploaded to the
@@ -66,15 +203,25 @@ complete | complete-with-unresolved | draft-only
 
 ## Source
 
+## Coverage by dimension
+
 ## Routes
 
-## CMS
+## Content
 
 ## Media
 
 ## Forms
 
-## SEO, Redirects, Locales
+## SEO and OG
+
+## Redirects and Headers
+
+## Integrations
+
+## Hosting
+
+## Timing
 
 ## Checks
 
@@ -83,15 +230,22 @@ complete | complete-with-unresolved | draft-only
 ## Next Actions
 ```
 
+`Coverage by dimension` is one row per migration surface (routes, content,
+forms, SEO/OG, redirects/headers, integrations, hosting, media, labels, and
+locales) with `gate`,
+`discovered`, `migrated`, `verified`, `unresolved`, `unsupported`,
+`denominator`, and `coverage`. Never collapse it into a single score: full route
+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.
+
+Cache freshness is a report check only when the source or user made freshness an
+accepted observable requirement; do not fail a migration for omitted provider
+cache mechanics alone.
+
 Use `complete` only when all required checks pass. Use
 `complete-with-unresolved` when the migrated site is usable and all gaps are
 owner-visible. Use `draft-only` when import or verification has not happened.
 
-The bundled script can update `qa.status` and write the report:
-
-```bash
-node <this-skill>/scripts/write-migration-report.mjs <project-root>
-```
-
-If it fails, read the generated report and either complete the missing work or
-add precise unresolved items with owner-friendly suggested actions.
+Write the report directly as text. A later evaluator may calculate the table
+from it, but the migration does not need a manifest or report-generation
+registry to run.