fimo 0.14.0 → 0.15.0-staging.2

package/assets/skills/fimo-migration/SKILL.md

@@ -7,163 +7,116 @@ description: >-
   media, CMS schemas and entries, forms, SEO, redirects, locales, and unresolved
   gaps with a verifiable manifest and QA gate. This is the single canonical
   migration skill for URL-only, source-backed, and hybrid migrations.
-fimoVersion: 0.1.0
 ---
 
 # Fimo Migration
 
-This skill orchestrates migrations into Fimo from published URLs, builder
-exports, source repositories, CMS exports, media folders, or any hybrid of those.
-It owns intake, source inventory, URL crawl bootstrapping, ledger normalization,
-imports, and QA so any LLM can run the work without silently dropping content.
-
-> Run every `fimo` command as `npx fimo@latest <command>` — always the latest CLI, no global install.
-
-## Non-Negotiables
-
-- No source data may disappear silently. Every route, CMS export, entry, media
-  asset, form, locale, redirect, SEO field, or unsupported behavior is imported,
-  deliberately ignored with a reason, or listed as unresolved.
-- Media files, CMS entries, and forms are the primary migration payload. The
-  migration is not complete until each of those three areas has discovery counts,
-  import counts, target IDs or files, and verification notes in the canonical
-  ledger.
-- Source exports beat inferred crawls. If CSV/XML/JSON exports, media folders, or
-  source code exist, treat the public URL as visual/SEO reference only.
-- Builder HTML is evidence, not the final runtime. Rebuild with Fimo conventions,
-  schemas, forms, media primitives, translations, and routes.
-- Do not report completion until the QA gate passes or every failed check is
-  recorded in the migration report.
-- Do not deploy or publish during the migration. Importing content is required
-  and uses the data-plane commands (`fimo assets upload`, `fimo schemas push`,
-  `fimo entries create`, `fimo forms push`); these do **not** rebuild the live
-  site. `fimo deploy` / `fimo publish` rebuild and restart the site — never run
-  them as part of the migration loop or to "check" rendering. Verify locally
-  (build + local dev). Deployment is a single, final, owner-approved step:
-  when the QA gate passes, **propose** it to the owner instead of running it.
-
-## Intake Decision
-
-1. Read the target project `AGENTS.md`.
-2. If editing or creating a Fimo project, read the project `fimo` skill and the
-   `fimo-cli` skill references needed for schemas, entries, forms, and assets.
-   Do not run `fimo deploy` / `fimo publish` here — deployment is a final,
-   owner-approved step (see Non-Negotiables and the Deployment rule below).
-3. Classify the source:
-   - **source-backed**: export folder, source repo, CMS CSV/XML/JSON, media
-     folder, downloaded HTML, or platform export. Use source files as truth and
-     inventory them directly with shell tools such as `rg`, `find`, and targeted
-     file reads.
-   - **url-only**: only a published URL exists. Follow `references/workflow.md`
-     and start with `fimo migrate <url> [dir]` to create the draft evidence
-     pack.
-   - **hybrid**: source files plus public URL. Use source-backed as truth and URL
-     for route, SEO, visual, and behavior comparison.
-4. Create or update the canonical ledger described in
-   `references/manifest.md`.
-
-## Workflow
-
-Read `references/workflow.md` before starting implementation. The short version:
-
-1. Inventory source artifacts. For URL-only work, run
-   `fimo migrate <url> [dir]`; for source-backed work, inspect the export or
-   repository directly with shell tools and targeted file reads.
-2. Normalize CMS, media, forms, routes, redirects, locales, and unsupported
-   behavior into the canonical ledger.
-3. Model content before page code.
-4. Generate or update Fimo schemas, entries, media mappings, forms, routes, and
-   React pages.
-5. Import reviewed media files, CMS schemas/entries, and forms through Fimo
-   APIs/CLI. Do not treat generated JSON as imported content.
-6. Run the QA gate in `references/qa.md`.
-7. Write `.fimo/migration/migration-report.md` with coverage, counts, mappings,
-   unresolved items, and next actions.
-
-To bootstrap or refresh the canonical ledger from existing URL/source migration
-artifacts, run:
+Move published URLs, exports, source repositories, CMS data, media, and forms
+into a real Fimo project without silently dropping source material.
 
-```bash
-node <this-skill>/scripts/build-canonical-manifest.mjs <project-root>
-```
+> **Experimental:** migration support is limited. Assess what can be preserved, explain unsupported parts, and never promise source-framework preservation.
+>
+> Use the CLI invocation selected for this flow for every `fimo` command in the migration. Otherwise use `npx fimo@latest`; do not install it globally.
 
-To update QA status and write the handoff report, run:
+## Core contract
 
-```bash
-node <this-skill>/scripts/write-migration-report.mjs <project-root>
-```
+- Record every route, CMS record, media asset, form, locale, redirect, SEO
+  field, and unsupported behavior as imported, deliberately ignored with a
+  reason, or unresolved.
+- Prefer source code and exports over inferred crawl data. Use a public URL as
+  visual, SEO, route, and behavior evidence when better source material exists.
+- Model content before page code. Generated JSON is not imported content.
+- Keep migration evidence in the canonical ledger from
+  `references/manifest.md`.
+- Do not report completion until the QA gate passes or every failed check is
+  present in the migration report.
+- Do not deploy while migrating. Import through the data-plane commands,
+  verify locally, and propose one final owner-approved deployment.
+
+## Orient and route
+
+1. Read the target project's `AGENTS.md`.
+2. When creating or changing a Fimo application, load its `fimo` and
+   `fimo-cli` skills for the required schemas, entries, forms, assets, and
+   framework APIs.
+3. Classify the available evidence:
+   - **source-backed**: source repository, export, downloaded HTML, CMS data,
+     or media folder. Treat the source files as truth and run the relevant
+     bounded inventory helpers when available. After the canonical manifest
+     records `source.rootPath` and `source.inventoryPath`, run
+     `fimo migrate inventory [project-root]` for deterministic framework,
+     runtime, package, locale, and message-file evidence.
+   - **url-only**: only a published URL. Run `fimo migrate <url> [dir]` to
+     create the draft evidence pack.
+   - **hybrid**: source material plus a public URL. Treat source material as
+     truth and the URL as comparison evidence.
+4. Read `references/workflow.md` before implementation and create or update the
+   canonical ledger.
+5. Load only the framework and inventory references that apply:
+   - Next.js source -> `references/frameworks/nextjs.md`.
+   - Locale or dictionary evidence -> `references/inventory/locales.md`.
+   - Declared next-intl dependency ->
+     `references/inventory/locales/next-intl.md`.
+   - Deterministic inventory coordination ->
+     `references/inventory/coordinator.md`.
+
+## Migration loop
+
+1. Prepare the deterministic inventory plan first. When independent workers
+   are available, create one read-only subagent per planned lane; otherwise run
+   the same lanes sequentially. Every worker returns its fragment, never a
+   prose claim. Run reconcile after every fan-out, then use targeted file reads
+   for evidence the inventory leaves unresolved. Use a validator worker that
+   produced no fragments to compare the plan, source evidence, fragments, and
+   unresolved claims. Reopen only affected lanes when validation finds a gap.
+2. Normalize CMS, media, forms, routes, redirects, locales, and unsupported
+   behavior into the canonical ledger.
+3. Model content and references before writing pages.
+4. Generate or update schemas, entries, media mappings, forms, routes, and
+   application code with native Fimo contracts.
+5. Import reviewed media, schemas, entries, and forms in the order required by
+   `references/import-contract.md`.
+6. Run the local QA gate in `references/qa.md`.
+7. Write `.fimo/migration/migration-report.md` with coverage, counts,
+   mappings, unresolved items, and next actions.
+
+Use the bundled deterministic helpers whenever their contract fits. If a
+helper cannot prove a source fact, follow the bounded fallback in the relevant
+inventory reference instead of treating the whole inventory as failed.
 
 ## References
 
-- `references/workflow.md` - full decision tree and phase order.
+- `references/workflow.md` - phase order, source intake, URL artifacts, and
+  implementation loop.
 - `references/manifest.md` - canonical migration ledger schema.
 - `references/content.md` - CMS, entries, references, and source value rules.
-- `references/media.md` - media inventory, upload, dedupe, and replacement rules.
-- `references/forms.md` - form classification and Fimo replacement rules.
-- `references/import-contract.md` - exact import obligations for media, entries,
-  and forms.
+- `references/media.md` - media inventory, upload, dedupe, and replacement.
+- `references/forms.md` - form classification and Fimo replacement.
+- `references/import-contract.md` - import obligations for media, entries, and
+  forms.
 - `references/platforms.md` - platform-specific source-of-truth and rebuild
   notes.
-- `references/qa.md` - required acceptance gate and report format.
-- `scripts/build-canonical-manifest.mjs` - creates
-  `.fimo/migration/manifest.json` from existing migration ledgers.
-- `scripts/write-migration-report.mjs` - updates manifest QA status and writes
-  `.fimo/migration/migration-report.md`.
-
-Load only the references needed for the current phase.
-
-## Completion Rule
-
-Final status must be one of:
-
-- **complete**: QA gate passed, counts match, imports verified.
-- **complete-with-unresolved**: site builds and known gaps are documented with
-  owner-friendly reasons and next actions.
-- **draft-only**: user explicitly asked for a draft or the migration cannot
-  import/verify yet.
-
-Never use “complete” when CMS entries, media mappings, forms, or route coverage
-are unknown. Generated seed JSON and media bundled under `public/` are **draft
-state**, not imported content: a migration whose entries were never created in
-Fimo, or whose referenced media was never uploaded to the Fimo media library, is
-`draft-only` (or `complete-with-unresolved` only when each gap is an explicit,
-owner-visible unresolved item). The QA gate enforces this and exits non-zero
-otherwise.
-
-## Deployment
-
-Deployment is **out of scope for the migration loop** and happens at most once,
-at the very end, with the owner's approval.
-
-- Never run `fimo deploy` or `fimo publish` to verify, preview, or "check"
-  rendering while migrating. All verification (build, local dev, route render,
-  visual comparison) is done locally.
-- Importing content (`fimo assets upload`, `fimo schemas push`,
-  `fimo entries create`, `fimo forms push`) is part of the migration and does
-  not deploy the site — run those as the import contract requires.
-- After the QA gate passes and the report is written, end by **proposing**
-  deployment: tell the owner the migration is ready and that running
-  `fimo deploy` once will publish it. Let them decide; do not deploy on their
-  behalf unless they explicitly ask in this turn.
-
-## URL-Only Migration Contract
-
-`fimo migrate <url> [dir]` creates migration evidence and a draft project; it
-does not replace the agent rebuild pass. After the command completes, read:
-
-- `.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` when present
-- `.fimo/migrations/current/refine/pages/*.md` when present
-
-Raw source HTML snapshots may exist under `.fimo/migrations/current/source/`.
-Use them as evidence, not as final runtime code.
-
-If the default crawl 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 with the regular Fimo CLI commands
-instead of relying on `fimo migrate` to push content directly.
+- `references/qa.md` - acceptance gate and report format.
+- `references/frameworks/nextjs.md` - Next.js source inventory routing.
+- `references/inventory/locales.md` - locale evidence and agent fallback.
+- `references/inventory/locales/next-intl.md` - next-intl strategy and support
+  boundary.
+- `references/inventory/coordinator.md` - deterministic inventory fan-out,
+  worker, and fan-in commands.
+- `scripts/build-canonical-manifest.mjs` - bootstrap the canonical ledger.
+- `scripts/write-migration-report.mjs` - update QA state and write the report.
+
+## Completion and deployment
+
+Use one final status:
+
+- **complete**: QA passed, counts match, and imports are verified.
+- **complete-with-unresolved**: the site builds and every known gap has an
+  owner-readable reason and next action.
+- **draft-only**: imports or verification are incomplete, or the user asked for
+  a draft.
+
+Never call a migration complete when CMS entries, media mappings, forms, or
+route coverage are unknown. Never run `fimo deploy` or `fimo publish` as a
+preview or QA step. After local QA passes, propose one final deployment and run
+it only when the owner explicitly approves it in the current turn.

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

@@ -0,0 +1,26 @@
+# Next.js source inventory
+
+Load this reference when the migration source is a Next.js application. This
+reference selects evidence strategies; 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.

package/assets/skills/fimo-migration/references/inventory/coordinator.md

@@ -0,0 +1,40 @@
+# Deterministic inventory coordination
+
+Prepare before running lanes:
+
+```bash
+fimo migrate inventory <project-root> --prepare
+```
+
+Read `inventory-plan.json`, then run each listed area in an independent worker
+that treats application source as read-only:
+
+```bash
+fimo migrate inventory <project-root> --area runtime-config
+fimo migrate inventory <project-root> --area locales
+```
+
+Run only areas present in the plan. The `locales` area is currently planned
+only when the source package manifest declares `next-intl`.
+
+Workers must return the written deterministic fragment, not a prose summary.
+They must read only the source root and write only their planned fragment and
+execution receipt. A worker may report structured unresolved claims in its
+fragment; process outcome and timing belong in the run receipt.
+
+If independent workers are unavailable, run the same areas sequentially:
+
+```bash
+fimo migrate inventory <project-root> --sequential
+```
+
+After every fan-out, run deterministic fan-in:
+
+```bash
+fimo migrate inventory <project-root> --reconcile
+```
+
+Use a separate validator worker that did not produce fragments to compare the
+plan, source evidence, fragments, and unresolved claims. If it finds a gap,
+reopen only the affected area and reconcile again. The CLI never starts an
+LLM or chooses a harness.

package/assets/skills/fimo-migration/references/inventory/locales/next-intl.md

@@ -0,0 +1,39 @@
+# next-intl locale inventory
+
+Use the shipped analyzer after `package.json` proves a next-intl dependency:
+
+```bash
+node <this-skill>/scripts/inventory/locales/next-intl.mjs <source-root>
+```
+
+It detects conventional JSON dictionaries, JSON imports with one dynamic locale
+segment, and static `defineRouting` locale/default-locale values. It emits
+deterministic facts and file/line evidence without changing the source.
+
+If request configuration does not reveal a custom JSON dictionary layout, let
+the agent select one relative pattern containing `{locale}` exactly once:
+
+```bash
+node <this-skill>/scripts/inventory/locales/next-intl.mjs <source-root> \
+  --messages-pattern 'src/translations/{locale}/common.json'
+```
+
+The script rejects absolute paths, paths outside the source root, non-JSON
+patterns, and ambiguous placeholders.
+
+## Support boundary
+
+The analyzer intentionally leaves a claim unresolved when its static source
+shape is unknown. Current gaps include:
+
+- locales/default locale declared only through legacy middleware or navigation
+  helpers;
+- dynamic or remote locale configuration;
+- non-JSON dictionaries such as extracted PO catalogs;
+- public route reachability.
+
+Treat package version as evidence that helps prioritize likely source shapes,
+not as the primary switch. If the analyzer cannot prove a claim, follow the
+temporary read-only strategy in `references/inventory/locales.md`. A zero exit
+code means the analyzer ran successfully; read `unresolved[]` as the exact
+claims still requiring evidence.

package/assets/skills/fimo-migration/references/inventory/locales.md

@@ -0,0 +1,41 @@
+# Locale inventory
+
+Inventory locale evidence without deciding that every dictionary is configured
+or publicly routable.
+
+## Evidence contract
+
+Keep these facts distinct:
+
+- **dictionary candidates**: locale-like values derived from message files or
+  records;
+- **configured locales**: values proven by static application configuration;
+- **default locale**: one statically proven fallback when present;
+- **public locales**: values proven reachable through the application's routes;
+- **unresolved claims**: individual facts that no strategy proved.
+
+A successful script run means evidence collection executed correctly. It does
+not mean every locale claim is known. Preserve proven facts when another claim
+remains unresolved.
+
+## Bounded fallback
+
+1. Run the shipped strategy for the detected locale system.
+2. If the dictionary layout is the only unknown, pass a supported bounded path
+   pattern to that strategy.
+3. If a claim remains unresolved, inspect only the files likely to own it.
+4. When repeated manual reads would be slower or less reliable, let the agent
+   create one disposable script in the harness or operating-system temporary
+   directory, outside the application source tree. The script must:
+   - read only the selected source root;
+   - perform no network calls or source writes;
+   - have explicit file, byte, or time bounds;
+   - print deterministic facts, evidence paths, and unresolved claims;
+   - avoid claiming route reachability from dictionary files alone.
+5. Validate the output, copy its evidence into the canonical ledger, and remove
+   the temporary script. Do not commit it to the migrated application.
+6. At fan-in, compare configured, default, dictionary, and public locales. Keep
+   every mismatch or unproven claim unresolved until evidence settles it.
+
+If the same temporary strategy is needed repeatedly across migrations, turn it
+into a tested shipped script in a separate Fimo change.

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

@@ -188,6 +188,7 @@ 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 and that a single
-   `fimo deploy` will publish it.
+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.