fimo 0.17.0 → 0.18.0

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

@@ -0,0 +1,72 @@
+# Migration decisions
+
+Migration decisions are plain text. Put them in
+`.fimo/migration/migration-plan.md` and the relevant worker report. Do not
+create `.fimo/migration/decision.json`, a target metadata file, or a second
+decision registry.
+
+The decision must say, in ordinary language:
+
+- what the source construct is;
+- where it is proven in the source;
+- whether it becomes collection content, a single, a label, or
+  application-owned code;
+- which schema/payload and consuming files are involved;
+- what was preserved, replaced, or left unresolved; and
+- who or what must do the next action.
+
+The owning worker may write schemas, content payloads, entries, assets, singles,
+and labels directly through the normal Fimo CLI/API contracts. The text plan is
+the handoff; it is not an approval queue and it is not required to replay a
+completed migration.
+
+## Labels
+
+A label is UI-visible copy presented to a visitor or user: navigation text,
+headings, buttons, form labels, validation and error text, calls to action,
+visible empty states, and visible translated copy.
+
+Do not classify every string as a label. Object keys, route segments, CSS
+tokens, analytics event names, internal identifiers, prices and other data
+values, application settings, and assistive-only attribute text remain in
+application code unless the source proves they are editor-managed content.
+Record the source file and consuming UI for each label.
+
+## Schema decisions
+
+Write the complete valid Fimo schema that the source justifies. For every field,
+decide its Fimo type, requiredness, default, string options, uniqueness,
+locale-sharing behavior, media multiplicity/MIME constraints, and reference
+target/cardinality when the source proves them. The schema JSON is an actual
+Fimo artifact and may be pushed by the content planner; it is not a report
+about the agent's reasoning.
+
+Choose field types from source semantics and editor experience, following
+`references/content.md`: use richtext for portable editorial prose, blocks for
+structured or repeatable editorial sections, media for assets, and references
+for independently managed records proven by the source. Use JSON only for
+opaque or application-owned data that has no Fimo-native model, and record why.
+
+Requiredness and defaults come from the source contract, such as a CMS schema,
+collection configuration, validation contract, or type declaration. A field is
+not required merely because the sampled files fill it. Use only source-declared
+or safe technical defaults such as an empty list, `false`, or absent. Never
+invent human-readable copy as a default.
+
+Preserve the raw value and explain the uncertainty in the text plan when a
+mapping is unclear. Validate every schema against the actual Fimo CLI/content
+schema contract and use its generated clients, renderers, and primitives.
+
+## Mapping rules
+
+- Markdown collections become one content type plus one document per slug.
+- Localized documents become one document with one payload per locale.
+- Local assets referenced by content become media-library uploads, and the
+  content payload references the uploaded asset. Media owns its alt text; do
+  not add a parallel alt field to the content schema.
+- Routes map source route modules to target route modules.
+- References are created only from stable source identity or a confirmed
+  mapping.
+- A custom or executable construct is unresolved only when it genuinely cannot
+  be carried over. Record its exact source location, why it is not portable,
+  and a suggested action. Never silently remove it.

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

@@ -1,15 +1,21 @@
 # Forms
 
-Builder form backends rarely migrate directly. Replace simple forms with Fimo
-forms and document complex behavior.
+Preserve the behavior a visitor sees. Replace a form with a Fimo form only when
+Fimo reproduces the source form's user-visible behavior end to end; otherwise
+keep the original integration wired and record what it needs.
 
 ## Classify
 
-Use `fimo-native` when the form is a simple contact, newsletter, lead capture,
-RSVP, quote request, or similar data collection form.
+Use `fimo-native` only when Fimo genuinely reproduces the source form's
+user-visible behavior end to end: a simple contact, newsletter, lead capture,
+RSVP, or quote request form whose submit, validation, and success/error flow a
+Fimo form matches 1:1.
 
-Use `third-party` when the form posts to Mailchimp, HubSpot, Typeform, Formspree,
-Zapier, Airtable, payment providers, or another external backend.
+Use `third-party` when the form posts to Brevo, Mailchimp, HubSpot, Typeform,
+Formspree, Zapier, Airtable, payment providers, or another external backend.
+When the external behavior is not 1:1 reproducible - a Brevo double-opt-in
+newsletter flow, for example - keeping the original integration wired is the
+correct terminal state, not a migration failure.
 
 Use `unsupported` when the form depends on auth, checkout, dynamic pricing,
 multi-step state, file workflows not supported by the current project, custom JS,
@@ -43,6 +49,32 @@ For `fimo-native` forms:
 Do not claim live submission parity until the form has been pushed/imported and
 rendered by the site.
 
+## Definition Versus Wiring
+
+Importing the Fimo form definition and wiring the source form UI are two
+different obligations; report them separately.
+
+- The definition (`src/forms/*.json`, pushed to Fimo) covers what the form
+  collects: fields, options, required flags.
+- The wiring covers the behavior the visitor sees around the form: the source
+  page's markup, conditional pricing, availability rules, client-side
+  validation, and the submit/success/error flow. Preserve that local behavior
+  in the application code where possible; pushing the definition does not
+  migrate it.
+- A third-party integration may be explicitly deferred as an unresolved item
+  with the source action and an owner decision, but a form is never reported
+  as migrated while its local behavior is missing or its integration was
+  silently dropped.
+
+## Credentials And Secrets
+
+Record the credential environment keys a preserved integration needs by name
+(`BREVO_API_KEY`, not its value). Never read secret values or copy them into
+migration artifacts. A missing secret is a user follow-up in the report: the
+integration stays wired, local build, evaluation, and QA checks still run with
+the integration inert, and the behavior is never deleted because its secret is
+unavailable.
+
 ## Unsupported Or Third-Party Forms
 
 Create an unresolved item with:

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

@@ -1,26 +1,182 @@
-# Next.js source inventory
+# Next.js source
 
-Load this reference when the migration source is a Next.js application. This
-reference selects evidence strategies; use the target project's `fimo-code`
+Load this reference when the migration source is a Next.js application or the
+user explicitly chose Next.js as a conversion target. It describes what each
+worker must read in that source; use the target project's `fimo-code`
 framework guidance when implementing the migrated application.
 
-## Inventory
-
-1. Record the installed Next.js and internationalization package declarations.
-2. Identify App Router, Pages Router, or a mixed tree without changing it.
-3. Inspect `next.config.*`, request configuration, middleware or proxy files,
-   navigation helpers, route segments, and message dictionaries.
-4. Keep these claims separate:
-   - dictionary locale candidates;
-   - configured locales;
-   - default locale;
-   - publicly routable locales;
-   - localized pathnames.
-5. When next-intl is declared, load
-   `references/inventory/locales/next-intl.md` and run its bounded strategy.
-6. Record dynamic, imported, remote, or otherwise unproven configuration as
-   unresolved for the locale inventory fan-in.
-
-Use package versions to prioritize likely strategies, not as proof of the
-source shape. Projects backport, customize, and combine conventions across
-versions; accept a claim only when its source evidence supports it.
+A Next.js source stays a Next.js target. Keep the detected router flavor,
+`next.config.*`, middleware, and runtime configuration; do not convert the app
+to React Router or another framework to simplify the migration. When framework
+detection is ambiguous, stop and ask. A non-Next.js source converts to Next.js
+only when the user explicitly chooses it.
+
+## Next.js as a conversion target
+
+When the user explicitly chose converting another framework (for example React
+Router/Vite) to Next.js, the framework conversion worker in
+`references/workers.md` owns the target. It inspects the app tree that
+`fimo migrate init` actually created, keeps that single tree, and rebuilds the
+source routes, 404, redirects, headers, middleware, sitemap/robots/OG
+structure, and locale routing structure inside it. It ports the source's own
+loaders, APIs, hardcoded content, and integrations unchanged; Fimo wiring
+happens later through the content workers. The conversion must pass the
+framework gate before content data and code workers start.
+
+Use package versions to prioritize likely shapes, not as proof of the source.
+Projects backport, customize, and combine conventions across versions; accept a
+claim only when its source evidence supports it.
+
+## Runtime and routes
+
+1. Record the installed Next.js, content, and internationalization package
+   declarations. A data-source package is a retrieval clue for the content
+   worker, nothing more.
+2. Identify App Router, Pages Router, or a mixed tree.
+3. Read `next.config.*`, request configuration, middleware or proxy files,
+   navigation helpers, and route segments before changing them. Map every
+   source route to a target route module, a redirect, or an unresolved item.
+4. Inventory `redirects()`, `rewrites()`, `headers()`, route handlers,
+   middleware, cache/revalidation calls, and provider adapters separately.
+   Preserve each rule until its behavior is replaced and verified. Record the
+   disposition of every rule; do not delete a whole provider file because some
+   rules became redundant.
+
+## Equivalents and hosting boundary
+
+Load the target project's `fimo-code` `frameworks/next` and
+`frameworks/hosting` references before implementing. Use normal Next.js
+equivalents when they fit the accepted contract:
+
+- route modules and route handlers for routes, feeds, negotiated responses, and
+  special text/XML files;
+- `not-found` and `notFound()` for framework-owned 404 behavior;
+- metadata APIs and OG/Twitter image routes for SEO and social output;
+- `redirects()`, `rewrites()`, `headers()`, middleware, or response headers for
+  rules that the chosen runtime actually executes; and
+- Next.js fetch/cache/revalidation APIs only when freshness is an observable
+  requirement rather than copied provider machinery.
+
+These are application-level options, not guarantees that Fimo hosting supports
+every header, redirect, route handler, cache mode, edge API, or middleware
+behavior. Verify the chosen host/runtime. If support cannot be established,
+preserve the existing deployment path or record the behavior unresolved and ask
+the user; do not promise equivalence from code shape alone.
+
+### Port Cloudflare behavior
+
+Do not mark a rule unresolved merely because it came from a Cloudflare Worker:
+port static redirects, rewrites, headers, and asset cache headers to the real
+`next.config.*`, then verify each with a request. Put dynamic behavior in
+middleware or route handlers, and use Next.js cache/revalidation APIs when they
+replace observable freshness. Cloudflare-only Cache API, bindings, `waitUntil`,
+and purge calls need a verified host equivalent or remain explicitly unresolved.
+
+Give every worker rule a `preserved`, `replaced`,
+`safely-unnecessary-implementation-detail`, or `unresolved` disposition with
+its target file and request-level proof.
+
+## SEO, OG, and social
+
+The routes/SEO worker owns the source's existing SEO and social surface:
+`metadata` exports, `generateMetadata`, `opengraph-image.*` and
+`twitter-image.*` route files, dynamic OG image routes built on
+`ImageResponse`, canonical URLs, robots, and sitemap generation. Preserve each
+behavior in place; when one cannot be preserved, record an explicit gap with
+the affected routes instead of shipping pages that silently lost their share
+metadata.
+
+## Build-time and browser runtime
+
+The Next server runtime reads `FIMO_CONTENT_API_URL`; client components and
+generated client hooks read `NEXT_PUBLIC_FIMO_API_URL`. For a local production
+build or migration acceptance run, expose both names and point them at the
+same tenant content URL. `FIMO_API_URL` is the management/CLI API and is not a
+substitute for either content API variable.
+
+`withFimo` derives these aliases during `next dev` when the project is linked,
+so local development does not need hand-written values. A production build,
+however, compiles `NEXT_PUBLIC_*` values into the browser bundle and the
+adapter intentionally does not inject them outside the development phase.
+For `next build`/`next start`, set temporary values in the shell or an ignored
+`.env.local`; never commit secret values. In either mode, exercise at least one
+client-side data read after startup.
+
+## 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.
+
+## Locales
+
+Keep these claims separate, and treat any one of them as unproven until its
+source says so: dictionary locale candidates, configured locales, the default
+locale, publicly routable locales, and localized pathnames. A dictionary file
+never proves route reachability.
+
+When `package.json` declares next-intl, the locales worker reads the actual
+message files, `defineRouting` values, middleware, request helpers, and call
+sites directly. A dictionary filename is evidence for a message locale, not
+proof that the locale is routable. If the source uses another library or a
+custom store, follow its imports and reads in the same worker. The worker may
+write a short bounded temporary extractor when that is faster, but it owns the
+interpretation and must record the source evidence and any unresolved claim.
+
+## Markdown, MDX, and inline content
+
+The content planner reads the content itself: file locations and formats,
+frontmatter keys and values, locale-shaped filenames or directories, route and
+component modules that consume them, hardcoded arrays and object literals, and
+local asset references under `public/`. It records every consuming source and
+target module in `affectedFiles` before code workers start. Nested frontmatter,
+mixed locale conventions, missing local assets, and unproven route references
+need a decision from the source, not a guess.
+
+Map what the source proves: a directory of Markdown files with several slugs may
+be one collection, locale-suffixed files may be locale payloads of one
+document, and a `public/` reference may become a media upload. The content
+planner decides the destination from the consuming route and data shape, rather
+than using a filename or extension as an automatic classification.
+
+Create one source item per Markdown/MDX document and per independently handled
+construct inside it. Portable prose and an executable MDX component are
+different items even when they share one file. Read the custom component, its
+import, and its data path; assign it to a code batch when it can be rebuilt with
+native Fimo content, otherwise record it unresolved before data import begins.
+Never remove JSX from the richtext payload without representing that JSX as its
+own migrated or unresolved source item.
+
+For a hardcoded content array, create one source item per object and preserve
+observable order explicitly. The matching data batch count must equal the
+source item count. A schema and query with zero planned entry items is an
+incomplete handoff.
+
+Use a temporary read-only extractor only when it reduces repeated work. Parsing
+frontmatter or a large literal array can be useful; a general Next.js AST parser
+is not required. Record the mapping in the text content plan and worker report.
+
+Content that is not file-backed follows the content planner's discovery branches
+in `references/workers.md`; preserve every provider gap as unresolved evidence.

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.