fimo 0.8.0 → 0.9.0-experimental.10

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

@@ -0,0 +1,662 @@
+# Wrap Mode
+
+Wrap mode is the default migration for a **source-backed, working JS codebase**.
+The supported-framework list lives in the CLI, not in this document: `fimo init`
+detects the framework and says whether it can adopt the site (and offers the
+rebuild path when it cannot). The contract below is framework-neutral;
+framework-specific notes live in the "Framework notes" section at the end.
+The user's stack stays. Nothing is rebuilt. The migration is a mechanical
+wrapping pass that makes existing content editable from Fimo, plus a mandatory
+content-seeding pass so Fimo becomes the source of truth.
+
+**Never rewrite routing, styling, structure, or component logic.** The final
+diff must contain only: the one-time wiring, wrapper components, label calls,
+config files, and lockfile/dependency changes. If a change does not make
+content editable, it does not belong in a wrap migration.
+
+## When wrap does NOT apply
+
+- URL-only migrations (no code) → rebuild path (`fimo migrate <url>`).
+- Builder exports / static HTML dumps → rebuild path.
+- Codebases that do not build/run as-is → fix-first is the owner's call;
+  wrap assumes a working site.
+- Non-JS backends (PHP/WordPress/Drupal) → not supported yet.
+
+## Phases
+
+### W0. Agent-driven run (default)
+
+When YOU (the coding agent) are asked to migrate an adopted site, you own the
+whole loop — the human's only remaining jobs are `fimo init` (done before you)
+and the final `fimo deploy` (never yours). The deterministic machine does the
+heavy lifting; you run it, relay the user's decisions, handle the judgment
+items, and loop until the gates say done:
+
+`fimo init` writes a starter `.fimo/migration/wrap/agent-prompt.md` and
+`fimo migrate` regenerates it with the full work order — that file is the
+source of truth at every step; the user's entry prompt just points to it.
+
+1. Preflight: `npx fimo whoami`. If it fails, STOP and ask the user to run
+   `fimo login` — do not investigate credentials or probe backends.
+2. Run `npx fimo migrate`. Non-interactive shells are the normal agent case:
+   it scans, wires, captures the render baseline, applies the safe transforms
+   (codemod), seeds staged labels, imports env keys, and detects collections
+   and external data sources. Recover mechanical failures yourself (missing
+   install, pnpm `minimumReleaseAgeExclude`, broken dev script) and re-run.
+3. Read the output facts and `.fimo/migration/manifest.json` →
+   `wrap.dataSources`: entries marked `decidedBy: "default"` are USER
+   decisions that could not be asked in your shell. Ask the user in your chat
+   NOW — before any wrapping work (one question per host: keep live, or
+   ingest into Fimo?), update the manifest (`decision`, `decidedBy: "user"`),
+   and re-run `npx fimo migrate` if anything changed (idempotent).
+4. Execute `.fimo/migration/wrap/agent-prompt.md`: the judgment items
+   (attributes, next/image, formatted text), the detected collection
+   candidates, and any user-approved ingestion. Collection candidates are
+   CLASSIFIED before anything is created: navigation links, style-bearing
+   lists, page furniture, and decorative imagery are NOT collections — ask
+   the user one batched question (candidate list + your recommendation),
+   keep-in-code candidates get their strings wrapped with `t()` (the array
+   stays), and only user-confirmed content lists become Fimo collections.
+   Candidates the scan annotated with REFERENCES (field values pointing at
+   another candidate's slugs/names) migrate with `reference` fields —
+   `{ "type": "reference", "target": "<Uid>" }`, `"many": true` for arrays,
+   `targets: [...]` for genuinely mixed slots — never as plain strings, and
+   their entries are created in dependency order (targets first, then
+   referencing entries carrying the recorded documentIds).
+   NAMING STANDARD (this is the judgment the whole flow exists for — hold
+   the bar): collection Uids are SINGULAR PascalCase DOMAIN terms — what the
+   site's owner would call one item — never the source variable or file name
+   when a better domain word exists (a `posts.json` of episode notes is
+   `Episode`, not `Post`; `items` rendered as staff cards is `TeamMember`).
+   Field names stay camelCase and faithful to the source unless the source
+   name is meaningless. Machine drafts under
+   `.fimo/migration/schema-drafts/` carry PROVISIONAL names precisely so you
+   rename them. Adopt them in ONE command:
+   `npx fimo schemas adopt-drafts --rename "Prov=Final,…" --drop "Junk,…"`
+   (copies kept drafts to src/schemas, rewrites reference targets through
+   the renames, renames the staged rows files in step, and pushes in
+   dependency order). Each draft carries `source`, `rowCount`, and a
+   `sample` row — classify and name from the drafts ALONE, without opening
+   the source data files. SEEDING is then ONE command for everything:
+   `npx fimo migrate seed`
+   — it seeds every `.fimo/migration/rows/*.rows.json` in
+   reference-dependency order (targets first, automatically, chunked at
+   1000 rows/request); the staged rows are already transformed (media
+   envelopes, richtext docs, dates) and the SERVER resolves reference
+   source values to documentIds, reporting per-field resolved/dangling
+   counts. Do not write mapping scripts, do not seed staged types
+   one-by-one, do not re-transform from the source files. PAGE REWIRING is
+   also mechanical where the shape is safe (Next app router): `fimo migrate`
+   switches pages rendering a staged collection to
+   `wrapCollection('<Uid>', sourceRows)` — a Fimo overlay onto the retained
+   source rows (per-field type-matched fallback, source order), in-code
+   arrays extracted to `src/data/*.json` first. `adopt-drafts` renames the
+   call-site uids in step. Only pages listed with a bail reason in the
+   migrate warnings need hand wiring — reuse the same `wrapCollection`
+   pattern there. Your FINAL REPORT must end with the naming table: every
+   collection Uid (with the source it came from) and every reference field
+   with its target type(s) and cardinality (single / many / polymorphic).
+   DANGLING references (source values pointing at targets that do not
+   exist) are handled at TWO layers: in the DATABASE store them null/empty
+   and document them in the manifest (`wrap.unresolvedReferences`) — never
+   invent placeholder targets; at RENDER time fall back per-field to the
+   raw source value (the retained fallback array's slug/string) whenever
+   the Fimo reference is null, so the page shows exactly what the source
+   site showed and render parity holds. Honest data AND honest rendering
+   are not in tension.
+   This deliberately differs from `content.md`'s rebuild-path rule ("prefer
+   modeling as a collection"): in wrap mode the user's code stays primary —
+   the rebuild rule does NOT apply here.
+   On simple sites the machine may leave NOTHING to do: the regenerated
+   prompt then says so explicitly ("already done by the machine") — your job
+   collapses to running the check and reporting. Never invent work the
+   prompt does not list.
+   When you start the dev server yourself, pin it to a free port (PORT env
+   or --port flag) — never the Fimo API's own port (apiUrl in
+   .fimo.settings.json; localhost:3000 in local dev). Next and Nuxt default
+   to 3000 and silently shadow the API for the whole machine.
+5. Loop `npx fimo migrate wrap --check` after every batch of fixes until it
+   exits 0. Make the loop cheap: start the dev server once in the background
+   at the beginning of your work and pass it to every check with
+   `--server http://localhost:<port>` — the warm server recompiles
+   incrementally, so each check costs seconds instead of a cold boot. Never
+   recapture the baseline, never add a convenience exemption, never bypass a
+   gate. If the same gate fails twice with the same error, stop and report
+   honestly.
+6. Report the summary and hand back: deploying is the user's call
+   (`npx fimo deploy` — never run it yourself).
+
+### W1. Adopt
+
+Connect the existing site to a Fimo project. From the site directory:
+
+```bash
+fimo init        # interactive: detects the framework, confirms the adopt
+fimo init . -y   # non-interactive (agents/CI): explicit dir = consent
+```
+
+Adoption creates the project, writes `fimo-config.json` (`framework` +
+scanned `routes` for the Studio page switcher), `.fimo.settings.json`, the
+framework env flavor (`NEXT_PUBLIC_FIMO_API_URL`,
+`NEXT_PUBLIC_FIMO_PREVIEW_SCRIPT_URL` for Next), wires the `fimo` git remote
+into the existing repo, and pushes the site as-is. No template is copied.
+
+If the user's config sets CSP headers with `frame-ancestors`, the Fimo Studio
+origins must be permitted or the preview iframe will be blocked. Framework
+quirks (preview origin allowlists, dev-server flags) are listed under
+"Framework notes" at the end of this document.
+
+Sites whose pages fetch external APIs server-side (GitHub, CMSes, analytics)
+hang in the sandbox when their API keys are absent — the page never answers
+and the preview proxy returns 502/504 while the dev server logs
+`Request timed out … Retrying`. `fimo migrate` imports the keys declared in
+the project's `.env`/`.env.local` into the Fimo project automatically
+(sensitive-looking keys as secrets, the rest as variables; existing values
+are never overwritten; Fimo-owned keys are skipped). If that step was
+unavailable (not signed in), push them manually with
+`fimo secrets set <KEY> <value>` / `fimo vars set`, then redeploy.
+
+### W2. Scan + automatic wiring
+
+```bash
+fimo migrate            # inside an adopted JS codebase this IS the wrap flow
+fimo migrate --apply    # + apply the provably-safe transforms automatically
+```
+
+`--apply` performs the deterministic wraps itself in seconds — plain JSX
+text → `FimoText` (whitespace preserved), `<img src="literal">` →
+`FimoMediaImage`, file links → `FimoFileLink` — with deterministic key
+naming and the generated labels staged AND seeded. The render-parity
+baseline is always captured before any transform. Everything needing
+judgment (attributes, formatted text, `next/image`, collections) is refused
+with a reason and stays in the plan for the agent.
+
+(`fimo migrate wrap` is the explicit form; `fimo migrate <url>` remains the
+crawl-and-rebuild path for URL-only migrations.)
+
+Writes `.fimo/migration/plan.json` (every unwrapped item with
+`kind`/`file`/`line`/`preview`) and `.fimo/migration/wrap/agent-prompt.md`.
+The scan finds hardcoded JSX text, `img`/`Image`/`video` sources, file links
+(pdf/zip/docx/…), and user-visible attribute strings (`placeholder`, `title`,
+`aria-label`). Content already inside Fimo wrappers or `t()` calls counts as
+covered.
+
+The command also performs the deterministic wiring itself: it adds the `fimo`
+dependency (platform-pinned) and, for Next.js, inserts `allowedDevOrigins`
+into the next config when missing. Run the project's package manager install
+afterwards.
+
+Known friction: pnpm ≥ 11 ships a `minimumReleaseAge` supply-chain policy
+that refuses packages younger than the cutoff — experimental `fimo` builds
+are minutes old by nature. If install fails with
+`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`, propose adding to the project's
+`pnpm-workspace.yaml`:
+
+```yaml
+minimumReleaseAgeExclude:
+  - fimo
+```
+
+### W3. Wire the layout (one-time)
+
+- Root layout (Next.js app router):
+
+```tsx
+import { FimoNextProviders, FimoNextScripts } from 'fimo/next';
+import { loadFimoConfig, loadFimoLabels } from 'fimo/next/server';
+
+const config = loadFimoConfig();
+const labels = await loadFimoLabels();
+// <head><FimoNextScripts /></head>
+// <body><FimoNextProviders config={config} labels={labels}>{children}</FimoNextProviders></body>
+```
+
+- React (framework-agnostic) uses `fimo/react`; React Router projects keep
+  `fimo/react-router`.
+
+RSC rule: the wrapper primitives are client components. Server components may
+render them directly as JSX children; do not call hooks like `useLabels()`
+outside client components (`'use client'`).
+
+### W4. Wrap
+
+Work through `plan.json` item by item:
+
+| Item kind                           | Wrap with                                                                              |
+| ----------------------------------- | -------------------------------------------------------------------------------------- |
+| text (plain)                        | `<FimoText id="…">original text</FimoText>`                                            |
+| text (formatted: strong/em/u/links) | `<FimoRichTextBlock id="…">…original markup…</FimoRichTextBlock>` — marks must survive |
+| attribute                           | `const { t } = useLabels()` then `placeholder={String(t('key', 'original value'))}`    |
+| image                               | `<FimoMediaImage id="…" src="/original.png" …/>`                                       |
+| video                               | `<FimoMediaVideo id="…" src="/original.mp4" …/>`                                       |
+| file-link                           | `<FimoFileLink id="…" href="/original.pdf">…</FimoFileLink>`                           |
+
+Rules:
+
+- The original value always stays inline as the fallback (child or prop). Wrap
+  fallbacks are deliberate: they keep the site rendering without Fimo
+  connectivity. This differs from Fimo-template projects, where inline
+  fallbacks are forbidden by lint — do not "fix" wrap fallbacks to match.
+- Key naming: `<route>.<section>.<n>` — `home.hero.title`,
+  `pricing.plans.starter.description`. Stable, human-readable, no indexes
+  unless the content is genuinely a list.
+- Repeated hardcoded arrays of 3+ structurally identical items (cards, tiles)
+  are still collections: model a schema + entries as in
+  `references/content.md`, render from `fetchEntries` (`fimo/next/server`).
+  Wrapping each array literal string individually is acceptable only as a
+  first pass and must be recorded as an unresolved modeling item.
+
+### W5. Seed (MANDATORY)
+
+Fallbacks are resilience, not storage. Every wrapped item is seeded into Fimo:
+
+- Labels: every `FimoText`/`t()` key with its original string via
+  `fimo labels set-many --file <json>`.
+- Media/files: `fimo assets upload <path>` per item, then a `WrappedMedia`
+  entry per wrapper id (`key` = wrapper id, `image` = the asset) via
+  `fimo schemas push` + `fimo entries create` (or, for anything beyond ~20
+  rows, `fimo entries create-many <Uid> --file <rows.json>` — a JSON array of
+  bare data objects, chunked through the batch endpoint with per-row
+  results; never loop single creates over a large collection).
+- Collections with machine-staged rows: `fimo migrate seed` — one command
+  seeds every `.fimo/migration/rows/*.rows.json` in reference-dependency
+  order at 1000 rows/request. Each file's `references` descriptor has the
+  server resolve reference source values (slugs) to documentIds;
+  self-references within one file resolve only against rows already
+  inserted (earlier chunks), so a fully intra-file cycle surfaces as
+  dangling counts — record those in the manifest like any dangling
+  reference. (`fimo entries create-many <Uid> --file <rows.json>` remains
+  the per-type primitive for rows you build yourself.)
+- Rich text: `WrappedRichText` entries (`key`, `body` = TipTap JSON converted
+  from the original markup; bold/italic/underline/link marks preserved).
+
+A wrap migration whose labels/entries were never created in Fimo is
+`draft-only`, exactly like a rebuild migration with un-imported seed JSON.
+
+### W6. Verify — four machine-enforced gates
+
+`fimo migrate wrap --check` is the definition of done. It fails until all
+four gates pass:
+
+1. **Coverage** — zero unwrapped items. Deliberate exceptions are recorded in
+   the ledger and the gate honors them: add to
+   `.fimo/migration/manifest.json` → `wrap.exemptions[]` an entry
+   `{ file, kind, preview, reason, status }` where `(file, kind, preview)`
+   matches the plan item exactly (a content change invalidates the exemption
+   so the item resurfaces).
+2. **Render parity** — the check boots the project's dev server and compares
+   every route's rendered text, inline marks, media srcs, and link hrefs
+   against the pre-wrap baseline that `fimo migrate` captured
+   (`.fimo/migration/parity-baseline.json`). Drift is reported per route and
+   block. Dynamic routes are captured by substituting the project's default
+   locale for `[locale]`-style params (so an all-`[locale]` i18n site is
+   verified, not skipped); routes with content params (`[slug]`, `[id]`) that
+   have no safe default still skip — call those out as UNVERIFIED in the
+   handoff. In a monorepo, the baseline boot builds the app's workspace deps
+   first (root `build` / `turbo run build`) so `next dev` does not die on
+   `Cannot find module '@repo/…'`. Run the check right after wrapping (strict,
+   pre-seed) and again after seeding. If the baseline is missing, capture one
+   from the pre-wrap git state: `git stash && npx fimo migrate snapshot && git stash pop`.
+   Text the site renders dynamically BY DESIGN (live clock, visitor counter)
+   drifts on every capture: record `wrap.parityIgnores[]`
+   `{ pattern, reason }` in the manifest — a full-match regex both sides must
+   match to compare equal. A route rendering a keep-live external source
+   (`wrap.dataSources` decision `live`) drifts wholesale: record
+   `{ route, reason }` instead (counted as unverified, never silently
+   clean). Never use either form to hide drift caused by your edit.
+3. **Seeding** — every wrapped key exists in the Fimo database (labels and
+   WrappedMedia/WrappedRichText entries), verified via the API. Fallbacks are
+   not storage. Labels-decision data files (below) are verified too via
+   their recorded `labelPrefix`.
+4. **Wiring** — the root providers are mounted (framework marker file, e.g.
+   `FimoNextProviders` in the app-router layout, `FimoSpaProviders` in the
+   SPA entry, `FimoRemixProviders` in `app/root`, `fimoLabels` in the
+   SvelteKit root `+layout.server`). Without them every wrapped value renders
+   its fallback forever and no other gate notices — coverage counts wraps,
+   parity sees identical fallbacks, seeding is database-side. `fimo migrate`
+   applies this wiring itself for safe shapes (Next.js app router, Vite React
+   SPA); the gate enforces the rest. Enforced only once items are wrapped;
+   Next pages-router-only projects get a warning, not a failure.
+
+**When a CMS was scaffolded, the four gates do NOT prove the reads resolve from
+Fimo.** Parity drift from real→example content is expected and gets ignored, so
+a wiring that silently falls through to the live CMS passes every gate while the
+page renders the CMS's own content (or 404s when the CMS is down). This is the
+CMS analog of the mandatory browser check — prove Fimo _ownership_ by hand:
+load the homepage plus one page per scaffolded type and confirm the rendered
+value is a scaffolded EXAMPLE marker (`Title example 1`, `Meta Title example 1`,
+a `<type>-example-1` slug), NOT real CMS content and NOT a 404. Then confirm in
+Studio Edit mode that a scaffolded block is selectable, not just rendered (a
+block item with no stable id renders but cannot be edited — editability is the
+whole point). **A single type (`Global`, `Header`, `Footer`) that reads empty
+while collections render is the singular-vs-plural keying bug**: the generated
+`fimo-strapi.ts` must key single types by their singular path (`'global'`, not
+`'globals'`), and in dev the adapter logs `/api/global looks like a scaffolded
+type but is not in the type map` on that fallthrough. Fix it in the CLI
+(`scripts/cms/strapi/schema-map.ts`) and regenerate with
+`fimo migrate --scaffold-cms` — never hand-edit the generated module.
+
+**Populate real routes** (scaffolded CMS only): example entries carry generated
+slugs, so only unfiltered reads (the homepage) resolve — every real route the
+site links to misses its slug filter and 404s (the adapter answers a filtered
+miss on a Fimo-owned type with an empty envelope; it never leaks the read to
+the old CMS). Harvest the site's real slugs (live production `sitemap.xml`,
+else nav/footer links in the code, else ask the user) and create one entry of
+the routed type per linked route — matching slug + path field, distinct title,
+varied block subset. Then click through the nav: every linked page renders,
+none 404. This is navigability, not the content migration (the real pull is a
+later, separate step).
+
+**Config-driven sites** (all copy in a data file, templates render only
+expressions): the scanner lists copy-bearing `.json`/`.yml` files and
+markdown groups in the plan (`dataFiles`) and the coverage gate fails until
+each has a decision in the manifest: `wrap.dataFiles[]`
+`{ file, decision: "labels" | "entries" | "ignore", reason, labelPrefix? }`.
+LOCAL CONTENT ALWAYS MIGRATES INTO FIMO — do not ask the user whether to
+migrate local files (only external live sources are a user question).
+`labels` = flat copy documents: seed each prose string as
+`<labelPrefix><json.path>` (arrays by index) and deep-merge label values over
+the parsed file at its server-side loader, keeping the file as fallback;
+`entries` = repeated documents/structures, INCLUDING markdown blog posts:
+the machine stages these as schema drafts + rows (a same-shaped group of ≥2
+md/mdx docs → frontmatter parsed into typed fields, `body` kept verbatim as a
+string so the site's own renderer still works, `slug` from the filename), so
+you adopt them with `adopt-drafts` + `migrate seed` like any collection — no
+hand-authoring, no re-parsing. Record the `entries` decision and rewire the
+reading route to `fetchEntries()` with the files as fallback; `ignore` =
+strictly non-content data (fixtures, geo payloads) — never a deferral.
+GeoJSON/TopoJSON are auto-skipped.
+
+Never bypass a failing gate (`--no-parity` / `--skip-seeding` are for the
+owner to decide, not the agent). Additional manual checks:
+
+- The site builds and runs **with its own toolchain** (`next build`,
+  `npm run dev`, …) — never assume Vite.
+- Diff audit: the migration diff contains only wiring, wrappers, label calls,
+  config, and dependency changes.
+- Then `fimo deploy` (allowed in wrap mode: it pushes the preview env and
+  boots the sandbox preview — it does not publish). Verify in Fimo Studio that
+  the preview renders and Edit mode can select and edit wrapped content, and
+  that an edited label round-trips (`fimo labels set <key> "new"` → reload →
+  rendered). `fimo publish` / `fimo deploy --publish` remain owner-only.
+
+### W7. Unwire the previous CMS — the cutover (when scaffolded)
+
+Injecting Fimo is only **half** a migration. If a CMS was scaffolded (W2/W5),
+the site now READS example content from Fimo but is still **wired to the old
+CMS**: the generated Fimo adapter falls back to it, the SDK/client is still
+imported, and the CMS env is still present. The migration is not done until a
+plain `pnpm dev` runs **purely on Fimo, with zero requests to the old CMS**.
+That cutover is the "wow" — deliver it.
+
+This phase is the agent's: every codebase talks to its CMS differently (bare
+`fetch`, an SDK client, axios, GraphQL, RSC loaders, image hosts), so the
+replacement needs judgment. The machine hands you the worklist; you do the work.
+
+1. **Read the worklist.** `npx fimo migrate cutover` lists every remaining
+   coupling — SDK/client/type deps, source lines that reach the CMS (env /
+   content-type IDs / SDK import), and leftover env keys. The generated agent
+   prompt embeds the same list under **Unwire &lt;CMS&gt;**.
+2. **Replace the data-access layer.** Prefer rewriting the CMS **client module**
+   (the one file that instantiates the SDK / holds the fetch helpers) into a
+   Fimo-backed adapter exposing the **same interface**, so every caller is fixed
+   by a single change. Read from Fimo with `fetchEntries` (`fimo/<framework>/server`).
+3. **Sever the fallthrough.** The generated Fimo adapter falls back to the CMS
+   for unmapped reads — a scaffold crutch. Once the client is Fimo-backed, drop
+   the fallthrough so an unmapped read fails loudly, never silently hits the CMS.
+4. **Remove the coupling.** Delete the CMS SDK/client/type dependencies and the
+   base-URL / token env, and fix any standalone routing the CMS handled (e.g. a
+   `/` → `/[locale]` redirect its middleware provided).
+5. **Verify — the cutover gate.** `npx fimo migrate cutover --check` must report
+   a **clean** cutover (0 couplings). Then `pnpm dev` and confirm the network
+   tab shows **zero** requests to the old CMS. Record the cutover in the manifest.
+
+Detection keys on actual CMS references, not filenames — a CMS client module you
+rewrote to call Fimo reads as clean. Keep-live sites (the user chose NOT to
+scaffold) skip this phase: the CMS stays the source of truth.
+
+## Manifest
+
+Record wrap mode in the canonical ledger (`references/manifest.md`): set
+`mode: "wrap"` and fill the `wrap` block (framework, coverage counts, seeded
+counts, wiring status). Routes/media/forms sections apply as usual — wrap mode
+changes how content becomes editable, not the accounting obligations.
+
+## Framework notes
+
+One short block per wrappable framework. Add a block when the CLI gains a
+framework — nothing above this section should name a specific framework.
+
+### Next.js
+
+- `fimo migrate` inserts `allowedDevOrigins: ['*.preview.fimo.ai']` into the
+  next config (named `nextConfig` bindings, `export default {` literals, and
+  `module.exports = {`); without it the sandbox preview serves a black iframe
+  with failing HMR websockets.
+- `fimo migrate` also wires the app-router ROOT LAYOUT itself for safe shapes
+  (one default-exported function returning `<html>…<body>…{children}`):
+  imports, async, loader calls, `<FimoNextScripts />` in head, `{children}`
+  wrapped in `<FimoNextProviders>`. When it bails (unusual layout), the agent
+  prompt's section 0 carries the recipe and the bail reason; pages-router
+  projects (`pages/_app`) are always manual and only WARN in the wiring gate.
+- Env flavor: `NEXT_PUBLIC_FIMO_API_URL`, `NEXT_PUBLIC_FIMO_PREVIEW_SCRIPT_URL`.
+- Server components cannot call `useLabels()`: use `loadFimoT()` from
+  `fimo/next/server` for attribute strings.
+- `next dev` rejects an unknown `--host` flag (fimopm only passes it to
+  Vite-family dev servers).
+
+### Remix (v2)
+
+- New Remix apps no longer exist (`create-remix` redirects to
+  create-react-router): this adapter targets the EXISTING remix-vite v2
+  fleet. Classic-compiler (`remix dev`) apps predate vite and are not
+  supported by the parity capture.
+- The JSX codemod runs here (React guaranteed): `--apply` wraps plain text,
+  imgs and file links with `fimo/remix` imports automatically.
+- Root wiring: a `loader` in `app/root.tsx` returns
+  `{ fimoConfig: loadFimoConfig(), fimoLabels: await loadFimoLabels() }`
+  (from `fimo/remix/server`); the `Layout` reads it with
+  `useRouteLoaderData<typeof loader>("root")` — GUARD the null case (error
+  boundaries render Layout without loader data) — and mounts
+  `<FimoRemixScripts />` in head plus
+  `<FimoRemixProviders config={…} labels={…}>{children}</FimoRemixProviders>`.
+
+- React: the full wrapper set applies (`fimo/remix` re-exports it) plus
+  `FimoRemixProviders`/`FimoRemixScripts` for `app/root.tsx`.
+- Env flavor: `FIMO_API_URL`, `FIMO_PREVIEW_SCRIPT_URL` (server-read).
+- Routes: flat files under `app/routes` (dots are slashes, `$param` dynamic).
+- Modern Remix dev runs on Vite (`--host` handled); classic `remix dev` honors HOST.
+
+### Astro
+
+- Server-loader + DOM-attrs based (no React needed): in frontmatter
+  `const t = await loadFimoT()` (from `fimo/astro/server`), render
+  `{t('key', 'fallback')}` with `{...fimoLabelAttrs('key')}` on the element.
+- **Islands are NOT React by default** (Solid, Svelte, Preact all ship as
+  `.tsx`/`.svelte`): never import `fimo/next` wrappers there — the JSX
+  runtime differs and the build breaks. The `--apply` codemod skips JSX in
+  Astro projects for this reason. Recipe for a mounted island: the parent
+  `.astro` loads `t` server-side and passes label values as props; the
+  island renders the prop with a literal
+  `data-fimo-source="__labels.<locale>.<key>.value"` attribute (no import
+  needed — it is just a DOM attribute).
+- Mixed text nodes (`Hi, I'm <b>Name</b>, a developer…`) wrap per text node:
+  each segment gets its own `<span {...fimoLabelAttrs(...)}>{t(...)}</span>`
+  (or the attrs go on the existing `<b>`/`<a>`), punctuation stays in the
+  segment it belongs to.
+- Playground/demo components not referenced by any route: exempt them
+  (`wrap.exemptions`, reason "dead template code") instead of fabricating
+  editability for UI that never renders.
+- Config-driven Astro themes (all copy in `src/data/*.json`) surface as
+  `dataFiles` in the plan — follow the data-file triage in W6.
+- Env flavor: `PUBLIC_FIMO_API_URL`, `PUBLIC_FIMO_PREVIEW_SCRIPT_URL`.
+- Routes: file-based under `src/pages` (`.astro`/`.md`/`.mdx`).
+- `astro dev` needs `--host` (fimopm passes it); verify the preview origin
+  allowlist on the first real dogfood.
+- Scanner coverage: `.astro` templates are text-scanned — frontmatter,
+  `<script>`/`<style>` bodies, `<title>` head metadata, and nested
+  `{expressions}` are excluded; what remains is real copy.
+- `--apply` auto-wraps PLAIN TEXT NODES in `.astro` templates (injects the
+  `loadFimoT` head into the frontmatter, wraps `{t('key', 'fallback')}`,
+  stages + seeds the labels). Files that already bind their own `t` (i18n
+  libraries) are left whole. Attributes, media, mixed markup, and
+  collections stay agent work via the recipe above.
+- pnpm >= 11 hard-fails installs on unapproved build scripts; adopt writes
+  `allowBuilds: { fimo: true }` into `pnpm-workspace.yaml` (the project's
+  own blocked deps — esbuild, sharp — are the owner's existing approvals).
+
+### Nuxt (3+)
+
+- Composable-based (SFCs are UNIVERSAL — they hydrate client-side, so never
+  import `fimo/nuxt/server` in a component; the nuxtship dogfood proved it
+  breaks `nuxt build` three different ways). In `<script setup>`:
+
+  ```vue
+  <script setup>
+  import { useFimoT, fimoLabelAttrs } from 'fimo/nuxt';
+  const t = await useFimoT();
+  </script>
+  <template>
+    <h1 v-bind="fimoLabelAttrs('hero.title')">{{ t('hero.title', 'Fallback') }}</h1>
+  </template>
+  ```
+
+  `useFimoT` fetches on the server only and hands the dictionary to the
+  client through the Nuxt payload (hydration-safe, one fetch per page).
+  `fimo/nuxt/server` remains for nitro server routes only.
+
+- In-component arrays (pricing tiers, feature lists): keep the array, wrap
+  its copy strings with `t('key', 'fallback')` inside the array literal —
+  `t` is available above them in the same `<script setup>`.
+- Env flavor: `NUXT_PUBLIC_FIMO_API_URL`, `NUXT_PUBLIC_FIMO_PREVIEW_SCRIPT_URL`.
+- Routes: file-based under `pages/`. `nuxt dev` needs `--host`.
+- Scanner coverage: `.vue` templates are text-scanned (template region only,
+  inline-svg `<title>` excluded); `<script setup>` arrays are
+  collection-scanned (nested copy like `button.text` counts).
+- `--apply` auto-wraps PLAIN TEXT NODES in `.vue` templates (injects the
+  `useFimoT` head into `<script setup>`, wraps `{{ t('key', 'fallback') }}`,
+  stages + seeds the labels). Options-API files and files that bind their
+  own `t` (vue-i18n) are left whole for the agent; attributes, media, and
+  collections stay agent work.
+- Parity capture: nuxi answers 503 while Vite builds — the boot probe waits
+  for a sub-500 response, so slow first compiles are fine.
+
+### SvelteKit
+
+- Load labels ONCE in `src/routes/+layout.server.js` (SvelteKit's own
+  server-only convention — no client-bundle risk):
+
+  ```js
+  import { loadFimoLabels } from 'fimo/svelte/server';
+  export const load = async () => {
+    const bundle = await loadFimoLabels();
+    return { fimoLabels: bundle.dictionaries[bundle.defaultLocale] ?? {} };
+  };
+  ```
+
+  Components build `t` locally from client-safe `fimo/svelte`:
+  pages/layouts via the data prop (`let { data } = $props()` in Svelte 5),
+  deep components via the page store (`$page.data.fimoLabels` /
+  `page.data` from `$app/state`):
+
+  ```svelte
+  <script>
+    import { makeFimoT, fimoLabelAttrs } from 'fimo/svelte';
+    let { data } = $props();
+    const t = makeFimoT(data.fimoLabels);
+  </script>
+  <h1 {...fimoLabelAttrs('hero.title')}>{t('hero.title', 'Fallback')}</h1>
+  ```
+
+  Never import `fimo/svelte/server` in a `.svelte` file (components
+  hydrate; the server barrel reads fs).
+  Build `t` with the mode-agnostic form
+  `const t = makeFimoT($page.data.fimoLabels);` — a plain store read,
+  valid in BOTH legacy and runes components (labels are fixed per render,
+  no reactivity needed). Do NOT use `$derived(...)` (a single rune flips
+  the whole component to runes mode and any existing `$:` in it 500s) and
+  do NOT use `$: t = ...` (reactive statements run after init, so arrays
+  built at init see `t` undefined). In files with a
+  `<script lang="ts" module>` block, the import goes in the INSTANCE
+  script, never the module script (`$page` is illegal there).
+
+- mdsvex blogs: `.md` post copy is markdown-ingestion territory (Tier 1b),
+  not wrap items; `+page.md` routes still discover and parity-capture.
+- Env flavor: `PUBLIC_FIMO_API_URL` (SvelteKit's public prefix).
+- Routes: `src/routes/**/+page.svelte` (+ `+page.md`); `(groups)` are
+  layout-only.
+- Vite dev server (`--host` handled). `.svelte` templates are text-scanned.
+- `--apply` auto-wraps PLAIN TEXT NODES in `.svelte` files (injects the
+  mode-agnostic head above into the instance script, wraps
+  `{t('key', 'fallback')}`, stages + seeds the labels) and writes
+  `src/routes/+layout.server.js` when the project has none. An EXISTING
+  root layout load is not touched — merging `fimoLabels` into it is your
+  work. Files binding their own `t` are left whole; attributes, media, and
+  collections stay agent work.
+- Repo pitfalls seen in the wild: a checked-in FOREIGN lockfile (pnpm-lock
+  in an npm project) makes the capture spawn the wrong package manager —
+  align on one lockfile; a `master` default branch maps to a nonexistent
+  Fimo env — rename to `main` (or create the env) before data commands.
+
+### Vite + React (SPA)
+
+- Detection: a `vite` dependency plus `react` (no meta-framework). The react
+  dependency pins the JSX runtime, so the full JSX codemod runs here —
+  `--apply` wraps plain text, imgs, and file links with `fimo/react` imports.
+  Bare Vite without react (Solid, Preact, lit) stays agent work.
+- One-time wiring: `fimo migrate` wraps the root render itself for the
+  mainstream entry shape (`createRoot(…).render(<JSX/>)` in `src/main.*` /
+  `src/index.*`). When it bails, mount the SPA providers yourself once around
+  the app root — there is no server pass; labels are fetched in the browser
+  and everything renders inline fallbacks until they resolve:
+
+  ```tsx
+  import { FimoSpaProviders } from 'fimo/react';
+  import config from '../fimo-config.json';
+
+  <FimoSpaProviders
+    config={config}
+    apiUrl={import.meta.env.VITE_API_URL}
+    previewScriptUrl={import.meta.env.DEV ? import.meta.env.VITE_FIMO_PREVIEW_SCRIPT_URL : undefined}
+  >
+    <App />
+  </FimoSpaProviders>;
+  ```
+
+- Instant content: the provider paints synchronously from
+  `window.__FIMO_CONTENT__` (baked) or the last visit's localStorage cache,
+  then revalidates in the background (Studio preview saves and window focus
+  trigger refetches — no reload needed). Only the FIRST EVER visit to a
+  non-baked site flashes inline fallbacks for one network round trip. If the
+  project prerenders its `index.html` (any SSG/prerender step), close that
+  gap by baking the payload at build time:
+
+  ```js
+  // e.g. scripts/bake-fimo-content.mjs — run AFTER the build/prerender step
+  import { fetchFimoSpaContent, serializeFimoSpaContent } from 'fimo/react';
+
+  const payload = await fetchFimoSpaContent(process.env.VITE_API_URL, config);
+  html = html.replace('</head>', `${serializeFimoSpaContent(payload)}</head>`);
+  ```
+
+- Routes: no file convention — the scan reads LITERAL ABSOLUTE paths from
+  react-router (`<Route path="/x">` and `createBrowserRouter([{ path: '/x' }])`)
+  into the fimo-config route registry. Relative child paths, `index` routes,
+  and `*` wildcards are not resolved: add those to `fimo-config.json` routes
+  yourself (scanned routes only ever ADD, never overwrite).
+- Parity caveat: a CSR dev server answers every route with the same HTML
+  shell, so the parity gate compares shells and passes vacuously. Coverage
+  and seeding carry the real signal; verify rendering in the browser.
+- Env flavor: `VITE_API_URL`, `VITE_FIMO_PREVIEW_SCRIPT_URL` (Vite inlines
+  only `VITE_`-prefixed vars into client code).
+
+### Vue (Vite SPA)
+
+- v1: DOM-attrs + client-side label hydration; routes come from fimo-config
+  (no file convention to discover).
+
+### Vite / React Router (native template)
+
+- The template pipeline (virtual modules, `t()` extraction) predates wrap mode
+  and stays the canonical path for Fimo-created projects; wrap mode is for
+  adopted codebases.