fimo 0.17.0 → 0.19.0

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

@@ -0,0 +1,39 @@
+# Content execution workers
+
+Execute the content planner's text handoff. Do not rediscover the source,
+reclassify values, redesign schemas, or edit files outside the assigned batch.
+If the handoff is incomplete, report the missing item to the coordinator so the
+planner can repair it.
+
+## Data worker
+
+Own one bounded schema/locale payload. Start only after every referenced asset
+has a confirmed Fimo mapping and, during conversion, the framework gate passes.
+Perform create-or-update writes and read the batch back before returning.
+
+For entry batches, use
+`fimo entries bulk-create <Uid> --file <payload> --upsert-by slug` and report
+per-chunk created, updated, reconciled, and conflict counts. Do not leave a
+payload as evidence of an import. An unavailable dependency blocks promptly;
+do not poll indefinitely.
+
+## Code worker
+
+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.
+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.
+4. Preserve executable React/MDX children in order around editable prose.
+5. Render at least one real imported item through every Server-to-Client or
+   plain-JSON boundary in the batch. Use the framework's generated
+   serialization/hydration contract; do not partially unwrap tracked values.
+6. Confirm each original literal or data source is gone only where its Fimo
+   replacement now renders once.
+
+A loader that reads Fimo while the consuming markup is missing, an imported
+entry no route consumes, or a successful build over empty data is incomplete.
+Return source items wired, files changed, read-back/render evidence, and any
+unresolved item in plain text.

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

@@ -0,0 +1,64 @@
+# Content planning worker
+
+Own semantic discovery, schema authoring, payload preparation, and the text
+handoff. Do not import entries or rewrite application consumers.
+
+1. Inspect every content-bearing source and consumer: Markdown/MDX bodies and
+   frontmatter, JSX/TSX modules, hardcoded arrays and objects, imports, data
+   clients, and call sites. Read local exports and public APIs directly. A
+   private API requires a user-provided export or narrowly scoped server-side
+   credential; never recover or copy secret values.
+2. Classify each value as collection content, single content, an
+   editor-visible label, or application-owned code. Repetition is evidence,
+   not an automatic collection rule. Assistive text, identifiers, and values
+   that drive behavior are not labels.
+3. Define complete schemas from source evidence: types, requiredness, defaults,
+   uniqueness, locale behavior, media constraints, references, and
+   cardinalities. Do not invent constraints. Load `references/decision.md` and
+   the target project's Fimo schema guidance.
+4. Trace every item to the route, component, loader, query, or render module
+   that consumes it. Record its `sourceFile`, `sourceKey`, target files, payload
+   file, and worker batch. Finding data without consumers is incomplete.
+5. Enumerate every media field and rich-text image node as an asset obligation.
+6. Write and push `src/schemas/*.json`, generate required clients/types, and
+   write self-contained JSON payloads for the data workers.
+7. Write `.fimo/migration/content-plan.md` before any entry, label, single, or
+   content-driven code rewrite begins.
+
+The text plan has one source item per independently migrated construct and
+groups them into non-overlapping data and code batches. Every object in a
+hardcoded content array is an item. MDX prose and executable imports/components
+are separate items when needed; executable JSX cannot disappear inside a
+rich-text conversion.
+
+Keep the handoff short:
+
+```md
+## BlogPost
+
+- Source: `content/blog/post.mdx`
+- Schema: `src/schemas/BlogPost.json` (pushed)
+- Payload: `.fimo/migration/content/BlogPost.en.json`
+- Items: title, body, cover, `CoverageChart` behavior
+- Consumers: `src/app/blog/[slug]/page.tsx`
+- Data worker: `BlogPost/en`
+- Code worker: `blog-rendering`, owns the consumer above
+
+## Unresolved
+
+- `content/blog/post.mdx:11`: `CoverageChart` implementation is absent; owner
+  must restore it. Do not remove the node silently.
+```
+
+A construct is unresolved only when it genuinely cannot be migrated. Include
+its exact source, user-visible impact, reason, and owner action; "custom" is not
+a reason.
+
+## Optional extraction helpers
+
+Start with `rg` and targeted reads. A bounded read-only helper under
+`.fimo/migration/tmp/` may parse repeated frontmatter, JSON/YAML exports, or
+literal structures while preserving source locations. Spot-check its output.
+The agent still owns classification, schema design, and consumer tracing. Do
+not build a generic codemod system or let the helper write Fimo data or app
+code.

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

@@ -0,0 +1,37 @@
+# Framework conversion worker
+
+Use this worker only after the user explicitly chose a framework conversion.
+Preserve mode never uses it.
+
+`fimo migrate init` creates the target first. Inspect the initialized template
+and its real paths before writing. Own all structural target code: dependencies,
+framework config, root layout and providers, app tree, route modules, 404,
+redirects, headers, middleware, sitemap/robots/OG structure, and locale-routing
+structure. There is no separate runtime or route writer during conversion.
+
+Port the source APIs, loaders, hardcoded content, integrations, and visible
+behavior into the new framework unchanged. Do not migrate those values to Fimo
+in this pass; schemas, data, and Fimo consumer wiring belong to later content
+workers. The content planner may inspect the source in parallel but must not
+edit structural target code.
+
+Load the target framework's `fimo-code` and hosting references. For Next.js,
+also load `references/frameworks/nextjs.md` and translate portable hosting
+behavior before declaring provider-specific behavior unresolved.
+
+## Framework gate
+
+Before returning, self-check and report:
+
+- dependencies install cleanly;
+- the framework build succeeds;
+- every source route maps to a target route and renders locally with its
+  expected status, including 404 behavior;
+- representative source text landmarks appear;
+- exactly one app tree and one root layout exist; and
+- primary routes have no runtime or console errors.
+
+Return a plain-text route map, files changed, check results, preserved behavior,
+and unresolved behavior. The coordinator independently reruns the build and
+representative route checks. Content data cannot start until this gate and the
+asset gate pass.

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

@@ -0,0 +1,25 @@
+# Migration validator
+
+The validator is an independent read-only worker. It did not author the
+migration and starts only after all writers return.
+
+Compare the source, content plan, actual `git diff`, real Fimo state, and local
+application behavior. A worker report is a claim, not evidence.
+
+Verify:
+
+- every source route renders with expected status and representative content;
+- 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
+  an appended duplicate section;
+- media URLs load as their expected media type;
+- native Fimo APIs are used without migration-only wrappers;
+- imports are safe to rerun;
+- build and representative browser interactions pass; and
+- every unsupported item names its impact and owner action.
+
+Return a plain-text report with status, duration, checks run, counts, failing
+source items, and suggested bounded repair surface. The coordinator may run one
+repair for that surface and rerun validation. It does not restart every worker
+or loop indefinitely.

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

@@ -0,0 +1,82 @@
+# Migration workers
+
+The root coding agent is the coordinator. It inspects the initialized target,
+writes a short text plan, starts independent workers through its native
+subagent mechanism, and fans their results back in. If subagents are
+unavailable, run the same lanes sequentially; never skip a surface silently.
+
+The CLI does not start language models. JSON is reserved for Fimo schemas and
+content payloads. Worker ownership, dependencies, reports, and unresolved work
+stay in `.fimo/migration/*.md` or the agents' plain-text responses.
+
+## Schedule
+
+Plan a lane only when the source proves that surface exists:
+
+| worker          | owns                                            | starts when              |
+| --------------- | ----------------------------------------------- | ------------------------ |
+| runtime         | framework/runtime files and provider config     | immediately              |
+| routes          | route modules, redirects, SEO and host behavior | immediately              |
+| content planner | schemas, content payloads, and content handoff  | immediately              |
+| locales         | locale setup and translated UI copy             | immediately              |
+| assets/forms    | media uploads and form behavior                 | after content planner    |
+| content data    | one schema/locale import                        | after assets             |
+| content code    | listed consuming files                          | after its data read-back |
+| validator       | read-only final checks                          | after all writers        |
+
+This is preserve mode, the default. When the user explicitly chose a framework
+conversion, one framework worker replaces runtime and routes and owns all
+structural target code. The content planner may run beside it. Data then waits
+for both the asset and framework gates, and code waits for real imported-data
+read-back.
+
+## Ownership
+
+- **runtime** preserves the detected framework, router, runtime, dependencies,
+  provider setup, environment wiring, and provider-specific configuration. An
+  unclear or unsupported setup produces a question, not a silent conversion.
+- **routes** preserves every route, redirect, 404, SEO/OG/social output,
+  sitemap, robots, feeds, headers, and other observable host behavior. A file
+  that consumes migrated content belongs to its later content-code worker.
+- **content planner** discovers and models all editable content, labels,
+  consumers, schemas, payloads, media obligations, and execution batches. It
+  never imports entries or rewrites consumers. Read
+  `references/workers/content-planner.md`.
+- **assets/forms** uploads every planner media obligation and patches payload
+  references. It replaces a form or integration only when Fimo preserves its
+  behavior end to end; otherwise it preserves or reports it.
+- **content data and code** execute the planner handoff without rediscovering
+  or redesigning it. Read `references/workers/content-execution.md`.
+- **locales** owns locale configuration, locale routing, and translated
+  visitor-visible labels.
+- **framework conversion** is used only after explicit user choice. Read
+  `references/workers/framework.md`.
+- **validator** authors nothing. Read `references/workers/validator.md`.
+
+If two lanes need one file, name one owner in the text plan and sequence the
+other after it. Do not add a metadata format for a small overlap.
+
+## Coordinator gates
+
+1. Run `fimo migrate init` and inspect the real target paths before workers
+   write.
+2. Start runtime/routes/content-planner/locales together, or the framework
+   worker plus content planner/locales in conversion mode.
+3. After the content plan, upload every planned asset and patch payloads.
+4. Start data workers only after the asset gate and, in conversion mode, the
+   framework gate.
+5. Start each code worker only after its own imported records read back as
+   non-empty. A build over empty data proves nothing.
+6. Start the independent validator only after every writer has returned.
+
+Each prompt names the worker's source paths, exact target ownership, applicable
+reference above, and dependencies. Each report states status, duration, source
+evidence, files changed, Fimo writes, source items handled, unresolved work,
+and the next action. The coordinator verifies those claims against `git diff`,
+CLI read-back, and rendered routes.
+
+A source item is covered only when its target value exists and the application
+consumes it at the original behavior path, or when an explicit unresolved item
+names the impact and owner action. If validation fails, create one bounded
+repair task for that surface and rerun the validator; do not restart every
+worker.

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

@@ -1,194 +1,142 @@
 # Migration Workflow
 
-Use this as the phase contract for complete migrations.
-
-## Phase 0: Target Safety
-
-1. Confirm the target path.
-2. If the target path is missing, create exactly one Fimo project there.
-3. If it has `.fimo/project.json` or the legacy `.fimo.settings.json`, reuse it.
-4. If it is non-empty and not a Fimo project, stop and ask for a target path.
-5. Never overwrite user work outside generated migration folders without reading
-   the existing files first.
-
-## Phase 1: Source Intake
-
-Classify all available evidence:
-
-- published URLs and sitemap URLs
-- downloaded HTML, source repo, builder export, or static export
-- CMS CSV/XML/JSON exports
-- media folders and remote media URLs
-- forms and third-party form actions
-- redirects, locales, SEO metadata, robots/sitemap data
-- unsupported app behavior such as auth, commerce, search, members, custom JS
-
-For source-backed migrations, inspect the source/export directly with shell
-tools such as `rg`, `find`, `ls`, and targeted file reads. Treat CMS exports and
-media folders as source-of-truth evidence, then copy normalized facts into the
-canonical ledger.
-
-For URL-only migrations, run `fimo migrate <url> [dir]` and inspect
-`.fimo/migrations/current/`.
-
-Read these URL migration artifacts first when they exist:
-
-- `.fimo/migrations/current/brief.md`
-- `.fimo/migrations/current/manifest.json`
-- `.fimo/migrations/current/extracted/pages.json`
-- `.fimo/migrations/current/extracted/forms.json`
-- `.fimo/migrations/current/extracted/design-tokens.json`
-- `.fimo/migrations/current/refine/agent-prompt.md`
-- `.fimo/migrations/current/refine/pages/*.md`
-
-When default crawling misses client-rendered or lazy-loaded content, use the
-agent or harness browser tools to collect additional HTML, screenshots, and route
-notes, then merge that evidence into the migration artifacts. Import reviewed
-media, schemas, forms, and entries through the regular Fimo CLI commands.
-
-## Phase 2: Canonical Ledger
-
-Create `.fimo/migration/manifest.json` using `references/manifest.md`.
-
-If an older ledger exists under `.fimo/migrations/current/` or
-`.fimo/source-migration/`, keep it as evidence and copy normalized facts into the
-canonical ledger instead of editing unrelated history.
-
-Use the bundled script when possible:
-
-```bash
-node <this-skill>/scripts/build-canonical-manifest.mjs <project-root>
-```
-
-Pass `--fresh` only when intentionally discarding previous canonical manifest
-progress such as verified statuses, uploaded asset IDs, or notes.
-
-Every item needs one of these statuses:
-
-- `discovered`
-- `planned`
-- `generated`
-- `imported`
-- `verified`
-- `ignored`
-- `unsupported`
-- `unresolved`
-
-## Phase 3: Content Model First
-
-Before writing page code:
-
-1. Detect dynamic collections from both repeated route groups AND repeated
-   in-page blocks. A hardcoded array of 3+ structurally-identical items (cards,
-   list rows, tiles) is a collection, not static markup. Ignore locale prefixes
-   when naming collections.
-2. Map each CMS export or inferred collection to a Fimo schema or unresolved item.
-3. Preserve stable source IDs, slugs, dates, SEO, authors, categories, tags,
-   locales, and publish status.
-4. Decide which references are real. Do not invent references from vague text.
-5. Build seed/import entries with source IDs and media references preserved.
-6. Record source count and planned import count for each content type.
-
-Use `references/content.md`, including "Detecting Dynamic Collections".
-
-## Phase 4: Media And Forms
-
-Before final page wiring:
-
-1. Build a media map from local files and remote URLs.
-2. Upload or plan uploads for media referenced by pages, CMS entries, SEO, and
-   forms.
-3. Replace source media references only after upload mapping is known.
-4. Classify forms as Fimo-native, third-party integration, or unsupported.
-5. Generate `src/forms/*.json` for accepted Fimo-native forms.
-
-Use `references/media.md` and `references/forms.md`.
-
-## Phase 5: Import Payloads
-
-Before calling the migration complete, prepare the actual import path described
-in `references/import-contract.md`.
-
-Required order:
-
-1. media files
-2. schemas
-3. CMS entries with media references resolved
-4. forms
-
-Record target IDs, import counts, failures, and unresolved items in the
-canonical ledger. Generated JSON without import counts is still draft state.
-
-## Phase 6: Fimo Implementation
-
-Implement routes, schemas, forms, entries, media, redirects, translations, and
-React pages with Fimo conventions.
-
-Rules:
-
-- If no target exists, create one Fimo project. Do not create a nested Fimo app
-  inside a source repository unless the user explicitly chose that directory.
-- If a target Fimo project exists, inspect existing routes, schemas, forms, and
-  components before writing.
-- Store migration analysis artifacts under `.fimo/migration/`.
-- Use source CSS/design files as visual evidence, not as a permanent global CSS
-  dump.
-- Schema-driven media renders with Fimo media primitives, not raw source URLs.
-- CMS pages must have matching `src/schemas/*.json` before generated clients or
-  queries are used.
-- Repeated dynamic items (games, locations, posts, testimonials, pricing) render
-  from CMS collections, not hardcoded arrays. A page left with a hardcoded array
-  of collection-shaped items is an incomplete migration, not a finished one.
-- Generated `.ts` schema/form clients are not edited manually.
-- Unsupported source behavior is replaced with a Fimo-native equivalent or shown
-  as unresolved, never hidden behind broken UI.
-
-## Phase 7: Import
-
-Import only reviewed artifacts:
-
-- media assets and media map updates
-- schemas
-- forms
-- entries
-- redirects/locales when supported by the current project tooling
-
-After import, update the ledger with created IDs, uploaded asset IDs, failures,
-and counts.
-
-## Phase 8: QA Gate And Report
-
-Run `references/qa.md`. Write `.fimo/migration/migration-report.md` with:
-
-- source summary
-- route coverage
-- CMS source/import counts
-- media source/upload/reference counts
-- form coverage
-- build/runtime checks
-- visual checks
-- unresolved/unsupported items
-- exact next actions
-
-Use the bundled report script to make the QA state explicit:
-
-```bash
-node <this-skill>/scripts/write-migration-report.mjs <project-root>
-```
-
-The script exits non-zero when required coverage checks fail. That is a prompt
-to continue the migration or document the gaps, not a reason to hide the report.
-
-All checks in this phase are **local** (build, local dev, route render, visual
-comparison). Do not run `fimo deploy` / `fimo publish` to verify anything.
-
-## Phase 9: Propose Deployment
-
-Deployment is not part of the migration loop and is never run to preview or
-verify. Once Phase 8 passes:
-
-1. Do not run `fimo deploy` or `fimo publish` yourself.
-2. End by proposing it: tell the owner the migration is ready, that one
-   `fimo deploy` creates its hosted preview, and that going live requires a
-   separate explicit publish.
-3. Deploy only if the owner explicitly asks in this turn, and then only once.
+Use this as the phase contract for a complete migration. The coordinator and
+workers communicate in plain text. JSON is used only for Fimo schemas and the
+content payloads that the data-plane commands import.
+
+## Phase 0: Initialize the target
+
+1. Confirm the target path. The target is a separate directory; the source
+   checkout remains read-only evidence.
+2. Initialize or reuse exactly one linked Fimo target before workers start:
+   - URL migration: `fimo migrate init <source-url> <target-dir> --framework <framework>`
+   - link an existing project: `fimo migrate init <target-dir> --project-id <projectId> --framework <framework>`
+   - create a project: `fimo migrate init <target-dir> --org <organizationId> --framework <framework>`
+     Use the detected source framework for source-backed migrations. A framework
+     conversion requires an explicit user choice; URL-only and rebuild
+     migrations ask the user which framework to use. Never choose a framework by
+     copying an arbitrary `--template-root`, invent a project ID, or hand-write
+     `.fimo/project.json`.
+3. Inspect the target's real `package.json`, `.fimo/config.json`, framework config, and route
+   directories. They are the authority for paths. Do not infer an app root
+   from a skill example and do not create a second `app/` or `src/app/` tree.
+4. If the target is non-empty and not a Fimo project, stop and ask for a target
+   path; do not overlay a template on top of it.
+5. Keep source material in `.fimo/migration/source` or another explicit source
+   location. Do not copy source files over the initialized target root.
+
+Write a short `.fimo/migration/migration-plan.md` containing the source
+location, selected framework, actual target directories, worker owners, and
+known questions. Do not create `target.json`, `manifest.json`,
+`worker-plan.json`, `decision.json`, or JSON worker receipts for a new run.
+
+## Phase 1: Source intake
+
+Read the source directly with `rg`, `find`, `ls`, and targeted file reads.
+Classify the available evidence:
+
+- source repository, export, downloaded HTML, or media folder;
+- CMS CSV/XML/JSON exports and public APIs;
+- forms and third-party form actions;
+- integrations and the environment-key names they need, never secret values;
+- redirects, security headers, locales, SEO, robots, sitemap, and OG behavior;
+- unsupported behavior such as auth, commerce, search, members, custom JS, or
+  provider-specific workers.
+
+For private APIs or CMSs, ask for a user-provided export or a narrowly scoped
+server-side credential. Never recover credentials from browser bundles or copy
+them into migration artifacts. Missing access blocks only that lane and becomes
+an unresolved item; never invent replacement content.
+
+For URL-only migrations, run `fimo migrate <url> [dir]` and inspect the
+generated `.fimo/migrations/current/` files as source evidence. Do not copy
+that crawl manifest into another canonical JSON registry.
+
+## Phase 2: Fan out workers
+
+The coordinator launches only the workers supported by the source:
+
+- **runtime**: preserve the detected framework, router, runtime, dependencies,
+  provider configuration, and environment wiring. A framework conversion needs
+  an explicit user choice.
+- **routes/SEO**: preserve one target route per source route, redirects, 404,
+  metadata, OG/social output, sitemap, robots, and other observable behavior.
+- **content planner**: discover content, labels, data sources, consumers, and
+  schemas; push schemas and prepare content payloads. It does not rewrite page
+  code or import every entry itself.
+- **locales**: configure locales and migrate translated UI-visible copy when
+  the source has it.
+- **assets/forms**: after content planning, upload every referenced media item
+  and preserve, replace, or report forms and integrations.
+
+When the user explicitly chose a framework conversion, one framework
+conversion worker replaces the runtime and routes lanes and owns all
+structural target code (see `references/workers/framework.md`). The content
+planner may read the source in parallel, but it must not convert the framework
+or rewrite page code. Follow the asset, data, and code gates in
+`references/workers.md`.
+
+The coordinator gives each worker a plain-language prompt naming its ownership,
+files, dependencies, and worker-specific reference from `references/workers/`.
+Workers may write the application inside their ownership. They do not need a
+JSON plan or receipt. If two workers need the same file, name one owner and run
+the other after it.
+
+## Phase 3: Content planning
+
+The planner follows `references/workers/content-planner.md`, plus
+`references/content.md`, `references/decision.md`, and
+`references/import-contract.md`. Its text plan and payloads must be complete
+before Phase 4; data workers must not rediscover unrelated source files.
+
+## Phase 4: Media, forms, and integrations
+
+1. Account for every planner media obligation, including schema media fields
+   and richtext/Tiptap image nodes, plus route, SEO, and form media.
+2. Upload media through Fimo and replace references only after the upload is
+   confirmed. A local `public/` copy or source URL is not an imported asset.
+3. Preserve third-party integrations unless Fimo reproduces their exact
+   user-visible behavior. Record required environment-key names only.
+4. Use a Fimo-native form only when it matches the source behavior end to end;
+   otherwise preserve the integration or report it unresolved.
+
+After every media obligation has a target mapping, patch the content payloads
+and run one data worker per schema/locale. Verify each imported batch by
+read-back before starting its content code worker. The code worker replaces
+each planned consumer in place and proves at least one real imported item
+crosses every Server-to-Client or plain-JSON boundary it uses. A build over an
+empty result is not proof. Load the active `fimo-code` framework reference for
+the exact serialization and hydration contract.
+
+## Phase 5: Framework implementation
+
+Preserve the detected source framework, router, runtime, and configuration.
+React Router/Vite stays React Router/Vite and Next.js stays Next.js. Convert to
+Next.js only after the user explicitly chooses it. An explicit conversion is a
+faithful first pass owned by the framework conversion worker: it ports the
+source's APIs, loaders, hardcoded content, integrations, and visible behavior
+into the new framework, and it must pass the framework gate in
+`references/workers/framework.md` before content code work continues. A gate
+failure is draft-only or unresolved; never fall back silently to a generic
+shell or another framework. Load the matching `fimo-code` framework and
+hosting references before integration work.
+
+Preserve the source route surface and behavior. Do not replace many pages with
+one generic static shell. Apply the matching framework reference before
+disposing of provider-specific rules; redirects, headers, feeds, metadata,
+forms, and freshness behavior are observable contracts.
+
+## Phase 6: Fan in, validate, and report
+
+Workers return the plain-text receipt defined in `references/workers.md`.
+The coordinator checks those claims against the diff, source, CLI read-back,
+build, and rendered routes. Then an independent worker follows
+`references/workers/validator.md`; a worker saying "done" is not evidence.
+
+Write `.fimo/migration/migration-report.md` with route/content/media/form/SEO
+coverage, import counts, worker timings, unresolved items, and next actions.
+Use `complete` only when required checks pass, `complete-with-unresolved` when
+the app works and every gap is explicit, and `draft-only` when import or
+verification is incomplete.
+
+All checks are local. Do not deploy or publish to verify a migration.